pyoptools.raytrace.ray package

Submodules

Module contents

class pyoptools.raytrace.ray.Ray

Bases: object

Class to define a ray in an optical system.

Parameters:

  • origin (tuple of float) – A tuple (x, y, z) representing the origin of the ray.

  • direction (tuple of float) – A tuple (x, y, z) representing the direction vector of the ray.

  • intensity (float, optional) – The intensity of the ray. Defaults to 1.0. Note: The physical meaning of this intensity is currently not well-defined.

  • wavelength (float, optional) – The wavelength of the ray in vacuum, in micrometers. Defaults to 0.58929 μm.

  • n (float, optional) – The refractive index of the medium from which the ray originates. If n is NaN, the ray is assumed to have been emitted from the medium, and the medium’s refractive index is used. Defaults to NaN.

  • label (str or object, optional) – A string or identifier used to track the ray through the optical system. Defaults to an empty string.

  • draw_color (object, optional) – The color used to render this ray. If None, the wavelength is used to determine the color. Otherwise, any valid Matplotlib color identifier can be used. Defaults to None.

  • parent (Ray or None, optional) – The parent ray from which this ray originates, used to follow the ray’s trajectory. Defaults to None.

  • pop (float, optional) – The optical path length of the parent ray. This may be removed in future versions. Defaults to 0.0. TODO: Check if this may be removed

  • orig_surf (list, optional) – A list representing the originating surface of the ray. Defaults to None. TODO: Explain what path means

  • order (int, optional) – The index of the ray in the parent’s child ray list. Defaults to 0.

  • parent_cnt (int, optional) – The count of parent rays for this ray, used to manage complex ray trajectories. Defaults to 0.

add_child(cr)

Add a child Ray to the current Ray and create the appropriate links.

This method adds a Ray object to the child list of the current Ray. The child Ray’s parent attribute is set to the current Ray, and its order attribute is set based on its position in the child list.

Parameters:

cr (Ray) – The Ray object to include in the child list.

Notes

A child Ray with intensity == 0 is used to indicate a parent endpoint, such as an intersection point with a stop, so it must be included in the child list even if its intensity is zero.

static almost_equal(ray1, ray2, tol=1e-07)
ch_coord_sys(origin_coordinates, rotation_angles)

Transform the coordinate system of the Ray.

This method applies a transformation to the coordinate system of the Ray, consisting of translation followed by a rotation. The rotation is applied in the order of the Z, Y, and then X axes. The rotation matrix is calculated as Rm = Rx * Ry * Rz.

Parameters:

  • origin_coordinates (array-like of float) – A list-like object (e.g., tuple, list, or NumPy array) containing three elements (X, Y, Z) that represent the coordinates of the origin of the new coordinate system in the old coordinate system.

  • rotation_angles (array-like of float) – A list-like object (e.g., tuple, list, or NumPy array) containing three elements (Rx, Ry, Rz) that represent the rotation angles in radians to be applied to the old coordinate system. The rotations are applied in the order of Rz (around the Z-axis), then Ry (around the Y-axis), and finally Rx (around the X-axis).

Returns:

A transformed Ray object with the new coordinate system applied.

Return type:

Ray

Notes

The transformation consists of a translation to the new origin first, followed by a rotation.

ch_coord_sys_inv(origin_coordinates, rotation_angles, childs=False)

Transform the coordinate system of the Ray.

This method applies a transformation to the coordinate system of the Ray, consisting of a rotation followed by a translation. The rotation is applied in the order of the X, Y, and then Z axes. The rotation matrix is calculated as Rm = Rz * Ry * Rx. Optionally, the transformation can also be applied to any child objects.

Parameters:

  • origin_coordinates (array-like of float) – A list-like object (e.g., tuple, list, or NumPy array) containing three elements (X, Y, Z) that represent the coordinates of the origin of the old coordinate system in the new coordinate system.

  • rotation_angles (array-like of float) – A list-like object (e.g., tuple, list, or NumPy array) containing three elements (Rx, Ry, Rz) that represent the rotation angles in radians to be applied to the old coordinate system. The rotations are applied in the order of Rz (around the Z-axis), then Ry (around the Y-axis), and finally Rx (around the X-axis).

  • childs (bool, optional) – If True, the coordinate system transformation is also applied to child objects. Default is False.

Returns:

A transformed Ray object with the new coordinate system applied.

Return type:

Ray

Notes

The transformation consists of a rotation applied first, followed by a translation to the new origin.

childs

Get a tuple of child Rays.

This property returns a tuple containing all child Ray objects. The internal list is converted to a tuple to prevent accidental modifications (e.g., using append), ensuring that the child list cannot be modified directly through this property.

Returns:

A tuple containing all child Ray objects.

Return type:

tuple of Ray

copy()

Return a copy of the Ray with specific attributes reset.

This method returns a copy of the current Ray object with the parent attribute set to None, the childs attribute set to an empty list, and the order attribute set to 0.

dir
direction

Get the direction vector of the ray.

The direction vector is normalized to have a length of 1. However, due to floating-point rounding errors, the vector may occasionally deviate slightly from being perfectly normalized.

Returns:

A numpy array (X, Y, Z) with the components of the direction vector of the ray.

Return type:

array

draw_color
get_final_rays(inc_zeros=True)

Find the final rays of the raytrace.

Parameters:

inc_zeros (bool) – If True, all child rays are included in the result. If False, rays with intensity == 0 are excluded.

Returns:

A list of final rays from the raytrace, optionally excluding rays with zero intensity.

Return type:

list of Ray

intensity
label
n
optical_path()

Return the optical path of the beam propagation from the origin of the original ray to the end of this ray (intersection with a surface).

This method calculates the total optical path length from the origin of the original ray to the intersection point of this ray with a surface.

Returns:

The optical path length. Returns 0 if the ray’s intensity is zero. If the ray has no child rays, returns infinity.

Return type:

float

optical_path_parent()

Return the optical path length from the origin of the original ray to the end of this ray’s parent (i.e., the origin of this ray).

This method calculates the optical path length recursively, starting from the origin of the first ray in the sequence and ending at the origin of the current ray. If the pop attribute of the current ray is non-zero, a warning is printed, and the actual parent optical path is used instead.

Returns:

The total optical path length from the original ray’s origin to this ray’s origin.

Return type:

float

Notes

The optical path length is calculated as the product of the distance between two points and the refractive index (n) of the medium. If the ray has a parent, this calculation is performed recursively.

order
orig_surf
origin

Get the origin of the ray as a tuple.

This property returns the origin of the ray in 3D space, represented as a tuple (x, y, z). The origin is stored internally as an Eigen::Vector3d and is converted to a Python tuple when accessed through this property.

Returns:

A numpy array containing the (x, y, z) coordinates of the ray’s origin.

Return type:

numpy array

parent
pop
pos
reverse()

Return a copy of the Ray with specific attributes reset and the direction inverted.

This method returns a copy of the current Ray object with the parent attribute set to None, the childs attribute set to an empty list, the order attribute set to 0, and the ray direction inverted.

wavelength
pyoptools.raytrace.ray.parallel_beam_c(origin=(0.0, 0.0, 0.0), direction=(0.0, 0.0, 0.0), size=(1.0, 1.0), num_rays=(10, 10), wavelength=0.58929, label='', draw_color=None)

Cartesian grid parallel beam

This function creates a parallel beam, where the rays are organized in a cartesian grid.

Parameters:

origin

Tuple with the coordinates of the central ray origin

direction

Tuple with the rotation of the beam around the XYZ axes.

size

Tuple with the beam’s width and the height.

num_rays

Tuple (nx,ny) containing the number of rays used to create the beam.

label

String used to identify the ray source

draw_color

Color used to represent the rays in plots. Default (None) automatically chooses a color based on the wavelength. Otherwise, can be any valid matplotlib color descriptor. See :

pyoptools.raytrace.ray.parallel_beam_p(origin=(0.0, 0.0, 0.0), direction=(0.0, 0.0, 0), radius=0.5, num_rays=(5, 10), wavelength=0.58929, label='', draw_color=None)

Polar grid parallel beam

This function creates a parallel beam, where the rays are organized in a polar grid.

Parameters:

origin

Tuple with the coordinates of the central ray origin

direction

Tuple with the rotation of the beam around the XYZ axes.

r

Beam radious

num_rays

Tuple (nr,na) containing the number of rays used to create the beam.

label

String used to identify the ray source

draw_color

Color used to represent the rays in plots. Default (None) automatically chooses a color based on the wavelength. Otherwise, can be any valid matplotlib color descriptor. See :

pyoptools.raytrace.ray.point_source_c(origin=(0.0, 0.0, 0.0), direction=(0.0, 0.0, 0), span=(0.39269908169872414, 0.39269908169872414), num_rays=(10, 10), wavelength=0.58929, label='', draw_color=None)

Point source, with a cartesian beam distribution

This function creates a point source, where the rays are organized in a cartesian grid.

Parameters:

origin

Tuple with the coordinates of the central ray origin

direction

Tuple with the rotation of the beam around the XYZ axes.

span

Tuple angular size of the ray pencil.

num_rays

Tuple (nx,ny) containing the number of rays used to create the beam.

label

String used to identify the ray source

draw_color

Color used to represent the rays in plots. Default (None) automatically chooses a color based on the wavelength. Otherwise, can be any valid matplotlib color descriptor. See :

pyoptools.raytrace.ray.point_source_p(origin=(0.0, 0.0, 0.0), direction=(0.0, 0.0, 0), span=0.39269908169872414, num_rays=(10, 10), wavelength=0.58929, label='', draw_color=None)

Point source, with a polar beam distribution

This function creates a point source, where the rays are organized in a polar grid.

Parameters:

origin

Tuple with the coordinates of the central ray origin

direction

Tuple with the rotation of the beam around the XYZ axes.

span

Tuple angular size of the ray pencil.

num_rays

Tuple (nr,na) containing the number of rays used to create the beam # TODO Please be more descriptive. It seems really hard to know how much rays we’ll get in advance. What is nr? # TODO What is na?

label

String used to identify the ray source

draw_color

Color used to represent the rays in plots. Default (None) automatically chooses a color based on the wavelength. Otherwise, can be any valid matplotlib color descriptor. See :

pyoptools.raytrace.ray.point_source_r(origin=(0.0, 0.0, 0.0), direction=(0.0, 0.0, 0), span=0.39269908169872414, num_rays=100, wavelength=0.58929, label='', draw_color=None)

Point source, with a ranrom beam distribution

This function creates a point source, where the rays are organized in a random grid.

Parameters:

origin

Tuple with the coordinates of the central ray origin

direction

Tuple with the rotation of the beam around the XYZ axes.

span

Tuple angular size of the ray pencil.

num_rays

Number of rays used to create the beam

label

String used to identify the ray source

draw_color

Color used to represent the rays in plots. Default (None) automatically chooses a color based on the wavelength. Otherwise, can be any valid matplotlib color descriptor. See :