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.
    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
    setDistance(long index, double distance)
    Set Fast Marching distance at 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

    • 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

    • 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.