IMG_Metadata.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        IMG_Metadata.h (IMG Library, C++)
 *
 * COMMENTS:
 */

#ifndef __IMG_Metadata__
#define __IMG_Metadata__

#include "IMG_API.h"
#include <UT/UT_JSONValue.h>
#include <initializer_list>

class UT_Options;
class UT_OptionEntry;

struct IMG_API IMG_MetadataItem
{
    enum class Scope
    {
        MD_Read = 0x01,
        MD_Write = 0x02,
        MD_RGBA = 0x04, // Only RGBA images (no AOVs)

        MD_ReadWrite = MD_Read|MD_Write,
        MD_ReadRGBA = MD_Read|MD_RGBA,

        MD_Default = MD_Write
    };
    /// @{
    /// Map enum to text string
    static const char   *scope(Scope s);
    static Scope         scope(const char *s);
    static bool          isWriteOnly(Scope s)
    {
        return (uint(s) & uint(Scope::MD_Read)) == 0;
    }
    static bool          isReadOnly(Scope s)
    {
        return s == Scope::MD_Read || s == Scope::MD_ReadRGBA;
    }
    /// @}
    enum class Storage
    {
        MD_Unknown = -1,
        MD_Bool,
        MD_Int8,
        MD_Int16,
        MD_Int32,
        MD_Int64,
        MD_UInt8,
        MD_UInt16,
        MD_UInt32,
        MD_UInt64,
        MD_Real16,
        MD_Real32,
        MD_Real64,
        MD_String,
    };
    constexpr static bool isInteger(Storage s)
    {
        return s == Storage::MD_Bool
            || s == Storage::MD_Int8
            || s == Storage::MD_Int16
            || s == Storage::MD_Int32
            || s == Storage::MD_Int64
            || s == Storage::MD_UInt8
            || s == Storage::MD_UInt16
            || s == Storage::MD_UInt32
            || s == Storage::MD_UInt64;
    }
    constexpr static bool isFloat(Storage s)
    {
        return s == Storage::MD_Real16
            || s == Storage::MD_Real32
            || s == Storage::MD_Real64;
    }
    constexpr static bool isString(Storage s)
    {
        return s == Storage::MD_String;
    }
    /// @{
    /// Map enum to text string
    static const char   *storage(Storage s);
    static Storage       storage(const char *s);
    /// @}

    enum class TypeInfo
    {
        MD_None,
        MD_Color,
        MD_Point,
        MD_Vector,
        MD_Normal,
        MD_Quaternion,
        MD_Matrix,
        MD_Box,

        // Some weird ones
        MD_Memory,         // int representing memory
        MD_Time,           // float representing time (in seconds)
        MD_Timecode,       // two int32 for 4-byte encoding of SMPTE time code
        MD_Rational,       // two int32 for numerator/denominator
        MD_Keycode,        // int[7] for the 28 byte encoding of SMPTE keycode
    };
    /// @{
    /// Map enum to text string
    static const char   *typeInfo(TypeInfo t);
    static TypeInfo      typeInfo(const char *t);
    /// @}

    IMG_MetadataItem() = default;
    IMG_MetadataItem(const UT_JSONValue &value,
            Storage store = Storage::MD_Unknown,
            TypeInfo type = TypeInfo::MD_None)
    {
        myValue = value;
        myStorage = store;
        myTypeInfo = type;
    }
    IMG_MetadataItem(const UT_OptionEntry &value,
            Storage store = Storage::MD_Unknown,
            TypeInfo type = TypeInfo::MD_None);

    /// Encode into a UT_JSONValue as a dict
    UT_JSONValue    encode() const;
    /// Decode from a UT_JSONValue dictionary
    bool            decode(const UT_JSONValue &dict);

    /// Set value from an encoded "typed" string (see IMG_Metadata for more info)
    /// The @c new_key will be the key name stripped of the type information
    void        setFromTypedString(const UT_StringHolder &typed_key,
                            const char *value,
                            UT_StringHolder &new_key);

    /// Check to see whether a string is a "typed" string.
    static bool isTypedString(const UT_StringRef &old_key);

    /// @{
    /// Set UI elements
    void    setLabel(const UT_StringHolder &label);
    void    setMenu(const UT_StringArray &tokens,
                    const UT_StringArray &labels,
                    bool strict);
    void    setRange(fpreal64 min, bool strict_min,
                    fpreal64 max, bool strict_max);
    void    setScope(Scope scope);
    /// @}

    /// @{
    /// Query UI elements - returns true of the UI element is defined
    bool    getLabel(UT_StringHolder &label) const;
    bool    hasMenu() const;
    bool    getMenu(UT_StringArray &tokens,
                    UT_StringArray &labels,
                    bool &strict) const;
    bool    hasRange() const;
    bool    getRange(fpreal64 &min, bool &strict_min,
                    fpreal64 &max, bool &strict_max) const;
    Scope   getScope() const;

    int                 menuSize() const;
    int                 menuIndex(const UT_StringRef &token) const;
    UT_StringHolder     menuToken(int index) const;
    UT_StringHolder     menuLabel(int index) const;
    UT_StringHolder     menuLabel(const UT_StringRef &token) const;
    /// @}

    /// Convert metadata to a string value.  When @c pretty_print is @c true:
    /// - If there's a menu, the corresponding label will be returned
    /// - If there's type information, it will be used (i.e. printing a time or
    ///   memory)
    UT_StringHolder     toString(bool pretty_print) const;

    void        clear()
    {
        myValue.setNull();
        myUI.setNull();
        myStorage = Storage::MD_Unknown;
        myTypeInfo = TypeInfo::MD_None;
    }

    /// Get the JSON value type.  This uses the storage type first, but then
    /// will fall back to the type of myValue.
    UT_JSONValue::Type  jsonType() const;

    bool        intStorage() const { return isInteger(myStorage); }
    bool        floatStorage() const { return isFloat(myStorage); }
    bool        stringStorage() const { return isString(myStorage); }

    /// Save the value to a JSON writer
    bool        save(UT_JSONWriter &os) const;

    /// Debug print
    void        dump() const;

    UT_JSONValue        myValue; // Value of the data
    UT_JSONValue        myUI; // Dictionary of UI hints
    Storage             myStorage; // Hin
    TypeInfo            myTypeInfo;
private:
    void    setUI(const UT_StringHolder &key, const UT_JSONValue &value);
    const UT_JSONValue  *getUI(const UT_StringRef &key) const;
};

static bool
operator&(IMG_MetadataItem::Scope a, IMG_MetadataItem::Scope b)
{
    return int(a) & int(b);
}

/// Map of metadata items
class IMG_API IMG_Metadata
{
public:
    using Storage = IMG_MetadataItem::Storage;
    using TypeInfo = IMG_MetadataItem::TypeInfo;

    /// Clear the table
    void        clear() { myTable.clear(); }

    /// Merge from other metadata.  If @c overwrite is enabled, any data in the
    /// source will overwrite existing keys.
    void        merge(const IMG_Metadata &src, bool overwrite = true);

    /// Add named metadata.
    /// @note this will overwrite existing keys
    bool        add(const UT_StringHolder &key, const IMG_MetadataItem &item);

    /// Set value from old-style metadata.  This mimics the interface before
    /// H20 (see @c IMG_File::setOption).  Normally when calling @c
    /// IMG_File::setOption, the value would be passed directly as a string.
    /// For example: @code
    ///         fp->setOption("artist", "Van Gough");
    ///         fp->setOption("compression", "75");
    ///         fp->setOption("worldToCamera", "[1,0,0,0,0,1,0,0,...]");
    /// @endcode
    /// But, alternatively, the string could be encoded with type information.
    /// For example: @code
    ///         fp->setOption("string artist", "Van Gough");
    ///         fp->setOption("int32 compression", "75");
    ///         fp->setOption("matrix4d worldToCamera", "[1,0,0...");
    /// @endcode
    /// The possible encoding type information was:
    ///  - bool         Bool
    ///  - int8         Int8
    ///  - int16        Int16
    ///  - int32        Int32
    ///  - int64        Int64
    ///  - vec2i        Int32[2] (no type info)
    ///  - vec3i        Int32[3] (no type info)
    ///  - vec4i        Int32[4] (no type info)
    ///  - uint8        UInt8
    ///  - uint16       UInt16
    ///  - uint32       UInt32
    ///  - uint64       UInt64
    ///  - vec2i        UInt32[2] (no type info)
    ///  - vec3i        UInt32[3] (no type info)
    ///  - vec4i        UInt32[4] (no type info)
    ///  - half         Real16
    ///  - vec2h        Real16[2] (no type info)
    ///  - vec3h        Real16[3] (no type info)
    ///  - vec4h        Real16[4] (no type info)
    ///  - float        Real32
    ///  - vec2f        Real32[2] (no type info)
    ///  - vec3f        Real32[3] (no type info)
    ///  - vec4f        Real32[4] (no type info)
    ///  - mat3f        <MATRIX> Real32[9]
    ///  - mat4f        <MATRIX> Real32[16]
    ///  - matrix3f     <MATRIX> Real32[9]
    ///  - matrix4f     <MATRIX> Real32[16]
    ///  - double       Real64
    ///  - vec2d        Real64[2]
    ///  - vec3d        Real64[3]
    ///  - vec4d        Real64[4]
    ///  - mat3d        <MATRIX> Real64[9]
    ///  - mat4d        <MATRIX> Real64[16]
    ///  - matrix3d     <MATRIX> Real64[9]
    ///  - matrix4d     <MATRIX> Real64[16]
    ///  - string       String
    ///  - clr3u8       <Color> UInt8[3]
    ///  - clr4u8       <Color> UInt8[4]
    ///  - clr3f        <Color> Real32[3]
    ///  - clr4f        <Color> Real32[4]
    ///  - clr3d        <Color> Real64[3]
    ///  - clr4d        <Color> Real64[4]
    ///  - point3f      <Point> Real32[3]
    ///  - point3d      <Point> Real64[3]
    ///  - normal3f     <Normal> Real32[3]
    ///  - normal3d     <Normal> Real64[3]
    ///  - vector3f     <Vector> Real32[3]
    ///  - vector3d     <Vector> Real64[3]
    ///  - timecode     <Timecode> Int32[2]
    ///  - keycode      <Keycode> Int32[7]
    ///  - rational     <Rational> Int32[2]
    ///  - box2i        <Box> Int32[4]
    ///  - box2f        <Box> Real32[4]
    ///  - box3i        <Box> Int32[6]
    ///  - box3f        <Box> Real32[6]
    ///  - memory       <Memory> Int64
    ///  - time         <Time> Real64
    ///  - seconds      <Time> Real64
    ///
    /// If there is no type information encoded in the string, the string will
    /// be added verbatim.
    bool        addTypedString(const UT_StringHolder &name, const char *val);

    /// Find an item in the map and return it's representation
    bool        find(const UT_StringRef &name,
                            IMG_MetadataItem &value,
                            const char *format_prefix = nullptr) const;

    /// Test if a key exists in the metadata
    bool        contains(const UT_StringRef &key) const
                    { return myTable.contains(key); }

    /// Old style getOption() call that gets the value as a string
    bool        getOption(const UT_StringRef &name,
                            UT_StringHolder &val,
                            const char *prefix = nullptr) const;

    /// Remove metadata
    void        erase(const UT_StringRef &name) { myTable.erase(name); }

    /// Number of items
    exint       size() const { return myTable.size(); }

    /// @{
    /// Iteration interface
    using       const_iterator = UT_StringMap<IMG_MetadataItem>::const_iterator;
    const_iterator      begin() const { return myTable.begin(); }
    const_iterator      end() const { return myTable.end(); }
    /// @}

    /// @{
    /// Import items
    bool        import(const UT_StringRef &name, bool &value,
                            const char *format = nullptr) const;
    bool        import(const UT_StringRef &n, UT_StringHolder &v,
                            const char *format = nullptr) const;
    bool        import(const UT_StringRef &name, int32 &val,
                            const char *format = nullptr) const;
    bool        import(const UT_StringRef &name, int64 &val,
                            const char *format = nullptr) const;
    bool        import(const UT_StringRef &name, fpreal32 &val,
                            const char *format = nullptr) const;
    bool        import(const UT_StringRef &name, fpreal64 &val,
                            const char *format = nullptr) const;
    bool        import(const UT_StringRef &name, UT_Matrix4F &m,
                            const char *format = nullptr) const;
    bool        import(const UT_StringRef &name, UT_Matrix4D &m,
                            const char *format = nullptr) const;
    /// @}

    /// Convert metadata to a string value.  When @c pretty_print is @c true:
    /// - If there's a menu, the corresponding label will be returned
    /// - If there's type information, it will be used (i.e. printing a time or
    ///   memory)
    bool        toString(const UT_StringRef &name,
                        UT_StringHolder &value,
                        const char *format = nullptr,
                        bool pretty_print = true) const;

    /// Save the value to a JSON writer
    bool        save(UT_JSONWriter &os) const;

    /// @{
    /// Save encoded data to a JSON writer
    UT_StringHolder     saveEncoded() const;
    bool                saveEncoded(UT_JSONWriter &os) const;
    /// @}
    /// Load from an encoded JSON object
    bool        loadEncoded(const UT_JSONValue &jvalue);

    /// Debug print
    void        dump() const;

    /// Fill a UT_Options the best we can.  IMG_Metadata is much more
    /// expressive and flexible than a UT_Options, but this method does the
    /// best.  The method exists for older interfaces which expect a
    /// UT_Options.
    ///
    /// If a piece of metadata isn't representable in a UT_Options, the string
    /// representation of the value will be saved.
    void        fill(UT_Options &opts) const;

private:
    UT_StringMap<IMG_MetadataItem>      myTable;
};

/// A list of well-known metdata that a format understands.  The list is ordered.
class IMG_API IMG_MetadataOptions
{
public:
    using Scope = IMG_MetadataItem::Scope;
    using Storage = IMG_MetadataItem::Storage;
    using TypeInfo = IMG_MetadataItem::TypeInfo;

    using MenuCreator = UT_Array<std::pair<const char *, const char *>>;
    struct IMG_API Item
    {
        Item() = default;
        Item(const UT_StringHolder &name,
            const IMG_MetadataItem &item)
            : myName(name)
            , myItem(item)
        {
        }
        /// Construct with storage/type info, but no UI
        Item(const UT_StringHolder &name,
                const UT_StringHolder &label,
                const UT_JSONValue &value,
                Storage storage,
                TypeInfo typeInfo);
        /// Full constructor with UI elements and type information
        Item(const UT_StringHolder &name,
                const UT_StringHolder &label,
                const UT_JSONValue &value,
                const MenuCreator &menu = MenuCreator(),
                fpreal64 range_min =  1,
                fpreal64 range_max = -1,
                Scope scope = Scope::MD_Default,
                Storage storage = Storage::MD_Unknown,
                TypeInfo typeInfo = TypeInfo::MD_None);

        UT_StringHolder         myName;
        IMG_MetadataItem        myItem;
    };
    explicit IMG_MetadataOptions() = default;
    explicit IMG_MetadataOptions(std::initializer_list<Item> init)
        : myList(init)
    {
    }

    void        append(const Item &item) { myList.append(item); }
    void        append(const UT_StringHolder &name,
                        const IMG_MetadataItem &item)
    {
        myList.append(Item(name, item));
    }

    /// @{
    /// Lookup item
    exint        size() const { return myList.size(); }
    int          index(const UT_StringRef &name) const;
    Item        &get(int idx) { return myList[idx]; }
    const Item  &get(int idx) const { return myList[idx]; }
    Item        &operator[](int idx) { return myList[idx]; }
    const Item  &operator[](int idx) const { return myList[idx]; }
    Item        &get(const UT_StringRef &name) { return myList[index(name)]; }
    const Item  &get(const UT_StringRef &name) const { return myList[index(name)]; }
    Item        &operator[](const UT_StringRef &name) { return myList[index(name)]; }
    const Item  &operator[](const UT_StringRef &name) const { return myList[index(name)]; }
    /// @}

    /// @{
    /// Find the corresponding menu index for the value of a given parameter
    int         menuIndex(int parm_index,
                        const UT_StringRef &menu_token) const;
    int         menuIndex(const UT_StringRef &parm_name,
                        const UT_StringRef &menu_token) const
                { return menuIndex(index(parm_name), menu_token); }
    /// @}
    /// @{
    /// Get the token/label from the menu of a given parameter
    UT_StringHolder menuToken(int parm_index, int menu_index) const;
    UT_StringHolder menuToken(const UT_StringRef &name, int idx) const
                                { return menuToken(index(name), idx); }
    UT_StringHolder menuLabel(int parm_index, int menu_index) const;
    UT_StringHolder menuLabel(const UT_StringRef &name, int idx) const
                    { return menuLabel(index(name), idx); }
    /// @}

    /// @{
    /// Iteration interface
    using               const_iterator = UT_Array<Item>::const_iterator;
    const_iterator      begin() const { return myList.begin(); }
    const_iterator      end() const { return myList.end(); }
    /// @}

    /// Debug printing
    void        dump() const;
    bool        save(UT_JSONWriter &w) const;

private:
    UT_Array<Item>          myList;
};

#endif