Exposure

class ctapointing.exposure.Exposure(is_simulated=False)

Bases: object

Class holding a PointingCamera image, including meta information such as telescope pointing and image meta data.

While a new Exposure object can be directly instantiated by calling the constructor, the more frequent use cases are

• construction by reading an image from database and file, using the Exposure.from_name() method

• construction by simulation, using the ctapointing.exposure.ExposureSimulator.

See tutorials to learn about frequent use cases.

Exposure supports low-level image reading from and writing to FITS files through the methods Exposure.read_from_fits() and Exposure.write_to_fits().

Attributes Summary

altazframe	Return AltAz coordinate frame, using currently available meta information.
camera_pointing	Calculate sky coordinates of the camera centre, using actual telescope pointing and SkyCameraFrame parameters.
mean_exposure_time	Return time of mean exposure of image.
moon_phase	Return Moon's phase at mean exposure time
moon_position	Return Moon's AltAz position at mean exposure time
skycameraframe	Return a SkyCameraFrame object, initialised from current exposure (observation time, location, telescope pointing) and camera (focal length, rotations, tilts etc.) properties.
sun_position	Return Sun's AltAz position at mean exposure time
telescope_pointing_altaz	Return AltAz telescope pointing, i.e. the telescope orientation at the time of mean exposure.
uuid	Return UUID of the exposure.

Methods Summary

create_empty_image()	Create an empty image.
from_container(container)	Construct Exposure object from an ExposureContainer
from_name(name, **kwargs)	Construct an instance by reading the image information from the database or directly from the FITS file.
get_array_indexes(coords)	Return internal numpy array indexes that represent given pixel coordinates
get_intensity(coords)	Return the intensity value stored in the image at the particular coordinates
read_from_fits([name])	Read image data from FITS file.
set_intensity(coords, intensities)	Set image intensity at coordinates coords to values intensity
to_container([prefix])	Write exposure image information to a ctapipe.core.Container for file or database storage.
transform_to_camera(coords[, to_pixels])	Project a given sky coordinate into the CCD chip.
transform_to_sky(coords[, update_skyframe])	Project a given array of SkyCameraFrame coordinates to ICRS.
write_to_fits(filename, **kwargs)	Write the image data to FITS file, with appropriate meta information.

Attributes Documentation

altazframe

Return AltAz coordinate frame, using currently available meta information.

camera_pointing

Calculate sky coordinates of the camera centre, using actual telescope pointing and SkyCameraFrame parameters.

Caution

Coincides with the telescope pointing position only if the camera is not tilted against the optical axis of the telescope

Returns:

camera_centre – camera centre in the ICRS frame

Return type:

SkyCoord

mean_exposure_time

Return time of mean exposure of image.

moon_phase

Return Moon’s phase at mean exposure time

Return type:

Moon phase (float)

moon_position

Return Moon’s AltAz position at mean exposure time

Return type:

Moon’s position in AltAz frame (SkyCoord)

skycameraframe

Return a SkyCameraFrame object, initialised from current exposure (observation time, location, telescope pointing) and camera (focal length, rotations, tilts etc.) properties.

Can be used to transform from/to SkyCameraFrame using up-to-date transformation parameters.

sun_position

Return Sun’s AltAz position at mean exposure time

telescope_pointing_altaz

Return AltAz telescope pointing, i.e. the telescope orientation at the time of mean exposure.

uuid

Return UUID of the exposure.

Methods Documentation

create_empty_image()

Create an empty image.

classmethod from_container(container)

Construct Exposure object from an ExposureContainer

Parameters:

Container (ctapointing.exposure.ExposureContainer) – instance of ExposureContainer from which exposure is filled

Returns:

exposure – exposure object

Return type:

Exposure object

classmethod from_name(name, **kwargs)

Construct an instance by reading the image information from the database or directly from the FITS file.

Parameters:

• name (str) – image filename in case of reading image directly from file, UUID in case of reading from container/database

• **kwargs – see below

Keyword Arguments:

• load_image (bool) – load image pixel data (defaults to True)

• load_camera (bool) – load camera data from database (defaults to True)

• read_meta_from_fits – read meta-data (exposure time, location etc) directly from image FITS header (defaults to False)

• swap_y – swap y coordinate of pixel data (defaults to False)

Returns:

exposure – instance of Exposure object

Return type:

Exposure object

get_array_indexes(coords: ndarray)

Return internal numpy array indexes that represent given pixel coordinates

Parameters:

coords (numpy.ndarray) – 2D array of pixel coordinates

Returns:

(pixel_coords, mask) – internal pixel coordinates and mask indicating valid (on-chip) pixel coordinates

Return type:

tuple of numpy.ndarray

get_intensity(coords: ndarray)

Return the intensity value stored in the image at the particular coordinates

Parameters:

coords (numpy.ndarray) – 2D array of pixel coordinates

Returns:

intensity – pixel intensities at given coordinates

Return type:

numpy.ndarray

read_from_fits(name=None, **kwargs)

Read image data from FITS file. The image can be flipped on the vertical axis, since this is standard for the real images.

Recursive search is possible, e.g. to search subdirectories of image_path.

set_intensity(coords: ndarray, intensities: ndarray)

Set image intensity at coordinates coords to values intensity

Parameters:

• coords (numpy.ndarray) – 2D array of pixel coordinates

• intensities (numpy.ndarray or list, float, int) – 1D array of intensities or single intensity value

to_container(prefix=None)

Write exposure image information to a ctapipe.core.Container for file or database storage.

Parameters:

prefix (str or None (default to None)) – prefix passed to ctapipe.core.Container

Returns:

exposure_container – instance of exposure container

Return type:

ctapipe.core.Container

transform_to_camera(coords, to_pixels=False)

Project a given sky coordinate into the CCD chip. Takes current camera orientation, camera intrinsic parameters and distortions into account.

Parameters:

• coords (SkyCoord) – sky coordinate (ICRS or AltAz)

• to_pixels (bool) – True: convert to camera pixels False: convert to SkyCamera coordinates

Returns:

coords

Return type:

SkyCoord in SkyCameraFrame or array of pixel coordinates

transform_to_sky(coords, update_skyframe=True)

Project a given array of SkyCameraFrame coordinates to ICRS. Takes current camera orientation, camera intrinsic parameters and distortions into account.

If update_skyframe is True, all SkyCameraFrame parameters that are internally stored in coords will be updated by the ones stored in this exposure object (only modifying the coordinate frame’s meta information, not the coordinate values themselves).

Parameters:

• coords (SkyCoord) – coordinates in SkyCameraFrame system

• update_skyframe (bool) – update coordinates with current SkyCameraFrame parameters

Return type:

SkyCoord in ICRS system

write_to_fits(filename, **kwargs)

Write the image data to FITS file, with appropriate meta information. The image can be flipped on the vertical axis, since this is standard for the real images.

Parameters:

filename (str) – image file name (including full path)

__init__(is_simulated=False)

property altazframe

Return AltAz coordinate frame, using currently available meta information.

camera_gain

camera gain (float)

property camera_pointing

Calculate sky coordinates of the camera centre, using actual telescope pointing and SkyCameraFrame parameters.

Caution

Coincides with the telescope pointing position only if the camera is not tilted against the optical axis of the telescope

Returns:

camera_centre – camera centre in the ICRS frame

Return type:

SkyCoord

create_empty_image()

Create an empty image.

classmethod from_container(container)

Construct Exposure object from an ExposureContainer

Parameters:

Container (ctapointing.exposure.ExposureContainer) – instance of ExposureContainer from which exposure is filled

Returns:

exposure – exposure object

Return type:

Exposure object

classmethod from_name(name, **kwargs)

Construct an instance by reading the image information from the database or directly from the FITS file.

Parameters:

• name (str) – image filename in case of reading image directly from file, UUID in case of reading from container/database

• **kwargs – see below

Keyword Arguments:

• load_image (bool) – load image pixel data (defaults to True)

• load_camera (bool) – load camera data from database (defaults to True)

• read_meta_from_fits – read meta-data (exposure time, location etc) directly from image FITS header (defaults to False)

• swap_y – swap y coordinate of pixel data (defaults to False)

Returns:

exposure – instance of Exposure object

Return type:

Exposure object

get_array_indexes(coords: ndarray)

Return internal numpy array indexes that represent given pixel coordinates

Parameters:

coords (numpy.ndarray) – 2D array of pixel coordinates

Returns:

(pixel_coords, mask) – internal pixel coordinates and mask indicating valid (on-chip) pixel coordinates

Return type:

tuple of numpy.ndarray

get_intensity(coords: ndarray)

Return the intensity value stored in the image at the particular coordinates

Parameters:

coords (numpy.ndarray) – 2D array of pixel coordinates

Returns:

intensity – pixel intensities at given coordinates

Return type:

numpy.ndarray

property mean_exposure_time

Return time of mean exposure of image.

property moon_phase

Return Moon’s phase at mean exposure time

Return type:

Moon phase (float)

property moon_position

Return Moon’s AltAz position at mean exposure time

Return type:

Moon’s position in AltAz frame (SkyCoord)

read_from_fits(name=None, **kwargs)

Read image data from FITS file. The image can be flipped on the vertical axis, since this is standard for the real images.

Recursive search is possible, e.g. to search subdirectories of image_path.

set_intensity(coords: ndarray, intensities: ndarray)

Set image intensity at coordinates coords to values intensity

Parameters:

• coords (numpy.ndarray) – 2D array of pixel coordinates

• intensities (numpy.ndarray or list, float, int) – 1D array of intensities or single intensity value

property skycameraframe

Return a SkyCameraFrame object, initialised from current exposure (observation time, location, telescope pointing) and camera (focal length, rotations, tilts etc.) properties.

Can be used to transform from/to SkyCameraFrame using up-to-date transformation parameters.

property sun_position

Return Sun’s AltAz position at mean exposure time

property telescope_pointing_altaz

Return AltAz telescope pointing, i.e. the telescope orientation at the time of mean exposure.

to_container(prefix=None)

Write exposure image information to a ctapipe.core.Container for file or database storage.

Parameters:

prefix (str or None (default to None)) – prefix passed to ctapipe.core.Container

Returns:

exposure_container – instance of exposure container

Return type:

ctapipe.core.Container

transform_to_camera(coords, to_pixels=False)

Project a given sky coordinate into the CCD chip. Takes current camera orientation, camera intrinsic parameters and distortions into account.

Parameters:

• coords (SkyCoord) – sky coordinate (ICRS or AltAz)

• to_pixels (bool) – True: convert to camera pixels False: convert to SkyCamera coordinates

Returns:

coords

Return type:

SkyCoord in SkyCameraFrame or array of pixel coordinates

transform_to_sky(coords, update_skyframe=True)

Project a given array of SkyCameraFrame coordinates to ICRS. Takes current camera orientation, camera intrinsic parameters and distortions into account.

If update_skyframe is True, all SkyCameraFrame parameters that are internally stored in coords will be updated by the ones stored in this exposure object (only modifying the coordinate frame’s meta information, not the coordinate values themselves).

Parameters:

• coords (SkyCoord) – coordinates in SkyCameraFrame system

• update_skyframe (bool) – update coordinates with current SkyCameraFrame parameters

Return type:

SkyCoord in ICRS system

property uuid

Return UUID of the exposure.

write_to_fits(filename, **kwargs)

Write the image data to FITS file, with appropriate meta information. The image can be flipped on the vertical axis, since this is standard for the real images.

Parameters:

filename (str) – image file name (including full path)