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

Class DiskBackedStorageBackend

java.lang.Object
sc.fiji.snt.tracing.auto.gwdt.DiskBackedStorageBackend
All Implemented Interfaces:
StorageBackend
public class DiskBackedStorageBackend extends Object implements StorageBackend
Disk-backed storage backend for very large images.

Uses ImgLib2's DiskCachedCellImg to store GWDT and Fast Marching data on disk with LRU caching in memory. Can process images of arbitrary size with bounded memory usage.

Trade-offs:
  • Memory: Constant (~500MB-1GB) regardless of image size
  • Speed: 2-5× slower than ArrayStorageBackend due to disk I/O
  • Disk: Requires ~25 bytes per voxel temporary disk space
  • Best for: Images > 2GB or when RAM is limited

Temporary files are stored in the system temp directory and automatically deleted when dispose() is called.

Author:
Tiago Ferreira

  • Constructor Details

    • DiskBackedStorageBackend

      public DiskBackedStorageBackend(long[] dims)

    • DiskBackedStorageBackend

      public DiskBackedStorageBackend(long[] dims, int cellSize, int cacheSize)
      Creates a disk-backed storage backend with custom cache settings.
      Parameters:
      dims - image dimensions
      cellSize - size of each cache cell (e.g., 64 for 64³ cells)
      cacheSize - number of cells to keep in RAM (e.g., 1000)

  • Method Details

    • computeGWDT

      public void computeGWDT(net.imglib2.RandomAccessibleInterval<?> source, double threshold, double[] spacing, double minIntensity, double maxIntensity)
      Description copied from interface: StorageBackend
      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.

      Specified by:
      computeGWDT in interface StorageBackend
      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

      public double getGWDT(long index)
      Description copied from interface: StorageBackend
      Get GWDT value at linear index.
      Specified by:
      getGWDT in interface StorageBackend
      Parameters:
      index - linear voxel index
      Returns:
      GWDT value, or Double.MAX_VALUE if not computed

    • getMaxGWDT

      public double getMaxGWDT()
      Description copied from interface: StorageBackend
      Get maximum GWDT value across the entire image.
      Specified by:
      getMaxGWDT in interface StorageBackend
      Returns:
      maximum GWDT value

    • initializeFastMarching

      public void initializeFastMarching(long[] dims, long seedIndex)
      Description copied from interface: StorageBackend
      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).

      Specified by:
      initializeFastMarching in interface StorageBackend
      Parameters:
      dims - image dimensions
      seedIndex - linear index of seed voxel (root)

    • setDistance

      public void setDistance(long index, double distance)
      Description copied from interface: StorageBackend
      Set Fast Marching distance at linear index.
      Specified by:
      setDistance in interface StorageBackend
      Parameters:
      index - linear voxel index
      distance - geodesic distance from seed

    • getDistance

      public double getDistance(long index)
      Description copied from interface: StorageBackend
      Get Fast Marching distance at linear index.
      Specified by:
      getDistance in interface StorageBackend
      Parameters:
      index - linear voxel index
      Returns:
      distance from seed, or Double.MAX_VALUE if unreached

    • setParent

      public void setParent(long index, long parentIndex)
      Description copied from interface: StorageBackend
      Set parent pointer at linear index.
      Specified by:
      setParent in interface StorageBackend
      Parameters:
      index - linear voxel index
      parentIndex - linear index of parent voxel in shortest path tree

    • getParent

      public long getParent(long index)
      Description copied from interface: StorageBackend
      Get parent pointer at linear index.
      Specified by:
      getParent in interface StorageBackend
      Parameters:
      index - linear voxel index
      Returns:
      parent index, or -1 if root or unset

    • setState

      public void setState(long index, byte stateValue)
      Description copied from interface: StorageBackend
      Set Fast Marching state at linear index.
      Specified by:
      setState in interface StorageBackend
      Parameters:
      index - linear voxel index
      stateValue - one of FAR (0), TRIAL (1), or ALIVE (2)

    • getState

      public byte getState(long index)
      Description copied from interface: StorageBackend
      Get Fast Marching state at linear index.
      Specified by:
      getState in interface StorageBackend
      Parameters:
      index - linear voxel index
      Returns:
      state value: FAR (0), TRIAL (1), or ALIVE (2)

    • buildGraph

      public DirectedWeightedGraph buildGraph(long[] dims, double[] spacing, double threshold)
      Description copied from interface: StorageBackend
      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.

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

    • estimateMemoryUsage

      public long estimateMemoryUsage()
      Description copied from interface: StorageBackend
      Get estimated memory usage in bytes.
      Specified by:
      estimateMemoryUsage in interface StorageBackend
      Returns:
      estimated memory footprint of this backend

    • getBackendType

      public String getBackendType()
      Description copied from interface: StorageBackend
      Get storage backend type name for logging.
      Specified by:
      getBackendType in interface StorageBackend
      Returns:
      human-readable backend type (e.g., "Array (in-memory)", "Sparse", "Disk-backed")

    • getAliveIndices

      public Set<Long> getAliveIndices()

    • dispose

      public void dispose()
      Description copied from interface: StorageBackend
      Clean up resources (close files, free memory, delete temp files).

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

      Specified by:
      dispose in interface StorageBackend

    • setConnectivityType

      public void setConnectivityType(int type)
      Sets the connectivity type for neighbor iteration.

    • setTrackAliveIndices

      public void setTrackAliveIndices(boolean track)
      Description copied from interface: StorageBackend
      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 StorageBackend.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
      Specified by:
      setTrackAliveIndices in interface StorageBackend
      Parameters:
      track - true to track ALIVE indices, false to use full-volume scan