loci.formats
Interface IFormatReader

All Superinterfaces:
IFormatHandler, StatusReporter
All Known Implementing Classes:
AliconaReader, AVIReader, BaseTiffReader, BioRadReader, BMPReader, ChannelFiller, ChannelMerger, ChannelSeparator, DeltavisionReader, DicomReader, DimensionSwapper, EPSReader, FileStitcher, FitsReader, FlexReader, FluoviewReader, FormatReader, GatanReader, GelReader, GIFReader, ICSReader, ImageIOReader, ImageReader, ImarisReader, ImarisTiffReader, ImprovisionTiffReader, IPLabReader, IPWReader, JPEGReader, KhorosReader, LegacyPictReader, LegacyQTReader, LegacyZVIReader, LeicaReader, LIFReader, LIMReader, MetamorphReader, MicromanagerReader, MinMaxCalculator, MNGReader, MRCReader, ND2Reader, NikonReader, NRRDReader, OIBReader, OIFReader, OMETiffReader, OMEXMLReader, OpenlabRawReader, OpenlabReader, PCIReader, PerkinElmerReader, PGMReader, PictReader, PNGReader, PrairieReader, PSDReader, QTReader, ReaderWrapper, SDTReader, SEQReader, SlidebookReader, TCSReader, TiffReader, VisitechReader, ZeissLSMReader, ZeissZVIReader

public interface IFormatReader
extends IFormatHandler

Interface for all biological file format readers.

Source code:
Trac, SVN


Field Summary
static int CAN_GROUP
           
static int CANNOT_GROUP
           
static int MUST_GROUP
          File grouping options.
 
Method Summary
 void close(boolean fileOnly)
          Closes the currently open file.
 int fileGroupOption(String id)
          Returns an int indicating that we cannot, must, or might group the files in a given dataset.
 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.
 int[] getChannelDimLengths()
          Gets the lengths of each subdimension of C, in fastest-to-sloweset rasterization order.
 int[] getChannelDimLengths(String id)
          Deprecated. Replaced by getChannelDimLengths()
 String[] getChannelDimTypes()
          Gets the name of each subdimension of C, in fastest-to-slowest rasterization order.
 String[] getChannelDimTypes(String id)
          Deprecated. Replaced by getChannelDimTypes()
 CoreMetadata getCoreMetadata()
          Obtains the core metadata values for the current file.
 CoreMetadata getCoreMetadata(String id)
          Deprecated. Replaced by getCoreMetadata()
 String getCurrentFile()
          Returns the current file.
 String getDimensionOrder()
          Gets a five-character string representing the dimension order within the file.
 String getDimensionOrder(String id)
          Deprecated. Replaced by getDimensionOrder()
 int getEffectiveSizeC()
          Gets the effective size of the C dimension, guaranteeing that getEffectiveSizeC() * getSizeZ() * getSizeT() == getImageCount() regardless of the result of isRGB().
 int getEffectiveSizeC(String id)
          Deprecated. Replaced by getEffectiveSizeC()
 int getImageCount()
          Determines the number of images in the current file.
 int getImageCount(String id)
          Deprecated. Replaced by getImageCount()
 int getIndex(int z, int c, int t)
          Gets the rasterized index corresponding to the given Z, C and T coordinates.
 int getIndex(String id, int z, int c, int t)
          Deprecated. Replaced by getIndex(int, int, int)
 Hashtable getMetadata()
          Obtains the hashtable containing the metadata field/value pairs from the current file.
 Hashtable getMetadata(String id)
          Deprecated. Replaced by getMetadata()
 MetadataStore getMetadataStore()
          Retrieves the current metadata store for this reader.
 MetadataStore getMetadataStore(String id)
          Deprecated. Replaced by getMetadataStore()
 Object getMetadataStoreRoot()
          Retrieves the current metadata store's root object.
 Object getMetadataStoreRoot(String id)
          Deprecated. Replaced by getMetadataStoreRoot()
 Object getMetadataValue(String field)
          Obtains the specified metadata field's value for the current file.
 Object getMetadataValue(String id, String field)
          Deprecated. Replaced by getMetadataValue(String)
 int getPixelType()
          Gets the pixel type.
 int getPixelType(String id)
          Deprecated. Replaced by getPixelType()
 int getRGBChannelCount()
          Gets the number of channels per RGB image (if not RGB, this returns 1).
 int getRGBChannelCount(String id)
          Deprecated. Replaced by getRGBChannelCount()
 int getSeries()
          Gets the currently active series.
 int getSeries(String id)
          Deprecated. Replaced by getSeries()
 int getSeriesCount()
          Gets the number of series in this file.
 int getSeriesCount(String id)
          Deprecated. Replaced by getSeriesCount()
 int getSizeC()
          Gets the size of the C dimension.
 int getSizeC(String id)
          Deprecated. Replaced by getSizeC()
 int getSizeT()
          Gets the size of the T dimension.
 int getSizeT(String id)
          Deprecated. Replaced by getSizeT()
 int getSizeX()
          Gets the size of the X dimension.
 int getSizeX(String id)
          Deprecated. Replaced by getSizeX()
 int getSizeY()
          Gets the size of the Y dimension.
 int getSizeY(String id)
          Deprecated. Replaced by getSizeY()
 int getSizeZ()
          Gets the size of the Z dimension.
 int getSizeZ(String id)
          Deprecated. Replaced by getSizeZ()
 int getThumbSizeX()
          Get the size of the X dimension for the thumbnail.
 int getThumbSizeX(String id)
          Deprecated. Replaced by getThumbSizeX()
 int getThumbSizeY()
          Get the size of the Y dimension for the thumbnail.
 int getThumbSizeY(String id)
          Deprecated. Replaced by getThumbSizeY()
 String[] getUsedFiles()
          Returns an array of filenames needed to open this dataset.
 String[] getUsedFiles(String id)
          Deprecated. Replaced by getUsedFiles()
 int[] getZCTCoords(int index)
          Gets the Z, C and T coordinates corresponding to the given rasterized index value.
 int[] getZCTCoords(String id, int index)
          Deprecated. Replaced by getZCTCoords(int)
 boolean isFalseColor()
          Returns false if isIndexed is false, or if isIndexed is true and the lookup table represents "real" color data.
 boolean isGroupFiles()
          Returns true if we should group files in multi-file formats.
 boolean isIndexed()
          Gets whether the images 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 isInterleaved(String id)
          Deprecated. Replaced by isInterleaved()
 boolean isInterleaved(String id, int subC)
          Deprecated. Replaced by isInterleaved(int)
 boolean isLittleEndian()
          Gets whether the data is in little-endian format.
 boolean isLittleEndian(String id)
          Deprecated. Replaced by isLittleEndian()
 boolean isMetadataCollected()
          Returns true if we should collect metadata.
 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 isOrderCertain(String id)
          Deprecated. Replaced by isOrderCertain()
 boolean isOriginalMetadataPopulated()
          Returns true if we should save proprietary metadata in the MetadataStore.
 boolean isRGB()
          Checks if the images in the file are RGB.
 boolean isRGB(String id)
          Deprecated. Replaced by isRGB()
 boolean isThisType(byte[] block)
          Checks if the given block is a valid header for this file format.
 byte[] openBytes(int no)
          Obtains the specified image from the current file as a byte array.
 byte[] openBytes(int no, byte[] buf)
          Obtains the specified image from the current file into a pre-allocated byte array of (sizeX * sizeY * bytesPerPixel).
 byte[] openBytes(String id, int no)
          Deprecated. Replaced by openBytes(int)
 byte[] openBytes(String id, int no, byte[] buf)
          Deprecated. Replaced by openBytes(int, byte[])
 BufferedImage openImage(int no)
          Obtains the specified image from the current file.
 BufferedImage openImage(String id, int no)
          Deprecated. Replaced by openImage(int)
 byte[] openThumbBytes(int no)
          Obtains a thumbnail for the specified image from the current file, as a byte array.
 byte[] openThumbBytes(String id, int no)
          Deprecated. Replaced by openThumbBytes(int)
 BufferedImage openThumbImage(int no)
          Obtains a thumbnail for the specified image from the current file.
 BufferedImage openThumbImage(String id, int no)
          Deprecated. Replaced by openThumbImage(int)
 void setGroupFiles(boolean group)
          Specifies whether or not to force grouping in multi-file formats.
 void setMetadataCollected(boolean collect)
          Specifies whether or not to collect metadata.
 void setMetadataFiltered(boolean filter)
          Specifies whether ugly metadata (entries with unprintable characters, and extremely large entries) should be discarded from the metadata table.
 void setMetadataStore(MetadataStore store)
          Sets the default metadata store for this reader.
 void setNormalized(boolean normalize)
          Specifies whether or not to normalize float data.
 void setOriginalMetadataPopulated(boolean populate)
          Specifies whether or not to save proprietary metadata in the MetadataStore.
 void setSeries(int no)
          Activates the specified series.
 void setSeries(String id, int no)
          Deprecated. Replaced by setSeries(int)
 
Methods inherited from interface loci.formats.IFormatHandler
close, getFormat, getSuffixes, isThisType, isThisType, setId, setId
 
Methods inherited from interface loci.formats.StatusReporter
addStatusListener, getStatusListeners, removeStatusListener
 

Field Detail

MUST_GROUP

static final int MUST_GROUP
File grouping options.

See Also:
Constant Field Values

CAN_GROUP

static final int CAN_GROUP
See Also:
Constant Field Values

CANNOT_GROUP

static final int CANNOT_GROUP
See Also:
Constant Field Values
Method Detail

isThisType

boolean isThisType(byte[] block)
Checks if the given block is a valid header for this file format.


getImageCount

int getImageCount()
Determines the number of images in the current file.


isRGB

boolean isRGB()
Checks if the images in the file are RGB.


getSizeX

int getSizeX()
Gets the size of the X dimension.


getSizeY

int getSizeY()
Gets the size of the Y dimension.


getSizeZ

int getSizeZ()
Gets the size of the Z dimension.


getSizeC

int getSizeC()
Gets the size of the C dimension.


getSizeT

int getSizeT()
Gets the size of the T dimension.


getPixelType

int getPixelType()
Gets the pixel type.

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

getEffectiveSizeC

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


getRGBChannelCount

int getRGBChannelCount()
Gets the number of channels per RGB image (if not RGB, this returns 1).


isIndexed

boolean isIndexed()
Gets whether the images are indexed color.


isFalseColor

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


get8BitLookupTable

byte[][] get8BitLookupTable()
                            throws FormatException,
                                   IOException
Gets the 8-bit color lookup table associated with the most recently opened image. If no images have been opened, or if isIndexed() returns false, then this returns null. Also, if getPixelType() returns anything other than INT8 or UINT8, this method will return null.

Throws:
FormatException
IOException

get16BitLookupTable

short[][] get16BitLookupTable()
                              throws FormatException,
                                     IOException
Gets the 16-bit color lookup table associated with the most recently opened image. If no images have been opened, or if isIndexed() returns false, then this returns null. Also, if getPixelType() returns anything other than INT16 or UINT16, this method will return null.

Throws:
FormatException
IOException

getChannelDimLengths

int[] getChannelDimLengths()
Gets the lengths of each subdimension of C, in fastest-to-sloweset rasterization order.


getChannelDimTypes

String[] getChannelDimTypes()
Gets the name of each subdimension of C, in fastest-to-slowest rasterization order. Common subdimensional types are enumerated in FormatTools.


getThumbSizeX

int getThumbSizeX()
Get the size of the X dimension for the thumbnail.


getThumbSizeY

int getThumbSizeY()
Get the size of the Y dimension for the thumbnail.


isLittleEndian

boolean isLittleEndian()
Gets whether the data is in little-endian format.


getDimensionOrder

String getDimensionOrder()
Gets a five-character string representing the dimension order within the file. Valid orders are: In cases where the channels are interleaved (e.g., CXYTZ), C will be the first dimension after X and Y (e.g., XYCTZ) and the isInterleaved(String) method will return true.


isOrderCertain

boolean isOrderCertain()
Gets whether the dimension order and sizes are known, or merely guesses.


isInterleaved

boolean isInterleaved()
Gets whether or not the channels are interleaved. This method exists because X and Y must appear first in the dimension order. For interleaved data, XYCTZ or XYCZT is used, and this method returns true.


isInterleaved

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


openBytes

byte[] openBytes(int no)
                 throws FormatException,
                        IOException
Obtains the specified image from the current file as a byte array.

Throws:
FormatException
IOException

openBytes

byte[] openBytes(int no,
                 byte[] buf)
                 throws FormatException,
                        IOException
Obtains the specified image from the current file into a pre-allocated byte array of (sizeX * sizeY * bytesPerPixel).

Parameters:
no - the image index within the file.
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.

openImage

BufferedImage openImage(int no)
                        throws FormatException,
                               IOException
Obtains the specified image from the current file.

Throws:
FormatException
IOException

openThumbBytes

byte[] openThumbBytes(int no)
                      throws FormatException,
                             IOException
Obtains a thumbnail for the specified image from the current file, as a byte array.

Throws:
FormatException
IOException

openThumbImage

BufferedImage openThumbImage(int no)
                             throws FormatException,
                                    IOException
Obtains a thumbnail for the specified image from the current file.

Throws:
FormatException
IOException

close

void close(boolean fileOnly)
           throws IOException
Closes the currently open file. If the flag is set, this is all that happens; if unset, it is equivalent to calling IFormatHandler.close().

Throws:
IOException

getSeriesCount

int getSeriesCount()
Gets the number of series in this file.


setSeries

void setSeries(int no)
Activates the specified series.


getSeries

int getSeries()
Gets the currently active series.


setNormalized

void setNormalized(boolean normalize)
Specifies whether or not to normalize float data.


isNormalized

boolean isNormalized()
Returns true if we should normalize float data.


setMetadataCollected

void setMetadataCollected(boolean collect)
Specifies whether or not to collect metadata.


isMetadataCollected

boolean isMetadataCollected()
Returns true if we should collect metadata.


setOriginalMetadataPopulated

void setOriginalMetadataPopulated(boolean populate)
Specifies whether or not to save proprietary metadata in the MetadataStore.


isOriginalMetadataPopulated

boolean isOriginalMetadataPopulated()
Returns true if we should save proprietary metadata in the MetadataStore.


setGroupFiles

void setGroupFiles(boolean group)
Specifies whether or not to force grouping in multi-file formats.


isGroupFiles

boolean isGroupFiles()
Returns true if we should group files in multi-file formats.


isMetadataComplete

boolean isMetadataComplete()
Returns true if this format's metadata is completely parsed.


fileGroupOption

int fileGroupOption(String id)
                    throws FormatException,
                           IOException
Returns an int indicating that we cannot, must, or might group the files in a given dataset.

Throws:
FormatException
IOException

getUsedFiles

String[] getUsedFiles()
Returns an array of filenames needed to open this dataset.


getCurrentFile

String getCurrentFile()
Returns the current file.


getIndex

int getIndex(int z,
             int c,
             int t)
Gets the rasterized index corresponding to the given Z, C and T coordinates.


getZCTCoords

int[] getZCTCoords(int index)
Gets the Z, C and T coordinates corresponding to the given rasterized index value.


getMetadataValue

Object getMetadataValue(String field)
Obtains the specified metadata field's value for the current file.

Parameters:
field - the name associated with the metadata field
Returns:
the value, or null if the field doesn't exist

getMetadata

Hashtable getMetadata()
Obtains the hashtable containing the metadata field/value pairs from the current file.

Returns:
the hashtable containing all metadata from the file

getCoreMetadata

CoreMetadata getCoreMetadata()
Obtains the core metadata values for the current file.


setMetadataFiltered

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


isMetadataFiltered

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


setMetadataStore

void setMetadataStore(MetadataStore store)
Sets the default metadata store for this reader.

Parameters:
store - a metadata store implementation.

getMetadataStore

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

Returns:
A metadata store implementation.

getMetadataStoreRoot

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

Returns:
Current metadata store's root object fully populated.

getImageCount

int getImageCount(String id)
                  throws FormatException,
                         IOException
Deprecated. Replaced by getImageCount()

Throws:
FormatException
IOException

isRGB

boolean isRGB(String id)
              throws FormatException,
                     IOException
Deprecated. Replaced by isRGB()

Throws:
FormatException
IOException

getSizeX

int getSizeX(String id)
             throws FormatException,
                    IOException
Deprecated. Replaced by getSizeX()

Throws:
FormatException
IOException

getSizeY

int getSizeY(String id)
             throws FormatException,
                    IOException
Deprecated. Replaced by getSizeY()

Throws:
FormatException
IOException

getSizeZ

int getSizeZ(String id)
             throws FormatException,
                    IOException
Deprecated. Replaced by getSizeZ()

Throws:
FormatException
IOException

getSizeC

int getSizeC(String id)
             throws FormatException,
                    IOException
Deprecated. Replaced by getSizeC()

Throws:
FormatException
IOException

getSizeT

int getSizeT(String id)
             throws FormatException,
                    IOException
Deprecated. Replaced by getSizeT()

Throws:
FormatException
IOException

getPixelType

int getPixelType(String id)
                 throws FormatException,
                        IOException
Deprecated. Replaced by getPixelType()

Throws:
FormatException
IOException

getEffectiveSizeC

int getEffectiveSizeC(String id)
                      throws FormatException,
                             IOException
Deprecated. Replaced by getEffectiveSizeC()

Throws:
FormatException
IOException

getRGBChannelCount

int getRGBChannelCount(String id)
                       throws FormatException,
                              IOException
Deprecated. Replaced by getRGBChannelCount()

Throws:
FormatException
IOException

getChannelDimLengths

int[] getChannelDimLengths(String id)
                           throws FormatException,
                                  IOException
Deprecated. Replaced by getChannelDimLengths()

Throws:
FormatException
IOException

getChannelDimTypes

String[] getChannelDimTypes(String id)
                            throws FormatException,
                                   IOException
Deprecated. Replaced by getChannelDimTypes()

Throws:
FormatException
IOException

getThumbSizeX

int getThumbSizeX(String id)
                  throws FormatException,
                         IOException
Deprecated. Replaced by getThumbSizeX()

Throws:
FormatException
IOException

getThumbSizeY

int getThumbSizeY(String id)
                  throws FormatException,
                         IOException
Deprecated. Replaced by getThumbSizeY()

Throws:
FormatException
IOException

isLittleEndian

boolean isLittleEndian(String id)
                       throws FormatException,
                              IOException
Deprecated. Replaced by isLittleEndian()

Throws:
FormatException
IOException

getDimensionOrder

String getDimensionOrder(String id)
                         throws FormatException,
                                IOException
Deprecated. Replaced by getDimensionOrder()

Throws:
FormatException
IOException

isOrderCertain

boolean isOrderCertain(String id)
                       throws FormatException,
                              IOException
Deprecated. Replaced by isOrderCertain()

Throws:
FormatException
IOException

isInterleaved

boolean isInterleaved(String id)
                      throws FormatException,
                             IOException
Deprecated. Replaced by isInterleaved()

Throws:
FormatException
IOException

isInterleaved

boolean isInterleaved(String id,
                      int subC)
                      throws FormatException,
                             IOException
Deprecated. Replaced by isInterleaved(int)

Throws:
FormatException
IOException

openImage

BufferedImage openImage(String id,
                        int no)
                        throws FormatException,
                               IOException
Deprecated. Replaced by openImage(int)

Throws:
FormatException
IOException

openBytes

byte[] openBytes(String id,
                 int no)
                 throws FormatException,
                        IOException
Deprecated. Replaced by openBytes(int)

Throws:
FormatException
IOException

openBytes

byte[] openBytes(String id,
                 int no,
                 byte[] buf)
                 throws FormatException,
                        IOException
Deprecated. Replaced by openBytes(int, byte[])

Throws:
FormatException
IOException

openThumbImage

BufferedImage openThumbImage(String id,
                             int no)
                             throws FormatException,
                                    IOException
Deprecated. Replaced by openThumbImage(int)

Throws:
FormatException
IOException

openThumbBytes

byte[] openThumbBytes(String id,
                      int no)
                      throws FormatException,
                             IOException
Deprecated. Replaced by openThumbBytes(int)

Throws:
FormatException
IOException

getSeriesCount

int getSeriesCount(String id)
                   throws FormatException,
                          IOException
Deprecated. Replaced by getSeriesCount()

Throws:
FormatException
IOException

setSeries

void setSeries(String id,
               int no)
               throws FormatException,
                      IOException
Deprecated. Replaced by setSeries(int)

Throws:
FormatException
IOException

getSeries

int getSeries(String id)
              throws FormatException,
                     IOException
Deprecated. Replaced by getSeries()

Throws:
FormatException
IOException

getUsedFiles

String[] getUsedFiles(String id)
                      throws FormatException,
                             IOException
Deprecated. Replaced by getUsedFiles()

Throws:
FormatException
IOException

getIndex

int getIndex(String id,
             int z,
             int c,
             int t)
             throws FormatException,
                    IOException
Deprecated. Replaced by getIndex(int, int, int)

Throws:
FormatException
IOException

getZCTCoords

int[] getZCTCoords(String id,
                   int index)
                   throws FormatException,
                          IOException
Deprecated. Replaced by getZCTCoords(int)

Throws:
FormatException
IOException

getMetadataValue

Object getMetadataValue(String id,
                        String field)
                        throws FormatException,
                               IOException
Deprecated. Replaced by getMetadataValue(String)

Throws:
FormatException
IOException

getMetadata

Hashtable getMetadata(String id)
                      throws FormatException,
                             IOException
Deprecated. Replaced by getMetadata()

Throws:
FormatException
IOException

getCoreMetadata

CoreMetadata getCoreMetadata(String id)
                             throws FormatException,
                                    IOException
Deprecated. Replaced by getCoreMetadata()

Throws:
FormatException
IOException

getMetadataStore

MetadataStore getMetadataStore(String id)
                               throws FormatException,
                                      IOException
Deprecated. Replaced by getMetadataStore()

Throws:
FormatException
IOException

getMetadataStoreRoot

Object getMetadataStoreRoot(String id)
                            throws FormatException,
                                   IOException
Deprecated. Replaced by getMetadataStoreRoot()

Throws:
FormatException
IOException