visualization.analysis.surface_sag

SurgaceSagViewer

This module provides a viewer for visualizing the sag of an optical surface. It generates a 2D sag map and 1D sag profiles along user-specified cross-sections.

Manuel Fragata Mendes, june 2025

Classes

CustomScalarFormatter([useOffset, ...])	Custom formatter to handle both small and large numbers automatically.
SurfaceSagViewer(optic)	A viewer for visualizing the sag of an optical surface.

class CustomScalarFormatter(useOffset=None, useMathText=None, useLocale=None, *, usetex=None)

Custom formatter to handle both small and large numbers automatically.

axis = None

create_dummy_axis(**kwargs)

static fix_minus(s)

Some classes may want to replace a hyphen for minus with the proper Unicode symbol (U+2212) for typographical correctness. This is a helper method to perform such a replacement when it is enabled via :rc:`axes.unicode_minus`.

format_data(value)

Return the full string representation of the value with the position unspecified.

format_data_short(value)

Return a short string version of the tick value.

Defaults to the position-independent long value.

format_ticks(values)

Return the tick labels for all the ticks at once.

get_offset()

Return scientific notation, plus offset.

get_useLocale()

Return whether locale settings are used for formatting.

See also

ScalarFormatter.set_useLocale

get_useMathText()

Return whether to use fancy math formatting.

See also

ScalarFormatter.set_useMathText

get_useOffset()

Return whether automatic mode for offset notation is active.

This returns True if set_useOffset(True); it returns False if an explicit offset was set, e.g. set_useOffset(1000).

See also

ScalarFormatter.set_useOffset

get_usetex()

Return whether TeX’s math mode is enabled for rendering.

locs = []

set_axis(axis)

set_locs(locs)

Set the locations of the ticks.

This method is called before computing the tick labels because some formatters need to know all tick locations to do so.

set_powerlimits(lims)

Set size thresholds for scientific notation.

Parameters:

lims ((int, int)) –

A tuple (min_exp, max_exp) containing the powers of 10 that determine the switchover threshold. For a number representable as \(a \times 10^\mathrm{exp}\) with \(1 <= |a| < 10\), scientific notation will be used if exp <= min_exp or exp >= max_exp.

The default limits are controlled by :rc:`axes.formatter.limits`.

In particular numbers with exp equal to the thresholds are written in scientific notation.

Typically, min_exp will be negative and max_exp will be positive.

For example, formatter.set_powerlimits((-3, 4)) will provide the following formatting: \(1 \times 10^{-3}, 9.9 \times 10^{-3}, 0.01,\) \(9999, 1 \times 10^4\).

See also

ScalarFormatter.set_scientific

set_scientific(b)

Turn scientific notation on or off.

See also

ScalarFormatter.set_powerlimits

set_useLocale(val)

Set whether to use locale settings for decimal sign and positive sign.

Parameters:

val (bool or None) – None resets to :rc:`axes.formatter.use_locale`.

set_useMathText(val)

Set whether to use fancy math formatting.

If active, scientific notation is formatted as \(1.2 \times 10^3\).

Parameters:

val (bool or None) – None resets to :rc:`axes.formatter.use_mathtext`.

set_useOffset(val)

Set whether to use offset notation.

When formatting a set numbers whose value is large compared to their range, the formatter can separate an additive constant. This can shorten the formatted numbers so that they are less likely to overlap when drawn on an axis.

Parameters:

val (bool or float) –

• If False, do not use offset notation.

• If True (=automatic mode), use offset notation if it can make the residual numbers significantly shorter. The exact behavior is controlled by :rc:`axes.formatter.offset_threshold`.

• If a number, force an offset of the given value.

Examples

With active offset notation, the values

100_000, 100_002, 100_004, 100_006, 100_008

will be formatted as 0, 2, 4, 6, 8 plus an offset +1e5, which is written to the edge of the axis.

set_usetex(val)

Set whether to use TeX’s math mode for rendering numbers in the formatter.

property useLocale

Return whether locale settings are used for formatting.

See also

ScalarFormatter.set_useLocale

property useMathText

Return whether to use fancy math formatting.

See also

ScalarFormatter.set_useMathText

property useOffset

Return whether automatic mode for offset notation is active.

This returns True if set_useOffset(True); it returns False if an explicit offset was set, e.g. set_useOffset(1000).

See also

ScalarFormatter.set_useOffset

property usetex

Return whether TeX’s math mode is enabled for rendering.

class SurfaceSagViewer(optic)

A viewer for visualizing the sag of an optical surface.

view(surface_index: int, y_cross_section: float = 0.0, x_cross_section: float = 0.0, fig_to_plot_on: Figure = None, max_extent: float = None, num_points_grid: int = 50, buffer_factor: float = 1.1)

Analyzes and visualizes the sag of a given lens surface.

This method generates a 2D sag map and 1D sag profiles along user-specified x and y cross-sections.

Parameters:

• surface_index (int) – The index of the surface to analyze.

• y_cross_section (float, optional) – The y-coordinate for the horizontal (X-axis) profile. Defaults to 0.0.

• x_cross_section (float, optional) – The x-coordinate for the vertical (Y-axis) profile. Defaults to 0.0.

• fig_to_plot_on (plt.Figure, optional) – Figure to plot on. If None, creates a new figure.

• max_extent (float, optional) – Maximum extent of the plot in mm. If None, uses the surface’s aperture with a buffer. This controls the viewing area size.

• num_points_grid (int, optional) – Number of points in each dimension of the grid. Defaults to 50.

• buffer_factor (float, optional) – Factor to multiply the aperture by to add a buffer around the plot. Defaults to 1.1.