# Coordinates (`coordinates`)¶

## Introduction¶

`ctapipe.coordinates` contains coordinate frame definitions and coordinate transformation routines that are associated with the reconstruction of Cherenkov telescope events. It is built on `astropy.coordinates`, which internally use the ERFA coordinate transformation library, the open-source-licensed fork of the IAU SOFA system.

## Getting Started¶

The coordinate library defines a set of frames, which represent different coordinate reprentations. Coordinates should be described using an `astropy.coordinates.SkyCoord` in the appropriate frame.

The following special frames are defined for CTA:

they can be transformed to and from any other `astropy.coordinates` frame, like `astropy.coordinates.AltAz` or `astropy.coordinates.ICRS` (RA/Dec)

The two different coordinate frames are shown here:

```"""
Plot the same event in two camera displays showing the
different coordinate frames for camera coordinates.
"""
import astropy.units as u
import matplotlib.pyplot as plt

from ctapipe.coordinates import EngineeringCameraFrame
from ctapipe.image.toymodel import Gaussian
from ctapipe.instrument import SubarrayDescription

def main():
fig, axs = plt.subplots(1, 2, constrained_layout=True, figsize=(6, 3))

model = Gaussian(0 * u.m, 0.1 * u.m, 0.3 * u.m, 0.05 * u.m, 25 * u.deg)

cam = subarray.tel[5].camera.geometry

image, *_ = model.generate_image(cam, 2500)

cam.transform_to(EngineeringCameraFrame()),
ax=axs[1],
image=image,
)

axs[0].set_title("CameraFrame")
axs[1].set_title("EngineeringCameraFrame")

plt.show()
```
```if __name__ == "__main__":
main()
```

(png, hires.png, pdf)

The `CameraFrame` is used internally in `ctapipe` and comes from `sim_telarray`. It abstracts the transformation differences between 1 and 2 mirror telescopes away. The `EngineeringCameraFrame` is used by MAGIC, FACT and the H.E.S.S. analysis software.

## Reference/API¶

### ctapipe.coordinates Package¶

Coordinates.

#### Functions¶

 `project_to_ground`(tilt_system) Project position in the tilted system onto the ground. Turns an alt/az coordinate into a 3d direction in a right-handed coordinate system. `impact_distance`(point, direction, test_points) Compute impact distance from a line defined by a point and a direction vector with an array of points `shower_impact_distance`(shower_geom, subarray) computes the impact distance of the shower axis to the telescope positions

#### Classes¶

 `TelescopeFrame`(*args, **kwargs) Telescope coordinate frame. `CameraFrame`(*args[, copy, …]) Camera coordinate frame. `EngineeringCameraFrame`(*args[, copy, …]) Engineering camera coordinate frame. `NominalFrame`(*args, **kwargs) Nominal coordinate frame. `GroundFrame`(*args[, copy, …]) Ground coordinate frame. `TiltedGroundFrame`(*args[, copy, …]) Tilted ground coordinate frame. `EastingNorthingFrame`(*args[, copy, …]) GroundFrame but in standard Easting/Northing coordinates instead of SimTel/Corsika conventions `MissingFrameAttributeWarning`

### ctapipe.coordinates.camera_frame Module¶

#### Classes¶

 `CameraFrame`(*args[, copy, …]) Camera coordinate frame.

### ctapipe.coordinates.telescope_frame Module¶

The code in this module is basically a copy of https://docs.astropy.org/en/stable/_modules/astropy/coordinates/builtin_frames/skyoffset.html

We are just not creating a metaclass and a factory but directly building the corresponding class.

#### Classes¶

 `TelescopeFrame`(*args, **kwargs) Telescope coordinate frame.

### ctapipe.coordinates.nominal_frame Module¶

The code in this module is basically a copy of https://docs.astropy.org/en/stable/_modules/astropy/coordinates/builtin_frames/skyoffset.html

We are just not creating a metaclass and a factory but directly building the corresponding class.

#### Classes¶

 `NominalFrame`(*args, **kwargs) Nominal coordinate frame.

### ctapipe.coordinates.ground_frames Module¶

This module defines the important coordinate systems to be used in reconstruction with the CTA pipeline and the transformations between this different systems. Frames and transformations are defined using the astropy.coordinates framework. This module defines transformations for ground based cartesian and planar systems.

For examples on usage see examples/coordinate_transformations.py

This code is based on the coordinate transformations performed in the read_hess code

TODO:

• Tests Tests Tests!

#### Functions¶

 `project_to_ground`(tilt_system) Project position in the tilted system onto the ground.

#### Classes¶

 `GroundFrame`(*args[, copy, …]) Ground coordinate frame. `TiltedGroundFrame`(*args[, copy, …]) Tilted ground coordinate frame. `EastingNorthingFrame`(*args[, copy, …]) GroundFrame but in standard Easting/Northing coordinates instead of SimTel/Corsika conventions