@fideus-labs/ngff-zarr 0.17.0 → 0.19.0

package/esm/utils/structural_validation.d.ts

@@ -0,0 +1,379 @@
+/**
+ * Structural validation for OME-Zarr v0.4 image/multiscales metadata.
+ *
+ * Where the Zod schema validation in {@link validateMetadata} answers "is this
+ * shaped like OME-Zarr?", the rules in this module answer "does this obey the
+ * specification's structural invariants?" -- axis counts, axis ordering,
+ * coordinate-transformation arity, finest-to-coarsest dataset ordering, and
+ * OMERO channel color format. These are spec MUSTs that a JSON Schema cannot
+ * express.
+ *
+ * Each rule is identified by a stable, kebab-case {@link SpecRule} value that is
+ * part of the observable surface: the identifiers, their evaluation order, and
+ * the dotted-segment location strings are kept byte-for-byte identical to the
+ * package's Python implementation so the two stay in lockstep (a property the
+ * cross-language parity tests assert). Rules fail fast -- the orchestrator
+ * throws a {@link ValidationError} on the first violation, in canonical
+ * specification order.
+ *
+ * This module provides the image/multiscales rule surface -- including the
+ * RFC 4 anatomical-orientation checks -- plus the HCS plate/well rules, which
+ * operate on separate metadata objects and are dispatched by the companion
+ * {@link validatePlate} and {@link validateWell} entry points.
+ */
+import { type Metadata } from "../types/zarr_metadata.js";
+import type { PlateMetadata, WellMetadata } from "../types/hcs.js";
+/**
+ * Stable, kebab-case identifiers for the structural specification rules.
+ *
+ * The string values are the observable surface -- they appear in
+ * {@link ValidationError.rule}, logs, and tests -- and must match the package's
+ * Python implementation exactly. Members are listed in canonical
+ * specification-MUST evaluation order.
+ */
+export declare const SpecRule: {
+    /** Axis count within the v0.4 range of 2..5 inclusive. */
+    readonly AxisCount: "axis-count";
+    /** At most one `time` axis and at most one `channel` axis. */
+    readonly AxisType: "axis-type";
+    /** time before channel before space; spatial names suffix (z, y, x). */
+    readonly AxisOrder: "axis-order";
+    /** Every scale/translation vector length equals the axis count. */
+    readonly ScaleLengthMismatch: "scale-length-mismatch";
+    /** Exactly one scale per dataset; a translation must follow it. */
+    readonly GlobalCoordTransformAfterPerLevel: "global-coord-transform-after-per-level";
+    /** Datasets ordered finest to coarsest; spatial scale must not shrink. */
+    readonly DatasetOrderHighestToLowest: "dataset-order-highest-to-lowest";
+    /** Each OMERO channel color is exactly six hexadecimal digits. */
+    readonly OmeroChannelColorFormat: "omero-channel-color-format";
+    /** All spatial-axis RFC 4 orientations share one `type`. */
+    readonly AxisOrientationConsistentType: "axis-orientation-consistent-type";
+    /** If any spatial axis declares an orientation, all spatial axes do. */
+    readonly AxisOrientationCompleteness: "axis-orientation-completeness";
+    /** Each well's rowIndex/columnIndex agrees with the row/column in its path. */
+    readonly PlateRowIndexConsistency: "plate-row-index-consistency";
+    /** Each well image references an acquisition when the plate declares many. */
+    readonly WellAcquisitionMissing: "well-acquisition-missing";
+};
+/** Union of the {@link SpecRule} string values. */
+export type SpecRule = (typeof SpecRule)[keyof typeof SpecRule];
+/**
+ * How much validation {@link validateStructural} performs.
+ *
+ * `"strict"` is the default and runs every structural image/multiscales rule.
+ * `"schema_only"` skips them -- schema validation is the separate concern of
+ * {@link validateMetadata}, which checks the raw attributes via Zod.
+ */
+export declare const ValidationLevel: {
+    /** Skip structural rules; rely on Zod schema validation only. */
+    readonly SchemaOnly: "schema_only";
+    /** Run every structural image/multiscales rule (the default). */
+    readonly Strict: "strict";
+};
+/** Union of the {@link ValidationLevel} string values. */
+export type ValidationLevel = (typeof ValidationLevel)[keyof typeof ValidationLevel];
+/**
+ * Options controlling structural validation.
+ */
+export interface ValidateOptions {
+    /**
+     * Validation level to run. Defaults to {@link ValidationLevel.Strict}
+     * (`"strict"`).
+     */
+    level?: ValidationLevel;
+    /**
+     * Whether unknown metadata fields are tolerated. Defaults to `true`,
+     * mirroring the parser, which warns on rather than rejects unknown fields.
+     */
+    allowUnknownFields?: boolean;
+}
+/**
+ * Raised when a structural specification rule is violated.
+ *
+ * Carries the offending {@link SpecRule} and an optional `location` identifying
+ * the offending metadata node in dotted-segment (JSON-Pointer-style) form, e.g.
+ * `multiscales[0].datasets[2].coordinateTransformations[0]`. The `message` is
+ * formatted as `Spec rule [<rule>] violated: <message>`.
+ */
+export declare class ValidationError extends Error {
+    /** The structural rule that was violated. */
+    readonly rule: SpecRule;
+    /** Dotted-segment location of the offending metadata node, if known. */
+    readonly location?: string;
+    constructor(rule: SpecRule, message: string, location?: string);
+}
+/**
+ * Validate that the axis count is within the v0.4-permitted range.
+ *
+ * OME-Zarr v0.4 requires between 2 and 5 axes, inclusive.
+ *
+ * @param metadata - The parsed multiscales metadata to validate.
+ * @throws {ValidationError} With {@link SpecRule.AxisCount} when
+ * `metadata.axes.length` lies outside `2..5`; location `multiscales[0].axes`.
+ */
+export declare function validateAxisCount(metadata: Metadata): void;
+/**
+ * Validate axis-type multiplicity.
+ *
+ * At most one `time` axis and at most one `channel` axis may be present.
+ *
+ * @param metadata - The parsed multiscales metadata to validate.
+ * @throws {ValidationError} With {@link SpecRule.AxisType} when more than one
+ * `time` axis or more than one `channel` axis is present; location
+ * `multiscales[0].axes`.
+ */
+export declare function validateAxisType(metadata: Metadata): void;
+/**
+ * Validate the class ordering of axes.
+ *
+ * Axes are ranked by type (`time` < `channel` < `space`) and must be listed in
+ * non-decreasing rank order: every `time` axis precedes every `channel` axis,
+ * which precedes every `space` axis. The first adjacent pair that inverts this
+ * ranking is reported. Pairs involving an axis type with no rank (e.g. `array`)
+ * are skipped.
+ *
+ * @param metadata - The parsed multiscales metadata to validate.
+ * @throws {ValidationError} With {@link SpecRule.AxisOrder} for the first
+ * adjacent pair where a lower-ranked axis type follows a higher-ranked one;
+ * location `multiscales[0].axes[i+1]`.
+ */
+export declare function validateAxisOrder(metadata: Metadata): void;
+/**
+ * Validate the count and names of spatial axes.
+ *
+ * The `space` axes, taken in order, must be the matching-length suffix of
+ * `(z, y, x)`: one spatial axis must be `(x)`, two must be `(y, x)`, and three
+ * must be `(z, y, x)`. At most three `space` axes are permitted.
+ *
+ * @param metadata - The parsed multiscales metadata to validate.
+ * @throws {ValidationError} With {@link SpecRule.AxisOrder} when there are more
+ * than three `space` axes, or when their names are not the expected suffix of
+ * `(z, y, x)`; location `multiscales[0].axes` or the first offending axis.
+ */
+export declare function validateSpatialAxisOrder(metadata: Metadata): void;
+/**
+ * Validate that each dataset defines exactly one `scale` transform.
+ *
+ * Every dataset's `coordinateTransformations` must contain exactly one `scale`
+ * (the per-level voxel size). This shares the per-dataset
+ * coordinate-transform-shape rule identifier
+ * ({@link SpecRule.GlobalCoordTransformAfterPerLevel}); there is no dedicated
+ * identifier for the scale count.
+ *
+ * @param metadata - The parsed multiscales metadata to validate.
+ * @throws {ValidationError} With
+ * {@link SpecRule.GlobalCoordTransformAfterPerLevel} when a dataset has zero or
+ * more than one `scale` transform; location
+ * `multiscales[0].datasets[i].coordinateTransformations`.
+ */
+export declare function validatePerDatasetScaleCount(metadata: Metadata): void;
+/**
+ * Validate coordinate-transform vector lengths against the axis count.
+ *
+ * Every `scale` and `translation` vector -- in the global
+ * `coordinateTransformations` (if present) and in each dataset -- must have
+ * exactly one entry per axis. The first mismatch, scanned
+ * global-then-per-dataset, is reported. The length invariant itself lives in
+ * {@link transformLenMismatch}.
+ *
+ * @param metadata - The parsed multiscales metadata to validate.
+ * @throws {ValidationError} With {@link SpecRule.ScaleLengthMismatch} for the
+ * first transform whose vector length disagrees with `metadata.axes.length`;
+ * location identifies the offending transform.
+ */
+export declare function validateScaleLength(metadata: Metadata): void;
+/**
+ * Validate coordinate-transform ordering within each dataset.
+ *
+ * Within a dataset's `coordinateTransformations`, a `translation` (if present)
+ * must follow its `scale` -- a `scale` must never appear after a `translation`.
+ *
+ * @param metadata - The parsed multiscales metadata to validate.
+ * @throws {ValidationError} With
+ * {@link SpecRule.GlobalCoordTransformAfterPerLevel} for the first dataset
+ * where a `scale` follows a `translation`; location identifies the offending
+ * `scale`.
+ */
+export declare function validateTransformOrder(metadata: Metadata): void;
+/**
+ * Validate that datasets are ordered finest to coarsest.
+ *
+ * Multiscale datasets must be listed from highest resolution (finest, i.e.
+ * smallest spatial `scale`) to lowest (coarsest). For each adjacent pair, the
+ * later level's `scale` must not be smaller than the earlier level's on any
+ * `space` axis. Pairs whose `scale` vectors are missing or too short to index a
+ * spatial axis are skipped -- those shapes are the concern of
+ * {@link validatePerDatasetScaleCount} and {@link validateScaleLength} -- so
+ * this rule never indexes out of bounds.
+ *
+ * @param metadata - The parsed multiscales metadata to validate.
+ * @throws {ValidationError} With {@link SpecRule.DatasetOrderHighestToLowest}
+ * for the first adjacent pair whose later (coarser) level has a smaller spatial
+ * scale; location `multiscales[0].datasets[i+1]`.
+ */
+export declare function validateDatasetOrder(metadata: Metadata): void;
+/**
+ * Validate the color format of each OMERO channel.
+ *
+ * When OMERO rendering metadata is present, every channel `color` must be
+ * exactly six hexadecimal digits (RGB). This reuses the package's existing
+ * {@link validateColor} predicate rather than re-implementing the format check,
+ * surfacing its failure message through the unified {@link ValidationError}
+ * channel.
+ *
+ * @param metadata - The parsed multiscales metadata to validate.
+ * @throws {ValidationError} With {@link SpecRule.OmeroChannelColorFormat} for
+ * the first channel whose `color` is not six hex digits; location
+ * `multiscales[0].omero.channels[i].color`.
+ */
+export declare function validateOmeroColorHex(metadata: Metadata): void;
+/**
+ * Validate RFC 4 anatomical-orientation metadata on the spatial axes.
+ *
+ * This rule does not reimplement RFC 4; it wraps the package's existing
+ * logic -- {@link hasRfc4OrientationMetadata} and
+ * {@link validateRfc4Orientation} -- and surfaces its failures through the
+ * unified {@link ValidationError} channel. The parsed {@link Axis} objects are
+ * first rendered back to the record form those helpers expect (see
+ * {@link axisToValidationRecord}).
+ *
+ * Orientation is optional in RFC 4, so when no spatial axis carries it the rule
+ * is a no-op.
+ *
+ * @param metadata - The parsed multiscales metadata to validate.
+ * @throws {ValidationError} With {@link SpecRule.AxisOrientationConsistentType}
+ * when the spatial axes' orientations do not all share one `type`, or
+ * {@link SpecRule.AxisOrientationCompleteness} when orientation is defined for
+ * some but not all spatial axes; location `multiscales[0].axes`. The original
+ * RFC 4 message text is preserved. Any other failure from
+ * {@link validateRfc4Orientation} -- e.g. an orientation value outside the
+ * RFC 4 vocabulary, a schema-level concern with no dedicated structural rule
+ * -- propagates unchanged.
+ */
+export declare function validateAxisOrientation(metadata: Metadata): void;
+/**
+ * Validate each plate well's recorded indices against its `path`.
+ *
+ * Every `PlateWell` records a `path` of the form `"<row>/<column>"` (e.g.
+ * `"B/03"`) alongside numeric `rowIndex` and `columnIndex` fields. OME-Zarr v0.4
+ * requires these to agree: the row segment must name an entry in `plate.rows`
+ * whose position equals `rowIndex`, and the column segment must name an entry in
+ * `plate.columns` whose position equals `columnIndex`. The first offending well,
+ * scanned in order, is reported.
+ *
+ * @param plate - The plate metadata whose wells are validated.
+ * @throws {ValidationError} With {@link SpecRule.PlateRowIndexConsistency} for
+ * the first well whose `path` is not `"<row>/<column>"`, whose row/column
+ * segment is absent from `plate.rows`/`plate.columns`, or whose recorded
+ * `rowIndex`/`columnIndex` disagrees with that segment's position; location
+ * `plate.wells[i]`.
+ */
+export declare function validatePlateWellIndexConsistency(plate: PlateMetadata): void;
+/**
+ * Validate that well images reference an acquisition when required.
+ *
+ * When a plate declares more than one acquisition, every image in each of its
+ * wells must carry an `acquisition` reference so the field can be attributed to
+ * a specific acquisition. Plates with zero or one acquisition impose no such
+ * requirement, so this rule is a no-op for them. The first image missing its
+ * reference, scanned in order, is reported.
+ *
+ * @param plate - The plate metadata declaring the acquisitions.
+ * @param well - The well metadata whose images are validated.
+ * @throws {ValidationError} With {@link SpecRule.WellAcquisitionMissing} for the
+ * first `WellImage` whose `acquisition` is absent while the plate declares
+ * multiple acquisitions; location `well.images[i].acquisition`.
+ */
+export declare function validateWellAcquisition(plate: PlateMetadata, well: WellMetadata): void;
+/**
+ * Run the structural image/multiscales rules in canonical specification order.
+ *
+ * Orchestrates the per-rule `validate*` functions in this module. It is
+ * fail-fast: the rules run in canonical specification-MUST order and the first
+ * {@link ValidationError} thrown propagates to the caller -- later rules do not
+ * run. The rules run in this order:
+ *
+ * 1. {@link validateAxisCount}
+ * 2. {@link validateAxisType}
+ * 3. {@link validateAxisOrder}
+ * 4. {@link validateSpatialAxisOrder}
+ * 5. {@link validatePerDatasetScaleCount}
+ * 6. {@link validateScaleLength}
+ * 7. {@link validateTransformOrder}
+ * 8. {@link validateDatasetOrder}
+ * 9. {@link validateOmeroColorHex}
+ * 10. {@link validateAxisOrientation}
+ *
+ * Under {@link ValidationLevel.SchemaOnly} this function returns immediately
+ * without running any structural rule -- shape/schema validation is the
+ * separate concern of {@link validateMetadata}, which checks the raw
+ * attributes via Zod. The default level is {@link ValidationLevel.Strict}.
+ *
+ * This orchestrator covers the image/multiscales rules, including the RFC 4
+ * anatomical-orientation checks ({@link validateAxisOrientation}, a no-op when
+ * no axis declares orientation). The HCS plate/well structural rules operate on
+ * separate metadata objects and are dispatched by the companion
+ * {@link validatePlate} and {@link validateWell} entry points.
+ *
+ * @param metadata - The parsed OME-Zarr v0.4 multiscales metadata to validate.
+ * @param options - Validation options; defaults to
+ * `{ level: "strict", allowUnknownFields: true }`.
+ * @throws {ValidationError} For the first structural rule violated, carrying
+ * the offending {@link SpecRule} and `location`. Never thrown under
+ * {@link ValidationLevel.SchemaOnly}, which runs no structural rule.
+ */
+export declare function validateStructural(metadata: Metadata, options?: ValidateOptions): void;
+/**
+ * Run the structural HCS plate rules in canonical specification order.
+ *
+ * The plate-level counterpart to {@link validateStructural}: it orchestrates
+ * the structural rules that operate on a parsed {@link PlateMetadata}. Like its
+ * image/multiscales sibling it is fail-fast -- the first {@link ValidationError}
+ * thrown propagates to the caller and later rules do not run. The rules run in
+ * this order:
+ *
+ * 1. {@link validatePlateWellIndexConsistency}
+ *
+ * Per-well image rules (e.g. acquisition references) are the separate concern
+ * of {@link validateWell}, called where each well's own metadata is loaded.
+ *
+ * Under {@link ValidationLevel.SchemaOnly} this function returns immediately
+ * without running any structural rule -- shape/schema validation is the
+ * separate concern of {@link validateMetadata}, which checks the raw attributes
+ * via Zod. The default level is {@link ValidationLevel.Strict}.
+ *
+ * @param plate - The parsed OME-Zarr v0.4 plate metadata to validate.
+ * @param options - Validation options; defaults to
+ * `{ level: "strict", allowUnknownFields: true }`.
+ * @throws {ValidationError} For the first structural plate rule violated,
+ * carrying the offending {@link SpecRule} and `location`. Never thrown under
+ * {@link ValidationLevel.SchemaOnly}, which runs no structural rule.
+ */
+export declare function validatePlate(plate: PlateMetadata, options?: ValidateOptions): void;
+/**
+ * Run the structural HCS well rules in canonical specification order.
+ *
+ * Validates a single {@link WellMetadata} in the context of its parent
+ * {@link PlateMetadata} -- the plate's acquisition declarations govern whether
+ * each well image must reference an acquisition. Fail-fast, like
+ * {@link validateStructural} and {@link validatePlate}. The rules run in this
+ * order:
+ *
+ * 1. {@link validateWellAcquisition}
+ *
+ * Under {@link ValidationLevel.SchemaOnly} this function returns immediately
+ * without running any structural rule -- shape/schema validation is the
+ * separate concern of {@link validateMetadata}, which checks the raw attributes
+ * via Zod. The default level is {@link ValidationLevel.Strict}.
+ *
+ * @param plate - The parsed plate metadata that owns `well`; supplies the
+ * acquisition context the well rules consult.
+ * @param well - The parsed well metadata to validate.
+ * @param options - Validation options; defaults to
+ * `{ level: "strict", allowUnknownFields: true }`.
+ * @throws {ValidationError} For the first structural well rule violated,
+ * carrying the offending {@link SpecRule} and `location`. Never thrown under
+ * {@link ValidationLevel.SchemaOnly}, which runs no structural rule.
+ */
+export declare function validateWell(plate: PlateMetadata, well: WellMetadata, options?: ValidateOptions): void;
+//# sourceMappingURL=structural_validation.d.ts.map

package/esm/utils/structural_validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural_validation.d.ts","sourceRoot":"","sources":["../../src/utils/structural_validation.ts"],"names":[],"mappings":"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"}