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_modelOpticalModel instance
  • pupil – 2d vector of relative pupil coordinates
  • fldField 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

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

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

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

returns (ray, ray_opl, wvl, opd)

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

boundary_ray_dict(opt_model, rim_rays)[source]
trace_boundary_rays(opt_model, **kwargs)[source]
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_fan(opt_model, fan_rng, fld, wvl, foc, img_filter=None, **kwargs)[source]
trace_grid(opt_model, grid_rng, fld, wvl, foc, img_filter=None, form='grid', append_if_none=True, **kwargs)[source]
setup_pupil_coords(opt_model, fld, wvl, foc, image_pt=None, image_delta=None)[source]
aim_chief_ray(opt_model, fld, wvl=None)[source]

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

apply_paraxial_vignetting(opt_model)[source]
get_chief_ray_pkg(opt_model, fld, wvl, foc)[source]

Get the chief ray package at fld, computing it if necessary.

Parameters:
  • opt_modelOpticalModel instance
  • fldField 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

refocus(opt_model)[source]

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

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:

tuple

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:

tuple