rayoptics.raytr.trace module¶
Supports model ray tracing in terms of relative aperture and field.
-
ray_pkg
(ray_pkg)[source]¶ return a
pandas.Series
containing a ray package (RayPkg)
-
ray_df
(ray)[source]¶ return a
pandas.DataFrame
containing ray data
-
list_ray
(ray_obj, tfrms=None, start=0)[source]¶ pretty print a ray either in local or global coordinates
-
trace_safe
(opt_model, pupil, fld, wvl, output_filter, rayerr_filter, **kwargs)[source]¶ Wrapper for trace_base that handles exceptions.
Parameters: - opt_model –
OpticalModel
instance - pupil – 2d vector of relative pupil coordinates
- fld –
Field
point for wave aberration calculation - wvl – wavelength of ray (nm)
- output_filter –
- if None, append entire ray
- if ‘last’, append the last ray segment only
- else treat as callable and append the return value
- rayerr_filter –
- if None, on ray error append nothing
- if ‘summary’, append the exception without ray data
- if ‘full’, append the exception with ray data up to error
- else append nothing
Returns: see discussion of filters, above.
Return type: ray_result
- opt_model –
-
retrieve_ray
(ray_result)[source]¶ Retrieve the ray (the list of ray segs) from ray_result.
This function handles the normal case where the ray traces successfully and the case of a ray failure, which returns a TraceError instance.
-
trace
(seq_model, pt0, dir0, wvl, **kwargs)[source]¶ returns (ray, ray_opl, wvl)
Parameters: - seq_model – the
SequentialModel
to be traced - pt0 – starting coordinate at object interface
- dir0 – starting direction cosines following object interface
- wvl – ray trace wavelength in nm
- **kwargs – keyword arguments
Returns: (ray, op_delta, wvl)
ray is a list for each interface in path_pkg of these elements: [pt, after_dir, after_dst, normal]
- pt: the intersection point of the ray
- after_dir: the ray direction cosine following the interface
- after_dst: after_dst: the geometric distance to the next interface
- normal: the surface normal at the intersection point
op_delta - optical path wrt equally inclined chords to the optical axis
wvl - wavelength (in nm) that the ray was traced in
- seq_model – the
-
trace_base
(opt_model, pupil, fld, wvl, apply_vignetting=True, **kwargs)[source]¶ Trace ray specified by relative aperture and field point.
Parameters: - opt_model – instance of
OpticalModel
to trace - pupil – relative pupil coordinates of ray
- fld – instance of
Field
- wvl – ray trace wavelength in nm
- **kwargs – keyword arguments
Returns: (ray, op_delta, wvl)
ray is a list for each interface in path_pkg of these elements: [pt, after_dir, after_dst, normal]
- pt: the intersection point of the ray
- after_dir: the ray direction cosine following the interface
- after_dst: after_dst: the geometric distance to the next interface
- normal: the surface normal at the intersection point
op_delta - optical path wrt equally inclined chords to the optical axis
wvl - wavelength (in nm) that the ray was traced in
- opt_model – instance of
-
iterate_ray
(opt_model, ifcx, xy_target, fld, wvl, **kwargs)[source]¶ iterates a ray to xy_target on interface ifcx, returns aim points on the paraxial entrance pupil plane
If idcx is None, i.e. a floating stop surface, returns xy_target.
If the iteration fails, a TraceError will be raised
-
trace_boundary_rays_at_field
(opt_model, fld, wvl, use_named_tuples=False)[source]¶ returns a list of RayPkgs for the boundary rays for field fld
-
trace_ray_list_at_field
(opt_model, ray_list, fld, wvl, foc)[source]¶ returns a list of ray
pandas.DataFrame
for the ray_list at field fld
-
trace_field
(opt_model, fld, wvl, foc)[source]¶ returns a
pandas.DataFrame
with the boundary rays for field fld
-
trace_all_fields
(opt_model)[source]¶ returns a
pandas.DataFrame
with the boundary rays for all fields
-
trace_chief_ray
(opt_model, fld, wvl, foc)[source]¶ Trace a chief ray for fld and wvl, returning the ray_pkg and exit pupil segment.
-
trace_grid
(opt_model, grid_rng, fld, wvl, foc, img_filter=None, form='grid', append_if_none=True, **kwargs)[source]¶
-
aim_chief_ray
(opt_model, fld, wvl=None)[source]¶ aim chief ray at center of stop surface and save results on fld
-
get_chief_ray_pkg
(opt_model, fld, wvl, foc)[source]¶ Get the chief ray package at fld, computing it if necessary.
Parameters: - opt_model –
OpticalModel
instance - fld –
Field
point for wave aberration calculation - wvl – wavelength of ray (nm)
- foc – defocus amount
Returns: tuple of chief_ray, cr_exp_seg
chief_ray: chief_ray, chief_ray_op, wvl
cr_exp_seg: chief ray exit pupil segment (pt, dir, dist)
- pt: chief ray intersection with exit pupil plane
- dir: direction cosine of the chief ray in exit pupil space
- dist: distance from interface to the exit pupil point
Return type: chief_ray_pkg
- opt_model –
-
trace_astigmatism_coddington_fan
(opt_model, fld, wvl, foc)[source]¶ calculate astigmatism by Coddington trace at fld
-
trace_coddington_fan
(opt_model, ray_pkg, foc=None)[source]¶ astigmatism calculation via Coddington trace
Note
spherical surfaces only
-
intersect_2_lines
(P1, V1, P2, V2)[source]¶ intersect 2 non-parallel lines, returning distance from P1
s = ((P2 - P1) x V1).(V1 x V2)/|(V1 x V2)|**2
Weisstein, Eric W. “Line-Line Intersection.” From MathWorld–A Wolfram Web Resource.
-
trace_astigmatism_curve
(opt_model, num_points=21, **kwargs)[source]¶ Trace a fan of fields and collect astigmatism data for each field.
Parameters: - opt_model – the optical model
- num_points – the number of FOV sampling points
- kwargs – keyword args for ray trace
Returns: field point, sagittal and tangential focus shifts
Return type:
-
trace_astigmatism
(opt_model, fld, wvl, foc, dx=0.001, dy=0.001)[source]¶ calculate astigmatism by tracing close rays about the chief ray at fld
This function implicitly assumes that the fld point is on a plane of symmetry, i.e. the system is rotationally symmetric, bilaterally symmetric, or quad symmetric. No check is done to ensure this.
Parameters: - opt_model – the optical model
- fld – a Field object
- wvl – wavelength in nm
- foc – defocus amount
- dx – delta in pupil coordinates for x/sagittal direction
- dy – delta in pupil coordinates for y/tangential direction
Returns: sagittal and tangential focus shifts at fld
Return type: