spacr.qt.widgets.image_ruler

A shared line ruler that measures image coordinates without changing pixels.

Classes

ImageRuler

Keep a line in image pixels and paint it through the host's transform.

Module Contents

class spacr.qt.widgets.image_ruler.ImageRuler(parent=None)

Bases: PySide6.QtCore.QObject

Keep a line in image pixels and paint it through the host’s transform.

Parameters:

parent – owning image canvas or view; defaults to None.

Hosts pass their widget-to-image mapping to handle() and inverse mapping to paint(). Zoom and pan never change the measured length. Pixel units are always shown. Physical units require validated calibration, either explicit through set_spacing() or stated by the image file’s own header through calibrate_from_file(); camera magnification is never guessed. Right-click clears while the tool is active.

Start with no line, no calibration and drawing disabled.

calibrate_from_file(path, shape=None)

Take the pixel spacing the shown image’s own file header states.

Only a size the file states counts (OME PhysicalSizeX/Y, an ImageJ micron calibration or centimetre resolution tags, read by spacr.point_spread.image_optics_metadata()); a magnification in the file name, an objective table or a default never calibrates the ruler. Calibration is cleared first, so a file that states nothing leaves the ruler in pixels.

Parameters:

• path – the image file being shown; None or ‘’ only clears.

• shape – the displayed array’s shape; defaults to None, which skips the check. When given, the header’s (Y, X) must equal its first two or last two dimensions, so a resampled or cropped display is never measured with the file’s spacing.

Returns:

the (x, y) spacing in µm now set, or None when the ruler stays uncalibrated.

clear()

Remove the line without changing tool activation or calibration.

Returns:

None; emits changed even when no line was present.

handle(event, to_image)

Consume ruler mouse gestures; return False for navigation gestures.

Parameters:

• event – a mouse press, move or release from the host canvas.

• to_image – widget QPointF -> image (x, y), or None off-image.

Returns:

True for consumed ruler gestures; False when the host should handle the event. Coordinates outside the image do not move endpoints.

label()

Return pixel length and, only when calibrated, physical length.

Returns:

text with lengths to two decimal places; empty before a line exists.

length(physical=False)

Return the line length, or None before a line exists.

Parameters:

physical – False (default) uses image pixels; True uses calibrated per-axis spacing, including different horizontal and vertical values.

Returns:

Euclidean length as a float in pixels or unit; None when no line exists or physical length is requested without calibration.

paint(painter, to_widget)

Draw endpoints, line and readout in widget coordinates.

Parameters:

• painter – an active painter for the host canvas/viewport.

• to_widget – image (x, y) -> widget QPointF or QPoint, or None.

Returns:

None; draws nothing when a line or either mapped endpoint is missing.

set_active(active)

Enable drawing; disabling preserves the finished line.

Parameters:

active – whether unmodified left drags measure instead of edit.

Returns:

None; emits changed after updating activation.

set_spacing(x=None, y=None, unit='µm')

Set physical distance per image pixel, or clear calibration.

Parameters:

• x – positive finite distance per horizontal image pixel in unit; defaults to None, which clears calibration and ignores y.

• y – positive finite distance per vertical image pixel in unit; defaults to None, which uses x for both axes.

• unit – physical unit label; defaults to 'µm'. The caller supplies spacing in this unit; this method does not convert units.

Raises:

ValueError – when spacing is nonpositive or nonfinite.

Returns:

None; emits changed after updating calibration.