footprint#

m4opt.fov.footprint(region, target_coord, rotation=None)[source] [edit on github]#

Transform a region to the desired target coordinate and optional rotation.

The region is expected to represent the field of view of an instrument at a standard orientation of R.A.=0, Dec.=0, P.A.=0. This function rotates the region as if the instrument is pointed at the given target coordinate and optional rotation.

The target coordinate and rotation may be arrays; in that case the return value is a Numpy array of regions.

Parameters:

region (Region | Regions) – The shape of the field of view in the standard orientation.
target_coord (SkyCoord) – The position for the center of the field of view.
rotation (Annotated[Quantity, PhysicalType('angle')] | None) – The rotation of the field of view about its center.

Examples

First, some imports:

>>> from regions import CircleSkyRegion, EllipseSkyRegion, PointSkyRegion, PolygonSkyRegion, RectangleSkyRegion, Regions
>>> from astropy.coordinates import SkyCoord
>>> from astropy import units as u
>>> from m4opt.fov import footprint
>>> import numpy as np

We support pointlike FOVs:

>>> region = PointSkyRegion(SkyCoord(0 * u.deg, 0 * u.deg))
>>> target_coord = SkyCoord(5 * u.deg, -5 * u.deg)
>>> footprint(region, target_coord)
<PointSkyRegion(center=<SkyCoord (ICRS): (ra, dec, distance) in (deg, deg, )
    (5., -5., 1.)>)>

and circular FOVs:

>>> region = CircleSkyRegion(SkyCoord(0 * u.deg, 0 * u.deg), 3 * u.deg)
>>> target_coord = SkyCoord(5 * u.deg, -5 * u.deg)
>>> footprint(region, target_coord)
<CircleSkyRegion(center=<SkyCoord (ICRS): (ra, dec, distance) in (deg, deg, )
    (5., -5., 1.)>, radius=3.0 deg)>

and rectangular FOVs:

>>> region2 = RectangleSkyRegion(SkyCoord(0 * u.deg, 0 * u.deg), 6 * u.deg, 8 * u.deg)
>>> target_coord = SkyCoord(5 * u.deg, -5 * u.deg)
>>> footprint(region2, target_coord)
<PolygonSkyRegion(vertices=<SkyCoord (ICRS): (ra, dec, distance) in (deg, deg, )
    [(1.97003363, -8.99308801, 1.), (8.02996637, -8.99308801, 1.),
     (7.99313556, -0.99317201, 1.), (2.00686444, -0.99317201, 1.)]>)>

We can compute the footprints for an array of target coordinates:

>>> ras, decs = np.meshgrid([0, 1], [2, 3]) * u.deg
>>> target_coords = SkyCoord(ras, decs)
>>> footprint(region, target_coords)
array([[<CircleSkyRegion(center=<SkyCoord (ICRS): (ra, dec, distance) in (deg, deg, )
            (0., 2., 1.)>, radius=3.0 deg)>                                          ,
        <CircleSkyRegion(center=<SkyCoord (ICRS): (ra, dec, distance) in (deg, deg, )
            (1., 2., 1.)>, radius=3.0 deg)>                                          ],
       [<CircleSkyRegion(center=<SkyCoord (ICRS): (ra, dec, distance) in (deg, deg, )
            (0., 3., 1.)>, radius=3.0 deg)>                                          ,
        <CircleSkyRegion(center=<SkyCoord (ICRS): (ra, dec, distance) in (deg, deg, )
            (1., 3., 1.)>, radius=3.0 deg)>                                          ]],
      dtype=object)

We support polygon regions:

>>> region = PolygonSkyRegion(SkyCoord([-2, 2, 0] * u.deg, [0, 0, 2] * u.deg))
>>> footprint(region, target_coord)
<PolygonSkyRegion(vertices=<SkyCoord (ICRS): (ra, dec, distance) in (deg, deg, )
    [(2.99236656, -4.99694639, 1.), (7.00763344, -4.99694639, 1.),
     (5.        , -3.        , 1.)]>)>

And arrays of target coordinates:

>>> footprint(region, target_coords)
array([[<PolygonSkyRegion(vertices=<SkyCoord (ICRS): (ra, dec, distance) in (deg, deg, )
            [(357.9987819, 1.99878116, 1.), (  2.0012181, 1.99878116, 1.),
             (  0.       , 4.        , 1.)]>)>                                          ,
        <PolygonSkyRegion(vertices=<SkyCoord (ICRS): (ra, dec, distance) in (deg, deg, )
            [(358.9987819, 1.99878116, 1.), (  3.0012181, 1.99878116, 1.),
             (  1.       , 4.        , 1.)]>)>                                          ],
       [<PolygonSkyRegion(vertices=<SkyCoord (ICRS): (ra, dec, distance) in (deg, deg, )
            [(357.99725754, 2.99817081, 1.), (  2.00274246, 2.99817081, 1.),
             (  0.        , 5.        , 1.)]>)>                                         ,
        <PolygonSkyRegion(vertices=<SkyCoord (ICRS): (ra, dec, distance) in (deg, deg, )
            [(358.99725754, 2.99817081, 1.), (  3.00274246, 2.99817081, 1.),
             (  1.        , 5.        , 1.)]>)>                                         ]],
      dtype=object)

Compound regions are also fine:

>>> regions = Regions([
...     CircleSkyRegion(SkyCoord(0 * u.deg, 0 * u.deg), 3 * u.deg),
...     PolygonSkyRegion(SkyCoord([-2, 2, 0] * u.deg, [0, 0, 2] * u.deg))])
>>> footprint(regions, target_coord)
<Regions([<CircleSkyRegion(center=<SkyCoord (ICRS): (ra, dec, distance) in (deg, deg, )
    (5., -5., 1.)>, radius=3.0 deg)>, <PolygonSkyRegion(vertices=<SkyCoord (ICRS): (ra, dec, distance) in (deg, deg, )
    [(2.99236656, -4.99694639, 1.), (7.00763344, -4.99694639, 1.),
     (5.        , -3.        , 1.)]>)>])>

Not all region types are supported:

>>> region = EllipseSkyRegion(SkyCoord(0 * u.deg, 0 * u.deg), 5 * u.deg, 2 * u.deg)
>>> footprint(region, target_coord)
Traceback (most recent call last):
  ...
NotImplementedError: Footprint transformations are not implemented for EllipseSkyRegion