Package biopb.image

Class Utils

java.lang.Object
biopb.image.Utils
public final class Utils extends Object

  • Method Details

    • SerializeFromInterval

      @Deprecated public static <T extends net.imglib2.type.numeric.RealType<T> & net.imglib2.type.NativeType<T>> Pixels SerializeFromInterval(net.imglib2.RandomAccessibleInterval<T> crop)
      Deprecated.
      Use serializeFromIntervalToImageData(RandomAccessibleInterval) instead to get ImageData protobuf which supports both eager and lazy data.

      This method converts imglib2 image data to a protobuf format suitable for gRPC transmission. The input interval is assumed to be in imglib2's XYZC dimension order (dimension 0 = X, dimension 1 = Y, dimension 2 = Z, dimension 3 = C).

      The original data type is preserved. Big-endian byte order is used.

      Dimension handling:

      • 2D inputs (X, Y) are promoted to 4D by adding singleton Z and C dimensions
      • 3D inputs (X, Y, Z) are promoted to 4D by adding a singleton C dimension
      • 4D inputs (X, Y, Z, C) are used as-is
      • 5D inputs (X, Y, Z, C, T) are used as-is
      Serialize a RandomAccessibleInterval to Pixels protobuf with default dimension order "XYZCT".
      Parameters:
      crop - the input RandomAccessibleInterval to serialize
      Returns:
      a Pixels protobuf message containing the serialized image data
      Throws:
      IllegalArgumentException - if the input has more than 5 dimensions

    • SerializeFromInterval

      @Deprecated public static <T extends net.imglib2.type.numeric.RealType<T> & net.imglib2.type.NativeType<T>> Pixels SerializeFromInterval(net.imglib2.RandomAccessibleInterval<T> crop, String dimensionOrder)
      Deprecated.
      Use serializeFromIntervalToImageData(RandomAccessibleInterval) instead to get ImageData protobuf which supports both eager and lazy data.

      This method converts imglib2 image data to a protobuf format suitable for gRPC transmission. The input interval is assumed to be in imglib2's XYZC dimension order (dimension 0 = X, dimension 1 = Y, dimension 2 = Z, dimension 3 = C).

      The original data type is preserved. Big-endian byte order is used.

      The dimension_order string describes how bytes are laid out in memory:

      • "XYZCT" - X varies fastest (Fortran/memory order), default for imglib2
      • "CXYZT" - C varies fastest (C order), used by Python/numpy

      Dimension handling:

      • 2D inputs (X, Y) are promoted to 4D by adding singleton Z and C dimensions
      • 3D inputs (X, Y, Z) are promoted to 4D by adding a singleton C dimension
      • 4D inputs (X, Y, Z, C) are used as-is
      • 5D inputs (X, Y, Z, C, T) are used as-is
      Serialize a RandomAccessibleInterval to Pixels protobuf with specified dimension order.
      Parameters:
      crop - the input RandomAccessibleInterval to serialize
      dimensionOrder - the dimension order string (e.g., "XYZCT" or "CXYZT"). Must be 5 chars.
      Returns:
      a Pixels protobuf message containing the serialized image data
      Throws:
      IllegalArgumentException - if the input has more than 5 dimensions

    • SerializeFromInterval

      @Deprecated public static <T extends net.imglib2.type.numeric.RealType<T> & net.imglib2.type.NativeType<T>> Pixels SerializeFromInterval(net.imglib2.RandomAccessibleInterval<T> crop, String dimensionOrder, String imglibIndexOrder)
      Deprecated.
      Use serializeFromIntervalToImageData(RandomAccessibleInterval, java.util.List) instead to get ImageData protobuf which supports both eager and lazy data with dimension labels.

      This method converts imglib2 image data to a protobuf format suitable for gRPC transmission. The original data type is preserved.

      Byte order (endianness) is always big-endian in the output.

      Serialize a RandomAccessibleInterval to Pixels protobuf with specified dimension orders.
      Parameters:
      crop - the input RandomAccessibleInterval to serialize
      dimensionOrder - F-order string for output protobuf (must be 5 chars, e.g., "XYZCT"). First letter varies fastest in the serialized bytes.
      imglibIndexOrder - String describing how imglib2 dimensions map to axis letters. First letter = dimension 0, second = dimension 1, etc. If null, inferred from input dimensions: 2D -> "XY", 3D -> "XYZ", 4D -> "XYZC", 5D -> "XYZCT"
      Returns:
      a Pixels protobuf message containing the serialized image data
      Throws:
      IllegalArgumentException - if dimensions are invalid

    • DeserializeToInterval

      @Deprecated public static net.imglib2.RandomAccessibleInterval<?> DeserializeToInterval(Pixels pixels)
      Deprecated.
      Use deserializeImageData(ImageData) instead which handles both eager and lazy data representations.

      This method converts protobuf image data received via gRPC to imglib2 format. The returned interval is in imglib2's XYZC dimension order (dimension 0 = X, dimension 1 = Y, dimension 2 = Z, dimension 3 = C).

      This is equivalent to calling _DeserializeToInterval(Pixels, String) with outputIndexOrder="XYZC".

      Deserialize a Pixels protobuf message to a RandomAccessibleInterval.
      Parameters:
      pixels - the protobuf message containing serialized image data
      Returns:
      a RandomAccessibleInterval in XYZC dimension order
      Throws:
      IllegalArgumentException - if the dimension order is invalid or dtype is unsupported

    • DeserializeToInterval

      @Deprecated public static net.imglib2.RandomAccessibleInterval<?> DeserializeToInterval(Pixels pixels, String outputIndexOrder)
      Deprecated.
      Use deserializeImageData(ImageData) instead which handles both eager and lazy data representations.

      This method converts protobuf image data received via gRPC to imglib2 format. The returned interval has the specified dimension order.

      Supported data types (dtype):

      • "f4" or "float32" - 32-bit float
      • "f8" or "float64" - 64-bit float
      • "u1" or "uint8" - 8-bit unsigned integer
      • "u2" or "uint16" - 16-bit unsigned integer
      • "u4" or "uint32" - 32-bit unsigned integer
      • "i1" or "int8" - 8-bit signed integer
      • "i2" or "int16" - 16-bit signed integer
      • "i4" or "int32" - 32-bit signed integer

      The outputIndexOrder specifies which dimensions to include in the output. Dimensions not in outputIndexOrder are squeezed (must be singleton).

      Byte order (endianness) is read from the BinData field and applied correctly. Dtype prefixes like ">", "<", "|", "=" are automatically stripped for backward compatibility. Note that BinData.endianness is the authoritative source for endianness; a warning is logged if the dtype prefix conflicts with BinData.endianness.

      Deserialize a Pixels protobuf message to a RandomAccessibleInterval with specified output index order.
      Parameters:
      pixels - the protobuf message containing serialized image data
      outputIndexOrder - the desired dimension order of the output (2-5 chars, e.g., "XY", "XYZC", "XYZCT"). Must be a subset permutation of "XYZCT".
      Returns:
      a RandomAccessibleInterval with the specified dimension order
      Throws:
      IllegalArgumentException - if the dimension order is invalid, outputIndexOrder is invalid, a non-singleton dimension is excluded, or dtype is unsupported

    • deserializeImageData

      public static net.imglib2.RandomAccessibleInterval<?> deserializeImageData(ImageData imageData)
      Deserialize an ImageData protobuf message to a RandomAccessibleInterval. Handles both eager_data (inline Tensor) and lazy_data (SerializedTensor). Also handles legacy pixels field for backward compatibility.
      Parameters:
      imageData - the protobuf message containing serialized image data
      Returns:
      a RandomAccessibleInterval (ArrayImg for eager_data, or SerializableTensorImg for lazy_data)
      Throws:
      IllegalArgumentException - if no data field is set or dtype is unsupported

    • tensorFromInterval

      public static <T extends net.imglib2.type.numeric.RealType<T> & net.imglib2.type.NativeType<T>> Tensor tensorFromInterval(net.imglib2.RandomAccessibleInterval<T> interval, List<String> dimLabels)
      Serialize a RandomAccessibleInterval to Tensor protobuf.

      Creates a generic nd tensor with optional dimension labels. The data is stored in C-order (last dimension varies fastest).

      Parameters:
      interval - the input RandomAccessibleInterval to serialize
      dimLabels - optional dimension labels (null if not needed)
      Returns:
      a Tensor protobuf message

    • tensorFromInterval

      public static <T extends net.imglib2.type.numeric.RealType<T> & net.imglib2.type.NativeType<T>> Tensor tensorFromInterval(net.imglib2.RandomAccessibleInterval<T> interval)
      Serialize a RandomAccessibleInterval to Tensor protobuf without dimension labels.

    • intervalFromTensor

      public static net.imglib2.RandomAccessibleInterval<?> intervalFromTensor(Tensor tensor)
      Deserialize a Tensor protobuf to a RandomAccessibleInterval.

      The returned interval has dimensions matching the Tensor's dims field, in C-order (last dimension varies fastest).

      Parameters:
      tensor - the Tensor protobuf message
      Returns:
      a RandomAccessibleInterval (ArrayImg)

    • getImageDataDimLabels

      public static List<String> getImageDataDimLabels(ImageData imageData)
      Get dimension labels from ImageData.
      Parameters:
      imageData - the ImageData protobuf
      Returns:
      list of dimension labels, or null if not available

    • getImageDataShape

      public static long[] getImageDataShape(ImageData imageData)
      Get shape from ImageData.
      Parameters:
      imageData - the ImageData protobuf
      Returns:
      array of dimension sizes, or null if not available

    • serializeFromIntervalToImageData

      public static <T extends net.imglib2.type.numeric.RealType<T> & net.imglib2.type.NativeType<T>> ImageData serializeFromIntervalToImageData(net.imglib2.RandomAccessibleInterval<T> crop)
      Serialize a RandomAccessibleInterval to ImageData protobuf with eager_data.
      Parameters:
      crop - the input RandomAccessibleInterval to serialize
      Returns:
      an ImageData protobuf message with eager_data set
      Throws:
      IllegalArgumentException - if dimensions are invalid

    • serializeFromIntervalToImageData

      public static <T extends net.imglib2.type.numeric.RealType<T> & net.imglib2.type.NativeType<T>> ImageData serializeFromIntervalToImageData(net.imglib2.RandomAccessibleInterval<T> crop, List<String> dimLabels)
      Serialize a RandomAccessibleInterval to ImageData protobuf with eager_data and dimension labels.
      Parameters:
      crop - the input RandomAccessibleInterval to serialize
      dimLabels - dimension labels for the tensor (must match number of dimensions)
      Returns:
      an ImageData protobuf message with eager_data set