Package loci.formats

Class ImageReader

java.lang.Object

loci.formats.ImageReader

All Implemented Interfaces:

Closeable, AutoCloseable, ICompressedTileReader, IFormatHandler, IFormatReader, IMetadataConfigurable, IPyramidHandler

public class ImageReader
extends Object
implements IFormatReader

ImageReader is the master file format reader for all supported formats. It uses one instance of each reader subclass (specified in readers.txt, or other class list source) to identify file formats and read data.

Field Summary

Fields inherited from interface loci.formats.IFormatReader

CAN_GROUP, CANNOT_GROUP, MUST_GROUP

Constructor Summary

Constructors

Constructor	Description
ImageReader()	Constructs a new ImageReader with the default list of reader classes from readers.txt.
ImageReader(ClassList<IFormatReader> classList)	Constructs a new ImageReader from the given list of reader classes.

Method Summary

Modifier and Type	Method	Description
void	close()
void	close(boolean fileOnly)	Closes the currently open file.
int	coreIndexToSeries(int index)	Returns the series corresponding to the specified core index.
int	fileGroupOption(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()	Return the index into CoreMetadata of the current resolution/series.
List<CoreMetadata>	getCoreMetadataList()	Obtains the core metadata values for the current file.
String	getCurrentFile()	Returns the current file.
String	getDatasetStructureDescription()	Returns a short description of the dataset structure.
static ClassList<IFormatReader>	getDefaultReaderClasses()
String	getDimensionOrder()	Gets a five-character string representing the dimension order in which planes will be returned.
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().
Byte	getFillColor()	Return the fill value for undefined pixels.
String	getFormat()	Gets the name of this file format.
String	getFormat(String id)	Gets a string describing the file format for the given file.
Hashtable<String,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).
MetadataOptions	getMetadataOptions()
MetadataStore	getMetadataStore()	Retrieves the current metadata store for this reader.
Object	getMetadataStoreRoot()	Retrieves the current metadata store's root object.
Object	getMetadataValue(String field)	Obtains the specified metadata field's value for the current file.
Modulo	getModuloC()
Modulo	getModuloT()
Modulo	getModuloZ()
Class<?>	getNativeDataType()	Returns the native data type of image planes for this reader, as returned by IFormatReader.openPlane(int, int, int, int, int) or IFormatWriter.savePlane(int, java.lang.Object).
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.
String[]	getPossibleDomains(String id)	Returns a list of scientific domains in which this format is used.
IFormatReader	getReader()	Gets the reader used to open the current file.
IFormatReader	getReader(Class<? extends IFormatReader> c)	Gets the file format reader instance matching the given class.
IFormatReader	getReader(String id)	Gets the reader used to open the given file.
IFormatReader[]	getReaders()	Gets all constituent file format readers.
int	getRequiredDirectories(String[] files)	Returns the number of parent directories that are important when processing the given list of files.
int	getResolution()	Get the current resolution level.
int	getResolutionCount()	Return the number of resolutions for the current series.
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.
Hashtable<String,Object>	getSeriesMetadata()	Obtains the hashtable containing metadata field/value pairs from the current series in the current file.
Object	getSeriesMetadataValue(String field)	Obtains the specified metadata field's value for the current series in the current file.
String[]	getSeriesUsedFiles()	Returns an array of filenames needed to open the current series.
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.
String[]	getSuffixes()	Gets the default file suffixes for this file format.
Set<MetadataLevel>	getSupportedMetadataLevels()
int	getThumbSizeX()	Get the size of the X dimension for the thumbnail.
int	getThumbSizeY()	Get the size of the Y dimension for the thumbnail.
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	getTileColumns(int no)	Get the number of columns of tiles in the specified plane in the current series.
int	getTileRows(int no)	Get the number of rows of tiles in the specified plane in the current series.
IFormatReader[]	getUnderlyingReaders()	Retrieves all underlying readers.
String[]	getUsedFiles()	Returns an array of filenames needed to open this dataset.
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 IFormatReader.isIndexed() is false, or if IFormatReader.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 IFormatReader.openBytes(int) call.
boolean	isSingleFile(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(String name)	Checks if the given string is a valid filename for this file format.
boolean	isThisType(String name, boolean open)	Checks if the given file is a valid instance of this file format.
boolean	isThisType(RandomAccessInputStream stream)	Checks if the given stream is a valid stream for 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).
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.
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)	Returns the first core index corresponding to the specified series.
void	setAllowOpenFiles(boolean allowOpen)	Toggles whether or not file system access is allowed when doing type detection.
void	setCoreIndex(int no)	Set the current resolution/series (ignores subresolutions).
void	setFillColor(Byte fill)	Set the fill value for undefined pixels.
void	setFlattenedResolutions(boolean flattened)	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	setId(String id)	Sets the current file name.
void	setMetadataFiltered(boolean filter)	Specifies whether ugly metadata (entries with unprintable characters, and extremely large entries) should be discarded from the metadata table.
void	setMetadataOptions(MetadataOptions options)
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	setResolution(int no)	Set the resolution level.
void	setSeries(int no)	Activates the specified series.

Methods inherited from class java.lang.Object

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

Constructor Details

ImageReader

public ImageReader()

Constructs a new ImageReader with the default list of reader classes from readers.txt.

ImageReader

public ImageReader(ClassList<IFormatReader> classList)

Constructs a new ImageReader from the given list of reader classes.

Method Details

getDefaultReaderClasses

public static ClassList<IFormatReader> getDefaultReaderClasses()

setAllowOpenFiles

public void setAllowOpenFiles(boolean allowOpen)

Toggles whether or not file system access is allowed when doing type detection. By default, file system access is allowed.

getFormat

public String getFormat(String id)
                 throws FormatException,
IOException

Gets a string describing the file format for the given file.

Throws:

FormatException

IOException

getReader

public IFormatReader getReader(String id)
                        throws FormatException,
IOException

Gets the reader used to open the given file.

Throws:

FormatException

IOException

getReader

public IFormatReader getReader()

Gets the reader used to open the current file.

getReader

public IFormatReader getReader(Class<? extends IFormatReader> c)

Gets the file format reader instance matching the given class.

getReaders

public IFormatReader[] getReaders()

Gets all constituent file format readers.

getSupportedMetadataLevels

public Set<MetadataLevel> getSupportedMetadataLevels()

Specified by:

getSupportedMetadataLevels in interface IMetadataConfigurable

getMetadataOptions

public MetadataOptions getMetadataOptions()

Specified by:

getMetadataOptions in interface IMetadataConfigurable

setMetadataOptions

public void setMetadataOptions(MetadataOptions options)

Specified by:

setMetadataOptions in interface IMetadataConfigurable

See Also:

• IMetadataConfigurable.setMetadataOptions(MetadataOptions)

isThisType

public boolean isThisType(String name,
 boolean open)

Description copied from interface: IFormatReader

Checks if the given file is a valid instance of this file format.

Specified by:

isThisType in interface IFormatReader

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

public boolean isThisType(byte[] block)

Description copied from interface: IFormatReader

Checks if the given block is a valid header for this file format.

Specified by:

isThisType in interface IFormatReader

See Also:

• IFormatReader.isThisType(RandomAccessInputStream)

isThisType

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

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

getImageCount

public int getImageCount()

Description copied from interface: IFormatReader

Determines the number of image planes in the current file.

Specified by:

getImageCount in interface IFormatReader

isRGB

public boolean isRGB()

Description copied from interface: IFormatReader

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

Specified by:

isRGB in interface IFormatReader

getSizeX

public int getSizeX()

Description copied from interface: IFormatReader

Gets the size of the X dimension.

Specified by:

getSizeX in interface IFormatReader

getSizeY

public int getSizeY()

Description copied from interface: IFormatReader

Gets the size of the Y dimension.

Specified by:

getSizeY in interface IFormatReader

getSizeC

public int getSizeC()

Description copied from interface: IFormatReader

Gets the size of the C dimension.

Specified by:

getSizeC in interface IFormatReader

getSizeZ

public int getSizeZ()

Description copied from interface: IFormatReader

Gets the size of the Z dimension.

Specified by:

getSizeZ in interface IFormatReader

getSizeT

public int getSizeT()

Description copied from interface: IFormatReader

Gets the size of the T dimension.

Specified by:

getSizeT in interface IFormatReader

getPixelType

public int getPixelType()

Description copied from interface: IFormatReader

Gets the pixel type.

Specified by:

getPixelType in interface IFormatReader

Returns:

the pixel type as an enumeration from FormatTools static pixel types such as FormatTools.INT8.

getBitsPerPixel

public int getBitsPerPixel()

Description copied from interface: IFormatReader

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 IFormatReader.getPixelType().

Specified by:

getBitsPerPixel in interface IFormatReader

getEffectiveSizeC

public int getEffectiveSizeC()

Description copied from interface: IFormatReader

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

Specified by:

getEffectiveSizeC in interface IFormatReader

getRGBChannelCount

public int getRGBChannelCount()

Description copied from interface: IFormatReader

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.

Specified by:

getRGBChannelCount in interface IFormatReader

isIndexed

public boolean isIndexed()

Description copied from interface: IFormatReader

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

Specified by:

isIndexed in interface IFormatReader

isFalseColor

public boolean isFalseColor()

Description copied from interface: IFormatReader

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

Specified by:

isFalseColor in interface IFormatReader

get8BitLookupTable

public byte[][] get8BitLookupTable()
                            throws FormatException,
IOException

Description copied from interface: IFormatReader

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

Specified by:

get8BitLookupTable in interface IFormatReader

Throws:

FormatException

IOException

get16BitLookupTable

public short[][] get16BitLookupTable()
                              throws FormatException,
IOException

Description copied from interface: IFormatReader

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

Specified by:

get16BitLookupTable in interface IFormatReader

Throws:

FormatException

IOException

getModuloZ

public Modulo getModuloZ()

Specified by:

getModuloZ in interface IFormatReader

getModuloC

public Modulo getModuloC()

Specified by:

getModuloC in interface IFormatReader

getModuloT

public Modulo getModuloT()

Specified by:

getModuloT in interface IFormatReader

getThumbSizeX

public int getThumbSizeX()

Description copied from interface: IFormatReader

Get the size of the X dimension for the thumbnail.

Specified by:

getThumbSizeX in interface IFormatReader

getThumbSizeY

public int getThumbSizeY()

Description copied from interface: IFormatReader

Get the size of the Y dimension for the thumbnail.

Specified by:

getThumbSizeY in interface IFormatReader

isLittleEndian

public boolean isLittleEndian()

Description copied from interface: IFormatReader

Gets whether the data is in little-endian format.

Specified by:

isLittleEndian in interface IFormatReader

getDimensionOrder

public 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

isOrderCertain

public boolean isOrderCertain()

Description copied from interface: IFormatReader

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

Specified by:

isOrderCertain in interface IFormatReader

isThumbnailSeries

public boolean isThumbnailSeries()

Description copied from interface: IFormatReader

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

Specified by:

isThumbnailSeries in interface IFormatReader

isInterleaved

public boolean isInterleaved()

Description copied from interface: IFormatReader

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, IFormatReader.getDimensionOrder() returns XYCTZ or XYCZT, and this method returns true. Note that this flag returns whether or not the data returned by IFormatReader.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.

Specified by:

isInterleaved in interface IFormatReader

isInterleaved

public boolean isInterleaved(int subC)

Description copied from interface: IFormatReader

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

invalid reference

loci.formats.in.SDTReader

handles spectral-lifetime data with interleaved lifetime bins and non-interleaved spectral channels.

Specified by:

isInterleaved in interface IFormatReader

openBytes

public byte[] openBytes(int no)
                 throws FormatException,
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

Throws:

FormatException

IOException

See Also:

• IFormatReader.openBytes(int, byte[])

openBytes

public byte[] openBytes(int no,
 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, whose upper-left corner is given by (x, y).

Specified by:

openBytes in interface IFormatReader

Throws:

FormatException

IOException

openBytes

public byte[] openBytes(int no,
 byte[] buf)
                 throws FormatException,
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

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.

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

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.

openPlane

public Object openPlane(int no,
 int x,
 int y,
 int w,
 int h)
                 throws FormatException,
IOException

Description copied from interface: IFormatReader

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.

Specified by:

openPlane in interface IFormatReader

Throws:

FormatException

IOException

See Also:

• FormatReader
• invalid reference

  loci.formats.gui.BufferedImageReader

openThumbBytes

public byte[] openThumbBytes(int no)
                      throws FormatException,
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

Throws:

FormatException

IOException

getSeriesCount

public int getSeriesCount()

Description copied from interface: IFormatReader

Gets the number of series in this file.

Specified by:

getSeriesCount in interface IFormatReader

setSeries

public void setSeries(int no)

Description copied from interface: IFormatReader

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

Specified by:

setSeries in interface IFormatReader

getSeries

public int getSeries()

Description copied from interface: IFormatReader

Gets the currently active series.

Specified by:

getSeries in interface IFormatReader

getUsedFiles

public String[] getUsedFiles()

Description copied from interface: IFormatReader

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.

Specified by:

getUsedFiles in interface IFormatReader

getUsedFiles

public String[] getUsedFiles(boolean noPixels)

Description copied from interface: IFormatReader

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.

Specified by:

getUsedFiles in interface IFormatReader

getSeriesUsedFiles

public String[] getSeriesUsedFiles()

Description copied from interface: IFormatReader

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.

Specified by:

getSeriesUsedFiles in interface IFormatReader

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

getAdvancedUsedFiles

public FileInfo[] getAdvancedUsedFiles(boolean noPixels)

Description copied from interface: IFormatReader

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.

Specified by:

getAdvancedUsedFiles in interface IFormatReader

getAdvancedSeriesUsedFiles

public FileInfo[] getAdvancedSeriesUsedFiles(boolean noPixels)

Description copied from interface: IFormatReader

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.

Specified by:

getAdvancedSeriesUsedFiles in interface IFormatReader

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

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

getZCTCoords

public int[] getZCTCoords(int index)

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

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

getMetadataValue

public Object getMetadataValue(String field)

Description copied from interface: IFormatReader

Obtains the specified metadata field's value for the current file.

Specified by:

getMetadataValue in interface IFormatReader

Parameters:

field - the name associated with the metadata field

Returns:

the value, or null if the field doesn't exist

getSeriesMetadataValue

public Object getSeriesMetadataValue(String field)

Description copied from interface: IFormatReader

Obtains the specified metadata field's value for the current series in the current file.

Specified by:

getSeriesMetadataValue in interface IFormatReader

Parameters:

field - the name associated with the metadata field

Returns:

the value, or null if the field doesn't exist

getGlobalMetadata

public Hashtable<String,Object> getGlobalMetadata()

Description copied from interface: IFormatReader

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

Specified by:

getGlobalMetadata in interface IFormatReader

Returns:

the hashtable containing all non-series-specific metadata from the file

getSeriesMetadata

public Hashtable<String,Object> getSeriesMetadata()

Description copied from interface: IFormatReader

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

Specified by:

getSeriesMetadata in interface IFormatReader

getCoreMetadataList

public List<CoreMetadata> getCoreMetadataList()

Description copied from interface: IFormatReader

Obtains the core metadata values for the current file.

Specified by:

getCoreMetadataList in interface IFormatReader

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

Throws:

IOException

setGroupFiles

public void setGroupFiles(boolean group)

Description copied from interface: IFormatReader

Specifies whether or not to force grouping in multi-file formats.

Specified by:

setGroupFiles in interface IFormatReader

See Also:

• IFormatReader.fileGroupOption(String)
• IFormatReader.isGroupFiles()

isGroupFiles

public boolean isGroupFiles()

Description copied from interface: IFormatReader

Returns true if we should group files in multi-file formats.

Specified by:

isGroupFiles in interface IFormatReader

See Also:

• IFormatReader.setGroupFiles(boolean)
• IFormatReader.fileGroupOption(String)

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

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

setFillColor

public void setFillColor(Byte fill)

Description copied from interface: IFormatReader

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.

Specified by:

setFillColor in interface IFormatReader

Parameters:

fill - value that will be used to fill pixel byte arrays

getFillColor

public Byte getFillColor()

Description copied from interface: IFormatReader

Return the fill value for undefined pixels. The default implementation in IFormatReader always returns 0.

Specified by:

getFillColor in interface IFormatReader

See Also:

• IFormatReader.setFillColor(Byte)

isMetadataComplete

public boolean isMetadataComplete()

Description copied from interface: IFormatReader

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

Specified by:

isMetadataComplete in interface IFormatReader

setNormalized

public void setNormalized(boolean normalize)

Description copied from interface: IFormatReader

Specifies whether or not to normalize float data.

Specified by:

setNormalized in interface IFormatReader

isNormalized

public boolean isNormalized()

Description copied from interface: IFormatReader

Returns true if we should normalize float data.

Specified by:

isNormalized in interface IFormatReader

setOriginalMetadataPopulated

public void setOriginalMetadataPopulated(boolean populate)

Description copied from interface: IFormatReader

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

Specified by:

setOriginalMetadataPopulated in interface IFormatReader

isOriginalMetadataPopulated

public boolean isOriginalMetadataPopulated()

Description copied from interface: IFormatReader

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

Specified by:

isOriginalMetadataPopulated in interface IFormatReader

getCurrentFile

public String getCurrentFile()

Description copied from interface: IFormatReader

Returns the current file.

Specified by:

getCurrentFile in interface IFormatReader

setMetadataFiltered

public void setMetadataFiltered(boolean filter)

Description copied from interface: IFormatReader

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

Specified by:

setMetadataFiltered in interface IFormatReader

isMetadataFiltered

public boolean isMetadataFiltered()

Description copied from interface: IFormatReader

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

Specified by:

isMetadataFiltered in interface IFormatReader

setMetadataStore

public void setMetadataStore(MetadataStore store)

Description copied from interface: IFormatReader

Sets the default metadata store for this reader.

Specified by:

setMetadataStore in interface IFormatReader

Parameters:

store - a metadata store implementation.

getMetadataStore

public MetadataStore getMetadataStore()

Description copied from interface: IFormatReader

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

Specified by:

getMetadataStore in interface IFormatReader

Returns:

A metadata store implementation.

getMetadataStoreRoot

public Object getMetadataStoreRoot()

Description copied from interface: IFormatReader

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.

Specified by:

getMetadataStoreRoot in interface IFormatReader

Returns:

Current metadata store's root object fully populated.

getUnderlyingReaders

public IFormatReader[] getUnderlyingReaders()

Description copied from interface: IFormatReader

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

Specified by:

getUnderlyingReaders in interface IFormatReader

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

Throws:

FormatException

IOException

getRequiredDirectories

public int getRequiredDirectories(String[] files)
                           throws FormatException,
IOException

Description copied from interface: IFormatReader

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.

Specified by:

getRequiredDirectories in interface IFormatReader

Throws:

FormatException

IOException

getDatasetStructureDescription

public String getDatasetStructureDescription()

Description copied from interface: IFormatReader

Returns a short description of the dataset structure.

Specified by:

getDatasetStructureDescription in interface IFormatReader

hasCompanionFiles

public boolean hasCompanionFiles()

Description copied from interface: IFormatReader

Returns true if this format supports multi-file datasets.

Specified by:

hasCompanionFiles in interface IFormatReader

getPossibleDomains

public String[] getPossibleDomains(String id)
                            throws FormatException,
IOException

Description copied from interface: IFormatReader

Returns a list of scientific domains in which this format is used.

Specified by:

getPossibleDomains in interface IFormatReader

Throws:

FormatException

IOException

getDomains

public String[] getDomains()

Description copied from interface: IFormatReader

Returns the list of domains represented by the current file.

Specified by:

getDomains in interface IFormatReader

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

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

getCoreIndex

public int getCoreIndex()

Description copied from interface: IFormatReader

Return the index into CoreMetadata of the current resolution/series.

Specified by:

getCoreIndex in interface IFormatReader

setCoreIndex

public void setCoreIndex(int no)

Description copied from interface: IFormatReader

Set the current resolution/series (ignores subresolutions). Equivalent to setSeries, but with flattened resolutions always set to false.

Specified by:

setCoreIndex in interface IFormatReader

seriesToCoreIndex

public int seriesToCoreIndex(int series)

Description copied from interface: IFormatReader

Returns the first core index corresponding to the specified series.

Specified by:

seriesToCoreIndex in interface IFormatReader

coreIndexToSeries

public int coreIndexToSeries(int index)

Description copied from interface: IFormatReader

Returns the series corresponding to the specified core index.

Specified by:

coreIndexToSeries in interface IFormatReader

getResolutionCount

public int getResolutionCount()

Description copied from interface: IPyramidHandler

Return the number of resolutions for the current series. Resolutions are stored in descending order, so the largest resolution is first and the smallest resolution is last.

Specified by:

getResolutionCount in interface IPyramidHandler

setResolution

public void setResolution(int no)

Description copied from interface: IPyramidHandler

Set the resolution level.

Specified by:

setResolution in interface IPyramidHandler

See Also:

• IPyramidHandler.getResolutionCount()

getResolution

public int getResolution()

Description copied from interface: IPyramidHandler

Get the current resolution level.

Specified by:

getResolution in interface IPyramidHandler

See Also:

• IPyramidHandler.getResolutionCount()

hasFlattenedResolutions

public boolean hasFlattenedResolutions()

Description copied from interface: IFormatReader

Return whether or not resolution flattening is enabled.

Specified by:

hasFlattenedResolutions in interface IFormatReader

setFlattenedResolutions

public void setFlattenedResolutions(boolean flattened)

Description copied from interface: IFormatReader

Set whether or not to flatten resolutions into individual series.

Specified by:

setFlattenedResolutions in interface IFormatReader

isThisType

public boolean isThisType(String name)

Description copied from interface: IFormatHandler

Checks if the given string is a valid filename for this file format.

Specified by:

isThisType in interface IFormatHandler

getFormat

public String getFormat()

Description copied from interface: IFormatHandler

Gets the name of this file format.

Specified by:

getFormat in interface IFormatHandler

getSuffixes

public String[] getSuffixes()

Description copied from interface: IFormatHandler

Gets the default file suffixes for this file format.

Specified by:

getSuffixes in interface IFormatHandler

getNativeDataType

public Class<?> getNativeDataType()

Description copied from interface: IFormatHandler

Returns the native data type of image planes for this reader, as returned by IFormatReader.openPlane(int, int, int, int, int) or IFormatWriter.savePlane(int, java.lang.Object). For most readers this type will be a byte array; however, some readers call external APIs that work with other types such as BufferedImage.

Specified by:

getNativeDataType in interface IFormatHandler

setId

public void setId(String id)
           throws FormatException,
IOException

Description copied from interface: IFormatHandler

Sets the current file name.

Specified by:

setId in interface IFormatHandler

Throws:

FormatException

IOException

reopenFile

public void reopenFile()
                throws IOException

Description copied from interface: IFormatReader

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.

Specified by:

reopenFile in interface IFormatReader

Throws:

IOException

close

public void close()
           throws IOException

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException

getTileRows

public int getTileRows(int no)

Description copied from interface: ICompressedTileReader

Get the number of rows of tiles in the specified plane in the current series.

Specified by:

getTileRows in interface ICompressedTileReader

Parameters:

no - plane index

Returns:

tile row count

getTileColumns

public int getTileColumns(int no)

Description copied from interface: ICompressedTileReader

Get the number of columns of tiles in the specified plane in the current series.

Specified by:

getTileColumns in interface ICompressedTileReader

Parameters:

no - plane index

Returns:

tile column count

openCompressedBytes

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

Description copied from interface: ICompressedTileReader

Retrieve the specified tile without performing any decompression.

Specified by:

openCompressedBytes in interface ICompressedTileReader

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

IOException

openCompressedBytes

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

Description copied from interface: ICompressedTileReader

Retrieve the specified tile without performing any decompression.

Specified by:

openCompressedBytes in interface ICompressedTileReader

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

IOException

getTileCodec

public Codec getTileCodec(int no)
                   throws FormatException,
IOException

Description copied from interface: ICompressedTileReader

Retrieve a codec that can be used to decompress compressed tiles.

Specified by:

getTileCodec in interface ICompressedTileReader

Parameters:

no - plane index

Returns:

codec that can be used for compressed tiles in the specified plane

Throws:

FormatException

IOException

See Also:

• ICompressedTileReader.openCompressedBytes(int,int,int)

getTileCodecOptions

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

Description copied from interface: ICompressedTileReader

Retrieve codec options that can be used to decompressed the specified tile.

Specified by:

getTileCodecOptions in interface ICompressedTileReader

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

IOException

See Also:

• ICompressedTileReader.getTileCodec(int)