ome-files 0.2.2

Classes | Public Member Functions | Protected Types | Protected Member Functions | Protected Attributes | Private Member Functions | Private Attributes | List of all members
ome::files::out::OMETIFFWriter Class Reference

TIFF writer with support for OME-XML metadata. More...

`#include <ome/files/out/OMETIFFWriter.h>`

Inheritance diagram for ome::files::out::OMETIFFWriter:
[legend]
Collaboration diagram for ome::files::out::OMETIFFWriter:
[legend]

## Classes
struct | SeriesState
| Current state of an image series. More...
struct | TIFFState
| State of TIFF file. More...

## Public Member Functions
| OMETIFFWriter ()
| Constructor.
virtual | ~OMETIFFWriter ()
| Destructor.
void | setId (const boost::filesystem::path &id)
| Set the current file name. More...
void | close (bool fileOnly=false)
| Close the currently open file. More...
void | setSeries (dimension_size_type series) const
| Set the active series. More...
void | setPlane (dimension_size_type plane) const
| Set the active plane. More...
void | saveBytes (dimension_size_type plane, VariantPixelBuffer &buf, dimension_size_type x, dimension_size_type y, dimension_size_type w, dimension_size_type h)
| Save an image plane. More...
void | setBigTIFF (boost::optional< bool > big=true)
| Set use of BigTIFF support. More...
boost::optional< bool > | getBigTIFF () const
| Query use of BigTIFF support. More...
Public Member Functions inherited from ome::files::detail::FormatWriter
virtual | ~FormatWriter ()
| Destructor.
bool | isThisType (const boost::filesystem::path &name, bool open=true) const
| Check if the given file is a valid instance of this file format. More...
virtual dimension_size_type | getSeriesCount () const
| Get the number of image series in this file. More...
void | setLookupTable (dimension_size_type plane, const VariantPixelBuffer &buf)
| Set the color lookup table associated with the current series. More...
void | saveBytes (dimension_size_type plane, VariantPixelBuffer &buf)
| Save an image plane. More...
dimension_size_type | getSeries () const
| Get the active series. More...
dimension_size_type | getPlane () const
| Get the active plane. More...
bool | canDoStacks () const
| Get whether or not the writer can save multiple images in a single file. More...
void | setMetadataRetrieve (ome::compat::shared_ptr< ::ome::xml::meta::MetadataRetrieve > &retrieve)
| Set the default metadata store for this writer. More...
const ome::compat::shared_ptr< ::ome::xml::meta::MetadataRetrieve > & | getMetadataRetrieve () const
| Get the current metadata store for this writer. More...
ome::compat::shared_ptr< ::ome::xml::meta::MetadataRetrieve > & | getMetadataRetrieve ()
| Get the current metadata store for this writer. More...
virtual dimension_size_type | getImageCount () const
| Determine the number of image planes in the current series. More...
virtual bool | isRGB (dimension_size_type channel) const
| Does a channel contain subchannels? More...
virtual dimension_size_type | getSizeX () const
| Get the size of the X dimension. More...
virtual dimension_size_type | getSizeY () const
| Get the size of the Y dimension. More...
virtual dimension_size_type | getSizeZ () const
| Get the size of the Z dimension. More...
virtual dimension_size_type | getSizeT () const
| Get the size of the T dimension. More...
virtual dimension_size_type | getSizeC () const
| Get the size of the C dimension. More...
virtual ome::xml::model::enums::PixelType | getPixelType () const
| Get the pixel type. More...
virtual pixel_size_type | getBitsPerPixel () const
| Get the number of valid bits per pixel. More...
virtual dimension_size_type | getEffectiveSizeC () const
| Get the effective size of the C dimension. More...
virtual dimension_size_type | getRGBChannelCount (dimension_size_type channel) const
| Get the number of channels required for a call to saveBytes(). More...
virtual const std::string & | getDimensionOrder () const
| Get the dimension order. More...
virtual dimension_size_type | getIndex (dimension_size_type z, dimension_size_type c, dimension_size_type t) const
| Get the linear index of a `Z`, `C` and `T` coordinate. More...
virtual ome::compat::array< dimension_size_type, 3 > | getZCTCoords (dimension_size_type index) const
| Get the `Z`, `C` and `T` coordinate of a linear index. More...
void | setFramesPerSecond (frame_rate_type rate)
| Set the frame rate to use when writing. More...
frame_rate_type | getFramesPerSecond () const
| Get the frame rate to use when writing. More...
const std::set< ome::xml::model::enums::PixelType > & | getPixelTypes () const
| Get supported pixel types. More...
const std::set< ome::xml::model::enums::PixelType > & | getPixelTypes (const std::string &codec) const
| Get supported pixel types for the given codec. More...
bool | isSupportedType (ome::xml::model::enums::PixelType type) const
| Check if the pixel type is supported. More...
bool | isSupportedType (ome::xml::model::enums::PixelType type, const std::string &codec) const
| Check if the pixel type is supported by the given codex. More...
const std::set< std::string > & | getCompressionTypes () const
| Get supported compression types. More...
void | setCompression (const std::string &compression)
| Set the compression type to use when writing. More...
const boost::optional< std::string > & | getCompression () const
| Get the compression type to use when writing. More...
void | setInterleaved (bool interleaved)
| Set subchannel interleaving. More...
const boost::optional< bool > & | getInterleaved () const
| Set subchannel interleaving. More...
void | changeOutputFile (const boost::filesystem::path &id)
| Switch the output file for the current dataset. More...
void | setWriteSequentially (bool sequential=true)
| Write planes sequentially. More...
bool | getWriteSequentially () const
| Check if planes are written sequentially. More...
const std::string & | getFormat () const
| Get the name of this file format. More...
const std::string & | getFormatDescription () const
| Get the description of this file format. More...
const std::vector< boost::filesystem::path > & | getSuffixes () const
| Get the default file suffixes for this file format. More...
const std::vector< boost::filesystem::path > & | getCompressionSuffixes () const
| Get the default compression suffixes for this file format. More...
Public Member Functions inherited from ome::files::FormatHandler
virtual | ~FormatHandler ()
| Destructor.

## Protected Types
typedef std::map< boost::filesystem::path, std::string > | file_uuid_map
| Map filename to UUID.
typedef std::map< boost::filesystem::path, TIFFState > | tiff_map
| Map filename to TIFF state.
typedef std::vector< SeriesState > | series_list
| Vector of SeriesState objects.

## Protected Member Functions
void | nextIFD () const
| Flush current IFD and create new IFD.
void | setupIFD () const
| Set IFD parameters for the current series.
Protected Member Functions inherited from ome::files::detail::FormatWriter
| FormatWriter (const WriterProperties &)
| Constructor.
Protected Member Functions inherited from ome::files::FormatWriter
| FormatWriter ()
| Constructor.
Protected Member Functions inherited from ome::files::FormatHandler
| FormatHandler ()
| Constructor.

## Protected Attributes
ome::common::Logger | logger
| Message logger.
boost::filesystem::path | baseDir
| Base path for computing relative paths in the OME-XML.
file_uuid_map | files
| UUID to filename mapping.
tiff_map | tiffs
| Open TIFF files.
tiff_map::iterator | currentTIFF
| Current TIFF file.
std::string | flags
| TIFF flags.
series_list | seriesState
| State of each series.
ome::compat::shared_ptr< ::ome::xml::meta::MetadataRetrieve > | originalMetadataRetrieve
| Original MetadataRetrieve. More...
ome::compat::shared_ptr< ome::xml::meta::OMEXMLMetadata > | omeMeta
| OME-XML metadata for embedding in the TIFF.
Protected Attributes inherited from ome::files::detail::FormatWriter
const WriterProperties & | writerProperties
| Writer properties specific to the derived file format.
boost::optional< boost::filesystem::path > | currentId
| The identifier (path) of the currently open file.
ome::compat::shared_ptr< std::ostream > | out
| Current output.
dimension_size_type | series
| Current series.
dimension_size_type | plane
| Current plane.
boost::optional< std::string > | compression
| The compression type to use.
boost::optional< bool > | interleaved
| Subchannel interleaving enabled.
bool | sequential
| Planes are written sequentially.
frame_rate_type | framesPerSecond
| The frames per second to use when writing.
ome::compat::shared_ptr< ::ome::xml::meta::MetadataRetrieve > | metadataRetrieve
| Current metadata store. More...

## Private Member Functions
void | fillMetadata ()
| Fill MetadataStore with cached metadata. More...
std::string | getOMEXML (const boost::filesystem::path &id)
| Get OME-XML for embedding into the specified TIFF file. More...
void | saveComment (const boost::filesystem::path &id, const std::string &xml)
| Save OME-XML text in the first IFD of the specified TIFF file. More...

## Private Attributes
boost::optional< bool > | bigTIFF
| Write a Big TIFF.

## Additional Inherited Members
Public Types inherited from ome::files::FormatWriter
typedef uint16_t | frame_rate_type
| Frame rate type.
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

TIFF writer with support for OME-XML metadata.

## Member Function Documentation

## § close()

void ome::files::out::OMETIFFWriter::close | ( | bool | fileOnly = `false` | ) |
| virtual

Close the currently open file.

An exception may be thrown when closing the file, for example if there are problems flushing any pending writes, or if there are any inconsistencies in the metadata which prevent completing any final writes. The causes are reader- or writer-dependent, and the exception type is dependent upon the implementation details of the reader or writer in use. It is advised to always explicitly close writers, since if this is automatically called at destruction time, any errors will be lost. If an exception is thrown, the object may be left in an inconsistent state and should not be reused.

Parameters

  fileOnly | close the open file only if `true`, or else free all internal state if `false`; only meaningful for readers, since writers will always free all internal state.

Exceptions

  On | error; exception type may vary.

Reimplemented from ome::files::detail::FormatWriter.

References bigTIFF, ome::files::detail::FormatWriter::close(), ome::files::detail::FormatWriter::currentId, currentTIFF, files, fillMetadata(), flags, getOMEXML(), nextIFD(), omeMeta, originalMetadataRetrieve, ome::files::removeBinData(), ome::files::removeTiffData(), saveComment(), seriesState, and tiffs.

Referenced by ~OMETIFFWriter().

Here is the caller graph for this function:

## § fillMetadata()

void ome::files::out::OMETIFFWriter::fillMetadata | ( |  | ) |
| private

Fill MetadataStore with cached metadata.

Set Image, Channel and TiffData elements.

References baseDir, ome::files::detail::FormatWriter::getSeriesCount(), ome::files::getZCTCoords(), make_relative(), ome::files::detail::FormatWriter::metadataRetrieve, omeMeta, ome::files::detail::FormatWriter::plane, ome::files::detail::OMETIFFPlane::PRESENT, ome::files::detail::FormatWriter::series, seriesState, and tiffs.

Referenced by close().

Here is the caller graph for this function:

## § getBigTIFF()

boost::optional< bool > ome::files::out::OMETIFFWriter::getBigTIFF | ( |  | ) | const

Query use of BigTIFF support.

If setBigTIFF has not been used to enable or disable BigTIFF explicitly, BigTIFF support will be disabled by default for data less than 4GiB, unless the data would be larger than 4GiB, in which case it will be enabled by default.

Returns
  `true` if BigTIFF support are enabled, or `false` if disabled.

References bigTIFF.

## § getOMEXML()

std::string ome::files::out::OMETIFFWriter::getOMEXML | ( | const boost::filesystem::path & | id | ) |
| private

Get OME-XML for embedding into the specified TIFF file.

Parameters

  id | the TIFF in which to embed the OME-XML.

Returns
  the OME-XML text for embedding.

References baseDir, ome::files::getOMEXML(), make_relative(), omeMeta, and tiffs.

Referenced by close().

Here is the caller graph for this function:

## § saveBytes()

void ome::files::out::OMETIFFWriter::saveBytes | ( | dimension_size_type | plane,
|  | VariantPixelBuffer & | buf,
|  | dimension_size_type | x,
|  | dimension_size_type | y,
|  | dimension_size_type | w,
|  | dimension_size_type | h
| ) |  |
| virtual

Save an image plane.

Write an image plane from a VariantPixelBuffer of size

getSizeX * getSizeY * bytesPerPixel * getRGBChannelCount()

to the current series in the current file.

Parameters

  plane | the plane index within the series.
  buf | the source 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 any of the parameters are invalid.

Implements ome::files::FormatWriter.

References ome::files::FormatHandler::assertId(), ome::files::detail::FormatWriter::currentId, currentTIFF, ome::files::detail::FormatWriter::getSeries(), ome::files::detail::OMETIFFPlane::id, ome::files::detail::OMETIFFPlane::PRESENT, seriesState, and setPlane().

## § saveComment()

void ome::files::out::OMETIFFWriter::saveComment | ( | const boost::filesystem::path & | id,
|  | const std::string & | xml
| ) |  |
| private

Save OME-XML text in the first IFD of the specified TIFF file.

Parameters

  id | the TIFF in which to embed the OME-XML.
  xml | the OME-XML text to embed.

References ome::files::ENDIAN_BIG, ome::files::ENDIAN_LITTLE, and ome::files::ENDIAN_NATIVE.

Referenced by close().

Here is the caller graph for this function:

## § setBigTIFF()

void ome::files::out::OMETIFFWriter::setBigTIFF | ( | boost::optional< bool > | big = `true` | ) |

Set use of BigTIFF support.

Enable or disable use of BigTIFF support for writing files larger than 4GiB.

Note
  libtiff must be compiled with BigTIFF support enabled for this option to have any effect.

Parameters

  big | `true` to enable or `false` to disable BigTIFF support.

References bigTIFF.

## § setId()

void ome::files::out::OMETIFFWriter::setId | ( | const boost::filesystem::path & | id | ) |
| virtual

Set the current file name.

Note this will throw FormatException if there are problems opening the file.

Parameters

  id | the filename to open.

Reimplemented from ome::files::detail::FormatWriter.

References ome::files::detail::OMETIFFPlane::ABSENT, baseDir, bigTIFF, ome::files::detail::OMETIFFPlane::certain, ome::files::detail::FormatWriter::currentId, currentTIFF, flags, ome::files::detail::FormatWriter::getMetadataRetrieve(), logger, ome::files::detail::FormatWriter::metadataRetrieve, omeMeta, ome::files::tiff::TIFF::open(), originalMetadataRetrieve, ome::files::pixelSize(), ome::files::detail::FormatWriter::plane, ome::files::out::OMETIFFWriter::SeriesState::planes, ome::files::detail::FormatWriter::series, seriesState, ome::files::detail::FormatWriter::setId(), setupIFD(), ome::files::significantPixelSize(), tiffs, and ome::files::validateModel().

## § setPlane()

void ome::files::out::OMETIFFWriter::setPlane | ( | dimension_size_type | plane | ) | const
| 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.

Reimplemented from ome::files::detail::FormatWriter.

References ome::files::detail::FormatWriter::getPlane(), nextIFD(), ome::files::detail::FormatWriter::setPlane(), and setupIFD().

Referenced by saveBytes().

Here is the caller graph for this function:

## § setSeries()

void ome::files::out::OMETIFFWriter::setSeries | ( | dimension_size_type | series | ) | const
| virtual

Set the active series.

Parameters

  series | the series to activate.

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

Reimplemented from ome::files::detail::FormatWriter.

References ome::files::detail::FormatWriter::getSeries(), nextIFD(), ome::files::detail::FormatWriter::setSeries(), and setupIFD().

## Member Data Documentation

## § originalMetadataRetrieve

ome::compat::shared_ptr< ::ome::xml::meta::MetadataRetrieve> ome::files::out::OMETIFFWriter::originalMetadataRetrieve
| protected

Original MetadataRetrieve.

We replace it with the generated OME-XML metadata store.

Todo:
  Overriding getMetadataRetrieve will be a cleaner solution, but need to eliminate all direct use of metadataRetrieve in all writers first.

Referenced by close(), and setId().

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

- ome/files/out/OMETIFFWriter.h
- ome/files/out/OMETIFFWriter.cpp