rayoptics.raytr.trace module

Supports model ray tracing in terms of relative aperture and field.

ray_pkg(ray_pkg)

return a pandas.Series containing a ray package (RayPkg)

ray_df(ray)

return a pandas.DataFrame containing ray data

list_ray(ray_obj, tfrms=None, start=0)

pretty print a ray either in local or global coordinates

The input ray_obj can be either the return from trace_ray(), i.e. a (ray_pkg, ray_err) tuple or a ray_pkg, i.e. (ray, opl, wvl) or a ray alone.

list_in_out_dir(path, ray)

list the incident and exiting ray direction cosines.

trace_ray(opt_model, pupil, fld, wvl, output_filter=None, rayerr_filter='full', **kwargs) → RayResult

Trace a single ray via pupil, field and wavelength specs.

This function traces a single ray at a given wavelength, pupil and field specification.

Ray failures (miss surface, TIR) and aperture clipping are handled via RayError exceptions. If a failure occurs, a second item is returned (if rayerr_filter is set to ‘summary’ or ‘full’) that contains information about the failure. Apertures are tested using the point_inside() API when check_apertures is True.

The pupil coordinates by default are normalized to the vignetted pupil extent. Alternatively, the pupil coordinates can be taken as actual coordinates on the pupil plane (and similarly for ray direction) using the pupil_type keyword argument.

The amount of output that is returned can range from the entire ray (default) to the image segment only or even the return from a user-supplied filtering function.

Parameters:

• opt_model – OpticalModel instance

• pupil – 2d vector of relative pupil coordinates

• fld – Field point for wave aberration calculation

• wvl – wavelength of ray (nm)

• check_apertures – if True, do point_inside() test on inc_pt

• apply_vignetting – if True, apply the fld vignetting factors to pupil

• pupil_type –

  - 'rel pupil': relative pupil coordinates
  - 'aim pt': aim point on pupil plane
  - 'aim dir': aim direction in object space
  

• use_named_tuples – if True, returns data as RayPkg and RaySeg.

• 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
  

• eps – accuracy tolerance for surface intersection calculation

Returns:

ray_pkg, trace_error | None

Return type:

tuple

trace_safe(opt_model, pupil, fld, wvl, output_filter, rayerr_filter, **kwargs) → RayResult

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

trace(seq_model, pt0, dir0, wvl, **kwargs) → RayPkg

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

trace_base(opt_model, pupil, fld, wvl, apply_vignetting=True, pupil_type='rel pupil', **kwargs) → RayPkg

Trace ray specified by relative aperture and field point.

pupil_type controls how pupil data is interpreted when calculating the starting ray coordinates.

Parameters:

• opt_model – instance of OpticalModel to trace

• pupil – aperture coordinates of ray

• fld – instance of Field

• wvl – ray trace wavelength in nm

• apply_vignetting – if True, apply the fld vignetting factors to pupil

• pupil_type –

  - 'rel pupil': relative pupil coordinates
  - 'aim pt': aim point on pupil plane
  - 'aim dir': aim direction in object space
  

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

iterate_ray(opt_model, ifcx, xy_target, fld, wvl, **kwargs)

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_with_opd(opt_model, pupil, fld, wvl, foc, **kwargs)

returns (ray, ray_opl, wvl, opd)

trace_boundary_rays_at_field(opt_model, fld, wvl, use_named_tuples=False, **kwargs)

returns a list of RayPkgs for the boundary rays for field fld

boundary_ray_dict(opt_model, rim_rays)

trace_boundary_rays(opt_model, **kwargs)

trace_ray_list_at_field(opt_model, ray_list, fld, wvl, foc, **kwargs)

returns a list of ray pandas.DataFrame for the ray_list at field fld

trace_field(opt_model, fld, wvl, foc)

returns a pandas.DataFrame with the boundary rays for field fld

trace_all_fields(opt_model)

returns a pandas.DataFrame with the boundary rays for all fields

trace_chief_ray(opt_model, fld, wvl, foc)

Trace a chief ray at fld and wvl.

Returns:

chief_ray, cr_exp_seg

• chief_ray: RayPkg of chief ray

• cr_exp_seg: exp_pt, exp_dir, exp_dst, ifc, b4_pt, b4_dir

Return type:

tuple

trace_fan(opt_model, fan_rng, fld, wvl, foc, img_filter=None, **kwargs)

trace_grid(opt_model, grid_rng, fld, wvl, foc, img_filter=None, form='grid', append_if_none=True, **kwargs)

setup_pupil_coords(opt_model, fld, wvl, foc, image_pt=None, image_delta=None)

Trace chief ray and setup reference sphere for fld.

Returns:

ref_sphere, chief_ray_pkg

• ref_sphere: image_pt, ref_dir, ref_sphere_radius, lcl_tfrm_last

• chief_ray_pkg: chief_ray, cr_exp_seg

Return type:

tuple

aim_chief_ray(opt_model, fld, wvl=None)

aim chief ray at center of stop surface and save results on fld

apply_paraxial_vignetting(opt_model)

get_chief_ray_pkg(opt_model, fld, wvl, foc)

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:

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:

tuple

refocus(opt_model)

Compute a focus shift bringing the axial marginal ray to zero.

trace_astigmatism_coddington_fan(opt_model, fld, wvl, foc)

calculate astigmatism by Coddington trace at fld

trace_coddington_fan(opt_model, ray_pkg, foc=None)

astigmatism calculation via Coddington trace

Note

spherical surfaces only

intersect_2_lines(P1, V1, P2, V2)

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)

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:

tuple

trace_astigmatism(opt_model, fld, wvl, foc, dx=0.001, dy=0.001)

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:

tuple

iterate_ray_raw(pthlist, ifcx, xy_target, pt0, d0, obj2pup_dist, eprad, wvl, not_wa, **kwargs)

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