CameraGeometry

class ctapipe.instrument.CameraGeometry(name, pix_id, pix_x, pix_y, pix_area, pix_type, pix_rotation=<Quantity 0. deg>, cam_rotation=<Quantity 0. deg>, neighbors=None, apply_derotation=True, frame=None, _validate=True)

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:

namestr

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

pix_idnp.ndarray[int]

pixels id numbers

pix_xu.Quantity

position of each pixel (x-coordinate)

pix_yu.Quantity

position of each pixel (y-coordinate)

pix_areau.Quantity

surface area of each pixel

pix_typePixelShape

either ‘rectangular’ or ‘hexagonal’

pix_rotationu.Quantity[angle]

rotation of the pixels, global value for all pixels

cam_rotationu.Quantity[angle]

rotation of the camera. All coordinates will be interpreted to be rotated by this angle with respect to the definition of the frame the pixel coordinates are defined in.

neighborslist[list[int]]

adjacency list for each pixel If not given, will be build from the pixel width and distances between pixels.

apply_derotationbool

If true, rotate the pixel coordinates, so that cam_rotation is 0.

framecoordinate frame

Frame in which the pixel coordinates are defined (after applying cam_rotation)

Attributes Summary

CURRENT_TAB_VERSION
SUPPORTED_TAB_VERSIONS
max_neighbors
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.
cartesian_index_to_image_index(row, col)	Convert cartesian index (row, col) to pixel index in 1d representation.
from_name([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_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_index_to_cartesian_index(pixel_index)	Convert pixel index in the 1d image representation to row and col
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

CURRENT_TAB_VERSION = '2.0'

SUPPORTED_TAB_VERSIONS = {'1', '1.0', '1.1', '2.0'}

max_neighbors

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

cartesian_index_to_image_index(row, col)

Convert cartesian index (row, col) to pixel index in 1d representation.

classmethod from_name(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:

namestr

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

version

camera version id

Returns:

new CameraGeometry

Notes

Warning: This method loads a pre-generated CameraGeometry and is thus not guaranteed to be the same pixel ordering or even positions that correspond with event data! Therefore if you are analysing data, you should not rely on this method, but rather open the data with an EventSource and use the CameraGeometry that is provided by source.subarray.tel[i].camera.geometry or by source.subarray.camera_types[type_name].geometry. This will guarantee that the pixels in the event data correspond with the 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

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_index_to_cartesian_index(pixel_index)

Convert pixel index in the 1d image representation to row and col

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 convertible 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: 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