reference

`labkit.app.interaction.scaleCalibration`

Convert a known image distance into pixels per unit.

Syntax

cal = labkit.app.interaction.scaleCalibration(referencePixels, ...
referenceLength, unitName)
cal = labkit.app.interaction.scaleCalibration(..., opts)

Inputs

referencePixels: Measured reference distance in image pixels. Empty, nonnumeric, nonfinite, or nonpositive values are treated as missing.
referenceLength: Physical reference distance expressed in unitName. Missing, nonfinite, or negative values become 0.
unitName: Unit label. With default options, legal values are "m", "cm", "mm", "um", and "nm". An unsupported value uses defaultUnit.
opts: Optional scalar struct described below. Default: struct().

Options

units: Allowed unit labels. Default: {'m','cm','mm','um','nm'}.
defaultUnit: Fallback unit. Default: the first entry in units.
referenceLine: N-by-2 numeric reference points stored with the result. When it contains exactly two rows and referencePixels is missing, their Euclidean distance supplies referencePixels. Default: zeros(0,2).

Outputs

cal: Scalar struct with the fields described below.

Calibration Fields

referencePixels: Positive measured pixel distance, or NaN when missing.
referenceLength: Nonnegative physical reference distance.
unit: Normalized unit label as a character vector.
pixelsPerUnit: referencePixels/referenceLength, or 0 when calibration is incomplete.
isCalibrated: true when pixelsPerUnit is positive.
referenceLine: Normalized N-by-2 numeric reference coordinates.

Description

This function builds a serializable calibration value; it does not read an image or draw a scale bar. Repeating the call with identical inputs returns identical numeric fields. Divide a pixel distance by pixelsPerUnit to obtain a distance in cal.unit.

Failure Behavior

Missing or invalid measurement values are normalized into an uncalibrated result instead of throwing. opts must be a scalar structure whose units can be converted to text and whose referenceLine can be converted to an N-by-2 numeric array; incompatible MATLAB values propagate conversion errors.

Example

cal = labkit.app.interaction.scaleCalibration(80, 20, "mm");
physicalLength = 40 / cal.pixelsPerUnit;
assert(cal.isCalibrated && physicalLength == 10)

labkit.app.interaction.scaleBarGeometry — Compute serializable image scale-bar overlay geometry.
labkit.app.interaction.anchorPath — Declare an editable open or closed path on one plot axis.
labkit.app.interaction.interpolateAnchorPath — Build a visible path through image anchor points.
labkit.app.interaction.interval — Declare an editable one-dimensional plot interval.
labkit.app.interaction.pairedAnchors — Declare matching editable points across plot axes.
labkit.app.interaction.pointSlots — Declare a fixed set of editable labeled point positions.
labkit.app.interaction.rectangle — Declare an editable rectangular plot region.
labkit.app.interaction.regionSelection — Declare a transient click-or-drag region gesture.

Source

This page is generated from the MATLAB help text in +labkit/+app/+interaction/scaleCalibration.m.

labkit.app.interaction.scaleCalibration