iactrace.analysis

Analysis tools for post-processing ray bundles.

Focal Surface

Intersect a RayBundle with a parametric focal surface to inspect spot diagrams, chief-ray angles, and other PSF metrics without going through the camera’s pixel binning.

class iactrace.analysis.FocalSurface

Bases: Module

Abstract focal surface attached to the camera frame.

Subclasses implement _intersect_local(), which receives a single ray already transformed into the surface-local frame (vertex at origin, +Z along the surface normal at the vertex). The base intersect() handles materialisation of lazy bundles, the world->local transform, and vectorisation across rays.

position = <dataclasses._MISSING_TYPE object>

rotation = <dataclasses._MISSING_TYPE object>

intersect(ray_bundle)

Intersect every ray in ray_bundle with this focal surface.

Lazy bundles are materialised first; per-ray analysis cannot fold.

__init__(position, rotation)

class iactrace.analysis.FlatFocalPlane

Bases: FocalSurface

A flat focal plane.

The plane passes through position with its normal aligned with the local +Z axis defined by rotation. This is the same model intersect_sensor() uses for sensors, just without pixel binning.

__init__(position=None, rotation=None)

class iactrace.analysis.AsphericFocalSurface

Bases: FocalSurface

A rotationally-symmetric aspheric focal surface.

Parameterisation matches AsphericSurfaceGroup; the surface sag is

z(r) = c r^2 / (1 + sqrt(1 - (1 + k) c^2 r^2))

• sum_i a_i r^(2i+4)

with r^2 = x^2 + y^2 in the local frame, i.e. aspherics[i] multiplies r^(2i + 4) – the polynomial starts at r^4, since an r^2 term would be degenerate with curvature. The vertex sits at position and the optical axis points along the local +Z (set by rotation). Pure conics are recovered with aspherics=None; curvature = 0 reduces to a flat plane (Newton converges in one step from the closed-form conic init).

__init__(position=None, rotation=None, *, curvature=0.0, conic=0.0, aspherics=None)

curvature = <dataclasses._MISSING_TYPE object>

conic = <dataclasses._MISSING_TYPE object>

aspherics = <dataclasses._MISSING_TYPE object>

class iactrace.analysis.FocalSurfaceHits

Bases: Module

Result of intersecting a RayBundle with a FocalSurface.

All arrays have leading dimension n_rays and are aligned with the input bundle. Dead rays appear with hit_mask = False and meaningless values in the position/direction arrays: always filter with hit_mask (or alive) before using xy_local for plotting or statistics.

Attributes:

xy_local: Tangent-plane coordinates at the hit, in the surface-local

frame (n_rays, 2).

z_local: Sag of the surface at the hit (n_rays,). Always 0 for a flat

focal plane.

t: Ray parameter at the hit; equals the world-frame distance travelled

from ray_bundle.origins to the surface (n_rays,).

hit_mask: Liveness at the surface (n_rays,): True for a ray that

was still alive on arrival and crossed this surface. This is the input bundle’s alive flag ANDed with a real intersection, so a ray lost upstream (shadowed, off-aperture) is False here even if its stale geometry would formally cross the surface.

directions_local: Ray directions in the surface-local frame (n_rays, 3).

Useful for chief-ray / angle-of-incidence analysis.

opl: Per-ray optical path length from the source wavefront to the

focal surface, in metres (n_rays,). Equals ray_bundle.path_length + t * ray_bundle.n.

xy_local = <dataclasses._MISSING_TYPE object>

z_local = <dataclasses._MISSING_TYPE object>

t = <dataclasses._MISSING_TYPE object>

hit_mask = <dataclasses._MISSING_TYPE object>

directions_local = <dataclasses._MISSING_TYPE object>

opl = <dataclasses._MISSING_TYPE object>

values = <dataclasses._MISSING_TYPE object>

property alive

Rays that reached the surface carrying light (hit_mask & values > 0).

The one-stop filter for photometry / spot diagrams: it excludes both geometry loss (hit_mask) and rays attenuated to zero throughput such as absorbed or totally-internally-reflected rays.

__init__(xy_local, z_local, t, hit_mask, directions_local, opl, values)