iactrace.sensors

Sensor classes for detecting rays at the focal plane.

Base Class

class iactrace.sensors.SensorGroup

Bases: Module

Abstract base class for sensor groups.

A sensor group contains N sensors at different positions/orientations that share the same pixel geometry. During ray tracing, rays are intersected with all sensor planes and the closest hit is kept. This enables modeling complex sensor arrangements like the CTAO SST with 64 planar sensors distributed over a curved surface.

All sensors in a group must have: - positions: 3D positions in world coordinates (N, 3) - rotations: Euler angles (tip, tilt, rotation) in degrees (N, 3) - get_accumulator_shape(): Returns shape of output per sensor - accumulate(sensor_idx, x, y, values): Accumulates values into pixels

The output shape is always (n_sensors, *per_sensor_shape), e.g.: - For square sensors: (N, height, width) - For hexagonal sensors: (N, n_pixels)

Attributes:

positions: Sensor positions in 3D space (N, 3) rotations: Sensor rotations as Euler angles in degrees (N, 3) config_type: Type identifier used in YAML configs

positions = <dataclasses._MISSING_TYPE object>

rotations = <dataclasses._MISSING_TYPE object>

config_type = <dataclasses._MISSING_TYPE object>

property n_sensors

Return number of sensors in the group.

__len__()

Return number of sensors in the group.

abstractmethod get_accumulator_shape()

Return the shape of the accumulator array per sensor.

Returns:

Shape tuple for the output image/accumulator per sensor. For square sensors: (height, width) For hexagonal sensors: (n_pixels,)

Note:

The full output shape is (n_sensors, *get_accumulator_shape()).

abstractmethod accumulate(sensor_idx, x, y, values)

Accumulate values at given positions into pixels across all sensors.

Args:

sensor_idx: Index of sensor each ray hit (n_rays,) x: X coordinates of hit positions in local sensor planes (n_rays,) y: Y coordinates of hit positions in local sensor planes (n_rays,) values: Values to accumulate (e.g., photon weights) (n_rays,)

Returns:

Accumulated images with shape (n_sensors, *get_accumulator_shape())

abstractmethod to_config(index=0)

Convert a single sensor at index to a configuration dictionary.

Args:

index: Index of sensor to convert (default: 0)

Returns:

Configuration dictionary for YAML serialization.

abstractmethod classmethod from_config(configs)

Create a sensor group from a list of configuration dictionaries.

All sensors in the group must share the same pixel geometry (width, height, bounds for square sensors; hex_centers for hexagonal sensors).

Args:

configs: List of configuration dictionaries from YAML.

Returns:

New sensor group instance containing all sensors.

__init__(positions, rotations)

Standard Sensors

These sensors accumulate ray hits into pixel bins:

class iactrace.sensors.SquareSensorGroup

Bases: SensorGroup

Square pixel sensor group.

Contains N sensors at different positions/orientations that share the same pixel geometry (width, height, bounds). Output shape is (N, height, width).

config_type = 'square'

__init__(positions, rotations, width, height, bounds, edge_width=0.0)

Initialize square sensor group.

Args:

positions: Sensor positions (N, 3) in world coordinates rotations: Sensor rotations (N, 3) as Euler angles in degrees width: Number of pixels in x direction (shared by all sensors) height: Number of pixels in y direction (shared by all sensors) bounds: (x_min, x_max, y_min, y_max) pixel bounds (shared by all sensors) edge_width: Width of edge exclusion zone (shared by all sensors)

positions = <dataclasses._MISSING_TYPE object>

rotations = <dataclasses._MISSING_TYPE object>

width = <dataclasses._MISSING_TYPE object>

height = <dataclasses._MISSING_TYPE object>

edge_width = <dataclasses._MISSING_TYPE object>

x0 = <dataclasses._MISSING_TYPE object>

y0 = <dataclasses._MISSING_TYPE object>

dx = <dataclasses._MISSING_TYPE object>

dy = <dataclasses._MISSING_TYPE object>

get_accumulator_shape()

Return per-sensor accumulator shape: (height, width).

to_config(index=0)

Convert sensor at index to config dict.

classmethod from_config(configs)

Create SquareSensorGroup from list of config dicts.

All sensors must share the same pixel geometry (width, height, bounds).

accumulate(sensor_idx, x, y, values)

Accumulate photon hits into pixels across all sensors.

Args:

sensor_idx: Index of sensor each ray hit (n_rays,) x: X coordinates in local sensor planes (n_rays,) y: Y coordinates in local sensor planes (n_rays,) values: Values to accumulate (n_rays,)

Returns:

Accumulated images (n_sensors, height, width)

class iactrace.sensors.HexagonalSensorGroup

Bases: SensorGroup

Hexagonal pixel sensor group with hard (non-differentiable) accumulation.

Contains N sensors at different positions/orientations that share the same hexagonal pixel geometry. Output shape is (N, n_pixels).

config_type = 'hexagonal'

__init__(positions, rotations, hex_centers, edge_width=0.0)

Initialize hexagonal sensor group.

Args:

positions: Sensor positions (N, 3) in world coordinates rotations: Sensor rotations (N, 3) as Euler angles in degrees hex_centers: Hexagon center positions (M, 2) - shared by all sensors edge_width: Width of edge exclusion zone

positions = <dataclasses._MISSING_TYPE object>

rotations = <dataclasses._MISSING_TYPE object>

hex_centers = <dataclasses._MISSING_TYPE object>

n_pixels = <dataclasses._MISSING_TYPE object>

edge_width = <dataclasses._MISSING_TYPE object>

hex_size = <dataclasses._MISSING_TYPE object>

hex_inradius = <dataclasses._MISSING_TYPE object>

grid_rotation = <dataclasses._MISSING_TYPE object>

grid_offset = <dataclasses._MISSING_TYPE object>

lookup_table = <dataclasses._MISSING_TYPE object>

q_min = <dataclasses._MISSING_TYPE object>

r_min = <dataclasses._MISSING_TYPE object>

get_accumulator_shape()

Return per-sensor accumulator shape: (n_pixels,).

to_config(index=0)

Convert sensor at index to config dict.

classmethod from_config(configs)

Create HexagonalSensorGroup from list of config dicts.

All sensors must share the same hexagonal pixel geometry.

accumulate(sensor_idx, x, y, values)

Accumulate values into hexagonal pixels across all sensors.

Args:

sensor_idx: Index of sensor each ray hit (n_rays,) x: X coordinates in local sensor planes (n_rays,) y: Y coordinates in local sensor planes (n_rays,) values: Values to accumulate (n_rays,)

Returns:

Accumulated values (n_sensors, n_pixels)

Straight-Through Sensors

These sensors pass ray coordinates through without binning, useful for debugging, analysis, and optimization (cleaner gradients):

class iactrace.sensors.StraightThroughSquareSensorGroup

Bases: SensorGroup

Square sensor group with straight-through estimator.

Forward pass uses hard assignment (like SquareSensorGroup). Backward pass uses bilinear interpolation for gradient computation.

Note: This is not registered with sensor_registry because YAML configs always load as SquareSensorGroup. Use telescope.with_ste() to convert.

config_type = 'square'

__init__(positions, rotations, width, height, bounds, edge_width=0.0)

Initialize straight-through square sensor group.

Args:

positions: Sensor positions (N, 3) in world coordinates rotations: Sensor rotations (N, 3) as Euler angles in degrees width: Number of pixels in x direction height: Number of pixels in y direction bounds: (x_min, x_max, y_min, y_max) pixel bounds edge_width: Width of edge exclusion zone

positions = <dataclasses._MISSING_TYPE object>

rotations = <dataclasses._MISSING_TYPE object>

width = <dataclasses._MISSING_TYPE object>

height = <dataclasses._MISSING_TYPE object>

edge_width = <dataclasses._MISSING_TYPE object>

x0 = <dataclasses._MISSING_TYPE object>

y0 = <dataclasses._MISSING_TYPE object>

dx = <dataclasses._MISSING_TYPE object>

dy = <dataclasses._MISSING_TYPE object>

get_accumulator_shape()

Return per-sensor accumulator shape: (height, width).

to_config(index=0)

Convert sensor at index to config dict.

classmethod from_config(configs)

Create StraightThroughSquareSensorGroup from list of config dicts.

accumulate(sensor_idx, x, y, values)

Accumulate with straight-through estimator.

Forward: hard assignment to single pixel. Backward: bilinear interpolation gradients.

class iactrace.sensors.StraightThroughHexagonalSensorGroup

Bases: SensorGroup

Hexagonal sensor group with straight-through estimator.

Forward pass uses hard assignment (like HexagonalSensorGroup). Backward pass uses barycentric interpolation to 3 nearest hex centers.

Note: This is not registered with sensor_registry because YAML configs always load as HexagonalSensorGroup. Use telescope.with_ste() to convert.

config_type = 'hexagonal'

__init__(positions, rotations, hex_centers, edge_width=0.0)

Initialize straight-through hexagonal sensor group.

Args:

positions: Sensor positions (N, 3) in world coordinates rotations: Sensor rotations (N, 3) as Euler angles in degrees hex_centers: Hexagon center positions (M, 2) - shared by all sensors edge_width: Width of edge exclusion zone

positions = <dataclasses._MISSING_TYPE object>

rotations = <dataclasses._MISSING_TYPE object>

hex_centers = <dataclasses._MISSING_TYPE object>

n_pixels = <dataclasses._MISSING_TYPE object>

edge_width = <dataclasses._MISSING_TYPE object>

hex_size = <dataclasses._MISSING_TYPE object>

hex_inradius = <dataclasses._MISSING_TYPE object>

grid_rotation = <dataclasses._MISSING_TYPE object>

grid_offset = <dataclasses._MISSING_TYPE object>

lookup_table = <dataclasses._MISSING_TYPE object>

q_min = <dataclasses._MISSING_TYPE object>

r_min = <dataclasses._MISSING_TYPE object>

get_accumulator_shape()

Return per-sensor accumulator shape: (n_pixels,).

to_config(index=0)

Convert sensor at index to config dict.

classmethod from_config(configs)

Create StraightThroughHexagonalSensorGroup from list of config dicts.

accumulate(sensor_idx, x, y, values)

Accumulate with straight-through estimator.

Forward: hard assignment to single hex pixel. Backward: barycentric interpolation gradients to 3 nearest hexes.