Package sc.fiji.snt.io

Class SpimDataUtils

java.lang.Object
sc.fiji.snt.io.SpimDataUtils
public class SpimDataUtils extends Object
Utilities for working with AbstractSpimData and BigDataViewer XML descriptors.
Author:
Tiago Ferreira

  • Method Details

    • openChannel

      public static SpimDataUtils.ChannelData openChannel(String path, int channelIdx, int timepoint) throws IOException
      Opens one channel of a dataset at full resolution, whatever its format: BDV .xml or Imaris .ims files (opened in memory, no XML sidecar is written), or N5/OME-Zarr containers (local or remote). Channels are in the order they are displayed by the viewers. Intended for scripts that operate on the full volume (see ChannelUnmixing.groovy).
      Parameters:
      path - path or URL of the dataset
      channelIdx - index of the channel (0-based)
      timepoint - index of the timepoint (0-based)
      Returns:
      the channel
      Throws:
      IOException - if the dataset cannot be opened
      IllegalArgumentException - if the format is unsupported or the indices are out of range

    • resolvePathToSource

      public static Object resolvePathToSource(String filePathOrUrl)
      Resolves a file path to an AbstractSpimData (for .ims and .xml files), an SpimDataUtils.N5Sources (for .n5/.zarr containers), or an ImgPlus (fallback).
      Parameters:
      filePathOrUrl - path or URL to the image file
      Returns:
      an AbstractSpimData, SpimDataUtils.N5Sources, or ImgPlus
      Throws:
      IllegalArgumentException - if the file cannot be opened

    • isRemoteUrl

      public static boolean isRemoteUrl(String path)
      Whether path is a remote URL (e.g. https://.../dataset.ome.zarr, s3://bucket/key, gs://bucket/key) rather than a local filesystem path. Also recognizes the same URLs after their scheme separator has been collapsed from "://" to ":/" by File's own path normalization (see restoreUrlScheme(String)) -- this happens whenever a URL is round-tripped through a File-typed SciJava parameter, e.g. a user typing a URL into BigDataLoaderCmd's "Main volume" field. Neither Windows drive letters (C:\...) nor UNC paths (\\server\share) match either form, so local paths are never misidentified

    • restoreUrlScheme

      public static String restoreUrlScheme(String url)
      Restores a URL's "://" scheme separator if File's path normalization collapsed it to a single slash (see isRemoteUrl(String)). A no-op if the separator is already intact.

    • patchImsXml

      public static void patchImsXml(String xmlPath, String base) throws IOException
      Patches an IMS XML sidecar file, replacing all "(name not specified)" placeholders with sequential channel names derived from the base name.
      Parameters:
      xmlPath - path to the XML sidecar
      base - base name to use (typically the IMS filename without extension)
      Throws:
      IOException - if the file cannot be read or written

    • resolveN5Selection

      public static SpimDataUtils.N5Sources resolveN5Selection(org.janelia.saalfeldlab.n5.ui.DataSelection selection, String name)
      Builds SpimDataUtils.N5Sources from a user-made DataSelection (e.g. from an interactive DatasetSelectorDialog), reusing the same source-building logic as the automatic discovery in resolvePathToSource(String). Intended as a fallback UI for containers whose structure resolvePathToSource(String) could not resolve on its own.
      Parameters:
      selection - the user's dataset selection
      name - display name for the resulting SpimDataUtils.N5Sources
      Returns:
      the resolved sources
      Throws:
      IllegalArgumentException - if no displayable sources are found

    • writeBdvN5Xml

      public static void writeBdvN5Xml(File xmlFile, String n5DirName, long[][] levelDims, double[] voxelSize, String unit, int nTimepoints, String setupName) throws IOException
      Writes a BDV-compatible XML descriptor for an N5 dataset. The resulting XML can be opened by BigDataViewer, BigVolumeViewer, or any BDV-based tool via XmlIoSpimDataMinimal.load().

      The descriptor references the N5 container using a relative path (assumes the XML sits next to the N5 directory). A single ViewSetup (id 0) is created with the supplied voxel size and calibration unit.

      Parameters:
      xmlFile - the XML file to write (will be overwritten if it exists)
      n5DirName - name of the N5 container directory (relative to the XML file's parent; e.g., "dataset_unmixed")
      levelDims - per-level dimensions: levelDims[level] = {x, y, z}
      voxelSize - physical voxel size at level 0: {sx, sy, sz}
      unit - calibration unit (e.g., "um", "pixel")
      nTimepoints - number of timepoints in the dataset
      setupName - display name for the single ViewSetup (e.g., "unmixed")
      Throws:
      IOException - if the file cannot be written

    • writeBdvN5Xml

      public static void writeBdvN5Xml(File xmlFile, String n5DirName, long[][] levelDims, double[] voxelSize, String unit, int nTimepoints, String setupName, int nChannels) throws IOException
      Throws:
      IOException

    • lockImarisReads

      public static <T extends mpicbg.spim.data.generic.AbstractSpimData<?>> T lockImarisReads(T spimData)
      Serializes all HDF5 reads of an Imaris-backed spimData. BDV's HDF5AccessHack only synchronizes its byte reads: the short and float reads share a mutable hyperslab selection, so concurrent cell loads (e.g., a parallel crop copy plus viewer fetcher threads) can return cells holding data from the wrong chunk. The loader opens lazily and captures its array loader when an image is first requested, so this must be called before any image is obtained from spimData. Does nothing for other loaders, and leaves spimData untouched if reflection fails
      Type Parameters:
      T - the dataset type
      Parameters:
      spimData - the dataset (typically freshly opened)
      Returns:
      spimData, for chaining