spacr.picture_settings

Which picture settings apply to which mode, and why the others do not.

THE KEYS ARE THE ANNOTATOR’S OWN, and that is the point of this module rather than a second list. spacr.settings.set_annotate_default_settings already names every one of them; a Cells tab with its own vocabulary for the same picture would be two panels that disagree about what “normalize” means.

WHY A TABLE AND NOT A BRANCH IN THE WIDGET. The greying rule has to hold wherever the settings are read – a panel, a settings CSV, a macro – and a rule that lives only in the widget that greys it is a rule with one entry point unguarded. That is what ml._require_backend says about backends and what the volcano’s adjusted axis needed at the API as well as in its menu.

Functions

applies_to(→ bool)	Whether key means anything in mode.
applies_to_picking(→ bool)	Whether key means anything for the chosen way of picking cells.
available_arrays(→ Tuple[str, ...])	The mask planes this screen's merged arrays actually record.
available_coordinate_columns(→ Tuple[str, ...])	The object-table columns a bounding box could be cut from.
bounding_box_only(→ bool)	Whether the chosen cut can only be a bounding box.
categories(→ Tuple[Tuple[str, Tuple[str, ...]], ...])	(title, keys) for each tab, covering every key in ALL_KEYS.
category_of(→ str)	The tab key is shown on, or "" when it is not offered here.
draw_crop(array, picture)	array drawn as the annotation application would draw it.
drop_retired(→ tuple)	(settings, [note]) with the retired keys taken out.
greyed_in(→ Tuple[str, ...])	The keys a panel must grey for mode, in a stable order.
modes(→ Tuple[Tuple[str, str], ...])	(value, label) for the three modes, default first.
montage_cap_cost(→ str)	Summarize the estimated cost of a montage containing cap objects.
offered_values(→ Tuple[str, ...])	What a chooser for key should list, or () for free text.
to_crop_settings(→ Dict[str, object])	The subset of a picture-settings dict the crop layer understands.
why_not(→ str)	The sentence a greyed control carries, or "" when it applies.

Module Contents

spacr.picture_settings.applies_to(key: str, mode: str) → bool

Whether key means anything in mode.

Parameters:

• key – picture-setting key whose source-mode applicability is tested.

• mode – selected crop-source mode.

A key this module has never heard of applies: it is not this module’s job to grey out a setting it does not know, and a panel that hid the unknown would hide new settings by default.

spacr.picture_settings.applies_to_picking(key: str, picking: str) → bool

Whether key means anything for the chosen way of picking cells.

Parameters:

• key – picture-setting key whose dependency is being checked.

• picking – selected cell-picking strategy.

spacr.picture_settings.available_arrays(source) → Tuple[str, ...]

The mask planes this screen’s merged arrays actually record.

object_array chooses which mask the intensity channels are cut by, and offering it as free text asks the user to remember what their own screen contains – and to spell it the way measure did. Every other chooser in spaCR is built from the data; this one was not.

Parameters:

source – a spacr.crops.CropSource, a CropSourceChoice, or anything with a spec.mask_dims.

Returns:

the plane names, in a stable order. Empty when the screen records none – which is the answer, not a failure: a run whose merged arrays carry no mask planes cannot cut by one.

spacr.picture_settings.available_coordinate_columns(frame) → Tuple[str, ...]

The object-table columns a bounding box could be cut from.

Parameters:

frame – measurement table whose coordinate columns are inspected.

All four corners or none: three of them describe no box, so a chooser that offered them singly would let a user assemble a request that cannot be met.

spacr.picture_settings.bounding_box_only(settings) → bool

Whether the chosen cut can only be a bounding box.

Parameters:

settings – picture settings containing the selected crop source.

Coordinate-only sources have no object outline, so a panel should disable object-shaped crops before the cut rather than silently return a rectangle.

spacr.picture_settings.categories() → Tuple[Tuple[str, Tuple[str, ...]], ...]

(title, keys) for each tab, covering every key in ALL_KEYS.

Keys that CATEGORY_SPEC names but ALL_KEYS does not are dropped – a retired setting must not leave an empty row behind – and keys ALL_KEYS has that the spec does not are gathered onto a trailing UNGROUPED_TITLE tab, which exists only when it has something on it.

spacr.picture_settings.category_of(key: str) → str

The tab key is shown on, or "" when it is not offered here.

Parameters:

key – picture-setting key to locate in the category specification.

spacr.picture_settings.draw_crop(array, picture)

array drawn as the annotation application would draw it.

Parameters:

• array – an (H, W, 3) uint8 crop.

• picture – the annotator-named settings.

Returns:

an array of the same shape, or the input unchanged when nothing was asked for or the pipeline is unavailable.

THE ANNOTATOR’S OWN FUNCTIONS DO THE WORK – normalize_pil, filter_channels_pil, outline_image from spacr.qt.annotate_engine. A second implementation of “normalise a crop” is a second answer to what normalise means. Reusing the annotator’s functions keeps identically configured images visually consistent.

NEVER RAISES. A picture is the last thing this produces and the least important: losing a montage to an outline is the worst trade available.

spacr.picture_settings.drop_retired(picture) → tuple

(settings, [note]) with the retired keys taken out.

Parameters:

picture – saved picture-settings mapping to migrate.

Called wherever a saved picture-settings blob is read. The notes are returned rather than printed, so the caller decides whether this is worth a line – it is worth one the first time and noise every time after.

A RENAMED key is moved rather than dropped: img_size became crop_size on 2026-09-19, and a saved run that chose a size keeps it. The rename is read from spacr.settings.surviving_setting_name(), the resolver the settings files use, and only onto a key this panel offers. The new name wins when a blob carries both.

spacr.picture_settings.greyed_in(mode: str) → Tuple[str, ...]

The keys a panel must grey for mode, in a stable order.

Parameters:

mode – selected crop-source mode.

spacr.picture_settings.modes() → Tuple[Tuple[str, str], ...]

(value, label) for the three modes, default first.

Two of them stream from merged/*.npy and differ only in how they find the object – by its label in a mask plane, or by its row in the measurement database. That difference decides whether the cut can follow an outline, so it is a choice the user makes here rather than something inferred from which other settings happen to be filled.

spacr.picture_settings.montage_cap_cost(cap) → str

Summarize the estimated cost of a montage containing cap objects.

Estimates use the measured page capacities, crop memory, and per-crop timings in MEASURED_PAGE_SIZES, MEASURED_CROP_BYTES, and MEASURED_MS_PER_CROP.

Parameters:

cap – Maximum number of objects in one montage.

Returns:

Estimated page count, memory use, and crop-extraction time, or "" when cap is not a positive integer.

spacr.picture_settings.offered_values(key: str, source=None, frame=None) → Tuple[str, ...]

What a chooser for key should list, or () for free text.

Parameters:

key – picture-setting key whose current choices are requested.

ONE PLACE, so the Cells tab and the annotation app cannot offer different answers for the same screen.

spacr.picture_settings.to_crop_settings(picture) → Dict[str, object]

The subset of a picture-settings dict the crop layer understands.

Parameters:

picture – the annotator-named settings, as spacr.qt.widgets.picture_settings_dialog.PictureSettingsDialog returns them.

Returns:

a mapping in the crop layer’s own vocabulary, carrying only what this mode actually uses and only what is set.

spacr.picture_settings.why_not(key: str, mode: str) → str

The sentence a greyed control carries, or "" when it applies.

Parameters:

• key – picture-setting key whose inapplicability is explained.

• mode – selected crop-source mode.

GREYED, NEVER HIDDEN (INVARIANTS 6). A control that vanishes cannot tell the user why their mode does not offer it.