pyoptools.raytrace.surface package¶

Submodules¶

Module contents¶

Module that defines all the classes that describe the optical surfaces

class pyoptools.raytrace.surface.Aperture¶

Bases: Plane

Class to define a surface with an aperture.

The Aperture class is used to define stops in an optical system. It represents a surface that has both an external shape and an internal shape, which defines the aperture (hole) in the surface.

Parameters:

shape (Shape, optional) – An instance of a Shape subclass that defines the external shape of the stop. This parameter is inherited from the Plane class and passed through to it.
ap_shape (Shape, optional) – An instance of a Shape subclass that defines the internal shape of the stop (the aperture shape). This parameter specifies the shape of the hole in the surface.

Examples

Creating an aperture surface with a rectangular external shape and a circular aperture:

ap = Aperture(shape=Rectangular(size=(60, 60)), ap_shape=Circular(radius=2.5))

Notes

To create a stop component, it is recommended to use the Stop class from the comp_lib module. The Stop class creates the aperture surface and encapsulates it in a component that can be used within a System.

ap_shape¶

propagate(ri, ni, nr)¶

Calculate the refracted ray on a surface.

This method calculates the ray refracted (or both refracted and reflected rays) on a surface.

Parameters:

incident_ray (Ray) – The incident ray, which must be in the coordinate system of the surface.
ni (double) – The refractive index of the incident medium.
nr (double) – The refractive index of the refracted medium.

Returns:

A list containing the rays resulting from the ray-surface interaction.

Return type:

list

class pyoptools.raytrace.surface.ArrayDetector¶

Bases: Plane

Class to simulate a CCD-like detector surface.

The ArrayDetector class acts similarly to a real CCD (Charge-Coupled Device) in an optical system. It is designed to capture and store the coordinates of rays that hit the detector surface, effectively simulating the behavior of a CCD detector.

Parameters:

size (tuple of float, optional) – A tuple (width, height) representing the physical size of the detector surface in mm. The default size is (10, 10).
*args (tuple, optional) – Additional positional arguments passed to the Plane superclass.
**kwargs (dict, optional) – Additional keyword arguments passed to the Plane superclass.

size¶

The physical size of the detector surface, as specified during initialization.

Type:: tuple of float

Examples

Creating an ArrayDetector with a specified size:

>>> detector = ArrayDetector(size=(10, 10))

Notes

The ArrayDetector captures the coordinates of rays that hit the detector surface and can be used to simulate the detection process in optical simulations.
The size parameter defines the physical dimensions of the detector, which determines the area over which it can detect incoming rays.
Refer to the Plane class documentation for additional options and functionality inherited by the ArrayDetector.

get_color_histogram(resolution=(256, 256))¶

Generate a color histogram of ray impacts per unit area on the detector surface.

This method returns a 3D array representing the number of ray impacts per unit area of the detector, simulating a color image. Each impact contributes to the RGB color channels based on the ray’s wavelength.

Parameters:: resolution (tuple of int, optional) – A tuple (px, py) representing the resolution of the histogram in pixels. px is the number of pixels along the X-axis, and py is the number of pixels along the Y-axis. The default value is (256, 256). The physical size of the detector is determined during the surface’s creation.
Returns:: A 3D numpy array of shape (px, py, 3) where each element contains the accumulated RGB values corresponding to ray impacts at that pixel position.
Return type:: ndarray

Notes

The resolution parameter controls the resolution of the histogram.

Increasing the resolution results in a finer grid with more pixels, while decreasing the resolution results in a coarser grid with fewer pixels. - The physical size of the detector, defined during its creation, determines the actual area over which the impacts are distributed. - The method does not currently account for the intensity of the rays, which should be considered in future improvements. - The Z-coordinate of the impact is assumed to be zero, consistent with a planar detector surface. - Rays that hit the detector are recorded in the _hit_list, which stores their impact coordinates and wavelengths.

get_histogram(resolution=(256, 256))¶

Generate a histogram of ray impacts per unit area on the detector surface.

This method returns a 2D array (histogram) representing the number of ray impacts per unit area of the detector. The histogram provides a pixelated view of how rays are distributed across the detector surface.

Parameters:: resolution (tuple of int, optional) – A tuple (px, py) representing the resolution of the histogram in pixels. px is the number of pixels along the X-axis, and py is the number of pixels along the Y-axis. The default value is (256, 256). The physical size of the detector is determined during the surface’s creation.
Returns:: A 2D numpy array of shape (px, py) where each element represents the number of ray impacts in that pixel area.
Return type:: ndarray

Notes

The resolution parameter controls the resolution of the histogram.

Increasing the resolution results in a finer grid with more pixels, while decreasing the resolution results in a coarser grid with fewer pixels. - The physical size of the detector, defined during its creation, determines the actual area over which the impacts are distributed. - The method assumes that the Z-coordinate of all impacts is zero, consistent with a planar detector surface. - Rays that hit the detector are recorded in the _hit_list, which stores their impact coordinates.

size¶

class pyoptools.raytrace.surface.Aspherical¶

Bases: Surface

Class representing a high-order aspherical optical surface.

An aspherical surface is defined by the equation:

Z = (Ax*x**2 + Ay*y**2) /: (1 + sqrt(1 - (1+Kx)*Ax**2*x**2 - (1+Ky)*Ay**2*y**2)) + Poly2D(x, y)

The aspherical surface combines a base aspheric shape with an additional polynomial deformation term defined by Function2D.

Parameters:

shape (Shape object) – The shape of the aspherical surface.
Ax (float, optional) – X-axis curvature coefficient. Default is 0.
Ay (float, optional) – Y-axis curvature coefficient. Default is 0.
Kx (float, optional) – X-axis conic constant. Default is 0.
Ky (float, optional) – Y-axis conic constant. Default is 0.
poly (Poly2D, optional) – Polynomial surface deformation term. If None, a zero-order polynomial is used (no deformation).
*args – Additional arguments passed to the parent Surface class.
**kwargs – Additional arguments passed to the parent Surface class.

xmin, xmax

Bounds of the surface in the x direction.

Type:: float

ymin, ymax

Bounds of the surface in the y direction.

Type:: float

zmin, zmax

Bounds of the surface in the z direction.

Type:: float

DX, DY

Partial derivatives of the polynomial deformation term.

Type:: Poly2D

Examples

>>> from pyoptools.raytrace.surface import Aspherical
>>> from pyoptools.raytrace.shape import Rectangle
>>> from pyoptools.misc.function_2d.poly_2d.poly_2d import Poly2D
>>> surface = Aspherical(
...     shape=Rectangle(size=(5,5)),
...     Ax=0.5,
...     Ay=0.3,
...     Kx=0.1,
...     Ky=0.1,
...     poly=Poly2D((0,1,1))
... )

Notes

The surface shape is determined by the combination of the base aspherical equation and the polynomial deformation term. The polynomial term allows for modeling complex surface irregularities or corrections.

Ax¶

Ay¶

DX¶

DY¶

Kx¶

Ky¶

poly¶

xmax¶

xmin¶

ymax¶

ymin¶

zmax¶

zmin¶

class pyoptools.raytrace.surface.Cylinder¶

Bases: Surface

Class to define cylindrical surfaces.

The Cylinder class represents a tube or hollow cylindrical surface in an optical system. The cylinder is defined by its radius and length, with the center located at the origin of the coordinate system (0, 0, 0) and its length aligned along the Z-axis.

Parameters:

radius (double, optional) – The radius of the cylinder. The default value is 10.0.
length (double, optional) – The length of the cylinder. The default value is 10.0.
*args (tuple, optional) – Additional positional arguments passed to the Surface superclass.
**kwargs (dict, optional) – Additional keyword arguments passed to the Surface superclass.

radius¶

The radius of the cylinder.

Type:: double

length¶

The length of the cylinder.

Type:: double

Examples

Creating a cylinder surface with a specific radius and length:

>>> cs = Cylinder(radius=5.0, length=10.0)

Notes

The cylinder is centered at the origin of the coordinate system, with its length extending along the Z-axis.
This class inherits additional functionality and attributes from the Surface class, which can be used to further define the optical properties of the cylinder.
Refer to the Surface class documentation for more details on other options and attributes that can be used in conjunction with this class.

length¶

polylist()¶

Generate a list of points and polygons representing the cylindrical surface.

This method generates a list of points and polygons that can be used to visualize the cylindrical surface. It is specifically designed for closed surfaces, which is why it is overloaded in this class.

Returns:

points: A list of tuples, where each tuple represents a point

(X, Y, Z) in 3D space that forms part of the cylindrical surface. - polys: A list of tuples, where each tuple contains three indices corresponding to points in the points list. These indices define the triangular polygons that make up the surface of the cylinder.

Return type:

tuple of lists

Notes

The method discretizes the cylindrical surface by sampling it at 40

evenly spaced angles around the Z-axis. For each angle, two points are generated: one at the lower end of the cylinder (Z1) and one at the upper end (Z2). - The polygons are then created by connecting adjacent points to form triangular surfaces, ensuring that the entire cylindrical surface is covered. - The method is designed to handle the closed nature of the cylindrical surface, which is why it is overloaded in this specific class.

Examples

Generating the points and polygons for a cylinder surface:

points, polys = cylinder.polylist()

radius¶

class pyoptools.raytrace.surface.Cylindrical¶

Bases: Surface

Class to define cylindrical optical surfaces.

The Cylindrical class represents a cylindrical optical surface. The surface is defined by specifying the aperture shape and the radius of curvature of the cylinder.

The vertex of the cylindrical surface is located at the origin of coordinates (0, 0, 0).

Parameters:

curvature (double, optional) – The curvature of the cylindrical surface. A positive curvature indicates a convex surface, while a negative curvature indicates a concave surface. The default is 0.0.
*args (tuple, optional) – Additional positional arguments passed to the Surface superclass.
**kwargs (dict, optional) – Additional keyword arguments passed to the Surface superclass.

curvature¶

The curvature of the cylindrical surface, as specified during initialization.

Type:: double

Examples

Creating a cylindrical surface with a rectangular aperture and a specific curvature:

>>> cs = Cylindrical(shape=Rectangular(size=(10, 20)), curvature=0.15)

Notes

The curvature is defined as the reciprocal of the radius of curvature (i.e., curvature = 1 / radius). A flat surface would have a curvature of 0.
Refer to the Surface documentation for additional options and parameters that can be used when defining the surface.

curvature¶

class pyoptools.raytrace.surface.IdealPPlanes¶

Bases: Surface

Clase que representa un par de superficies principales ideales. Se utiliza para crear lentes ideales gruesas

propagate(incident_ray, ni, nr)¶: This is overloaded, as the ray propagation here is different than the snell law

class pyoptools.raytrace.surface.IdealSurface¶

Bases: Surface

Clase que representa una superficie ideal. Se utiliza para crear lentes ideales

f¶

normal(ri)¶: Method that returns the normal to the surface

propagate(ri, ni, nr)¶

Calculate the refracted ray on a surface.

This method calculates the ray refracted (or both refracted and reflected rays) on a surface.

Parameters:

incident_ray (Ray) – The incident ray, which must be in the coordinate system of the surface.
ni (double) – The refractive index of the incident medium.
nr (double) – The refractive index of the refracted medium.

Returns:

A list containing the rays resulting from the ray-surface interaction.

Return type:

list

class pyoptools.raytrace.surface.Plane¶

Bases: Surface

Class to define a plane surface.

Description:

Plane is a class to define rectangular plane surfaces. The surface shape is given by the shape attribute

Example

>>> ps=Plane(shape=Rectangular(size=(25,15)))

class pyoptools.raytrace.surface.Powell¶

Bases: Surface

Class that defines a Powell lens surface

A Powell lens surface is defined as:

Z=sqrt((1+K)*x**2- 2*R*x+y**2)

without an additional poly2d definition like in the aspherical surface case The values K and R correspond to the conicity and curvature respectively

Example

>>> cs=Powell(shape=Circular(radius=2.5), K=-4.302, R=3.00)

K¶

R¶

normal(int_p)¶

Return the vector normal to the surface

This method returns the vector normal to the asphere at a point int_p=(x,y,z).

Note: It uses x and y to calculate the z value and the normal.

poly¶

zmax¶

zmin¶

class pyoptools.raytrace.surface.RPPMask¶

Bases: Plane

Reflective plane phase mask surface.

A class to define diffractive plane surfaces that can be either reflective, transmissive, or both. The surface’s behavior is controlled by its reflectivity: 1 for purely reflective, 0 for purely transmissive, or a value between 0 and 1 for both behaviors.

Parameters:

phm (Poly2D, optional) – Polynomial describing the phase modulation of the grating. The X and Y input values of the polynomial are in microns. Default is a zero polynomial.
M (list, optional) – List of diffraction orders to consider. Default is [1].
*args – Additional arguments passed to the parent Plane class.
**kwargs – Additional arguments passed to the parent Plane class.

phm¶

Phase modulation polynomial

Type:: Poly2D

phx¶

X derivative of the phase modulation polynomial

Type:: Poly2D

phy¶

Y derivative of the phase modulation polynomial

Type:: Poly2D

M¶

Diffraction orders

Type:: list

Notes

The surface shape is given by the shape attribute inherited from the parent class.

Examples

Create a 10mm x 10mm linear grating with a fringe every 15 microns:

>>> g = RPPMask(shape=Rectangular(size=(10,10)),
...             phm=Poly2D([0,2*pi/15.,0]),
...             M=[1])

M¶

phm¶

phx¶

phy¶

propagate(incident_ray, ni, nr)¶

Calculate the propagation of a ray through a diffraction grating.

This method implements the physical behavior of light when it encounters a reflective plane phase mask, considering both transmitted and reflected diffracted rays based on the surface’s reflectivity. :param incident_ray: The incoming ray to be propagated :type incident_ray: Ray :param ni: Index of refraction of the incident medium :type ni: float :param nr: Index of refraction of the refractive medium :type nr: float

Returns:: List of Ray objects representing the propagated rays (transmitted and/or reflected) after interaction with the grating
Return type:: list

Notes

All units are in millimeters
The intensity of the output rays is divided equally among the diffraction orders
Physically impossible rays (where oz2 < 0) are handled by returning the incident ray direction with zero intensity

class pyoptools.raytrace.surface.Spherical¶

Bases: Surface

Class to define spherical optical surfaces.

The Spherical class represents a spherical optical surface. The surface is defined by specifying the shape of the aperture and the radius of curvature of the sphere.

The vertex of the spherical surface is located at the origin of coordinates (0, 0, 0), and the aperture is centered at the origin as well.

Parameters:

curvature (double, optional) – The curvature of the spherical surface. A positive curvature indicates a convex surface, while a negative curvature indicates a concave surface. The default is 0.0.
*args (tuple, optional) – Additional positional arguments passed to the Surface superclass.
**kwargs (dict, optional) – Additional keyword arguments passed to the Surface superclass.

curvature¶

The curvature of the spherical surface, as specified during initialization.

Type:: double

Examples

Creating a spherical surface with a circular aperture and specific curvature:

>>> cs = Spherical(shape=Circular(radius=60), curvature=0.15)

Notes

The curvature is defined as the reciprocal of the radius of curvature (i.e., curvature = 1 / radius). A flat surface would have a curvature of 0.
Refer to the Surface documentation for additional options and parameters that can be used when defining the surface.

curvature¶

class pyoptools.raytrace.surface.Surface¶

Bases: Picklable

” Surface is an abstract superclass for all optical surface objects. This class defines an API that all subclasses must implement.

All subclasses of Surface share the following attributes and properties:

reflectivity¶

A floating-point number between 0 and 1 representing the reflectivity of the surface. A value of 0 indicates a completely transparent surface, while a value of 1 indicates a completely reflective surface. Values between 0 and 1 represent beam splitters.

Type:: float

shape¶

An instance of the Shape class that defines the aperture shape of the surface.

Type:: Shape

id¶

A list of surface identifiers or tags. (Clarification of its specific purpose may be needed.)

Type:: list

Properties¶

----------

hit_list¶

A read-only property that provides access to the _hit_list attribute, which stores information about rays that have impacted the surface. This list tracks the points of impact in the surface’s reference system and keeps a pointer to the hitting ray, allowing retrieval of information such as intensity, wavelength, and other ray properties. The reset method clears this list.

Type:: list

Notes

Subclasses of Surface should implement specific methods to define geometry and behavior.

distance(incident_ray)¶

Calculate the distance propagated by a ray until it intersects with a surface.

This method returns the distance traveled by a ray from its origin to its point of intersection with a surface.

Parameters:

incident_ray (Ray) – The incident ray, which must be in the coordinate system of the surface.

Returns:

A tuple (distance, point_of_intersection, surface), where:

distancefloat: The distance from the ray’s origin to the point of intersection with the surface.
point_of_intersectiontuple: The coordinates of the intersection point in the coordinate system of the surface.
surfaceSurface: A reference to the surface object.

Return type:

tuple

get_z_at_point(x, y)¶

Python wrapper for calculating Z coordinate at a single point on the Surface.

This method provides a Python-accessible interface to topo_cy, allowing calculation of the surface height at a single (X, Y) coordinate pair.

Parameters:

x (double) – The X coordinate of the point.
y (double) – The Y coordinate of the point.

Returns:

The Z coordinate (height) of the surface at the specified point.

Return type:

double

Note

This is a wrapper around topo_cy which must be implemented in Surface subclasses.

hit_list¶

A read-only property that provides an immutable view of the hit list.

Returns:: A tuple containing the elements of the hit list, ensuring immutability.
Return type:: tuple

id¶

intersection(incident_ray)¶

Calculate the point of intersection between a ray and this surface.

This method returns the point of intersection between the surface and the incident ray. The intersection point is calculated in the coordinate system of the surface.

This calculation is performed considering only the ray and this surface in isolation. It does not take into account any other optical elements that may be present in the system. For this method, the only existing elements are the ray and the surface.

If there is no point of intersection, such as when the ray is outside the surface’s boundary, the method returns a tuple (NaN, NaN, NaN).

Parameters:: incident_ray (Ray) – The incident ray, which must be in the coordinate system of the surface.
Returns:: A tuple (x, y, z) containing the coordinates of the point of intersection between the ray and the surface. If there is no intersection, it returns (NaN, NaN, NaN).
Return type:: tuple

normal(intersection_point)¶

Calculate the normal vector at a specific intersection point.

This method returns the normalized normal vector at a given intersection point. The method must be overloaded in all Surface subclasses to provide surface-specific geometry calculations.

Parameters:: intersection_point (tuple or list) – The intersection point as a tuple or list (x, y, z) in the coordinate system of the surface.
Returns:: A tuple (dx, dy, dz) representing the normalized normal vector at the intersection point.
Return type:: tuple

Notes

The normal vector is normalized and perpendicular to the surface at

the given intersection point. - This method should be overloaded in all subclasses of Surface to provide specific implementations based on the surface geometry.

polylist()¶

propagate(incident_ray, ni, nr)¶

Calculate the refracted ray on a surface.

This method calculates the ray refracted (or both refracted and reflected rays) on a surface.

Parameters:

incident_ray (Ray) – The incident ray, which must be in the coordinate system of the surface.
ni (double) – The refractive index of the incident medium.
nr (double) – The refractive index of the refracted medium.

Returns:

A list containing the rays resulting from the ray-surface interaction.

Return type:

list

pw_cohef(ni, nr, ilimit, slimit, step, order, rsamples, zb)¶

Method to generate the taylor polinomial coheficients that can be used to obtain the phase and intensity for different plane wave inclinations.

Notes

The pupil is normalized to the radius of the lens
This method assumes a circular shaped pupil
The phase is returned as an optical path
The intensity is normalized to 1

Arguments:

ni,nr	Refraction index from the incident and refracted sides
ilimit	Inferior limit for incidence angle of the plane wave in radians
slimit	Superior limit for incidence angle of the plane wave in radians
step	Step to be used to generate the interpolation data
order	Order of the Taylor interpolation used
rsamples	Tuple containing the number of ray samples to be used in each direction
zb	Z position of the plane where the measurementas are made. The origin is the vertex of the surface. If None, an estimate position is taken.

pw_propagate(ri, ni, nr, rsamples, shape, order, z)¶

Method to calculate wavefront emerging from the surface

This method calculates the wavefront emerging from the optical surface when illuminated by an unity amplitude plane wave. The k vector of the incoming PW is given by the direction of ri. The wavelength of the PW is given by the wavelength of ri. The origin of ri is not used at all.

Parameters:

ray (ri -- surface incident)
n. (ni -- refraction index in the incident media)
media (nr -- refraction index in the refracted)
surface (rsamples -- number of rays used to sample the)
wavefront (shape -- shape of the output)
fit (order -- order of the polynomial)
the (z -- Z position of the input and output plane. The origin is) – surface vertex

ri must be in the coordinate system of the surface Note: The ray comes from the negative side. Need to change this

pw_propagate1(ri, ni, nr, rsamples, isamples, knots)¶

Method to calculate wavefront emerging from the surface

Note

This method needs to be checked, because the incoming plane wave has not a constant intensity. The ray distribution is affected by the surface topography. it is better to use the slow version pw_propagate.

The input and output planes are located at z=0 in the surface coordinated system.

Note: this method needs to be checked, because the incoming plane wave has not a constant intensity. The ray distribution is affected by the surface topography. it is better to use the slow version pw_propagate1.

Note: The ray comes from the negative side. Need to change this

Parameters:

ray (ri -- isurface.pyncident)
n. (ni -- refraction index in the incident media)
media (nr -- refraction index in the refracted)

ri must be in the coordinate system of the surface

pw_propagate_list(ri, ni, nr, rsamples, z)¶

Method to calculate wavefront emerging from the surface

This method calculates samples of the wavefront emerging from the optical surface when illuminated by an unity amplitude plane wave. The k vector of the incoming PW is given by the direction of ri. The wavelength of the PW is given by the wavelength of ri. The origin of ri is not used at all.

The returned value is a list containing the x,y coordinates of the ray list in the output surface, and the optical path at such point.

To create an output matrix, this values must be interpolated.

Parameters:

ray (ri -- incident)
n. (ni -- refraction index in the incident media)
media (nr -- refraction index in the refracted)
surface (rsamples -- number of rays used to sample the)
the (z -- Z position of the input and output plane. The origin is) – surface vertex

ri must be in the coordinate system of the surface Note: The ray comes from the negative side. Need to change this

reflectivity¶

reset()¶: Remove information from the hit_list

shape¶

topo(X, Y)¶

Calculate the Z values for given X and Y coordinates on the Surface object.

This method computes the topography (Z values) of the Surface object corresponding to the provided X and Y coordinates. It is primarily used for plotting the surface.

Parameters:

X (list of float) – A list of X coordinates on the surface for which Z values are to be calculated.
Y (list of float) – A list of Y coordinates on the surface for which Z values are to be calculated.

Returns:

A list of Z values corresponding to each (X, Y) pair, representing the height of the surface at those coordinates.

Return type:

list of float

Note

This method uses the topo_cy method, which must be overloaded in all Surface subclasses.

wf_propagate(wf, ni, nr, samples, shape, knots)¶

Method to calculate wavefront emerging from the surface

This method calculates the wavefront emerging from the optical surface when illuminated by an arbitrary wavefront.

The input and output planes are located at z=0 in the surface coordinated system.

Parameters:

wavefront (wf -- Field instance containing the incoming)
n. (ni -- refraction index in the incident media)
media. (nr -- refraction index in the refracted)
field. (samples -- Tuple containing the number of rays used to sample the)
field (shape -- Tuple containing the shape of the output)

class pyoptools.raytrace.surface.TaylorPoly¶

Bases: Surface

Class that defines a high order polynomical surface

An aspherical surface is defined as:

Z= poly2d(x,y)

Example

>>> cs=TaylorPoly(shape=Rectangle(size=(5,5)), poly =poly2d((0,1,1)))

normal(int_p)¶

Return the vector normal to the surface

This method returns the vector normal to the asphere at a point int_p=(x,y,z).

Note: It uses x and y to calculate the z value and the normal.

poly¶

zmax¶

zmin¶