Coordinates and Frames

Coordinates and Frames#

The coordinax.frames module provides a flexible and extensible framework for working with reference frames and coordinate objects. This system allows you to represent positions in different frames, transform between frames, and attach frame metadata to your data.

Built-in Frames#

coordinax.frames includes several standard astronomical frames:

>>> import coordinax.frames as cxf
>>> icrs = cxf.ICRS()
>>> icrs
ICRS()

>>> gc = cxf.Galactocentric()
>>> gc
Galactocentric(
  galcen=LonLatSphericalPos(...),
  roll=Quantity(...),
  z_sun=Quantity(...),
  galcen_v_sun=CartesianVel3D(...)
)

Creating Coordinate Objects#

Coordinate objects attach a vector (or KinematicSpace) to a frame:

>>> import coordinax.vecs as cxv
>>> q = cxv.CartesianPos3D.from_([1, 2, 3], "kpc")
>>> coord = cxf.Coordinate(q, frame=icrs)
>>> print(coord)
Coordinate(
    {
        'length': <CartesianPos3D: (x, y, z) [kpc]
            [1 2 3]>
    },
    frame=ICRS()
)

You can also create coordinates from a KinematicSpace object containing multiple vectors.

Transforming Between Frames#

You can transform coordinates or vectors between frames using transformation operators:

>>> op = cxf.frame_transform_op(icrs, gc)
>>> q_gc = op(q)
>>> print(q_gc)
<CartesianPos3D: (x, y, z) [kpc]
    [-11.375   1.845   0.133]>

>>> coord_gc = coord.to_frame(gc)
>>> print(coord_gc)
Coordinate(
    {
        'length': <CartesianPos3D: (x, y, z) [kpc]
            [-11.375   1.845   0.133]>
    },
    frame=Galactocentric(...)
)

Converting Representations Within a Frame#

You can convert the internal representation of a coordinate (e.g., Cartesian to Spherical) without changing its frame:

>>> coord_sph = coord.vconvert(cxv.SphericalPos)
>>> print(coord_sph)
Coordinate(
    {
        'length': <SphericalPos: (r[kpc], theta[rad], phi[rad])
            [3.742 0.641 1.107]>
    },
    frame=ICRS()
)

Custom Frames and Advanced Usage#

You can define your own frames by subclassing the frame base classes and specifying transformation logic. All features above apply to custom frames as well.