CameraGeometry

class ctapipe.instrument.camera.CameraGeometry(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

selftype

description

namestr

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

pix_idarray(int)

pixels id numbers

pix_xarray with units

position of each pixel (x-coordinate)

pix_yarray with units

position of each pixel (y-coordinate)

pix_areaarray(float)

surface area of each pixel, if None will be calculated

neighborslist(arrays)

adjacency list for each pixel

pix_typestring

either ‘rectangular’ or ‘hexagonal’

pix_rotationvalue convertable to an astropy.coordinates.Angle

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

cam_rotationoverall camera rotation with units

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

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