pyoptools.raytrace.comp_lib module¶

Helper module with definition of standard optical components

The classes imported in this module are defined in the _comp_lib module, and are used to create the surfaces and the components needed to define some standard optical components, and return an instance to such components. This module hides from the end user un needed stuff.

class pyoptools.raytrace.comp_lib.AirSpacedDoublet(radius=25.0, curvature_s1=0.01, curvature_s2=0.01, curvature_s3=0.01, curvature_s4=0.01, thickness_l1=5, air_gap=5, thickness_l2=5, material_l1=1.0, material_l2=1.0, *args, **kwarks)¶

Bases: System

Class to define a an Air Spaced Doublet Lens

This class is used to define a System with containing the components needed to define a Doublet lens.

Parameters:

radius (float) – Radius of the doublet
curvature_s1 (float) – Curvature of the anterior surface of the first lens
curvature_s2 (float) – Curvature of the posterior surface of the first lens
curvature_s3 (float) – Curvature of the anterior surface of the first lens
curvature_s4 (float) – Curvature of the posterior surface of the first lens
thickness_l1 (float) – Thickness of the anterior lens at the optical axis
thickness_l2 (float) – Thickness of the posterior lens at the optical axis
air_gap (float) – Distance between the 2 lenses
material_l1 (float or Material subclass instance) – Material of the anterior lens
material_l2 (float or Material subclass instance) – Material of the posterior lens

The origin of the coordinate system is located at the center of the doublet in the optical axis.

class pyoptools.raytrace.comp_lib.AsphericLens(outer_diameter=8.0, thickness=3.0, material=1.5, origin='center', s1={'diameter': 6.0, 'k': -1.5, 'max_thickness': None, 'polycoefficents': (0, 0, 0, 0, 0.003, 0, -1e-05), 'roc': 3.0}, s2=None, *args, **kwargs)¶

Bases: Component

Helper class to define radially-symmetric aspherical lenses.

Both single sided and double sided aspherics are supported. Lenses with a outer brim larger than the aspheric surface are supported.

Parameters:

thickness (float) – The total thickness in mm of the lens at the maximum
outer_diameter (float, optional) – The outer diameter of the lens in mm. If unspecified or None, will be found from the largest of either aspheric surface.
material (Material or float) – Material defining the refraction index of the lens. Can be a material instance or floating point number if the refraction index is constant.
origin (str) –
Where along the optical axis to place the origin of the coordinate system. By default will the the geometric center. Can also be:
- ’s1_max’ : Point of maximum thickness on s1
- ’s1_min’ : Point of minimum thickness on s1
- ’s2_max’ : Point of maximum thickness on s2
- ’s2_min’ : Point of minimum thickness on s2
- ’center’ : Geometric center
These options can be convenient for placing the origin at mounting face.
s1 (dict) – Radially symmetric aspheric surface definition dict for the anterior surface, as described below.
s2 (dict, optional) – Either None for a plano-aspheric lens or a symmetric aspheric surface definition dict for the posterior surface, as described below.
Definitions (Surface)
-------------------
diameter (float) – Diameter of the aspheric surface in mm
roc (float) – Radius of curvature parameter for the surface in mm
k (float) – Conic constant
polycoefficents (tuple of float) – Tuple listing the higher order aspheric coefficients The first element corresponds to index zero. Typically, the elements used in a surface description are even numbered, starting at index 4, so the first four elements are typically zero.
max_thickness (float, optional) – Maximum thickness of the surface in mm or None. If None, the maximum thickness will be found from the thickness at zero radius, however not all possible surfaces have the maximum here.

class pyoptools.raytrace.comp_lib.BeamSplitingCube(*argv, **kwargs)¶

Bases: BeamSplittingCube

Deprecated class, please use the one with the correct spelling BeamSplittingCube

Warning

Will be removed in the future

class pyoptools.raytrace.comp_lib.BeamSplittingCube(size=50.0, reflectivity=0.5, material=1.0, **traits)¶

Bases: System

Class to define a BeamSplittingCube.

This class defines an System object containing the components to define an BeamSplitingCube.

Parameters:

size (float) – Side dimension of the cube
reflectivity (float) – Reflectivity of the hypotenuse (between 0 and 1).
material (float or Material subclass instance) – Material used to make the cube. Used to calculate the refraction index of the cube

The origin of the coordinate system is located at the center of the cube in the optical axis (center of the hypotenuse).

class pyoptools.raytrace.comp_lib.Block(size=(10, 10, 10), **traits)¶

Bases: Component

Class to define a Glass Block

This class defines a component containing a glass block

Parameters:: size (tuple(float, float, float)) – Tuple (W,H,L) containing the width, height and length of the glass block. Dimensions given in mm.

class pyoptools.raytrace.comp_lib.CCD(size=(10, 10), transparent=True, *args, **kwargs)¶

Bases: Component

Class to define a CCD like detector

Parameters:

size (tuple(float, float)) – Tuple with the physical size (sx,sy) of the CCD chip
transparent (bool) – Boolean to set the detector transparent characteristic. Not implemented

Using the same CCD, images of different resolutions can be simulated. See the im_show and spot_diagram methods

get_color_image(size=(256, 256))¶

Returns the CCD hit_list as a color image, using the rays wavelength.

Parameters:: size – Tuple (dx,dy) containing the image size in pixels. Use this attribute to set the simulated resolution.

get_image(size=(256, 256))¶

Returns the ccd hit_list as a grayscale PIL image

Parameters:: size – Tuple (dx,dy) containing the image size in pixels. Use this a ttribute to set the simulated resolution.

get_optical_path_data()¶

Return the optical path of the rays hitting the detector.

This method returns a tuple X,Y,D, containing the X,Y hit points, and D containing the optical path data

Warning

If the rays hitting the surface are produced by more than one optical source, the information may not be valid.

get_optical_path_map(size=(20, 20), mask=None)¶

Return the optical path of the rays hitting the detector.

This method uses the optical path of the rays hitting the surface to create a optical path map. The returned value is an interpolation of the values obtained by the rays.

Warning

If the rays hitting the surface are produced by more than one optical source, the returned map might not be valid.

Parameters:

size – Tuple (nx,ny) containing the number of samples of the returned map. The map size will be the same as the CCD
mask – Shape instance containing the mask of the aperture. If not given, the mask will be automatically calculated.

Returns:

A masked array as defined in the numpy.ma module, containing the optical paths

get_optical_path_map_lsq(order=10)¶

Return a 2D polinomial describing the the optical path of the: rays hitting the detector.

Parameters:: order – Order of the polynomial used to fit the data
Returns:: tuple (e, p) where e es the rms error of the data when compared with the returned polynomial, and p is a poly2d instance.

property hit_list¶: List containing a tuple for each ray hitting the CCD. The first component of the tuple is the coordinates of intersection of the ray with the CCD (in its coordinate system). The second component of each tuple points to the Ray that intersected the CCD.

class pyoptools.raytrace.comp_lib.CylindricalLens(size=(20, 20), thickness=10, curvature_s1=0.005, curvature_s2=0.005, *args, **kwargs)¶

Bases: Component

Class to define a rectangular shaped cylindrical Lens.

Parameters:

size (tuple(float,float)) – Size (sx,sy) of the lens in mm
thickness (float) – Thickness of the lens at the center
curvature_s1 (float) – Curvature of the anterior surface of the lens, in mm^-1.
curvature_s2 (float) – Curvature of the posterior surface of the lens, in mm^-1.
material (float or Material’s subclass instance) – Material of the lens

class pyoptools.raytrace.comp_lib.Doublet(radius=25.0, curvature_s1=0.01, curvature_s2=0.01, curvature_s3=0.01, thickness_l1=5, thickness_l2=5, material_l1=1.0, material_l2=1.0, *args, **kwarks)¶

Bases: System

Class to define a Doublet Lens

This class is used to define a System with containing the components needed to define a Doublet lens.

Parameters:

radius (float) – Radius of the doublet. Given in mm
curvature_s1 (float) – Curvature of the anterior surface. Given in 1/mm
curvature_s2 (float) – Curvature of the middle surface. Given in 1/mm
curvature_s3 (float) – Curvature of the last surface
thickness_l1 (float) – Thickness of the anterior lens at the optical axis
thickness_l2 – Thickness of the posterior lens at the optical axis
material_l1 (float or Material subclass instance) – Material of the anterior lens
material_l2 – Material of the posterior lens

The origin of the coordinate system is located at the center of the doublet in the optical axis.

class pyoptools.raytrace.comp_lib.DovePrism(s, length, *args, **kwargs)¶

Bases: Component

Class to define a dove prism

Parameters:

s (float) – Height and depth of the dove prism
length (float) – Width of the dove prism (length of the longest side)
material (float or Material’s subclass instance) – Material of the prism

pyoptools.raytrace.comp_lib.IdealLens(shape=<pyoptools.raytrace.shape.rectangular.Rectangular object>, f=100)¶

Function to create a component that behaves as an ideal lens

Parameters:: shape (Shape) – Shape of the lens

pyoptools.raytrace.comp_lib.IdealTLens(shape=<pyoptools.raytrace.shape.rectangular.Rectangular object>, ap_shape=<pyoptools.raytrace.shape.rectangular.Rectangular object>, f=100, d=20)¶: Function to define an ideal thick lens.

class pyoptools.raytrace.comp_lib.MultiLens(sd, *args, **kwarks)¶

Bases: System

Class to define a multilens system from a table of parameters as given in standard raytracing programs.

sd¶

List of tuples (ty, rad, thick, semid, matcat, marref) that contain each of the parameters needed to define each spherical surface using the same format used by the standard raytracing software.

ty: str
String representing the surface type. For the moment only “spherical” surfaces are valid.
rad: float
Radius of the surface in mm
thick: float
Thickness of the material in mm. Distance from this surface to the next. For the last surface it has no real meaning.
semid: float
Semi-diameter (radius) in mm of the round aperture that limits the surface.
matcat: str
String with the material catalog where the material is defined. If matcat = “”, the first material with name matref will be used.
matref: str of float
String with the material name, or or number representing the constant refraction index of the material. matref = “” means there is no material between the 2 surfaces.

Type:: list

The origin of the optical system is located in the center of the Multilens in the optical axis. The center is the mid-point between the 2 most external vertices

class pyoptools.raytrace.comp_lib.PentaPrism(s, *args, **kwargs)¶

Bases: Component

Class to define a pentaprism

Parameters:

s (float) – Size of the entrance aperture of the pentaprism (the aperture is square)
material (float or Material’s subclass instance) – Material of the pentaprism

class pyoptools.raytrace.comp_lib.PowellLens(radius=4.445, thickness=7.62, K=-4.302, R=3.0, *args, **kwargs)¶

Bases: Component

Class to define a powell Lens.

Attributes:

radius: diameter/2. of the lens in the part of the cylinder
thickness: Thickness of the lens measured in the center
Conicity K: Conicity of the aspherical surface
curvature R: curvature of the aspherical surface
material: to calculate the refraction index of the lens (inherited from component)

The origin of the coordinate system is located at the center of the lens in the optical axis (center between vertex).

class pyoptools.raytrace.comp_lib.RectGratting(size=(50.0, 50.0, 10.0), reflectivity=0.0, lpmm=600, angle=0, M=[1], *args, **kwargs)¶: Bases: Component

class pyoptools.raytrace.comp_lib.RectMirror(size=(50.0, 50.0, 10.0), reflectivity=0.5, filter_spec=('nofilter',), *args, **kwargs)¶: Bases: Component

class pyoptools.raytrace.comp_lib.RightAnglePrism(width=50, height=10.0, reflectivity=0, reflega=0, reflegb=0, *args, **kwargs)¶

Bases: Component

Class to define a Right Angle Prism.

ARGUMENTS:

width

Width of the prism face

height

Height of the prism face

material

To calculate the refraction index of the prism (inherited from component)

reflectivity

Reflectivity of the coating of the hypotenuse. For a normal prism it is 0. Note: Total internal reflection works in the prism.

reflega

Reflectivity of the Leg A of the prism. For a normal prism it is 0.

reflegb

Reflectivity of the Leg B of the prism. For a normal prism it is 0.

The origin of the coordinate system is located at the center of hypotenuse face of the prism

class pyoptools.raytrace.comp_lib.RoundMirror(radius=50.0, thickness=10, reflectivity=0.5, filter_spec=('nofilter',), wedge_angle=0.0, *args, **kwargs)¶

Bases: Component

Circular mirror / beam splitter plate with optional wedge.

A round mirror or beam splitter plate with two flat surfaces (S1 reflective, S2 plain) and two cylindrical barrel surfaces (B1, B2).

When wedge_angle is non-zero, S2 is tilted around the Y-axis while S1 remains perpendicular to the optical axis. This produces a wedge beam splitter that deviates the transmitted beam and separates ghost reflections — useful for both beam splitters and mirrors. The azimuthal direction of the wedge is controlled by rotating the entire component around its Z-axis.

Parameters:

radius (float) – Radius of the circular aperture.
thickness (float) – Plate thickness at the center (S1–S2 distance along Z).
reflectivity (float) – Reflectivity of the front surface (S1), from 0 to 1.
filter_spec (tuple) – Filter specification for S1. Default is no filter.
wedge_angle (float) – Tilt angle (radians) of S2 around the Y-axis. Default is 0 (parallel faces, no wedge). The thickness value always represents the center thickness.
*args – Passed to Component.
**kwargs – Passed to Component.

Notes

When wedge_angle is non-zero, only S2 is tilted; the barrel surfaces (B1, B2) are not adjusted. This is valid for small wedge angles (typically < 2 degrees), where the mismatch at the plate edge is negligible. Larger angles leave a geometric gap/overlap between S2 and the barrel surfaces. No validation is performed on wedge_angle; the caller is expected to provide physically sensible values.

class pyoptools.raytrace.comp_lib.SimpleDMDDevice(tilt_angle, on_direction_angle, off_direction_angle, state='flat', width=10.368, height=5.832, thickness=2.0, **kwargs)¶

Bases: Component

Component representing a complete DMD device with parallelepiped structure.

SimpleDMDDevice provides a convenient wrapper for integrating DMD (Digital Micromirror Device) elements into optical systems. The component consists of 6 surfaces arranged as a parallelepiped: - Front face: SimpleDMD surface (active DMD with state-dependent reflection) - Other 5 faces: OpticalStop surfaces (full stops with no apertures)

Origin Pattern: This component follows the “principal surface” pattern where the origin is placed at the center of the optically active surface (the DMD front face at z=0). This is consistent with mirrors and diffraction gratings, but differs from lenses which use the geometric center pattern.

Parameters:

tilt_angle (float) – Tilt angle in radians for the SimpleDMD surface. This is the angle between the surface normal and the perpendicular direction (Z-axis). When tilt_angle=0, the normal is perpendicular to the surface. Use math.radians() to convert from degrees.
on_direction_angle (float) – Direction angle in radians defining where the surface normal is rotated to for the ON state. Measured counter-clockwise from the +X axis in the XY plane when viewed from +Z. For example, 0° points toward +X, 90° points toward +Y, 180° points toward -X, and 270° points toward -Y.
off_direction_angle (float) – Direction angle in radians defining where the surface normal is rotated to for the OFF state. Measured counter-clockwise from the +X axis in the XY plane when viewed from +Z. For example, 0° points toward +X, 90° points toward +Y, 180° points toward -X, and 270° points toward -Y.
state (str, optional) – Initial DMD state: “on”, “off”, or “flat”. Default is “flat”.
width (float, optional) – Width of the DMD device in mm (X dimension). Default is 10.8 mm, matching typical Texas Instruments DLP chip active areas.
height (float, optional) – Height of the DMD device in mm (Y dimension). Default is 10.8 mm.
thickness (float, optional) – Thickness of the DMD device in mm (Z dimension). Default is 2.0 mm.
**kwargs – Additional arguments passed to Component base class.

surflist¶

Dictionary mapping surface names to (surface, position, rotation) tuples. Keys are: “front”, “back”, “left”, “right”, “top”, “bottom”.

Type:: dict

Examples

Create a DMD device with 12° tilt magnitude:

from math import radians
from pyoptools.all import SimpleDMDDevice

dmd = SimpleDMDDevice(
    tilt_angle=radians(12),           # 12° tilt magnitude
    on_direction_angle=radians(45),   # Normal tilts toward northeast
    off_direction_angle=radians(225), # Normal tilts toward southwest
    state="on"
)

Create a DMD with custom dimensions:

dmd = SimpleDMDDevice(
    tilt_angle=radians(12),
    on_direction_angle=radians(45),
    off_direction_angle=radians(225),
    width=15.0,   # Custom width
    height=12.0,  # Custom height
    thickness=3.0 # Custom thickness
)

Change DMD state at runtime:

# Access the SimpleDMD surface and change state
dmd.surflist["front"][0].state = "off"

Notes

Default dimensions: 10.368×5.832×1.0 mm (DLP4710 active area dimensions)
Origin at DMD surface: z=0 is at the center of the front (DMD) face, following the “principal surface” pattern used by mirrors/gratings
SimpleDMD model: Uses the simplified DMD surface model suitable for system-level design. Does not model individual pixels or diffraction effects.
Side faces: All five non-front faces are full stops (OpticalStop with ap_shape=None) that block rays completely.
Direction angles: These specify where the surface normal is rotated to, which may differ from manufacturer datasheets. Adjust empirically to match your desired optical behavior.

f	Effective Focal length
afl	Anterior focal length (negative for positive lenses)
pfl	Posterior focal length (positive for positive lenses)

width	Width of the prism face
height	Height of the prism face
material	To calculate the refraction index of the prism (inherited from component)
reflectivity	Reflectivity of the coating of the hypotenuse. For a normal prism it is 0. Note: Total internal reflection works in the prism.
reflega	Reflectivity of the Leg A of the prism. For a normal prism it is 0.
reflegb	Reflectivity of the Leg B of the prism. For a normal prism it is 0.

radius	Aperture radious of the lens given in mm
thickness	Thickness of the lens measured in the center given in mm
curvature_s1	curvature of the anterior surface given in 1/mm
curvature_s2	curvature of the posterior surface given in 1/mm
material	Used to calculate the refraction index of the lens (inherited from component). Can be a material instance or floating point number if the refraction index is constant.

wavelength	Wavelength used for the calculations
n	Refraction index of the surrounding media

shape	Stop external shape
ap_shape	Aperture (hole) shape