loci.formats.in

## Class PrairieReader

- java.lang.Object
- - loci.formats.FormatHandler
  - - loci.formats.FormatReader
    - - loci.formats.in.PrairieReader

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

      public class PrairieReader
      extends FormatReader

  PrairieReader is the file format reader for Prairie Technologies' TIFF variant.
  Author:
    Curtis Rueden, Melissa Linkert, Michael Fox

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String[]` | `CFG_SUFFIX`
    `private java.lang.String` | `cfgFile` The associated XML files.
    `private int[]` | `channels` List of active channels.
    `private static java.lang.String` | `DATE_FORMAT`
    `static java.lang.String[]` | `ENV_SUFFIX`
    `private java.lang.String` | `envFile` The associated XML files.
    `private boolean[]` | `framesAreTime` Whether a series uses `Frame`s as time points rather than focal planes (i.e., sizeZ and sizeT values inverted).
    `private PrairieMetadata` | `meta` Format-specific metadata.
    `static java.lang.String[]` | `PRAIRIE_SUFFIXES`
    `private static int` | `PRAIRIE_TAG_1`
    `private static int` | `PRAIRIE_TAG_2`
    `private static int` | `PRAIRIE_TAG_3`
    `private java.util.ArrayList<PrairieMetadata.Sequence>` | `sequences` List of Prairie metadata `Sequence`s, ordered by cycle.
    `private boolean` | `singleTiffMode` Flag indicating that the reader is operating in a mode where grouping of files is disallowed.
    `private TiffReader` | `tiff` Helper reader for opening images.
    `static java.lang.String[]` | `XML_SUFFIX`
    `private java.lang.String` | `xmlFile` The associated XML files.

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

      `core, coreIndex, datasetDescription, domains, fillColor, filterMetadata, flattenedResolutions, group, hasCompanionFiles, in, indexedAsRGB, metadata, metadataStore, normalizeData, resolution, saveOriginalMetadata, series, suffixNecessary, suffixSufficient, THUMBNAIL_DIMENSION`

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

      `COMPRESSION_SUFFIXES, currentId, format, LOGGER, metadataOptions, suffixes`

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

      `CAN_GROUP, CANNOT_GROUP, MUST_GROUP`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PrairieReader()` Constructs a new Prairie TIFF reader.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `private byte[]` | `blank(byte[] buf)` Blanks out and returns the given buffer.
    `void` | `close(boolean fileOnly)` Closes the currently open file.
    `private int` | `computeSizeT(int sequenceCount)` Scans the parsed metadata to determine the number of actual time points versus the number of actual stage positions.
    `private static boolean` | `equal(ome.units.quantity.Length xPos, ome.units.quantity.Length xInitial)` Determines whether the two `Length` values are equal.
    `int` | `fileGroupOption(java.lang.String id)` Returns an indication of whether the files in a multi-file dataset can be handled individually.
    `private loci.common.Location` | `find(java.lang.String[] suffix)` Finds the first file with one of the given suffixes.
    `private void` | `findMetadataFiles()`
    `private int` | `frameIndex(PrairieMetadata.Sequence sequence, int z, int t, int s)` Gets the frame index associated with the given (Z, T) position of the specified series.
    `int` | `getOptimalTileHeight()` Returns the optimal sub-image height for use with openBytes.
    `int` | `getOptimalTileWidth()` Returns the optimal sub-image width for use with openBytes.
    `private java.lang.String` | `getPath(PrairieMetadata.PFile file)` Gets the absolute path to the filename of the given `PrairieMetadata.PFile`.
    `java.lang.String[]` | `getSeriesUsedFiles(boolean noPixels)` Returns an array of filenames needed to open the current series.
    `protected void` | `initFile(java.lang.String id)` Initializes the given file (parsing header information, etc.).
    `private boolean` | `isMinimumMetadata()` Gets whether to populate only the minimum required metadata.
    `boolean` | `isSingleFile(java.lang.String id)` Returns true if the named file is expected to be the only file in the dataset.
    `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 a file matches the type of this format reader.
    `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.
    `private org.w3c.dom.Document` | `parseDOM(loci.common.Location file)` Parses a `Document` from the data in the given file.
    `private void` | `parsePrairieMetadata()` This step parses the Prairie metadata files into the Prairie-specific metadata structure, `meta`.
    `private ome.xml.model.primitives.PositiveFloat` | `pf(java.lang.Double value, java.lang.String name)` Converts the given `double` to a `PositiveFloat`, or `null` if incompatible.
    `private void` | `populateCoreMetadata()` This step populates the `CoreMetadata` by extracting relevant values from the parsed `meta` structure.
    `private void` | `populateOMEMetadata()` This step populates the OME `MetadataStore` by extracting relevant values from the parsed `meta` structure.
    `private void` | `populateOriginalMetadata()` This steps populates the original metadata table (the tables returned by `FormatReader.getGlobalMetadata()` and `FormatReader.getSeriesMetadata()`).
    `private boolean` | `positionsMatch(int sizeT, int sizeP)` Verifies that stage coordinates match for all (P, Z) across time.
    `private PrairieMetadata.Sequence` | `sequence(int s)` Gets the first sequence associated with the given series.
    `private PrairieMetadata.Sequence` | `sequence(int t, int s)` Gets the sequence associated with the given series and time point.
    `private PrairieMetadata.Sequence` | `sequence(int t, int p, int sizeP)` Gets the sequence associated with the given time point and stage position.
    `private void` | `warnFile(PrairieMetadata.Sequence sequence, int index, int channel)` Emits a warning about a missing `<File>`.
    `private void` | `warnFilename(PrairieMetadata.Sequence sequence, int index, int channel)` Emits a warning about a `<File>`'s missing `filename`.
    `private void` | `warnFrame(PrairieMetadata.Sequence sequence, int index)` Emits a warning about a missing `<Frame>`.

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

      `addGlobalMeta, addGlobalMeta, addGlobalMeta, addGlobalMeta, addGlobalMeta, addGlobalMeta, addGlobalMeta, addGlobalMeta, addGlobalMeta, addGlobalMetaList, addMeta, addMetaList, addSeriesMeta, addSeriesMeta, addSeriesMeta, addSeriesMeta, addSeriesMeta, addSeriesMeta, addSeriesMeta, addSeriesMeta, addSeriesMeta, addSeriesMetaList, close, coreIndexToSeries, flattenHashtables, get16BitLookupTable, get8BitLookupTable, getAcquisitionMode, getAdvancedSeriesUsedFiles, getAdvancedUsedFiles, getArcType, getAvailableOptions, getBinning, getBitsPerPixel, getCompression, getContrastMethod, getCoreIndex, getCoreMetadataList, getCorrection, getCurrentCore, getCurrentFile, getDatasetStructureDescription, getDetectorType, getDimensionOrder, getDimensionOrder, getDomains, getEffectiveSizeC, getExperimentType, getFilamentType, getFillColor, getFillRule, getFilterType, getFontFamily, getFontStyle, getGlobalMeta, getGlobalMetadata, getIlluminationType, getImageCount, getImmersion, getIndex, getIndex, getLaserMedium, getLaserType, getMarker, getMedium, getMetadataStore, getMetadataStoreRoot, getMetadataValue, getMicrobeamManipulationType, getMicroscopeType, getModuloC, getModuloT, getModuloZ, getNamingConvention, getPixelType, getPixelType, getPossibleDomains, getPulse, getRequiredDirectories, getResolution, getResolutionCount, getRGBChannelCount, getRotationTransform, getSeries, getSeriesCount, getSeriesMeta, getSeriesMetadata, getSeriesMetadataValue, getSeriesUsedFiles, getSizeC, getSizeT, getSizeX, getSizeY, getSizeZ, getThumbSizeX, getThumbSizeY, getTileColumns, getTileRows, getUnderlyingReaders, getUsedFiles, getUsedFiles, getZCTCoords, getZCTModuloCoords, hasCompanionFiles, hasFlattenedResolutions, isFalseColor, isGroupFiles, isIndexed, isInterleaved, isInterleaved, isLittleEndian, isMetadataComplete, isMetadataFiltered, isNormalized, isOrderCertain, isOriginalMetadataPopulated, isRGB, isThisType, isThisType, isThumbnailSeries, isUsedFile, makeFilterMetadata, openBytes, openBytes, openBytes, openPlane, openThumbBytes, readPlane, readPlane, readPlane, reopenFile, seriesToCoreIndex, setCoreIndex, setFillColor, setFlattenedResolutions, setGroupFiles, setId, setMetadataFiltered, setMetadataStore, setNormalized, setOriginalMetadataPopulated, setResolution, setSeries, updateMetadataLists`

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

      `checkSuffix, checkSuffix, getFormat, getMetadataOptions, getNativeDataType, getSuffixes, getSupportedMetadataLevels, setMetadataOptions`

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

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

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

      `getFormat, getNativeDataType, getSuffixes`

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

      `getMetadataOptions, getSupportedMetadataLevels, setMetadataOptions`

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

      `getTileCodec, getTileCodecOptions, openCompressedBytes, openCompressedBytes`

- - ### Field Detail

    - #### CFG_SUFFIX

          public static final java.lang.String[] CFG_SUFFIX

    - #### ENV_SUFFIX

          public static final java.lang.String[] ENV_SUFFIX

    - #### XML_SUFFIX

          public static final java.lang.String[] XML_SUFFIX

    - #### PRAIRIE_SUFFIXES

          public static final java.lang.String[] PRAIRIE_SUFFIXES

    - #### PRAIRIE_TAG_1

          private static final int PRAIRIE_TAG_1

      See Also:
        Constant Field Values

    - #### PRAIRIE_TAG_2

          private static final int PRAIRIE_TAG_2

      See Also:
        Constant Field Values

    - #### PRAIRIE_TAG_3

          private static final int PRAIRIE_TAG_3

      See Also:
        Constant Field Values

    - #### DATE_FORMAT

          private static final java.lang.String DATE_FORMAT

      See Also:
        Constant Field Values

    - #### tiff

          private TiffReader tiff

      Helper reader for opening images.

    - #### xmlFile

          private java.lang.String xmlFile

      The associated XML files.

    - #### cfgFile

          private java.lang.String cfgFile

      The associated XML files.

    - #### envFile

          private java.lang.String envFile

      The associated XML files.

    - #### meta

          private PrairieMetadata meta

      Format-specific metadata.

    - #### sequences

          private java.util.ArrayList<PrairieMetadata.Sequence> sequences

      List of Prairie metadata `Sequence`s, ordered by cycle.

    - #### channels

          private int[] channels

      List of active channels.

    - #### framesAreTime

          private boolean[] framesAreTime

      Whether a series uses `Frame`s as time points rather than focal planes (i.e., sizeZ and sizeT values inverted).

      This situation occurs when the series's first `Sequence` is labeled as a "TSeries" (i.e., `PrairieMetadata.Sequence.isTimeSeries()` returns true), but there is only one `Sequence`.

      The array length equals the number of series; i.e., it is a parallel array to `FormatReader.core`.

    - #### singleTiffMode

          private boolean singleTiffMode

      Flag indicating that the reader is operating in a mode where grouping of files is disallowed. In the case of Prairie, this happens if a TIFF file is passed to `FormatReader.setId(java.lang.String)` while `FormatReader.isGroupFiles()` is `false`.

  - ### Constructor Detail

    - #### PrairieReader

          public PrairieReader()

      Constructs a new Prairie TIFF reader.

  - ### Method Detail

    - #### isSingleFile

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

      Description copied from interface: `IFormatReader`
      Returns true if the named file is expected to be the only file in the dataset. For single-file formats, always returns true.
      Specified by:
        `isSingleFile` in interface `IFormatReader`
      Overrides:
        `isSingleFile` in class `FormatReader`
      Throws:
        `FormatException`
        `java.io.IOException`

    - #### isThisType

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

      Description copied from class: `FormatReader`
      Checks if a file matches the type of this format reader. Checks filename suffixes against those known for this format. If the suffix check is inconclusive and the open parameter is true, the file is opened and tested with `FormatReader.isThisType(RandomAccessInputStream)`.
      Specified by:
        `isThisType` in interface `IFormatReader`
      Overrides:
        `isThisType` in class `FormatReader`
        `open` - If true, and the file extension is insufficient to determine the file type, the (existing) file is opened for further analysis.

    - #### isThisType

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

      Description copied from interface: `IFormatReader`
      Checks if the given stream is a valid stream for this file format. The number of bytes read is format-dependent.
      Specified by:
        `isThisType` in interface `IFormatReader`
      Overrides:
        `isThisType` in class `FormatReader`
      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`

    - #### fileGroupOption

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

      Description copied from interface: `IFormatReader`
      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.
      Specified by:
        `fileGroupOption` in interface `IFormatReader`
      Overrides:
        `fileGroupOption` in class `FormatReader`
      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 `IFormatReader.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`

    - #### getSeriesUsedFiles

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

      Description copied from interface: `IFormatReader`
      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.
      Specified by:
        `getSeriesUsedFiles` in interface `IFormatReader`
      Overrides:
        `getSeriesUsedFiles` in class `FormatReader`

    - #### getOptimalTileWidth

          public int getOptimalTileWidth()

      Description copied from interface: `IFormatReader`
      Returns the optimal sub-image width for use with openBytes.
      Specified by:
        `getOptimalTileWidth` in interface `IFormatReader`
      Overrides:
        `getOptimalTileWidth` in class `FormatReader`

    - #### getOptimalTileHeight

          public int getOptimalTileHeight()

      Description copied from interface: `IFormatReader`
      Returns the optimal sub-image height for use with openBytes.
      Specified by:
        `getOptimalTileHeight` in interface `IFormatReader`
      Overrides:
        `getOptimalTileHeight` in class `FormatReader`

    - #### 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`
      Specified by:
        `openBytes` in class `FormatReader`
      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.

    - #### close

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

      Description copied from interface: `IFormatReader`
      Closes the currently open file. If the flag is set, this is all that happens; if unset, it is equivalent to calling `Closeable.close()`.
      Specified by:
        `close` in interface `IFormatReader`
      Overrides:
        `close` in class `FormatReader`
      Throws:
        `java.io.IOException`

    - #### initFile

          protected void initFile(java.lang.String id)
                           throws FormatException,
                                  java.io.IOException

      Description copied from class: `FormatReader`
      Initializes the given file (parsing header information, etc.). Most subclasses should override this method to perform initialization operations such as parsing metadata.
      Overrides:
        `initFile` in class `FormatReader`
      Throws:
        `FormatException` - if a parsing error occurs processing the file.
        `java.io.IOException` - if an I/O error occurs processing the file

    - #### findMetadataFiles

          private void findMetadataFiles()

    - #### parsePrairieMetadata

          private void parsePrairieMetadata()
                                     throws FormatException,
                                            java.io.IOException

      This step parses the Prairie metadata files into the Prairie-specific metadata structure, `meta`.
      Throws:
        `FormatException`
        `java.io.IOException`

    - #### populateCoreMetadata

          private void populateCoreMetadata()
                                     throws FormatException,
                                            java.io.IOException

      This step populates the `CoreMetadata` by extracting relevant values from the parsed `meta` structure.
      Throws:
        `FormatException`
        `java.io.IOException`

    - #### populateOriginalMetadata

          private void populateOriginalMetadata()

      This steps populates the original metadata table (the tables returned by `FormatReader.getGlobalMetadata()` and `FormatReader.getSeriesMetadata()`).

    - #### populateOMEMetadata

          private void populateOMEMetadata()
                                    throws FormatException

      This step populates the OME `MetadataStore` by extracting relevant values from the parsed `meta` structure.
      Throws:
        `FormatException`

    - #### isMinimumMetadata

          private boolean isMinimumMetadata()

      Gets whether to populate only the minimum required metadata.

    - #### parseDOM

          private org.w3c.dom.Document parseDOM(loci.common.Location file)
                                         throws javax.xml.parsers.ParserConfigurationException,
                                                org.xml.sax.SAXException,
                                                java.io.IOException

      Parses a `Document` from the data in the given file.
      Throws:
        `javax.xml.parsers.ParserConfigurationException`
        `org.xml.sax.SAXException`
        `java.io.IOException`

    - #### warnFrame

          private void warnFrame(PrairieMetadata.Sequence sequence,
                                 int index)

      Emits a warning about a missing `<Frame>`.

    - #### warnFile

          private void warnFile(PrairieMetadata.Sequence sequence,
                                int index,
                                int channel)

      Emits a warning about a missing `<File>`.

    - #### warnFilename

          private void warnFilename(PrairieMetadata.Sequence sequence,
                                    int index,
                                    int channel)

      Emits a warning about a `<File>`'s missing `filename`.

    - #### getPath

          private java.lang.String getPath(PrairieMetadata.PFile file)

      Gets the absolute path to the filename of the given `PrairieMetadata.PFile`.

    - #### blank

          private byte[] blank(byte[] buf)

      Blanks out and returns the given buffer.

    - #### pf

          private ome.xml.model.primitives.PositiveFloat pf(java.lang.Double value,
                                                            java.lang.String name)

      Converts the given `double` to a `PositiveFloat`, or `null` if incompatible.

    - #### find

          private loci.common.Location find(java.lang.String[] suffix)

      Finds the first file with one of the given suffixes.

    - #### computeSizeT

          private int computeSizeT(int sequenceCount)

      Scans the parsed metadata to determine the number of actual time points versus the number of actual stage positions. The Prairie file format makes no distinction between the two, referring to both as "Sequences", so we must compare XYZ stage positions to differentiate them.

    - #### positionsMatch

          private boolean positionsMatch(int sizeT,
                                         int sizeP)

      Verifies that stage coordinates match for all (P, Z) across time.

    - #### sequence

          private PrairieMetadata.Sequence sequence(int s)

      Gets the first sequence associated with the given series.
      Parameters:
        `s` - The series (i.e., stage position).
      Returns:
        The first associated `Sequence`.

    - #### sequence

          private PrairieMetadata.Sequence sequence(int t,
                                                    int s)

      Gets the sequence associated with the given series and time point.
      Parameters:
        `t` - The time point.
        `s` - The series (i.e., stage position).
      Returns:
        The associated `Sequence`.

    - #### sequence

          private PrairieMetadata.Sequence sequence(int t,
                                                    int p,
                                                    int sizeP)

      Gets the sequence associated with the given time point and stage position.
      Parameters:
        `t` - The time point.
        `p` - The stage position.
        `sizeP` - The number of stage positions.
      Returns:
        The associated `Sequence`.

    - #### frameIndex

          private int frameIndex(PrairieMetadata.Sequence sequence,
                                 int z,
                                 int t,
                                 int s)

      Gets the frame index associated with the given (Z, T) position of the specified series.
      Parameters:
        `sequence` - The sequence from which to extract the frame.
        `z` - The focal plane.
        `t` - The time point.
        `s` - The series (i.e., stage position).
      Returns:
        The frame index which can be passed to `PrairieMetadata.Sequence.getFrame(int)`.

    - #### equal

          private static boolean equal(ome.units.quantity.Length xPos,
                                       ome.units.quantity.Length xInitial)

      Determines whether the two `Length` values are equal.

Copyright © 2026 Open Microscopy Environment