Getting Started¶

Introduction¶

The Regions package provides classes to represent:

Regions defined using pixel coordinates (a “region-on-image”; e.g., CirclePixelRegion)
Regions defined using celestial coordinates, but still in an Euclidean geometry (i.e., a planar projection, as a “region-on-image”; e.g., CircleSkyRegion)
Regions defined using celestial coordinates, and with a spherical geometry (a “region-on-celestial-sphere”; e.g., CircleSphericalSkyRegion)

To transform between (planar) sky and pixel regions, a world coordinate system object (e.g., astropy.wcs.WCS) is needed. To transform between spherical and planar (sky or pixel) regions, in addition to a wcs, it is also necessary to specify whether or not boundary distortions should be included (capturing the projection effects inherent in projection-to-spherical transformations, or the inverse).

Regions also provides a unified interface for reading, writing, parsing, and serializing regions data in different formats, including the DS9 Region Format, CRTF (CASA Region Text Format), and FITS Region Binary Table format.

Coordinates¶

Pixel Coordinates¶

PixCoord objects are used to represent pixel coordinates. Pixel coordinates are defined with a scalar or an array of x and y Cartesian coordinates:

>>> from regions import PixCoord
>>> pixcoord = PixCoord(x=42, y=43)
>>> pixcoord
PixCoord(x=42, y=43)
>>> pixcoord.x
42
>>> pixcoord.y
43
>>> pixcoord.xy
(42, 43)

PixCoord objects can also represent arrays of pixel coordinates. These work in the same way as single-value coordinates, but they store multiple coordinates in a single object. Let’s create a 1D array of pixel coordinates:

>>> pixcoord = PixCoord(x=[0, 1], y=[2, 3])
>>> pixcoord
PixCoord(x=[0 1], y=[2 3])
>>> pixcoord.x
array([0, 1])
>>> pixcoord.y
array([2, 3])
>>> pixcoord.xy
(array([0, 1]), array([2, 3]))

Let’s now create a 2D array of pixel coordinates:

>>> pixcoord = PixCoord(x=[[1, 2, 3], [4, 5, 6]],
...                     y=[[11, 12, 13], [14, 15, 16]])
>>> pixcoord
PixCoord(x=[[1 2 3]
 [4 5 6]], y=[[11 12 13]
 [14 15 16]])

Sky Coordinates¶

SkyCoord objects are used to represent sky coordinates. SkyCoord is a very powerful class that provides a flexible interface for celestial coordinate representation, manipulation, and transformation between systems. See the extensive Astronomical Coordinate Systems (astropy.coordinates) documentation for more details.

Let’s create a single sky coordinate:

>>> from astropy.coordinates import SkyCoord
>>> skycoord = SkyCoord(42, 43, unit='deg', frame='galactic')
>>> skycoord
<SkyCoord (Galactic): (l, b) in deg
    (42., 43.)>

Sky coordinates also support array coordinates. These work in the same way as single-value coordinates, but they store multiple coordinates in a single object:

>>> skycoord = SkyCoord(ra=[10, 11, 12], dec=[41, 42, 43], unit='deg')
>>> skycoord
<SkyCoord (ICRS): (ra, dec) in deg
[(10., 41.), (11., 42.), (12., 43.)]>

To represent angles both on the sky and in an image, Angle objects or Quantity objects with angular units can be used.

Pixel/Sky Coordinate Transformations¶

To transform between pixel and sky coordinates, a world coordinate system object (e.g., astropy.wcs.WCS) is needed.

Let’s start by creating a WCS object:

>>> from regions import make_example_dataset
>>> dataset = make_example_dataset(data='simulated')
>>> wcs = dataset.wcs

Now let’s use this WCS to convert between sky and pixel coordinates:

>>> skycoord = SkyCoord(42, 43, unit='deg', frame='galactic')
>>> pixcoord = PixCoord.from_sky(skycoord=skycoord, wcs=wcs)
>>> pixcoord
PixCoord(x=146.2575703393558, y=131.5998051082584)
>>> pixcoord.to_sky(wcs=wcs)
<SkyCoord (Galactic): (l, b) in deg
    (42., 43.)>

Pixel Regions¶

Pixel regions are regions that are defined using pixel coordinates and sizes in pixels. The regions package provides a set of “pixel-based” regions classes, for example, CirclePixelRegion:

>>> from regions import PixCoord, CirclePixelRegion
>>> center = PixCoord(x=42, y=43)
>>> radius = 4.2
>>> region = CirclePixelRegion(center, radius)

You can print the region to get some information about its properties:

>>> print(region)
Region: CirclePixelRegion
center: PixCoord(x=42, y=43)
radius: 4.2

You can access its properties via attributes:

>>> region.center
PixCoord(x=42, y=43)
>>> region.radius
4.2

See the Region Shapes documentation for the complete list of pixel-based regions and to learn more about Region objects and their capabilities.

Sky Regions¶

Sky regions are regions that are defined using celestial coordinates. Please note they are not defined as regions on the celestial sphere, but rather are meant to represent shapes on an image (“region-on-image”). They simply use sky coordinates instead of pixel coordinates to define their position. The remaining shape parameters are converted to pixels using the pixel scale of the image.

Let’s create a sky region:

>>> from astropy.coordinates import Angle, SkyCoord
>>> from regions import CircleSkyRegion
>>> center = SkyCoord(42, 43, unit='deg')
>>> radius = Angle(3, 'deg')
>>> region = CircleSkyRegion(center, radius)

Alternatively, one can define the radius using a Quantity object with angular units:

>>> import astropy.units as u
>>> from regions import CircleSkyRegion
>>> center = SkyCoord(42, 43, unit='deg')
>>> radius = 3.0 * u.deg
>>> region = CircleSkyRegion(center, radius)

You can print the region to get some information about its properties:

>>> print(region)
Region: CircleSkyRegion
center: <SkyCoord (ICRS): (ra, dec) in deg
    (42., 43.)>
radius: 3.0 deg

You can access its properties via attributes:

>>> region.center
 <SkyCoord (ICRS): (ra, dec) in deg
     (42., 43.)>
>>> region.radius
<Quantity 3. deg>

See the Region Shapes documentation for the complete list of pixel-based regions and to learn more about Region objects and their capabilities.

Spherical Sky Regions¶

Spherical sky regions are defined using celestial coordinates, and are defined as regions on the celestial sphere (“regions-on-celestial-sphere”, in contrast to the planar Sky Regions). In order to transform between spherical and planar (“region-on-image”) regions, the planar projection (encoded in a world coordinate system object; e.g., astropy.wcs.WCS) must be specified, along with a specification of whether or not boundary distortions should be included. These distortions (implemented through discrete boundary sampling) capture the impact of the spherical-to-planar (or vice versa) projection. However, it is possible to ignore these distortions (e.g., transforming a spherical circle to a planar circle).

Spherical sky regions are created using celestial coordinates (as SkyCoord) and angular distances, for instance specified as

>>> from astropy.coordinates import Angle, SkyCoord
>>> from regions import CircleSphericalSkyRegion
>>> center = SkyCoord(42, 43, unit='deg')
>>> radius = Angle(3, 'deg')
>>> region = CircleSphericalSkyRegion(center, radius)

Alternatively, one can define the radius using a Quantity object with angular units:

>>> import astropy.units as u
>>> from regions import CircleSphericalSkyRegion
>>> center = SkyCoord(42, 43, unit='deg')
>>> radius = 3.0 * u.deg
>>> region = CircleSphericalSkyRegion(center, radius)

You can print the region to get some information about its properties:

>>> print(region)
Region: CircleSphericalSkyRegion
center: <SkyCoord (ICRS): (ra, dec) in deg
    (42., 43.)>
radius: 3.0 deg

You can access its properties via attributes:

>>> region.center
 <SkyCoord (ICRS): (ra, dec) in deg
     (42., 43.)>
>>> region.radius
<Quantity 3. deg>

See the Region Shapes documentation for the complete list of pixel-based regions and to learn more about Region objects and their capabilities.

Navigation

Getting Started¶

Introduction¶

Coordinates¶

Pixel Coordinates¶

Sky Coordinates¶

Pixel/Sky Coordinate Transformations¶

Pixel Regions¶

Sky Regions¶

Spherical Sky Regions¶