4.12. Plotting Functions

4.12.1. Namespace

Multiple plot and visualization features are included in the optrace.plots submodule.

import optrace.plots as otp

4.12.2. Parameters

Most methods include a title argument for a user defined plot title.

otp.any_plotting_function(..., title="Name of plot")

Inside the figures, legends and labels are generated from object descriptions. Just make sure to create all your objects with expressive desc=".." or long_desc="..." parameters.

obj = Object(..., desc="Abc378")
obj2 = Object(..., long_desc="Some long description")

otp.any_plotting_function([obj, obj2], ...)

Plotting uses matplotlib under the hood, so advanced settings, including figure size and dpi, can be set globally with the matplotlib.rcParams dictionary:

import matplotlib
matplotlib.rcParams["figure.figsize"] = (5, 5)
matplotlib.rcParams["figure.dpi"] = 100

4.12.3. Block/Pause Plots

By default, the plot windows are shown and the rest of the program continues executing. Call optrace.plots.block to pause and enable interaction with the plots.

import optrace.plots as otp

# do the plotting
...

# make blocking
otp.block()

4.12.4. Saving Figures

Specifying the path parameter inhibits the display of the window and saves the plot at the provided location instead. The file type is determined automatically from the filename. Note that files are overwritten and not stored if the path is invalid.

otp.any_plotting_function(..., path="./results/image.jpeg")

Additional saving parameters are specified with the sargs dictionary, whose keys and values are passed to the internally called matplotlib.pyplot.savefig function.

otp.any_plotting_function(..., path="./results/image.jpeg", sargs=dict(dpi=150, pad_inches=0, transparent=True))

4.12.5. Changing Fonts and Other Plot Settings

By default, serif-fonts are used for publication-like plots. As mentioned in Section 4.12.2, global matplotlib settings are changed through matplotlib.rcParams . To change the fonts to be sans serif, do:

import optrace as ot
import optrace.plots as otp
import matplotlib

...

# needs to be set after importing optrace.plots
matplotlib.rcParams['mathtext.fontset'] = 'dejavusans'
matplotlib.rcParams['font.family'] = 'sans serif'

Depending on the installed fonts on your system, you need to change 'dejavusans' to a different sans-serif font.

4.12.6. Plotting Surfaces

The function surface_profile_plot plots one or multiple surface profiles. It takes a Surface or a Surface list as argument, combined with some additional display options. The profiles are created in x-direction through the center y-coordinate. Rotate the objects beforehand to slice through a different axis. By default, the surface profiles are plotted with absolute coordinates. Provide remove_offset=True to display them relative to their center.

In the following example, both front and back surface of the cornea from the Arizona eye model are plotted:

import optrace as ot
import optrace.plots as otp

G = ot.presets.geometry.arizona_eye()
L0 = G.lenses[0]

otp.surface_profile_plot([L0.front, L0.back], remove_offset=True)

Provide values for x0 and xe to select only a section of the profile.

otp.surface_profile_plot([L0.front, L0.back], remove_offset=True, x0=-0.5, xe=1.2, title="Cornea Surfaces")

This results in the following plot:

../_images/surface_profile_plot.svg

Fig. 4.61 Surface profile plot for the two cornea surfaces of the arizona eye model.

4.12.7. Spectrum Plotting

Spectrum, LightSpectrum or TransmissionSpectrum are plotted with the function spectrum_plot. It takes a single object or a list of objects as parameter.

otp.spectrum_plot(ot.presets.light_spectrum.standard_natural)

The user can provide a user-defined title and toggle label or legend visibility with legend_off, labels_off.

ot.plots.spectrum_plot(ot.presets.light_spectrum.standard_natural, labels_off=False,
                       title="CIE Standard Illuminants", legend_off=False)

The following figures demonstrate two examples for spectral plots.

../_images/LED_illuminants.svg

Fig. 4.62 CIE standard illuminants LED series.
../_images/example_spectrum_histogram.svg

Fig. 4.63 A rendered histogram spectrum.

4.12.8. Plotting Images

Image

The image_plot plotting function takes an RGBImage or ScalarImage as first parameter. A RenderImage needs to be converted to a specific image type first.

img = ot.presets.image.hong_kong([2, 2])
otp.image_plot(img)

The additional parameter log is used to scale the image values logarithmically. Provide flip=True to rotate the image by 180 degrees around the optical axis. This option is most commonly used for flipping images from a system with negative magnification.

otp.image_plot(img, title="Title 123", log=True, flip=True)

Image Profile

For plotting an image profile, the analogous function image_profile_plot is applied. It requires an additional profile parameter x or y that specifies the profile coordinate.

otp.image_profile_plot(img, x=0)

Supporting the same parameters as for image_plot, the following call is valid:

otp.image_profile_plot(img, y=0.2, title="Title 123", log=True, flip=True)
Table 4.19 Example image plot and image profile plot from the Prism example.
../_images/color_dispersive2.svg
../_images/color_dispersive1_cut.svg

4.12.9. Chromaticity Plots

Usage

Chromaticity plots allow for a representation of image or spectrum colors inside a chromaticity diagram. Both the chromaticities_cie_1931 and chromaticities_cie_1976 function are available.

It supports the plotting of RenderImage, RGBImage and LightSpectrum types. Example code for a RenderImage is:

dimg = RT.detector_image()
otp.chromaticities_cie_1931(dimg)

Passing an RGBImage is possible with:

img = ot.presets.image.color_checker([3, 2])
otp.chromaticities_cie_1931(img)

A LightSpectrum can also be provided:

spec = ot.presets.light_spectrum.led_b1
otp.chromaticities_cie_1976(spec)

Or a list of multiple spectra:

specs = [ot.presets.light_spectrum.led_b3, ot.presets.light_spectrum.d65]
otp.chromaticities_cie_1976(specs)

norm specifies the brightness normalization, explained in Table 4.21 below:

otp.chromaticities_cie_1976(ot.presets.light_spectrum.standard, title="Standard Illuminants", norm="Largest")
Table 4.20 Examples of CIE 1931 and 1976 chromaticity diagrams.
../_images/chroma_1931.svg
../_images/chroma_1976.svg

Norms

Chromaticity norms define the brightness normalization method for the colored gamut background inside the plot.

Sum

Normalize the sRGB values so the channel sum for each color equals one. Produces a diagram with smooth color changes and approximately equal brightness.

Euclidean

Root-mean-square value of linear sRGB channels. A good compromise between “Largest” and “Sum”, having more saturated colors than “Sum”, but also smoother color changes compared to “Largest”. The default option.

Largest

Maximum possible brightness for each sRGB color. Leads to colors with maximum brightness and saturation.
Table 4.21 Example of “Sum”, “Euclidean” and “Largest” norm (from left to right)
../_images/chroma_sum_norm.svg
../_images/chroma_rms_norm.svg
../_images/chroma_largest_norm.svg

4.12.10. Plotting Refractive Indices

Index Plot

A RefractionIndex or a list of them can be plotted with the function refraction_index_plot from optrace.plots. The example below displays all glass presets in one figure.

import optrace.plots as otp

otp.refraction_index_plot(ot.presets.refraction_index.glasses)

Enable or disable the legend and labels with legend_off and labels_off.

otp.refraction_index_plot(ot.presets.refraction_index.glasses, title="Test abc",
                          legend_off=False, labels_off=True)
../_images/glass_presets_n.svg

Fig. 4.64 Example of a Refractive Index Plot.

Abbe Plot

An Abbe plot is generated with abbe_plot.

otp.abbe_plot(ot.presets.refraction_index.glasses)

You can provide user defined spectral lines to calculate the index and V-number at:

otp.abbe_plot(ot.presets.refraction_index.glasses, title="abc", lines=ot.presets.spectral_lines.FeC)
../_images/glass_presets_V.svg

Fig. 4.65 Example of an Abbe Plot.

4.12.11. Focus Search Cost Function Plots

These plots are for debugging the focus search and assessing how pronounced a focus or focus region is. Plotting the cost function and result is done through the focus_search_cost_plot method from optrace.plots. It requires the res, fsdict results from the focus_search function.

from optrace.plots import focus_search_cost_plot

focus_search_cost_plot(res, fsdict)

You can find examples for two cost function plots below.

../_images/focus_rms_spot_size.svg

Fig. 4.66 Focus search for mode “RMS Spot Size” in the Spherical Aberration example.
../_images/focus_image_sharpness.svg

Fig. 4.67 Focus search for mode “Image Sharpness” in the Spherical Aberration example.

When using the TraceGUI, the focus information are also visible inside the Focus-tab of the UI:

Found 3D position: [5.684185e-06mm, 2.022295e-06mm, 15.39223mm]
Search Region: z = [0.9578644mm, 40mm]
Method: Irradiance Maximum
Used 200000 Rays for Autofocus
Ignoring Filters and Apertures

OptimizeResult:
  message: CONVERGENCE: REL_REDUCTION_OF_F_<=_FACTR*EPSMCH
  success: True
   status: 0
      fun: 0.019262979304881897
        x: 15.3922327445026
      nit: 4
      jac: [ 9.024e-03]
     nfev: 102
     njev: 51
 hess_inv: <1x1 LbfgsInvHessProduct with dtype=float64>