Plotting

Core

class diffinytrace.plotting.core.Plotable(fill_color: str = 'white', outline_color: str = 'black', is_volume: bool = False)

Bases: object

Base class for objects that can be visualized in the optical system.

This class provides a common interface for objects that support 2D/3D plotting, color scale configuration, and hierarchical visualization. Subclasses should implement methods for generating plot points and color scales as needed.

fill_color

Color used to fill the object in plots.

Type:

str

outline_color

Color used for the object’s outline in plots.

Type:

str

is_volume

If True, the object is treated as a volumetric entity.

Type:

bool

get_plotly_color_scale() → List[List[float | str]]

Returns a color scale for Plotly, based on the fill and outline colors.

get_plotable_childs() → List

Returns a list of all plotable child objects of this object. Each child is represented as a list containing the child object and its name.

get_plot_points_2D(resolution: int) → List

Returns a list of 2D plot points for the object.

Parameters:

resolution (int) – The resolution for the plot points.

Returns:

A list of 2D plot points.

Return type:

list

get_plot_points_3D(resolution: int) → List

Returns a list of 3D plot points for the object.

Parameters:

resolution (int) – The resolution for the plot points.

Returns:

A list of 3D plot points.

Return type:

list

Quantity2D

diffinytrace.plotting.quantity2D.plot(val: Callable | ndarray, title: str = '', x_range: Tuple[float, float] | None = None, y_range: Tuple[float, float] | None = None, cmap: str = 'jet', subtitle: str = '', title_fontsize: int = 14, suptitle_fontsize: int = 12, interpolation: str = 'none', xlabel: str = 'x [mm]', ylabel: str = 'y [mm]', colorbar: bool = True, norm=None, show: bool = True, vmin: float | None = None, vmax: float | None = None, resolution: int = 501, **kwargs)

Plot a 2D quantity using matplotlib. This function handles both callable quantities and numpy arrays. If a callable is provided, it should accept a 2D array of coordinates and return a 2D array of values. The function will create a 2D plot with the specified parameters. If a numpy array is provided, it will be plotted directly.

Parameters:

• val (callable or np.ndarray) – The quantity to plot. If callable, it should accept a 2D array of coordinates.

• title (str) – Title of the plot.

• x_range (tuple) – Range of x-axis.

• y_range (tuple) – Range of y-axis.

• cmap (str) – Colormap to use.

• subtitle (str) – Subtitle of the plot.

• title_fontsize (int) – Font size of the title.

• suptitle_fontsize (int) – Font size of the subtitle.

• interpolation (str) – Interpolation method.

• xlabel (str) – Label for x-axis.

• ylabel (str) – Label for y-axis.

• colorbar (bool) – Whether to show colorbar.

• show (bool) – Whether to show the plot.

• vmin (float) – Minimum value for color normalization.

• vmax (float) – Maximum value for color normalization.

• resolution (int) – Resolution of the plot.

• **kwargs – Additional arguments for imshow.

Returns:

None

System2D

diffinytrace.plotting.system2D.annotate_position_simple(nz, ny, name)

Annotate the position of a point in 2D space using its coordinates.

Parameters:

• nz (torch.Tensor) – z-coordinates of the point.

• ny (torch.Tensor) – y-coordinates of the point.

• name (str) – Text label to annotate at the position.

Returns:

None

diffinytrace.plotting.system2D.annotate_position(position, offset, name, color='black', **kwargs)

Annotate a point in 2D space with an arrow and label.

Parameters:

• position (tuple) – (z, y) coordinates of the point.

• offset (tuple) – Offset for the annotation text.

• name (str) – Text label to annotate.

• color (str) – Color of the annotation and arrow.

Returns:

None

diffinytrace.plotting.system2D.annotated_arrow(start, end, offset, name, arrowstyle, color='black', **kwargs)

Draw and annotate an arrow between two points in 2D space.

Parameters:

• start (tuple) – Start position (z, y) of the arrow.

• end (tuple) – End position (z, y) of the arrow.

• offset (tuple) – Offset for the annotation text.

• name (str) – Text label to annotate.

• arrowstyle (str) – Matplotlib arrow style string.

• color (str) – Color of the arrow and annotation.

Returns:

None

diffinytrace.plotting.system2D.layout()

Set up the layout for the 2D plot, including margins, aspect ratio, and axis labels.

Returns:

None

diffinytrace.plotting.system2D.ray_paths(rays, ray_color='#85549c', ray_linewidth=1.25)

Plot ray paths projected onto the y-z plane.

Parameters:

• rays (list[torch.Tensor]) – List of ray paths to plot.

• ray_color (str) – Color of the rays.

• ray_linewidth (float) – Line width of the rays.

Returns:

None

diffinytrace.plotting.system2D.plot(element=None, rays=None, resolution=200, annotate=False, ray_color='#85549c', ray_linewidth=1.25, fill_color=None, outline_color=None, linewidth=None, show=True)

Plot a 2D surface and optionally ray paths.

Parameters:

• element – The element to plot (must implement Plotable interface).

• rays (list[torch.Tensor]) – List of ray paths to plot.

• resolution (int) – Resolution for the surface plot.

• annotate (bool) – Whether to annotate the surface.

• ray_color (str) – Color of the rays.

• ray_linewidth (float) – Line width of the rays.

• fill_color (str) – Fill color for the surface.

• outline_color (str) – Outline color for the surface.

• linewidth (float) – Line width for the surface.

• show (bool) – Whether to display the plot immediately.

Returns:

None

System3D

diffinytrace.plotting.system3D.ray_paths_one_bin(rays, ray_color, ray_linewidth)

Generate a Plotly 3D line plot for a group of rays with the same number of segments.

Parameters:

• rays (list[torch.Tensor]) – List of ray paths, each as a tensor.

• ray_color (str) – Color for the ray lines.

• ray_linewidth (float) – Line width for the ray lines.

Returns:

Plotly figure containing the ray paths.

Return type:

plotly.graph_objs.Figure

diffinytrace.plotting.system3D.ray_paths(rays, ray_color='#9673A6', ray_linewidth=3)

Generate Plotly line objects for multiple ray paths, grouped by path length.

Parameters:

• rays (list[torch.Tensor]) – List of rays to plot.

• ray_color (str) – Color of the rays.

• ray_linewidth (float) – Line width of the rays.

Returns:

List of Plotly line objects for each ray group.

Return type:

list

diffinytrace.plotting.system3D.surface(transformation, surface, name, aperture_radius, resolution, colorscale, is_square=False)

Generate a Plotly surface plot for an optical element.

Parameters:

• transformation – Transformation object for the optical element.

• surface – Surface object to plot.

• name (str) – Name of the surface.

• aperture_radius (float) – Radius of the aperture.

• resolution (int) – Resolution for the surface plot.

• colorscale (list) – Color scale for the surface plot.

• is_square (bool) – Whether the aperture is square or circular.

Returns:

List of Plotly surface objects.

Return type:

list

diffinytrace.plotting.system3D.get_optical_system_layout(show_grid, xlabel='x [mm]', ylabel='y [mm]', zlabel='z [mm]', xticks=None, yticks=None, zticks=None, axislabel_font_size=10, tick_font_size=10)

Create a Plotly layout for 3D visualization of the optical system.

Parameters:

• show_grid (bool) – Whether to show the grid.

• xlabel (str) – Label for the x-axis.

• ylabel (str) – Label for the y-axis.

• zlabel (str) – Label for the z-axis.

• xticks (list[float], optional) – Custom x-ticks.

• yticks (list[float], optional) – Custom y-ticks.

• zticks (list[float], optional) – Custom z-ticks.

• axislabel_font_size (int) – Font size for axis labels.

• tick_font_size (int) – Font size for tick labels.

Returns:

Layout object for the plot.

Return type:

plotly.graph_objs.Layout

diffinytrace.plotting.system3D.plot(element=None, rays=None, resolution=32, show_grid=True, xlabel='x [mm]', ylabel='y [mm]', zlabel='z [mm]', xticks=None, yticks=None, zticks=None, axislabel_font_size=10, tick_font_size=10, ray_color='#9673A6', ray_linewidth=3.0, show=True, html_file_name=None)

Visualize the optical system and ray paths in 3D using Plotly.

Parameters:

• element – The optical system element to plot (must implement Plotable interface).

• rays (list[torch.Tensor] or dict) – List of rays or dict containing ray paths.

• resolution (int) – Resolution for the surface plot.

• show_grid (bool) – Whether to show the grid.

• xlabel (str) – Label for the x-axis.

• ylabel (str) – Label for the y-axis.

• zlabel (str) – Label for the z-axis.

• xticks (list[float], optional) – Custom x-ticks.

• yticks (list[float], optional) – Custom y-ticks.

• zticks (list[float], optional) – Custom z-ticks.

• axislabel_font_size (int) – Font size for axis labels.

• tick_font_size (int) – Font size for tick labels.

• ray_color (str) – Color of the rays.

• ray_linewidth (float) – Line width of the rays.

• show (bool) – Whether to display the plot immediately.

• html_file_name (str, optional) – If provided, saves the plot as an HTML file.

Returns:

The Plotly figure object if show is False, otherwise None.

Return type:

plotly.graph_objs.Figure or None

Wavelength

class diffinytrace.plotting.wavelength.PlotableWavelength(bounds: Tuple[float, float], ylabel: str)

Bases: object

Represents a wavelength range and y-axis label for plotting spectral data.

bounds

Lower and upper bounds for the wavelength range.

Type:

tuple

ylabel

Label for the y-axis in plots.

Type:

str

diffinytrace.plotting.wavelength.add_colour_bar(fig, ax, wl)

Add a color strip below the plot to represent the wavelength spectrum.

Parameters:

• fig (matplotlib.figure.Figure) – The figure object.

• ax (matplotlib.axes.Axes) – The main axis of the plot.

• wl (array-like) – Wavelengths in µm.

diffinytrace.plotting.wavelength.plot(wl, vals=None, title='', xlabel='Wavelength [µm]', ylabel='y', labels=None, colour_bar=True, linewidth=2, legend=True, resolution=500, show=True)

Plot a spectrum with a color strip below it.

Parameters:

• wl (array-like) – Wavelengths in nm or µm.

• vals (array-like) – Values of the spectrum at the given wavelengths.

• title (str) – Title of the plot.

• xlabel (str) – Label for the x-axis.

• ylabel (str) – Label for the y-axis.

• labels (list) – Labels for the different curves.

• colour_bar (bool) – Whether to show a color bar.

• linewidth (int) – Line width of the plot.

• legend (bool) – Whether to show a legend.

• resolution (int) – Resolution of the plot.

• show (bool) – Whether to show the plot.

Returns:

None

Module Contents

class diffinytrace.plotting.Plotable(fill_color: str = 'white', outline_color: str = 'black', is_volume: bool = False)

Bases: object

Base class for objects that can be visualized in the optical system.

This class provides a common interface for objects that support 2D/3D plotting, color scale configuration, and hierarchical visualization. Subclasses should implement methods for generating plot points and color scales as needed.

fill_color

Color used to fill the object in plots.

Type:

str

outline_color

Color used for the object’s outline in plots.

Type:

str

is_volume

If True, the object is treated as a volumetric entity.

Type:

bool

get_plotly_color_scale() → List[List[float | str]]

Returns a color scale for Plotly, based on the fill and outline colors.

get_plotable_childs() → List

Returns a list of all plotable child objects of this object. Each child is represented as a list containing the child object and its name.

get_plot_points_2D(resolution: int) → List

Returns a list of 2D plot points for the object.

Parameters:

resolution (int) – The resolution for the plot points.

Returns:

A list of 2D plot points.

Return type:

list

get_plot_points_3D(resolution: int) → List

Returns a list of 3D plot points for the object.

Parameters:

resolution (int) – The resolution for the plot points.

Returns:

A list of 3D plot points.

Return type:

list