libCZI.h

// SPDX-FileCopyrightText: 2017-2022 Carl Zeiss Microscopy GmbH
//
// SPDX-License-Identifier: LGPL-3.0-or-later
 
#pragma once
 
#include <functional>
#include <memory>
#include <map>
#include <limits>
#include <string>
#include <vector>
 
#include "ImportExport.h"
 
#include "libCZI_exceptions.h"
#include "libCZI_DimCoordinate.h"
#include "libCZI_Pixels.h"
#include "libCZI_Metadata.h"
#include "libCZI_Metadata2.h"
#include "libCZI_Utilities.h"
#include "libCZI_Compositor.h"
#include "libCZI_Site.h"
#include "libCZI_compress.h"
#include "libCZI_StreamsLib.h"
 
// virtual d'tor -> https://isocpp.org/wiki/faq/virtual-functions#virtual-dtors
 
namespace libCZI
{
    enum class SiteObjectType
    {
        Default,        
        WithJxrDecoder, 
        WithWICDecoder, 
    };
 
    class ISite;
 
    LIBCZI_API ISite* GetDefaultSiteObject(libCZI::SiteObjectType type);
 
    LIBCZI_API void SetSiteObject(libCZI::ISite* pSite);
 
    class ICZIReader;
    class ICziWriter;
    class ICziReaderWriter;
    class IStream;
    class IOutputStream;
    class IInputOutputStream;
    class ISubBlock;
    class IMetadataSegment;
    class ISubBlockRepository;
    class IAttachment;
    class ISubBlockCache;
 
    struct BuildInformation
    {
        std::string compilerIdentification;
 
        std::string repositoryUrl;
 
        std::string repositoryBranch;
 
        std::string repositoryTag;
    };
 
    LIBCZI_API void GetLibCZIVersion(int* pMajor, int* pMinor = nullptr, int* pPatch = nullptr, int* pTweak = nullptr);
 
    LIBCZI_API void GetLibCZIBuildInformation(BuildInformation& info);
 
    LIBCZI_API std::shared_ptr<ICZIReader> CreateCZIReader();
 
    struct CZIWriterOptions
    {
        bool allow_duplicate_subblocks{ false };
    };
 
    LIBCZI_API std::shared_ptr<ICziWriter> CreateCZIWriter(const CZIWriterOptions* options = nullptr);
 
    LIBCZI_API std::shared_ptr<ICziReaderWriter> CreateCZIReaderWriter();
 
    LIBCZI_API std::shared_ptr<IBitmapData>  CreateBitmapFromSubBlock(ISubBlock* subBlk);
 
    LIBCZI_API std::shared_ptr<ICziMetadata> CreateMetaFromMetadataSegment(IMetadataSegment* metadataSegment);
 
    LIBCZI_API std::shared_ptr<IAccessor> CreateAccesor(std::shared_ptr<ISubBlockRepository> repository, AccessorType accessorType);
 
    LIBCZI_API std::shared_ptr<IStream> CreateStreamFromFile(const wchar_t* szFilename);
 
    LIBCZI_API std::shared_ptr<IStream> CreateStreamFromMemory(std::shared_ptr<const void> ptr, size_t dataSize);
 
    LIBCZI_API std::shared_ptr<IStream> CreateStreamFromMemory(IAttachment* attachment);
 
    LIBCZI_API std::shared_ptr<IOutputStream> CreateOutputStreamForFile(const wchar_t* szFilename, bool overwriteExisting);
 
    LIBCZI_API std::shared_ptr<IInputOutputStream> CreateInputOutputStreamForFile(const wchar_t* szFilename);
 
    LIBCZI_API std::shared_ptr<ICziMetadataBuilder> CreateMetadataBuilder();
 
    LIBCZI_API std::shared_ptr<ISubBlockCache> CreateSubBlockCache();
 
    LIBCZI_API std::shared_ptr<ICziMetadataBuilder> CreateMetadataBuilderFromXml(const std::string& xml);
 
    class IStream
    {
    public:
        virtual void Read(std::uint64_t offset, void* pv, std::uint64_t size, std::uint64_t* ptrBytesRead) = 0;
 
        virtual ~IStream() = default;
    };
 
    class IOutputStream
    {
    public:
 
        virtual void Write(std::uint64_t offset, const void* pv, std::uint64_t size, std::uint64_t* ptrBytesWritten) = 0;
        virtual ~IOutputStream() = default;
    };
 
    class IInputOutputStream : public IStream, public IOutputStream
    {
    };
 
    struct SubBlockInfo
    {
        std::int32_t            compressionModeRaw;
 
        PixelType               pixelType;
 
        libCZI::CDimCoordinate  coordinate;
 
        libCZI::IntRect         logicalRect;
 
        libCZI::IntSize         physicalSize;
 
        int                     mIndex;
 
        SubBlockPyramidType     pyramidType;
 
        double                  GetZoom() const
        {
            if (this->physicalSize.w > this->physicalSize.h)
            {
                return static_cast<double>(this->physicalSize.w) / this->logicalRect.w;
            }
 
            return static_cast<double>(this->physicalSize.h) / this->logicalRect.h;
        }
 
        CompressionMode         GetCompressionMode() const
        {
            return Utils::CompressionModeFromRawCompressionIdentifier(this->compressionModeRaw);
        }
 
        bool                    IsMindexValid() const
        {
            return libCZI::Utils::IsValidMindex(this->mIndex);
        }
    };
 
    struct DirectorySubBlockInfo : SubBlockInfo
    {
        std::uint64_t filePosition; 
    };
 
    class ISubBlock
    {
    public:
        enum MemBlkType
        {
            Metadata,   
            Data,       
            Attachment  
        };
 
        virtual const SubBlockInfo& GetSubBlockInfo() const = 0;
 
        virtual void DangerousGetRawData(MemBlkType type, const void*& ptr, size_t& size) const = 0;
 
        virtual std::shared_ptr<const void> GetRawData(MemBlkType type, size_t* ptrSize) = 0;
 
        virtual std::shared_ptr<IBitmapData> CreateBitmap() = 0;
 
        virtual ~ISubBlock() = default;
 
        template <class Q>
        void DangerousGetRawData(MemBlkType type, const Q*& ptr, size_t& size) const
        {
            const void* p;
            this->DangerousGetRawData(type, p, size);
            ptr = static_cast<const Q*>(p);
        }
    };
 
    struct AttachmentInfo
    {
        libCZI::GUID    contentGuid;            
        char            contentFileType[9];     
        std::string     name;                   
    };
 
    class IAttachment
    {
    public:
        virtual const AttachmentInfo& GetAttachmentInfo() const = 0;
 
        virtual void DangerousGetRawData(const void*& ptr, size_t& size) const = 0;
 
        virtual std::shared_ptr<const void> GetRawData(size_t* ptrSize) = 0;
 
        virtual ~IAttachment() = default;
 
        template <class Q>
        void DangerousGetRawData(const Q*& ptr, size_t& size) const
        {
            const void* p;
            this->DangerousGetRawData(p, size);
            ptr = static_cast<Q*>(p);
        }
    };
 
    class IMetadataSegment
    {
    public:
        enum MemBlkType
        {
            XmlMetadata,    
            Attachment      
        };
 
        virtual std::shared_ptr<const void> GetRawData(MemBlkType type, size_t* ptrSize) = 0;
 
        virtual void DangerousGetRawData(MemBlkType type, const void*& ptr, size_t& size) const = 0;
 
        virtual ~IMetadataSegment() = default;
 
        std::shared_ptr<ICziMetadata> CreateMetaFromMetadataSegment() { return libCZI::CreateMetaFromMetadataSegment(this); }
    };
 
    struct BoundingBoxes
    {
        IntRect boundingBox;
 
        IntRect boundingBoxLayer0;
    };
 
    struct SubBlockStatistics
    {
        int subBlockCount;
 
        int minMindex;
 
        int maxMindex;
 
        IntRect boundingBox;
 
        IntRect boundingBoxLayer0Only;
 
        CDimBounds dimBounds;
 
        std::map<int, BoundingBoxes> sceneBoundingBoxes;
 
        bool IsMIndexValid() const
        {
            return this->minMindex <= this->maxMindex ? true : false;
        }
 
        void Invalidate()
        {
            this->subBlockCount = -1;
            this->boundingBox.Invalidate();
            this->boundingBoxLayer0Only.Invalidate();
            this->dimBounds.Clear();
            this->sceneBoundingBoxes.clear();
            this->minMindex = (std::numeric_limits<int>::max)();
            this->maxMindex = (std::numeric_limits<int>::min)();
        }
    };
 
    struct PyramidStatistics
    {
        struct PyramidLayerInfo
        {
            std::uint8_t minificationFactor;    
            std::uint8_t pyramidLayerNo;        
 
            bool IsLayer0() const { return this->minificationFactor == 0 && this->pyramidLayerNo == 0; }
 
            bool IsNotIdentifiedAsPyramidLayer() const { return this->minificationFactor == 0xff && this->pyramidLayerNo == 0xff; }
        };
 
        struct PyramidLayerStatistics
        {
            PyramidLayerInfo    layerInfo;  
            int                 count;      
        };
 
        std::map<int, std::vector<PyramidLayerStatistics>> scenePyramidStatistics;
    };
 
    class LIBCZI_API ISubBlockRepository
    {
    public:
        virtual void EnumerateSubBlocks(const std::function<bool(int index, const SubBlockInfo& info)>& funcEnum) = 0;
 
        virtual void EnumSubset(const IDimCoordinate* planeCoordinate, const IntRect* roi, bool onlyLayer0, const std::function<bool(int index, const SubBlockInfo& info)>& funcEnum) = 0;
 
        virtual std::shared_ptr<ISubBlock> ReadSubBlock(int index) = 0;
 
        virtual bool TryGetSubBlockInfoOfArbitrarySubBlockInChannel(int channelIndex, SubBlockInfo& info) = 0;
 
        virtual bool TryGetSubBlockInfo(int index, SubBlockInfo* info) const = 0;
 
        virtual SubBlockStatistics GetStatistics() = 0;
 
        virtual PyramidStatistics GetPyramidStatistics() = 0;
 
        virtual libCZI::IntPointAndFrameOfReference TransformPoint(const libCZI::IntPointAndFrameOfReference& source_point, libCZI::CZIFrameOfReference destination_frame_of_reference) = 0;
 
        virtual ~ISubBlockRepository() = default;
 
        libCZI::IntRectAndFrameOfReference TransformRectangle(const libCZI::IntRectAndFrameOfReference& source_rectangle, libCZI::CZIFrameOfReference destination_frame_of_reference)
        {
            libCZI::IntPointAndFrameOfReference source_point_and_frame_of_reference;
            source_point_and_frame_of_reference.frame_of_reference = source_rectangle.frame_of_reference;
            source_point_and_frame_of_reference.point = { source_rectangle.rectangle.x, source_rectangle.rectangle.y };
            libCZI::IntPoint transformed_point_upper_left = this->TransformPoint(source_point_and_frame_of_reference, destination_frame_of_reference).point;
            source_point_and_frame_of_reference.point = { source_rectangle.rectangle.x + source_rectangle.rectangle.w, source_rectangle.rectangle.y + source_rectangle.rectangle.h };
            libCZI::IntPointAndFrameOfReference transformed_point_lower_right = this->TransformPoint(source_point_and_frame_of_reference, destination_frame_of_reference);
            return
            {
                transformed_point_lower_right.frame_of_reference,
                {
                    transformed_point_upper_left.x,
                    transformed_point_upper_left.y,
                    transformed_point_lower_right.point.x - transformed_point_upper_left.x,
                    transformed_point_lower_right.point.y - transformed_point_upper_left.y
                }
            };
        }
    };
 
    class LIBCZI_API ISubBlockRepositoryEx
    {
    public:
        virtual void EnumerateSubBlocksEx(const std::function<bool(int index, const DirectorySubBlockInfo& info)>& funcEnum) = 0;
 
        virtual ~ISubBlockRepositoryEx() = default;
    };
 
    class LIBCZI_API IAttachmentRepository
    {
    public:
        virtual void EnumerateAttachments(const std::function<bool(int index, const AttachmentInfo& info)>& funcEnum) = 0;
 
        virtual void EnumerateSubset(const char* contentFileType, const char* name, const std::function<bool(int index, const AttachmentInfo& info)>& funcEnum) = 0;
 
        virtual std::shared_ptr<IAttachment> ReadAttachment(int index) = 0;
 
        virtual ~IAttachmentRepository() = default;
    };
 
    struct FileHeaderInfo
    {
        libCZI::GUID fileGuid;
        int majorVersion;   
        int minorVersion;   
    };
 
    class LIBCZI_API ICZIReader : public ISubBlockRepository, public ISubBlockRepositoryEx, public IAttachmentRepository
    {
    public:
        struct LIBCZI_API OpenOptions
        {
            bool lax_subblock_coordinate_checks{ true };
 
            bool ignore_sizem_for_pyramid_subblocks{ false };
 
            libCZI::CZIFrameOfReference default_frame_of_reference{ libCZI::CZIFrameOfReference::Invalid };
 
            void SetDefault()
            {
                this->lax_subblock_coordinate_checks = true;
                this->ignore_sizem_for_pyramid_subblocks = false;
                this->default_frame_of_reference = libCZI::CZIFrameOfReference::Invalid;
            }
        };
 
        virtual void Open(const std::shared_ptr<IStream>& stream, const OpenOptions* options = nullptr) = 0;
 
        virtual FileHeaderInfo GetFileHeaderInfo() = 0;
 
        virtual std::shared_ptr<IMetadataSegment> ReadMetadataSegment() = 0;
 
        virtual std::shared_ptr<IAccessor> CreateAccessor(AccessorType accessorType) = 0;
 
        virtual void Close() = 0;
    public:
        std::shared_ptr<ISingleChannelTileAccessor>  CreateSingleChannelTileAccessor()
        {
            return std::dynamic_pointer_cast<ISingleChannelTileAccessor, IAccessor>(this->CreateAccessor(libCZI::AccessorType::SingleChannelTileAccessor));
        }
 
        std::shared_ptr<ISingleChannelPyramidLayerTileAccessor>  CreateSingleChannelPyramidLayerTileAccessor()
        {
            return std::dynamic_pointer_cast<ISingleChannelPyramidLayerTileAccessor, IAccessor>(this->CreateAccessor(libCZI::AccessorType::SingleChannelPyramidLayerTileAccessor));
        }
 
        std::shared_ptr<ISingleChannelScalingTileAccessor> CreateSingleChannelScalingTileAccessor()
        {
            return std::dynamic_pointer_cast<ISingleChannelScalingTileAccessor, IAccessor>(this->CreateAccessor(libCZI::AccessorType::SingleChannelScalingTileAccessor));
        }
    };
}
 
#include "libCZI_Helpers.h"
#include "libCZI_Write.h"
#include "libCZI_ReadWrite.h"