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_DETAIL_FORMATREADER_H
#define OME_FILES_DETAIL_FORMATREADER_H

#include <string>
#include <vector>
#include <map>

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

namespace ome
{
  namespace files
  {
    namespace detail
    {

      struct ReaderProperties
      {
        std::string name;
        std::string description;
        std::vector<boost::filesystem::path> suffixes;
        std::vector<boost::filesystem::path> compression_suffixes;
        std::set<MetadataOptions::MetadataLevel> metadata_levels;

        ReaderProperties(const std::string& name,
                         const std::string& description):
          name(name),
          description(description),
          suffixes(),
          compression_suffixes(),
          metadata_levels()
        {
          compression_suffixes.push_back(boost::filesystem::path(""));
        }
      };

      class FormatReader : public ::ome::files::FormatReader,
                           virtual public ::ome::files::FormatHandler
      {
      protected:
        typedef std::vector<std::shared_ptr<::ome::files::CoreMetadata>> coremetadata_list_type;

        const ReaderProperties& readerProperties;

        boost::optional<boost::filesystem::path> currentId;

        std::shared_ptr<std::istream> in;

        ::ome::files::MetadataMap metadata;

        mutable dimension_size_type coreIndex;

        mutable dimension_size_type series;

        mutable dimension_size_type plane;

        coremetadata_list_type core;

        mutable dimension_size_type resolution;

        bool flattenedResolutions;

        bool suffixNecessary;

        bool suffixSufficient;

        bool companionFiles;

        std::string datasetDescription;

        bool normalizeData;

        bool filterMetadata;

        bool saveOriginalMetadata;

        bool indexedAsRGB;

        bool group;

        std::vector<std::string> domains;

        std::shared_ptr<::ome::xml::meta::MetadataStore> metadataStore;

        MetadataOptions metadataOptions;

        FormatReader(const ReaderProperties&);

        FormatReader (const FormatReader&) = delete;

        FormatReader&
        operator= (const FormatReader&) = delete;

      public:
        virtual
        ~FormatReader();

      protected:
        virtual
        void
        initFile(const boost::filesystem::path& id);

        virtual
        bool
        isUsedFile(const boost::filesystem::path& file);

        virtual
        void
        readPlane(std::istream&       source,
                  VariantPixelBuffer& dest,
                  dimension_size_type x,
                  dimension_size_type y,
                  dimension_size_type w,
                  dimension_size_type h,
                  dimension_size_type samples);

        virtual
        void
        readPlane(std::istream&       source,
                  VariantPixelBuffer& dest,
                  dimension_size_type x,
                  dimension_size_type y,
                  dimension_size_type w,
                  dimension_size_type h,
                  dimension_size_type scanlinePad,
                  dimension_size_type samples);

        virtual
        std::shared_ptr<::ome::xml::meta::MetadataStore>
        makeFilterMetadata();

        const CoreMetadata&
        getCoreMetadata(dimension_size_type index) const
        {
          coremetadata_list_type::value_type cm(core.at(index));
          if (!cm)
            throw std::logic_error("CoreMetadata null");
          return *cm;
        }

        CoreMetadata&
        getCoreMetadata(dimension_size_type index)
        {
          coremetadata_list_type::value_type cm(core.at(index));
          if (!cm)
            throw std::logic_error("CoreMetadata null");
          return *cm;
        }

      public:
        // Documented in superclass.
        const std::set<MetadataOptions::MetadataLevel>&
        getSupportedMetadataLevels();

        // Documented in superclass.
        void
        setMetadataOptions(const MetadataOptions& options);

        // Documented in superclass.
        const MetadataOptions&
        getMetadataOptions() const;

        MetadataOptions&
        getMetadataOptions();

        // Documented in superclass.
        const MetadataMap&
        getGlobalMetadata() const;

        // Documented in superclass.
        const MetadataMap::value_type&
        getMetadataValue(const std::string& field) const;

        // Documented in superclass.
        const MetadataMap&
        getSeriesMetadata() const;

        // Documented in superclass.
        const MetadataMap::value_type&
        getSeriesMetadataValue(const MetadataMap::key_type& field) const;

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

        // Documented in superclass.
        bool
        isThisType(const uint8_t *begin,
                   std::size_t    length) const;

        // Documented in superclass.
        bool
        isThisType(const uint8_t *begin,
                   const uint8_t *end) const;

        // Documented in superclass.
        bool
        isThisType(std::istream& stream) const;

      protected:
        virtual
        bool
        isFilenameThisTypeImpl(const boost::filesystem::path& name) const;

        virtual
        bool
        isStreamThisTypeImpl(std::istream& stream) const;

      public:
        // Documented in superclass.
        dimension_size_type
        getImageCount() const;

        // Documented in superclass.
        bool
        isRGB(dimension_size_type channel) const;

        // Documented in superclass.
        dimension_size_type
        getSizeX() const;

        // Documented in superclass.
        dimension_size_type
        getSizeY() const;

        // Documented in superclass.
        dimension_size_type
        getSizeZ() const;

        // Documented in superclass.
        dimension_size_type
        getSizeT() const;

        // Documented in superclass.
        dimension_size_type
        getSizeC() const;

        // Documented in superclass.
        ome::xml::model::enums::PixelType
        getPixelType() const;

        // Documented in superclass.
        pixel_size_type
        getBitsPerPixel() const;

        // Documented in superclass.
        dimension_size_type
        getEffectiveSizeC() const;

        // Documented in superclass.
        dimension_size_type
        getRGBChannelCount(dimension_size_type channel) const;

        // Documented in superclass.
        bool
        isIndexed() const;

        // Documented in superclass.
        bool
        isFalseColor() const;

        // Documented in superclass.
        void
        getLookupTable(dimension_size_type plane,
                       VariantPixelBuffer& buf) const;

        // Documented in superclass.
        Modulo&
        getModuloZ();

        // Documented in superclass.
        const Modulo&
        getModuloZ() const;

        // Documented in superclass.
        Modulo&
        getModuloT();

        // Documented in superclass.
        const Modulo&
        getModuloT() const;

        // Documented in superclass.
        Modulo&
        getModuloC();

        // Documented in superclass.
        const Modulo&
        getModuloC() const;

      protected:
        std::array<dimension_size_type, 2>
        getThumbSize() const;

      public:
        // Documented in superclass.
        dimension_size_type
        getThumbSizeX() const;

        // Documented in superclass.
        dimension_size_type
        getThumbSizeY() const;

        // Documented in superclass.
        bool
        isLittleEndian() const;

        // Documented in superclass.
        const std::string&
        getDimensionOrder() const;

        // Documented in superclass.
        bool
        isOrderCertain() const;

        // Documented in superclass.
        bool
        isThumbnailSeries() const;

        // Documented in superclass.
        bool
        isInterleaved() const;

        // Documented in superclass.
        bool
        isInterleaved(dimension_size_type subC) const;

        // Documented in superclass.
        void
        openBytes(dimension_size_type plane,
                  VariantPixelBuffer& buf) const;

        // Documented in superclass.
        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;

      protected:
        virtual
        void
        openBytesImpl(dimension_size_type plane,
                      VariantPixelBuffer& buf,
                      dimension_size_type x,
                      dimension_size_type y,
                      dimension_size_type w,
                      dimension_size_type h) const = 0;

      public:
        // Documented in superclass.
        void
        openThumbBytes(dimension_size_type plane,
                       VariantPixelBuffer& buf) const;

        // Documented in superclass.
        void
        close(bool fileOnly = false);

        // Documented in superclass.
        dimension_size_type
        getSeriesCount() const;

        // Documented in superclass.
        void
        setSeries(dimension_size_type series) const;

        // Documented in superclass.
        dimension_size_type
        getSeries() const;

        // Documented in superclass.
        void
        setPlane(dimension_size_type plane) const;

        // Documented in superclass.
        dimension_size_type
        getPlane() const;

        // Documented in superclass.
        void
        setGroupFiles(bool group);

        // Documented in superclass.
        bool
        isGroupFiles() const;

        // Documented in superclass.
        FileGroupOption
        fileGroupOption(const std::string& id);

        // Documented in superclass.
        bool
        isMetadataComplete() const;

        // Documented in superclass.
        void
        setNormalized(bool normalize);

        // Documented in superclass.
        bool
        isNormalized() const;

        // Documented in superclass.
        void
        setOriginalMetadataPopulated(bool populate);

        // Documented in superclass.
        bool
        isOriginalMetadataPopulated() const;

        // Documented in superclass.
        const std::vector<boost::filesystem::path>
        getUsedFiles(bool noPixels = false) const;

        // Documented in superclass.
        const std::vector<boost::filesystem::path>
        getSeriesUsedFiles(bool noPixels = false) const;

        // Documented in superclass.
        std::vector<FileInfo>
        getAdvancedUsedFiles(bool noPixels = false) const;

        // Documented in superclass.
        std::vector<FileInfo>
        getAdvancedSeriesUsedFiles(bool noPixels = false) const;

        // Documented in superclass.
        const boost::optional<boost::filesystem::path>&
        getCurrentFile() const;

        // Documented in superclass.
        dimension_size_type
        getIndex(dimension_size_type z,
                 dimension_size_type c,
                 dimension_size_type t) const;

        // Documented in superclass.
        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;

        // Documented in superclass.
        std::array<dimension_size_type, 3>
        getZCTCoords(dimension_size_type index) const;

        // Documented in superclass.
        std::array<dimension_size_type, 6>
        getZCTModuloCoords(dimension_size_type index) const;

        // Documented in superclass.
        const std::vector<std::shared_ptr<::ome::files::CoreMetadata>>&
        getCoreMetadataList() const;

        // Documented in superclass.
        void
        setMetadataFiltered(bool filter);

        // Documented in superclass.
        bool
        isMetadataFiltered() const;

        // Documented in superclass.
        void
        setMetadataStore(std::shared_ptr<::ome::xml::meta::MetadataStore>& store);

        // Documented in superclass.
        const std::shared_ptr<::ome::xml::meta::MetadataStore>&
        getMetadataStore() const;

        // Documented in superclass.
        std::shared_ptr<::ome::xml::meta::MetadataStore>&
        getMetadataStore();

        // Documented in superclass.
        std::vector<std::shared_ptr<::ome::files::FormatReader>>
        getUnderlyingReaders() const;

        // Documented in superclass.
        bool
        isSingleFile(const boost::filesystem::path& id) const;

        // Documented in superclass.
        uint32_t
        getRequiredDirectories(const std::vector<std::string>& files) const;

        // Documented in superclass.
        const std::string&
        getDatasetStructureDescription() const;

        // Documented in superclass.
        const std::vector<std::string>&
        getPossibleDomains(const std::string& id) const;

        // Documented in superclass.
        bool
        hasCompanionFiles() const;

        // Documented in superclass.
        const std::vector<std::string>&
        getDomains() const;

        // Documented in superclass.
        dimension_size_type
        getOptimalTileWidth(dimension_size_type channel) const;

        // Documented in superclass.
        dimension_size_type
        getOptimalTileHeight(dimension_size_type channel) const;

        // Documented in superclass.
        dimension_size_type
        getOptimalTileWidth() const;

        // Documented in superclass.
        dimension_size_type
        getOptimalTileHeight() const;

        // Documented in superclass.
        dimension_size_type
        seriesToCoreIndex(dimension_size_type series) const;

        // Documented in superclass.
        dimension_size_type
        coreIndexToSeries(dimension_size_type index) const;

        // Documented in superclass.
        dimension_size_type
        getCoreIndex() const;

        // Documented in superclass.
        void
        setCoreIndex(dimension_size_type index) const;

        // Documented in superclass.
        dimension_size_type
        getResolutionCount() const;

        // Documented in superclass.
        void
        setResolution(dimension_size_type resolution) const;

        // Documented in superclass.
        dimension_size_type
        getResolution() const;

        // Documented in superclass.
        bool
        hasFlattenedResolutions() const;

        // Documented in superclass.
        void
        setFlattenedResolutions(bool flatten);

        // Documented in superclass.
        void
        setId(const boost::filesystem::path& id);

        // Documented in superclass.
        const std::string&
        getFormat() const;

        // Documented in superclass.
        const std::string&
        getFormatDescription() const;

        // Documented in superclass.
        const std::vector<boost::filesystem::path>&
        getSuffixes() const;

        // Documented in superclass.
        const std::vector<boost::filesystem::path>&
        getCompressionSuffixes() const;
      };

    }
  }
}

#endif // OME_FILES_DETAIL_FORMATREADER_H

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