Package sc.fiji.snt.util

Class TreeToRaster

java.lang.Object
sc.fiji.snt.util.TreeToRaster
public class TreeToRaster extends Object
Rasterizes a Tree into a 3D image using frustum (truncated-cone) geometry with partial-volume supersampling. Each segment between consecutive nodes is modeled as a frustum whose radii are linearly interpolated from the node radii. This produces a volumetric rendering that respects the thickness of each neurite, unlike the skeleton-based rasterization in Tree.getSkeleton().

Optionally, Poisson shot noise and Gaussian blur (to simulate spatially correlated noise) can be applied, producing realistic synthetic fluorescence microscopy images.

Optionally, voxel intensities can be modulated by local neurite thickness via setThicknessModulation(double), producing brighter thick neurites and dimmer thin ones.

Pass 2 (partial-volume supersampling) and subsequent passes are parallelized across z-slices for improved performance. A spatial grid is used for frustum lookups to reduce computation costs.

Inspired by SWC2IMG (E. Meijering, imagescience.org).

Author:
Tiago Ferreira
See Also:

  • Constructor Details

    • TreeToRaster

      public TreeToRaster(Tree tree)
      Constructs a new rasterizer for the given tree. Resolution defaults to the tree's own spatial calibration if available, otherwise 1 unit isotropic.
      Parameters:
      tree - the Tree to rasterize (must not be empty)

  • Method Details

    • setLateralRes

      public TreeToRaster setLateralRes(double lateralRes)
      Sets the lateral (x, y) voxel size.
      Parameters:
      lateralRes - voxel size in the tree's spatial units (typically µm)
      Returns:
      this instance for chaining

    • setAxialRes

      public TreeToRaster setAxialRes(double axialRes)
      Sets the axial (z) voxel size.
      Parameters:
      axialRes - voxel size in the tree's spatial units (typically µm)
      Returns:
      this instance for chaining

    • setDefaultRadius

      public TreeToRaster setDefaultRadius(double radius)
      Sets the default radius used for nodes/trees that have no radii defined. If not set, defaults to half the lateral voxel size (i.e., a 1-voxel diameter).
      Parameters:
      radius - the default radius in the tree's spatial units
      Returns:
      this instance for chaining

    • setReferenceBounds

      public TreeToRaster setReferenceBounds(ij.ImagePlus imp)
      Sets reference bounds from an ImagePlus, so the output image matches its exact dimensions. When set, the rasterized image will have the same width, height, and depth as the reference, with the origin at (0, 0, 0) in pixel coordinates. This ensures pixel-level alignment between the rasterized output and the reference image. Resolution is also updated from the reference calibration.
      Parameters:
      imp - the reference image whose dimensions to match
      Returns:
      this instance for chaining

    • setReferenceBounds

      public TreeToRaster setReferenceBounds(int width, int height, int depth)
      Sets reference bounds explicitly, so the output image matches the specified dimensions. When set, the rasterized image will have exactly the given width, height, and depth, with the origin at (0, 0, 0) in pixel coordinates.
      Parameters:
      width - the reference width in pixels
      height - the reference height in pixels
      depth - the reference depth in slices
      Returns:
      this instance for chaining

    • setPoissonNoise

      public TreeToRaster setPoissonNoise(double snr, double background)
      Enables Poisson shot noise on the rasterized image, simulating photon counting noise typical of fluorescence microscopy.

      The peak intensity is derived from the SNR and background using the photon-counting model: SNR = (peak - bg) / sqrt(peak). Note that Poisson shot noise is ignored when using rasterizePathLabels()

      Parameters:
      snr - the signal-to-noise ratio (peak-to-noise). Must be positive.
      background - the background intensity (photon count). Must be non-negative.
      Returns:
      this instance for chaining

    • setGaussianBlur

      public TreeToRaster setGaussianBlur(double sigma)
      Enables Gaussian blurring of the (optionally noisy) image, simulating spatially correlated noise and optical blur. Note that Gaussian blurring is ignored when using rasterizePathLabels().
      Parameters:
      sigma - the Gaussian sigma in the tree's spatial units (typically µm). Must be positive.
      Returns:
      this instance for chaining

    • setThicknessModulation

      public TreeToRaster setThicknessModulation(double factor)
      Enables intensity modulation based on local neurite thickness. When enabled, thicker neurites are rendered brighter and thinner neurites dimmer, proportional to the local radius.

      The modulation factor defines what fraction of the intensity range is used for thickness variation. For example, a factor of 0.2 means the thickest frustum receives full intensity (1.0) while the thinnest receives 80% of the maximum (0.8).

      Note: This option incurs additional computation since the local radius must be resolved for every sub-voxel hit during supersampling. Also, a factor of 1.0 maps the thinnest structure to zero intensity, effectively wiping it.

      Parameters:
      factor - the modulation depth in [0, 1]. 0 disables modulation (default). Must be non-negative and at most 1.
      Returns:
      this instance for chaining

    • rasterize

      public ij.ImagePlus rasterize()
      Rasterizes the tree into a 32-bit (float) image using partial-volume supersampling. Voxel values represent the fraction of the supersampled sub-voxels that fall inside the neuron structure (0.0 = background, 1.0 = fully inside), unless noise has been enabled via setPoissonNoise(double, double), in which case values represent simulated photon counts.
      Returns:
      the rasterized ImagePlus

    • rasterizeLabels

      @Deprecated public ij.ImagePlus rasterizeLabels()
      Deprecated.
      Use rasterizePathLabels() instead
      Rasterizes the tree into a 16-bit label image where each voxel is assigned the 1-based index of the Path that owns it (as ordered by Tree.list()). Background voxels are 0.
      Returns:
      a 16-bit ImagePlus of path labels

    • rasterizePathLabels

      public ij.ImagePlus rasterizePathLabels()
      Rasterizes the tree into a 16-bit label image where each voxel is assigned the 1-based index of the Path that owns it (as ordered by Tree.list()). Background voxels are 0.

      At intersection sites where multiple paths overlap, the path with the largest local radius wins (thickest-wins priority), ensuring that thin branches crossing a thick trunk do not overwrite it.

      The returned image has the same dimensions and calibration as the density image produced by rasterize(), so the two can be used as overlays. Noise and blur settings are ignored for label images.

      Returns:
      a 16-bit ImagePlus of path labels
      See Also:

    • rasterizeNodeValueLabels

      public ij.ImagePlus rasterizeNodeValueLabels()
      Rasterizes the tree into a 16-bit label image where each voxel is assigned the node value of the nearest path node (as stored via Path.setNodeValue(double, int)). This enables per-node labeling, e.g., from delineation assignments, atlas annotations, or other node-level classifications.

      Node values are expected to be negative integers (as used by DelineationsManager); they are negated to produce positive labels in the output image. Nodes with NaN or non-negative values are treated as background (0).

      Each frustum (segment between consecutive nodes) inherits the label of its start node. At intersection sites, the frustum with the largest local radius wins (thickest-wins), consistent with rasterizePathLabels().

      Note: The output is 16-bit unsigned (short), so label values above 65535 will overflow. In practice this is not a concern when the source is a label/segmentation image with a bounded class count, but callers should be aware of this limit.

      Returns:
      a 16-bit ImagePlus of node-value labels
      See Also: