pyoptools.raytrace.surface.surface module¶

class pyoptools.raytrace.surface.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)