ome-files 0.1.0

- Main Page
- Related Pages
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

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

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

`#include <ome/files/FormatReader.h>`

Inheritance diagram for ome::files::FormatReader:
[legend]
Collaboration diagram for ome::files::FormatReader:
[legend]

## 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 Modulo & | getModuloZ ()=0
| Get the Modulo subdivision of the Z dimension. More...
virtual const Modulo & | getModuloZ () const =0
| Get the Modulo subdivision of the Z dimension. More...
virtual Modulo & | getModuloT ()=0
| Get the Modulo subdivision of the T dimension. More...
virtual const Modulo & | getModuloT () const =0
| Get the Modulo subdivision of the T dimension. More...
virtual Modulo & | getModuloC ()=0
| Get the Modulo subdivision of the C dimension. More...
virtual const Modulo & | getModuloC () 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< FileInfo > | getAdvancedUsedFiles (bool noPixels=false) const =0
| Get the files used by this dataset. More...
virtual std::vector< FileInfo > | getAdvancedSeriesUsedFiles (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_type & | getMetadataValue (const std::string &field) const =0
| Get a global metadata value. More...
virtual const MetadataMap::value_type & | getSeriesMetadataValue (const MetadataMap::key_type &field) const =0
| Get a series metadata value. More...
virtual const MetadataMap & | getGlobalMetadata () const =0
| Get global metadata map. More...
virtual const MetadataMap & | getSeriesMetadata () 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::files::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::files::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 MetadataOptions & | getMetadataOptions () const =0
| Get metadata options. More...
virtual MetadataOptions & | getMetadataOptions ()=0
| Get metadata options. More...

## Protected Member Functions
| FormatReader ()
| Constructor.
Protected Member Functions inherited from ome::files::FormatHandler
| FormatHandler ()
| Constructor.
Protected Member Functions inherited from ome::files::MetadataConfigurable
| MetadataConfigurable ()
| Constructor.

## Private Member Functions
| FormatReader (const FormatReader &)
| Copy constructor (deleted).
FormatReader & | operator= (const FormatReader &)
| Assignment operator (deleted).

## Additional Inherited Members
Static Public Member Functions inherited from ome::files::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

enum ome::files::FormatReader::FileGroupOption

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::files::FormatReader::coreIndexToSeries | ( | dimension_size_type | index | ) | const
| pure virtual

Get the series corresponding to the specified core index.

Parameters

  index | the core index to use.

Returns
  the series for the index.

Implemented in ome::files::detail::FormatReader.

virtual FileGroupOption ome::files::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

  id | filename to check.

Returns
  the grouping option for the specified file.

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

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

Get the files used by the active series.

Parameters

  noPixels | exclude pixel data files if `true`, or include them if `false`.

Returns
  a list of FileInfo objects representing each used file.

Implemented in ome::files::detail::FormatReader.

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

Get the files used by this dataset.

Parameters

  noPixels | exclude pixel data files if `true`, or include them if `false`.

Returns
  a list of FileInfo objects representing each used file.

Implemented in ome::files::detail::FormatReader.

virtual pixel_size_type ome::files::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::files::detail::FormatReader.

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

Here is the caller graph for this function:

virtual dimension_size_type ome::files::FormatReader::getCoreIndex | ( |  | ) | const
| pure virtual

Get the CoreMetadata index of the current resolution/series.

Returns
  the index.

Implemented in ome::files::detail::FormatReader.

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

Here is the caller graph for this function:

virtual const std::vector<ome::compat::shared_ptr<CoreMetadata> >& ome::files::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::files::detail::FormatReader.

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

Get the currently open file.

Returns
  the filename.

Implemented in ome::files::detail::FormatReader.

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

Here is the caller graph for this function:

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

Get a short description of the dataset structure.

Returns
  a short description.

Implemented in ome::files::detail::FormatReader.

virtual const std::string& ome::files::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::files::detail::FormatReader.

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

Here is the caller graph for this function:

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

Get the domains represented by the current file.

Returns
  a list of domains.

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

virtual dimension_size_type ome::files::FormatReader::getEffectiveSizeC | ( |  | ) | const
| pure virtual

Get the effective size of the C dimension.

This guarantees that

getEffectiveSizeC() * getSizeZ() * getSizeT() == getImageCount()

regardless of the result of isRGB().

Returns
  the effective C dimension size.

Implemented in ome::files::detail::FormatReader.

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

Here is the caller graph for this function:

virtual const MetadataMap& ome::files::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::files::detail::FormatReader.

virtual dimension_size_type ome::files::FormatReader::getImageCount | ( |  | ) | const
| pure virtual

Determine the number of image planes in the current series.

Returns
  the number of image planes.

Implemented in ome::files::detail::FormatReader.

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

Here is the caller graph for this function:

virtual dimension_size_type ome::files::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

  z | the `Z` coordinate (real size).
  c | the `C` coordinate (real size).
  t | the `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::files::detail::FormatReader.

virtual dimension_size_type ome::files::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

  z | the `Z` coordinate (effective size).
  c | the `C` coordinate (effective size).
  t | the `T` coordinate (effective size).
  moduloZ | the `ModuloZ` coordinate (effective size).
  moduloC | the `ModuloC` coordinate (effective size).
  moduloT | the `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::files::detail::FormatReader.

virtual void ome::files::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

  buf | the destination pixel buffer.
  plane | the plane index within the series.

Exceptions

  FormatException | if a lookup table could not be obtained.

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

virtual const ome::compat::shared_ptr< ::ome::xml::meta::MetadataStore>& ome::files::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::files::detail::FormatReader.

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

Get the current metadata store for this reader.

Returns
  the metadata store, which will never be `null`.

Implemented in ome::files::detail::FormatReader.

virtual const MetadataMap::value_type& ome::files::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

  field | the name associated with the metadata field.

Returns
  the value.

Exceptions

  boost::bad_get | on failure if the key was not found.

Implemented in ome::files::detail::FormatReader.

virtual Modulo& ome::files::FormatReader::getModuloC | ( |  | ) |
| pure virtual

Get the Modulo subdivision of the C dimension.

Returns
  the Modulo defining the C dimension subdivision.

Implemented in ome::files::detail::FormatReader.

virtual const Modulo& ome::files::FormatReader::getModuloC | ( |  | ) | const
| pure virtual

Get the Modulo subdivision of the C dimension.

Returns
  the Modulo defining the C dimension subdivision.

Implemented in ome::files::detail::FormatReader.

virtual Modulo& ome::files::FormatReader::getModuloT | ( |  | ) |
| pure virtual

Get the Modulo subdivision of the T dimension.

Returns
  the Modulo defining the T dimension subdivision.

Implemented in ome::files::detail::FormatReader.

virtual const Modulo& ome::files::FormatReader::getModuloT | ( |  | ) | const
| pure virtual

Get the Modulo subdivision of the T dimension.

Returns
  the Modulo defining the T dimension subdivision.

Implemented in ome::files::detail::FormatReader.

virtual Modulo& ome::files::FormatReader::getModuloZ | ( |  | ) |
| pure virtual

Get the Modulo subdivision of the Z dimension.

Returns
  the Modulo defining the Z dimension subdivision.

Implemented in ome::files::detail::FormatReader.

virtual const Modulo& ome::files::FormatReader::getModuloZ | ( |  | ) | const
| pure virtual

Get the Modulo subdivision of the Z dimension.

Returns
  the Modulo defining the Z dimension subdivision.

Implemented in ome::files::detail::FormatReader.

virtual dimension_size_type ome::files::FormatReader::getOptimalTileHeight | ( | dimension_size_type | channel | ) | const
| pure virtual

Get the optimal sub-image height.

This is intended for use with openBytes().

Parameters

  channel | the channel to use, range [0, EffectiveSizeC).

Returns
  the optimal height.

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

virtual dimension_size_type ome::files::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::files::detail::FormatReader.

virtual dimension_size_type ome::files::FormatReader::getOptimalTileWidth | ( | dimension_size_type | channel | ) | const
| pure virtual

Get the optimal sub-image width.

This is intended for use with openBytes().

Parameters

  channel | the channel to use, range [0, EffectiveSizeC).

Returns
  the optimal width.

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

virtual dimension_size_type ome::files::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::files::detail::FormatReader.

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

Get the pixel type.

Returns
  the pixel type.

Implemented in ome::files::detail::FormatReader.

Referenced by ome::files::fillMetadata(), and ome::files::fillPixels().

Here is the caller graph for this function:

virtual dimension_size_type ome::files::FormatReader::getPlane | ( |  | ) | const
| pure virtual

Get the active plane.

Returns
  the active plane.

Implemented in ome::files::detail::FormatReader.

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

Here is the caller graph for this function:

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

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

Parameters

  id | filename to check.

Returns
  a list of domains.

Exceptions

  FormatException | if there was a problem parsing the metadata of the file.

Todo:
  can this be a reference to static data?

Implemented in ome::files::detail::FormatReader.

virtual uint32_t ome::files::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

  files | the file list being processed.

Returns
  the number of important parent directories for the file list.

Exceptions

  FormatException | if 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::files::detail::FormatReader.

virtual dimension_size_type ome::files::FormatReader::getResolution | ( |  | ) | const
| pure virtual

Get the active resolution level.

Returns
  the resolution level.

See also
  getResolutionCount()

Implemented in ome::files::detail::FormatReader.

virtual dimension_size_type ome::files::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::files::detail::FormatReader.

virtual dimension_size_type ome::files::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

  channel | the channel to use, range [0, EffectiveSizeC).

Returns
  the number of channels.

Implemented in ome::files::detail::FormatReader.

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

Here is the caller graph for this function:

virtual dimension_size_type ome::files::FormatReader::getSeries | ( |  | ) | const
| pure virtual

Get the active series.

Returns
  the active series.

Implemented in ome::files::detail::FormatReader.

Referenced by ome::files::fillAllPixels(), ome::files::fillMetadata(), and ome::files::fillPixels().

Here is the caller graph for this function:

virtual dimension_size_type ome::files::FormatReader::getSeriesCount | ( |  | ) | const
| pure virtual

Get the number of image series in this file.

Returns
  the number of image series.

Exceptions

  std::logic_error | if the sub-resolution metadata (if any) is invalid; this will only occur if the reader sets invalid metadata.

Implemented in ome::files::detail::FormatReader.

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

Here is the caller graph for this function:

virtual const MetadataMap& ome::files::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::files::detail::FormatReader.

virtual const MetadataMap::value_type& ome::files::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

  field | the name associated with the metadata field.

Returns
  the value.

Exceptions

  boost::bad_get | on failure if the key was not found.

Implemented in ome::files::detail::FormatReader.

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

Get the files used by the active series.

Parameters

  noPixels | exclude pixel data files if `true`, or include them if `false`.

Returns
  a list of filenames.

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

virtual dimension_size_type ome::files::FormatReader::getSizeC | ( |  | ) | const
| pure virtual

Get the size of the C dimension.

Returns
  the C dimension size.

Implemented in ome::files::detail::FormatReader.

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

Here is the caller graph for this function:

virtual dimension_size_type ome::files::FormatReader::getSizeT | ( |  | ) | const
| pure virtual

Get the size of the T dimension.

Returns
  the T dimension size.

Implemented in ome::files::detail::FormatReader.

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

Here is the caller graph for this function:

virtual dimension_size_type ome::files::FormatReader::getSizeX | ( |  | ) | const
| pure virtual

Get the size of the X dimension.

Returns
  the X dimension size.

Implemented in ome::files::detail::FormatReader.

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

Here is the caller graph for this function:

virtual dimension_size_type ome::files::FormatReader::getSizeY | ( |  | ) | const
| pure virtual

Get the size of the Y dimension.

Returns
  the Y dimension size.

Implemented in ome::files::detail::FormatReader.

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

Here is the caller graph for this function:

virtual dimension_size_type ome::files::FormatReader::getSizeZ | ( |  | ) | const
| pure virtual

Get the size of the Z dimension.

Returns
  the Z dimension size.

Implemented in ome::files::detail::FormatReader.

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

Here is the caller graph for this function:

virtual dimension_size_type ome::files::FormatReader::getThumbSizeX | ( |  | ) | const
| pure virtual

Get the thumbnail size of the X dimension.

Returns
  the X dimension thumbnail size.

Implemented in ome::files::detail::FormatReader.

virtual dimension_size_type ome::files::FormatReader::getThumbSizeY | ( |  | ) | const
| pure virtual

Get the thumbnail size of the Y dimension.

Returns
  the Y dimension thumbnail size.

Implemented in ome::files::detail::FormatReader.

virtual std::vector<ome::compat::shared_ptr<FormatReader> > ome::files::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::files::detail::FormatReader.

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

Get the files used by this dataset.

Parameters

  noPixels | exclude pixel data files if `true`, or include them if `false`.

Returns
  a list of filenames.

Implemented in ome::files::detail::FormatReader.

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

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

Parameters

  index | the linear index.

Returns
  an array containing `Z`, `C` and `T` values (real sizes).

Todo:
  unify with the pixel buffer dimension indexes.

Implemented in ome::files::detail::FormatReader.

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

Here is the caller graph for this function:

virtual ome::compat::array<dimension_size_type, 6> ome::files::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

  index | the 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::files::detail::FormatReader.

virtual bool ome::files::FormatReader::hasCompanionFiles | ( |  | ) | const
| pure virtual

Does this format support multi-file datasets?

Returns
  `true` if multiple files are supported, `false` otherwise.

Implemented in ome::files::detail::FormatReader.

virtual bool ome::files::FormatReader::hasFlattenedResolutions | ( |  | ) | const
| pure virtual

Get resolution flattening.

Returns
  `true` if flattening is enabled, `false` otherwise.

Implemented in ome::files::detail::FormatReader.

virtual bool ome::files::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::files::detail::FormatReader.

virtual bool ome::files::FormatReader::isGroupFiles | ( |  | ) | const
| pure virtual

Get file grouping.

Returns
  `true` if grouping is enabled, `false` otherwise.

Implemented in ome::files::detail::FormatReader.

virtual bool ome::files::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::files::detail::FormatReader.

virtual bool ome::files::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::files::detail::FormatReader.

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

Here is the caller graph for this function:

virtual bool ome::files::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

  channel | the channel to use, range [0, EffectiveSizeC).

Returns
  `true` if the sub-channel is interleaved, `false` otherwise.

Implemented in ome::files::detail::FormatReader.

virtual bool ome::files::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::files::detail::FormatReader.

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

Here is the caller graph for this function:

virtual bool ome::files::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::files::detail::FormatReader.

virtual bool ome::files::FormatReader::isMetadataFiltered | ( |  | ) | const
| pure virtual

Get metadata filtering.

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

Implemented in ome::files::detail::FormatReader.

virtual bool ome::files::FormatReader::isNormalized | ( |  | ) | const
| pure virtual

Get float normalization.

Returns
  `true` if float normalization is enabled, `false` otherwise.

Implemented in ome::files::detail::FormatReader.

virtual bool ome::files::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::files::detail::FormatReader.

virtual bool ome::files::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::files::detail::FormatReader.

virtual bool ome::files::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

  channel | the channel to use, range [0, EffectiveSizeC).

Returns
  `true` if and only if getRGBChannelCount() returns a value greater than 1, `false` otherwise.

Implemented in ome::files::detail::FormatReader.

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

Is this a single-file format?

Parameters

  id | filename to check.

Returns
  `true` if this is a single-file format, `false` otherwise.

Exceptions

  FormatException | if there was a problem parsing the metadata of the file.

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

virtual bool ome::files::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

  name | the file to open for checking.
  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.

Returns
  `true` if the file is valid, `false` otherwise.

Todo:
  Could this method be static?

Implements ome::files::FormatHandler.

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

virtual bool ome::files::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

  begin | the start of the buffer.
  end | one 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::files::detail::FormatReader.

virtual bool ome::files::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

  begin | the start of the buffer.
  length | the buffer length.

Returns
  `true` if the file is valid, `false` otherwise.

Todo:
  Could this method be static and/or const?

Implemented in ome::files::detail::FormatReader.

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

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

Parameters

  stream | the 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::files::detail::FormatReader.

virtual bool ome::files::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::files::detail::FormatReader.

virtual void ome::files::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

getSizeX * getSizeY * bytesPerPixel * getRGBChannelCount(channel)

Parameters

  plane | the plane index within the series.
  buf | the destination pixel buffer.

Exceptions

  FormatException | if there was a problem parsing the metadata of the file.

Implemented in ome::files::detail::FormatReader.

virtual void ome::files::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

w * h * bytesPerPixel * getRGBChannelCount(channel)

Parameters

  plane | the plane index within the series.
  buf | the destination pixel buffer.
  x | the `X` coordinate of the upper-left corner of the sub-image.
  y | the `Y` coordinate of the upper-left corner of the sub-image.
  w | the width of the sub-image.
  h | the height of the sub-image.

Exceptions

  FormatException | if there was a problem parsing the metadata of the file.

Implemented in ome::files::detail::FormatReader.

virtual void ome::files::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

  plane | the plane index within the series.
  buf | the destination pixel buffer.

Implemented in ome::files::detail::FormatReader.

virtual dimension_size_type ome::files::FormatReader::seriesToCoreIndex | ( | dimension_size_type | series | ) | const
| pure virtual

Get the first core index corresponding to the specified series.

Parameters

  series | the series to use.

Returns
  the first for index for the series.

Implemented in ome::files::detail::FormatReader.

virtual void ome::files::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

  index | the core index to set.

Todo:
  Remove use of stateful API which requires use of series switching in const methods.

Exceptions

  std::logic_error | if the index is invalid.

Implemented in ome::files::detail::FormatReader.

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

Here is the caller graph for this function:

virtual void ome::files::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

  flatten | `true` to enable flattening, `false` to disable.

Implemented in ome::files::detail::FormatReader.

virtual void ome::files::FormatReader::setGroupFiles | ( | bool | group | ) |
| pure virtual

Set file grouping.

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

Parameters

  group | `true` to enable grouping, `false` to disable.

Implemented in ome::files::detail::FormatReader.

virtual void ome::files::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

  filter | `true` to enable filtering, `false` to disable.

Implemented in ome::files::detail::FormatReader.

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

Set the default metadata store for this reader.

Parameters

  store | a metadata store implementation.

Implemented in ome::files::detail::FormatReader.

virtual void ome::files::FormatReader::setNormalized | ( | bool | normalize | ) |
| pure virtual

Set float normalization.

Parameters

  normalize | `true` to enable normalization, or `false` to disable.

Implemented in ome::files::detail::FormatReader.

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

Set the active plane.

Parameters

  plane | the plane to activate.

Todo:
  Remove use of stateful API which requires use of plane switching in const methods.

Implemented in ome::files::detail::FormatReader.

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

Here is the caller graph for this function:

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

Set the active resolution level.

Note
  This also resets the current plane to 0.

Parameters

  resolution | the resolution to set.

See also
  getResolutionCount()

Todo:
  Remove use of stateful API which requires use of series switching in const methods.

Exceptions

  std::logic_error | if the resolution is invalid.

Implemented in ome::files::detail::FormatReader.

virtual void ome::files::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

  series | the series to activate.

Todo:
  Remove use of stateful API which requires use of series switching in const methods.

Exceptions

  std::logic_error | if the series is invalid.

Implemented in ome::files::detail::FormatReader.

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

Here is the caller graph for this function:

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

- ome/files/FormatReader.h