RangeSphericalSkyRegion

class regions.RangeSphericalSkyRegion(frame=None, longitude_range=None, latitude_range=None, meta=None, visual=None, **kwargs)

Bases: ComplexSphericalSkyRegion

Sky Region defined within a range of longitude and/or latitudes. At least one set of longitude or latitude bounds must be set.

If latitude_range[0] > latitude_range[1], will wrap over the poles (eg, will exclude the central latitude range.)

Parameters:

frameBaseCoordinateFrame

The coordinate frame for the specified range region.

longitude_rangelength 2 list-like of Angle or

Quantity or None Longitude range in region. Spans from first to second entries (in increasing longitude value), so inverting the order will select the complement longitude range.

latitude_rangelength 2 list-like of Angle or

Quantity or None Latitude range in region. Spans from first to second entries (in increasing latitude value), so inverting the order will select the complement latitude range. I.e., if latitude_range[0] > latitude_range[1], will wrap over the poles, and will instead exclude the central latitude range.

metaRegionMeta or dict, optional

A dictionary that stores the meta attributes of the region.

visualRegionVisual or dict, optional

A dictionary that stores the visual meta attributes of the region.

**kwargsKeyword arguments

Additional keyword arguments passed when created new instances after coordinate transformations.

Attributes Summary

bounding_circle	Bounding circle for the spherical sky region.
bounding_lonlat	Bounding longitude and latitude of the spherical sky region, in the region's frame.
centroid	Region centroid.
centroid_avg	An approximate "centroid", taking the average of the vertices longitude / latitudes, and invert as needed to define an "inside" point for a wide angle longitude range.
centroid_mindist	Region centroid.
latitude_bounds	Latitude bounds of the range spherical sky region.
latitude_range	The range of longitude values, as a length-2 astropy.units.Quantity angle or list or as None
longitude_bounds	Longitude bounds of the range spherical sky region.
longitude_range	The range of longitude values, as a length-2 astropy.units.Quantity angle or list or as None
vertices	Region vertices.

Methods Summary

contains(coord)	Check whether a sky coordinate falls inside the spherical sky region.
discretize_boundary([n_points])	Discretize the boundary into a PolygonSphericalSkyRegion, as an approximation where all sides follow great circles.
to_pixel([wcs, ...])	Convert to a planar PixelRegion instance.
to_sky([wcs, include_boundary_distortions, ...])	Convert to a planar SkyRegion instance.
transform_to(frame[, merge_attributes])	Transform the SphericalSkyRegion instance into another instance with a different coordinate reference frame.

Attributes Documentation

bounding_circle

bounding_lonlat

centroid

Region centroid.

If both longitude and latitude bounds are set:

Defined as the point equidistant from all vertices.

However, if this point falls outside of the region (as in cases very “long and narrow” ranges), the centroid is instead approximated as the average of the longitude and latitudes of all vertices.

If only longitude or only latitude bounds are set, the centroid is taken as the centroid of that boundary shape (i.e., the lune centroid or annulus center).

centroid_avg

An approximate “centroid”, taking the average of the vertices longitude / latitudes, and invert as needed to define an “inside” point for a wide angle longitude range.

Will behave poorly for regions crossing the poles.

centroid_mindist

Region centroid.

Defined as the point equidistant from all vertices.

latitude_bounds

Latitude bounds of the range spherical sky region.

Defined as a spherical circular annulus, a circle (if ending at a pole), or None if no latitude bound set.

latitude_range

The range of longitude values, as a length-2 astropy.units.Quantity angle or list or as None

longitude_bounds

Longitude bounds of the range spherical sky region.

Defined as a spherical lune, or None if no longitude bound set.

longitude_range

The range of longitude values, as a length-2 astropy.units.Quantity angle or list or as None

vertices

Region vertices.

The result depends on which ranges are set:

If both longitude and latitude ranges are set, returns 4 vertices (the “corners” of the composite range) as a SkyCoord.

If only a longitude range is set, returns 2 vertices (the vertices of the longitude spherical lune boundary) as a SkyCoord.

If only latitude ranges are set, returns None (no vertices for the spherical circular annulus latitude bounds).

Methods Documentation

contains(coord)

Check whether a sky coordinate falls inside the spherical sky region.

Parameters:

coordSkyCoord

The position or positions to check.

discretize_boundary(n_points=10)

Discretize the boundary into a PolygonSphericalSkyRegion, as an approximation where all sides follow great circles.

Parameters:

n_pointsint, optional

Number of points along the region’s boundary.

Returns:

poly_sky_region: PolygonSphericalSkyRegion

Spherical sky polygon object.

to_pixel(wcs=None, include_boundary_distortions=False, discretize_kwargs=None)

Convert to a planar PixelRegion instance.

Parameters:

wcsWCS instance, optional

The world coordinate system transformation to use to convert between sky and pixel coordinates. Required if transforming with boundary distortions (if include_boundary_distortions is True). Ignored if boundary distortions not included.

include_boundary_distortionsbool, optional

If True, accounts for boundary boundary distortions in spherical to planar conversions, by discretizing the boundary and converting the boundary polygon. Default is False, which converts to an equivalent idealized shape.

discretize_kwargsdict, optional

Optional keyword arguments to pass to discretize_boundary() method if including boundary distortions.

Returns:

pixel_regionPixelRegion

A pixel region, with an equivalent shape (if include_boundary_distortions is False), or a discretized polygon of the boundary (if include_boundary_distortions is True).

to_sky(wcs=None, include_boundary_distortions=False, discretize_kwargs=None)

Convert to a planar SkyRegion instance.

Parameters:

wcsWCS instance, optional

The world coordinate system transformation to use to convert between sky and pixel coordinates. Required if transforming with boundary distortions (if include_boundary_distortions is True). Ignored if boundary distortions not included.

include_boundary_distortionsbool, optional

If True, accounts for boundary boundary distortions in spherical to planar conversions, by discretizing the boundary and converting the boundary polygon. Default is False, which converts to an equivalent idealized shape.

discretize_kwargsdict, optional

Optional keyword arguments to pass to discretize_boundary() method if including boundary distortions.

Returns:

sky_regionSkyRegion

A planar sky region, with an equivalent shape (if include_boundary_distortions is False), or a discretized polygon of the boundary (if include_boundary_distortions is True).

transform_to(frame, merge_attributes=True)

Transform the SphericalSkyRegion instance into another instance with a different coordinate reference frame.

The precise frame transformed to depends on merge_attributes. If False, the destination frame is used exactly as passed in. But this is often not quite what one wants. E.g., suppose one wants to transform an ICRS coordinate that has an obstime attribute to FK4; in this case, one likely would want to use this information. Thus, the default for merge_attributes is True, in which the precedence is as follows: (1) explicitly set (i.e., non-default) values in the destination frame; (2) explicitly set values in the source; (3) default value in the destination frame.

Note that in either case, any explicitly set attributes on the source astropy.coordinates.SkyCoord that are not part of the destination frame’s definition are kept (stored on the resulting astropy.coordinates.SkyCoord), and thus one can round-trip (e.g., from FK4 to ICRS to FK4 without losing obstime).

Parameters:

framestr, or BaseCoordinateFrame class or instance

The frame to transform this coordinate into.

merge_attributesbool, optional

Whether the default attributes in the destination frame are allowed to be overridden by explicitly set attributes in the source (see note above; default: True).

Returns:

sph_sky_regionSphericalSkyRegion

A new spherical sky region represented in the frame frame.