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:

• CameraFrame

• EngineeringCameraFrame

• TelescopeFrame

• NominalFrame

• GroundFrame

• TiltedGroundFrame

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
from ctapipe.visualization import CameraDisplay


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)

    subarray = SubarrayDescription.read("dataset://gamma_prod5.simtel.zst")
    cam = subarray.tel[5].camera.geometry

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

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

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

    plt.show()

(Source code)

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.
altaz_to_righthanded_cartesian(alt, az)	Turns an alt/az coordinate into a 3d direction in a right-handed coordinate system.

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 http://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 http://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