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 its center in the xy-plane :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