batch_crop.cropGeometry.scalePlan

Description

Converts every image calibration to a requested physical unit, determines a common output pixel density, and calculates native crop and common output dimensions. Automatic density is the median converted source density. Large scale differences produce warnings but do not reject the plan.

Inputs

items

Nonempty structure array. Each element must have a valid scaleCalibration accepted by batch_crop.scaleCalibration.isSet, including a positive pixelsPerUnit value and its source unit.

opts

Scalar structure containing the physical crop options below.

Options

physicalWidth

Required positive crop width in scaleUnit.

physicalHeight

Required positive crop height in scaleUnit.

scaleUnit

Unit used for physical dimensions and pixel densities. Legal values are "m", "cm", "mm", "um", and "nm". Default: "um".

targetPixelsPerUnit

Positive common output density in pixels per scaleUnit. Zero, negative, or nonfinite input selects the median source density automatically. Default: 0.

maxUpsamplePercent

Largest accepted upsampling above native density before a warning is recorded. Negative input is treated as zero. Default: 15.

Outputs

plan

Scalar structure with these fields:

Plan Fields

mode

"Physical".

unit

Effective scaleUnit.

targetSource

"Manual" for a positive targetPixelsPerUnit, otherwise "Auto". physicalWidth, physicalHeight - Requested dimensions in unit.

sourcePixelsPerUnit

Converted density for each input item.

targetPixelsPerUnit

Common output density.

resampleFactor

targetPixelsPerUnit ./ sourcePixelsPerUnit. nativeCropWidth, nativeCropHeight - Per-item native crop sizes in pixels, rounded to integers with a minimum of one. outputWidth, outputHeight - Common output size in pixels, rounded to integers with a minimum of one.

warnings

Per-item text. Upsampling beyond maxUpsamplePercent reports "upsample ...x"; resample factors below 0.5 report "downsample ...x".

Errors

labkit_BatchImageCrop_app:ScaleCalibrationMissing

Any item lacks a valid calibration convertible to scaleUnit.

labkit_BatchImageCrop_app:InvalidPhysicalSize

physicalWidth or physicalHeight is missing, nonscalar, nonfinite, or nonpositive.

labkit_BatchImageCrop_app:InvalidScaleUnit

scaleUnit is unsupported.

Example

cal = labkit.app.interaction.scaleCalibration(20, 10, "um");
items = struct("scaleCalibration", cal);
opts = struct("physicalWidth", 5, "physicalHeight", 3, ...
"scaleUnit", "um", "targetPixelsPerUnit", 4);
plan = batch_crop.cropGeometry.scalePlan(items, opts);
assert(plan.outputWidth == 20 && plan.outputHeight == 12)