6.5. tracer.geometry Submodule

6.5.1. tracer.geometry.aperture

class optrace.tracer.geometry.aperture.Aperture(surface, pos, **kwargs)

Create a Aperture object. Used for absorption of rays.

Parameters:

  • surface (Surface) – Surface object

  • pos (list | ndarray) – 3D position of Aperture center (numpy array or list)

  • kwargs – keyword parameters for parent classes

abbr: str = 'AP'

object abbreviation

6.5.2. tracer.geometry.detector

class optrace.tracer.geometry.detector.Detector(surface, pos, **kwargs)

Create a Detector object.

Parameters:

  • surface (Surface) – the Detector surface

  • pos (list | ndarray) – position in 3D space

  • kwargs – additional keyword arguments for parent classes

abbr: str = 'DET'

object abbreviation

6.5.3. tracer.geometry.filter

class optrace.tracer.geometry.filter.Filter(surface, pos, spectrum, **kwargs)

Create a Filter object. A filter is a surface with wavelength dependent or constant transmittance. Useful for color filters or apertures.

Parameters:

  • Surface – Surface object

  • pos (list | ndarray) – 3D position of Filter center

  • spectrum (TransmissionSpectrum) – transmission spectrum. Output range needs be inside [0, 1].

  • kwargs – additional keyword arguments for parent classes

  • surface (Surface)

__call__(wl)

Return filter transmittance for specified wavelengths, pass-through of spectrum.__call__, see this method for details

Parameters:

wl (ndarray)

Return type:

ndarray

color(rendering_intent='Absolute', clip=True, L_th=0, chroma_scale=None)

Get Filter color under daylight (D65). pass-through of spectrum.color, see this method for details

Return type:

tuple[float, float, float, float]

abbr: str = 'F'

object abbreviation

6.5.4. tracer.geometry.group

class optrace.tracer.geometry.group.Group(elements=None, n0=None, **kwargs)

Create a group by including elements from the ‘elements’ parameter. Without this parameter an empty group is created.

A Group contains multiple elements of types Lens, PointMarker, LineMarker, RaySource, Filter, Aperture, Detector. This class provides the functionality for moving, rotating and flipping its whole geometry. A well as including, removing elements and clearing is whole content.

Parameters:

  • elements (list[Element]) – list of elements to add. Can be empty

  • n0 (RefractionIndex) – ambient refraction index

  • kwargs – additional keyword arguments for the BaseClass class

add(el)

Add an element, list or group to the geometry.

Parameters:

el (Element | list[Element] | Group) – object to add

Return type:

None

clear()

clear geometry, remove all objects from group

Return type:

None

flip(y0=0, z0=None)

Flip the group (= rotate by 180 deg) around an axis parallel to the x-axis and through the point (y0, z0). By default y0 = 0 and z0 is the center of the z-extent of the group.

This also sets and reassigns ambient and lens refraction indices.

Parameters:

  • y0 (float) – y-position of axis

  • z0 (float) – z-position of axis

Return type:

None

has(el)

checks if element is included in geometry. Don’t use this function with lists or Groups.

Parameters:

el (Element)

Returns:

if object is inside group geometry

Return type:

bool

move_to(pos)

Moves all elements such that pos is the new position of the first element. Relative distances between objects are mantained

Parameters:

pos (list | ndarray) – new position (3 element list/array)

Return type:

None

remove(el)

Remove the element specified by its id from raytracing geometry. Returns True if element(s) have been found and removes, False otherwise.

Parameters:

el (Element | list[Element] | Group)

Returns:

if anything was found and removed

Return type:

bool

rotate(angle, x0=0, y0=0)

Rotate the group around an axis at (x0, y0) with direction (0, 0, 1) The rotation angle is the angle in the xy-plane with counter-clockwise direction

Parameters:

  • angle (float) – rotation angle in degrees

  • x0 (float) – x-position of axis

  • y0 (float) – y-position of axis

Return type:

None

tma(wl=555.0)

Creates an ray transfer matrix analysis object from the group geometry. Note that this is a snapshot and does not get updated.

Parameters:

wl (float) – wavelength for matrix analysis

Returns:

ray transfer matrix analysis object

Return type:

TMA

apertures

apertures in raytracing geometry

detectors

detectors in raytracing geometry

property elements: list[Element]

all included elements sorted in z-order

property extent: tuple[float, float, float, float, float, float]

Extent of all elements. Equivalent to the smallest cuboid that encompasses all group objects inside.

Returns:

tuple of the form (x0, x1, y0, y1, z0, z1)

filters

filters in raytracing geometry

lenses

lenses in raytracing geometry

markers

markers in raytracing geometry

n0

ambient refraction index

property pos: ndarray

position of first element (sorting in z-order)

ray_sources

ray sources in raytracing geometry

property tracing_surfaces: list[Surface]

List of all tracing surfaces (lenses, apertures, filters). Sorted by center z-position.

Returns:

sorted list of tracing surfaces

volumes

volumes in raytracing geometry

6.5.5. tracer.geometry.ideal_lens

class optrace.tracer.geometry.ideal_lens.IdealLens(r, D, pos, n2=None, **kwargs)

Create an ideal lens, that refracts light without aberrations to the correct image distance. An IdealLens has a disc geometry (CircularSurface) and zero thickness.

Parameters:

  • r (float) – radial size of the lens

  • D (float) – optical power of the lens, this is the inverse of the geometrical focal length

  • n2 (RefractionIndex) – refraction index behind lens (positive z direction) (RefractionIndex object)

  • pos (list | ndarray) – 3D position of lens center (list or numpy array)

  • kwargs – additional keyword arguments for parent classes

is_ideal: bool = True

6.5.6. tracer.geometry.lens

class optrace.tracer.geometry.lens.Lens(front, back, n, pos, de=0, d=None, d1=None, d2=None, n2=None, **kwargs)

Creates a lens object using 2 surfaces and additional properties. Of the thickness parameters only one of d, de or (d1, d2) needs to be specified.

A lens is an geometrical object with two refractive surfaces. A refractive index is specified for the material and one for the area behind the lens (optional)

Parameters:

  • front (Surface) – front surface (smaller z-position) (Surface object)

  • back (Surface) – back surface (higher z-position) (Surface object)

  • de (float) – thickness extension. additional thickness between maximum height of front and minimal height of back, (float)

  • d (float) – thickness at the optical axis / lens center

  • d1 (float) – thickness of front surface relative to surface center position (float)

  • d2 (float) – thickness of back surface relative to surface center position (float)

  • n (RefractionIndex) – material refraction index (RefractionIndex object)

  • n2 (RefractionIndex) – refraction index behind lens (positive z direction) (RefractionIndex object)

  • pos (list | ndarray) – 3D position of lens center (list or numpy array)

  • kwargs – additional keyword arguments for parent classes

tma(wl=555.0, n0=None)

Matrix analysis object for the lens. Note that the lens does not know which medium n0 comes before it, if you want some value n0 != 1, you need to specify n0. The medium 2 after it is set by Lens.n2

Parameters:
Returns:

transfer matrix analysis object

abbr: str = 'L'

object abbreviation

property d: float

lens thickness at center

property de: float

thickness extension

is_ideal: bool = False

6.5.7. tracer.geometry.ray_source

class optrace.tracer.geometry.ray_source.RaySource(surface, pos=None, divergence='None', div_angle=0.5, div_2d=False, div_axis_angle=0, div_func=None, div_args={}, spectrum=None, power=1.0, s=None, s_sph=None, orientation='Constant', conv_pos=None, or_func=None, or_args={}, polarization='Uniform', pol_angle=0.0, pol_angles=None, pol_probs=None, pol_func=None, pol_args={}, **kwargs)

Create a RaySource with a specific area, orientation, divergence, polarization, power and spectrum.

  • When a ‘surface’ is provided as Surface (RectangularSurface, RingSurface, Point, Line, CircularSurface), there will be uniform emittance over the surface and the spectrum can be set by the ‘spectrum’ parameter.

  • When ‘surface’ is provided as GrayscaleImage, the emittance follows the image intensity distribution, the spectrum can be set by the ‘spectrum’ parameter.

  • When ‘surface’ is provided as RGBImage, the spectrum and brightness for each pixel is generated from three primaries so it matches the pixel color.

Parameters:

  • surface (Surface | Line | Point | GrayscaleImage | RGBImage) – emitting Surface, Point, Line, RGBImage or GrayscaleImage object

  • divergence (str) – divergence type, see “divergences” list

  • orientation (str) – orientation type, see “orientations” list

  • polarization (str) – polarization type, see “polarizations” list

  • spectrum (LightSpectrum) – LightSpectrum of the RaySource

  • pos (list | ndarray) – 3D position of RaySource center

  • power (float) – total power of the RaySource in W

  • div_angle (float) – cone opening angle in degrees

  • div_2d (bool) – if divergence is inside of a circular arc instead a cone

  • div_axis_angle (float) – axis angle for 2D divergence with div_2d=True

  • div_func (Callable[[ndarray], ndarray]) – divergence function, must take angles in radians in range [0, div_angle] and return a probability

  • div_args (dict) – additional keywords arguments for div_func in a dictionary

  • conv_pos (list[float] | ndarray) – convergence position for orientation=’Converging’, 3D position

  • pol_angle (float) – polarization angle as float, value in degrees

  • pol_angles (list[float]) – polarization angle list, values in degrees

  • pol_probs (list[float]) – probabilities for the pol_angles

  • pol_func (Callable[[ndarray], ndarray]) – polarization function, must take an numpy array in range [0, 2*pi] and return a probability

  • pol_args (dict) – dictionary of additional keyword arguments for pol_func

  • s (list | ndarray) – 3D direction vector

  • s_sph (list | ndarray) – 3D direction vector in spherical coordinates, specified as theta, phi, both in degrees

  • or_func (Callable[[ndarray, ndarray], ndarray]) – orientation function, takes 1D array of x and y coordinates as input, returns (N, 3) numpy 2D array with orientations

  • or_args (dict) – dictionary of additional keyword arguments for or_func

  • kwargs – additional keyword arguments for parent classes

color(rendering_intent='Ignore', clip=False)

Get the average color of the RaySource

Parameters:

  • rendering_intent (str) – rendering_intent for color calculation

  • clip – if sRGB values are clipped

Returns:

tuple of sRGB values with data range [0, 1]

Return type:

tuple[float, float, float]

create_rays(N, no_pol=False, power=None)

Generate N rays according to the property of the RaySource

Parameters:

  • N (int) – number of rays

  • no_pol (bool) – if polarization needs to be calculated

  • power (float) – power to use, when not specified internal object value is used

Returns:

position array (numpy 2D array), direction array (numpy 2D array), polarization array (numpy 2D array) weight array (numpy 1D array), wavelength array (numpy 1D array) first dimension: ray number, second dimension: values

Return type:

tuple[ndarray, ndarray, ndarray, ndarray, ndarray]

abbr: str = 'RS'

object abbreviation

divergences: list[str] = ['None', 'Lambertian', 'Isotropic', 'Function']

Possible divergence types

orientations: list[str] = ['Constant', 'Converging', 'Function']

Possible orientation types

polarizations: list[str] = ['Constant', 'Uniform', 'List', 'Function', 'x', 'y', 'xy']

Possible polarization types

6.5.8. tracer.geometry.element

Parent class for Filter, Aperture, Lens, Detector, Volume, RaySource, Marker and Volume

A Element has a front and an optional back.

Meaning of ‘front’ and ‘back’

  • Defined by the surface z-position

  • Element.front: Surface with smaller z-position

  • Element.back: Surface with larger z-position

Properties with FrontSurface only:

  • Element.pos is Element.front.pos.

  • Element.extent is Element.front.extent.

  • Element.surface is an alias for Element.front

Properties with FrontSurface + BackSurface:

  • d = (Element.d1 + Element.d2) is the whole z-difference between the centers of both surfaces

  • Element.d1 defines the z-distance between z-pos of the Element and the z-pos of Element.front

  • Element.d2 defines the z-distance between z-pos of the Element and the z-pos of Element.back

  • Element.pos is (z-pos of front + d1) or (z-pos of back - d2),

    which by above definitions are the same.

  • Element.extent is the extent of both surfaces,

    each value is determined by checking which surface has a larger extent in this dimension

class optrace.tracer.geometry.element.Element(front, pos, back=None, d1=None, d2=None, **kwargs)

Parent class for Lens, RaySource, Detector, Aperture, Filter, PointMarker and LineMarker.

Parameters:

  • front (Surface | Line | Point) – front surface/point/line

  • pos (list | ndarray) – 3D position of element

  • back (Surface | Point | Line) – back surface

  • d1 (float) – z-distance between front and pos

  • d2 (float) – z-distance between pos and back

  • kwargs – keyword arguments for optrace.tracer.base_class.BaseClass

cylinder_surface(nc=100)

Get a 3D surface representation of the Element cylinder for plotting.

Parameters:

nc (int) – number of surface edge points (int)

Returns:

tuple of coordinate arrays X, Y, Z (2D numpy arrays)

Return type:

tuple[ndarray, ndarray, ndarray]

flip()

flip the element around the x-axis, absolute position stays the same

Return type:

None

get_desc(fallback=None)

Get the description of the object.

Parameters:

fallback (str) – unused parameter

Returns:

the descriptions

Return type:

str

has_back()
Returns:

if the Element has a BackSurface

Return type:

bool

move_to(pos)

Moves the Element in 3D space.

Parameters:

pos (list | ndarray) – new 3D position of Element center (list or numpy array)

Return type:

None

rotate(angle)

rotate the object around the z-axis :param angle: rotation angle in degrees

Parameters:

angle (float)

Return type:

None

set_surface(surf)

Assign a new Surface to the Element.

Parameters:

surf (Surface) – Surface to assign

Return type:

None

abbr: str = 'EL'

abbreviation for objects of this class

property extent: tuple[float, float, float, float, float, float]

3D extent of the Element

property pos: ndarray

position of the Element center

property surface

alias for Element.front

6.5.9. tracer.geometry.point

class optrace.tracer.geometry.point.Point(**kwargs)

Create a Point object. This is just a position in 3D space

Parameters:

kwargs – additional keyword arguments for parent classes

flip()

flip the point around the x-axis

Return type:

None

move_to(pos)

Moves the surface in 3D space.

Parameters:

pos (list | ndarray) – 3D position to move to (list or numpy 1D array)

Return type:

None

random_positions(N)

Get random positions, for a point that is just the list of its position.

Parameters:

N (int) – number of positions

Returns:

positions, shape (N, 3)

Return type:

ndarray

rotate(angle)

rotate the point around the z-axis

Parameters:

angle (float) – rotation angle in degrees

Return type:

None

property extent: tuple[float, float, float, float, float, float]

Point extent, values for a smallest box encompassing all of the surface

Returns:

tuple of x0, x1, y0, y1, z0, z1

6.5.10. tracer.geometry.line

class optrace.tracer.geometry.line.Line(r, angle=0, **kwargs)

Create a Line object. A Line lies in a plane perpendicular to the z-axis.

Parameters:

  • r (float) – radial size

  • angle (float) – axis angle in xy-plane, value in degrees

  • kwargs – additional keyword arguments for parent classes

flip()

flip the line around the x-axis

Return type:

None

move_to(pos)

Move the line in 3D space.

Parameters:

pos (list | ndarray) – 3D position to move to (list or numpy 1D array)

Return type:

None

random_positions(N)

Get random 3D positions on the line, uniformly distributed

Parameters:

N (int) – number of positions

Returns:

position array, shape (N, 3)

Return type:

ndarray

rotate(angle)

rotate the line around the z-axis

Parameters:

angle (float) – rotation angle in degrees

Return type:

None

property extent: tuple[float, float, float, float, float, float]

Line extent, values for a smallest box encompassing all of the surface

Returns:

tuple of x0, x1, y0, y1, z0, z1

6.5.11. tracer.geometry.marker.point_marker

class optrace.tracer.geometry.marker.point_marker.PointMarker(desc, pos, text_factor=1.0, marker_factor=1.0, label_only=False, **kwargs)

Create a new PointMarker.

A PointMarker is an Element, where the front surface is a point Markers are used as point and/or text annotations in the tracing geometry text only: provide a text string and set the parameter label_only=True marker/point only: leave the text empty

Parameters:

  • desc (str) – text to display

  • pos (list | ndarray) – position of marker

  • text_factor (float) – text scaling factor

  • marker_factor (float) – marker scaling factor

  • label_only (bool) – don’t plot marker, only text

  • kwargs – additional keyword args for class Element and BaseClass

6.5.12. tracer.geometry.marker.line_marker

class optrace.tracer.geometry.marker.line_marker.LineMarker(r, pos, desc='', angle=0, text_factor=1.0, line_factor=1.0, **kwargs)

Create a new LineMarker.

A LineMarker is an Element, where the front surface is a Line LineMarkers are used as line and text annotations in the tracing geometry

Parameters:

  • r (float) – radius of the line

  • desc (str) – text to display

  • angle (float) – angle of the line in xy-plane

  • pos (list | ndarray) – position of marker

  • text_factor (float) – text scaling factor

  • line_factor (float) – marker scaling factor

  • kwargs – additional keyword args for class Element and BaseClass

6.5.13. tracer.geometry.volume.sphere_volume

class optrace.tracer.geometry.volume.sphere_volume.SphereVolume(R, pos, color=None, opacity=0.3, **kwargs)

Create a sphere volume.

Parameters:

  • R (float) – sphere radius

  • pos (list | ndarray) – position of sphere center

  • color (tuple[float]) – sRGB color tuple, optional

  • opacity (float) – plotting opacity, value range 0.0 - 1.0

  • kwargs – additional keyword args for class Volume, Element and BaseClass

6.5.14. tracer.geometry.volume.box_volume

class optrace.tracer.geometry.volume.box_volume.BoxVolume(dim, length, pos, color=None, opacity=0.3, **kwargs)

Create a box volume.

Parameters:

  • dim (list | ndarray) – side lengths of the front surface, see class RectangularSurface

  • length (float) – length of the box in z-direction

  • pos (list | ndarray) – position of front surface center

  • color (tuple[float]) – sRGB color tuple, optional

  • opacity (float) – plotting opacity, value range 0.0 - 1.0

  • kwargs – additional keyword args for class Volume, Element and BaseClass

6.5.15. tracer.geometry.volume.cylinder_volume

class optrace.tracer.geometry.volume.cylinder_volume.CylinderVolume(r, length, pos, color=None, opacity=0.3, **kwargs)

Create a cylinder volume.

Parameters:

  • r (float) – radius of the cylinder

  • length (float) – length of the cylinder

  • pos (list | ndarray) – position of front disk center

  • opacity (float) – plotting opacity, value range 0.0 - 1.0

  • color (tuple[float]) – sRGB color tuple (optional)

  • kwargs – additional keyword args for class Volume, Element and BaseClass

6.5.16. tracer.geometry.volume.volume

class optrace.tracer.geometry.volume.volume.Volume(front, back, pos, d1, d2, color=None, opacity=0.3, **kwargs)

Create a volume object with two surfaces and thickness. A volume object is an Element that displays some 3D object and does not interact with rays.

Parameters:

  • front – front surface

  • back – back surface

  • pos – position

  • d1 – thickness between front and position

  • d2 – thickness between position and back

  • color (tuple[float]) – sRGB color tuple, optional

  • opacity (float) – plotting opacity, value range 0.0 - 1.0

  • kwargs – additional keyword args for class Element and BaseClass

abbr: str = 'V'

abbreviation for objects of this class