Package sc.fiji.snt.tracing.auto

Class GWDTTracerFactory

java.lang.Object
sc.fiji.snt.tracing.auto.GWDTTracerFactory
public class GWDTTracerFactory extends Object
Factory for creating optimal GWDT tracer implementations based on image size. Automatically selects the best storage backend:
  • Array storage: Images < 1GB - Fast, high memory
  • Sparse storage: Images 1GB-5GB - Balanced, lower memory
  • Disk-backed storage: Images > 5GB - Slow, minimal memory

The thresholds are based on estimated working memory (not source image size): working memory ≈ source size × 10 (for GWDT + Fast Marching data structures).

Usage: 

 // Automatic selection
 AbstractGWDTTracer<?> tracer = GWDTTracerFactory.createOptimal(image);
 tracer.setSeedPhysical(somaCenter);
 List<Tree> trees = tracer.traceTrees();

 // Manual selection
 AbstractGWDTTracer<?> tracer = new SparseGWDTTracer<>(image);
Author:
Tiago Ferreira

  • Constructor Details

    • GWDTTracerFactory

      public GWDTTracerFactory()

  • Method Details

    • createOptimal

      public static AbstractGWDTTracer<?> createOptimal(net.imglib2.RandomAccessibleInterval<?> source, double[] spacing)
      Creates the optimal GWDT tracer for the given image.

      Automatically selects between Array, Sparse, or DiskBacked storage based on estimated working memory requirements.

      Parameters:
      source - the grayscale image to trace
      spacing - voxel spacing [x, y, z]
      Returns:
      optimal tracer implementation

    • createOptimal

      public static AbstractGWDTTracer<?> createOptimal(net.imagej.ImgPlus<?> source)
      Creates the optimal GWDT tracer from an ImgPlus.
      Parameters:
      source - the grayscale image to trace
      Returns:
      optimal tracer implementation

    • createOptimal

      public static AbstractGWDTTracer<?> createOptimal(ij.ImagePlus source)
      Creates the optimal GWDT tracer from an ImagePlus.
      Parameters:
      source - the grayscale image to trace
      Returns:
      optimal tracer implementation

    • estimateWorkingMemoryMB

      public static long estimateWorkingMemoryMB(long[] dims)
      Estimate working memory requirements in MB.

      Formula: (total voxels × bytes per voxel) / (1024²) where bytes per voxel = GWDT (8) + distances (8) + parents (4) + state (1) = 21 We use 25 to include overhead.

      Parameters:
      dims - image dimensions
      Returns:
      estimated working memory in megabytes

    • recommendBackend

      public static String recommendBackend(long[] dims)
      Get recommended storage backend type for an image.
      Parameters:
      dims - image dimensions
      Returns:
      "array", "sparse", or "disk"

    • getCurrentThresholds

      public static long[] getCurrentThresholds()
      Get current memory thresholds being used.

      Useful for diagnostics and testing.

      Returns:
      array of [sparseThresholdMB, diskThresholdMB]

    • printMemoryStatus

      public static void printMemoryStatus()
      Print current memory status and thresholds to console. Useful for debugging memory-related issues.

    • createOptimal

      public static AbstractGWDTTracer<?> createOptimal(net.imglib2.RandomAccessibleInterval<?> source, double[] spacing, long sparseThresholdMB, long diskThresholdMB)
      Creates optimal tracer with manual threshold override.

      Allows forcing specific backends for testing or when automatic selection is not appropriate for your workflow.

      Parameters:
      source - the grayscale image to trace
      spacing - voxel spacing [x, y, z]
      sparseThresholdMB - use sparse above this (MB), or -1 for dynamic
      diskThresholdMB - use disk above this (MB), or -1 for dynamic
      Returns:
      optimal tracer implementation

    • forceArray

      public static GWDTTracer<?> forceArray(net.imglib2.RandomAccessibleInterval<?> source, double[] spacing)
      Force use of array storage regardless of image size.

      Use with caution - may cause OutOfMemoryError for large images.

      Parameters:
      source - the grayscale image to trace
      spacing - voxel spacing
      Returns:
      array-based tracer

    • forceSparse

      public static SparseGWDTTracer<?> forceSparse(net.imglib2.RandomAccessibleInterval<?> source, double[] spacing)
      Force use of sparse storage regardless of image size.
      Parameters:
      source - the grayscale image to trace
      spacing - voxel spacing
      Returns:
      sparse tracer

    • forceDisk

      public static DiskBackedGWDTTracer<?> forceDisk(net.imglib2.RandomAccessibleInterval<?> source, double[] spacing)
      Force use of disk-backed storage regardless of image size.
      Parameters:
      source - the grayscale image to trace
      spacing - voxel spacing
      Returns:
      disk-backed tracer