FormatReader.h

/*
 * #%L
 * OME-FILES C++ library for image IO.
 * Copyright © 2006 - 2015 Open Microscopy Environment:
 *   - Massachusetts Institute of Technology
 *   - National Institutes of Health
 *   - University of Dundee
 *   - Board of Regents of the University of Wisconsin-Madison
 *   - Glencoe Software, Inc.
 * %%
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 *
 * The views and conclusions contained in the software and documentation are
 * those of the authors and should not be interpreted as representing official
 * policies, either expressed or implied, of any organization.
 * #L%
 */

#ifndef OME_FILES_FORMATREADER_H
#define OME_FILES_FORMATREADER_H

#include <array>
#include <memory>
#include <string>
#include <vector>
#include <map>

#include <boost/optional.hpp>

#include <ome/compat/memory.h>

#include <ome/files/CoreMetadata.h>
#include <ome/files/FileInfo.h>
#include <ome/files/FormatHandler.h>
#include <ome/files/MetadataConfigurable.h>
#include <ome/files/MetadataMap.h>
#include <ome/files/Types.h>

#include <ome/xml/meta/MetadataStore.h>

namespace ome
{
  namespace files
  {

    class VariantPixelBuffer;

    class FormatReader : virtual public FormatHandler,
                         virtual public MetadataConfigurable
    {
    public:
      using FormatHandler::isThisType;

      enum FileGroupOption
        {
          MUST_GROUP,  
          CAN_GROUP,   
          CANNOT_GROUP 
        };

    protected:
      class SaveSeries
      {
      private:
        const FormatReader& reader;
        dimension_size_type coreIndex;
        dimension_size_type plane;

      public:
        SaveSeries(const FormatReader& reader):
          reader(reader),
          coreIndex(reader.getCoreIndex()),
          plane(reader.getPlane())
        {}

        ~SaveSeries()
        {
          try
            {
              if (coreIndex != reader.getCoreIndex())
                reader.setCoreIndex(coreIndex);
              if (plane != reader.getPlane())
                reader.setPlane(plane);
            }
          catch (...)
            {
              // We can't throw in a destructor.
            }
        }
      };

      FormatReader()
      {}

    private:
      FormatReader (const FormatReader&);

      FormatReader&
      operator= (const FormatReader&);

    public:
      virtual
      ~FormatReader()
      {}

      // Documented in superclass.
      virtual
      bool
      isThisType(const boost::filesystem::path& name,
                 bool                           open = true) const = 0;

      virtual
      bool
      isThisType(const uint8_t *begin,
                 const uint8_t *end) const = 0;

      virtual
      bool
      isThisType(const uint8_t *begin,
                 std::size_t    length) const = 0;

      virtual
      bool
      isThisType(std::istream& stream) const = 0;

      virtual
      dimension_size_type
      getImageCount() const = 0;

      virtual
      bool
      isRGB(dimension_size_type channel) const = 0;

      virtual
      dimension_size_type
      getSizeX() const = 0;

      virtual
      dimension_size_type
      getSizeY() const = 0;

      virtual
      dimension_size_type
      getSizeZ() const = 0;

      virtual
      dimension_size_type
      getSizeT() const = 0;

      virtual
      dimension_size_type
      getSizeC() const = 0;

      virtual
      ome::xml::model::enums::PixelType
      getPixelType() const = 0;

      virtual
      pixel_size_type
      getBitsPerPixel() const = 0;

      virtual
      dimension_size_type
      getEffectiveSizeC() const = 0;

      virtual
      dimension_size_type
      getRGBChannelCount(dimension_size_type channel) const = 0;

      virtual
      bool
      isIndexed() const = 0;

      virtual
      bool
      isFalseColor() const = 0;

      virtual
      void
      getLookupTable(dimension_size_type plane,
                     VariantPixelBuffer& buf) const = 0;

      virtual
      Modulo&
      getModuloZ() = 0;

      virtual
      const Modulo&
      getModuloZ() const = 0;

      virtual
      Modulo&
      getModuloT() = 0;

      virtual
      const Modulo&
      getModuloT() const = 0;

      virtual
      Modulo&
      getModuloC() = 0;

      virtual
      const Modulo&
      getModuloC() const = 0;

      virtual
      dimension_size_type
      getThumbSizeX() const = 0;

      virtual
      dimension_size_type
      getThumbSizeY() const = 0;

      virtual
      bool
      isLittleEndian() const = 0;

      virtual
      const std::string&
      getDimensionOrder() const = 0;

      virtual
      bool
      isOrderCertain() const = 0;

      virtual
      bool
      isThumbnailSeries() const = 0;

      virtual
      bool
      isInterleaved() const = 0;

      virtual
      bool
      isInterleaved(dimension_size_type channel) const = 0;

      virtual
      void
      openBytes(dimension_size_type plane,
                VariantPixelBuffer& buf) const = 0;

      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;

      virtual
      void
      openThumbBytes(dimension_size_type plane,
                     VariantPixelBuffer& buf) const = 0;

      virtual
      dimension_size_type
      getSeriesCount() const = 0;

      virtual
      void
      setSeries(dimension_size_type series) const = 0;

      virtual
      dimension_size_type
      getSeries() const = 0;

      virtual void
      setPlane(dimension_size_type plane) const = 0;

      virtual dimension_size_type
      getPlane() const = 0;

      virtual
      void
      setNormalized(bool normalize) = 0;

      virtual
      bool
      isNormalized() const = 0;

      virtual
      void
      setOriginalMetadataPopulated(bool populate) = 0;

      virtual
      bool
      isOriginalMetadataPopulated() const = 0;

      virtual
      void
      setGroupFiles(bool group) = 0;

      virtual
      bool
      isGroupFiles() const = 0;

      virtual
      bool
      isMetadataComplete() const = 0;

      virtual
      FileGroupOption
      fileGroupOption(const std::string& id) = 0;

      virtual
      const std::vector<boost::filesystem::path>
      getUsedFiles(bool noPixels = false) const = 0;

      virtual
      const std::vector<boost::filesystem::path>
      getSeriesUsedFiles(bool noPixels = false) const = 0;

      virtual
      std::vector<FileInfo>
      getAdvancedUsedFiles(bool noPixels = false) const = 0;

      virtual
      std::vector<FileInfo>
      getAdvancedSeriesUsedFiles(bool noPixels = false) const = 0;

      virtual
      const boost::optional<boost::filesystem::path>&
      getCurrentFile() const = 0;

      virtual
      const std::vector<std::string>&
      getDomains() const = 0;

      virtual
      dimension_size_type
      getIndex(dimension_size_type z,
               dimension_size_type c,
               dimension_size_type t) const = 0;

      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;

      virtual
      std::array<dimension_size_type, 3>
      getZCTCoords(dimension_size_type index) const = 0;

      virtual
      std::array<dimension_size_type, 6>
      getZCTModuloCoords(dimension_size_type index) const = 0;

      virtual
      const MetadataMap::value_type&
      getMetadataValue(const std::string& field) const = 0;

      virtual
      const MetadataMap::value_type&
      getSeriesMetadataValue(const MetadataMap::key_type& field) const = 0;

      virtual
      const MetadataMap&
      getGlobalMetadata() const = 0;

      virtual
      const MetadataMap&
      getSeriesMetadata() const = 0;

      virtual
      const std::vector<std::shared_ptr<CoreMetadata>>&
      getCoreMetadataList() const = 0;

      virtual
      void
      setMetadataFiltered(bool filter) = 0;

      virtual
      bool
      isMetadataFiltered() const = 0;

      virtual
      void
      setMetadataStore(std::shared_ptr<::ome::xml::meta::MetadataStore>& store) = 0;

      virtual
      const std::shared_ptr<::ome::xml::meta::MetadataStore>&
      getMetadataStore() const = 0;

      virtual
      std::shared_ptr<::ome::xml::meta::MetadataStore>&
      getMetadataStore() = 0;

      virtual
      std::vector<std::shared_ptr<FormatReader>>
      getUnderlyingReaders() const = 0;

      virtual
      bool
      isSingleFile(const boost::filesystem::path& id) const = 0;

      virtual
      uint32_t
      getRequiredDirectories(const std::vector<std::string>& files) const = 0;

      virtual
      const std::string&
      getDatasetStructureDescription() const = 0;

      virtual
      const std::vector<std::string>&
      getPossibleDomains(const std::string& id) const = 0;

      virtual
      bool
      hasCompanionFiles() const = 0;

      virtual
      dimension_size_type
      getOptimalTileWidth(dimension_size_type channel) const = 0;

      virtual
      dimension_size_type
      getOptimalTileHeight(dimension_size_type channel) const = 0;

      virtual
      dimension_size_type
      getOptimalTileWidth() const = 0;

      virtual
      dimension_size_type
      getOptimalTileHeight() const = 0;

      // Sub-resolution API methods

      virtual
      dimension_size_type
      seriesToCoreIndex(dimension_size_type series) const = 0;

      virtual
      dimension_size_type
      coreIndexToSeries(dimension_size_type index) const = 0;

      virtual
      dimension_size_type
      getCoreIndex() const = 0;

      virtual
      void
      setCoreIndex(dimension_size_type index) const = 0;

      virtual
      dimension_size_type
      getResolutionCount() const = 0;

      virtual
      void
      setResolution(dimension_size_type resolution) const = 0;

      virtual
      dimension_size_type
      getResolution() const = 0;

      virtual
      bool
      hasFlattenedResolutions() const = 0;

      virtual
      void
      setFlattenedResolutions(bool flatten) = 0;
    };

  }
}

#endif // OME_FILES_FORMATREADER_H

/*
 * Local Variables:
 * mode:C++
 * End:
 */