libCZI_Metadata.h

// SPDX-FileCopyrightText: 2017-2022 Carl Zeiss Microscopy GmbH
//
// SPDX-License-Identifier: LGPL-3.0-or-later
 
#pragma once
 
#include "ImportExport.h"
#include "libCZI_DimCoordinate.h"
#include "libCZI_Pixels.h"
#include <limits>
#include <string>
#include <vector>
#include <map>
#include <functional>
#include <memory>
#include <cmath>
#include <sstream>
#include <stdexcept>
 
namespace libCZI
{
    struct SubBlockStatistics;
 
    struct LIBCZI_API XmlDateTime
    {
        int sec;   
        int min;   
        int hour;  
        int mday;  
        int mon;   
        int year;  
 
        bool isUTC;
 
        int offsetHours;
 
        int offsetMinutes;
 
        void Clear()
        {
            this->sec = this->min = this->hour = this->mday = this->mon = this->year = 0;
            this->isUTC = false;
            this->offsetHours = (std::numeric_limits<int>::min)();
            this->offsetMinutes = (std::numeric_limits<int>::min)();
        }
 
        bool HasTimeZoneOffset() const
        {
            if (this->isUTC)
            {
                return false;
            }
 
            if (this->offsetHours <= -24 || this->offsetHours >= 24 || this->offsetMinutes >= 60 || this->offsetMinutes < 0)
            {
                return false;
            }
 
            return true;
        }
 
        std::string ToXmlString() const;
 
        std::wstring ToXmlWstring() const;
 
        bool IsValid() const;
 
        static bool TryParse(const char* sz, XmlDateTime* ptrDateTime);
 
        static bool TryParse(const wchar_t* szw, XmlDateTime* ptrDateTime);
    };
 
    struct GeneralDocumentInfo
    {
        LIBCZI_API GeneralDocumentInfo() : name_valid(false), title_valid(false), userName_valid(false), description_valid(false), comment_valid(false), keywords_valid(false), rating_valid(false), rating(0), creationDateTime_valid(false) {}
        bool name_valid;                
        std::wstring name;              
        bool title_valid;               
        std::wstring title;             
        bool userName_valid;            
        std::wstring userName;          
        bool description_valid;         
        std::wstring description;       
        bool comment_valid;             
        std::wstring comment;           
        bool keywords_valid;            
        std::wstring keywords;          
        bool rating_valid;              
        int rating;                     
        bool creationDateTime_valid;    
        std::wstring creationDateTime;  
 
        LIBCZI_API void SetName(const wchar_t* sz) { this->SetMember(&GeneralDocumentInfo::name, &GeneralDocumentInfo::name_valid, sz); }
 
        LIBCZI_API void SetName(const std::wstring& str) { this->SetName(str.c_str()); }
 
        LIBCZI_API void SetTitle(const wchar_t* sz) { this->SetMember(&GeneralDocumentInfo::title, &GeneralDocumentInfo::title_valid, sz); }
 
        LIBCZI_API void SetTitle(const std::wstring& str) { this->SetTitle(str.c_str()); }
 
        LIBCZI_API void SetUserName(const wchar_t* sz) { this->SetMember(&GeneralDocumentInfo::userName, &GeneralDocumentInfo::userName_valid, sz); }
 
        LIBCZI_API void SetUserName(const std::wstring& str) { this->SetUserName(str.c_str()); }
 
        LIBCZI_API void SetDescription(const wchar_t* sz) { this->SetMember(&GeneralDocumentInfo::description, &GeneralDocumentInfo::description_valid, sz); }
 
        LIBCZI_API void SetDescription(const std::wstring& str) { this->SetDescription(str.c_str()); }
 
        LIBCZI_API void SetComment(const wchar_t* sz) { this->SetMember(&GeneralDocumentInfo::comment, &GeneralDocumentInfo::comment_valid, sz); }
 
        LIBCZI_API void SetComment(const std::wstring& str) { this->SetComment(str.c_str()); }
 
        LIBCZI_API void SetKeywords(const wchar_t* sz) { this->SetMember(&GeneralDocumentInfo::keywords, &GeneralDocumentInfo::keywords_valid, sz); }
 
        LIBCZI_API void SetKeywords(const std::wstring& str) { this->SetKeywords(str.c_str()); }
 
        LIBCZI_API void SetRating(int rating) { this->rating = rating; this->rating_valid = rating >= 0 ? true : false; }
 
        LIBCZI_API void SetCreationDate(const wchar_t* sz) { this->SetMember(&GeneralDocumentInfo::creationDateTime, &GeneralDocumentInfo::creationDateTime_valid, sz); }
 
        LIBCZI_API void SetCreationDate(const std::wstring& str) { this->SetCreationDate(str.c_str()); }
 
        LIBCZI_API void SetCreationDate(const XmlDateTime* dateTime) { if (dateTime != nullptr && dateTime->IsValid()) { this->SetCreationDate(dateTime->ToXmlWstring()); } else { this->SetCreationDate(static_cast<const wchar_t*>(nullptr)); } }
 
        LIBCZI_API void Clear()
        {
            this->name_valid = this->title_valid = this->userName_valid = this->description_valid =
                this->comment_valid = this->keywords_valid = this->rating_valid = this->creationDateTime_valid = false;
        }
    private:
        void SetMember(std::wstring(GeneralDocumentInfo::* strMember), bool(GeneralDocumentInfo::* validMember), const wchar_t* str)
        {
            if (str == nullptr || *str == L'\0')
            {
                (this->*strMember).clear();
                this->*validMember = false;
            }
            else
            {
                this->*strMember = str;
                this->*validMember = true;
            }
        }
    };
 
    struct LIBCZI_API ScalingInfo
    {
        ScalingInfo() : scaleX(std::numeric_limits<double>::quiet_NaN()), scaleY(std::numeric_limits<double>::quiet_NaN()), scaleZ(std::numeric_limits<double>::quiet_NaN()) {}
        double scaleX;  
        double scaleY;  
        double scaleZ;  
 
        bool IsScaleXValid() const { return !std::isnan(this->scaleX) && !std::isinf(this->scaleX); }
 
        bool IsScaleYValid() const { return !std::isnan(this->scaleY) && !std::isinf(this->scaleY); }
 
        bool IsScaleZValid() const { return !std::isnan(this->scaleZ) && !std::isinf(this->scaleZ); }
 
        bool IsScaleValid(char d) const
        {
            switch (d)
            {
            case 'x':case'X': return this->IsScaleXValid();
            case 'y':case'Y': return this->IsScaleYValid();
            case 'z':case'Z': return this->IsScaleZValid();
            default: throw std::invalid_argument("invalid dimension");
            }
        }
 
        double GetScale(char d) const
        {
            switch (d)
            {
            case 'x':case'X': return this->scaleX;
            case 'y':case'Y': return this->scaleY;
            case 'z':case'Z': return this->scaleZ;
            default: throw std::invalid_argument("invalid dimension");
            }
        }
    };
 
    struct ScalingInfoEx : ScalingInfo
    {
        std::wstring defaultUnitFormatX;    
        std::wstring defaultUnitFormatY;    
        std::wstring defaultUnitFormatZ;    
 
        LIBCZI_API std::wstring GetDefaultUnitFormat(char d) const
        {
            switch (d)
            {
            case 'x':case'X': return this->defaultUnitFormatX;
            case 'y':case'Y': return this->defaultUnitFormatY;
            case 'z':case'Z': return this->defaultUnitFormatZ;
            default: throw std::invalid_argument("invalid dimension");
            }
        }
    };
 
    class LIBCZI_API IDimensionInfo
    {
    public:
 
        virtual DimensionIndex GetDimension() const = 0;
 
        virtual void GetInterval(int* start, int* end) const = 0;
 
        virtual void GetIntervalIsExplicitlyStated(bool* startExplicitlyStated, bool* endExplicitlyStated) const = 0;
 
        virtual ~IDimensionInfo() = default;
    };
 
    class LIBCZI_API IDimensionZInfo
    {
    public:
        enum class XyzHandedness : std::uint8_t
        {
            LeftHanded, 
            RightHanded,
            Undefined   
        };
 
        enum class ZaxisDirection : std::uint8_t
        {
            FromSpecimenToObjective,    
            FromObjectiveToSpecimen,    
            Undefined                   
        };
 
        enum class ZDriveMode : std::uint8_t
        {
            Continuous, 
            Step        
        };
 
        virtual bool TryGetReferencePosition(double* d) = 0;
 
        virtual bool TryGetIntervalDefinition(double* offset, double* increment) = 0;
 
        virtual bool TryGetPositionList(std::vector<double>* positions) = 0;
 
        virtual bool TryGetXyzHandedness(XyzHandedness* xyzHandedness) = 0;
 
        virtual bool TryGetZAxisDirection(ZaxisDirection* zAxisDirection) = 0;
 
        virtual bool TryGetZDriveMode(ZDriveMode* zdrivemode) = 0;
 
        virtual bool TryZDriveSpeed(double* zdrivespeed) = 0;
 
        virtual ~IDimensionZInfo() = default;
    };
 
    class LIBCZI_API IDimensionTInfo
    {
    public:
        virtual bool TryGetStartTime(XmlDateTime* dateTime) = 0;
 
        virtual bool TryGetIntervalDefinition(double* offset, double* increment) = 0;
 
        virtual bool TryGetOffsetsList(std::vector<double>* offsets) = 0;
 
        virtual ~IDimensionTInfo() = default;
    };
 
    class IChannelDisplaySetting;
    struct DisplaySettingsPOD;
    struct ChannelDisplaySettingsPOD;
 
    class LIBCZI_API IDisplaySettings
    {
    public:
        struct SplineControlPoint
        {
            double x;   
            double y;   
 
            SplineControlPoint(double x, double y) : x(x), y(y) {}
 
            bool operator==(const SplineControlPoint& rhs) const { return this->x == rhs.x && this->y == rhs.y; }
 
            bool operator!=(const SplineControlPoint& rhs) const { return !this->operator==(rhs); }
        };
 
        enum class GradationCurveMode : std::uint8_t
        {
            Linear,     
            Gamma,      
            Spline      
        };
 
 
        enum class TintingMode : std::uint8_t
        {
            None = 0,                   
            Color = 1,                  
            LookUpTableExplicit = 2,    
            LookUpTableWellKnown = 3    
        };
 
        struct CubicSplineCoefficients
        {
            double a; 
            double b; 
            double c; 
            double d; 
 
            double Get(int index) const
            {
                switch (index)
                {
                case 0:     return this->a;
                case 1:     return this->b;
                case 2:     return this->c;
                case 3:     return this->d;
                default:    return std::numeric_limits<double>::quiet_NaN();
                }
            }
        };
 
        struct SplineData
        {
            double xPos;
 
            CubicSplineCoefficients coefficients;
        };
 
        virtual void EnumChannels(std::function<bool(int chIndex)> func) const = 0;
 
        virtual std::shared_ptr<libCZI::IChannelDisplaySetting> GetChannelDisplaySettings(int chIndex) const = 0;
 
        virtual ~IDisplaySettings() = default;
 
        static void Clone(const IDisplaySettings* disp, DisplaySettingsPOD& pod);
    };
 
    class LIBCZI_API IChannelDisplaySetting
    {
    public:
        virtual bool    GetIsEnabled() const = 0;
 
        virtual float   GetWeight() const = 0;
 
        virtual bool    TryGetTintingColorRgb8(libCZI::Rgb8Color* pColor) const = 0;
 
        virtual void    GetBlackWhitePoint(float* pBlack, float* pWhite) const = 0;
 
        virtual IDisplaySettings::GradationCurveMode GetGradationCurveMode() const = 0;
 
        virtual bool    TryGetGamma(float* gamma) const = 0;
 
        virtual bool    TryGetSplineControlPoints(std::vector<libCZI::IDisplaySettings::SplineControlPoint>* ctrlPts) const = 0;
 
        virtual bool    TryGetSplineData(std::vector<libCZI::IDisplaySettings::SplineData>* data) const = 0;
 
        virtual ~IChannelDisplaySetting() = default;
 
        static void Clone(const IChannelDisplaySetting* disp, ChannelDisplaySettingsPOD& pod);
    };
 
    struct ChannelDisplaySettingsPOD
    {
        bool isEnabled;
 
        float weight;
 
        IDisplaySettings::TintingMode tintingMode;
 
        libCZI::Rgb8Color tintingColor;
 
        float blackPoint;
 
        float whitePoint;
 
        IDisplaySettings::GradationCurveMode  gradationCurveMode;
 
        float gamma;
 
        std::vector<libCZI::IDisplaySettings::SplineControlPoint> splineCtrlPoints;
 
        LIBCZI_API static IChannelDisplaySetting* CreateIChannelDisplaySetting(const ChannelDisplaySettingsPOD& pod);
 
        LIBCZI_API static std::shared_ptr<IChannelDisplaySetting> CreateIChannelDisplaySettingSp(const ChannelDisplaySettingsPOD& pod);
 
        LIBCZI_API void Clear()
        {
            this->isEnabled = false;
            this->tintingMode = IDisplaySettings::TintingMode::None;
            this->blackPoint = 0;
            this->whitePoint = 1;
            this->gradationCurveMode = IDisplaySettings::GradationCurveMode::Linear;
            this->weight = 1;
            this->gamma = 1;
        }
    };
 
    struct DisplaySettingsPOD
    {
        std::map<int, ChannelDisplaySettingsPOD > channelDisplaySettings;
 
        LIBCZI_API static libCZI::IDisplaySettings* CreateIDisplaySetting(const DisplaySettingsPOD& pod);
 
        LIBCZI_API static std::shared_ptr<libCZI::IDisplaySettings> CreateIDisplaySettingSp(const DisplaySettingsPOD& pod);
    };
 
    class IDimensionsChannelsInfo;
 
    class LIBCZI_API ICziMultiDimensionDocumentInfo
    {
    public:
        virtual GeneralDocumentInfo GetGeneralDocumentInfo() const = 0;
 
        virtual libCZI::ScalingInfoEx GetScalingInfoEx() const = 0;
 
        virtual libCZI::ScalingInfo GetScalingInfo() const = 0;
 
        virtual void EnumDimensions(const std::function<bool(DimensionIndex)>& enumDimensions) = 0;
 
        virtual std::shared_ptr<IDimensionInfo> GetDimensionInfo(DimensionIndex dim) = 0;
 
        virtual std::shared_ptr<IDimensionZInfo> GetDimensionZInfo() = 0;
 
        virtual std::shared_ptr<IDimensionTInfo> GetDimensionTInfo() = 0;
 
        virtual std::shared_ptr<IDimensionsChannelsInfo> GetDimensionChannelsInfo() = 0;
 
        virtual std::shared_ptr<IDisplaySettings> GetDisplaySettings() const = 0;
 
        virtual ~ICziMultiDimensionDocumentInfo() = default;
 
        std::vector<DimensionIndex> GetDimensions()
        {
            std::vector<DimensionIndex> vec;
            this->EnumDimensions([&](DimensionIndex i)->bool {vec.push_back(i); return true; });
            return vec;
        }
    };
 
    class LIBCZI_API IXmlNodeRead
    {
    public:
        virtual std::wstring Name() const = 0;
 
        virtual bool TryGetAttribute(const wchar_t* attributeName, std::wstring* attribValue) const = 0;
 
        virtual void EnumAttributes(const std::function<bool(const std::wstring& attribName, const std::wstring& attribValue)>& enumFunc) const = 0;
 
        virtual bool TryGetValue(std::wstring* value) const = 0;
 
        virtual std::shared_ptr<IXmlNodeRead> GetChildNodeReadonly(const char* path) = 0;
 
        virtual void EnumChildren(const std::function<bool(std::shared_ptr<IXmlNodeRead>)>& enumChildren) = 0;
 
        bool TryGetValueAsDouble(double* p);
 
        bool TryGetValueAsFloat(float* p);
 
        bool TryGetValueAsInt32(std::int32_t* p);
 
        bool TryGetValueAsUInt32(std::uint32_t* p);
 
        bool TryGetValueAsInt64(std::int64_t* p);
 
        bool TryGetValueAsUInt64(std::uint64_t* p);
 
        bool TryGetValueAsBool(bool* p);
 
        virtual ~IXmlNodeRead() = default;
    };
 
    class LIBCZI_API ICziMetadata : public IXmlNodeRead
    {
    public:
        virtual bool IsXmlValid() const = 0;
 
        virtual std::string GetXml() = 0;
 
        virtual std::shared_ptr<libCZI::ICziMultiDimensionDocumentInfo> GetDocumentInfo() = 0;
 
        virtual ~ICziMetadata() = default;
    };
 
    class IXmlNodeRw;
 
    class LIBCZI_API IXmlNodeWrite
    {
    public:
        virtual std::shared_ptr<IXmlNodeRw> GetOrCreateChildNode(const char* path) = 0;
 
        virtual std::shared_ptr<IXmlNodeRw> GetChildNode(const char* path) = 0;
 
        virtual std::shared_ptr<IXmlNodeRw> AppendChildNode(const char* name) = 0;
 
        virtual void SetAttribute(const char* name, const char* value) = 0;
 
        virtual void SetAttribute(const wchar_t* name, const wchar_t* value) = 0;
 
        virtual void SetValue(const char* str) = 0;
 
        virtual void SetValue(const wchar_t* str) = 0;
 
        virtual void SetValueI32(int value) = 0;
 
        virtual void SetValueUI32(unsigned int value) = 0;
 
        virtual void SetValueDbl(double value) = 0;
 
        virtual void SetValueFlt(float value) = 0;
 
        virtual void SetValueBool(bool value) = 0;
 
        virtual void SetValueI64(long long value) = 0;
 
        virtual void SetValueUI64(unsigned long long value) = 0;
 
        virtual void RemoveChildren() = 0;
 
        virtual void RemoveAttributes() = 0;
 
        virtual bool RemoveChild(const char* name) = 0;
 
        virtual bool RemoveAttribute(const char* name) = 0;
 
        virtual ~IXmlNodeWrite() = default;
 
        void SetValue(const std::string& str) { this->SetValue(str.c_str()); }
 
        void SetValue(const std::wstring& str) { this->SetValue(str.c_str()); }
 
        std::shared_ptr<IXmlNodeRw> GetOrCreateChildNode(const std::string& path) { return this->GetOrCreateChildNode(path.c_str()); }
 
        std::shared_ptr<IXmlNodeRw> GetChildNode(const std::string& path) { return this->GetChildNode(path.c_str()); }
    };
 
    class IXmlNodeRw : public IXmlNodeRead, public IXmlNodeWrite
    {
    };
 
    class ICziMetadataBuilder
    {
    public:
        virtual std::shared_ptr<IXmlNodeRw> GetRootNode() = 0;
 
        virtual std::string GetXml(bool withIndent = false) = 0;
 
        virtual ~ICziMetadataBuilder() = default;
    };
 
    struct LIBCZI_API CustomValueVariant
    {
    public:
        enum class Type
        {
            Invalid,    
            Int32,      
            Float,      
            Double,     
            Boolean,    
            String      
        };
 
        CustomValueVariant() : type(Type::Invalid)
        {
        }
 
        explicit CustomValueVariant(std::int32_t v)
        {
            this->SetInt32(v);
        }
 
        explicit CustomValueVariant(double v)
        {
            this->SetDouble(v);
        }
 
        explicit CustomValueVariant(float v)
        {
            this->SetFloat(v);
        }
 
        explicit CustomValueVariant(bool v)
        {
            this->SetBool(v);
        }
 
        explicit CustomValueVariant(const std::string& v)
        {
            this->SetString(v);
        }
 
        explicit CustomValueVariant(const char* string)
        {
            this->SetString(string);
        }
 
        void SetInt32(std::int32_t v)
        {
            this->type = Type::Int32;
            this->int32Value = v;
        }
 
        void SetDouble(double v)
        {
            this->type = Type::Double;
            this->doubleValue = v;
        }
 
        void SetFloat(float v)
        {
            this->type = Type::Float;
            this->floatValue = v;
        }
 
        void SetBool(bool v)
        {
            this->type = Type::Boolean;
            this->boolValue = v;
        }
 
        void SetString(const std::string& v)
        {
            this->type = Type::String;
            this->stringValue = v;
        }
 
        std::int32_t GetAsInt32OrThrow() const
        {
            this->ThrowIfTypeIsUnequalTo(Type::Int32);
            return this->int32Value;
        }
 
        double GetAsDoubleOrThrow() const
        {
            this->ThrowIfTypeIsUnequalTo(Type::Double);
            return this->doubleValue;
        }
 
        float GetAsFloatOrThrow() const
        {
            this->ThrowIfTypeIsUnequalTo(Type::Float);
            return this->floatValue;
        }
 
        bool GetAsBoolOrThrow() const
        {
            this->ThrowIfTypeIsUnequalTo(Type::Boolean);
            return this->boolValue;
        }
 
        std::string GetAsStringOrThrow() const
        {
            this->ThrowIfTypeIsUnequalTo(Type::String);
            return this->stringValue;
        }
 
        Type GetType() const
        {
            return this->type;
        }
 
    private:
        Type type;   
 
        union
        {
            std::int32_t int32Value;
            float floatValue;
            double doubleValue;
            bool boolValue;
        };
 
        std::string stringValue;
 
        void ThrowIfTypeIsUnequalTo(Type typeToCheck) const
        {
            if (this->type != typeToCheck)
            {
                throw std::runtime_error("Unexpected type encountered.");
            }
        }
    };
 
    class LIBCZI_API MetadataUtils
    {
    public:
        struct CoerceAdditionalInfoForChannelDisplaySettings
        {
            bool writePixelType{ false };       
            libCZI::PixelType pixelType;        
            bool writeIdAttribute{ false };     
            std::wstring idAttribute;           
            bool writeNameAttribute{ false };   
            std::wstring nameAttribute;         
        };
 
        static void WriteImageSizeInformation(libCZI::ICziMetadataBuilder* builder, int width, int height);
 
        static void WriteMIndexSizeInformation(libCZI::ICziMetadataBuilder* builder, int mSize);
 
        static void WriteDimensionSize(libCZI::ICziMetadataBuilder* builder, libCZI::DimensionIndex dim, int size);
 
        static void WriteFillWithSubBlockStatistics(libCZI::ICziMetadataBuilder* builder, const libCZI::SubBlockStatistics& statistics);
 
        static void WriteDimInfoT_Interval(libCZI::ICziMetadataBuilder* builder, const libCZI::XmlDateTime* startTime, double startOffSet, double increment);
 
        static void WriteDimInfoT_List(libCZI::ICziMetadataBuilder* builder, const libCZI::XmlDateTime* startTime, const std::function<double(int)>& funcGetOffsets);
 
        static void WriteDimInfoZ_Interval(libCZI::ICziMetadataBuilder* builder, double startPos, double startOffSet, double increment);
 
        static void WriteDimInfoZ_List(libCZI::ICziMetadataBuilder* builder, double startPos, const std::function<double(int)>& funcGetOffsets);
 
        static void WriteGeneralDocumentInfo(libCZI::ICziMetadataBuilder* builder, const libCZI::GeneralDocumentInfo& info);
 
        static void WriteScalingInfo(libCZI::ICziMetadataBuilder* builder, const libCZI::ScalingInfo& scalingInfo);
 
        static void WriteScalingInfoEx(libCZI::ICziMetadataBuilder* builder, const libCZI::ScalingInfoEx& scalingInfo);
 
        static void SetOrAddCustomKeyValuePair(libCZI::ICziMetadataBuilder* builder, const std::string& key, const libCZI::CustomValueVariant& value);
 
        static void WriteDisplaySettings(libCZI::ICziMetadataBuilder* builder, const libCZI::IDisplaySettings* display_settings, const std::map<int, PixelType>* channel_pixel_type = nullptr);
 
        static void WriteDisplaySettings(libCZI::ICziMetadataBuilder* builder, const libCZI::IDisplaySettings* display_settings, int channel_count, const std::map<int, PixelType>* channel_pixel_type = nullptr);
 
        static void WriteDisplaySettings(libCZI::ICziMetadataBuilder* builder, const libCZI::IDisplaySettings* display_settings, int channel_count, const std::function<void(int, CoerceAdditionalInfoForChannelDisplaySettings&)>& coerce_additional_info_functor);
    };
}