.. include:: references.txt .. _getting_started: Getting Started =============== Introduction ------------ The Regions package provides classes to represent: * Regions defined using pixel coordinates (e.g., `~regions.CirclePixelRegion`) * Regions defined using celestial coordinates, but still in an Euclidean geometry (e.g., `~regions.CircleSkyRegion`) To transform between sky and pixel regions, a `world coordinate system `_ object (e.g., `astropy.wcs.WCS`) is needed. 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. .. _getting_started-coord: Coordinates ----------- Pixel Coordinates ~~~~~~~~~~~~~~~~~ :class:`~regions.PixCoord` objects are used to represent pixel coordinates. Pixel coordinates are defined with a scalar or an array of ``x`` and ``y`` Cartesian coordinates: .. code-block:: python >>> 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) `~regions.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: .. code-block:: python >>> 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: .. code-block:: python >>> 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 ~~~~~~~~~~~~~~~ :class:`~astropy.coordinates.SkyCoord` objects are used to represent sky coordinates. `~astropy.coordinates.SkyCoord` is a very powerful class that provides a flexible interface for celestial coordinate representation, manipulation, and transformation between systems. See the extensive :ref:`astropy-coordinates` documentation for more details. Let's create a single sky coordinate: .. code-block:: python >>> from astropy.coordinates import SkyCoord >>> skycoord = SkyCoord(42, 43, unit='deg', frame='galactic') >>> skycoord 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: .. code-block:: python >>> skycoord = SkyCoord(ra=[10, 11, 12], dec=[41, 42, 43], unit='deg') >>> skycoord To represent angles both on the sky and in an image, `~astropy.coordinates.Angle` objects or `~astropy.units.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: .. code-block:: python >>> 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: .. code-block:: python >>> skycoord = SkyCoord(42, 43, unit='deg', frame='galactic') >>> pixcoord = PixCoord.from_sky(skycoord=skycoord, wcs=wcs) >>> pixcoord # doctest: +FLOAT_CMP PixCoord(x=146.2575703393558, y=131.5998051082584) >>> pixcoord.to_sky(wcs=wcs) 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, `~regions.CirclePixelRegion`: .. code-block:: python >>> 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: .. code-block:: python >>> print(region) Region: CirclePixelRegion center: PixCoord(x=42, y=43) radius: 4.2 You can access its properties via attributes: .. code-block:: python >>> region.center PixCoord(x=42, y=43) >>> region.radius 4.2 See the :ref:`shapes` documentation for the complete list of pixel-based regions and to learn more about :class:`~regions.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. 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: .. code-block:: python >>> 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 `~astropy.units.Quantity` object with angular units: .. code-block:: python >>> 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: .. code-block:: python >>> print(region) Region: CircleSkyRegion center: radius: 3.0 deg You can access its properties via attributes: .. code-block:: python >>> region.center >>> region.radius See the :ref:`shapes` documentation for the complete list of pixel-based regions and to learn more about :class:`~regions.Region` objects and their capabilities.