Package net.preibisch.mvrecon.process.fusion.blk

Class DisplacementFieldN5Tools

java.lang.Object

net.preibisch.mvrecon.process.fusion.blk.DisplacementFieldN5Tools

public final class DisplacementFieldN5Tools
extends Object

Static helpers to persist displacement fields to an N5/Zarr container and reload them as in-memory ArrayImgs. Layout: each dfield is stored as a 4D dataset of shape (n, gridX, gridY, gridZ) where n is the number of vector components (3 for 3D). The spacing (double[]) and offset (double[]) used during sampling are written as N5 attributes on the dataset so that the DisplacementFields.TransformedDisplacementField can be reconstructed exactly on the read side. Important: per the perf contract of BlkThinPlateSplineFusion, the read side returns an ArrayImg-backed dfield (not a lazy CachedCellImg). The downstream block operator is tuned for ArrayImg access patterns.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	CACHE_GROUP

Method Summary

Modifier and Type	Method	Description
static <D extends net.imglib2.type.NativeType<D> & net.imglib2.type.numeric.RealType<D>> void	createEmptyDataset(org.janelia.saalfeldlab.n5.N5Writer n5Writer, String datasetPath, net.imglib2.Interval bbox, double[] spacing, int[] blockSize3d, D type, org.janelia.saalfeldlab.n5.Compression compression)	Backward-compatible overload: no correspondence-label / min annotation (treated as "no correspondence midpoints used") and no corner anchors.
static <D extends net.imglib2.type.NativeType<D> & net.imglib2.type.numeric.RealType<D>> void	createEmptyDataset(org.janelia.saalfeldlab.n5.N5Writer n5Writer, String datasetPath, net.imglib2.Interval bbox, double[] spacing, int[] blockSize3d, D type, org.janelia.saalfeldlab.n5.Compression compression, String correspondenceLabel, int minNumCorrespondences)	Backward-compatible overload: correspondence label + min, no corner anchors.
static <D extends net.imglib2.type.NativeType<D> & net.imglib2.type.numeric.RealType<D>> void	createEmptyDataset(org.janelia.saalfeldlab.n5.N5Writer n5Writer, String datasetPath, net.imglib2.Interval bbox, double[] spacing, int[] blockSize3d, D type, org.janelia.saalfeldlab.n5.Compression compression, String correspondenceLabel, int minNumCorrespondences, boolean anchorOverlapCorners, double cornerCoverageRadius)	Backward-compatible overload: corner anchors with N=2 (corners only).
static <D extends net.imglib2.type.NativeType<D> & net.imglib2.type.numeric.RealType<D>> void	createEmptyDataset(org.janelia.saalfeldlab.n5.N5Writer n5Writer, String datasetPath, net.imglib2.Interval bbox, double[] spacing, int[] blockSize3d, D type, org.janelia.saalfeldlab.n5.Compression compression, String correspondenceLabel, int minNumCorrespondences, boolean anchorOverlapCorners, double cornerCoverageRadius, int samplesPerAxis)	Backward-compatible overload: no per-split schedule.
static <D extends net.imglib2.type.NativeType<D> & net.imglib2.type.numeric.RealType<D>> void	createEmptyDataset(org.janelia.saalfeldlab.n5.N5Writer n5Writer, String datasetPath, net.imglib2.Interval bbox, double[] spacing, int[] blockSize3d, D type, org.janelia.saalfeldlab.n5.Compression compression, String correspondenceLabel, int minNumCorrespondences, boolean anchorOverlapCorners, double cornerCoverageRadius, int samplesPerAxis, int[] samplesScheduleThresholds, int[] samplesScheduleValues)	Pre-create an empty dfield dataset (4D, shape (n, gridX, gridY, gridZ)) with the right block size, datatype, compression, and attributes.
static boolean	datasetMatches(org.janelia.saalfeldlab.n5.N5Reader n5Reader, String datasetPath, net.imglib2.Interval expectedBbox, double[] expectedSpacing)	Backward-compatible overload: no correspondence-label / anchor checks.
static boolean	datasetMatches(org.janelia.saalfeldlab.n5.N5Reader n5Reader, String datasetPath, net.imglib2.Interval expectedBbox, double[] expectedSpacing, String expectedCorrespondenceLabel, int expectedMinNumCorrespondences)	Backward-compatible overload: correspondence-label + min check, no anchor check.
static boolean	datasetMatches(org.janelia.saalfeldlab.n5.N5Reader n5Reader, String datasetPath, net.imglib2.Interval expectedBbox, double[] expectedSpacing, String expectedCorrespondenceLabel, int expectedMinNumCorrespondences, boolean expectedAnchorOverlapCorners, double expectedCornerCoverageRadius)	Backward-compatible overload: corner anchors with N=2 (corners only).
static boolean	datasetMatches(org.janelia.saalfeldlab.n5.N5Reader n5Reader, String datasetPath, net.imglib2.Interval expectedBbox, double[] expectedSpacing, String expectedCorrespondenceLabel, int expectedMinNumCorrespondences, boolean expectedAnchorOverlapCorners, double expectedCornerCoverageRadius, int expectedSamplesPerAxis)	Backward-compatible overload: no per-split schedule.
static boolean	datasetMatches(org.janelia.saalfeldlab.n5.N5Reader n5Reader, String datasetPath, net.imglib2.Interval expectedBbox, double[] expectedSpacing, String expectedCorrespondenceLabel, int expectedMinNumCorrespondences, boolean expectedAnchorOverlapCorners, double expectedCornerCoverageRadius, int expectedSamplesPerAxis, int[] expectedScheduleThresholds, int[] expectedScheduleValues)	Check whether a dfield dataset already exists at the given path with the expected spacing, offset (= bbox.min), correspondence label/min, and corner-anchor config.
static String	datasetPath(mpicbg.spim.data.sequence.ViewId underlyingViewId)	Canonical N5/Zarr dataset path for the displacement field of a given underlying view.
static long[]	gridBlockCount(net.imglib2.Interval bbox, double[] spacing, int[] blockSize3d)	Compute the per-dim count of dfield blocks for the given bbox/spacing/blockSize.
static net.imglib2.realtransform.AffineTransform3D	readApproxAffine(org.janelia.saalfeldlab.n5.N5Reader n5Reader, String datasetPath)	Read the per-view approximate affine from a dfield dataset's attributes.
static net.imglib2.Interval	readBbox(org.janelia.saalfeldlab.n5.N5Reader n5Reader, String datasetPath)	Read the back-projected bbox (render coordinates) of the source view from a previously-written dfield dataset's attributes.
static <D extends net.imglib2.type.NativeType<D> & net.imglib2.type.numeric.RealType<D>> net.imglib2.algorithm.blocks.dfield.DisplacementFields.TransformedDisplacementField<D>	readDisplacementFieldAsArrayImg(org.janelia.saalfeldlab.n5.N5Reader n5Reader, String datasetPath, D type)	Read a dfield dataset (previously written by writeDisplacementField(net.imglib2.realtransform.RealTransform, net.imglib2.Interval, double[], org.janelia.saalfeldlab.n5.N5Writer, java.lang.String, int[], D, org.janelia.saalfeldlab.n5.Compression)) into a full ArrayImg and reconstruct the DisplacementFields.TransformedDisplacementField.
static <D extends net.imglib2.type.NativeType<D> & net.imglib2.type.numeric.RealType<D>> net.imglib2.algorithm.blocks.dfield.DisplacementFields.TransformedDisplacementField<D>	readDisplacementFieldAsCellImg(org.janelia.saalfeldlab.n5.N5Reader n5Reader, String datasetPath, D type)	Read a dfield dataset (previously written by writeDisplacementField(net.imglib2.realtransform.RealTransform, net.imglib2.Interval, double[], org.janelia.saalfeldlab.n5.N5Writer, java.lang.String, int[], D, org.janelia.saalfeldlab.n5.Compression) or createEmptyDataset(org.janelia.saalfeldlab.n5.N5Writer, java.lang.String, net.imglib2.Interval, double[], int[], D, org.janelia.saalfeldlab.n5.Compression)+writeDisplacementFieldBlock(net.imglib2.realtransform.RealTransform, net.imglib2.Interval, double[], int[], long[], org.janelia.saalfeldlab.n5.N5Writer, java.lang.String, D)) as a lazy CellImg and reconstruct the DisplacementFields.TransformedDisplacementField.
static void	writeApproxAffine(org.janelia.saalfeldlab.n5.N5Writer n5Writer, String datasetPath, net.imglib2.realtransform.AffineTransform3D affine)	Write the per-view approximate affine (the affine that fits from the TPS landmarks for blending-weight adjustment) as an N5 attribute on the dfield dataset.
static <D extends net.imglib2.type.NativeType<D> & net.imglib2.type.numeric.RealType<D>> void	writeDisplacementField(net.imglib2.realtransform.RealTransform transform, net.imglib2.Interval bbox, double[] spacing, org.janelia.saalfeldlab.n5.N5Writer n5Writer, String datasetPath, int[] blockSize3d, D type, org.janelia.saalfeldlab.n5.Compression compression)	Sample the given transform over bbox at spacing and write the resulting displacement field to an N5/Zarr dataset.
static <D extends net.imglib2.type.NativeType<D> & net.imglib2.type.numeric.RealType<D>> void	writeDisplacementFieldBlock(net.imglib2.realtransform.RealTransform transform, net.imglib2.Interval bbox, double[] spacing, int[] blockSize3d, long[] blockGridPos3d, org.janelia.saalfeldlab.n5.N5Writer n5Writer, String datasetPath, D type)	Sample one block of the displacement field and write it via N5Utils.saveBlock(net.imglib2.RandomAccessibleInterval<T>, org.janelia.saalfeldlab.n5.N5Writer, java.lang.String, org.janelia.saalfeldlab.n5.DatasetAttributes, long[]).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

CACHE_GROUP

public static final String CACHE_GROUP

See Also:

• Constant Field Values

Method Details

datasetPath

public static String datasetPath(mpicbg.spim.data.sequence.ViewId underlyingViewId)

Canonical N5/Zarr dataset path for the displacement field of a given underlying view.

writeDisplacementField

public static <D extends net.imglib2.type.NativeType<D> & net.imglib2.type.numeric.RealType<D>>
void writeDisplacementField(net.imglib2.realtransform.RealTransform transform,
 net.imglib2.Interval bbox,
 double[] spacing,
 org.janelia.saalfeldlab.n5.N5Writer n5Writer,
 String datasetPath,
 int[] blockSize3d,
 D type,
 org.janelia.saalfeldlab.n5.Compression compression)

Sample the given transform over bbox at spacing and write the resulting displacement field to an N5/Zarr dataset.

Parameters:

transform - the transform to sample (target -> source).

bbox - the interval in render coordinates to sample over.

spacing - dfield grid spacing per dim.

n5Writer - open writer for the destination container.

datasetPath - path inside the container, e.g. "_displacement_field_cache/setup0/timepoint0".

blockSize3d - dfield block size in grid coords (3D); will be prefixed with the vector-component dim to form the 4D N5 block size.

type - dfield component type (FloatType or DoubleType).

compression - N5 compression for the dataset.

createEmptyDataset

public static <D extends net.imglib2.type.NativeType<D> & net.imglib2.type.numeric.RealType<D>>
void createEmptyDataset(org.janelia.saalfeldlab.n5.N5Writer n5Writer,
 String datasetPath,
 net.imglib2.Interval bbox,
 double[] spacing,
 int[] blockSize3d,
 D type,
 org.janelia.saalfeldlab.n5.Compression compression)

Backward-compatible overload: no correspondence-label / min annotation (treated as "no correspondence midpoints used") and no corner anchors.

createEmptyDataset

public static <D extends net.imglib2.type.NativeType<D> & net.imglib2.type.numeric.RealType<D>>
void createEmptyDataset(org.janelia.saalfeldlab.n5.N5Writer n5Writer,
 String datasetPath,
 net.imglib2.Interval bbox,
 double[] spacing,
 int[] blockSize3d,
 D type,
 org.janelia.saalfeldlab.n5.Compression compression,
 String correspondenceLabel,
 int minNumCorrespondences)

Backward-compatible overload: correspondence label + min, no corner anchors.

createEmptyDataset

public static <D extends net.imglib2.type.NativeType<D> & net.imglib2.type.numeric.RealType<D>>
void createEmptyDataset(org.janelia.saalfeldlab.n5.N5Writer n5Writer,
 String datasetPath,
 net.imglib2.Interval bbox,
 double[] spacing,
 int[] blockSize3d,
 D type,
 org.janelia.saalfeldlab.n5.Compression compression,
 String correspondenceLabel,
 int minNumCorrespondences,
 boolean anchorOverlapCorners,
 double cornerCoverageRadius)

Backward-compatible overload: corner anchors with N=2 (corners only).

createEmptyDataset

public static <D extends net.imglib2.type.NativeType<D> & net.imglib2.type.numeric.RealType<D>>
void createEmptyDataset(org.janelia.saalfeldlab.n5.N5Writer n5Writer,
 String datasetPath,
 net.imglib2.Interval bbox,
 double[] spacing,
 int[] blockSize3d,
 D type,
 org.janelia.saalfeldlab.n5.Compression compression,
 String correspondenceLabel,
 int minNumCorrespondences,
 boolean anchorOverlapCorners,
 double cornerCoverageRadius,
 int samplesPerAxis)

Backward-compatible overload: no per-split schedule.

createEmptyDataset

public static <D extends net.imglib2.type.NativeType<D> & net.imglib2.type.numeric.RealType<D>>
void createEmptyDataset(org.janelia.saalfeldlab.n5.N5Writer n5Writer,
 String datasetPath,
 net.imglib2.Interval bbox,
 double[] spacing,
 int[] blockSize3d,
 D type,
 org.janelia.saalfeldlab.n5.Compression compression,
 String correspondenceLabel,
 int minNumCorrespondences,
 boolean anchorOverlapCorners,
 double cornerCoverageRadius,
 int samplesPerAxis,
 int[] samplesScheduleThresholds,
 int[] samplesScheduleValues)

Pre-create an empty dfield dataset (4D, shape (n, gridX, gridY, gridZ)) with the right block size, datatype, compression, and attributes. Designed to be called once on the driver before block-level Spark tasks each sample and save one block via writeDisplacementFieldBlock(net.imglib2.realtransform.RealTransform, net.imglib2.Interval, double[], int[], long[], org.janelia.saalfeldlab.n5.N5Writer, java.lang.String, D), so executors don't race on dataset creation. Also records the correspondence-label and min-N used to build the dfield's landmarks (see SplitImgLoaderThinPlateSplineFusion.getCoefficients(...)), so the cache can be invalidated when these change.

writeDisplacementFieldBlock

public static <D extends net.imglib2.type.NativeType<D> & net.imglib2.type.numeric.RealType<D>>
void writeDisplacementFieldBlock(net.imglib2.realtransform.RealTransform transform,
 net.imglib2.Interval bbox,
 double[] spacing,
 int[] blockSize3d,
 long[] blockGridPos3d,
 org.janelia.saalfeldlab.n5.N5Writer n5Writer,
 String datasetPath,
 D type)

Sample one block of the displacement field and write it via N5Utils.saveBlock(net.imglib2.RandomAccessibleInterval<T>, org.janelia.saalfeldlab.n5.N5Writer, java.lang.String, org.janelia.saalfeldlab.n5.DatasetAttributes, long[]). Used to parallelize dfield rasterization across Spark tasks: each task computes a small sub-region of the dfield grid (typically a single N5 chunk) and writes it independently. The dataset must already exist (see createEmptyDataset(org.janelia.saalfeldlab.n5.N5Writer, java.lang.String, net.imglib2.Interval, double[], int[], D, org.janelia.saalfeldlab.n5.Compression)).

Parameters:

transform - the transform to sample (target -> source).

bbox - full-view bounding box in render coordinates (same as used in createEmptyDataset(org.janelia.saalfeldlab.n5.N5Writer, java.lang.String, net.imglib2.Interval, double[], int[], D, org.janelia.saalfeldlab.n5.Compression) for this dataset).

spacing - dfield grid spacing per dim.

blockSize3d - dfield block size in grid coordinates (same as used in createEmptyDataset(org.janelia.saalfeldlab.n5.N5Writer, java.lang.String, net.imglib2.Interval, double[], int[], D, org.janelia.saalfeldlab.n5.Compression)).

blockGridPos3d - block index per dim in the 3D grid of dfield blocks (i.e., 0-based block coordinates: blockGridPos3d[d] = blockStart[d] / blockSize3d[d]).

gridBlockCount

public static long[] gridBlockCount(net.imglib2.Interval bbox,
 double[] spacing,
 int[] blockSize3d)

Compute the per-dim count of dfield blocks for the given bbox/spacing/blockSize. Used by the driver to enumerate blockGridPos3d values to dispatch.

readBbox

public static net.imglib2.Interval readBbox(org.janelia.saalfeldlab.n5.N5Reader n5Reader,
 String datasetPath)

Read the back-projected bbox (render coordinates) of the source view from a previously-written dfield dataset's attributes.

writeApproxAffine

public static void writeApproxAffine(org.janelia.saalfeldlab.n5.N5Writer n5Writer,
 String datasetPath,
 net.imglib2.realtransform.AffineTransform3D affine)

Write the per-view approximate affine (the affine that fits from the TPS landmarks for blending-weight adjustment) as an N5 attribute on the dfield dataset. Stored as a flat double[12] in row-major 3x4 order — the same layout produced by AffineTransform3D.toArray(double[]).

readApproxAffine

public static net.imglib2.realtransform.AffineTransform3D readApproxAffine(org.janelia.saalfeldlab.n5.N5Reader n5Reader,
 String datasetPath)

Read the per-view approximate affine from a dfield dataset's attributes. Returns null if the attribute is absent (so callers can fall back to recomputing it from landmarks for back-compat with pre-cache containers).

readDisplacementFieldAsArrayImg

public static <D extends net.imglib2.type.NativeType<D> & net.imglib2.type.numeric.RealType<D>>
net.imglib2.algorithm.blocks.dfield.DisplacementFields.TransformedDisplacementField<D> readDisplacementFieldAsArrayImg(org.janelia.saalfeldlab.n5.N5Reader n5Reader,
 String datasetPath,
 D type)

Read a dfield dataset (previously written by writeDisplacementField(net.imglib2.realtransform.RealTransform, net.imglib2.Interval, double[], org.janelia.saalfeldlab.n5.N5Writer, java.lang.String, int[], D, org.janelia.saalfeldlab.n5.Compression)) into a full ArrayImg and reconstruct the DisplacementFields.TransformedDisplacementField. The returned dfield is backed by an ArrayImg, not a lazy cell image, so downstream BlkThinPlateSplineFusion operations meet their perf expectations.

readDisplacementFieldAsCellImg

public static <D extends net.imglib2.type.NativeType<D> & net.imglib2.type.numeric.RealType<D>>
net.imglib2.algorithm.blocks.dfield.DisplacementFields.TransformedDisplacementField<D> readDisplacementFieldAsCellImg(org.janelia.saalfeldlab.n5.N5Reader n5Reader,
 String datasetPath,
 D type)

Read a dfield dataset (previously written by writeDisplacementField(net.imglib2.realtransform.RealTransform, net.imglib2.Interval, double[], org.janelia.saalfeldlab.n5.N5Writer, java.lang.String, int[], D, org.janelia.saalfeldlab.n5.Compression) or createEmptyDataset(org.janelia.saalfeldlab.n5.N5Writer, java.lang.String, net.imglib2.Interval, double[], int[], D, org.janelia.saalfeldlab.n5.Compression)+writeDisplacementFieldBlock(net.imglib2.realtransform.RealTransform, net.imglib2.Interval, double[], int[], long[], org.janelia.saalfeldlab.n5.N5Writer, java.lang.String, D)) as a lazy CellImg and reconstruct the DisplacementFields.TransformedDisplacementField. The returned dfield is backed by a CachedCellImg — chunks are loaded from N5 on demand, so per-task heap is bounded by the cells actually touched by the current Spark block (typically a few MB) instead of the full grid (typically GB). Prefer this over readDisplacementFieldAsArrayImg(org.janelia.saalfeldlab.n5.N5Reader, java.lang.String, D) when the dfield is large enough that holding the full grid in heap is impractical, and accept the per-cell load overhead.

datasetMatches

public static boolean datasetMatches(org.janelia.saalfeldlab.n5.N5Reader n5Reader,
 String datasetPath,
 net.imglib2.Interval expectedBbox,
 double[] expectedSpacing)

Backward-compatible overload: no correspondence-label / anchor checks.

datasetMatches

public static boolean datasetMatches(org.janelia.saalfeldlab.n5.N5Reader n5Reader,
 String datasetPath,
 net.imglib2.Interval expectedBbox,
 double[] expectedSpacing,
 String expectedCorrespondenceLabel,
 int expectedMinNumCorrespondences)

Backward-compatible overload: correspondence-label + min check, no anchor check.

datasetMatches

public static boolean datasetMatches(org.janelia.saalfeldlab.n5.N5Reader n5Reader,
 String datasetPath,
 net.imglib2.Interval expectedBbox,
 double[] expectedSpacing,
 String expectedCorrespondenceLabel,
 int expectedMinNumCorrespondences,
 boolean expectedAnchorOverlapCorners,
 double expectedCornerCoverageRadius)

Backward-compatible overload: corner anchors with N=2 (corners only).

datasetMatches

public static boolean datasetMatches(org.janelia.saalfeldlab.n5.N5Reader n5Reader,
 String datasetPath,
 net.imglib2.Interval expectedBbox,
 double[] expectedSpacing,
 String expectedCorrespondenceLabel,
 int expectedMinNumCorrespondences,
 boolean expectedAnchorOverlapCorners,
 double expectedCornerCoverageRadius,
 int expectedSamplesPerAxis)

Backward-compatible overload: no per-split schedule.

datasetMatches

public static boolean datasetMatches(org.janelia.saalfeldlab.n5.N5Reader n5Reader,
 String datasetPath,
 net.imglib2.Interval expectedBbox,
 double[] expectedSpacing,
 String expectedCorrespondenceLabel,
 int expectedMinNumCorrespondences,
 boolean expectedAnchorOverlapCorners,
 double expectedCornerCoverageRadius,
 int expectedSamplesPerAxis,
 int[] expectedScheduleThresholds,
 int[] expectedScheduleValues)

Check whether a dfield dataset already exists at the given path with the expected spacing, offset (= bbox.min), correspondence label/min, and corner-anchor config. Absent attributes are treated as null label / false anchor / 0 thresholds, so datasets written before these features are detected as stale when any of them is requested.