From 820ae4a80d6b83ff244a9be05efbf3a1f6de3212 Mon Sep 17 00:00:00 2001
From: Guillaume Jacquemet <guillaume.jacquemet@abo.fi>
Date: Tue, 13 Oct 2026 14:50:35 +0000
Subject: [PATCH 1/2] Calibration: unit catalog, unknown is a value, field
 states, _calibration request (SPEC_WRONG_SCIENCE section 2)

- units come from the conformance catalog of the installed labconstrictor-tools (symbols exact, words case-insensitive after trimming, 72/96 dpi unknown, damaged micro sign refused)
- a linked PixelSizeOf field is unset / auto / user (a flag set by the person's edits); an unknown source clears it; the declared default is never a stand-in
- a required linked field that is unset blocks the run with the spec sentence; an Optional one sends null
- anisotropic pixels (tolerance 1e-3) and non-length units are unknown with a warning
- the request carries the per-axis reserved input _calibration (x and y); the run record keeps it
- TIFF files are read by their own tags (OME / ImageJ unit first, resolution tags only when not a default dpi); QuPath's own 72 dpi reading of such a TIFF is not trusted unless the calibration was entered in QuPath
- tests/gui_test_calibration_body.groovy runs CAL-01..20 and CAL-T1..T9 through the form, the request and real worker runs

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y2SN8SuEakTdiWy3F2WUqN
---
 README.md                                     |  13 +-
 .../qupath/LabConstrictorTools.groovy         | 528 ++++++++++++++++--
 tests/calibration_fixtures.py                 |  29 +
 tests/frame_app/frame_lc_tools.py             |  22 +-
 tests/gui_test_calibration_body.groovy        | 327 +++++++++++
 tests/gui_test_parity_pixel_body.groovy       |  32 +-
 tests/run_gui_ci.sh                           |   2 +
 7 files changed, 888 insertions(+), 65 deletions(-)
 create mode 100644 tests/calibration_fixtures.py
 create mode 100644 tests/gui_test_calibration_body.groovy

diff --git a/README.md b/README.md
index 42f423e..fd7feaa 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ Without the jar: open `src/main/resources/org/cellmigrationlab/labconstrictor/qu
 
 ## What it does
 * Pick an app and a tool. Numbers (range, unit), choices, checkboxes, text, files and folders become fields; parameters of a group sit under a heading, advanced ones in a collapsed section, optional ones without a default have a "set" box (unticked = the tool gets nothing), and `enabled_when` greys fields out.
-* **Image inputs**: the image open in QuPath, any image of the open project, or a file. QuPath's image is exported losslessly as TIFF (the whole image, or the part chosen under **Image area**, see below). The pixel size of the chosen image or typed file (its header is read) fills the tool's pixel-size field (micrometres) until you edit the field (then your value is kept); pixels that are not square are said in the status line ("pixel size differs: Y .. µm, X .. µm - the tool takes one value and gets X").
+* **Image inputs**: the image open in QuPath, any image of the open project, or a file. QuPath's image is exported losslessly as TIFF (the whole image, or the part chosen under **Image area**, see below). The pixel size of the chosen image or typed file fills the tool's pixel-size field (see **Pixel size** below).
 * Results open in a window: values, tables (as a table: the first 100 000 rows, then "table 'name' (N rows, first M shown; the full table is in P)", the Napari wording; cells with commas, quotes and line breaks are read as CSV says), images (a preview, the path and an "Open in QuPath" button), alignment matrices, files, messages (also shown under the status line) and points.
 * **Interaction hints** of the manifest: a `choices_from` parameter is a dropdown filled by another tool of the app (a text field when that tool cannot answer), `clear_after_run` parameters are reset after a successful run, a `Collapsed` group is a folded section, and an output with `Replace()` reuses the results window of the tool instead of opening a new one.
 * **Channel selector**: an image input declared with `PickChannel()` gets a Channel chooser (the channel names of the chosen image, or of a file); the tool receives only that channel.
@@ -24,6 +24,15 @@ Without the jar: open `src/main/resources/org/cellmigrationlab/labconstrictor/qu
 * Results are kept in `~/.labconstrictor/results/<time>_<6 hex>_<app>_<tool>` (names made safe), like the command line. The host never deletes a results folder or a run record (retention belongs to the Tools reference code, QuPath issue #14). Every run that reached the tool leaves a record `~/.labconstrictor/runs/<time>_<app>_<tool>/run.json` (none ever deleted by the host, the Tools format plus `"host": "qupath"`), and every log line is also appended to the shared `~/.labconstrictor/logs/labconstrictor.log` (Tools line format, `qupath:` prefix, 1 MB rotation with 5 backups), so `labconstrictor-tools logs` and `support-bundle` see QuPath runs.
 * **Same rules as the other hosts** (the host-parity inventory of labconstrictor-tools): a form shows parameters in the Napari/Fiji order (a group gathered where it first appears; a Collapsed group is folded where it first appears; advanced last); `clear_after_run` resets every type of field; `enabled_when` follows text, number, choice, yes/no and "set" drivers (`""` counts as unset, numbers compare as numbers); a whole-number box holds ±(2^53 - 1) at most, declared limits or not (the largest whole number a double holds exactly, Tools `notebook.MAX_FORM_INTEGER`; a typed number beyond it stops at the limit), a decimal box without declared limits ±1e15; a choice of integers is sent as an integer; a missing input says `'L' is required`; NaN is refused with `'L' must be a finite number`; a folder input must be a folder; a worker that is idle for 10 minutes is closed; a worker ended after Cancel reads `cancelled (worker stopped)`; a worker that died is explained with the Tools sentences (a missing package first, then the exit code); a tool with a parameter type this host does not know is refused alone (`this tool cannot be shown: ...`); two tools with one label are listed as `label (id)` and the apps are sorted by name; `Copy as command` writes Python text the way `repr` does (a newline cannot break the snippet) and says `there is no clipboard to copy to` when there is none; message results show `- ` items as bullets; a result file that is missing, or a result type this version does not know, is said in one sentence.
 
+## Pixel size (calibration)
+A tool parameter linked to an image with `PixelSizeOf` (micrometres per pixel) is a text box with a button "Use the image's calibration". It follows the chosen image, the typed file and the image open in QuPath until you type a value (then your value stays, also when the image changes; press the button, or empty the box, to take the image's calibration again).
+
+* **Unknown is a value.** Only an explicit length unit plus a number is a calibration; the number alone never is. A source without a unit (QuPath's `px`), with a unit that is not a length, with a damaged unit text (U+FFFD) or with pixels that are not square (X and Y differ by more than 0.1 %, relative to the larger) is unknown: the box is emptied (tooltip "not calibrated: 'image' has no pixel size"), a warning goes to the status line, and the value of another image never stays. Within 0.1 % the box takes the mean of X and Y.
+* **Units** come from the unit catalog of the installed labconstrictor-tools (`conformance.json`, loaded with `python -m labconstrictor_tools.conformance --path` of a registered app; this script keeps no list): symbols (`um`, `nm`, the micro sign forms, the Angstrom signs, ...) are matched as exact text, words (`micron`, ` MILLIMETER `, ...) case-insensitively after trimming. When the catalog cannot be loaded every calibration is unknown and the status says so.
+* **Where it comes from.** The image open in QuPath and project images: QuPath's `PixelCalibration` through the catalog. A file input: its own TIFF tags (OME `PhysicalSize` or ImageJ `unit=` first; the resolution tags only for `INCH` or `CENTIMETER` and not when they look like a 72 or 96 dpi default; `NONE` is unknown); other file formats through QuPath's reader. For a TIFF that QuPath itself read (a project image, the open image) and whose calibration was not entered in QuPath, the TIFF rules apply as well, because QuPath's reader turns a 72 dpi tag into 352.8 um per pixel; a calibration entered in QuPath ("Set pixel width/height") is explicit and is kept. A file wins over the open image when the image input is a file.
+* **A run needs a value.** A linked parameter that is not `Optional` and is unset blocks the run: `'pixel_size' needs a value: 'image' has no pixel size. Enter it in um.` (the declared default is never a stand-in). An `Optional[float]` that is unset sends `null`.
+* **The request** carries the number in the manifest parameter and the reserved input `_calibration` (per axis, x and y, in um, with `source` image, file or user and the raw number and unit text); tools never see it, the run record (`run.json`, `inputs`) keeps it. A request with a pixel-size value and no `_calibration` entry is a bug.
+
 ## Large images: the Image area and the size guard
 Every image or labels input that uses the image open in QuPath ("Current image: ...") has an **Image area** chooser beside the image chooser:
 
@@ -91,6 +100,8 @@ The `gui_test_parity_*` bodies need the registered `interactions` app (its Pytho
 
 `BODY=gui_test_parity_results_body.groovy tests/run_gui_test.sh` builds result tables of 150 000, 100 000, 2 001 and a few rows, with quoted commas, doubled quotes and multi-line cells, and checks the rows shown and the sentence (12 checks).
 
+`BODY=gui_test_calibration_body.groovy tests/run_gui_test.sh` runs CAL-01..CAL-20 and CAL-T1..CAL-T9 of `conformance.json` through the form (a file input, project images and the image open in QuPath, one real worker run each for a required and an optional field) and checks the request and the `_calibration` input, not only the field; the images are written by `tests/calibration_fixtures.py` (tifffile) with the Python of the registered `frame` app.
+
 `BODY=gui_test_parity_pixel_body.groovy LC_HOME=<scratch folder named lhome_pixel> tests/run_gui_test.sh` reads the pixel size of files (ImageJ unit, centimetre TIFF unit), keeps a typed value, says non-square pixels, reports an unreadable file (15 checks).
 
 `BODY=gui_test_parity_form_body.groovy LC_HOME=<scratch folder named lhome_form> tests/run_gui_test.sh` registers a synthetic app and checks the form order, ClearAfterRun for every type, EnabledWhen for every driver, number limits (whole numbers up to 2^53 - 1, held and typed), integer choices, required and non-finite inputs (55 checks).
diff --git a/src/main/resources/org/cellmigrationlab/labconstrictor/qupath/LabConstrictorTools.groovy b/src/main/resources/org/cellmigrationlab/labconstrictor/qupath/LabConstrictorTools.groovy
index 9c6ade0..9495d39 100644
--- a/src/main/resources/org/cellmigrationlab/labconstrictor/qupath/LabConstrictorTools.groovy
+++ b/src/main/resources/org/cellmigrationlab/labconstrictor/qupath/LabConstrictorTools.groovy
@@ -7,7 +7,7 @@
  *
  * Use it as the extension jar (Extensions > LabConstrictor tools...) or paste it in the Script Editor and run it.
  *
- * Sections, in file order: logging (LcLog), JSON (LcJson), registry and trust checks (LcRegistry), the worker (LcWorker), the dialog (LcDialog:
+ * Sections, in file order: logging (LcLog), JSON (LcJson), image area (LcArea), calibration (LcUnits, LcCal, LcTiff, LcLink), registry and trust checks (LcRegistry), the worker (LcWorker), the dialog (LcDialog:
  * form, copy as command, request, running, results) and the entry point.
  */
 import com.google.gson.Gson
@@ -35,6 +35,8 @@ import javafx.scene.image.ImageView
 import javafx.util.Duration
 import java.awt.image.BufferedImage
 
+import java.nio.ByteBuffer
+import java.nio.ByteOrder
 import java.nio.file.Files
 import java.util.concurrent.BlockingQueue
 import java.util.concurrent.LinkedBlockingQueue
@@ -287,6 +289,369 @@ class LcArea {
     }
 }
 
+// ---------------------------------------------------------------------------------------------------- calibration (SPEC_WRONG_SCIENCE section 2)
+/** The unit catalog of conformance.json (`wrong_science.calibration`), loaded once; this script keeps no list of units of its own. The file is the one of the installed
+ *  labconstrictor-tools: `python -m labconstrictor_tools.conformance --path`, run with the interpreter of a registered app (or the file named by the environment variable
+ *  LC_CONFORMANCE, which the tests may set). Matching rule (2.1.4): symbols are exact text (case-sensitive, nothing trimmed), words are matched case-insensitively after
+ *  trimming; text in neither list is an unknown unit and gives an unknown calibration. A catalog that cannot be loaded makes every calibration unknown (said once): the
+ *  number alone is never evidence. */
+class LcUnits {
+    static final String CONFORMANCE_ENV = "LC_CONFORMANCE"
+    static final String NOT_SQUARE_TEXT = "pixels are not square"                          // conformance messages.pixels_not_square_warning
+    static final String NOT_A_LENGTH_TEXT = "unit '{unit}' is not a length"                // messages.unit_not_length_warning
+    static final String DAMAGED_TEXT = "unit text '{unit}' is damaged; enter the pixel size"      // messages.unit_damaged_warning
+    static final String CALIBRATION_REQUIRED = "'{param}' needs a value: '{of}' has no pixel size. Enter it in um."      // messages.calibration_required
+    static final String NOT_CALIBRATED_TOOLTIP = "not calibrated: '{of}' has no pixel size"        // messages.calibration_unknown_tooltip
+    static final String NO_CATALOG_TEXT = "the unit catalog of labconstrictor-tools could not be loaded (update the app's labconstrictor-tools); enter the pixel size"
+    static final String DAMAGED_PREFIX = "�"                                           // a micro sign that was damaged on its way here
+    static final Set<String> NO_UNIT = ["", "pixel", "pixels", "px", "dimensionless", "none"] as Set      // text that says "no physical unit": unknown, and not worth a warning
+    static final int PROCESS_SECONDS = 30
+    private static List<Map> apps = []          // registry entries whose interpreter can give the conformance file
+    private static Map data = null              // the parsed conformance file
+    private static Map catalogs = null          // [symbols: text -> um, words: text -> um]
+
+    /** The registered apps whose interpreter may be asked for the conformance file (a call with other apps forgets the loaded catalog only when none was loaded). */
+    static synchronized void useApps(Collection entries) {
+        apps = entries.findAll { it != null } as List<Map>
+    }
+
+    /** Forgets the loaded catalog (tests that change LC_CONFORMANCE or the apps). */
+    static synchronized void reset() { data = null; catalogs = null }
+
+    /** The parsed conformance file, or null (logged once) when no source could give it. */
+    static synchronized Map conformance() {
+        if (data != null) return data
+        def candidates = []
+        def fromEnv = System.getenv(CONFORMANCE_ENV)
+        if (fromEnv) candidates << new File(fromEnv)
+        for (entry in apps) {
+            def path = pathFrom(entry)
+            if (path != null) candidates << new File(path)
+            if (path != null) break         // the first app that answers: every app of one machine ships the same file format
+        }
+        for (file in candidates) {
+            try { data = LcJson.parse(file) as Map; return data }
+            catch (Exception e) { LcLog.warn("conformance file " + file + " could not be read", e) }      // broad on purpose: a damaged file is the same as none
+        }
+        LcLog.once("no-conformance", "no conformance file: " + NO_CATALOG_TEXT)
+        return null
+    }
+
+    /** `python -m labconstrictor_tools.conformance --path` of one app's interpreter, or null. */
+    static String pathFrom(Map entry) {
+        try {
+            def process = new ProcessBuilder([entry.python as String, "-m", "labconstrictor_tools.conformance", "--path"]).redirectErrorStream(false).start()
+            def out = process.inputStream.getText("UTF-8").trim()
+            if (!process.waitFor(PROCESS_SECONDS, TimeUnit.SECONDS)) { process.destroyForcibly(); return null }
+            return process.exitValue() == 0 && out ? out.readLines().last().trim() : null
+        } catch (IOException e) {      // the interpreter cannot be started
+            LcLog.warn("the conformance file could not be asked from " + entry.python, e)
+            return null
+        }
+    }
+
+    /** The calibration section of the conformance file (null without a catalog). */
+    static Map calibrationData() { return conformance()?.wrong_science?.calibration as Map }
+
+    private static synchronized Map catalog() {
+        if (catalogs != null) return catalogs
+        def section = calibrationData()
+        if (section == null) return null
+        def symbols = [:], words = [:]
+        section.length_units.each { name, entry ->
+            double factor = entry.um_per_unit as double
+            entry.symbols.each { symbols[it as String] = factor }
+            entry.words.each { words[it as String] = factor }
+        }
+        catalogs = [symbols: symbols, words: words]
+        return catalogs
+    }
+
+    /** [micrometres per unit, warning] for a unit text. [null, null] is "no unit" (pixel, empty); [null, warning] a unit that is not in the catalog or is damaged. The factor is never guessed. */
+    static List unitFactor(Object unit) {
+        String text = unit == null ? "" : unit.toString()
+        if (text.contains(DAMAGED_PREFIX)) return [null, DAMAGED_TEXT.replace("{unit}", text)]
+        def known = catalog()
+        if (known == null) return [null, NO_CATALOG_TEXT]
+        if (known.symbols.containsKey(text)) return [known.symbols[text], null]       // exact: 'UM', ' um', 'mms' are not symbols
+        String word = text.trim().toLowerCase(Locale.ROOT)
+        if (known.words.containsKey(word)) return [known.words[word], null]
+        return word in NO_UNIT ? [null, null] : [null, NOT_A_LENGTH_TEXT.replace("{unit}", text)]
+    }
+
+    /** 72 or 96 dpi (28.35 or 37.80 per cm), within the tolerance of the conformance file: what software writes when nobody calibrated the image. */
+    static boolean defaultLooking(double resolution, boolean perInch) {
+        def rule = calibrationData()?.default_resolution_dpi
+        if (rule == null) return true           // no rule to compare with: a resolution tag alone is not trusted
+        def defaults = perInch ? rule.values : rule.per_cm
+        return defaults.any { Math.abs(resolution - (it as double)) <= (rule.tolerance_relative as double) * (it as double) }
+    }
+}
+
+/** The pixel size of one source: `y` and `x` are micrometres per pixel, or null when unknown (`warning` may say why); `raw` keeps what the source said, [[scale, unit], [scale, unit]] for y and x. */
+class LcCal {
+    final Double y, x
+    final List raw
+    final String warning
+    LcCal(Double y, Double x, List raw, String warning = null) { this.y = y; this.x = x; this.raw = raw; this.warning = warning }
+
+    static final LcCal UNKNOWN = new LcCal(null, null, [[null, null], [null, null]])
+
+    boolean isKnown() { return y != null && x != null }
+
+    /** Y and X differ by at most the tolerance, relative to the larger. */
+    boolean isSquare() { return known && Math.abs(y - x) <= LcConst.SQUARE_PIXEL_TOLERANCE * Math.max(Math.abs(y), Math.abs(x)) }
+
+    /** What the scalar pixel-size field takes: the mean of X and Y when they agree within the tolerance, else null (unknown). The field is never filled from one axis. */
+    Double getFieldValue() { return known && square ? (y + x) / 2d : null }
+
+    /** The warning to show: why the source is unknown when it is a problem (not just "no calibration"), or that the pixels are not square. */
+    String getNote() { return warning ?: (known && !square ? LcUnits.NOT_SQUARE_TEXT : null) }
+
+    /** Each axis is (scale, unit text): scale times the unit's size in micrometres, or unknown. */
+    static LcCal calibrate(Object yScale, Object yUnit, Object xScale, Object xUnit) {
+        def raw = [[number(yScale), yUnit == null ? null : yUnit.toString()], [number(xScale), xUnit == null ? null : xUnit.toString()]]
+        def sizes = []
+        for (axis in [[yScale, yUnit], [xScale, xUnit]]) {
+            def (factor, warning) = LcUnits.unitFactor(axis[1])
+            def n = number(axis[0])
+            if (factor == null || n == null || n <= 0d) return new LcCal(null, null, raw, warning as String)
+            sizes << n * (factor as double)
+        }
+        return new LcCal(sizes[0] as Double, sizes[1] as Double, raw)
+    }
+
+    static Double number(Object v) {
+        if (v == null) return null
+        try { double d = (v instanceof Number) ? (v as Number).doubleValue() : Double.parseDouble(v.toString().trim()); return Double.isFinite(d) ? d : null }
+        catch (NumberFormatException e) { return null }       // text that is not a number is no number
+    }
+
+    /** The pixel size of an image server: its PixelCalibration through the catalog, except for an unedited local TIFF, which says it through its own tags (see ofTiffFile). */
+    static LcCal ofServer(def server) {
+        def pc = server.pixelCalibration
+        def fromServer = calibrate(pc.pixelHeight, pc.pixelHeightUnit, pc.pixelWidth, pc.pixelWidthUnit)
+        def file = localTiff(server)
+        if (file == null || calibrationEdited(server)) return fromServer      // a calibration the person entered in QuPath is explicit: kept
+        try { return ofTiffFile(file) }
+        catch (IOException e) { LcLog.warn("TIFF header of " + file + " could not be read (the calibration of the server is used)", e); return fromServer }
+    }
+
+    /** The local file behind a server when it is a TIFF (by its header), else null. */
+    static File localTiff(def server) {
+        try {
+            def uri = server.URIs?.find { it.scheme == "file" }
+            if (uri == null) return null
+            def file = new File(uri)
+            LcTiff.tags(file)
+            return file
+        } catch (IOException | RuntimeException e) {      // not a local file, or not a TIFF: the server's own calibration is used
+            return null
+        }
+    }
+
+    /** The calibration in the server's metadata differs from the one the reader found: somebody entered it in QuPath. */
+    static boolean calibrationEdited(def server) {
+        try { return server.metadata.pixelCalibration != server.originalMetadata.pixelCalibration }
+        catch (RuntimeException e) { LcLog.warn("could not compare the calibration of the server with its original", e); return false }
+    }
+
+    /** The pixel size of a file: a TIFF by its tags (OME or ImageJ unit first, resolution tags only when they are not a 72 / 96 dpi default), any other file by its server. */
+    static LcCal ofFile(String path) {
+        def file = new File(path)
+        try { return ofTiffFile(file) } catch (IOException e) { LcLog.warn("not read as a TIFF: " + path + " (" + e.message + ")") }
+        def server = ImageServers.buildServer(file.toURI().toString())
+        def cal
+        try { cal = ofServer(server) } finally { server.close() }
+        return cal
+    }
+
+    /** A TIFF's own metadata (SPEC 2.1.6): an OME physical size or an ImageJ `unit=` wins over the resolution tags; tags alone count only when ResolutionUnit is INCH or
+     *  CENTIMETER and the resolution does not look like a 72 / 96 dpi default; NONE is unknown. Throws IOException for a file that is not a readable TIFF. */
+    static LcCal ofTiffFile(File file) {
+        def t = LcTiff.tags(file)
+        def ome = omePixelSizes(t.description as String)
+        if (ome != null) return calibrate(ome[0][0], ome[0][1], ome[1][0], ome[1][1])
+        if (t.xres == null) return UNKNOWN
+        double perX = t.xres[0] / t.xres[1], sizeX = t.xres[1] / t.xres[0]
+        def yres = t.yres ?: t.xres          // a missing YResolution means square
+        double perY = yres[0] / yres[1], sizeY = yres[1] / yres[0]
+        def unit = imageJUnit(t.description as String)
+        if (unit) return calibrate(sizeY, unit, sizeX, unit)       // ImageJ's own unit text names the unit, the tags give the number
+        int code = t.unit == null ? 2 : (t.unit as int)             // no ResolutionUnit tag: the TIFF default, INCH
+        if (code != 2 && code != 3) return UNKNOWN                  // NONE (or odd): the number has no unit
+        String name = code == 2 ? "inch" : "centimeter"
+        def raw = [[sizeY, name], [sizeX, name]]
+        if (LcUnits.defaultLooking(perX, code == 2) || LcUnits.defaultLooking(perY, code == 2)) return new LcCal(null, null, raw)
+        double factor = code == 2 ? 25400d : 10000d
+        return new LcCal(sizeY * factor, sizeX * factor, raw)
+    }
+
+    /** [[sizeY, unitY], [sizeX, unitX]] of the first <Pixels> element of an OME-XML description, or null without a physical size. A missing PhysicalSizeY means square; a size
+     *  without a unit text is unknown to the caller (the number alone is no evidence). */
+    static List omePixelSizes(String description) {
+        if (description == null || !description.contains("<OME")) return null
+        def m = description =~ /<(?:\w+:)?Pixels\b[^>]*>/
+        if (!m.find()) return null
+        String element = m.group()
+        def attr = { String name -> def a = element =~ (/\b/ + name + /\s*=\s*"([^"]*)"/); a.find() ? xmlText(a.group(1)) : null }
+        def sx = attr("PhysicalSizeX")
+        if (sx == null) return null
+        def ux = attr("PhysicalSizeXUnit")
+        def sy = attr("PhysicalSizeY")
+        return [[sy ?: sx, sy != null ? attr("PhysicalSizeYUnit") : ux], [sx, ux]]
+    }
+
+    static String xmlText(String s) {
+        return s.replaceAll(/&#x([0-9A-Fa-f]+);/) { all, hex -> new String(Character.toChars(Integer.parseInt(hex as String, 16))) }
+                .replaceAll(/&#(\d+);/) { all, dec -> new String(Character.toChars(Integer.parseInt(dec as String))) }
+                .replace("&lt;", "<").replace("&gt;", ">").replace("&quot;", '"').replace("&apos;", "'").replace("&amp;", "&")
+    }
+
+    /** The `unit=` of an ImageJ description ("ImageJ=1.x" first line), with \uXXXX escapes decoded; null without one. */
+    static String imageJUnit(String description) {
+        if (description == null || !description.startsWith("ImageJ=")) return null
+        def line = description.readLines().find { it.startsWith("unit=") }
+        if (line == null) return null
+        def text = line.substring(5).replaceAll(/\\u([0-9A-Fa-f]{4})/) { all, hex -> new String(Character.toChars(Integer.parseInt(hex as String, 16))) }
+        return text ?: null
+    }
+}
+
+/** The few tags of the first page of a TIFF (classic or BigTIFF) the calibration needs: ImageDescription, XResolution, YResolution, ResolutionUnit. Read without decoding any pixel. */
+class LcTiff {
+    static final int TAG_DESCRIPTION = 270, TAG_XRES = 282, TAG_YRES = 283, TAG_UNIT = 296
+    static final int MAX_DESCRIPTION_BYTES = 64 * 1024 * 1024
+    static final int MAX_ENTRIES = 4096
+
+    /** [description, xres: [numerator, denominator], yres, unit] of the first page; IOException when the file is not a TIFF or its first page cannot be read. */
+    static Map tags(File file) {
+        def raf = new RandomAccessFile(file, "r")
+        try {
+            def ch = raf.channel
+            def head = read(ch, 0L, 16, ByteOrder.BIG_ENDIAN)
+            if (head == null) throw new IOException("not a TIFF (too short)")
+            int b0 = head.get(0), b1 = head.get(1)
+            ByteOrder order = (b0 == 0x49 && b1 == 0x49) ? ByteOrder.LITTLE_ENDIAN : (b0 == 0x4D && b1 == 0x4D) ? ByteOrder.BIG_ENDIAN : null
+            if (order == null) throw new IOException("not a TIFF (no byte order mark)")
+            head.order(order)
+            int magic = head.getShort(2) & 0xffff
+            boolean big = magic == 43
+            if (!big && magic != 42) throw new IOException("not a TIFF (bad magic number " + magic + ")")
+            long ifd = big ? head.getLong(8) : (head.getInt(4) & 0xffffffffL)
+            def countBuf = read(ch, ifd, big ? 8 : 2, order)
+            if (countBuf == null) throw new IOException("TIFF: the first page lies outside the file")
+            long entries = big ? countBuf.getLong(0) : (countBuf.getShort(0) & 0xffffL)
+            if (entries <= 0 || entries > MAX_ENTRIES) throw new IOException("TIFF: odd number of tags in the first page: " + entries)
+            int entrySize = big ? 20 : 12, inline = big ? 8 : 4
+            def out = [description: null, xres: null, yres: null, unit: null]
+            for (long i = 0; i < entries; i++) {
+                long at = ifd + (big ? 8 : 2) + i * entrySize
+                def e = read(ch, at, entrySize, order)
+                if (e == null) throw new IOException("TIFF: a tag lies outside the file")
+                int tag = e.getShort(0) & 0xffff, type = e.getShort(2) & 0xffff
+                long count = big ? e.getLong(4) : (e.getInt(4) & 0xffffffffL)
+                if (!(tag in [TAG_DESCRIPTION, TAG_XRES, TAG_YRES, TAG_UNIT])) continue
+                long size = count * typeSize(type)
+                long data = size <= inline ? at + (big ? 12 : 8) : (big ? e.getLong(12) : (e.getInt(8) & 0xffffffffL))
+                if (tag == TAG_DESCRIPTION && type == 2) {
+                    if (size > MAX_DESCRIPTION_BYTES) continue
+                    def bytes = read(ch, data, (int) size, order)
+                    if (bytes != null) out.description = new String(bytes.array(), 0, (int) size, "UTF-8").replace("\u0000", "")
+                } else if ((tag == TAG_XRES || tag == TAG_YRES) && type == 5 && count >= 1) {
+                    def r = read(ch, data, 8, order)
+                    if (r != null) {
+                        long num = r.getInt(0) & 0xffffffffL, den = r.getInt(4) & 0xffffffffL
+                        if (num != 0 && den != 0) out[tag == TAG_XRES ? "xres" : "yres"] = [num as double, den as double]
+                    }
+                } else if (tag == TAG_UNIT && (type == 3 || type == 4) && count >= 1) {
+                    def r = read(ch, data, type == 3 ? 2 : 4, order)
+                    if (r != null) out.unit = type == 3 ? (r.getShort(0) & 0xffff) : r.getInt(0)
+                }
+            }
+            return out
+        } finally { raf.close() }
+    }
+
+    static int typeSize(int type) { return [1: 1, 2: 1, 3: 2, 4: 4, 5: 8, 6: 1, 7: 1, 8: 2, 9: 4, 10: 8, 11: 4, 12: 8, 16: 8, 17: 8, 18: 8].get(type, 1) }
+
+    /** `length` bytes at `position`, or null when they are not all in the file. */
+    static ByteBuffer read(def channel, long position, int length, ByteOrder order) {
+        if (position < 0 || position + length > channel.size()) return null
+        def buf = ByteBuffer.allocate(length)
+        while (buf.hasRemaining()) { if (channel.read(buf, position + buf.position()) < 0) return null }
+        buf.flip()
+        buf.order(order)
+        return buf
+    }
+}
+
+/** The state of a linked pixel-size field (SPEC 2.2) and the `_calibration` entry of a request (2.3.4). A `PixelSizeOf` field is unset, auto(source, value) or user(value).
+ *  The state is a flag set by the person's edit events (userEdit), never inferred by comparing the field with the last automatic value, and a programmatic set
+ *  (sourceChanged) never makes it user. The value a run sends is read from here, not from the box. */
+class LcLink {
+    static final String UNSET = "unset", AUTO = "auto", USER = "user"
+    static final String CANONICAL_UNIT = "um"       // micrometres per pixel: the contract of PixelSizeOf
+    final String param, of           // the manifest parameter and the image parameter it describes
+    String state = UNSET
+    LcCal cal                        // the source the AUTO value came from
+    String source                    // "image" | "file" (where `cal` came from)
+    Double user
+    String invalid                   // text the person typed that is not a number (state USER, no value): a run refuses it by name
+
+    LcLink(String param, String of) { this.param = param; this.of = of }
+
+    /** The image, the file or the project image changed (or the field is derived again). True when the field's value may have changed. A user value stays; otherwise the field
+     *  takes the new source's value, or is cleared when the source is unknown. */
+    boolean sourceChanged(LcCal derived, String from) {
+        if (state == USER) return false
+        if (derived != null && derived.fieldValue != null) { state = AUTO; cal = derived; source = from }
+        else { state = UNSET; cal = null; source = null }
+        return true
+    }
+
+    /** The person typed or pasted a value. An empty text is the person asking for the image's calibration again: unset, and the caller derives it from the current source. */
+    void userEdit(Double value) {
+        invalid = null
+        if (value == null) { state = UNSET; user = null; cal = null; source = null }
+        else { state = USER; user = value }       // 0, a negative or a non-finite number is the person's too; a run refuses it by name
+    }
+
+    Double getValue() {
+        if (state == USER) return user
+        return state == AUTO && cal != null ? cal.fieldValue : null
+    }
+
+    String getOrigin() { return state == USER ? USER : (cal != null ? source : null) }
+
+    /** The `_calibration` entry of this field (2.3.4), or null while it has no value. Phase 1: x and y only. */
+    Map entry() {
+        Double v = value
+        if (v == null) return null
+        def axis = { double number, String from, List raw ->
+            def a = [value: number, unit: CANONICAL_UNIT, source: from]
+            if (raw != null && (raw[0] != null || raw[1] != null)) a.raw = [scale: raw[0], unit: raw[1]]
+            a
+        }
+        def axes
+        if (state == USER || cal == null || !cal.known) axes = [x: axis(v, USER, null), y: axis(v, USER, null)]
+        else axes = [x: axis(cal.x, source, cal.raw[1] as List), y: axis(cal.y, source, cal.raw[0] as List)]
+        return [of: of, source: origin, axes: axes]
+    }
+
+    String tooltip() {
+        Double v = value
+        if (state == USER && v != null) return String.format(Locale.ROOT, "%s um per pixel, entered by you: it overrides the calibration of '%s'", LcLink.plain(v), of)
+        if (state == AUTO && cal != null && v != null) return LcLink.plain(v) + " um per pixel, from the calibration of " + (source == "file" ? "the file" : "'" + of + "'")
+        return LcUnits.NOT_CALIBRATED_TOOLTIP.replace("{of}", of)
+    }
+
+    String requiredMessage() { return LcUnits.CALIBRATION_REQUIRED.replace("{param}", param).replace("{of}", of) }
+
+    /** A number as short as it can be written exactly (0.25, 1, 0.5002), never 1.0E-4. */
+    static String plain(double v) { return new BigDecimal(Double.toString(v)).stripTrailingZeros().toPlainString() }
+}
+
 // ---------------------------------------------------------------------------------------------------- registry and trust checks
 /** Finds the registered LabConstrictor apps and refuses entries that fail the trust checks in load(). */
 class LcRegistry {
@@ -705,7 +1070,10 @@ class LcDialog {
     volatile Map<String, Map> framesAtRun = [:]        // image parameter -> [width, height] of what the tool received (SPEC 1.1.7: a result that says ApplyTo and has another size is said)
     List<String> resultNotes = []                      // sentences about the results of the last run that go to the status line (e.g. size_mismatch), said once
     Map<String, String> imageOf = [:]            // pixel-size parameter -> image parameter
-    Map<String, Double> autoPixel = [:]          // pixel-size parameter -> the value the host last wrote (a different value in the box was typed by the person)
+    Map<String, LcLink> links = [:]              // pixel-size parameter -> the state of its field (unset / auto / user), a flag set by the person's edits (SPEC 2.2)
+    volatile Map<String, Map> calibrationAtRun = [:]     // pixel-size parameter -> its `_calibration` entry, frozen when the request was read (SPEC 2.3.4)
+    List imageDataListeners = []                 // listeners on QuPath's image property (removed when the window closes)
+    boolean programmatic = false                 // true while the host writes a pixel-size field (such a write is never a person's edit)
     Map<String, TextField> fileFields = [:]      // image parameter -> the field for a file path
     LcWorker worker
     String workerApp
@@ -717,6 +1085,7 @@ class LcDialog {
         this.qupath = qupath
         this.apps = registry.apps
         this.problems = registry.problems
+        LcUnits.useApps(apps.values().collect { it.entry })      // the unit catalog comes from the labconstrictor-tools of a registered app
     }
 
     // ---- the form: window and top-level wiring
@@ -731,7 +1100,7 @@ class LcDialog {
             status.text = "No LabConstrictor app is registered on this machine." + (problems ? " Skipped: " + problems.join("; ") : "")
         }
         stage.scene = new Scene(root)
-        stage.onHidden = { stopWorker(false) }   // also when closed from code
+        stage.onHidden = { stopWorker(false); imageDataListeners.each { qupath?.imageDataProperty()?.removeListener(it as javafx.beans.value.ChangeListener) } }   // also when closed from code
         stage.show()
         if (!apps.isEmpty()) appBox.value = apps.keySet().first()
     }
@@ -832,7 +1201,7 @@ class LcDialog {
         def app = apps[appBox.value]
         currentTool = app ? toolNames(app.schema.tools)[toolBox.value] : null
         formBox.children.clear()
-        getters.clear(); setters.clear(); controls.clear(); wrappers.clear(); imageBoxes.clear(); areaBoxes.clear(); imageOf.clear(); selectionBoxes.clear(); autoPixel.clear(); fileFields.clear()
+        getters.clear(); setters.clear(); controls.clear(); wrappers.clear(); imageBoxes.clear(); areaBoxes.clear(); imageOf.clear(); selectionBoxes.clear(); links.clear(); fileFields.clear()
         checks.clear(); choiceBoxes.clear(); choiceSeq.clear(); channelBoxes.clear()
         description.text = currentTool?.description ?: ""
         if (currentTool == null) return
@@ -947,6 +1316,7 @@ class LcDialog {
         currentTool.inputs.findAll { it.clear_after_run }.each { p ->
             checks[p.name]?.selected = false
             choiceBoxes[p.name]?.value = ""
+            if (p.pixel_size_of && links[p.name] != null) { links[p.name].userEdit(null); fillPixelSize(p); return }      // a linked pixel size starts again from its image, never from the declared default
             def start = p.default != null ? p.default : (p.type == "string" ? "" : null)
             if (start != null && p.type != "image" && p.type != "labels") setters[p.name](start)
         }
@@ -1068,7 +1438,7 @@ class LcDialog {
             case "boolean": built = booleanControl(p); break
             case "choice": built = choiceControl(p); break
             case "integer": built = integerControl(p); break
-            case "float": built = floatControl(p); break
+            case "float": built = p.pixel_size_of ? pixelSizeControl(p) : floatControl(p); break
             case "image":
             case "labels": built = imageControl(p, sources); break
             case "file":
@@ -1078,7 +1448,7 @@ class LcDialog {
         }
         Node node = built.node
         Closure get = built.get, set = built.set
-        if (p.nullable && !p.region_of) {      // optional without a default: unticked = the tool receives None (a region has its own 'use the selection' box)
+        if (p.nullable && !p.region_of && !p.pixel_size_of) {      // optional without a default: unticked = the tool receives None (a region has its own 'use the selection' box; a linked pixel size has its own state: unset sends null)
             def check = new CheckBox("set")
             checks[name] = check
             def control = node
@@ -1375,64 +1745,105 @@ class LcDialog {
         update()
     }
 
-    /** PixelSizeOf: refill the pixel size whenever another image is chosen or another file is typed, until the person edits the field (the Napari rule). */
-    void hookPixelSize(Map p) {
+    /** The control of a linked pixel-size field (PixelSizeOf, SPEC 2.2): a text box that shows the calibration of the chosen image or file, or nothing ("(not set)") when that is
+     *  unknown, and a button that asks for the image's calibration again. What a run sends is the state in `links`, not the text. A write by the host is never an edit by the person:
+     *  `programmatic` guards the text listener; typed or pasted text (also the same text again, through the key event) makes the value the person's. */
+    Map pixelSizeControl(Map p) {
+        def name = p.name as String
+        def field = new TextField()
+        field.promptText = "(not set)"
+        field.prefColumnCount = 10
+        def link = new LcLink(name, p.pixel_size_of as String)
+        links[name] = link
+        controls[name] = field
+        field.textProperty().addListener({ o, a, b -> if (!programmatic) pixelTextEdited(p) } as javafx.beans.value.ChangeListener)
+        field.addEventFilter(javafx.scene.input.KeyEvent.KEY_TYPED, { e -> if (!programmatic) Platform.runLater { pixelTextEdited(p) } } as javafx.event.EventHandler)      // typing the text the box already shows changes no text, but is still an edit
+        field.focusedProperty().addListener({ o, was, now -> if (!now && link.state == LcLink.UNSET && !field.text?.trim()) fillPixelSize(p) } as javafx.beans.value.ChangeListener)      // left empty: the image's calibration again
+        def useImage = new Button("Use the image's calibration")
+        useImage.onAction = { link.userEdit(null); fillPixelSize(p) }
+        return [node: new HBox(6, field, useImage), get: { link.value }, set: { writePixelText(p, it as Double) }]
+    }
+
+    /** The host writes `value` into a pixel-size field (null empties it): the state is not touched. */
+    void writePixelText(Map p, Double value) {
+        def field = controls[p.name] as TextField
+        programmatic = true
+        try { field.text = value == null ? "" : LcLink.plain(value) } finally { programmatic = false }
+    }
+
+    /** The person typed, pasted or deleted in a pixel-size field: the state becomes theirs. An empty box is "unset" (the image's calibration is taken again when the box loses the focus or a run starts); text that
+     *  is not a number is kept as typed, and a run refuses it by name. */
+    void pixelTextEdited(Map p) {
+        def link = links[p.name as String]
+        def field = controls[p.name] as TextField
+        if (link == null || field == null) return
+        def text = field.text?.trim()
+        if (!text) { link.userEdit(null); return }
+        def number = LcCal.number(text)
+        if (number == null) { link.userEdit(null); link.state = LcLink.USER; link.invalid = text; return }      // text that is not a number: the person's, and refused at the run
+        link.userEdit(number)
+    }
+
+    /** The calibration of what the field describes now, as [cal, source, label] or null (nothing to read yet): the file when the image input is a file (the file wins over the open
+     *  image), else the chosen QuPath image. An image that cannot be read is said and counts as unknown: the value of another image is never kept. */
+    Map deriveCalibration(Map p) {
         def box = imageBoxes[p.pixel_size_of]
-        if (box == null) return
-        autoPixel[p.name as String] = readPixelField(p)      // what the field holds now counts as "not edited"
-        box.valueProperty().addListener({ o, a, b -> fillPixelSize(p) } as javafx.beans.value.ChangeListener)
-        fileFields[p.pixel_size_of]?.textProperty()?.addListener({ o, a, b -> fillPixelSize(p) } as javafx.beans.value.ChangeListener)
-    }
-
-    /** The number now in a pixel-size field, or null. */
-    Double readPixelField(Map p) {
-        def v = getters[p.name]?.call()
-        return v instanceof Number ? (v as Double) : null
-    }
-
-    /** Same number, as the box holds it (a value the host wrote and read back). */
-    static boolean sameNumber(Double a, Double b) {
-        return a == null || b == null ? a == b : Math.abs(a - b) <= 1e-9d * Math.max(Math.abs(a), Math.abs(b))
-    }
-
-    /** The calibration of the chosen image or typed file as [y, x] micrometres per pixel (null: none stored). A file that cannot be read says so and returns null. */
-    List<Double> pixelSizeOfChoice(Map p, ComboBox<String> box) {
+        if (box == null) return null
+        def choice = box.value as String
+        if (choice == null || choice == NO_IMAGE) return null
         try {
-            def server = null
-            if (box.value == FILE_CHOICE) {
+            if (choice == FILE_CHOICE) {
                 def path = fileFields[p.pixel_size_of]?.text?.trim()
-                if (!path || !new File(path).isFile()) return null          // still being typed: nothing to read yet
-                server = ImageServers.buildServer(path)
-            } else {
-                server = imageSources()[box.value]?.call()
+                return (!path || !new File(path).isFile()) ? null : [cal: LcCal.ofFile(path), source: "file", label: path]      // a path still being typed: nothing to read yet
             }
-            def cal = server?.pixelCalibration
-            return (cal != null && cal.hasPixelSizeMicrons()) ? [cal.pixelHeightMicrons, cal.pixelWidthMicrons] : null
+            def server = imageSources()[choice]?.call()
+            if (server == null) return null
+            try { return [cal: LcCal.ofServer(server), source: "image", label: choice] }
+            finally { if (!isCurrentImage(choice)) server.close() }          // the open image belongs to QuPath; a project image was opened here
         } catch (Exception e) {     // broad on purpose (any reader can fail on any file): a listener on the image chooser must never break the form; the person types the value
-            LcLog.warn("pixel size of '" + box.value + "' could not be read", e)
-            status?.text = "could not read the pixel size from " + (box.value == FILE_CHOICE ? fileFields[p.pixel_size_of]?.text?.trim() : box.value) + " (" + e.message + "): type it"
+            LcLog.warn("pixel size of '" + choice + "' could not be read", e)
+            status?.text = "could not read the pixel size from " + (choice == FILE_CHOICE ? fileFields[p.pixel_size_of]?.text?.trim() : choice) + " (" + e.message + "): type it"
             return null
         }
     }
 
-    /** The pixel size of the chosen QuPath image or file goes into its pixel-size parameter (micrometres per pixel), unless the person typed another value;
-     *  pixels that are not square are said: the tool takes one value and gets X. */
+    /** PixelSizeOf: the source changed (another image or file, or the field is derived again): an unset or automatic field takes the new source's calibration, or is cleared when that is
+     *  unknown (SPEC 2.2); a value the person entered stays. A warning (pixels not square, a unit that is not a length) goes to the status line. */
     void fillPixelSize(Map p) {
+        def link = links[p.name as String]
+        if (link == null || imageBoxes[p.pixel_size_of] == null) return
+        if (link.state != LcLink.USER) {
+            def derived = deriveCalibration(p)
+            link.sourceChanged(derived?.cal as LcCal, derived?.source as String)
+            link.invalid = null
+            def note = (derived?.cal as LcCal)?.note
+            if (note) status?.text = "\u26a0 " + note + " (" + derived.label + ")"
+        }
+        showLink(p)
+    }
+
+    /** What the field shows for its state: the value (empty when unset) and the tooltip that says where it comes from. */
+    void showLink(Map p) {
+        def link = links[p.name as String]
+        def field = controls[p.name] as TextField
+        if (link.state != LcLink.USER) writePixelText(p, link.value)
+        field.tooltip = new Tooltip(link.tooltip())
+    }
+
+    /** PixelSizeOf: the field follows the chosen image, the typed file and the image open in QuPath until the person enters a value. */
+    void hookPixelSize(Map p) {
         def box = imageBoxes[p.pixel_size_of]
         if (box == null) return
-        def name = p.name as String
-        if (!sameNumber(readPixelField(p), autoPixel[name])) return       // edited by the person: kept
-        def yx = pixelSizeOfChoice(p, box)
-        if (yx == null) return
-        setters[name](yx[1])
-        autoPixel[name] = readPixelField(p)
-        if (Math.abs(yx[0] - yx[1]) > LcConst.SQUARE_PIXEL_TOLERANCE * Math.max(Math.abs(yx[0]), Math.abs(yx[1])))
-            status?.text = "\u26a0 pixel size differs: Y " + significant(yx[0]) + " \u00b5m, X " + significant(yx[1]) + " \u00b5m - the tool takes one value and gets X"
+        def again = { o, a, b -> fillPixelSize(p) } as javafx.beans.value.ChangeListener
+        box.valueProperty().addListener(again)
+        fileFields[p.pixel_size_of]?.textProperty()?.addListener(again)
+        qupath?.imageDataProperty()?.addListener(again)      // the open image changed: "Current image" is another image now
+        imageDataListeners << again
     }
 
-    /** `value` with six significant digits and no trailing zeros, like Python's "%.6g" (0.25 not 0.250000). */
-    static String significant(double value) {
-        return new BigDecimal(value).round(new java.math.MathContext(LcConst.SIGNIFICANT_DIGITS)).stripTrailingZeros().toPlainString()
+    /** A run starts: every field that is not the person's own reads its source again (a calibration may have been edited in QuPath since it was chosen). */
+    void refreshLinks() {
+        currentTool?.inputs?.findAll { it.pixel_size_of && links[it.name] != null }?.each { p -> fillPixelSize(p) }
     }
 
     // ---- copy as command (the text format of labconstrictor_tools.command, the reference). Quoting only through two helpers: shellQuote (terminal words)
@@ -1591,6 +2002,19 @@ class LcDialog {
         for (p in currentTool.inputs) {
             def v
             try { v = getters[p.name]() } catch (Exception e) { LcLog.warn("could not read '" + p.name + "'", e); status.text = "Check '" + p.label + "': " + e.message; return null }
+            if (p.pixel_size_of && links[p.name] != null) {      // a linked pixel size (SPEC 2.3): the state decides; the declared default is never a stand-in
+                def link = links[p.name]
+                if (link.invalid != null) { status.text = "'" + p.label + "': '" + link.invalid + "' is not a number"; return null }
+                if (v == null) {
+                    if (!p.nullable) { status.text = link.requiredMessage(); return null }
+                    values[p.name] = null       // Optional[float]: an unset field sends null, nothing is blocked
+                    continue
+                }
+                if (!Double.isFinite(v as double)) { status.text = "'" + p.label + "' must be a finite number"; return null }
+                if (!((v as double) > 0d)) { status.text = "'" + p.label + "' must be greater than 0 (um per pixel)"; return null }
+                values[p.name] = v
+                continue
+            }
             if (v == null) {
                 if (p.required && !p.nullable && p.type in ["image", "labels", "table", "file", "folder", "string"]) { status.text = requiredSentence(p); return null }
                 continue
@@ -1598,6 +2022,7 @@ class LcDialog {
             if (v instanceof Double && !Double.isFinite(v)) { status.text = "'" + p.label + "' must be a finite number"; return null }      // Gson cannot write NaN or infinity: refused here, with the worker's sentence
             values[p.name] = v
         }
+        calibrationAtRun = links.collectEntries { name, link -> [(name): link.entry()] }.findAll { it.value != null && values[it.key] != null } as Map      // frozen with the values
         return values
     }
 
@@ -1610,6 +2035,7 @@ class LcDialog {
     /** Run pressed: read the form, then start the run in the background. */
     void run() {
         if (running || currentTool == null) return
+        refreshLinks()
         def values = readFormValues()
         if (values == null) return
         imageChoiceAtRun = imageBoxes.collectEntries { k, b -> [(k): b.value as String] }
@@ -1741,6 +2167,8 @@ class LcDialog {
         framesAtRun = [:]
         areasAtRun = resolveAreas(values, params)       // before anything is exported: a refused area costs nothing
         values.each { name, v -> inputs[name] = prepareInput(params.find { it.name == name }, name as String, v, tmp, appName) }
+        def calibration = calibrationAtRun.findAll { name, entry -> values[name] != null }
+        if (calibration) inputs["_calibration"] = calibration      // the reserved per-axis input (SPEC 2.3.4): tools never see it, the run record keeps it
         inputs["_job_dir"] = newJobDir(appName, toolId).absolutePath
         return inputs
     }
diff --git a/tests/calibration_fixtures.py b/tests/calibration_fixtures.py
new file mode 100644
index 0000000..adb402f
--- /dev/null
+++ b/tests/calibration_fixtures.py
@@ -0,0 +1,29 @@
+"""Writes the images of the calibration tests (tests/gui_test_calibration_body.groovy) from a JSON list: python tests/calibration_fixtures.py spec.json
+Each entry: {"file": path, "kind": "ome" | "imagej" | "tags" | "plain", ...}. `ome`: sx, ux, sy, uy (PhysicalSize and its unit text, kept exactly);
+`imagej`: unit, resolution; `tags`: resolution (pixels per resolution unit, x then y), resolutionunit (INCH, CENTIMETER, NONE); `plain`: nothing."""
+import json
+import sys
+
+import numpy as np
+import tifffile
+
+
+def main(spec_path: str) -> None:
+    image = np.arange(8 * 12, dtype=np.uint16).reshape(8, 12)
+    for item in json.load(open(spec_path, encoding="utf-8")):
+        kind = item["kind"]
+        if kind == "ome":
+            meta = {"axes": "YX", "PhysicalSizeX": item["sx"], "PhysicalSizeXUnit": item["ux"]}
+            if item.get("sy") is not None:
+                meta.update({"PhysicalSizeY": item["sy"], "PhysicalSizeYUnit": item["uy"]})
+            tifffile.imwrite(item["file"], image, ome=True, metadata=meta)
+        elif kind == "imagej":
+            tifffile.imwrite(item["file"], image, imagej=True, resolution=tuple(item["resolution"]), metadata={"unit": item["unit"]})
+        elif kind == "tags":
+            tifffile.imwrite(item["file"], image, resolution=tuple(item["resolution"]), resolutionunit=item["resolutionunit"])
+        else:
+            tifffile.imwrite(item["file"], image)
+
+
+if __name__ == "__main__":
+    main(sys.argv[1])
diff --git a/tests/frame_app/frame_lc_tools.py b/tests/frame_app/frame_lc_tools.py
index b9ca1f5..934cee8 100644
--- a/tests/frame_app/frame_lc_tools.py
+++ b/tests/frame_app/frame_lc_tools.py
@@ -1,10 +1,10 @@
-"""Test tool for the coordinate-frame tests (CF-01..14): it reports what it RECEIVED (image shape, pixel values, mask) and returns results at positions the test chooses.
+"""Test tools for the coordinate-frame (CF-01..14) and calibration (CAL-01..20, CAL-T1..T9) tests: it reports what it RECEIVED (image shape, pixel values, mask) and returns results at positions the test chooses.
 
 The tool never sees a world, slide or viewer coordinate: it gets the exported file only (SPEC_WRONG_SCIENCE 1.1.1), so what it reports is the host's export."""
 from typing import Annotated, Optional
 
 import numpy as np
-from labconstrictor_tools import ApplyTo, Image, LabelsOut, Labels, MessageOut, Name, PointsOut, RegionOf, Replace, Scalars, ShapesOut, tool
+from labconstrictor_tools import ApplyTo, Image, LabelsOut, Labels, MessageOut, Name, PixelSizeOf, PointsOut, RegionOf, Replace, Scalars, ShapesOut, Unit, tool
 
 
 @tool("Frame probe")
@@ -35,3 +35,21 @@ def probe(
     x0, x1, y0, y1 = cols.min() - 0.5, cols.max() + 0.5, rows.min() - 0.5, rows.max() + 0.5
     box = {"type": "FeatureCollection", "features": [{"type": "Feature", "properties": {"label": 1}, "geometry": {"type": "Polygon", "coordinates": [[[x0, y0], [x1, y0], [x1, y1], [x0, y1], [x0, y0]]]}}]}
     return seen, [{"y": float(y), "x": float(x)}], box, labels, "probed"
+
+
+@tool("Pixel size required")
+def pixel_required(
+    image: Image,
+    pixel_size: Annotated[float, PixelSizeOf("image"), Unit("um/px")] = 1.0,  # a declared default that must never stand in for a missing calibration (CAL-T8)
+) -> Annotated[Scalars, Name("seen")]:
+    """Report the pixel size it received (the number the host sent in the manifest parameter)."""
+    return {"pixel_size": float(pixel_size), "image_shape": [int(n) for n in np.asarray(image).shape]}
+
+
+@tool("Pixel size optional")
+def pixel_optional(
+    image: Image,
+    pixel_size: Annotated[Optional[float], PixelSizeOf("image"), Unit("um/px")] = None,
+) -> Annotated[Scalars, Name("seen")]:
+    """Report the pixel size it received: null when the host had no calibration."""
+    return {"pixel_size": None if pixel_size is None else float(pixel_size), "image_shape": [int(n) for n in np.asarray(image).shape]}
diff --git a/tests/gui_test_calibration_body.groovy b/tests/gui_test_calibration_body.groovy
new file mode 100644
index 0000000..4f87840
--- /dev/null
+++ b/tests/gui_test_calibration_body.groovy
@@ -0,0 +1,327 @@
+// ================================================================== GUI test body: calibration (SPEC_WRONG_SCIENCE section 2: CAL-01..CAL-20 and CAL-T1..CAL-T9 of conformance.json)
+// (appended to the tool script by tests/run_gui_test.sh). Needs the `frame` test app (tests/frame_app: tools "Pixel size required" with a declared default of 1.0 and "Pixel size optional").
+// Every case checks the REQUEST the host would send (readFormValues + prepareInputs: the value of the manifest parameter and the reserved `_calibration` input), not only the
+// field, and the transitions also run the real worker and read the run record. The cases and the unit catalog are read from the conformance file of labconstrictor-tools
+// (LC_CONFORMANCE, else `python -m labconstrictor_tools.conformance --path` of the registered app: the way the host itself loads the catalog).
+// Sources in QuPath: a file input (TIFF/OME tags and units, ImageJ units), a project image and the image open in QuPath (its PixelCalibration, through the unit catalog).
+import javafx.scene.input.KeyCode
+import javafx.scene.input.KeyEvent
+import java.util.concurrent.CountDownLatch
+import java.awt.image.BufferedImage
+
+def FIXTURES = System.getProperty("lc.test.fixtures", new File("tests/fixtures").absolutePath)
+def TESTS = new File(FIXTURES).parentFile
+def WORK = new File(System.getProperty("java.io.tmpdir"), "lc_cal_scratch"); WORK.deleteDir(); WORK.mkdirs()
+def results = [:]
+def fx = { Closure c ->
+    if (Platform.isFxApplicationThread()) return c()
+    def latch = new CountDownLatch(1); def box = [null, null]
+    Platform.runLater { try { box[0] = c() } catch (Throwable t) { box[1] = t } finally { latch.countDown() } }
+    latch.await()
+    if (box[1] != null) throw box[1]
+    return box[0]
+}
+def expect = { String name, boolean ok, Object detail = "" ->
+    results[name] = ok
+    println((ok ? "PASS " : "FAIL ") + name + (ok ? "" : " -> " + detail))
+}
+def waitIdle = { dlg, int seconds = 300 ->
+    def end = System.currentTimeMillis() + seconds * 1000
+    while (System.currentTimeMillis() < end) { Thread.sleep(200); if (!dlg.running && fx { !dlg.runButton.disable }) return true }
+    return false
+}
+def status = { dlg -> fx { dlg.status.text } }
+def pick = { dlg, app, tool -> fx { dlg.appBox.value = app }; fx { dlg.toolBox.value = tool } }
+def run = { dlg -> fx { dlg.run() }; Thread.sleep(1500); waitIdle(dlg, 120) }
+def SHARED_HOME = new File(System.getenv("LC_SHARED_HOME") ?: System.getenv("LC_HOME"))
+def FRAME_APP = LcJson.parse(new File(SHARED_HOME, "apps/frame.json"))
+def PY = FRAME_APP.python
+def confPath = System.getenv("LC_CONFORMANCE") ?: [PY, "-m", "labconstrictor_tools.conformance", "--path"].execute().text.trim()
+def CONF = LcJson.parse(new File(confPath))
+def CAL = CONF.wrong_science.calibration
+def calCase = { String id -> def c = CAL.cases.find { it.id == id }; assert c != null : "conformance.json has no case " + id; c }
+def transition = { String id -> def c = CAL.transitions.find { it.id == id }; assert c != null : "conformance.json has no transition " + id; c }
+def near = { double a, double b -> Math.abs(a - b) <= 1e-9 * Math.max(Math.abs(a), Math.abs(b)) }
+def REQUIRED = { String param, String of -> CONF.messages.calibration_required.template.replace("{param}", param).replace("{of}", of) }
+def TOOLTIP = { String of -> CONF.messages.calibration_unknown_tooltip.template.replace("{of}", of) }
+def NOT_SQUARE = CONF.messages.pixels_not_square_warning.template
+def NOT_LENGTH = { String u -> CONF.messages.unit_not_length_warning.template.replace("{unit}", u) }
+def DAMAGED = { String u -> CONF.messages.unit_damaged_warning.template.replace("{unit}", u) }
+// the files of the cases: written by one python call (tests/calibration_fixtures.py), named c000.tif ...
+def specs = [], counter = 0
+def spec = { Map s -> def f = new File(WORK, String.format("c%03d.tif", counter++)).absolutePath; specs << ([file: f] + s); f }
+def ome = { sx, ux, sy = null, uy = null -> spec([kind: "ome", sx: sx, ux: ux, sy: sy, uy: uy]) }
+
+Thread.start("lc-gui-test") {
+    try {
+        // ---- the data this test stands on exists (no silent skip when a key is missing)
+        expect("conformance_has_the_calibration_data", CAL.length_units.keySet().containsAll(["nm", "um", "mm", "cm", "m", "angstrom"]) && CAL.cases.size() == 20 && CAL.transitions.size() == 9 && CAL.unit_match_refused.size() > 40 && CAL.reserved_input == "_calibration", CAL.keySet())
+        expect("constants_are_the_conformance_values", LcConst.SQUARE_PIXEL_TOLERANCE == (CAL.anisotropy_tolerance.relative_to_larger as double) && LcUnits.NOT_SQUARE_TEXT == NOT_SQUARE && LcUnits.CALIBRATION_REQUIRED == CONF.messages.calibration_required.template &&
+                LcUnits.NOT_CALIBRATED_TOOLTIP == CONF.messages.calibration_unknown_tooltip.template && LcUnits.NOT_A_LENGTH_TEXT == CONF.messages.unit_not_length_warning.template && LcUnits.DAMAGED_TEXT == CONF.messages.unit_damaged_warning.template && LcUnits.DAMAGED_PREFIX == CAL.damaged_micro_prefix, "")
+
+        // ---- the files
+        def imageJFile = { double res, String unit -> spec([kind: "imagej", unit: unit, resolution: [res, res]]) }
+        def A = imageJFile(4.0, "um"), B = imageJFile(2.0, "um"), U = spec([kind: "tags", resolution: [1, 1], resolutionunit: "NONE"]), U2 = spec([kind: "plain"])   // A 0.25 um, B 0.5 um, U and U2 uncalibrated
+        def cases = [:]            // case id -> list of [label, file, expected]
+        def add = { String id, String label, String file, def expected, String warning = null -> cases.get(id, []) << [label: label, file: file, expected: expected, warning: warning] }
+        // CAL-01..04 (Napari layers) as OME files: a number with an explicit unit, a unit that is the default 'pixel', or none
+        add("CAL-01", "(1,1) micrometer", ome(1.0, "micrometer", 1.0, "micrometer"), 1.0)
+        add("CAL-02", "(1,1) pixel", ome(1.0, "pixel", 1.0, "pixel"), "unknown")
+        add("CAL-03", "(1,1) millimeter", ome(1.0, "millimeter", 1.0, "millimeter"), 1000.0)
+        add("CAL-04", "(0.25,0.25) pixel", ome(0.25, "pixel", 0.25, "pixel"), "unknown")
+        add("CAL-04", "(0.25,0.25) no unit", ome(0.25, "", 0.25, ""), "unknown")
+        calCase("CAL-05").input.variants.each { v -> add("CAL-05", v.scale + " " + v.unit, ome(v.scale, v.unit, v.scale, v.unit), 0.325) }
+        add("CAL-06", "(0.5,0.25) um", ome(0.25, "um", 0.5, "um"), "unknown", NOT_SQUARE)             // OME: x 0.25, y 0.5 (the case's scale is (y, x) = (0.5, 0.25))
+        add("CAL-07", "(1,1) second", ome(1.0, "second", 1.0, "second"), "unknown", NOT_LENGTH("second"))
+        // CAL-08 (Fiji Calibration): the same unit text as an ImageJ file
+        [["micron", 1.0], ["pixel", "unknown"], ["", "unknown"]].each { u, e -> add("CAL-08", "ImageJ unit '" + u + "'", u == "" ? spec([kind: "imagej", unit: "", resolution: [1.0, 1.0]]) : imageJFile(1.0, u), e) }
+        // CAL-10..14 (TIFF)
+        add("CAL-10", "ImageJ unit=micron, 1 um", imageJFile(1.0, "micron"), 1.0)
+        add("CAL-10", "no unit, ResolutionUnit NONE", U, "unknown")
+        add("CAL-10", "no tags at all", U2, "unknown")
+        add("CAL-11", "INCH 72 dpi", spec([kind: "tags", resolution: [72, 72], resolutionunit: "INCH"]), "unknown")
+        add("CAL-12", "INCH 96 dpi", spec([kind: "tags", resolution: [96, 96], resolutionunit: "INCH"]), "unknown")
+        add("CAL-13", "CENTIMETER 28.35", spec([kind: "tags", resolution: [28.35, 28.35], resolutionunit: "CENTIMETER"]), "unknown")
+        add("CAL-13", "CENTIMETER 37.80", spec([kind: "tags", resolution: [37.8, 37.8], resolutionunit: "CENTIMETER"]), "unknown")
+        add("CAL-14", "INCH 25400 dpi", spec([kind: "tags", resolution: [25400, 25400], resolutionunit: "INCH"]), 1.0)
+        add("CAL-14", "CENTIMETER 10000 per cm", spec([kind: "tags", resolution: [10000, 10000], resolutionunit: "CENTIMETER"]), 1.0)
+        add("CAL-11", "INCH 72.2 dpi (within 0.5 %)", spec([kind: "tags", resolution: [72.2, 72.2], resolutionunit: "INCH"]), "unknown")
+        add("CAL-14", "INCH 73 dpi (outside 0.5 %)", spec([kind: "tags", resolution: [73, 73], resolutionunit: "INCH"]), 25400.0 / 73)
+        calCase("CAL-15").input.variants.each { v -> add("CAL-15", "unit " + v.unit, ome(v.scale, v.unit, v.scale, v.unit), 0.5) }
+        add("CAL-16", "damaged micro sign", ome(0.5, "�m", 0.5, "�m"), "unknown", DAMAGED("�m"))
+        calCase("CAL-17").input.variants.each { v -> add("CAL-17", "unit " + v.unit, ome(v.scale, v.unit, v.scale, v.unit), 0.0001) }
+        add("CAL-18", "(0.5, 0.5004)", ome(0.5004, "um", 0.5, "um"), 0.5002)
+        add("CAL-18", "(0.5, 0.5006)", ome(0.5006, "um", 0.5, "um"), "unknown", NOT_SQUARE)
+        CAL.unit_match_refused.each { u -> add("CAL-19", "refused '" + u + "'", ome(1.0, u, 1.0, u), "unknown") }
+        def c20 = calCase("CAL-20")
+        c20.input.variants.eachWithIndex { v, i -> add("CAL-20", "unit '" + v.unit + "'", ome(v.scale, v.unit, v.scale, v.unit), c20.expect.um_per_px_each[i]) }
+        def specFile = new File(WORK, "spec.json"); specFile.setText(LcJson.toJson(specs), "UTF-8")
+        def make = [PY, new File(TESTS, "calibration_fixtures.py").path, specFile.path].execute()
+        def makeErr = make.err.text
+        expect("fixture_files_were_written", make.waitFor() == 0 && specs.every { new File(it.file).isFile() }, makeErr)
+        // the premise of the unit cases: the file keeps the unit text exactly
+        def damagedFile = cases["CAL-16"][0].file
+        expect("premise_the_damaged_unit_text_is_in_the_file", LcTiff.tags(new File(damagedFile)).description.contains("PhysicalSizeXUnit=\"�m\""), "")
+
+        // ---- the project: A, B, U as project images, A open in QuPath
+        fx {
+            def dir = new File(System.getProperty("java.io.tmpdir"), "qp_project_cal"); dir.deleteDir()
+            qupath.lib.gui.prefs.PathPrefs.imageTypeSettingProperty().set(qupath.lib.gui.prefs.PathPrefs.ImageTypeSetting.AUTO_ESTIMATE)
+            def project = qupath.lib.projects.Projects.createProject(dir, BufferedImage)
+            [["A", A], ["B", B], ["U", U]].each { n, f -> def s = qupath.lib.images.servers.ImageServers.buildServer(f); def e = project.addImage(s.getBuilder()); e.setImageName(n) }
+            project.syncChanges(); qupath.setProject(project)
+        }
+        def openImage = { String name ->
+            fx { qupath.imageData?.setChanged(false); qupath.openImageEntry(qupath.project.imageList.find { it.imageName == name }); null }
+            Thread.sleep(2500)
+        }
+        openImage("A")
+        def dlg = fx { lcShow() }
+        Thread.sleep(800)
+        pick(dlg, "frame", "Pixel size required"); Thread.sleep(800)
+        def p = [name: "pixel_size", pixel_size_of: "image", label: "Pixel size"]
+        def field = fx { dlg.controls["pixel_size"] }
+        def fieldText = { fx { field.text } }
+        def link = { fx { dlg.links["pixel_size"] } }
+        def imageBox = fx { dlg.imageBoxes["image"] }
+        def chooseImage = { String prefix -> fx { imageBox.value = imageBox.items.find { it.startsWith(prefix) }; null } }
+        def chooseFile = { String path -> fx { imageBox.value = LcDialog.FILE_CHOICE; dlg.fileFields["image"].text = path; null } }
+        // what the host would send: the values of the form and the request built from them (null values: the run is blocked, the status says why)
+        def requestOf = {
+            def values = fx { dlg.readFormValues() }
+            if (values == null) return [values: null, status: status(dlg), inputs: null]
+            fx { dlg.imageChoiceAtRun = dlg.imageBoxes.collectEntries { k, b -> [(k): b.value as String] } }
+            def tmp = java.nio.file.Files.createTempDirectory("lccal_").toFile()
+            def inputs = dlg.prepareInputs(values, dlg.currentTool.inputs, tmp, "frame", "pixel")
+            tmp.deleteDir()
+            return [values: values, status: status(dlg), inputs: inputs]
+        }
+        def xyOf = { Map req, String axis -> req.inputs?._calibration?.pixel_size?.axes?.get(axis) }
+
+        // ---- CAL-01..20 as file inputs: field, request and `_calibration`
+        cases.each { id, list ->
+            list.each { c ->
+                chooseFile(c.file); Thread.sleep(50)
+                def afterFill = status(dlg)
+                def req = requestOf()
+                def name = id + "_" + c.label
+                def shown = fieldText()
+                if (c.expected == "unknown") {
+                    boolean ok = req.values == null && req.status == REQUIRED("pixel_size", "image") && shown == "" && link().value == null && fx { field.tooltip.text } == TOOLTIP("image")
+                    if (c.warning) ok &= afterFill.contains(c.warning)
+                    expect(name + "_is_unknown_and_the_run_is_blocked", ok, [req.status, shown, afterFill])
+                } else {
+                    def want = c.expected as double
+                    def x = xyOf(req, "x"), y = xyOf(req, "y")
+                    boolean ok = req.values != null && near(req.values.pixel_size as double, want) && x != null && y != null && x.unit == "um" && y.unit == "um" && x.source == "file" && y.source == "file" &&
+                            req.inputs._calibration.pixel_size.of == "image" && req.inputs._calibration.pixel_size.source == "file" && shown != "" && near(Double.parseDouble(shown), want)
+                    expect(name + "_gives_" + c.expected, ok, [req.values, req.inputs?._calibration, shown])
+                }
+            }
+        }
+        // per axis: the request keeps both axes while the field takes their mean (CAL-18) and the raw text of the file
+        chooseFile(cases["CAL-18"][0].file); def req18 = requestOf()
+        expect("CAL-18_axes_are_kept_per_axis_with_their_raw_text", near(xyOf(req18, "x").value as double, 0.5004) && near(xyOf(req18, "y").value as double, 0.5) && xyOf(req18, "x").raw == [scale: 0.5004d, unit: "um"], req18.inputs?._calibration)
+        chooseFile(cases["CAL-15"][0].file); def req15 = requestOf()
+        expect("CAL-15_the_raw_unit_text_is_kept_in_the_request", xyOf(req15, "x").raw.unit == "µm" && near(xyOf(req15, "x").raw.scale as double, 0.5), req15.inputs?._calibration)
+
+        // ---- CAL-09 QuPath's PixelCalibration (hasPixelSizeMicrons true with 1.0 / false) on the image open in QuPath
+        def cal09 = calCase("CAL-09")
+        chooseImage("Current image")
+        def server = fx { qupath.imageData.server }
+        def originalMetadata = fx { server.originalMetadata }
+        def setCalibration = { Double w, Double h ->
+            fx {
+                def b = new qupath.lib.images.servers.ImageServerMetadata.Builder(originalMetadata)
+                b.pixelSizeMicrons(w, h)       // null, null: a server that says nothing about the pixel size (hasPixelSizeMicrons() false)
+                server.setMetadata(b.build())
+                dlg.fillPixelSize(p)
+                null
+            }
+        }
+        setCalibration(1.0d, 1.0d)
+        def r09a = requestOf()
+        expect("CAL-09_hasPixelSizeMicrons_true_gives_1_0", fx { server.pixelCalibration.hasPixelSizeMicrons() } && r09a.values != null && near(r09a.values.pixel_size as double, 1.0d) && xyOf(r09a, "x").source == "image" && xyOf(r09a, "x").raw.unit == "µm", [r09a.values, r09a.inputs?._calibration])
+        fx { server.setMetadata(originalMetadata); null }
+        setCalibration(null, null)
+        def r09b = requestOf()
+        expect("CAL-09_hasPixelSizeMicrons_false_is_unknown", fx { !server.pixelCalibration.hasPixelSizeMicrons() } && r09b.values == null && r09b.status == REQUIRED("pixel_size", "image") && fieldText() == "", [r09b.status, fieldText()])
+        // a calibration entered in QuPath beats the TIFF rules: the file says 72 dpi (unknown), the person's entry is explicit
+        setCalibration(0.4d, 0.4d)
+        def r09c = requestOf()
+        expect("CAL-09_a_calibration_entered_in_QuPath_is_explicit", r09c.values != null && near(r09c.values.pixel_size as double, 0.4d), [r09c.values, r09c.status])
+        fx { server.setMetadata(originalMetadata); dlg.fillPixelSize(p); null }
+        def r09d = requestOf()
+        expect("CAL-09_back_to_the_files_own_calibration", r09d.values != null && near(r09d.values.pixel_size as double, 0.25d), [r09d.values, r09d.status])
+        // a plain TIFF with a 72 dpi tag: QuPath's own reader says 352.78 um, the host says unknown (CAL-11 for a project image)
+        def dpiFile = cases["CAL-11"][0].file
+        def dpiServer = qupath.lib.images.servers.ImageServers.buildServer(dpiFile)
+        println "PREMISE QuPath's own calibration of the 72 dpi TIFF: " + dpiServer.pixelCalibration.pixelWidthMicrons + " um (hasPixelSizeMicrons " + dpiServer.pixelCalibration.hasPixelSizeMicrons() + ")"
+        fx {
+            def e = qupath.project.addImage(dpiServer.getBuilder()); e.setImageName("dpi72"); qupath.project.syncChanges(); null
+        }
+        pick(dlg, "frame", "Pixel size required"); fx { dlg.onTool() }; Thread.sleep(800)
+        imageBox = fx { dlg.imageBoxes["image"] }; field = fx { dlg.controls["pixel_size"] }
+        chooseImage("Project: dpi72")
+        def r72 = requestOf()
+        expect("CAL-11_a_72_dpi_project_image_is_unknown_though_QuPath_says_a_size", dpiServer.pixelCalibration.hasPixelSizeMicrons() && r72.values == null && r72.status == REQUIRED("pixel_size", "image") && fieldText() == "", [r72.status, fieldText(), dpiServer.pixelCalibration.pixelWidthMicrons])
+        dpiServer.close()
+
+        // ---- CAL-01, 03, 05 also as project images (source image): the same answer, the source is the image
+        chooseImage("Project: A"); def rA = requestOf()
+        expect("CAL-source_a_project_image_says_source_image", rA.values != null && near(rA.values.pixel_size as double, 0.25d) && xyOf(rA, "x").source == "image" && rA.inputs._calibration.pixel_size.source == "image", rA.inputs?._calibration)
+
+        // ---- transitions (each asserts the field and the request)
+        def typeText = { String text ->
+            fx { field.requestFocus(); field.selectAll(); null }
+            text.each { ch -> fx { javafx.event.Event.fireEvent(field, new KeyEvent(KeyEvent.KEY_TYPED, ch.toString(), ch.toString(), KeyCode.UNDEFINED, false, false, false, false)); null } }
+            Thread.sleep(150)
+        }
+        def clearByHand = { fx { field.requestFocus(); field.selectAll(); field.deleteText(0, field.text.length()); null }; Thread.sleep(150) }
+        def reset = { fx { dlg.onTool(); null }; Thread.sleep(800); imageBox = fx { dlg.imageBoxes["image"] }; field = fx { dlg.controls["pixel_size"] } }
+        def sourceOf = { Map req -> req.inputs?._calibration?.pixel_size?.source }
+        // T1
+        reset(); openImage("A"); reset()
+        chooseImage("Project: A"); def t1a = requestOf()
+        chooseImage("Project: B"); def t1b = requestOf()
+        expect("CAL-T1_A_to_B_field_request_source", t1a.values != null && near(t1a.values.pixel_size as double, 0.25d) && fieldText() == "0.5" && t1b.values != null && near(t1b.values.pixel_size as double, 0.5d) && sourceOf(t1b) == "image" && near(xyOf(t1b, "x").value as double, 0.5d), [t1a.values, t1b.values, fieldText()])
+        // T2
+        chooseImage("Project: A"); chooseImage("Project: U"); def t2 = requestOf()
+        expect("CAL-T2_uncalibrated_B_empties_the_field_and_blocks_the_run", fieldText() == "" && t2.values == null && t2.status == REQUIRED("pixel_size", "image") && fx { field.tooltip.text } == TOOLTIP("image"), [fieldText(), t2.status])
+        // T2, Optional: the request has null, A's value is in no request
+        def runTool = { String tool -> pick(dlg, "frame", tool); fx { dlg.onTool() }; Thread.sleep(800); imageBox = fx { dlg.imageBoxes["image"] }; field = fx { dlg.controls["pixel_size"] } }
+        runTool("Pixel size optional")
+        chooseImage("Project: A"); chooseImage("Project: U")
+        def t2o = requestOf()
+        expect("CAL-T2_optional_sends_null_and_no_calibration", t2o.values != null && t2o.inputs.containsKey("pixel_size") && t2o.inputs.pixel_size == null && !t2o.inputs.containsKey("_calibration") && fieldText() == "", [t2o.values, t2o.inputs])
+        run(dlg)
+        def recordOf = { def runs = new File(LcRegistry.home(), "runs").listFiles().findAll { it.isDirectory() }.sort { it.name }; LcJson.parse(new File(runs.last(), "run.json")) }
+        def seenOf = { def report = (dlg.lastReport as String).split("\n\nworker output:")[0]; LcJson.parseText(report).outputs?.results?.find { it.type == "values" }?.values }
+        expect("CAL-T2_optional_run_reaches_the_tool_with_none", seenOf()?.pixel_size == null && seenOf()?.image_shape != null && !recordOf().inputs.containsKey("_calibration"), seenOf())
+        // T1 as a real run: the tool receives 0.5 and the run record keeps `_calibration`
+        runTool("Pixel size required")
+        chooseImage("Project: B"); run(dlg)
+        def rec = recordOf()
+        expect("CAL-T1_real_run_the_tool_got_0_5_and_the_record_has_the_calibration", near(seenOf().pixel_size as double, 0.5d) && rec.inputs.pixel_size == 0.5d && rec.inputs._calibration.pixel_size.axes.x.value == 0.5d && rec.inputs._calibration.pixel_size.axes.x.unit == "um" && rec.inputs._calibration.pixel_size.of == "image", rec.inputs)
+        // T3: A, the person types 0.3, switch to B -> 0.3, source user
+        reset(); chooseImage("Project: A"); typeText("0.3")
+        expect("CAL-T3_typed_text_shows", fieldText() == "0.3" && link().state == LcLink.USER, [fieldText(), link().state])
+        chooseImage("Project: B"); def t3 = requestOf()
+        expect("CAL-T3_a_typed_value_survives_a_source_change", t3.values != null && near(t3.values.pixel_size as double, 0.3d) && sourceOf(t3) == "user" && xyOf(t3, "x").source == "user" && xyOf(t3, "y").source == "user" && fx { field.tooltip.text }.contains("entered by you"), [t3.values, t3.inputs?._calibration])
+        // T4: user(0.3), the person clears the field, source B -> auto 0.5
+        clearByHand()
+        expect("CAL-T4_an_empty_field_is_unset", link().state == LcLink.UNSET, link().state)
+        chooseImage("Project: A"); chooseImage("Project: B"); def t4 = requestOf()
+        expect("CAL-T4_cleared_then_source_B_is_auto_0_5", link().state == LcLink.AUTO && t4.values != null && near(t4.values.pixel_size as double, 0.5d) && sourceOf(t4) == "image", [link().state, t4.values])
+        // ... the button does the same for a typed value
+        typeText("0.7"); fx { dlg.wrappers["pixel_size"].children[1].fire(); null }; def t4b = requestOf()
+        expect("CAL-T4_the_button_asks_for_the_image_calibration_again", link().state == LcLink.AUTO && t4b.values != null && near(t4b.values.pixel_size as double, 0.5d), [link().state, t4b.values])
+        // T5 / T6: open image A, a file B that is uncalibrated -> unset, run blocked; file cleared -> auto 0.25 (A)
+        reset(); chooseImage("Current image"); def t5a = requestOf()
+        chooseFile(U); def t5 = requestOf()
+        expect("CAL-T5_open_image_A_then_an_uncalibrated_file_is_unset_and_blocked", t5a.values != null && near(t5a.values.pixel_size as double, 0.25d) && fieldText() == "" && t5.values == null && t5.status == REQUIRED("pixel_size", "image"), [t5a.values, fieldText(), t5.status])
+        chooseImage("Current image"); def t6 = requestOf()
+        expect("CAL-T6_file_cleared_gives_A_again", link().state == LcLink.AUTO && t6.values != null && near(t6.values.pixel_size as double, 0.25d) && sourceOf(t6) == "image", [link().state, t6.values])
+        // a file input with a calibration wins over the open image
+        chooseFile(B); def t6b = requestOf()
+        expect("CAL-T5_a_calibrated_file_wins_over_the_open_image", near(t6b.values.pixel_size as double, 0.5d) && sourceOf(t6b) == "file", [t6b.values, t6b.inputs?._calibration])
+        // T7 (QuPath): project image A -> a file image that is uncalibrated -> unset
+        reset(); chooseImage("Project: A"); def t7a = requestOf(); chooseFile(U2); def t7 = requestOf()
+        expect("CAL-T7_project_image_then_an_uncalibrated_file_is_unset", t7a.values != null && link().state == LcLink.UNSET && fieldText() == "" && t7.values == null, [t7a.values, link().state, fieldText()])
+        // T8: a required linked field with a declared default 1.0, source unknown: blocked, the default is not sent
+        reset(); chooseImage("Project: U"); def t8 = requestOf()
+        expect("CAL-T8_default_1_0_is_not_a_stand_in", fx { dlg.currentTool.inputs.find { it.name == "pixel_size" }.default } == 1.0d && t8.values == null && t8.status == REQUIRED("pixel_size", "image") && fieldText() == "", [t8.status, fieldText()])
+        // ... also at the first form of a tool (nothing was chosen yet but an uncalibrated image)
+        // T9: user types 0.25 equal to the last auto value, then switch to the uncalibrated B -> stays 0.25, source user
+        reset(); chooseImage("Project: A")
+        def lastAuto = fieldText()
+        typeText("0.25"); def sameAsAuto = fieldText()
+        chooseImage("Project: U"); def t9 = requestOf()
+        expect("CAL-T9_typing_the_value_the_box_shows_is_still_the_persons", lastAuto == "0.25" && sameAsAuto == "0.25" && link().state == LcLink.USER && t9.values != null && near(t9.values.pixel_size as double, 0.25d) && sourceOf(t9) == "user", [lastAuto, sameAsAuto, link().state, t9.values])
+        // ... and the same text typed over itself, key by key, with no change of the text in between (a paste of the same text): the key event alone is an edit
+        reset(); chooseImage("Project: A")
+        fx { field.requestFocus(); javafx.event.Event.fireEvent(field, new KeyEvent(KeyEvent.KEY_TYPED, "x", "x", KeyCode.UNDEFINED, false, false, false, false)); null }; Thread.sleep(150)
+        expect("CAL-T9_a_key_event_that_leaves_the_text_alone_still_counts_as_an_edit", link().state == LcLink.USER, [link().state, fieldText()])
+        // a host write is never the person's: setters, the programmatic write, a source change keep the field automatic
+        reset(); chooseImage("Project: A"); fx { dlg.setters["pixel_size"](0.9d); null }
+        expect("programmatic_set_does_not_make_the_value_the_persons", link().state == LcLink.AUTO && fieldText() == "0.9", [link().state, fieldText()])
+        chooseImage("Project: B")
+        expect("programmatic_value_follows_the_next_source", fieldText() == "0.5" && link().state == LcLink.AUTO, [fieldText(), link().state])
+        // text that is not a number, zero and negative numbers are refused by name
+        typeText("abc"); def bad1 = requestOf()
+        expect("a_text_that_is_not_a_number_is_refused_by_name", bad1.values == null && bad1.status == "'" + fx { dlg.currentTool.inputs.find { it.name == "pixel_size" }.label } + "': 'abc' is not a number", bad1.status)
+        typeText("0"); def bad2 = requestOf()
+        expect("zero_is_refused", bad2.values == null && bad2.status.contains("must be greater than 0"), bad2.status)
+        typeText("-0.5"); def bad3 = requestOf()
+        expect("a_negative_value_is_refused", bad3.values == null && bad3.status.contains("must be greater than 0"), bad3.status)
+        typeText("NaN"); def bad4 = requestOf()
+        expect("not_finite_is_refused", bad4.values == null, bad4.status)
+        // ClearAfterRun and the declared default never stand in: after a reset the field is the image's
+        reset(); chooseImage("Project: A")
+        expect("the_form_starts_from_the_image_not_the_declared_default", fieldText() == "0.25" && link().state == LcLink.AUTO, [fieldText(), link().state])
+        // a calibration edited in QuPath between choosing the image and pressing Run is read again at the click (not the person's own value)
+        openImage("A"); reset(); chooseImage("Current image")
+        def srv = fx { qupath.imageData.server }; def orig = fx { srv.originalMetadata }
+        fx { srv.setMetadata(new qupath.lib.images.servers.ImageServerMetadata.Builder(orig).pixelSizeMicrons(0.8d, 0.8d).build()); null }
+        fx { dlg.refreshLinks(); null }
+        def rEdit = requestOf()
+        expect("a_calibration_edited_in_QuPath_is_read_again_before_the_run", rEdit.values != null && near(rEdit.values.pixel_size as double, 0.8d), [rEdit.values, fieldText()])
+        fx { srv.setMetadata(orig); null }
+
+        // ---- the catalog and the unit rules at the conversion level (the same function the files and servers go through)
+        expect("unit_catalog_is_loaded_from_the_conformance_file_not_from_this_script", LcUnits.conformance().is(null) == false && LcUnits.calibrationData().length_units.keySet() == CAL.length_units.keySet(), "")
+        expect("symbols_are_exact_text", LcUnits.unitFactor("um")[0] == 1.0d && LcUnits.unitFactor("UM")[0] == null && LcUnits.unitFactor(" um")[0] == null && LcUnits.unitFactor("mms")[0] == null, "")
+        expect("words_ignore_case_and_surrounding_blanks", LcUnits.unitFactor(" MILLIMETER ")[0] == 1000.0d && LcUnits.unitFactor("micro meter")[0] == null, "")
+        expect("calibrate_never_assumes_um", LcCal.calibrate(1.0, "pixel", 1.0, "pixel").known == false && LcCal.calibrate(0.25, null, 0.25, null).known == false && LcCal.calibrate(1.0, "um", 1.0, "um").known, "")
+        expect("tolerance_is_relative_to_the_larger", LcCal.calibrate(0.5, "um", 0.5004, "um").square && !LcCal.calibrate(0.5, "um", 0.5006, "um").square, "")
+        // without a catalog nothing is converted by a list of this script: every calibration is unknown, with the sentence that says why
+        if (System.getenv("LC_CONFORMANCE") == null) {
+            def appEntries = dlg.apps.values().collect { it.entry }
+            LcUnits.useApps([]); LcUnits.reset()
+            def none = LcCal.calibrate(1.0, "um", 1.0, "um")
+            LcUnits.useApps(appEntries); LcUnits.reset()
+            expect("a_missing_catalog_is_never_replaced_by_a_guess", !none.known && none.warning == LcUnits.NO_CATALOG_TEXT && LcCal.calibrate(1.0, "um", 1.0, "um").known, [none.warning])
+        } else println "NOT_APPLICABLE a_missing_catalog_is_never_replaced_by_a_guess: LC_CONFORMANCE is set"
+    } catch (Throwable t) { t.printStackTrace(); results["EXCEPTION"] = false }
+    finally { println "RESULTS " + results; Thread.sleep(500); System.exit(results && results.every { it.value } ? 0 : 1) }
+}
diff --git a/tests/gui_test_parity_pixel_body.groovy b/tests/gui_test_parity_pixel_body.groovy
index c402261..7f5f0b4 100644
--- a/tests/gui_test_parity_pixel_body.groovy
+++ b/tests/gui_test_parity_pixel_body.groovy
@@ -1,4 +1,6 @@
 // ================================================================== GUI test body: pixel size (QP-8) (appended to the tool script by tests/run_gui_test.sh)
+// Updated for SPEC_WRONG_SCIENCE section 2 (calibration): the field is unset/auto/user (a flag set by the person's edits), an unknown source clears it, a declared default is
+// never a stand-in, pixels that are not square are unknown with a warning; the full CAL-01..20 / CAL-T1..T9 cases are in gui_test_calibration_body.groovy.
 // Needs no real app: it registers a synthetic app (only its schema is used) in the scratch LC_HOME (a folder named lhome_pixel); the registered `interactions` app (LC_SHARED_HOME) gives the Python that writes the test images (tifffile).
 import javafx.embed.swing.SwingFXUtils
 import javax.imageio.ImageIO
@@ -81,9 +83,17 @@ Thread.start("lc-gui-test") {
         def broken = FXD + "/px_broken.tif"; new File(broken).text = "this is text, not a TIFF"
         pick(dlg, "pixelapp", "Relocalize 2D"); Thread.sleep(1500)
         def refPixel = { fx { dlg.getters["reference_pixel_size_um"]() } }
+        def refField = { fx { dlg.controls["reference_pixel_size_um"] } }
+        // the person types: select all, then one key event per character (a host write through the setters is not an edit)
+        def typeInto = { String name, String text ->
+            def f = fx { dlg.controls[name] }
+            fx { f.requestFocus(); f.selectAll(); null }
+            text.each { ch -> fx { javafx.event.Event.fireEvent(f, new javafx.scene.input.KeyEvent(javafx.scene.input.KeyEvent.KEY_TYPED, ch.toString(), ch.toString(), javafx.scene.input.KeyCode.UNDEFINED, false, false, false, false)); null } }
+            Thread.sleep(150)
+        }
         def refFile = { String path -> fx { dlg.imageBoxes["reference"].value = LcDialog.FILE_CHOICE; dlg.fileFields["reference"].text = path } }
         def px = [name: "reference_pixel_size_um", pixel_size_of: "reference", label: "Reference pixel size"]
-        expect("pixel_field_starts_at_its_default", refPixel() == 0.65d, refPixel())
+        expect("pixel_field_starts_unset_not_at_its_declared_default", refPixel() == null && dlg.links["reference_pixel_size_um"].state == "unset", refPixel())      // was: starts at its default 0.65 (CAL-T8: a default is no stand-in)
         refFile(um05)
         expect("typed_file_header_fills_the_field", Math.abs(refPixel() - 0.5d) < 1e-6, refPixel())
         refFile(um025)
@@ -91,16 +101,16 @@ Thread.start("lc-gui-test") {
         refFile(cm)
         expect("a_centimetre_tiff_unit_is_read", Math.abs(refPixel() - 1.0d) < 1e-6, refPixel())
         refFile(plain)
-        expect("a_file_without_calibration_leaves_the_value", Math.abs(refPixel() - 1.0d) < 1e-6, refPixel())
+        expect("a_file_without_calibration_clears_the_field", refPixel() == null && refField().text == "", [refPixel(), refField().text])      // was: leaves the value (the value of another image must not stay, CAL-T5)
         // an edited value is kept when the image changes
-        fx { dlg.setters["reference_pixel_size_um"](0.9d) }
+        typeInto("reference_pixel_size_um", "0.9")
         refFile(um05)
         expect("typed_value_is_not_overwritten_by_another_file", refPixel() == 0.9d, refPixel())
         fx { dlg.fillPixelSize(px) }
         expect("typed_value_is_not_overwritten_by_a_refill", refPixel() == 0.9d, refPixel())
-        // the query field is independent
+        // the query field is independent: nothing was chosen for it, so it is unset (its declared default 0.325 is no stand-in)
         def queryBefore = fx { dlg.getters["query_pixel_size_um"]() }
-        expect("the_other_pixel_field_was_not_touched", queryBefore == 0.325d, queryBefore)
+        expect("the_other_pixel_field_was_not_touched", queryBefore == null, queryBefore)
         // a field never edited follows again after the tool is chosen anew
         pick(dlg, "pixelapp", "Relocalize 2D")
         fx { dlg.onTool() }; Thread.sleep(500)
@@ -110,15 +120,13 @@ Thread.start("lc-gui-test") {
         refFile(aniso)
         def st = status(dlg)
         println "STATUS_ANISO " + st
-        expect("anisotropic_pixels_are_said", st.contains("pixel size differs: Y 0.25 µm, X 0.5 µm - the tool takes one value and gets X"), st)
-        expect("anisotropic_pixels_send_x", Math.abs(refPixel() - 0.5d) < 1e-6, refPixel())
+        expect("anisotropic_pixels_are_said", st.contains("pixels are not square"), st)      // was: "pixel size differs: Y 0.25 µm, X 0.5 µm - the tool takes one value and gets X"
+        expect("anisotropic_pixels_leave_the_field_unset", refPixel() == null, refPixel())      // was: the field gets X (CAL-06: never filled from one axis)
         refFile(um05)
-        expect("square_pixels_say_nothing", !status(dlg).contains("pixel size differs") || status(dlg) == st, status(dlg))
-        // a file that cannot be read: said, the field keeps its value
-        fx { dlg.setters["reference_pixel_size_um"](0.5d) }
-        fx { dlg.autoPixel["reference_pixel_size_um"] = 0.5d }
+        expect("square_pixels_say_nothing", !status(dlg).contains("pixels are not square") || status(dlg) == st, status(dlg))
+        // a file that cannot be read: said, the field is unset (the value of another source must not stay)
         refFile(broken)
-        expect("unreadable_file_is_said_and_value_kept", status(dlg).startsWith("could not read the pixel size from " + broken) && status(dlg).endsWith("): type it") && refPixel() == 0.5d, status(dlg))
+        expect("unreadable_file_is_said_and_the_field_is_unset", status(dlg).startsWith("could not read the pixel size from " + broken) && status(dlg).endsWith("): type it") && refPixel() == null, status(dlg))      // was: "... and value kept"
         expect("unreadable_file_is_logged", LcLog.recent.any { it.contains("pixel size of 'File...' could not be read") }, LcLog.recent)
         // a path still being typed (no such file yet) says nothing
         fx { dlg.status.text = "idle" }
diff --git a/tests/run_gui_ci.sh b/tests/run_gui_ci.sh
index 03c683f..eaaa8be 100755
--- a/tests/run_gui_ci.sh
+++ b/tests/run_gui_ci.sh
@@ -17,7 +17,9 @@ declare -A needs=(
   [gui_test_adversarial_body.groovy]="adv"
   [gui_test_playground_body.groovy]="LabConstrictorPlayground"
   [gui_test_frame_body.groovy]="frame"
+  [gui_test_calibration_body.groovy]="frame"
   [gui_test_frame_body.groovy]="frame"
+  [gui_test_calibration_body.groovy]="frame"
 )
 for b in area buttons channel copy fallbacks interactions region shapes widgets; do needs[gui_test_${b}_body.groovy]="interactions"; done
 for b in parity_form parity_host parity_lifecycle parity_messages parity_pixel parity_results parity_support parity_quote; do needs[gui_test_${b}_body.groovy]="interactions"; done

From 61617752e8a2feafb1d5f209f85ab78fdea89639 Mon Sep 17 00:00:00 2001
From: Guillaume Jacquemet <guillaume.jacquemet@abo.fi>
Date: Tue, 13 Oct 2026 15:21:16 +0000
Subject: [PATCH 2/2] Calibration tests: BigTIFF and big-endian headers, the
 field state machine on its own, the run re-reads an edited calibration

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y2SN8SuEakTdiWy3F2WUqN
---
 tests/calibration_fixtures.py          |  5 ++--
 tests/gui_test_calibration_body.groovy | 35 ++++++++++++++++++++++----
 2 files changed, 33 insertions(+), 7 deletions(-)

diff --git a/tests/calibration_fixtures.py b/tests/calibration_fixtures.py
index adb402f..f4903fc 100644
--- a/tests/calibration_fixtures.py
+++ b/tests/calibration_fixtures.py
@@ -1,6 +1,6 @@
 """Writes the images of the calibration tests (tests/gui_test_calibration_body.groovy) from a JSON list: python tests/calibration_fixtures.py spec.json
 Each entry: {"file": path, "kind": "ome" | "imagej" | "tags" | "plain", ...}. `ome`: sx, ux, sy, uy (PhysicalSize and its unit text, kept exactly);
-`imagej`: unit, resolution; `tags`: resolution (pixels per resolution unit, x then y), resolutionunit (INCH, CENTIMETER, NONE); `plain`: nothing."""
+`imagej`: unit, resolution; `tags`: resolution (pixels per resolution unit, x then y), resolutionunit (INCH, CENTIMETER, NONE), optional bigtiff / byteorder; `plain`: nothing."""
 import json
 import sys
 
@@ -20,7 +20,8 @@ def main(spec_path: str) -> None:
         elif kind == "imagej":
             tifffile.imwrite(item["file"], image, imagej=True, resolution=tuple(item["resolution"]), metadata={"unit": item["unit"]})
         elif kind == "tags":
-            tifffile.imwrite(item["file"], image, resolution=tuple(item["resolution"]), resolutionunit=item["resolutionunit"])
+            extra = {k: item[k] for k in ("bigtiff", "byteorder") if k in item}  # BigTIFF and big-endian files: the header reader of the host must handle them
+            tifffile.imwrite(item["file"], image, resolution=tuple(item["resolution"]), resolutionunit=item["resolutionunit"], **extra)
         else:
             tifffile.imwrite(item["file"], image)
 
diff --git a/tests/gui_test_calibration_body.groovy b/tests/gui_test_calibration_body.groovy
index 4f87840..e6f5df1 100644
--- a/tests/gui_test_calibration_body.groovy
+++ b/tests/gui_test_calibration_body.groovy
@@ -87,6 +87,11 @@ Thread.start("lc-gui-test") {
         add("CAL-14", "CENTIMETER 10000 per cm", spec([kind: "tags", resolution: [10000, 10000], resolutionunit: "CENTIMETER"]), 1.0)
         add("CAL-11", "INCH 72.2 dpi (within 0.5 %)", spec([kind: "tags", resolution: [72.2, 72.2], resolutionunit: "INCH"]), "unknown")
         add("CAL-14", "INCH 73 dpi (outside 0.5 %)", spec([kind: "tags", resolution: [73, 73], resolutionunit: "INCH"]), 25400.0 / 73)
+        // the same tags in a BigTIFF and in a big-endian TIFF: the header reader handles both
+        add("CAL-14", "BigTIFF INCH 25400 dpi", spec([kind: "tags", resolution: [25400, 25400], resolutionunit: "INCH", bigtiff: true]), 1.0)
+        add("CAL-11", "BigTIFF INCH 72 dpi", spec([kind: "tags", resolution: [72, 72], resolutionunit: "INCH", bigtiff: true]), "unknown")
+        add("CAL-14", "big-endian CENTIMETER 10000 per cm", spec([kind: "tags", resolution: [10000, 10000], resolutionunit: "CENTIMETER", byteorder: ">"]), 1.0)
+        add("CAL-12", "big-endian INCH 96 dpi", spec([kind: "tags", resolution: [96, 96], resolutionunit: "INCH", byteorder: ">"]), "unknown")
         calCase("CAL-15").input.variants.each { v -> add("CAL-15", "unit " + v.unit, ome(v.scale, v.unit, v.scale, v.unit), 0.5) }
         add("CAL-16", "damaged micro sign", ome(0.5, "�m", 0.5, "�m"), "unknown", DAMAGED("�m"))
         calCase("CAL-17").input.variants.each { v -> add("CAL-17", "unit " + v.unit, ome(v.scale, v.unit, v.scale, v.unit), 0.0001) }
@@ -299,15 +304,35 @@ Thread.start("lc-gui-test") {
         // ClearAfterRun and the declared default never stand in: after a reset the field is the image's
         reset(); chooseImage("Project: A")
         expect("the_form_starts_from_the_image_not_the_declared_default", fieldText() == "0.25" && link().state == LcLink.AUTO, [fieldText(), link().state])
-        // a calibration edited in QuPath between choosing the image and pressing Run is read again at the click (not the person's own value)
-        openImage("A"); reset(); chooseImage("Current image")
+        // a calibration edited in QuPath between choosing the image and pressing Run is read again at the click (a real run; the box is not the person's own value)
+        openImage("A"); runTool("Pixel size required"); chooseImage("Current image")
         def srv = fx { qupath.imageData.server }; def orig = fx { srv.originalMetadata }
+        def stale = fieldText()
         fx { srv.setMetadata(new qupath.lib.images.servers.ImageServerMetadata.Builder(orig).pixelSizeMicrons(0.8d, 0.8d).build()); null }
-        fx { dlg.refreshLinks(); null }
-        def rEdit = requestOf()
-        expect("a_calibration_edited_in_QuPath_is_read_again_before_the_run", rEdit.values != null && near(rEdit.values.pixel_size as double, 0.8d), [rEdit.values, fieldText()])
+        run(dlg)
+        def recEdit = recordOf()
+        expect("a_calibration_edited_in_QuPath_is_read_again_by_the_run", stale == "0.25" && near(seenOf().pixel_size as double, 0.8d) && recEdit.inputs._calibration.pixel_size.axes.x.value == 0.8d && fieldText() == "0.8", [stale, seenOf(), fieldText()])
         fx { srv.setMetadata(orig); null }
 
+        // ---- the field state machine on its own (SPEC 2.2): a flag set by edit events, never inferred by comparing values
+        def calA = LcCal.calibrate(0.25d, "um", 0.25d, "um"), calB = LcCal.calibrate(0.5d, "um", 0.5d, "um"), calNone = LcCal.calibrate(1.0d, "pixel", 1.0d, "pixel")
+        def lk = new LcLink("pixel_size", "image")
+        lk.sourceChanged(calA, "image")
+        expect("state_auto_follows_the_source", lk.state == LcLink.AUTO && lk.value == 0.25d && lk.origin == "image", [lk.state, lk.value])
+        lk.userEdit(0.25d)
+        expect("state_user_even_when_the_value_equals_the_auto_value", lk.state == LcLink.USER && lk.origin == "user", lk.state)
+        expect("state_user_survives_a_source_change", lk.sourceChanged(calB, "image") == false && lk.state == LcLink.USER && lk.value == 0.25d && lk.sourceChanged(calNone, "image") == false && lk.value == 0.25d, [lk.state, lk.value])
+        lk.userEdit(null)
+        expect("state_cleared_is_unset_until_the_source_is_read_again", lk.state == LcLink.UNSET && lk.value == null && lk.sourceChanged(calB, "file") && lk.state == LcLink.AUTO && lk.value == 0.5d && lk.origin == "file", [lk.state, lk.value])
+        lk.sourceChanged(calNone, "image")
+        expect("state_unknown_source_clears_the_value", lk.state == LcLink.UNSET && lk.value == null && lk.entry() == null, [lk.state, lk.value])
+        lk.sourceChanged(calA, "image")
+        def entry = lk.entry()
+        expect("calibration_entry_is_per_axis_with_provenance", entry == [of: "image", source: "image", axes: [x: [value: 0.25d, unit: "um", source: "image", raw: [scale: 0.25d, unit: "um"]], y: [value: 0.25d, unit: "um", source: "image", raw: [scale: 0.25d, unit: "um"]]]], entry)
+        lk.userEdit(0.3d)
+        expect("calibration_entry_of_a_typed_value_is_user_on_both_axes", lk.entry() == [of: "image", source: "user", axes: [x: [value: 0.3d, unit: "um", source: "user"], y: [value: 0.3d, unit: "um", source: "user"]]], lk.entry())
+        expect("calibration_entry_follows_the_conformance_request_shape", CAL.request_shape._calibration.pixel_size.axes.x.keySet() == (["value", "unit", "source", "raw"] as Set) && entry.axes.x.keySet() == CAL.request_shape._calibration.pixel_size.axes.x.keySet(), CAL.request_shape)
+
         // ---- the catalog and the unit rules at the conversion level (the same function the files and servers go through)
         expect("unit_catalog_is_loaded_from_the_conformance_file_not_from_this_script", LcUnits.conformance().is(null) == false && LcUnits.calibrationData().length_units.keySet() == CAL.length_units.keySet(), "")
         expect("symbols_are_exact_text", LcUnits.unitFactor("um")[0] == 1.0d && LcUnits.unitFactor("UM")[0] == null && LcUnits.unitFactor(" um")[0] == null && LcUnits.unitFactor("mms")[0] == null, "")