Module org.bonej.bonej_utilities
Package org.bonej.utilities

Class AxisUtils

java.lang.Object
org.bonej.utilities.AxisUtils
public final class AxisUtils extends Object
Various utils for inspecting image axis properties
Author:
Richard Domander

  • Method Details

    • countSpatialDimensions

      public static <S extends net.imagej.space.AnnotatedSpace<A>, A extends net.imagej.axis.TypedAxis> long countSpatialDimensions(S space)
      Counts the number of spatial dimensions in the given space.
      Type Parameters:
      S - type of the space.
      A - type of axes in the space.
      Parameters:
      space - an N-dimensional space.
      Returns:
      number of spatial dimensions in the space.

    • getSpatialUnit

      public static <S extends net.imagej.space.AnnotatedSpace<C>, C extends net.imagej.axis.CalibratedAxis> Optional<String> getSpatialUnit(S space, net.imagej.units.UnitService unitService) throws IllegalArgumentException
      Returns the common unit of the spatial calibrations of the given space.

      The common unit is the unit of the first spatial axis if it can be converted to the units of the other axes.

      Type Parameters:
      S - type of the space.
      C - type of axis in the space
      Parameters:
      space - an n-dimensional space with calibrated axes.
      unitService - an UnitService to convert axis calibrations.
      Returns:
      an optional with the unit of spatial calibration. It's empty if there's no conversion between the units of spatial axes. The Optional contains an empty string none of the axes have a unit, i.e. they're uncalibrated.
      Throws:
      IllegalArgumentException - if space has no spatial axes.

    • hasChannelDimensions

      public static <S extends net.imagej.space.AnnotatedSpace<A>, A extends net.imagej.axis.TypedAxis> boolean hasChannelDimensions(S space)
      Checks if the given space has a channel dimension.
      Type Parameters:
      S - type of the space.
      A - type of axes in the space.
      Parameters:
      space - an N-dimensional space.
      Returns:
      true if there are any channel type axes.

    • hasSpatialDimensions

      public static <S extends net.imagej.space.AnnotatedSpace<A>, A extends net.imagej.axis.TypedAxis> boolean hasSpatialDimensions(S space)
      Checks if the given space has any spatial dimensions.
      Type Parameters:
      S - type of the space.
      A - type of axes in the space.
      Parameters:
      space - an N-dimensional space.
      Returns:
      true if there are any spatial type axes.

    • hasXYDimensions

      public static <S extends net.imagej.space.AnnotatedSpace<A>, A extends net.imagej.axis.TypedAxis> boolean hasXYDimensions(S space)
      Checks if the given annotated space contains both X and Y axes.
      Type Parameters:
      S - type of the space.
      A - type of axes in the space.
      Parameters:
      space - the annotated space to check.
      Returns:
      true if both X and Y axes are present, false otherwise.

    • hasTimeDimensions

      public static <S extends net.imagej.space.AnnotatedSpace<A>, A extends net.imagej.axis.TypedAxis> boolean hasTimeDimensions(S space)
      Checks if the given space has a time dimension.
      Type Parameters:
      S - type of the space.
      A - type of axes in the space.
      Parameters:
      space - an N-dimensional space.
      Returns:
      true if there are any time type axes.

    • hasNonXYZCTDimension

      public static <S extends net.imagej.space.AnnotatedSpace<A>, A extends net.imagej.axis.TypedAxis> boolean hasNonXYZCTDimension(S space)
      Checks whether the given annotated space contains any dimension (axis) that is not one of the standard X, Y, Z, Channel, or Time axes.

      This method is useful for detecting the presence of non-standard axes (e.g., Angle, Lambda, Phase, etc.) in an image or dataset, which may require special handling in algorithms or processing pipelines.

      Type Parameters:
      S - the type of the annotated space, which must extend AnnotatedSpace<A>
      A - the type of the axis, which must extend TypedAxis
      Parameters:
      space - the annotated space (e.g., image or dataset) to check for non-standard dimensions
      Returns:
      true if the space contains at least one axis that is not X, Y, Z, Channel, or Time; false otherwise
      See Also:
      • AnnotatedSpace
      • TypedAxis
      • Axes

    • isSpatialCalibrationsIsotropic

      public static <S extends net.imagej.space.AnnotatedSpace<A>, A extends net.imagej.axis.CalibratedAxis> boolean isSpatialCalibrationsIsotropic(S space, double tolerance, net.imagej.units.UnitService unitService) throws IllegalArgumentException
      Checks if the spatial axes in the space have the same i.e. isotropic scaling.

      If calibrations are isotropic, then the values returned by CalibratedAxis.averageScale(double, double) differ only within the given tolerance. For example, if X-axis scale = 1.00, Y-axis scale = 1.02, and tolerance = 0.03, then calibration is isotropic.

      NB if the calibrations of the axes are not in the same unit, the method tries to convert them to the unit of the first spatial axis (x-axis).

      Type Parameters:
      S - type of the space
      A - type of the axes in the space
      Parameters:
      space - a space with spatial axes
      tolerance - tolerance for anisotropy in scaling
      unitService - service to convert between units of calibration
      Returns:
      true if spatial calibrations are isotropic within tolerance
      Throws:
      IllegalArgumentException - if tolerance is negative or NaN, or calibration units cannot be converted

    • getAnisotropy

      public static <S extends net.imagej.space.AnnotatedSpace<A>, A extends net.imagej.axis.CalibratedAxis> double getAnisotropy(S space, net.imagej.units.UnitService unitService) throws IllegalArgumentException
      Calculates the worst-case anisotropy deviation between spatial axes in the given space.

      This method determines the ratio of the coarsest resolution (largest scale) to the finest resolution (smallest scale) among all spatial dimensions, after converting them to a common unit. The result represents the relative deviation from isotropy:

      • 0.0: The space is perfectly isotropic (all spatial scales are equal).
      • > 0.0: The space is anisotropic. A value of X indicates that the coarsest axis is (X * 100)% larger than the finest axis. (e.g., 2.0 means the coarsest voxel is 3 times larger than the finest).
      • Double.POSITIVE_INFINITY: Returned if the finest scale is zero or negative, indicating undefined or infinite anisotropy.

      The calculation formula is: (max_scale / min_scale) - 1.0.

      Type Parameters:
      S - the type of the annotated space (e.g., Dataset)
      A - the type of the calibrated axis
      Parameters:
      space - the annotated space containing calibration data
      unitService - the UnitService used to convert axis units to a common denominator
      Returns:
      the anisotropy deviation value (0.0 for isotropic, positive for anisotropic, infinity if min scale is <= 0)
      Throws:
      IllegalArgumentException - if:
      • space has no spatial dimensions (X, Y, or Z)
      • the spatial units cannot be converted to a common unit (e.g., mixing time and length)
      • unitService is null
      See Also:

    • getScale

      public static double getScale(net.imagej.Dataset ds, net.imagej.axis.AxisType type)
      Get the interval spacing in real units along an axis
      Parameters:
      ds - the dataset to inspect
      type - the type of axis to check
      Returns:
      the average sample spacing in calibrated units along the given axis

    • has3SpatialDimensions

      public static boolean has3SpatialDimensions(net.imagej.Dataset ds)
      Check whether the dataset has exactly 3 spatial dimensions. Ignores whether there are (or are not) any other dimensions.
      Parameters:
      ds - the dataset to check
      Returns:
      true if the dataset has exactly 3 spatial dimensions

    • has2SpatialDimensions

      public static boolean has2SpatialDimensions(net.imagej.Dataset ds)
      Check whether the dataset has exactly 2 spatial dimensions. Ignores whether there are (or are not) any other dimensions.
      Parameters:
      ds - the dataset to check
      Returns:
      true if the dataset has exactly 2 spatial dimensions

    • hasNSpatialDimensions

      public static boolean hasNSpatialDimensions(net.imagej.Dataset ds, int n)
      Check whether the dataset has exactly N spatial dimensions. Ignores whether there are (or are not) any other dimensions.
      Parameters:
      ds - the dataset to check
      n - the number of spatial dimensions required
      Returns:
      true if the dataset has exactly n spatial dimensions