ome-files  0.1.1
FormatReader.h
1 /*
2  * #%L
3  * OME-FILES C++ library for image IO.
4  * Copyright © 2006 - 2015 Open Microscopy Environment:
5  * - Massachusetts Institute of Technology
6  * - National Institutes of Health
7  * - University of Dundee
8  * - Board of Regents of the University of Wisconsin-Madison
9  * - Glencoe Software, Inc.
10  * %%
11  * Redistribution and use in source and binary forms, with or without
12  * modification, are permitted provided that the following conditions are met:
13  *
14  * 1. Redistributions of source code must retain the above copyright notice,
15  * this list of conditions and the following disclaimer.
16  * 2. Redistributions in binary form must reproduce the above copyright notice,
17  * this list of conditions and the following disclaimer in the documentation
18  * and/or other materials provided with the distribution.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
24  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
25  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
26  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
27  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
28  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
29  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
30  * POSSIBILITY OF SUCH DAMAGE.
31  *
32  * The views and conclusions contained in the software and documentation are
33  * those of the authors and should not be interpreted as representing official
34  * policies, either expressed or implied, of any organization.
35  * #L%
36  */
37 
38 #ifndef OME_FILES_FORMATREADER_H
39 #define OME_FILES_FORMATREADER_H
40 
41 #include <string>
42 #include <vector>
43 #include <map>
44 
45 #include <boost/optional.hpp>
46 
47 #include <ome/files/CoreMetadata.h>
48 #include <ome/files/FileInfo.h>
49 #include <ome/files/FormatHandler.h>
50 #include <ome/files/MetadataConfigurable.h>
51 #include <ome/files/MetadataMap.h>
52 #include <ome/files/Types.h>
53 
54 #include <ome/compat/array.h>
55 
56 #include <ome/xml/meta/MetadataStore.h>
57 
58 namespace ome
59 {
60  namespace files
61  {
62 
63  class VariantPixelBuffer;
64 
70  class FormatReader : virtual public FormatHandler,
71  virtual public MetadataConfigurable
72  {
73  public:
75 
78  {
82  };
83 
84  protected:
97  class SaveSeries
98  {
99  private:
106 
107  public:
113  SaveSeries(const FormatReader& reader):
114  reader(reader),
115  coreIndex(reader.getCoreIndex()),
116  plane(reader.getPlane())
117  {}
118 
125  {
126  try
127  {
128  if (coreIndex != reader.getCoreIndex())
129  reader.setCoreIndex(coreIndex);
130  if (plane != reader.getPlane())
131  reader.setPlane(plane);
132  }
133  catch (...)
134  {
135  // We can't throw in a destructor.
136  }
137  }
138  };
139 
142  {}
143 
144  private:
146  FormatReader (const FormatReader&);
147 
149  FormatReader&
150  operator= (const FormatReader&);
151 
152  public:
154  virtual
156  {}
157 
158  // Documented in superclass.
159  virtual
160  bool
161  isThisType(const boost::filesystem::path& name,
162  bool open = true) const = 0;
163 
176  virtual
177  bool
178  isThisType(const uint8_t *begin,
179  const uint8_t *end) const = 0;
180 
193  virtual
194  bool
195  isThisType(const uint8_t *begin,
196  std::size_t length) const = 0;
197 
206  virtual
207  bool
208  isThisType(std::istream& stream) const = 0;
209 
215  virtual
217  getImageCount() const = 0;
218 
227  virtual
228  bool
229  isRGB(dimension_size_type channel) const = 0;
230 
236  virtual
238  getSizeX() const = 0;
239 
245  virtual
247  getSizeY() const = 0;
248 
254  virtual
256  getSizeZ() const = 0;
257 
263  virtual
265  getSizeT() const = 0;
266 
272  virtual
274  getSizeC() const = 0;
275 
281  virtual
283  getPixelType() const = 0;
284 
294  virtual
296  getBitsPerPixel() const = 0;
297 
309  virtual
311  getEffectiveSizeC() const = 0;
312 
324  virtual
326  getRGBChannelCount(dimension_size_type channel) const = 0;
327 
336  virtual
337  bool
338  isIndexed() const = 0;
339 
350  virtual
351  bool
352  isFalseColor() const = 0;
353 
370  virtual
371  void
373  VariantPixelBuffer& buf) const = 0;
374 
380  virtual
381  Modulo&
382  getModuloZ() = 0;
383 
389  virtual
390  const Modulo&
391  getModuloZ() const = 0;
392 
398  virtual
399  Modulo&
400  getModuloT() = 0;
401 
407  virtual
408  const Modulo&
409  getModuloT() const = 0;
410 
416  virtual
417  Modulo&
418  getModuloC() = 0;
419 
425  virtual
426  const Modulo&
427  getModuloC() const = 0;
428 
434  virtual
436  getThumbSizeX() const = 0;
437 
443  virtual
445  getThumbSizeY() const = 0;
446 
452  virtual
453  bool
454  isLittleEndian() const = 0;
455 
474  virtual
475  const std::string&
476  getDimensionOrder() const = 0;
477 
483  virtual
484  bool
485  isOrderCertain() const = 0;
486 
493  virtual
494  bool
495  isThumbnailSeries() const = 0;
496 
515  virtual
516  bool
517  isInterleaved() const = 0;
518 
532  virtual
533  bool
534  isInterleaved(dimension_size_type channel) const = 0;
535 
551  virtual
552  void
554  VariantPixelBuffer& buf) const = 0;
555 
575  virtual
576  void
578  VariantPixelBuffer& buf,
582  dimension_size_type h) const = 0;
583 
593  virtual
594  void
596  VariantPixelBuffer& buf) const = 0;
597 
606  virtual
608  getSeriesCount() const = 0;
609 
623  virtual
624  void
625  setSeries(dimension_size_type series) const = 0;
626 
632  virtual
634  getSeries() const = 0;
635 
644  virtual void
645  setPlane(dimension_size_type plane) const = 0;
646 
652  virtual dimension_size_type
653  getPlane() const = 0;
654 
661  virtual
662  void
663  setNormalized(bool normalize) = 0;
664 
672  virtual
673  bool
674  isNormalized() const = 0;
675 
680  virtual
681  void
682  setOriginalMetadataPopulated(bool populate) = 0;
683 
692  virtual
693  bool
694  isOriginalMetadataPopulated() const = 0;
695 
703  virtual
704  void
705  setGroupFiles(bool group) = 0;
706 
712  virtual
713  bool
714  isGroupFiles() const = 0;
715 
722  virtual
723  bool
724  isMetadataComplete() const = 0;
725 
733  virtual
735  fileGroupOption(const std::string& id) = 0;
736 
744  virtual
745  const std::vector<boost::filesystem::path>
746  getUsedFiles(bool noPixels = false) const = 0;
747 
755  virtual
756  const std::vector<boost::filesystem::path>
757  getSeriesUsedFiles(bool noPixels = false) const = 0;
758 
767  virtual
768  std::vector<FileInfo>
769  getAdvancedUsedFiles(bool noPixels = false) const = 0;
770 
779  virtual
780  std::vector<FileInfo>
781  getAdvancedSeriesUsedFiles(bool noPixels = false) const = 0;
782 
788  virtual
789  const boost::optional<boost::filesystem::path>&
790  getCurrentFile() const = 0;
791 
797  virtual
798  const std::vector<std::string>&
799  getDomains() const = 0;
800 
815  virtual
819  dimension_size_type t) const = 0;
820 
844  virtual
849  dimension_size_type moduloZ,
850  dimension_size_type moduloC,
851  dimension_size_type moduloT) const = 0;
852 
862  virtual
863  ome::compat::array<dimension_size_type, 3>
864  getZCTCoords(dimension_size_type index) const = 0;
865 
882  virtual
883  ome::compat::array<dimension_size_type, 6>
884  getZCTModuloCoords(dimension_size_type index) const = 0;
885 
897  virtual
899  getMetadataValue(const std::string& field) const = 0;
900 
912  virtual
914  getSeriesMetadataValue(const MetadataMap::key_type& field) const = 0;
915 
924  virtual
925  const MetadataMap&
926  getGlobalMetadata() const = 0;
927 
936  virtual
937  const MetadataMap&
938  getSeriesMetadata() const = 0;
939 
948  virtual
949  const std::vector<ome::compat::shared_ptr<CoreMetadata> >&
950  getCoreMetadataList() const = 0;
951 
962  virtual
963  void
964  setMetadataFiltered(bool filter) = 0;
965 
972  virtual
973  bool
974  isMetadataFiltered() const = 0;
975 
981  virtual
982  void
983  setMetadataStore(ome::compat::shared_ptr< ::ome::xml::meta::MetadataStore>& store) = 0;
984 
990  virtual
991  const ome::compat::shared_ptr< ::ome::xml::meta::MetadataStore>&
992  getMetadataStore() const = 0;
993 
999  virtual
1000  ome::compat::shared_ptr< ::ome::xml::meta::MetadataStore>&
1001  getMetadataStore() = 0;
1002 
1011  virtual
1012  std::vector<ome::compat::shared_ptr<FormatReader> >
1013  getUnderlyingReaders() const = 0;
1014 
1025  virtual
1026  bool
1027  isSingleFile(const boost::filesystem::path& id) const = 0;
1028 
1059  virtual
1060  uint32_t
1061  getRequiredDirectories(const std::vector<std::string>& files) const = 0;
1062 
1068  virtual
1069  const std::string&
1070  getDatasetStructureDescription() const = 0;
1071 
1082  virtual
1083  const std::vector<std::string>&
1084  getPossibleDomains(const std::string& id) const = 0;
1085 
1092  virtual
1093  bool
1094  hasCompanionFiles() const = 0;
1095 
1104  virtual
1106  getOptimalTileWidth(dimension_size_type channel) const = 0;
1107 
1116  virtual
1118  getOptimalTileHeight(dimension_size_type channel) const = 0;
1119 
1133  virtual
1135  getOptimalTileWidth() const = 0;
1136 
1150  virtual
1152  getOptimalTileHeight() const = 0;
1153 
1154  // Sub-resolution API methods
1155 
1162  virtual
1164  seriesToCoreIndex(dimension_size_type series) const = 0;
1165 
1172  virtual
1174  coreIndexToSeries(dimension_size_type index) const = 0;
1175 
1181  virtual
1183  getCoreIndex() const = 0;
1184 
1198  virtual
1199  void
1200  setCoreIndex(dimension_size_type index) const = 0;
1201 
1211  virtual
1213  getResolutionCount() const = 0;
1214 
1229  virtual
1230  void
1231  setResolution(dimension_size_type resolution) const = 0;
1232 
1240  virtual
1242  getResolution() const = 0;
1243 
1249  virtual
1250  bool
1251  hasFlattenedResolutions() const = 0;
1252 
1264  virtual
1265  void
1266  setFlattenedResolutions(bool flatten) = 0;
1267  };
1268 
1269  }
1270 }
1271 
1272 #endif // OME_FILES_FORMATREADER_H
1273 
1274 /*
1275  * Local Variables:
1276  * mode:C++
1277  * End:
1278  */
virtual Modulo & getModuloT()=0
Get the Modulo subdivision of the T dimension.
virtual dimension_size_type getOptimalTileHeight() const =0
Get the optimal sub-image height.
virtual dimension_size_type getSizeZ() const =0
Get the size of the Z dimension.
virtual void openBytes(dimension_size_type plane, VariantPixelBuffer &buf) const =0
Obtain an image plane.
virtual const MetadataMap & getSeriesMetadata() const =0
Get series metadata map.
virtual bool isOriginalMetadataPopulated() const =0
Get proprietary metadata storage.
virtual bool isFalseColor() const =0
Get whether the image planes are false color.
virtual dimension_size_type seriesToCoreIndex(dimension_size_type series) const =0
Get the first core index corresponding to the specified series.
virtual void setSeries(dimension_size_type series) const =0
Set the active series.
Files may be grouped.
Definition: FormatReader.h:80
uint32_t pixel_size_type
Size type for pixel bit depths.
Definition: Types.h:62
virtual void setMetadataStore(ome::compat::shared_ptr< ::ome::xml::meta::MetadataStore > &store)=0
Set the default metadata store for this reader.
virtual std::vector< FileInfo > getAdvancedUsedFiles(bool noPixels=false) const =0
Get the files used by this dataset.
virtual dimension_size_type getSizeT() const =0
Get the size of the T dimension.
virtual std::vector< FileInfo > getAdvancedSeriesUsedFiles(bool noPixels=false) const =0
Get the files used by the active series.
std::size_t dimension_size_type
Size type for image dimensions.
Definition: Types.h:59
virtual bool isGroupFiles() const =0
Get file grouping.
virtual void setFlattenedResolutions(bool flatten)=0
Set resolution flattening.
virtual const MetadataMap & getGlobalMetadata() const =0
Get global metadata map.
~SaveSeries()
Destructor.
Definition: FormatReader.h:124
virtual Modulo & getModuloC()=0
Get the Modulo subdivision of the C dimension.
boost::make_variant_over< discriminated_types >::type value_type
Value type, allowing assignment of all storable types.
Definition: MetadataMap.h:147
Sentry for saving and restoring reader series state.
Definition: FormatReader.h:97
FileGroupOption
File grouping options.
Definition: FormatReader.h:77
virtual void openThumbBytes(dimension_size_type plane, VariantPixelBuffer &buf) const =0
Obtain a thumbnail of an image plane.
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...
FormatReader & operator=(const FormatReader &)
Assignment operator (deleted).
virtual dimension_size_type getSeries() const =0
Get the active series.
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.
Metadata key-value map using a restricted set of value types.
Definition: MetadataMap.h:79
virtual const std::vector< ome::compat::shared_ptr< CoreMetadata > > & getCoreMetadataList() const =0
Get the core metadata.
virtual bool isIndexed() const =0
Get whether the image planes are indexed color.
virtual bool isNormalized() const =0
Get float normalization.
virtual dimension_size_type getSizeX() const =0
Get the size of the X dimension.
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.
virtual dimension_size_type coreIndexToSeries(dimension_size_type index) const =0
Get the series corresponding to the specified core index.
dimension_size_type coreIndex
Saved core index.
Definition: FormatReader.h:103
virtual dimension_size_type getSeriesCount() const =0
Get the number of image series in this file.
const FormatReader & reader
Reader for which the state will be saved and restored.
Definition: FormatReader.h:101
virtual dimension_size_type getRGBChannelCount(dimension_size_type channel) const =0
Get the number of channels returned for a call to openBytes().
virtual void setGroupFiles(bool group)=0
Set file grouping.
virtual const std::string & getDimensionOrder() const =0
Get the dimension order.
virtual void setOriginalMetadataPopulated(bool populate)=0
Specifies whether or not to save proprietary metadata in the MetadataStore.
virtual bool isLittleEndian() const =0
Get whether the data is in little-endian format.
virtual pixel_size_type getBitsPerPixel() const =0
Get the number of valid bits per pixel.
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.
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.
std::string key_type
Key type.
Definition: MetadataMap.h:144
virtual dimension_size_type getSizeY() const =0
Get the size of the Y dimension.
virtual const std::vector< std::string > & getDomains() const =0
Get the domains represented by the current file.
virtual dimension_size_type getImageCount() const =0
Determine the number of image planes in the current series.
Files can not be grouped.
Definition: FormatReader.h:81
virtual bool hasCompanionFiles() const =0
Does this format support multi-file datasets?
virtual ~FormatReader()
Destructor.
Definition: FormatReader.h:155
virtual bool hasFlattenedResolutions() const =0
Get resolution flattening.
Metadata configuration interface.
Definition: MetadataConfigurable.h:53
virtual FileGroupOption fileGroupOption(const std::string &id)=0
Returns an enum indicating that we cannot, must, or might group the files in this dataset...
Files must be grouped.
Definition: FormatReader.h:79
virtual const std::string & getDatasetStructureDescription() const =0
Get a short description of the dataset structure.
virtual const ome::compat::shared_ptr< ::ome::xml::meta::MetadataStore > & getMetadataStore() const =0
Get the current metadata store for this reader.
virtual dimension_size_type getSizeC() const =0
Get the size of the C dimension.
virtual void setResolution(dimension_size_type resolution) const =0
Set the active resolution level.
virtual dimension_size_type getCoreIndex() const =0
Get the CoreMetadata index of the current resolution/series.
virtual bool isInterleaved() const =0
Get whether or not the channels are interleaved.
virtual void setCoreIndex(dimension_size_type index) const =0
Set the current resolution/series (ignoring sub-resolutions).
virtual dimension_size_type getThumbSizeY() const =0
Get the thumbnail size of the Y dimension.
virtual const std::vector< boost::filesystem::path > getUsedFiles(bool noPixels=false) const =0
Get the files used by this dataset.
dimension_size_type plane
Saved plane index.
Definition: FormatReader.h:105
virtual dimension_size_type getThumbSizeX() const =0
Get the thumbnail size of the X dimension.
virtual bool isThumbnailSeries() const =0
Get whether the current series is a lower resolution copy of a different series.
virtual const boost::optional< boost::filesystem::path > & getCurrentFile() const =0
Get the currently open file.
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.
virtual ome::xml::model::enums::PixelType getPixelType() const =0
Get the pixel type.
virtual dimension_size_type getPlane() const =0
Get the active plane.
virtual void setNormalized(bool normalize)=0
Set float normalization.
Interface for all biological file format readers.
Definition: FormatReader.h:70
virtual bool isMetadataFiltered() const =0
Get metadata filtering.
virtual void setMetadataFiltered(bool filter)=0
Set metadata filtering.
virtual dimension_size_type getResolution() const =0
Get the active resolution level.
virtual const MetadataMap::value_type & getMetadataValue(const std::string &field) const =0
Get a global metadata value.
virtual const std::vector< boost::filesystem::path > getSeriesUsedFiles(bool noPixels=false) const =0
Get the files used by the active series.
virtual const MetadataMap::value_type & getSeriesMetadataValue(const MetadataMap::key_type &field) const =0
Get a series metadata value.
virtual dimension_size_type getEffectiveSizeC() const =0
Get the effective size of the C dimension.
virtual void setPlane(dimension_size_type plane) const =0
Set the active plane.
A subdimension of Z, C, or T.
Definition: Modulo.h:57
virtual dimension_size_type getOptimalTileWidth() const =0
Get the optimal sub-image width.
virtual std::vector< ome::compat::shared_ptr< FormatReader > > getUnderlyingReaders() const =0
Get all underlying readers.
virtual uint32_t getRequiredDirectories(const std::vector< std::string > &files) const =0
Get required parent directories.
virtual bool isSingleFile(const boost::filesystem::path &id) const =0
Is this a single-file format?
virtual bool isMetadataComplete() const =0
Get status of metadata parsing.
virtual bool isOrderCertain() const =0
Get whether the dimension order and sizes are known, or merely guesses.
Buffer for all pixel types.
Definition: VariantPixelBuffer.h:75
virtual Modulo & getModuloZ()=0
Get the Modulo subdivision of the Z dimension.
virtual void getLookupTable(dimension_size_type plane, VariantPixelBuffer &buf) const =0
Get the color lookup table associated with an image plane.
virtual dimension_size_type getResolutionCount() const =0
Get the number of resolutions for the current series.
Interface for all biological file format readers and writers.
Definition: FormatHandler.h:64
FormatReader()
Constructor.
Definition: FormatReader.h:141
virtual const std::vector< std::string > & getPossibleDomains(const std::string &id) const =0
Get the possible domains represented in which this format is used.
SaveSeries(const FormatReader &reader)
Constructor.
Definition: FormatReader.h:113