Package loci.formats.in

Class PrairieReader

java.lang.Object

loci.formats.FormatHandler

loci.formats.FormatReader

loci.formats.in.PrairieReader

All Implemented Interfaces:

Closeable, 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	Description
static final String[]	CFG_SUFFIX
private String	cfgFile	The associated XML files.
private int[]	channels	List of active channels.
private static final String	DATE_FORMAT
static final String[]	ENV_SUFFIX
private String	envFile	The associated XML files.
private boolean[]	framesAreTime	Whether a series uses Frames as time points rather than focal planes (i.e., sizeZ and sizeT values inverted).
private PrairieMetadata	meta	Format-specific metadata.
static final String[]	PRAIRIE_SUFFIXES
private static final int	PRAIRIE_TAG_1
private static final int	PRAIRIE_TAG_2
private static final int	PRAIRIE_TAG_3
private ArrayList<PrairieMetadata.Sequence>	sequences	List of Prairie metadata Sequences, 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 final String[]	XML_SUFFIX
private 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	Description
PrairieReader()	Constructs a new Prairie TIFF reader.

Method Summary

Modifier and Type	Method	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(String id)	Returns an indication of whether the files in a multi-file dataset can be handled individually.
private loci.common.Location	find(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 String	getPath(PrairieMetadata.PFile file)	Gets the absolute path to the filename of the given PrairieMetadata.PFile.
String[]	getSeriesUsedFiles(boolean noPixels)	Returns an array of filenames needed to open the current series.
protected void	initFile(String id)	Initializes the given file (parsing header information, etc.).
private boolean	isMinimumMetadata()	Gets whether to populate only the minimum required metadata.
boolean	isSingleFile(String id)	Returns true if the named file is expected to be the only file in the dataset.
boolean	isThisType(String name, boolean open)	Checks if a file matches the type of this format reader.
boolean	isThisType(loci.common.RandomAccessInputStream stream)	Checks if the given stream is a valid stream for this file format.
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 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(Double value, 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.ICompressedTileReader

getTileCodec, getTileCodecOptions, openCompressedBytes, openCompressedBytes

Methods inherited from interface loci.formats.IFormatHandler

getFormat, getNativeDataType, getSuffixes

Methods inherited from interface loci.formats.IMetadataConfigurable

getMetadataOptions, getSupportedMetadataLevels, setMetadataOptions

Field Details

CFG_SUFFIX

public static final String[] CFG_SUFFIX

ENV_SUFFIX

public static final String[] ENV_SUFFIX

XML_SUFFIX

public static final String[] XML_SUFFIX

PRAIRIE_SUFFIXES

public static final 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 String DATE_FORMAT

See Also:

• Constant Field Values

tiff

private TiffReader tiff

Helper reader for opening images.

xmlFile

private String xmlFile

The associated XML files.

cfgFile

private String cfgFile

The associated XML files.

envFile

private String envFile

The associated XML files.

meta

private PrairieMetadata meta

Format-specific metadata.

sequences

private ArrayList<PrairieMetadata.Sequence> sequences

List of Prairie metadata Sequences, ordered by cycle.

channels

private int[] channels

List of active channels.

framesAreTime

private boolean[] framesAreTime

Whether a series uses Frames 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 Details

PrairieReader

public PrairieReader()

Constructs a new Prairie TIFF reader.

Method Details

isSingleFile

public boolean isSingleFile(String id)
                     throws FormatException,
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

IOException

isThisType

public boolean isThisType(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

Parameters:

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 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:

IOException

fileGroupOption

public int fileGroupOption(String id)
                    throws FormatException,
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

IOException

See Also:

• FormatTools.MUST_GROUP
• FormatTools.CAN_GROUP
• FormatTools.CANNOT_GROUP

getSeriesUsedFiles

public 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,
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.

IOException - if there was a problem reading the file.

close

public void close(boolean fileOnly)
           throws 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:

IOException

initFile

protected void initFile(String id)
                 throws FormatException,
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.

IOException - if an I/O error occurs processing the file

findMetadataFiles

private void findMetadataFiles()

parsePrairieMetadata

private void parsePrairieMetadata()
                           throws FormatException,
IOException

This step parses the Prairie metadata files into the Prairie-specific metadata structure, meta.

Throws:

FormatException

IOException

populateCoreMetadata

private void populateCoreMetadata()
                           throws FormatException,
IOException

This step populates the CoreMetadata by extracting relevant values from the parsed meta structure.

Throws:

FormatException

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 Document parseDOM(loci.common.Location file)
                   throws ParserConfigurationException,
SAXException,
IOException

Parses a Document from the data in the given file.

Throws:

ParserConfigurationException

SAXException

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 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(Double value,
 String name)

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

find

private loci.common.Location find(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.