CameraGeometry

class ctapipe.instrument.camera.geometry.CameraGeometry(camera_name, pix_id, pix_x, pix_y, pix_area, pix_type, pix_rotation='0d', cam_rotation='0d', neighbors=None, apply_derotation=True, frame=None)

Bases: object

CameraGeometry is a class that stores information about a Cherenkov Camera that us useful for imaging algorithms and displays. It contains lists of pixel positions, areas, pixel shapes, as well as a neighbor (adjacency) list and matrix for each pixel. In general the neighbor_matrix attribute should be used in any algorithm needing pixel neighbors, since it is much faster. See for example ctapipe.image.tailcuts_clean

The class is intended to be generic, and work with any Cherenkov Camera geometry, including those that have square vs hexagonal pixels, gaps between pixels, etc.

Parameters

self: type

description

camera_name: str

Camera name (e.g. NectarCam, LSTCam, …)

pix_id: array(int)

pixels id numbers

pix_x: array with units

position of each pixel (x-coordinate)

pix_y: array with units

position of each pixel (y-coordinate)

pix_area: array(float)

surface area of each pixel, if None will be calculated

neighbors: list(arrays)

adjacency list for each pixel

pix_type: string

either ‘rectangular’ or ‘hexagonal’

pix_rotation: value convertable to an `astropy.coordinates.Angle`

rotation angle with unit (e.g. 12 * u.deg), or “12d”

cam_rotation: overall camera rotation with units

Attributes Summary

neighbor_matrix
neighbor_matrix_sparse
neighbors	A list of the neighbors pixel_ids for each pixel
pixel_moment_matrix	Pre-calculated matrix needed for higher-order moment calculation, up to 4th order.
pixel_width	in-circle diameter for hexagons, edge width for square pixels, diameter for circles.

Methods Summary

calc_pixel_neighbors([diagonal])	Calculate the neighbors of pixels using a kdtree for nearest neighbor lookup.
from_name([camera_name, version])	Construct a CameraGeometry using the name of the camera and array.
from_table(url_or_table, **kwargs)	Load a CameraGeometry from an astropy.table.Table instance or a file that is readable by astropy.table.Table.read
get_border_pixel_mask([width])	Get a mask for pixels at the border of the camera of arbitrary width
guess_pixel_area(pix_x, pix_y, pix_type)	Guess pixel area based on the pixel type and layout.
guess_pixel_width(pix_x, pix_y)	Calculate pixel diameter by looking at the minimum distance between pixels
guess_radius()	Guess the camera radius as mean distance of the border pixels from the center pixel
image_from_cartesian_representation(image_2d)	Create a 1D-array from a given 2D image.
image_to_cartesian_representation(image)	Create a 2D-image from a given flat image or multiple flat images.
info([printer])	print detailed info about this camera
make_rectangular([npix_x, npix_y, range_x, …])	Generate a simple camera with 2D rectangular geometry.
position_to_pix_index(x, y)	Return the index of a camera pixel which contains a given position (x,y) in the camera frame.
rotate(angle)	rotate the camera coordinates about the center of the camera by specified angle.
simtel_shape_to_type(pixel_shape)
to_table()	convert this to an astropy.table.Table
transform_to(frame)	Transform the pixel coordinates stored in this geometry and the pixel and camera rotations to another camera coordinate frame.

Attributes Documentation

neighbor_matrix

neighbor_matrix_sparse

neighbors

A list of the neighbors pixel_ids for each pixel

pixel_moment_matrix

Pre-calculated matrix needed for higher-order moment calculation, up to 4th order.

Note this is not recalculated if the CameraGeometry is modified.

this matrix M can be multiplied by an image and normalized by the sum to get the moments:

M = geom.pixel_moment_matrix()
moms = (M @ image)/image.sum()

Returns

array:

x, y, x**2, x*y, y^2, x^3, x^2*y,x*y^2, y^3, x^4, x^3*y, x^2*y2, x*y^3, y^4

pixel_width

in-circle diameter for hexagons, edge width for square pixels, diameter for circles.

This is calculated from the pixel area.

Methods Documentation

calc_pixel_neighbors(diagonal=False)

Calculate the neighbors of pixels using a kdtree for nearest neighbor lookup.

Parameters

diagonal: bool

If rectangular geometry, also add diagonal neighbors

classmethod from_name(camera_name='NectarCam', version=None)

Construct a CameraGeometry using the name of the camera and array.

This expects that there is a resource accessible via get_table_dataset called "[array]-[camera].camgeom.fits.gz" or "[array]-[camera]-[version].camgeom.fits.gz"

Parameters

camera_name: str

Camera name (e.g. NectarCam, LSTCam, …)

version:

camera version id (currently unused)

Returns

new CameraGeometry

classmethod from_table(url_or_table, **kwargs)

Load a CameraGeometry from an astropy.table.Table instance or a file that is readable by astropy.table.Table.read

Parameters

url_or_table: string or astropy.table.Table

either input filename/url or a Table instance

kwargs: extra keyword arguments

extra arguments passed to astropy.table.Table.read, depending on file type (e.g. format, hdu, path)

get_border_pixel_mask(width=1)

Get a mask for pixels at the border of the camera of arbitrary width

Parameters

width: int

The width of the border in pixels

Returns

mask: array

A boolean mask, True if pixel is in the border of the specified width

classmethod guess_pixel_area(pix_x, pix_y, pix_type)

Guess pixel area based on the pixel type and layout. This first uses guess_pixel_width and then calculates area from the given pixel type.

Note this will not work on cameras with varying pixel sizes.

static guess_pixel_width(pix_x, pix_y)

Calculate pixel diameter by looking at the minimum distance between pixels

Note this will not work on cameras with varying pixel sizes or gaps

Returns

in-circle diameter for hexagons, edge width for square pixels

guess_radius()

Guess the camera radius as mean distance of the border pixels from the center pixel

image_from_cartesian_representation(image_2d)

Create a 1D-array from a given 2D image.

Parameters

image_2d: np.ndarray

2D image created by the image_to_cartesian_representation function of the same geometry. shape is expected to be: (n_images, n_rows, n_cols) or (n_rows, n_cols) for a single image.

Returns

1d array

The image in the 1D format, which has shape (n_images, n_pixels). For single images the leading dimension is omitted.

image_to_cartesian_representation(image)

Create a 2D-image from a given flat image or multiple flat images. In the case of hexagonal pixels, the resulting image is skewed to match a rectangular grid.

Parameters

image: np.ndarray

One or multiple images of shape (n_images, n_pixels) or (n_pixels) for a single image.

Returns

image_2s: np.ndarray

The transformed image of shape (n_images, n_rows, n_cols). For a single image the leading dimension is omitted.

info(printer=<built-in function print>)

print detailed info about this camera

classmethod make_rectangular(npix_x=40, npix_y=40, range_x=(- 0.5, 0.5), range_y=(- 0.5, 0.5))

Generate a simple camera with 2D rectangular geometry.

Used for testing.

Parameters

npix_xint

number of pixels in X-dimension

npix_yint

number of pixels in Y-dimension

range_x(float,float)

min and max of x pixel coordinates in meters

range_y(float,float)

min and max of y pixel coordinates in meters

Returns

CameraGeometry object

position_to_pix_index(x, y)

Return the index of a camera pixel which contains a given position (x,y) in the camera frame. The (x,y) coordinates can be arrays (of equal length), for which the methods returns an array of pixel ids. A warning is raised if the position falls outside the camera.

Parameters

x: astropy.units.Quantity (distance) of horizontal position(s) in the camera frame

y: astropy.units.Quantity (distance) of vertical position(s) in the camera frame

Returns

pix_indices: Pixel index or array of pixel indices. Returns -1 if position falls

outside camera

rotate(angle)

rotate the camera coordinates about the center of the camera by specified angle. Modifies the CameraGeometry in-place (so after this is called, the pix_x and pix_y arrays are rotated.

Parameters

angle: value convertable to an `astropy.coordinates.Angle`

rotation angle with unit (e.g. 12 * u.deg), or “12d”

Notes

This is intended only to correct simulated data that are rotated by a fixed angle. For the more general case of correction for camera pointing errors (rotations, translations, skews, etc), you should use a true coordinate transformation defined in ctapipe.coordinates.

static simtel_shape_to_type(pixel_shape)

to_table()

convert this to an astropy.table.Table

transform_to(frame: astropy.coordinates.baseframe.BaseCoordinateFrame)

Transform the pixel coordinates stored in this geometry and the pixel and camera rotations to another camera coordinate frame.

Note that geom.frame must contain all the necessary attributes needed to transform into the requested frame, i.e. if going from CameraFrame to TelescopeFrame, it should contain the correct data in the focal_length attribute.

Parameters

frame: ctapipe.coordinates.CameraFrame

The coordinate frame to transform to.

Returns

CameraGeometry:

new instance in the requested Frame