bioformats  5.1.8
Classes | Public Types | Public Member Functions | Protected Member Functions | Private Member Functions | List of all members
ome::bioformats::FormatReader Class Referenceabstract

Interface for all biological file format readers. More...

#include <ome/bioformats/FormatReader.h>

+ Inheritance diagram for ome::bioformats::FormatReader:
+ Collaboration diagram for ome::bioformats::FormatReader:

Classes

class  SaveSeries
 Sentry for saving and restoring reader series state. More...
 

Public Types

enum  FileGroupOption { MUST_GROUP, CAN_GROUP, CANNOT_GROUP }
 File grouping options. More...
 

Public Member Functions

virtual ~FormatReader ()
 Destructor.
 
virtual bool isThisType (const boost::filesystem::path &name, bool open=true) const =0
 Check if the given file is a valid instance of this file format. More...
 
virtual bool isThisType (const uint8_t *begin, const uint8_t *end) const =0
 Check if the given buffer is a valid header for this file format. More...
 
virtual bool isThisType (const uint8_t *begin, std::size_t length) const =0
 Check if the given buffer is a valid header for this file format. More...
 
virtual bool isThisType (std::istream &stream) const =0
 Check if the given input stream is a valid stream for this file format. More...
 
virtual dimension_size_type getImageCount () const =0
 Determine the number of image planes in the current series. More...
 
virtual bool isRGB (dimension_size_type channel) const =0
 Check if the image planes for a channel have more than one sub-channel per openBytes() call. More...
 
virtual dimension_size_type getSizeX () const =0
 Get the size of the X dimension. More...
 
virtual dimension_size_type getSizeY () const =0
 Get the size of the Y dimension. More...
 
virtual dimension_size_type getSizeZ () const =0
 Get the size of the Z dimension. More...
 
virtual dimension_size_type getSizeT () const =0
 Get the size of the T dimension. More...
 
virtual dimension_size_type getSizeC () const =0
 Get the size of the C dimension. More...
 
virtual ome::xml::model::enums::PixelType getPixelType () const =0
 Get the pixel type. More...
 
virtual pixel_size_type getBitsPerPixel () const =0
 Get the number of valid bits per pixel. More...
 
virtual dimension_size_type getEffectiveSizeC () const =0
 Get the effective size of the C dimension. More...
 
virtual dimension_size_type getRGBChannelCount (dimension_size_type channel) const =0
 Get the number of channels returned for a call to openBytes(). More...
 
virtual bool isIndexed () const =0
 Get whether the image planes are indexed color. More...
 
virtual bool isFalseColor () const =0
 Get whether the image planes are false color. More...
 
virtual void getLookupTable (dimension_size_type plane, VariantPixelBuffer &buf) const =0
 Get the color lookup table associated with an image plane. More...
 
virtual ModulogetModuloZ ()=0
 Get the Modulo subdivision of the Z dimension. More...
 
virtual const ModulogetModuloZ () const =0
 Get the Modulo subdivision of the Z dimension. More...
 
virtual ModulogetModuloT ()=0
 Get the Modulo subdivision of the T dimension. More...
 
virtual const ModulogetModuloT () const =0
 Get the Modulo subdivision of the T dimension. More...
 
virtual ModulogetModuloC ()=0
 Get the Modulo subdivision of the C dimension. More...
 
virtual const ModulogetModuloC () const =0
 Get the Modulo subdivision of the C dimension. More...
 
virtual dimension_size_type getThumbSizeX () const =0
 Get the thumbnail size of the X dimension. More...
 
virtual dimension_size_type getThumbSizeY () const =0
 Get the thumbnail size of the Y dimension. More...
 
virtual bool isLittleEndian () const =0
 Get whether the data is in little-endian format. More...
 
virtual const std::string & getDimensionOrder () const =0
 Get the dimension order. More...
 
virtual bool isOrderCertain () const =0
 Get whether the dimension order and sizes are known, or merely guesses. More...
 
virtual bool isThumbnailSeries () const =0
 Get whether the current series is a lower resolution copy of a different series. More...
 
virtual bool isInterleaved () const =0
 Get whether or not the channels are interleaved. More...
 
virtual bool isInterleaved (dimension_size_type channel) const =0
 Get whether or not the given channel is interleaved. More...
 
virtual void openBytes (dimension_size_type plane, VariantPixelBuffer &buf) const =0
 Obtain an image plane. More...
 
virtual void openBytes (dimension_size_type plane, VariantPixelBuffer &buf, dimension_size_type x, dimension_size_type y, dimension_size_type w, dimension_size_type h) const =0
 Obtain a sub-image of an image plane. More...
 
virtual void openThumbBytes (dimension_size_type plane, VariantPixelBuffer &buf) const =0
 Obtain a thumbnail of an image plane. More...
 
virtual dimension_size_type getSeriesCount () const =0
 Get the number of image series in this file. More...
 
virtual void setSeries (dimension_size_type series) const =0
 Set the active series. More...
 
virtual dimension_size_type getSeries () const =0
 Get the active series. More...
 
virtual void setPlane (dimension_size_type plane) const =0
 Set the active plane. More...
 
virtual dimension_size_type getPlane () const =0
 Get the active plane. More...
 
virtual void setNormalized (bool normalize)=0
 Set float normalization. More...
 
virtual bool isNormalized () const =0
 Get float normalization. More...
 
virtual void setOriginalMetadataPopulated (bool populate)=0
 Specifies whether or not to save proprietary metadata in the MetadataStore.
 
virtual bool isOriginalMetadataPopulated () const =0
 Get proprietary metadata storage. More...
 
virtual void setGroupFiles (bool group)=0
 Set file grouping. More...
 
virtual bool isGroupFiles () const =0
 Get file grouping. More...
 
virtual bool isMetadataComplete () const =0
 Get status of metadata parsing. More...
 
virtual FileGroupOption fileGroupOption (const std::string &id)=0
 Returns an enum indicating that we cannot, must, or might group the files in this dataset. More...
 
virtual const std::vector< boost::filesystem::path > getUsedFiles (bool noPixels=false) const =0
 Get the files used by this dataset. More...
 
virtual const std::vector< boost::filesystem::path > getSeriesUsedFiles (bool noPixels=false) const =0
 Get the files used by the active series. More...
 
virtual std::vector< FileInfogetAdvancedUsedFiles (bool noPixels=false) const =0
 Get the files used by this dataset. More...
 
virtual std::vector< FileInfogetAdvancedSeriesUsedFiles (bool noPixels=false) const =0
 Get the files used by the active series. More...
 
virtual const boost::optional< boost::filesystem::path > & getCurrentFile () const =0
 Get the currently open file. More...
 
virtual const std::vector< std::string > & getDomains () const =0
 Get the domains represented by the current file. More...
 
virtual dimension_size_type getIndex (dimension_size_type z, dimension_size_type c, dimension_size_type t) const =0
 Get the linear index of a Z, C and T coordinate. More...
 
virtual dimension_size_type getIndex (dimension_size_type z, dimension_size_type c, dimension_size_type t, dimension_size_type moduloZ, dimension_size_type moduloC, dimension_size_type moduloT) const =0
 Get the linear index of a Z, C, T, ModuloZ, ModuloC and ModuloT coordinate. More...
 
virtual ome::compat::array< dimension_size_type, 3 > getZCTCoords (dimension_size_type index) const =0
 Get the Z, C and T coordinate of a linear index. More...
 
virtual ome::compat::array< dimension_size_type, 6 > getZCTModuloCoords (dimension_size_type index) const =0
 Get the Z, C, T, ModuloZ, ModuloC and ModuloT coordinate of a linear index. More...
 
virtual const MetadataMap::value_typegetMetadataValue (const std::string &field) const =0
 Get a global metadata value. More...
 
virtual const MetadataMap::value_typegetSeriesMetadataValue (const MetadataMap::key_type &field) const =0
 Get a series metadata value. More...
 
virtual const MetadataMapgetGlobalMetadata () const =0
 Get global metadata map. More...
 
virtual const MetadataMapgetSeriesMetadata () const =0
 Get series metadata map. More...
 
virtual const std::vector< ome::compat::shared_ptr< CoreMetadata > > & getCoreMetadataList () const =0
 Get the core metadata. More...
 
virtual void setMetadataFiltered (bool filter)=0
 Set metadata filtering. More...
 
virtual bool isMetadataFiltered () const =0
 Get metadata filtering. More...
 
virtual void setMetadataStore (ome::compat::shared_ptr< ::ome::xml::meta::MetadataStore > &store)=0
 Set the default metadata store for this reader. More...
 
virtual const ome::compat::shared_ptr< ::ome::xml::meta::MetadataStore > & getMetadataStore () const =0
 Get the current metadata store for this reader. More...
 
virtual ome::compat::shared_ptr< ::ome::xml::meta::MetadataStore > & getMetadataStore ()=0
 Get the current metadata store for this reader. More...
 
virtual std::vector< ome::compat::shared_ptr< FormatReader > > getUnderlyingReaders () const =0
 Get all underlying readers. More...
 
virtual bool isSingleFile (const boost::filesystem::path &id) const =0
 Is this a single-file format? More...
 
virtual uint32_t getRequiredDirectories (const std::vector< std::string > &files) const =0
 Get required parent directories. More...
 
virtual const std::string & getDatasetStructureDescription () const =0
 Get a short description of the dataset structure. More...
 
virtual const std::vector< std::string > & getPossibleDomains (const std::string &id) const =0
 Get the possible domains represented in which this format is used. More...
 
virtual bool hasCompanionFiles () const =0
 Does this format support multi-file datasets? More...
 
virtual dimension_size_type getOptimalTileWidth (dimension_size_type channel) const =0
 Get the optimal sub-image width. More...
 
virtual dimension_size_type getOptimalTileHeight (dimension_size_type channel) const =0
 Get the optimal sub-image height. More...
 
virtual dimension_size_type getOptimalTileWidth () const =0
 Get the optimal sub-image width. More...
 
virtual dimension_size_type getOptimalTileHeight () const =0
 Get the optimal sub-image height. More...
 
virtual dimension_size_type seriesToCoreIndex (dimension_size_type series) const =0
 Get the first core index corresponding to the specified series. More...
 
virtual dimension_size_type coreIndexToSeries (dimension_size_type index) const =0
 Get the series corresponding to the specified core index. More...
 
virtual dimension_size_type getCoreIndex () const =0
 Get the CoreMetadata index of the current resolution/series. More...
 
virtual void setCoreIndex (dimension_size_type index) const =0
 Set the current resolution/series (ignoring sub-resolutions). More...
 
virtual dimension_size_type getResolutionCount () const =0
 Get the number of resolutions for the current series. More...
 
virtual void setResolution (dimension_size_type resolution) const =0
 Set the active resolution level. More...
 
virtual dimension_size_type getResolution () const =0
 Get the active resolution level. More...
 
virtual bool hasFlattenedResolutions () const =0
 Get resolution flattening. More...
 
virtual void setFlattenedResolutions (bool flatten)=0
 Set resolution flattening. More...
 
- Public Member Functions inherited from ome::bioformats::FormatHandler
virtual ~FormatHandler ()
 Destructor.
 
virtual const std::string & getFormat () const =0
 Get the name of this file format. More...
 
virtual const std::string & getFormatDescription () const =0
 Get the description of this file format. More...
 
virtual const std::vector< boost::filesystem::path > & getSuffixes () const =0
 Get the default file suffixes for this file format. More...
 
virtual const std::vector< boost::filesystem::path > & getCompressionSuffixes () const =0
 Get the default compression suffixes for this file format. More...
 
virtual void setId (const boost::filesystem::path &id)=0
 Set the current file name. More...
 
virtual void close (bool fileOnly=false)=0
 Close the currently open file. More...
 
- Public Member Functions inherited from ome::bioformats::MetadataConfigurable
virtual ~MetadataConfigurable ()
 Destructor.
 
virtual const std::set< MetadataOptions::MetadataLevel > & getSupportedMetadataLevels ()=0
 Get the supported metadata levels. More...
 
virtual void setMetadataOptions (const MetadataOptions &options)=0
 Set metadata options. More...
 
virtual const MetadataOptionsgetMetadataOptions () const =0
 Get metadata options. More...
 
virtual MetadataOptionsgetMetadataOptions ()=0
 Get metadata options. More...
 

Protected Member Functions

 FormatReader ()
 Constructor.
 
- Protected Member Functions inherited from ome::bioformats::FormatHandler
 FormatHandler ()
 Constructor.
 
- Protected Member Functions inherited from ome::bioformats::MetadataConfigurable
 MetadataConfigurable ()
 Constructor.
 

Private Member Functions

 FormatReader (const FormatReader &)
 Copy constructor (deleted).
 
FormatReaderoperator= (const FormatReader &)
 Assignment operator (deleted).
 

Additional Inherited Members

- Static Public Member Functions inherited from ome::bioformats::FormatHandler
static bool checkSuffix (const boost::filesystem::path &name, const boost::filesystem::path &suffix)
 Perform suffix matching for the given filename. More...
 
static bool checkSuffix (const boost::filesystem::path &name, const std::vector< boost::filesystem::path > &suffixes)
 Perform suffix matching for the given filename. More...
 
static bool checkSuffix (const boost::filesystem::path &name, const std::vector< boost::filesystem::path > &suffixes, const std::vector< boost::filesystem::path > &compression_suffixes)
 Perform suffix matching for the given filename. More...
 
static void assertId (const boost::optional< boost::filesystem::path > &id, bool notNull=true)
 Assert that the current file is valid. More...
 

Detailed Description

Interface for all biological file format readers.

Note
No IOException in C++.

Member Enumeration Documentation

File grouping options.

Enumerator
MUST_GROUP 

Files must be grouped.

CAN_GROUP 

Files may be grouped.

CANNOT_GROUP 

Files can not be grouped.

Member Function Documentation

virtual dimension_size_type ome::bioformats::FormatReader::coreIndexToSeries ( dimension_size_type  index) const
pure virtual

Get the series corresponding to the specified core index.

Parameters
indexthe core index to use.
Returns
the series for the index.

Implemented in ome::bioformats::detail::FormatReader.

virtual FileGroupOption ome::bioformats::FormatReader::fileGroupOption ( const std::string &  id)
pure virtual

Returns an enum indicating that we cannot, must, or might group the files in this dataset.

Parameters
idfilename to check.
Returns
the grouping option for the specified file.

Implemented in ome::bioformats::detail::FormatReader, and ome::bioformats::in::OMETIFFReader.

virtual std::vector<FileInfo> ome::bioformats::FormatReader::getAdvancedSeriesUsedFiles ( bool  noPixels = false) const
pure virtual

Get the files used by the active series.

Parameters
noPixelsexclude pixel data files if true, or include them if false.
Returns
a list of FileInfo objects representing each used file.

Implemented in ome::bioformats::detail::FormatReader.

virtual std::vector<FileInfo> ome::bioformats::FormatReader::getAdvancedUsedFiles ( bool  noPixels = false) const
pure virtual

Get the files used by this dataset.

Parameters
noPixelsexclude pixel data files if true, or include them if false.
Returns
a list of FileInfo objects representing each used file.

Implemented in ome::bioformats::detail::FormatReader.

virtual pixel_size_type ome::bioformats::FormatReader::getBitsPerPixel ( ) const
pure virtual

Get the number of valid bits per pixel.

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

Returns
the number of valid bits per pixel.

Implemented in ome::bioformats::detail::FormatReader.

Referenced by ome::qtwidgets::gl::Image2D::create(), and ome::bioformats::fillPixels().

+ Here is the caller graph for this function:

virtual dimension_size_type ome::bioformats::FormatReader::getCoreIndex ( ) const
pure virtual

Get the CoreMetadata index of the current resolution/series.

Returns
the index.

Implemented in ome::bioformats::detail::FormatReader.

Referenced by ome::bioformats::FormatReader::SaveSeries::~SaveSeries().

+ Here is the caller graph for this function:

virtual const std::vector<ome::compat::shared_ptr<CoreMetadata> >& ome::bioformats::FormatReader::getCoreMetadataList ( ) const
pure virtual

Get the core metadata.

A CoreMetadata object exists to describe the each series in the dataset.

Returns
a const reference to the core metadata.

Implemented in ome::bioformats::detail::FormatReader.

virtual const boost::optional<boost::filesystem::path>& ome::bioformats::FormatReader::getCurrentFile ( ) const
pure virtual

Get the currently open file.

Returns
the filename.

Implemented in ome::bioformats::detail::FormatReader.

Referenced by ome::bioformats::fillMetadata().

+ Here is the caller graph for this function:

virtual const std::string& ome::bioformats::FormatReader::getDatasetStructureDescription ( ) const
pure virtual

Get a short description of the dataset structure.

Returns
a short description.

Implemented in ome::bioformats::detail::FormatReader.

virtual const std::string& ome::bioformats::FormatReader::getDimensionOrder ( ) const
pure virtual

Get the dimension order.

The dimension order is a five-character string representing the order in which planes will be returned. Valid orders are:

  • XYCTZ
  • XYCZT
  • XYTCZ
  • XYTZC
  • XYZCT
  • XYZTC

In cases where the channels are interleaved (e.g. CXYTZ), C will be the first dimension after X and Y (e.g. XYCTZ) and the isInterleaved() method will return true.

Returns
the dimension order.

Implemented in ome::bioformats::detail::FormatReader.

Referenced by ome::bioformats::fillPixels().

+ Here is the caller graph for this function:

virtual const std::vector<std::string>& ome::bioformats::FormatReader::getDomains ( ) const
pure virtual

Get the domains represented by the current file.

Returns
a list of domains.

Implemented in ome::bioformats::detail::FormatReader, and ome::bioformats::in::OMETIFFReader.

virtual dimension_size_type ome::bioformats::FormatReader::getEffectiveSizeC ( ) const
pure virtual

Get the effective size of the C dimension.

This guarantees that

regardless of the result of isRGB().

Returns
the effective C dimension size.

Implemented in ome::bioformats::detail::FormatReader.

Referenced by ome::bioformats::fillPixels().

+ Here is the caller graph for this function:

virtual const MetadataMap& ome::bioformats::FormatReader::getGlobalMetadata ( ) const
pure virtual

Get global metadata map.

Obtain the map containing the global metadata field/value pairs the current dataset.

Returns
the global metadata map.

Implemented in ome::bioformats::detail::FormatReader.

virtual dimension_size_type ome::bioformats::FormatReader::getImageCount ( ) const
pure virtual

Determine the number of image planes in the current series.

Returns
the number of image planes.

Implemented in ome::bioformats::detail::FormatReader.

Referenced by ome::bioformats::fillMetadata().

+ Here is the caller graph for this function:

virtual dimension_size_type ome::bioformats::FormatReader::getIndex ( dimension_size_type  z,
dimension_size_type  c,
dimension_size_type  t 
) const
pure virtual

Get the linear index of a Z, C and T coordinate.

The index is computed using the DimensionOrder.

Parameters
zthe Z coordinate (real size).
cthe C coordinate (real size).
tthe T coordinate (real size).
Returns
the linear index.
Todo:

unify with the pixel buffer dimension indexes.

Don't use separate values to match the return of getZCTCoords.

Implemented in ome::bioformats::detail::FormatReader.

virtual dimension_size_type ome::bioformats::FormatReader::getIndex ( dimension_size_type  z,
dimension_size_type  c,
dimension_size_type  t,
dimension_size_type  moduloZ,
dimension_size_type  moduloC,
dimension_size_type  moduloT 
) const
pure virtual

Get the linear index of a Z, C, T, ModuloZ, ModuloC and ModuloT coordinate.

The index is computed using the DimensionOrder.

Note
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.
Parameters
zthe Z coordinate (effective size).
cthe C coordinate (effective size).
tthe T coordinate (effective size).
moduloZthe ModuloZ coordinate (effective size).
moduloCthe ModuloC coordinate (effective size).
moduloTthe ModuloT coordinate (effective size).
Returns
the linear index.
Todo:

unify with the pixel buffer dimension indexes.

Don't use separate values to match the return of getZCTModuloCoords.

Implemented in ome::bioformats::detail::FormatReader.

virtual void ome::bioformats::FormatReader::getLookupTable ( dimension_size_type  plane,
VariantPixelBuffer buf 
) const
pure virtual

Get the color lookup table associated with an image plane.

If no image planes have been opened, or if isIndexed() returns false, then this may throw an exception.

The VariantPixelBuffer will use the X dimension for the value index and the sub-channel dimension for the color samples (order is RGB). Depending upon the image type, the size of the X dimension may vary. It will typically be 2^8 or 2^16, but other sizes are possible.

Parameters
bufthe destination pixel buffer.
planethe plane index within the series.
Exceptions
FormatExceptionif a lookup table could not be obtained.

Implemented in ome::bioformats::detail::FormatReader, ome::bioformats::in::OMETIFFReader, and ome::bioformats::in::MinimalTIFFReader.

virtual const ome::compat::shared_ptr< ::ome::xml::meta::MetadataStore>& ome::bioformats::FormatReader::getMetadataStore ( ) const
pure virtual

Get the current metadata store for this reader.

Returns
the metadata store, which will never be null.

Implemented in ome::bioformats::detail::FormatReader.

virtual ome::compat::shared_ptr< ::ome::xml::meta::MetadataStore>& ome::bioformats::FormatReader::getMetadataStore ( )
pure virtual

Get the current metadata store for this reader.

Returns
the metadata store, which will never be null.

Implemented in ome::bioformats::detail::FormatReader.

virtual const MetadataMap::value_type& ome::bioformats::FormatReader::getMetadataValue ( const std::string &  field) const
pure virtual

Get a global metadata value.

Obtain the specified metadata field's value for the current dataset.

Parameters
fieldthe name associated with the metadata field.
Returns
the value.
Exceptions
boost::bad_geton failure if the key was not found.

Implemented in ome::bioformats::detail::FormatReader.

virtual Modulo& ome::bioformats::FormatReader::getModuloC ( )
pure virtual

Get the Modulo subdivision of the C dimension.

Returns
the Modulo defining the C dimension subdivision.

Implemented in ome::bioformats::detail::FormatReader.

virtual const Modulo& ome::bioformats::FormatReader::getModuloC ( ) const
pure virtual

Get the Modulo subdivision of the C dimension.

Returns
the Modulo defining the C dimension subdivision.

Implemented in ome::bioformats::detail::FormatReader.

virtual Modulo& ome::bioformats::FormatReader::getModuloT ( )
pure virtual

Get the Modulo subdivision of the T dimension.

Returns
the Modulo defining the T dimension subdivision.

Implemented in ome::bioformats::detail::FormatReader.

virtual const Modulo& ome::bioformats::FormatReader::getModuloT ( ) const
pure virtual

Get the Modulo subdivision of the T dimension.

Returns
the Modulo defining the T dimension subdivision.

Implemented in ome::bioformats::detail::FormatReader.

virtual Modulo& ome::bioformats::FormatReader::getModuloZ ( )
pure virtual

Get the Modulo subdivision of the Z dimension.

Returns
the Modulo defining the Z dimension subdivision.

Implemented in ome::bioformats::detail::FormatReader.

virtual const Modulo& ome::bioformats::FormatReader::getModuloZ ( ) const
pure virtual

Get the Modulo subdivision of the Z dimension.

Returns
the Modulo defining the Z dimension subdivision.

Implemented in ome::bioformats::detail::FormatReader.

virtual dimension_size_type ome::bioformats::FormatReader::getOptimalTileHeight ( dimension_size_type  channel) const
pure virtual

Get the optimal sub-image height.

This is intended for use with openBytes().

Parameters
channelthe channel to use, range [0, EffectiveSizeC).
Returns
the optimal height.

Implemented in ome::bioformats::detail::FormatReader, and ome::bioformats::in::OMETIFFReader.

virtual dimension_size_type ome::bioformats::FormatReader::getOptimalTileHeight ( ) const
pure virtual

Get the optimal sub-image height.

This is intended for use with openBytes(). Note that this overload does not have a channel argument, and so the value returned is the smallest height for all channels for convienience and compatibility with the Java implementation. If the optimal height varies widely between channels, this may result in suboptimal performance; specify the channel to get the optimal height for each channel.

Returns
the optimal height.

Implemented in ome::bioformats::detail::FormatReader.

virtual dimension_size_type ome::bioformats::FormatReader::getOptimalTileWidth ( dimension_size_type  channel) const
pure virtual

Get the optimal sub-image width.

This is intended for use with openBytes().

Parameters
channelthe channel to use, range [0, EffectiveSizeC).
Returns
the optimal width.

Implemented in ome::bioformats::detail::FormatReader, and ome::bioformats::in::OMETIFFReader.

virtual dimension_size_type ome::bioformats::FormatReader::getOptimalTileWidth ( ) const
pure virtual

Get the optimal sub-image width.

This is intended for use with openBytes(). Note that this overload does not have a channel argument, and so the value returned is the smallest width for all channels for convienience and compatibility with the Java implementation. If the optimal width varies widely between channels, this may result in suboptimal performance; specify the channel to get the optimal width for each channel.

Returns
the optimal width.

Implemented in ome::bioformats::detail::FormatReader.

virtual ome::xml::model::enums::PixelType ome::bioformats::FormatReader::getPixelType ( ) const
pure virtual

Get the pixel type.

Returns
the pixel type.

Implemented in ome::bioformats::detail::FormatReader.

Referenced by ome::qtwidgets::gl::Image2D::create(), ome::bioformats::fillMetadata(), and ome::bioformats::fillPixels().

+ Here is the caller graph for this function:

virtual dimension_size_type ome::bioformats::FormatReader::getPlane ( ) const
pure virtual

Get the active plane.

Returns
the active plane.

Implemented in ome::bioformats::detail::FormatReader.

Referenced by ome::bioformats::FormatReader::SaveSeries::~SaveSeries().

+ Here is the caller graph for this function:

virtual const std::vector<std::string>& ome::bioformats::FormatReader::getPossibleDomains ( const std::string &  id) const
pure virtual

Get the possible domains represented in which this format is used.

Parameters
idfilename to check.
Returns
a list of domains.
Exceptions
FormatExceptionif there was a problem parsing the metadata of the file.
Todo:
can this be a reference to static data?

Implemented in ome::bioformats::detail::FormatReader.

virtual uint32_t ome::bioformats::FormatReader::getRequiredDirectories ( const std::vector< std::string > &  files) const
pure virtual

Get required parent directories.

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

Parameters
filesthe file list being processed.
Returns
the number of important parent directories for the file list.
Exceptions
FormatExceptionif there was a problem parsing the metadata of the file.
Todo:
This could use a much better explanation, it's not at all clear what the return value means. Is it an index into files? Is it an index into the path components? Of which of the files? In which order? From the root or common parent? Is the order of files important?

Implemented in ome::bioformats::detail::FormatReader.

virtual dimension_size_type ome::bioformats::FormatReader::getResolution ( ) const
pure virtual

Get the active resolution level.

Returns
the resolution level.
See also
getResolutionCount()

Implemented in ome::bioformats::detail::FormatReader.

virtual dimension_size_type ome::bioformats::FormatReader::getResolutionCount ( ) const
pure virtual

Get the number of resolutions for the current series.

Resolutions are stored in descending order of size, so the largest resolution is first and the smallest resolution is last.

Returns
the number of resolutions.

Implemented in ome::bioformats::detail::FormatReader.

virtual dimension_size_type ome::bioformats::FormatReader::getRGBChannelCount ( dimension_size_type  channel) const
pure virtual

Get the number of channels returned for a 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.

Parameters
channelthe channel to use, range [0, EffectiveSizeC).
Returns
the number of channels.

Implemented in ome::bioformats::detail::FormatReader.

Referenced by ome::bioformats::fillPixels().

+ Here is the caller graph for this function:

virtual dimension_size_type ome::bioformats::FormatReader::getSeries ( ) const
pure virtual

Get the active series.

Returns
the active series.

Implemented in ome::bioformats::detail::FormatReader.

Referenced by ome::qtwidgets::gl::Image2D::create(), ome::bioformats::fillAllPixels(), ome::bioformats::fillMetadata(), ome::bioformats::fillPixels(), and ome::qtwidgets::gl::Image2D::setPlane().

+ Here is the caller graph for this function:

virtual dimension_size_type ome::bioformats::FormatReader::getSeriesCount ( ) const
pure virtual

Get the number of image series in this file.

Returns
the number of image series.
Exceptions
std::logic_errorif the sub-resolution metadata (if any) is invalid; this will only occur if the reader sets invalid metadata.

Implemented in ome::bioformats::detail::FormatReader.

Referenced by ome::bioformats::fillAllPixels(), and ome::bioformats::fillMetadata().

+ Here is the caller graph for this function:

virtual const MetadataMap& ome::bioformats::FormatReader::getSeriesMetadata ( ) const
pure virtual

Get series metadata map.

Obtain the map containing the series metadata field/value pairs the active series in the current dataset.

Returns
the series metadata map.

Implemented in ome::bioformats::detail::FormatReader.

virtual const MetadataMap::value_type& ome::bioformats::FormatReader::getSeriesMetadataValue ( const MetadataMap::key_type field) const
pure virtual

Get a series metadata value.

Obtain the specified metadata field's value for the active series in the current dataset.

Parameters
fieldthe name associated with the metadata field.
Returns
the value.
Exceptions
boost::bad_geton failure if the key was not found.

Implemented in ome::bioformats::detail::FormatReader.

virtual const std::vector<boost::filesystem::path> ome::bioformats::FormatReader::getSeriesUsedFiles ( bool  noPixels = false) const
pure virtual

Get the files used by the active series.

Parameters
noPixelsexclude pixel data files if true, or include them if false.
Returns
a list of filenames.

Implemented in ome::bioformats::detail::FormatReader, and ome::bioformats::in::OMETIFFReader.

virtual dimension_size_type ome::bioformats::FormatReader::getSizeC ( ) const
pure virtual

Get the size of the C dimension.

Returns
the C dimension size.

Implemented in ome::bioformats::detail::FormatReader.

Referenced by ome::bioformats::fillPixels().

+ Here is the caller graph for this function:

virtual dimension_size_type ome::bioformats::FormatReader::getSizeT ( ) const
pure virtual

Get the size of the T dimension.

Returns
the T dimension size.

Implemented in ome::bioformats::detail::FormatReader.

Referenced by ome::bioformats::fillPixels().

+ Here is the caller graph for this function:

virtual dimension_size_type ome::bioformats::FormatReader::getSizeX ( ) const
pure virtual

Get the size of the X dimension.

Returns
the X dimension size.

Implemented in ome::bioformats::detail::FormatReader.

Referenced by ome::qtwidgets::gl::Image2D::create(), and ome::bioformats::fillPixels().

+ Here is the caller graph for this function:

virtual dimension_size_type ome::bioformats::FormatReader::getSizeY ( ) const
pure virtual

Get the size of the Y dimension.

Returns
the Y dimension size.

Implemented in ome::bioformats::detail::FormatReader.

Referenced by ome::qtwidgets::gl::Image2D::create(), and ome::bioformats::fillPixels().

+ Here is the caller graph for this function:

virtual dimension_size_type ome::bioformats::FormatReader::getSizeZ ( ) const
pure virtual

Get the size of the Z dimension.

Returns
the Z dimension size.

Implemented in ome::bioformats::detail::FormatReader.

Referenced by ome::bioformats::fillPixels().

+ Here is the caller graph for this function:

virtual dimension_size_type ome::bioformats::FormatReader::getThumbSizeX ( ) const
pure virtual

Get the thumbnail size of the X dimension.

Returns
the X dimension thumbnail size.

Implemented in ome::bioformats::detail::FormatReader.

virtual dimension_size_type ome::bioformats::FormatReader::getThumbSizeY ( ) const
pure virtual

Get the thumbnail size of the Y dimension.

Returns
the Y dimension thumbnail size.

Implemented in ome::bioformats::detail::FormatReader.

virtual std::vector<ome::compat::shared_ptr<FormatReader> > ome::bioformats::FormatReader::getUnderlyingReaders ( ) const
pure virtual

Get all underlying readers.

Note
If there are no underlying readers, the list will be empty.
Returns
a list of readers.

Implemented in ome::bioformats::detail::FormatReader.

virtual const std::vector<boost::filesystem::path> ome::bioformats::FormatReader::getUsedFiles ( bool  noPixels = false) const
pure virtual

Get the files used by this dataset.

Parameters
noPixelsexclude pixel data files if true, or include them if false.
Returns
a list of filenames.

Implemented in ome::bioformats::detail::FormatReader.

virtual ome::compat::array<dimension_size_type, 3> ome::bioformats::FormatReader::getZCTCoords ( dimension_size_type  index) const
pure virtual

Get the Z, C and T coordinate of a linear index.

Parameters
indexthe linear index.
Returns
an array containing Z, C and T values (real sizes).
Todo:
unify with the pixel buffer dimension indexes.

Implemented in ome::bioformats::detail::FormatReader.

Referenced by ome::bioformats::fillMetadata().

+ Here is the caller graph for this function:

virtual ome::compat::array<dimension_size_type, 6> ome::bioformats::FormatReader::getZCTModuloCoords ( dimension_size_type  index) const
pure virtual

Get the Z, C, T, ModuloZ, ModuloC and ModuloT coordinate of a linear index.

Note
The Z, C and T coordinates are not the same as those returned by getZCTCoords(dimension_size_type) 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.
Parameters
indexthe linear index.
Returns
an array containing Z, C, T, ModuloZ, ModuloC and ModuloT values (effective sizes).
Todo:
unify with the pixel buffer dimension indexes.

Implemented in ome::bioformats::detail::FormatReader.

virtual bool ome::bioformats::FormatReader::hasCompanionFiles ( ) const
pure virtual

Does this format support multi-file datasets?

Returns
true if multiple files are supported, false otherwise.

Implemented in ome::bioformats::detail::FormatReader.

virtual bool ome::bioformats::FormatReader::hasFlattenedResolutions ( ) const
pure virtual

Get resolution flattening.

Returns
true if flattening is enabled, false otherwise.

Implemented in ome::bioformats::detail::FormatReader.

virtual bool ome::bioformats::FormatReader::isFalseColor ( ) const
pure virtual

Get whether the image planes are false color.

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

Returns
true if false color, false otherwise.

Implemented in ome::bioformats::detail::FormatReader.

virtual bool ome::bioformats::FormatReader::isGroupFiles ( ) const
pure virtual

Get file grouping.

Returns
true if grouping is enabled, false otherwise.

Implemented in ome::bioformats::detail::FormatReader.

virtual bool ome::bioformats::FormatReader::isIndexed ( ) const
pure virtual

Get whether the image planes are indexed color.

This value does not affect getSizeC(), getEffectiveSizeC() or getRGBChannelCount().

Returns
true if indexed, false otherwise.

Implemented in ome::bioformats::detail::FormatReader.

virtual bool ome::bioformats::FormatReader::isInterleaved ( ) const
pure virtual

Get whether or not the channels are interleaved.

This method exists because X and Y must appear first in the dimension order. For interleaved data, getDimensionOrder() returns XYCTZ or XYCZT and this method returns true.

Note that this flag returns whether or not the data returned by openBytes() 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.

Returns
true if the channels are interleaved, false otherwise.

Implemented in ome::bioformats::detail::FormatReader.

Referenced by ome::bioformats::fillPixels().

+ Here is the caller graph for this function:

virtual bool ome::bioformats::FormatReader::isInterleaved ( dimension_size_type  channel) const
pure virtual

Get whether or not the given channel is interleaved.

Some data with multiple channels within C have the sub-channels of one sub-dimension interleaved, and the other not. For example, SDTReader handles spectral-lifetime data with interleaved lifetime bins and non-interleaved spectral channels.

Parameters
channelthe channel to use, range [0, EffectiveSizeC).
Returns
true if the sub-channel is interleaved, false otherwise.

Implemented in ome::bioformats::detail::FormatReader.

virtual bool ome::bioformats::FormatReader::isLittleEndian ( ) const
pure virtual

Get whether the data is in little-endian format.

Returns
false if big endian, true if little endian.

Implemented in ome::bioformats::detail::FormatReader.

Referenced by ome::bioformats::fillPixels().

+ Here is the caller graph for this function:

virtual bool ome::bioformats::FormatReader::isMetadataComplete ( ) const
pure virtual

Get status of metadata parsing.

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

Implemented in ome::bioformats::detail::FormatReader.

virtual bool ome::bioformats::FormatReader::isMetadataFiltered ( ) const
pure virtual

Get metadata filtering.

Returns
true if metadata filtering is enabled, false if disabled.

Implemented in ome::bioformats::detail::FormatReader.

virtual bool ome::bioformats::FormatReader::isNormalized ( ) const
pure virtual

Get float normalization.

Returns
true if float normalization is enabled, false otherwise.

Implemented in ome::bioformats::detail::FormatReader.

virtual bool ome::bioformats::FormatReader::isOrderCertain ( ) const
pure virtual

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

Returns
true if the order is known, false otherwise.

Implemented in ome::bioformats::detail::FormatReader.

virtual bool ome::bioformats::FormatReader::isOriginalMetadataPopulated ( ) const
pure virtual

Get proprietary metadata storage.

Returns
true if proprietary metadata is saved in the MetadataStore, false otherwise.
Todo:
The name of this method is awful.

Implemented in ome::bioformats::detail::FormatReader.

virtual bool ome::bioformats::FormatReader::isRGB ( dimension_size_type  channel) const
pure virtual

Check if the image planes for a channel have more than one sub-channel per openBytes() call.

Parameters
channelthe channel to use, range [0, EffectiveSizeC).
Returns
true if and only if getRGBChannelCount() returns a value greater than 1, false otherwise.

Implemented in ome::bioformats::detail::FormatReader.

virtual bool ome::bioformats::FormatReader::isSingleFile ( const boost::filesystem::path &  id) const
pure virtual

Is this a single-file format?

Parameters
idfilename to check.
Returns
true if this is a single-file format, false otherwise.
Exceptions
FormatExceptionif there was a problem parsing the metadata of the file.

Implemented in ome::bioformats::detail::FormatReader, and ome::bioformats::in::OMETIFFReader.

virtual bool ome::bioformats::FormatReader::isThisType ( const boost::filesystem::path &  name,
bool  open = true 
) const
pure virtual

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

Parameters
namethe file to open for checking.
openIf 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.
Returns
true if the file is valid, false otherwise.
Todo:
Could this method be static?

Implements ome::bioformats::FormatHandler.

Implemented in ome::bioformats::detail::FormatReader, and ome::bioformats::in::OMETIFFReader.

virtual bool ome::bioformats::FormatReader::isThisType ( const uint8_t *  begin,
const uint8_t *  end 
) const
pure virtual

Check if the given buffer is a valid header for this file format.

The buffer is defined as a half-open range using two iterators.

Parameters
beginthe start of the buffer.
endone past the end of the buffer.
Returns
true if the file is valid, false otherwise.
Todo:
Could this method be static and/or const?

Implemented in ome::bioformats::detail::FormatReader.

virtual bool ome::bioformats::FormatReader::isThisType ( const uint8_t *  begin,
std::size_t  length 
) const
pure virtual

Check if the given buffer is a valid header for this file format.

The buffer is defined as a half-open range using two iterators.

Parameters
beginthe start of the buffer.
lengththe buffer length.
Returns
true if the file is valid, false otherwise.
Todo:
Could this method be static and/or const?

Implemented in ome::bioformats::detail::FormatReader.

virtual bool ome::bioformats::FormatReader::isThisType ( std::istream &  stream) const
pure virtual

Check if the given input stream is a valid stream for this file format.

Parameters
streamthe input stream to check.
Returns
true if the file is valid, false otherwise.
Todo:
Could this method be static and/or const?

Implemented in ome::bioformats::detail::FormatReader.

virtual bool ome::bioformats::FormatReader::isThumbnailSeries ( ) const
pure virtual

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

Returns
true if a low resolution copy, false otherwise.

Implemented in ome::bioformats::detail::FormatReader.

virtual void ome::bioformats::FormatReader::openBytes ( dimension_size_type  plane,
VariantPixelBuffer buf 
) const
pure virtual

Obtain an image plane.

Obtain and copy the image plane from the current series into a VariantPixelBuffer of size

Parameters
planethe plane index within the series.
bufthe destination pixel buffer.
Exceptions
FormatExceptionif there was a problem parsing the metadata of the file.

Implemented in ome::bioformats::detail::FormatReader.

Referenced by ome::qtwidgets::gl::Image2D::setPlane().

+ Here is the caller graph for this function:

virtual void ome::bioformats::FormatReader::openBytes ( dimension_size_type  plane,
VariantPixelBuffer buf,
dimension_size_type  x,
dimension_size_type  y,
dimension_size_type  w,
dimension_size_type  h 
) const
pure virtual

Obtain a sub-image of an image plane.

Obtain and copy the sub-image of an image plane from the current series into a VariantPixelBuffer of size

Parameters
planethe plane index within the series.
bufthe destination pixel buffer.
xthe X coordinate of the upper-left corner of the sub-image.
ythe Y coordinate of the upper-left corner of the sub-image.
wthe width of the sub-image.
hthe height of the sub-image.
Exceptions
FormatExceptionif there was a problem parsing the metadata of the file.

Implemented in ome::bioformats::detail::FormatReader.

virtual void ome::bioformats::FormatReader::openThumbBytes ( dimension_size_type  plane,
VariantPixelBuffer buf 
) const
pure virtual

Obtain a thumbnail of an image plane.

Obtail and copy the thumbnail for the specified image plane from the current series into a VariantPixelBuffer.

Parameters
planethe plane index within the series.
bufthe destination pixel buffer.

Implemented in ome::bioformats::detail::FormatReader.

virtual dimension_size_type ome::bioformats::FormatReader::seriesToCoreIndex ( dimension_size_type  series) const
pure virtual

Get the first core index corresponding to the specified series.

Parameters
seriesthe series to use.
Returns
the first for index for the series.

Implemented in ome::bioformats::detail::FormatReader.

virtual void ome::bioformats::FormatReader::setCoreIndex ( dimension_size_type  index) const
pure virtual

Set the current resolution/series (ignoring sub-resolutions).

Equivalent to setSeries(), but with flattened resolutions always set to false.

Parameters
indexthe core index to set.
Todo:
Remove use of stateful API which requires use of series switching in const methods.
Exceptions
std::logic_errorif the index is invalid.

Implemented in ome::bioformats::detail::FormatReader.

Referenced by ome::bioformats::FormatReader::SaveSeries::~SaveSeries().

+ Here is the caller graph for this function:

virtual void ome::bioformats::FormatReader::setFlattenedResolutions ( bool  flatten)
pure virtual

Set resolution flattening.

This controls whether or not resolution levels are flattened into individual series. This alters the behaviour of setSeries() and getSeries() but does not affect the behaviour of setCoreIndex() and getCoreIndex(), which are resolution-independent.

Parameters
flattentrue to enable flattening, false to disable.

Implemented in ome::bioformats::detail::FormatReader.

virtual void ome::bioformats::FormatReader::setGroupFiles ( bool  group)
pure virtual

Set file grouping.

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

Parameters
grouptrue to enable grouping, false to disable.

Implemented in ome::bioformats::detail::FormatReader.

virtual void ome::bioformats::FormatReader::setMetadataFiltered ( bool  filter)
pure virtual

Set metadata filtering.

If filtering is enabled, "ugly" metadata (entries with unprintable characters, and extremely large entries) should be discarded from the metadata table.

Parameters
filtertrue to enable filtering, false to disable.

Implemented in ome::bioformats::detail::FormatReader.

virtual void ome::bioformats::FormatReader::setMetadataStore ( ome::compat::shared_ptr< ::ome::xml::meta::MetadataStore > &  store)
pure virtual

Set the default metadata store for this reader.

Parameters
storea metadata store implementation.

Implemented in ome::bioformats::detail::FormatReader.

virtual void ome::bioformats::FormatReader::setNormalized ( bool  normalize)
pure virtual

Set float normalization.

Parameters
normalizetrue to enable normalization, or false to disable.

Implemented in ome::bioformats::detail::FormatReader.

virtual void ome::bioformats::FormatReader::setPlane ( dimension_size_type  plane) const
pure virtual

Set the active plane.

Parameters
planethe plane to activate.
Todo:
Remove use of stateful API which requires use of plane switching in const methods.

Implemented in ome::bioformats::detail::FormatReader.

Referenced by ome::bioformats::FormatReader::SaveSeries::~SaveSeries().

+ Here is the caller graph for this function:

virtual void ome::bioformats::FormatReader::setResolution ( dimension_size_type  resolution) const
pure virtual

Set the active resolution level.

Note
This also resets the current plane to 0.
Parameters
resolutionthe resolution to set.
See also
getResolutionCount()
Todo:
Remove use of stateful API which requires use of series switching in const methods.
Exceptions
std::logic_errorif the resolution is invalid.

Implemented in ome::bioformats::detail::FormatReader.

virtual void ome::bioformats::FormatReader::setSeries ( dimension_size_type  series) const
pure virtual

Set the active series.

Note
This also resets the resolution to 0 and the current plane to 0.
Parameters
seriesthe series to activate.
Todo:
Remove use of stateful API which requires use of series switching in const methods.
Exceptions
std::logic_errorif the series is invalid.

Implemented in ome::bioformats::detail::FormatReader.

Referenced by ome::qtwidgets::gl::Image2D::create(), ome::bioformats::fillAllPixels(), ome::bioformats::fillMetadata(), and ome::qtwidgets::gl::Image2D::setPlane().

+ Here is the caller graph for this function:


The documentation for this class was generated from the following file: