loci.formats

## Interface IFormatReader

- All Superinterfaces:
    java.lang.AutoCloseable, java.io.Closeable, ICompressedTileReader, IFormatHandler, IMetadataConfigurable, IPyramidHandler
  All Known Implementing Classes:
    AFIReader, AIMReader, AliconaReader, AmiraReader, AnalyzeReader, APLReader, APNGReader, ARFReader, AVIReader, BaseTiffReader, BaseZeissReader, BDReader, BDVReader, BIFormatReader, BioRadGelReader, BioRadReader, BioRadSCNReader, BMPReader, BrukerReader, BufferedImageReader, BurleighReader, CanonRawReader, CellH5Reader, CellomicsReader, CellSensReader, CellVoyagerReader, CellWorxReader, ChannelFiller, ChannelMerger, ChannelSeparator, ColumbusReader, CV7000Reader, DCIMGReader, DelegateReader, DeltavisionReader, DicomReader, DimensionSwapper, DNGReader, Ecat7Reader, EPSReader, FakeReader, FEIReader, FEITiffReader, FilePatternReader, FileStitcher, FitsReader, FlexReader, FlowSightReader, FluoviewReader, FormatReader, FujiReader, FV1000Reader, GatanDM2Reader, GatanReader, GelReader, GIFReader, HamamatsuVMSReader, HISReader, HitachiReader, HRDGDFReader, I2IReader, ICSReader, IM3Reader, ImaconReader, ImageIOReader, ImageProcessorReader, ImageReader, ImagicReader, ImarisHDFReader, ImarisReader, ImarisTiffReader, IMODReader, ImprovisionTiffReader, ImspectorReader, InCell3000Reader, InCellReader, INRReader, InveonReader, IonpathMIBITiffReader, IPLabReader, IPWReader, IvisionReader, JDCEReader, JEOLReader, JPEG2000Reader, JPEGReader, JPEGReader.DefaultJPEGReader, JPKReader, JPXReader, KhorosReader, KLBReader, KodakReader, L2DReader, LeicaReader, LeicaSCNReader, LEOReader, LiFlimReader, LIFReader, LIMReader, LMSFileReader, LOFReader, Memoizer, MetamorphReader, MetamorphTiffReader, MetaxpressTiffReader, MIASReader, MicroCTReader, MicromanagerReader, MikroscanTiffReader, MINCReader, MinimalTiffReader, MinMaxCalculator, MNGReader, MolecularImagingReader, MRCReader, MRWReader, MultipleImagesReader, NAFReader, ND2Reader, NDPIReader, NDPISReader, NiftiReader, NikonElementsTiffReader, NikonReader, NikonTiffReader, NRRDReader, OBFReader, OIRReader, OlympusTileReader, OMETiffReader, OMEXMLReader, OpenlabRawReader, OpenlabReader, OperettaReader, OxfordInstrumentsReader, PCIReader, PCORAWReader, PCXReader, PDSReader, PerkinElmerReader, PGMReader, PhotoshopTiffReader, PictReader, PovrayReader, PQBinReader, PrairieReader, PSDReader, PyramidTiffReader, QTReader, QuesantReader, RCPNLReader, ReaderWrapper, RHKReader, SBIGReader, ScanrReader, SDTReader, SeikoReader, SEQReader, SIFReader, SimplePCITiffReader, SISReader, SlideBook7Reader, SlidebookReader, SlidebookTiffReader, SMCameraReader, SPCReader, SPEReader, SpiderReader, SubResolutionFormatReader, SVSReader, TargaReader, TCSReader, TecanReader, TextReader, TiffDelegateReader, TiffJAIReader, TiffReader, TileJPEGReader, TileStitcher, TillVisionReader, TissueFAXSReader, TopometrixReader, TrestleReader, UBMReader, UnisokuReader, VarianFDFReader, VectraReader, VeecoReader, VentanaReader, VGSAMReader, VirtualReader, VisitechReader, VolocityClippingReader, VolocityReader, WATOPReader, WrappedReader, XLEFReader, ZeissCZIReader, ZeissLMSReader, ZeissLSMReader, ZeissTIFFReader, ZeissXRMReader, ZeissZVIReader, ZipReader

      public interface IFormatReader
      extends IFormatHandler, IPyramidHandler, ICompressedTileReader

  Interface for all biological file format readers.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `CAN_GROUP`
    `static int` | `CANNOT_GROUP`
    `static int` | `MUST_GROUP` File grouping options.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close(boolean fileOnly)` Closes the currently open file.
    `int` | `coreIndexToSeries(int index)` Deprecated. This method is no longer required for sub-resolution support.
    `int` | `fileGroupOption(java.lang.String id)` Returns an indication of whether the files in a multi-file dataset can be handled individually.
    `short[][]` | `get16BitLookupTable()` Gets the 16-bit color lookup table associated with the most recently opened image.
    `byte[][]` | `get8BitLookupTable()` Gets the 8-bit color lookup table associated with the most recently opened image.
    `FileInfo[]` | `getAdvancedSeriesUsedFiles(boolean noPixels)` Returns an array of FileInfo objects representing the files needed to open the current series.
    `FileInfo[]` | `getAdvancedUsedFiles(boolean noPixels)` Returns an array of FileInfo objects representing the files needed to open this dataset.
    `int` | `getBitsPerPixel()` Gets the number of valid bits per pixel.
    `int` | `getCoreIndex()` Deprecated. This method is no longer required for sub-resolution support.
    `java.util.List<CoreMetadata>` | `getCoreMetadataList()` Deprecated. Reader internals should not be accessed by reader users
    `java.lang.String` | `getCurrentFile()` Returns the current file.
    `java.lang.String` | `getDatasetStructureDescription()` Returns a short description of the dataset structure.
    `java.lang.String` | `getDimensionOrder()` Gets a five-character string representing the dimension order in which planes will be returned.
    `java.lang.String[]` | `getDomains()` Returns the list of domains represented by the current file.
    `int` | `getEffectiveSizeC()` Gets the effective size of the C dimension, guaranteeing that getEffectiveSizeC() * getSizeZ() * getSizeT() == getImageCount() regardless of the result of isRGB().
    `default java.lang.Byte` | `getFillColor()` Return the fill value for undefined pixels.
    `java.util.Hashtable<java.lang.String,java.lang.Object>` | `getGlobalMetadata()` Obtains the hashtable containing the metadata field/value pairs from the current file.
    `int` | `getImageCount()` Determines the number of image planes in the current file.
    `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).
    `MetadataStore` | `getMetadataStore()` Retrieves the current metadata store for this reader.
    `java.lang.Object` | `getMetadataStoreRoot()` Retrieves the current metadata store's root object.
    `java.lang.Object` | `getMetadataValue(java.lang.String field)` Obtains the specified metadata field's value for the current file.
    `Modulo` | `getModuloC()`
    `Modulo` | `getModuloT()`
    `Modulo` | `getModuloZ()`
    `int` | `getOptimalTileHeight()` Returns the optimal sub-image height for use with openBytes.
    `int` | `getOptimalTileWidth()` Returns the optimal sub-image width for use with openBytes.
    `int` | `getPixelType()` Gets the pixel type.
    `java.lang.String[]` | `getPossibleDomains(java.lang.String id)` Returns a list of scientific domains in which this format is used.
    `int` | `getRequiredDirectories(java.lang.String[] files)` Returns the number of parent directories that are important when processing the given list of files.
    `int` | `getRGBChannelCount()` Gets the number of channels returned with each call to openBytes.
    `int` | `getSeries()` Gets the currently active series.
    `int` | `getSeriesCount()` Gets the number of series in this file.
    `java.util.Hashtable<java.lang.String,java.lang.Object>` | `getSeriesMetadata()` Obtains the hashtable containing metadata field/value pairs from the current series in the current file.
    `java.lang.Object` | `getSeriesMetadataValue(java.lang.String field)` Obtains the specified metadata field's value for the current series in the current file.
    `java.lang.String[]` | `getSeriesUsedFiles()` Returns an array of filenames needed to open the current series.
    `java.lang.String[]` | `getSeriesUsedFiles(boolean noPixels)` Returns an array of filenames needed to open the current series.
    `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.
    `int` | `getThumbSizeX()` Get the size of the X dimension for the thumbnail.
    `int` | `getThumbSizeY()` Get the size of the Y dimension for the thumbnail.
    `IFormatReader[]` | `getUnderlyingReaders()` Retrieves all underlying readers.
    `java.lang.String[]` | `getUsedFiles()` Returns an array of filenames needed to open this dataset.
    `java.lang.String[]` | `getUsedFiles(boolean noPixels)` Returns an array of filenames needed to open this dataset.
    `int[]` | `getZCTCoords(int index)` 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.
    `boolean` | `hasCompanionFiles()` Returns true if this format supports multi-file datasets.
    `boolean` | `hasFlattenedResolutions()` Return whether or not resolution flattening is enabled.
    `boolean` | `isFalseColor()` Returns false if `isIndexed()` is false, or if `isIndexed()` is true and the lookup table represents "real" color data.
    `boolean` | `isGroupFiles()` Returns true if we should group files in multi-file formats.
    `boolean` | `isIndexed()` Gets whether the image planes are indexed color.
    `boolean` | `isInterleaved()` Gets whether or not the channels are interleaved.
    `boolean` | `isInterleaved(int subC)` Gets whether or not the given sub-channel is interleaved.
    `boolean` | `isLittleEndian()` Gets whether the data is in little-endian format.
    `boolean` | `isMetadataComplete()` Returns true if this format's metadata is completely parsed.
    `boolean` | `isMetadataFiltered()` Returns true if ugly metadata (entries with unprintable characters, and extremely large entries) are discarded from the metadata table.
    `boolean` | `isNormalized()` Returns true if we should normalize float data.
    `boolean` | `isOrderCertain()` Gets whether the dimension order and sizes are known, or merely guesses.
    `boolean` | `isOriginalMetadataPopulated()` Returns true if we should save proprietary metadata in the MetadataStore.
    `boolean` | `isRGB()` Checks if the image planes in the file have more than one channel per `openBytes(int)` call.
    `boolean` | `isSingleFile(java.lang.String id)` Returns true if the named file is expected to be the only file in the dataset.
    `boolean` | `isThisType(byte[] block)` Checks if the given block is a valid header for this file format.
    `boolean` | `isThisType(loci.common.RandomAccessInputStream stream)` Checks if the given stream is a valid stream for this file format.
    `boolean` | `isThisType(java.lang.String name, boolean open)` Checks if the given file is a valid instance of this file format.
    `boolean` | `isThumbnailSeries()` Gets whether the current series is a lower resolution copy of a different series.
    `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).
    `java.lang.Object` | `openPlane(int no, int x, int y, int w, int h)` Obtains the specified image plane (or sub-image thereof) in the reader's native data structure.
    `byte[]` | `openThumbBytes(int no)` Obtains a thumbnail for the specified image plane from the current file, as a byte array.
    `void` | `reopenFile()` Reopen any files that were closed, and which are expected to be open while the reader is open.
    `int` | `seriesToCoreIndex(int series)` Deprecated. This method is no longer required for sub-resolution support.
    `void` | `setCoreIndex(int no)` Deprecated. This method is no longer required for sub-resolution support.
    `default void` | `setFillColor(java.lang.Byte color)` Set the fill value for undefined pixels.
    `void` | `setFlattenedResolutions(boolean flatten)` Set whether or not to flatten resolutions into individual series.
    `void` | `setGroupFiles(boolean group)` Specifies whether or not to force grouping in multi-file formats.
    `void` | `setMetadataFiltered(boolean filter)` Specifies whether ugly metadata (entries with unprintable characters, and extremely large entries) should be discarded from the metadata table.
    `void` | `setMetadataStore(MetadataStore store)` Sets the default metadata store for this reader.
    `void` | `setNormalized(boolean normalize)` Specifies whether or not to normalize float data.
    `void` | `setOriginalMetadataPopulated(boolean populate)` Specifies whether or not to save proprietary metadata in the MetadataStore.
    `void` | `setSeries(int no)` Activates the specified series.

    - ### Methods inherited from interface loci.formats.IFormatHandler

      `getFormat, getNativeDataType, getSuffixes, isThisType, setId`

    - ### Methods inherited from interface java.io.Closeable

      `close`

    - ### Methods inherited from interface loci.formats.IMetadataConfigurable

      `getMetadataOptions, getSupportedMetadataLevels, setMetadataOptions`

    - ### Methods inherited from interface loci.formats.IPyramidHandler

      `getResolution, getResolutionCount, setResolution`

    - ### Methods inherited from interface loci.formats.ICompressedTileReader

      `getTileCodec, getTileCodecOptions, getTileColumns, getTileRows, openCompressedBytes, openCompressedBytes`

- - ### Field Detail

    - #### MUST_GROUP

          static final int MUST_GROUP

      File grouping options.
      See Also:
        Constant Field Values

    - #### CAN_GROUP

          static final int CAN_GROUP

      See Also:
        Constant Field Values

    - #### CANNOT_GROUP

          static final int CANNOT_GROUP

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### isThisType

          boolean isThisType(java.lang.String name,
                             boolean open)

      Checks if the given file is a valid instance of this file format.
      Parameters:
        `open` - If true, and the file extension is insufficient to determine the file type, the file may be opened for further analysis, or other relatively expensive file system operations (such as file existence tests and directory listings) may be performed. If false, file system access is not allowed.

    - #### isThisType

          boolean isThisType(byte[] block)

      Checks if the given block is a valid header for this file format.
      See Also:
        `isThisType(RandomAccessInputStream)`

    - #### isThisType

          boolean isThisType(loci.common.RandomAccessInputStream stream)
                      throws java.io.IOException

      Checks if the given stream is a valid stream for this file format. The number of bytes read is format-dependent.
      Parameters:
        `stream` - A RandomAccessInputStream representing the file to check. The first byte in the stream is assumed to be the first byte in the file.
      Returns:
        true if the file represented by the stream can be read by this reader; false otherwise.
      Throws:
        `java.io.IOException`

    - #### getImageCount

          int getImageCount()

      Determines the number of image planes in the current file.

    - #### isRGB

          boolean isRGB()

      Checks if the image planes in the file have more than one channel per `openBytes(int)` call. This method returns true if and only if `getRGBChannelCount()` returns a value greater than 1.

    - #### getSizeX

          int getSizeX()

      Gets the size of the X dimension.

    - #### getSizeY

          int getSizeY()

      Gets the size of the Y dimension.

    - #### getSizeZ

          int getSizeZ()

      Gets the size of the Z dimension.

    - #### getSizeC

          int getSizeC()

      Gets the size of the C dimension.

    - #### getSizeT

          int getSizeT()

      Gets the size of the T dimension.

    - #### getPixelType

          int getPixelType()

      Gets the pixel type.
      Returns:
        the pixel type as an enumeration from `FormatTools` static pixel types such as `FormatTools.INT8`.

    - #### getBitsPerPixel

          int getBitsPerPixel()

      Gets the number of valid bits per pixel. The number of valid bits per pixel is always less than or equal to the number of bits per pixel that correspond to `getPixelType()`.

    - #### getEffectiveSizeC

          int getEffectiveSizeC()

      Gets the effective size of the C dimension, guaranteeing that getEffectiveSizeC() * getSizeZ() * getSizeT() == getImageCount() regardless of the result of isRGB().

    - #### getRGBChannelCount

          int getRGBChannelCount()

      Gets the number of channels returned with each call to openBytes. The most common case where this value is greater than 1 is for interleaved RGB data, such as a 24-bit color image plane. However, it is possible for this value to be greater than 1 for non-interleaved data, such as an RGB TIFF with Planar rather than Chunky configuration.

    - #### isIndexed

          boolean isIndexed()

      Gets whether the image planes are indexed color. This value has no impact on `getSizeC()`, `getEffectiveSizeC()` or `getRGBChannelCount()`.

    - #### isFalseColor

          boolean isFalseColor()

      Returns false if `isIndexed()` is false, or if `isIndexed()` is true and the lookup table represents "real" color data. Returns true if `isIndexed()` is true and the lookup table is only present to aid in visualization.

    - #### get8BitLookupTable

          byte[][] get8BitLookupTable()
                               throws FormatException,
                                      java.io.IOException

      Gets the 8-bit color lookup table associated with the most recently opened image. If no image planes have been opened, or if `isIndexed()` returns false, then this may return null. Also, if `getPixelType()` returns anything other than `FormatTools.INT8` or `FormatTools.UINT8`, this method will return null.
      Throws:
        `FormatException`
        `java.io.IOException`

    - #### get16BitLookupTable

          short[][] get16BitLookupTable()
                                 throws FormatException,
                                        java.io.IOException

      Gets the 16-bit color lookup table associated with the most recently opened image. If no image planes have been opened, or if `isIndexed()` returns false, then this may return null. Also, if `getPixelType()` returns anything other than `FormatTools.INT16` or `FormatTools.UINT16`, this method will return null.
      Throws:
        `FormatException`
        `java.io.IOException`

    - #### getModuloZ

          Modulo getModuloZ()

    - #### getModuloC

          Modulo getModuloC()

    - #### getModuloT

          Modulo getModuloT()

    - #### getThumbSizeX

          int getThumbSizeX()

      Get the size of the X dimension for the thumbnail.

    - #### getThumbSizeY

          int getThumbSizeY()

      Get the size of the Y dimension for the thumbnail.

    - #### isLittleEndian

          boolean isLittleEndian()

      Gets whether the data is in little-endian format.

    - #### getDimensionOrder

          java.lang.String getDimensionOrder()

      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 `isInterleaved()` method will return true.

    - #### isOrderCertain

          boolean isOrderCertain()

      Gets whether the dimension order and sizes are known, or merely guesses.

    - #### isThumbnailSeries

          boolean isThumbnailSeries()

      Gets whether the current series is a lower resolution copy of a different series.

    - #### isInterleaved

          boolean isInterleaved()

      Gets whether or not the channels are interleaved. This method exists because X and Y must appear first in the dimension order. For interleaved data, `getDimensionOrder()` returns XYCTZ or XYCZT, and this method returns true. Note that this flag returns whether or not the data returned by `openBytes(int)` is interleaved. In most cases, this will match the interleaving in the original file, but for some formats (e.g. TIFF) channel re-ordering is done internally and the return value of this method will not match what is in the original file.

    - #### isInterleaved

          boolean isInterleaved(int subC)

      Gets whether or not the given sub-channel is interleaved. This method exists because some data with multiple rasterized sub-dimensions within C have one sub-dimension interleaved, and the other not—e.g., `SDTReader` handles spectral-lifetime data with interleaved lifetime bins and non-interleaved spectral channels.

    - #### openBytes

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

      Obtains the specified image plane from the current file as a byte array.
      Throws:
        `FormatException`
        `java.io.IOException`
      See Also:
        `openBytes(int, byte[])`

    - #### openBytes

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

      Obtains a sub-image of the specified image plane, whose upper-left corner is given by (x, y).
      Throws:
        `FormatException`
        `java.io.IOException`

    - #### openBytes

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

      Obtains the specified image plane from the current file into a pre-allocated byte array of (sizeX * sizeY * bytesPerPixel * RGB channel count).
      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

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

      Obtains a sub-image of the specified image plane into a pre-allocated byte array.
      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.

    - #### openPlane

          java.lang.Object openPlane(int no,
                                     int x,
                                     int y,
                                     int w,
                                     int h)
                              throws FormatException,
                                     java.io.IOException

      Obtains the specified image plane (or sub-image thereof) in the reader's native data structure. For most readers this is a byte array; however, some readers call external APIs that work with other types such as `BufferedImage`. The openPlane method exists to maintain generality and efficiency while avoiding pollution of the API with AWT-specific logic.
      Throws:
        `FormatException`
        `java.io.IOException`
      See Also:
        `FormatReader`, `BufferedImageReader`

    - #### openThumbBytes

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

      Obtains a thumbnail for the specified image plane from the current file, as a byte array.
      Throws:
        `FormatException`
        `java.io.IOException`

    - #### close

          void close(boolean fileOnly)
              throws java.io.IOException

      Closes the currently open file. If the flag is set, this is all that happens; if unset, it is equivalent to calling `Closeable.close()`.
      Throws:
        `java.io.IOException`

    - #### getSeriesCount

          int getSeriesCount()

      Gets the number of series in this file.

    - #### setSeries

          void setSeries(int no)

      Activates the specified series. This also resets the resolution to 0.

    - #### getSeries

          int getSeries()

      Gets the currently active series.

    - #### setNormalized

          void setNormalized(boolean normalize)

      Specifies whether or not to normalize float data.

    - #### isNormalized

          boolean isNormalized()

      Returns true if we should normalize float data.

    - #### setOriginalMetadataPopulated

          void setOriginalMetadataPopulated(boolean populate)

      Specifies whether or not to save proprietary metadata in the MetadataStore.

    - #### isOriginalMetadataPopulated

          boolean isOriginalMetadataPopulated()

      Returns true if we should save proprietary metadata in the MetadataStore.

    - #### setGroupFiles

          void setGroupFiles(boolean group)

      Specifies whether or not to force grouping in multi-file formats.
      See Also:
        `fileGroupOption(String)`, `isGroupFiles()`

    - #### isGroupFiles

          boolean isGroupFiles()

      Returns true if we should group files in multi-file formats.
      See Also:
        `setGroupFiles(boolean)`, `fileGroupOption(String)`

    - #### setFillColor

          default void setFillColor(java.lang.Byte color)

      Set the fill value for undefined pixels. This can be used to override the default fill value defined in a reader. The default implementation in IFormatReader is a no-op.
      Parameters:
        `color` - value that will be used to fill pixel byte arrays

    - #### getFillColor

          default java.lang.Byte getFillColor()

      Return the fill value for undefined pixels. The default implementation in IFormatReader always returns 0.
      See Also:
        `setFillColor(Byte)`

    - #### isMetadataComplete

          boolean isMetadataComplete()

      Returns true if this format's metadata is completely parsed.

    - #### fileGroupOption

          int fileGroupOption(java.lang.String id)
                       throws FormatException,
                              java.io.IOException

      Returns an indication of whether the files in a multi-file dataset can be handled individually. This method is only useful for formats and datasets which contain multiple files.
      Parameters:
        `id` - a file in the multi-file dataset
      Returns:
        an int indicating that we cannot, must, or might group the files. A return value of `FormatTools.MUST_GROUP` indicates that the files cannot be handled separately; the reader will always detect and read all files in the dataset. `FormatTools.CAN_GROUP` indicates that the files may be handled separately, but file grouping must then be disabled via `setGroupFiles(boolean)`. `FormatTools.CANNOT_GROUP` indicates that the files must be handled separately; the reader will not attempt to read all files in the dataset (this is rare).
      Throws:
        `FormatException`
        `java.io.IOException`
      See Also:
        `FormatTools.MUST_GROUP`, `FormatTools.CAN_GROUP`, `FormatTools.CANNOT_GROUP`

    - #### getUsedFiles

          java.lang.String[] getUsedFiles()

      Returns an array of filenames needed to open this dataset. The first element in the array is expected to be the path passed to `IFormatHandler.setId(String)`. The remaining elements are expected to be in a consistent order; if a directory listing is necessary to build the list then it should be sorted first.

    - #### getUsedFiles

          java.lang.String[] getUsedFiles(boolean noPixels)

      Returns an array of filenames needed to open this dataset. If the 'noPixels' flag is set, then only files that do not contain pixel data will be returned. The first element in the array is expected to be the path passed to `IFormatHandler.setId(String)`, if appropriate based upon 'noPixels'. The remaining elements are expected to be in a consistent order; if a directory listing is necessary to build the list then it should be sorted first.

    - #### getSeriesUsedFiles

          java.lang.String[] getSeriesUsedFiles()

      Returns an array of filenames needed to open the current series. The first element in the array is expected to be the path passed to `IFormatHandler.setId(String)`. The remaining elements are expected to be in a consistent order; if a directory listing is necessary to build the list then it should be sorted first.

    - #### getSeriesUsedFiles

          java.lang.String[] getSeriesUsedFiles(boolean noPixels)

      Returns an array of filenames needed to open the current series. If the 'noPixels' flag is set, then only files that do not contain pixel data will be returned. The first element in the array is expected to be the path passed to `IFormatHandler.setId(String)`, if appropriate based upon 'noPixels'. The remaining elements are expected to be in a consistent order; if a directory listing is necessary to build the list then it should be sorted first.

    - #### getAdvancedUsedFiles

          FileInfo[] getAdvancedUsedFiles(boolean noPixels)

      Returns an array of FileInfo objects representing the files needed to open this dataset. If the 'noPixels' flag is set, then only files that do not contain pixel data will be returned.

    - #### getAdvancedSeriesUsedFiles

          FileInfo[] getAdvancedSeriesUsedFiles(boolean noPixels)

      Returns an array of FileInfo objects representing the files needed to open the current series. If the 'noPixels' flag is set, then only files that do not contain pixel data will be returned.

    - #### getCurrentFile

          java.lang.String getCurrentFile()

      Returns the current file.

    - #### getDomains

          java.lang.String[] getDomains()

      Returns the list of domains represented by the current file.

    - #### getIndex

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

      Gets the rasterized index corresponding to the given Z, C and T coordinates (real sizes).

    - #### getIndex

          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). 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.

    - #### getZCTCoords

          int[] getZCTCoords(int index)

      Gets the Z, C and T coordinates (real sizes) corresponding to the given rasterized index value.

    - #### getZCTModuloCoords

          int[] getZCTModuloCoords(int index)

      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.

    - #### getMetadataValue

          java.lang.Object getMetadataValue(java.lang.String field)

      Obtains the specified metadata field's value for the current file.
      Parameters:
        `field` - the name associated with the metadata field
      Returns:
        the value, or null if the field doesn't exist

    - #### getSeriesMetadataValue

          java.lang.Object getSeriesMetadataValue(java.lang.String field)

      Obtains the specified metadata field's value for the current series in the current file.
      Parameters:
        `field` - the name associated with the metadata field
      Returns:
        the value, or null if the field doesn't exist

    - #### getGlobalMetadata

          java.util.Hashtable<java.lang.String,java.lang.Object> getGlobalMetadata()

      Obtains the hashtable containing the metadata field/value pairs from the current file.
      Returns:
        the hashtable containing all non-series-specific metadata from the file

    - #### getSeriesMetadata

          java.util.Hashtable<java.lang.String,java.lang.Object> getSeriesMetadata()

      Obtains the hashtable containing metadata field/value pairs from the current series in the current file.

    - #### getCoreMetadataList

          @Deprecated
          java.util.List<CoreMetadata> getCoreMetadataList()

      Deprecated. Reader internals should not be accessed by reader users
      Obtains the core metadata values for the current file.

    - #### setMetadataFiltered

          void setMetadataFiltered(boolean filter)

      Specifies whether ugly metadata (entries with unprintable characters, and extremely large entries) should be discarded from the metadata table.

    - #### isMetadataFiltered

          boolean isMetadataFiltered()

      Returns true if ugly metadata (entries with unprintable characters, and extremely large entries) are discarded from the metadata table.

    - #### setMetadataStore

          void setMetadataStore(MetadataStore store)

      Sets the default metadata store for this reader.
      Parameters:
        `store` - a metadata store implementation.

    - #### getMetadataStore

          MetadataStore getMetadataStore()

      Retrieves the current metadata store for this reader. You can be assured that this method will never return a `null` metadata store.
      Returns:
        A metadata store implementation.

    - #### getMetadataStoreRoot

          java.lang.Object getMetadataStoreRoot()

      Retrieves the current metadata store's root object. It is guaranteed that all file parsing has been performed by the reader prior to retrieval. Requests for a full populated root object should be made using this method.
      Returns:
        Current metadata store's root object fully populated.

    - #### getUnderlyingReaders

          IFormatReader[] getUnderlyingReaders()

      Retrieves all underlying readers. Returns null if there are no underlying readers.

    - #### isSingleFile

          boolean isSingleFile(java.lang.String id)
                        throws FormatException,
                               java.io.IOException

      Returns true if the named file is expected to be the only file in the dataset. For single-file formats, always returns true.
      Throws:
        `FormatException`
        `java.io.IOException`

    - #### getRequiredDirectories

          int getRequiredDirectories(java.lang.String[] files)
                              throws FormatException,
                                     java.io.IOException

      Returns the number of parent directories that are important when processing the given list of files. The number of directories is relative to the common parent. For example, given a list with these two files: /path/to/file/foo /path/to/file/that/is/related A return value of 0 indicates that "/path/to/file/" is irrelevant. A return value of 1 indicates that "/path/to/" is irrelevant. Return values less than 0 are invalid. All listed files are assumed to belong to datasets of the same format.
      Throws:
        `FormatException`
        `java.io.IOException`

    - #### getDatasetStructureDescription

          java.lang.String getDatasetStructureDescription()

      Returns a short description of the dataset structure.

    - #### getPossibleDomains

          java.lang.String[] getPossibleDomains(java.lang.String id)
                                         throws FormatException,
                                                java.io.IOException

      Returns a list of scientific domains in which this format is used.
      Throws:
        `FormatException`
        `java.io.IOException`

    - #### hasCompanionFiles

          boolean hasCompanionFiles()

      Returns true if this format supports multi-file datasets.

    - #### getOptimalTileWidth

          int getOptimalTileWidth()

      Returns the optimal sub-image width for use with openBytes.

    - #### getOptimalTileHeight

          int getOptimalTileHeight()

      Returns the optimal sub-image height for use with openBytes.

    - #### seriesToCoreIndex

          @Deprecated
          int seriesToCoreIndex(int series)

      Deprecated. This method is no longer required for sub-resolution support.
      Returns the first core index corresponding to the specified series.

    - #### coreIndexToSeries

          @Deprecated
          int coreIndexToSeries(int index)

      Deprecated. This method is no longer required for sub-resolution support.
      Returns the series corresponding to the specified core index.

    - #### getCoreIndex

          @Deprecated
          int getCoreIndex()

      Deprecated. This method is no longer required for sub-resolution support.
      Return the index into CoreMetadata of the current resolution/series.

    - #### setCoreIndex

          @Deprecated
          void setCoreIndex(int no)

      Deprecated. This method is no longer required for sub-resolution support.
      Set the current resolution/series (ignores subresolutions). Equivalent to setSeries, but with flattened resolutions always set to false.

    - #### hasFlattenedResolutions

          boolean hasFlattenedResolutions()

      Return whether or not resolution flattening is enabled.

    - #### setFlattenedResolutions

          void setFlattenedResolutions(boolean flatten)

      Set whether or not to flatten resolutions into individual series.

    - #### reopenFile

          void reopenFile()
                   throws java.io.IOException

      Reopen any files that were closed, and which are expected to be open while the reader is open. This assumes that `IFormatHandler.setId(java.lang.String)` has been called, but close(false) has not been called.
      Throws:
        `java.io.IOException`

Copyright © 2026 Open Microscopy Environment