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`.

property format

[Deprecated]

Notes

Deprecated since version 3.11:

format_data(value)

Return the context-independent string representation of a single value.

This is used internally, e.g. for constructing offset and scientific-notation strings. It always formats with pos=None and should return a context-independent representation rather than a concise tick label.

The output may contain mathtext or LaTeX markup.

format_data_short(value)

Return a short string representation of value for the mouseover tooltip (the coordinate display in the interactive figure window).

This should return concise, plain text (no mathtext / LaTeX). The precision is typically adapted to the current axis resolution so that neighbouring pixels produce distinguishable labels.

Defaults to .Formatter.format_data; subclasses should override this to provide a plain-text representation that is independent of the current tick locations.

Note: The mouseover text can be customized by setting the Axes.fmt_xdata and Axes.fmt_ydata attributes.

format_ticks(values)

Return the tick label strings for all values.

This is the public API for generating tick labels. It calls set_locs to configure context-dependent formatting state before delegating to __call__ for each individual value.

The output may contain mathtext or LaTeX markup.

Use this method (rather than __call__) whenever formatting a complete set of tick values, so that formatters which need to see all tick locations (e.g. to determine precision, offsets, or which date components to display) can work correctly.

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.

property locs

[Deprecated]

Notes

Deprecated since version 3.11:

property orderOfMagnitude

[Deprecated]

Notes

Deprecated since version 3.11:

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.