Package sc.fiji.snt.tracing.auto.gwdt

Interface StorageBackend

All Known Implementing Classes:
ArrayStorageBackend, DiskBackedStorageBackend, SparseStorageBackend
public interface StorageBackend
Storage backend for GWDT tracing data structures.

Implementations can use in-memory arrays (ArrayStorageBackend), disk-backed storage, or sparse representations for memory efficiency.

The backend handles storage for:
  • GWDT (Gray-Weighted Distance Transform) values
  • Fast Marching distances
  • Fast Marching parent pointers
  • Fast Marching state (FAR/TRIAL/ALIVE)
Author:
Tiago Ferreira

  • Method Summary

    Modifier and Type
    Method
    Description
    DirectedWeightedGraph
    buildGraph(long[] dims, double[] spacing, double threshold)
    Build graph from computed Fast Marching data.
    void
    computeGWDT(net.imglib2.RandomAccessibleInterval<?> source, double threshold, double[] spacing, double minIntensity, double maxIntensity)
    Compute Gray-Weighted Distance Transform.
    void
    dispose()
    Clean up resources (close files, free memory, delete temp files).
    long
    estimateMemoryUsage()
    Get estimated memory usage in bytes.
    default Set<Long>
    getAliveIndices()
    Returns the set of linear indices that have been marked as ALIVE during Fast Marching.
    String
    getBackendType()
    Get storage backend type name for logging.
    double
    getDistance(long index)
    Get Fast Marching distance at linear index.
    double
    getGWDT(long index)
    Get GWDT value at linear index.
    double
    getMaxGWDT()
    Get maximum GWDT value across the entire image.
    long
    getParent(long index)
    Get parent pointer at linear index.
    byte
    getState(long index)
    Get Fast Marching state at linear index.
    void
    initializeFastMarching(long[] dims, long seedIndex)
    Initialize Fast Marching data structures.
    void
    reinitializeFastMarching(long[] dims, long seedIndex, Set<Long> excludedIndices)
    Re-initializes Fast Marching data structures (distances, parents, state) while preserving the pre-computed GWDT.
    void
    setDistance(long index, double distance)
    Set Fast Marching distance at linear index.
    void
    setGWDT(long index, double value)
    Overwrites the GWDT value at a linear index.
    void
    setParent(long index, long parentIndex)
    Set parent pointer at linear index.
    void
    setState(long index, byte stateValue)
    Set Fast Marching state at linear index.
    default void
    setTrackAliveIndices(boolean track)
    Enable or disable tracking of ALIVE indices during Fast Marching.

  • Method Details

    • computeGWDT

      void computeGWDT(net.imglib2.RandomAccessibleInterval<?> source, double threshold, double[] spacing, double minIntensity, double maxIntensity)
      Compute Gray-Weighted Distance Transform.

      For each foreground pixel, GWDT = sum of intensities along shortest path to background. Uses Fast Marching with background pixels as seeds.

      Parameters:
      source - input image (untyped RandomAccessibleInterval)
      threshold - background threshold
      spacing - voxel spacing [x, y, z]
      minIntensity - minimum intensity in source (for normalization)
      maxIntensity - maximum intensity in source (for normalization)

    • getGWDT

      double getGWDT(long index)
      Get GWDT value at linear index.
      Parameters:
      index - linear voxel index
      Returns:
      GWDT value, or Double.MAX_VALUE if not computed

    • setGWDT

      void setGWDT(long index, double value)
      Overwrites the GWDT value at a linear index. Used to apply waypoint attractors between GWDT computation and Fast Marching: pulling a voxel's GWDT value toward getMaxGWDT() makes its traversal cost approach zero, so the FM wavefront prefers it.

      The maximum reported by getMaxGWDT() is not automatically recomputed; callers that bias above the original max should refresh it externally if needed.

      Parameters:
      index - linear voxel index
      value - the new GWDT value

    • getMaxGWDT

      double getMaxGWDT()
      Get maximum GWDT value across the entire image.
      Returns:
      maximum GWDT value

    • initializeFastMarching

      void initializeFastMarching(long[] dims, long seedIndex)
      Initialize Fast Marching data structures.

      Allocates storage for distances, parents, and state arrays. Initializes all values to defaults (distances=MAX_VALUE, parents=-1, state=FAR).

      Parameters:
      dims - image dimensions
      seedIndex - linear index of seed voxel (root)

    • setDistance

      void setDistance(long index, double distance)
      Set Fast Marching distance at linear index.
      Parameters:
      index - linear voxel index
      distance - geodesic distance from seed

    • getDistance

      double getDistance(long index)
      Get Fast Marching distance at linear index.
      Parameters:
      index - linear voxel index
      Returns:
      distance from seed, or Double.MAX_VALUE if unreached

    • setParent

      void setParent(long index, long parentIndex)
      Set parent pointer at linear index.
      Parameters:
      index - linear voxel index
      parentIndex - linear index of parent voxel in shortest path tree

    • getParent

      long getParent(long index)
      Get parent pointer at linear index.
      Parameters:
      index - linear voxel index
      Returns:
      parent index, or -1 if root or unset

    • setState

      void setState(long index, byte stateValue)
      Set Fast Marching state at linear index.
      Parameters:
      index - linear voxel index
      stateValue - one of FAR (0), TRIAL (1), or ALIVE (2)

    • getState

      byte getState(long index)
      Get Fast Marching state at linear index.
      Parameters:
      index - linear voxel index
      Returns:
      state value: FAR (0), TRIAL (1), or ALIVE (2)

    • buildGraph

      DirectedWeightedGraph buildGraph(long[] dims, double[] spacing, double threshold)
      Build graph from computed Fast Marching data.

      Walks the parent pointers to reconstruct the shortest path tree, converting voxel coordinates to physical coordinates and creating SWCPoint nodes connected by edges.

      Parameters:
      dims - image dimensions
      spacing - voxel spacing for coordinate conversion
      threshold - background threshold (for validation)
      Returns:
      directed weighted graph representing the traced tree

    • estimateMemoryUsage

      long estimateMemoryUsage()
      Get estimated memory usage in bytes.
      Returns:
      estimated memory footprint of this backend

    • getBackendType

      String getBackendType()
      Get storage backend type name for logging.
      Returns:
      human-readable backend type (e.g., "Array (in-memory)", "Sparse", "Disk-backed")

    • setTrackAliveIndices

      default void setTrackAliveIndices(boolean track)
      Enable or disable tracking of ALIVE indices during Fast Marching.

      When enabled, the backend maintains a set of linear indices that have been marked as ALIVE. This allows buildGraph(long[], double[], double) to iterate only touched voxels instead of scanning the entire volume, providing dramatic speedup for large sparse images.

      Memory cost: ~24 bytes per ALIVE voxel

      Recommended settings:
      • ArrayStorageBackend: ON (default) - moderate speedup, low cost
      • SparseStorageBackend: OFF (default) - already iterates keys only
      • DiskBackedStorageBackend: ON (default) - essential for performance
      Parameters:
      track - true to track ALIVE indices, false to use full-volume scan

    • getAliveIndices

      default Set<Long> getAliveIndices()
      Returns the set of linear indices that have been marked as ALIVE during Fast Marching. Only available when ALIVE tracking is enabled; returns null otherwise.
      Returns:
      the tracked ALIVE indices, or null if tracking is disabled

    • reinitializeFastMarching

      void reinitializeFastMarching(long[] dims, long seedIndex, Set<Long> excludedIndices)
      Re-initializes Fast Marching data structures (distances, parents, state) while preserving the pre-computed GWDT. Voxels whose linear indices appear in excludedIndices are pre-marked as ALIVE with distance 0, effectively making them impassable barriers for the next FM run.

      Excluded voxels are stamped directly into the state array after ALIVE tracking is initialized, so they are not added to the tracked ALIVE set. This ensures buildGraph(long[], double[], double) only sees voxels reached by the current FM pass, not leftover exclusions.

      This enables a NeuTube-style recovery pass: after tracing from one seed, the traced region (optionally dilated) is excluded and a new FM run can proceed from a different seed without recomputing the GWDT.

      Parameters:
      dims - image dimensions
      seedIndex - linear index of the new seed voxel
      excludedIndices - set of linear indices to pre-mark as ALIVE (impassable); may be null or empty

    • dispose

      void dispose()
      Clean up resources (close files, free memory, delete temp files).

      Called automatically after tracing completes. Implementations should release any resources and allow garbage collection.