loci.formats

## Class DimensionSwapper

- java.lang.Object
- - loci.formats.ReaderWrapper
  - - loci.formats.DimensionSwapper

- All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable, ICompressedTileReader, IFormatHandler, IFormatReader, IMetadataConfigurable, IPyramidHandler

      public class DimensionSwapper
      extends ReaderWrapper

  Handles swapping the dimension order of an image series. This class is useful for both reassigning ZCT sizes (the input dimension order), and shuffling around the resultant planar order (the output dimension order).

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private java.util.List<CoreMetadata>` | `core` Core metadata associated with this dimension swapper.

    - ### Fields inherited from class loci.formats.ReaderWrapper

      `reader`

    - ### Fields inherited from interface loci.formats.IFormatReader

      `CAN_GROUP, CANNOT_GROUP, MUST_GROUP`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DimensionSwapper()` Constructs a DimensionSwapper around a new image reader.
    `DimensionSwapper(IFormatReader r)` Constructs a DimensionSwapper with the given reader.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.util.List<CoreMetadata>` | `getCoreMetadataList()` Obtains the core metadata values for the current file.
    `java.lang.String` | `getDimensionOrder()` Gets a five-character string representing the dimension order in which planes will be returned.
    `int` | `getIndex(int z, int c, int t)` Gets the rasterized index corresponding to the given Z, C and T coordinates (real sizes).
    `int` | `getIndex(int z, int c, int t, int moduloZ, int moduloC, int moduloT)` Gets the rasterized index corresponding to the given Z, C, T, moduloZ, moduloC and moduloT coordinates (effective sizes).
    `java.lang.String` | `getInputOrder()`
    `int` | `getSizeC()` Gets the size of the C dimension.
    `int` | `getSizeT()` Gets the size of the T dimension.
    `int` | `getSizeX()` Gets the size of the X dimension.
    `int` | `getSizeY()` Gets the size of the Y dimension.
    `int` | `getSizeZ()` Gets the size of the Z dimension.
    `Codec` | `getTileCodec(int no)` Retrieve a codec that can be used to decompress compressed tiles.
    `CodecOptions` | `getTileCodecOptions(int no, int x, int y)` Retrieve codec options that can be used to decompressed the specified tile.
    `int[]` | `getZCTCoords(int no)` Gets the Z, C and T coordinates (real sizes) corresponding to the given rasterized index value.
    `int[]` | `getZCTModuloCoords(int index)` Gets the Z, C, T, moduloZ, moduloC and moduloT coordinates (effective sizes) corresponding to the given rasterized index value.
    `static DimensionSwapper` | `makeDimensionSwapper(IFormatReader r)` Converts the given reader into a DimensionSwapper, wrapping if needed.
    `byte[]` | `openBytes(int no)` Obtains the specified image plane from the current file as a byte array.
    `byte[]` | `openBytes(int no, byte[] buf)` Obtains the specified image plane from the current file into a pre-allocated byte array of (sizeX * sizeY * bytesPerPixel * RGB channel count).
    `byte[]` | `openBytes(int no, byte[] buf, int x, int y, int w, int h)` Obtains a sub-image of the specified image plane into a pre-allocated byte array.
    `byte[]` | `openBytes(int no, int x, int y, int w, int h)` Obtains a sub-image of the specified image plane, whose upper-left corner is given by (x, y).
    `byte[]` | `openCompressedBytes(int no, byte[] buf, int x, int y)` Retrieve the specified tile without performing any decompression.
    `byte[]` | `openCompressedBytes(int no, int x, int y)` Retrieve the specified tile without performing any decompression.
    `byte[]` | `openThumbBytes(int no)` Obtains a thumbnail for the specified image plane from the current file, as a byte array.
    `protected int` | `reorder(int no)`
    `void` | `setId(java.lang.String id)` Sets the current file name.
    `void` | `setOutputOrder(java.lang.String outputOrder)` Sets the output dimension order according to the given string (e.g., "XYZCT").
    `void` | `swapDimensions(java.lang.String order)` Sets the input dimension order according to the given string (e.g., "XYZCT").

    - ### Methods inherited from class loci.formats.ReaderWrapper

      `close, close, coreIndexToSeries, duplicate, fileGroupOption, get16BitLookupTable, get8BitLookupTable, getAdvancedSeriesUsedFiles, getAdvancedUsedFiles, getBitsPerPixel, getCoreIndex, getCurrentFile, getDatasetStructureDescription, getDomains, getEffectiveSizeC, getFillColor, getFormat, getGlobalMetadata, getImageCount, getMetadataOptions, getMetadataStore, getMetadataStoreRoot, getMetadataValue, getModuloC, getModuloT, getModuloZ, getNativeDataType, getOptimalTileHeight, getOptimalTileWidth, getPixelType, getPossibleDomains, getReader, getRequiredDirectories, getResolution, getResolutionCount, getRGBChannelCount, getSeries, getSeriesCount, getSeriesMetadata, getSeriesMetadataValue, getSeriesUsedFiles, getSeriesUsedFiles, getSuffixes, getSupportedMetadataLevels, getThumbSizeX, getThumbSizeY, getTileColumns, getTileRows, getUnderlyingReaders, getUsedFiles, getUsedFiles, hasCompanionFiles, hasFlattenedResolutions, isFalseColor, isGroupFiles, isIndexed, isInterleaved, isInterleaved, isLittleEndian, isMetadataComplete, isMetadataFiltered, isNormalized, isOrderCertain, isOriginalMetadataPopulated, isRGB, isSingleFile, isThisType, isThisType, isThisType, isThisType, isThumbnailSeries, openPlane, reopenFile, seriesToCoreIndex, setCoreIndex, setFillColor, setFlattenedResolutions, setGroupFiles, setMetadataFiltered, setMetadataOptions, setMetadataStore, setNormalized, setOriginalMetadataPopulated, setResolution, setSeries, unwrap, unwrap, unwrap`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### core

          private java.util.List<CoreMetadata> core

      Core metadata associated with this dimension swapper.

  - ### Constructor Detail

    - #### DimensionSwapper

          public DimensionSwapper()

      Constructs a DimensionSwapper around a new image reader.

    - #### DimensionSwapper

          public DimensionSwapper(IFormatReader r)

      Constructs a DimensionSwapper with the given reader.

  - ### Method Detail

    - #### makeDimensionSwapper

          public static DimensionSwapper makeDimensionSwapper(IFormatReader r)

      Converts the given reader into a DimensionSwapper, wrapping if needed.

    - #### swapDimensions

          public void swapDimensions(java.lang.String order)

      Sets the input dimension order according to the given string (e.g., "XYZCT"). This string indicates the planar rasterization order from the source, overriding the detected order. It may result in the dimensional axis sizes changing. If the given order is identical to the file's native order, then nothing happens. Note that this method will throw an exception if X and Y do not appear in positions 0 and 1 (although X and Y can be reversed).

    - #### setOutputOrder

          public void setOutputOrder(java.lang.String outputOrder)

      Sets the output dimension order according to the given string (e.g., "XYZCT"). This string indicates the final planar rasterization order—i.e., the mapping from 1D plane number to 3D (Z, C, T) tuple. Changing it will not affect the Z, C or T sizes but will alter the order in which planes are returned when iterating. This method is useful when your application requires a particular output dimension order; e.g., ImageJ virtual stacks must be in XYCZT order.

    - #### getInputOrder

          public java.lang.String getInputOrder()

    - #### getSizeX

          public int getSizeX()

      Description copied from interface: `IFormatReader`
      Gets the size of the X dimension.
      Specified by:
        `getSizeX` in interface `IFormatReader`
      Overrides:
        `getSizeX` in class `ReaderWrapper`

    - #### getSizeY

          public int getSizeY()

      Description copied from interface: `IFormatReader`
      Gets the size of the Y dimension.
      Specified by:
        `getSizeY` in interface `IFormatReader`
      Overrides:
        `getSizeY` in class `ReaderWrapper`

    - #### getSizeZ

          public int getSizeZ()

      Description copied from interface: `IFormatReader`
      Gets the size of the Z dimension.
      Specified by:
        `getSizeZ` in interface `IFormatReader`
      Overrides:
        `getSizeZ` in class `ReaderWrapper`

    - #### getSizeC

          public int getSizeC()

      Description copied from interface: `IFormatReader`
      Gets the size of the C dimension.
      Specified by:
        `getSizeC` in interface `IFormatReader`
      Overrides:
        `getSizeC` in class `ReaderWrapper`

    - #### getSizeT

          public int getSizeT()

      Description copied from interface: `IFormatReader`
      Gets the size of the T dimension.
      Specified by:
        `getSizeT` in interface `IFormatReader`
      Overrides:
        `getSizeT` in class `ReaderWrapper`

    - #### getDimensionOrder

          public java.lang.String getDimensionOrder()

      Description copied from interface: `IFormatReader`
      Gets a five-character string representing the dimension order in which planes will be returned. Valid orders are:
      - XYCTZ
      - XYCZT
      - XYTCZ
      - XYTZC
      - XYZCT
      - XYZTC
      In cases where the channels are interleaved (e.g., CXYTZ), C will be the first dimension after X and Y (e.g., XYCTZ) and the `IFormatReader.isInterleaved()` method will return true.
      Specified by:
        `getDimensionOrder` in interface `IFormatReader`
      Overrides:
        `getDimensionOrder` in class `ReaderWrapper`

    - #### openBytes

          public byte[] openBytes(int no)
                           throws FormatException,
                                  java.io.IOException

      Description copied from interface: `IFormatReader`
      Obtains the specified image plane from the current file as a byte array.
      Specified by:
        `openBytes` in interface `IFormatReader`
      Overrides:
        `openBytes` in class `ReaderWrapper`
      Throws:
        `FormatException`
        `java.io.IOException`
      See Also:
        `IFormatReader.openBytes(int, byte[])`

    - #### openBytes

          public byte[] openBytes(int no,
                                  int x,
                                  int y,
                                  int w,
                                  int h)
                           throws FormatException,
                                  java.io.IOException

      Description copied from interface: `IFormatReader`
      Obtains a sub-image of the specified image plane, whose upper-left corner is given by (x, y).
      Specified by:
        `openBytes` in interface `IFormatReader`
      Overrides:
        `openBytes` in class `ReaderWrapper`
      Throws:
        `FormatException`
        `java.io.IOException`

    - #### openBytes

          public byte[] openBytes(int no,
                                  byte[] buf)
                           throws FormatException,
                                  java.io.IOException

      Description copied from interface: `IFormatReader`
      Obtains the specified image plane from the current file into a pre-allocated byte array of (sizeX * sizeY * bytesPerPixel * RGB channel count).
      Specified by:
        `openBytes` in interface `IFormatReader`
      Overrides:
        `openBytes` in class `ReaderWrapper`
      Parameters:
        `no` - the plane index within the current series.
        `buf` - a pre-allocated buffer.
      Returns:
        the pre-allocated buffer `buf` for convenience.
      Throws:
        `FormatException` - if there was a problem parsing the metadata of the file.
        `java.io.IOException` - if there was a problem reading the file.

    - #### openBytes

          public byte[] openBytes(int no,
                                  byte[] buf,
                                  int x,
                                  int y,
                                  int w,
                                  int h)
                           throws FormatException,
                                  java.io.IOException

      Description copied from interface: `IFormatReader`
      Obtains a sub-image of the specified image plane into a pre-allocated byte array.
      Specified by:
        `openBytes` in interface `IFormatReader`
      Overrides:
        `openBytes` in class `ReaderWrapper`
      Parameters:
        `no` - the plane index within the current series.
        `buf` - a pre-allocated buffer.
        `x` - X coordinate of the upper-left corner of the sub-image
        `y` - Y coordinate of the upper-left corner of the sub-image
        `w` - width of the sub-image
        `h` - height of the sub-image
      Returns:
        the pre-allocated buffer `buf` for convenience.
      Throws:
        `FormatException` - if there was a problem parsing the metadata of the file.
        `java.io.IOException` - if there was a problem reading the file.

    - #### openThumbBytes

          public byte[] openThumbBytes(int no)
                                throws FormatException,
                                       java.io.IOException

      Description copied from interface: `IFormatReader`
      Obtains a thumbnail for the specified image plane from the current file, as a byte array.
      Specified by:
        `openThumbBytes` in interface `IFormatReader`
      Overrides:
        `openThumbBytes` in class `ReaderWrapper`
      Throws:
        `FormatException`
        `java.io.IOException`

    - #### getZCTCoords

          public int[] getZCTCoords(int no)

      Description copied from interface: `IFormatReader`
      Gets the Z, C and T coordinates (real sizes) corresponding to the given rasterized index value.
      Specified by:
        `getZCTCoords` in interface `IFormatReader`
      Overrides:
        `getZCTCoords` in class `ReaderWrapper`

    - #### getZCTModuloCoords

          public int[] getZCTModuloCoords(int index)

      Description copied from interface: `IFormatReader`
      Gets the Z, C, T, moduloZ, moduloC and moduloT coordinates (effective sizes) corresponding to the given rasterized index value. Note that the Z, C and T coordinates are not the same as those returned by getZCTCoords(int) because the size of the modulo dimensions is taken into account. The effective size for each of these dimensions is limited to the total size of the dimension divided by the modulo size.
      Specified by:
        `getZCTModuloCoords` in interface `IFormatReader`
      Overrides:
        `getZCTModuloCoords` in class `ReaderWrapper`

    - #### getIndex

          public int getIndex(int z,
                              int c,
                              int t)

      Description copied from interface: `IFormatReader`
      Gets the rasterized index corresponding to the given Z, C and T coordinates (real sizes).
      Specified by:
        `getIndex` in interface `IFormatReader`
      Overrides:
        `getIndex` in class `ReaderWrapper`

    - #### getIndex

          public int getIndex(int z,
                              int c,
                              int t,
                              int moduloZ,
                              int moduloC,
                              int moduloT)

      Description copied from interface: `IFormatReader`
      Gets the rasterized index corresponding to the given Z, C, T, moduloZ, moduloC and moduloT coordinates (effective sizes). Note that the Z, C and T coordinates take the modulo dimension sizes into account. The effective size for each of these dimensions is limited to the total size of the dimension divided by the modulo size.
      Specified by:
        `getIndex` in interface `IFormatReader`
      Overrides:
        `getIndex` in class `ReaderWrapper`

    - #### getCoreMetadataList

          public java.util.List<CoreMetadata> getCoreMetadataList()

      Description copied from interface: `IFormatReader`
      Obtains the core metadata values for the current file.
      Specified by:
        `getCoreMetadataList` in interface `IFormatReader`
      Overrides:
        `getCoreMetadataList` in class `ReaderWrapper`

    - #### setId

          public void setId(java.lang.String id)
                     throws FormatException,
                            java.io.IOException

      Description copied from interface: `IFormatHandler`
      Sets the current file name.
      Specified by:
        `setId` in interface `IFormatHandler`
      Overrides:
        `setId` in class `ReaderWrapper`
      Throws:
        `FormatException`
        `java.io.IOException`

    - #### openCompressedBytes

          public byte[] openCompressedBytes(int no,
                                            int x,
                                            int y)
                                     throws FormatException,
                                            java.io.IOException

      Description copied from interface: `ICompressedTileReader`
      Retrieve the specified tile without performing any decompression.
      Specified by:
        `openCompressedBytes` in interface `ICompressedTileReader`
      Overrides:
        `openCompressedBytes` in class `ReaderWrapper`
      Parameters:
        `no` - plane index
        `x` - tile X index (indexed from 0, @see getTileColumns(int))
        `y` - tile Y index (indexed from 0, @see getTileRows(int))
      Returns:
        compressed tile bytes
      Throws:
        `FormatException`
        `java.io.IOException`

    - #### openCompressedBytes

          public byte[] openCompressedBytes(int no,
                                            byte[] buf,
                                            int x,
                                            int y)
                                     throws FormatException,
                                            java.io.IOException

      Description copied from interface: `ICompressedTileReader`
      Retrieve the specified tile without performing any decompression.
      Specified by:
        `openCompressedBytes` in interface `ICompressedTileReader`
      Overrides:
        `openCompressedBytes` in class `ReaderWrapper`
      Parameters:
        `no` - plane index
        `buf` - pre-allocated buffer in which to store compressed bytes
        `x` - tile X index (indexed from 0, @see getTileColumns(int))
        `y` - tile Y index (indexed from 0, @see getTileRows(int))
      Returns:
        compressed tile bytes
      Throws:
        `FormatException`
        `java.io.IOException`

    - #### getTileCodec

          public Codec getTileCodec(int no)
                             throws FormatException,
                                    java.io.IOException

      Description copied from interface: `ICompressedTileReader`
      Retrieve a codec that can be used to decompress compressed tiles.
      Specified by:
        `getTileCodec` in interface `ICompressedTileReader`
      Overrides:
        `getTileCodec` in class `ReaderWrapper`
      Parameters:
        `no` - plane index
      Returns:
        codec that can be used for compressed tiles in the specified plane
      Throws:
        `FormatException`
        `java.io.IOException`
      See Also:
        `ICompressedTileReader.openCompressedBytes(int, int, int)`

    - #### getTileCodecOptions

          public CodecOptions getTileCodecOptions(int no,
                                                  int x,
                                                  int y)
                                           throws FormatException,
                                                  java.io.IOException

      Description copied from interface: `ICompressedTileReader`
      Retrieve codec options that can be used to decompressed the specified tile.
      Specified by:
        `getTileCodecOptions` in interface `ICompressedTileReader`
      Overrides:
        `getTileCodecOptions` in class `ReaderWrapper`
      Parameters:
        `no` - plane index
        `x` - tile X index (indexed from 0, @see getTileColumns(int))
        `y` - tile Y index (indexed from 0, @see getTileRows(int))
      Returns:
        codec options
      Throws:
        `FormatException`
        `java.io.IOException`
      See Also:
        `ICompressedTileReader.getTileCodec(int)`

    - #### reorder

          protected int reorder(int no)

Copyright © 2026 Open Microscopy Environment