HealSparse Geometry
HealSparse
has a basic geometry library that allows you to generate maps from circles, convex polygons, and ellipses as supported by hpgeom
. Each geometric object is associated with a single value. On construction, geometry objects only contain information about the shape, and they are only rendered onto a HEALPix grid when requested.
There are a few methods to realize geometry objects.
The easiest is to combine a geometric object with a HealSparseMap
map, with the or
, and
, or add
operation.
One can generate a HealSparseMap
from the geometric object.
Finally, for integer-value objects one can use the realize_geom()
method to combine multiple objects by :cod:`or`-ing the integer values together.
HealSparse Geometry Shapes
The three shapes supported are Circle
, Ellipse
, and Polygon
. They share a base class, and while the instantiation is different, the operations are the same.
Circle
import healsparse
# All units are decimal degrees
circ = healsparse.Circle(ra=200.0, dec=0.0, radius=1.0, value=1)
Ellipse
import healsparse
# All units are decimal degrees
# The inclination angle alpha is defined counterclockwise with respect to North.
# See https://hpgeom.readthedocs.io/en/latest .
ellipse = healsparse.Ellipse(ra=200.0, dec=0.0, semi_major=1.0, semi_minor=0.5, alpha=45.0, value=1)
Convex Polygon
# All units are decimal degrees
poly = healsparse.Polygon(ra=[200.0, 200.2, 200.3, 200.2, 200.1],
dec=[0.0, 0.1, 0.2, 0.25, 0.13],
value=8)
Combining Geometric Objects with Maps
Given a map, it is very simple to combine geometric objects to build up complex shapes/masks/etc.
Behind the scenes, large geometric objects are rendered with hpgeom
pixel ranges which leads to greater memory efficiency.
import healsparse
import numpy as np
# Create an empty map.
m = healsparse.HealSparseMap.make_empty(32, 4096, np.uint16)
# Set a large circle to a value using the ``or`` operation
m |= healsparse.Circle(ra=200.0, dec=20.0, radius=5.0, value=1)
# Remove a small circle from the center using the ``and`` operation
m &= healsparse.Circle(ra=200.0, dec=20.0, radius=1.0, value=0)
# And add in another circle.
m += healsparse.Circle(ra=202.0, dec=21.0, radius=0.5, value=10)
Making a Map
To make a map from a geometry object, use the get_map()
method as such. The higher resolution you choose, the better the aliasing at the edges (given that these are pixelized approximations of the true shapes). You can also combine two maps using the general operations. Note that if the polygon is an integer value, the default sentinel when using get_map()
is 0
.
smap_poly = poly.get_map(nside_coverage=32, nside_sparse=32768, dtype=np.int16)
smap_circ = circ.get_map(nside_coverage=32, nside_sparse=32768, dtype=np.int16)
combo = healsparse.or_union([smap_poly, smap_circ])
Using realize_geom()
You can only use realize_geom()
to create maps from combinations of polygons if you are using integer maps, and want to or
them together. This method is more memory efficient than generating each individual individual map and combining them, as above.
realized_combo = healsparse.HealSparseMap.make_empty(32, 32768, np.int16, sentinel=0)
healsparse.realize_geom([poly, circ], realized_combo)