ImfIDManifest.h

Go to the documentation of this file.

// SPDX-License-Identifier: BSD-3-Clause
// Copyright (c) Contributors to the OpenEXR Project.

#ifndef INCLUDED_IMF_ID_MANIFEST_H
#define INCLUDED_IMF_ID_MANIFEST_H

//-----------------------------------------------------------------------------
//
//        class IDManifest, to store a table mapping ID numbers to text
//
//-----------------------------------------------------------------------------
#include "ImfForward.h"

#include <cstdint>
#include <map>
#include <set>
#include <string>
#include <vector>

OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER

class IMF_EXPORT_TYPE IDManifest
{
public:
    // indication of how long a mapping between an ID number and the text holds for
    enum IMF_EXPORT_ENUM IdLifetime
    {
        LIFETIME_FRAME, // The mapping may change every frame:
        LIFETIME_SHOT,  // The mapping is consistent for every frame of a shot
        LIFETIME_STABLE // The mapping is consistent for all time.
    };

    //
    // hashing scheme is stored as a string rather than an enum, to allow
    // proprietary schemes to be encoded with less danger of collision
    // proprietary schemes should be encoded in a reverse-URL syntax
    //

    IMF_EXPORT
    static const std::string
        UNKNOWN; // = "unknown" : default value for encoding scheme and hash scheme - should be changed
    IMF_EXPORT
    static const std::string
        NOTHASHED; // = "none" : no relationship between text and ID
    IMF_EXPORT
    static const std::string
        CUSTOMHASH; // = "custom" : text is hashed using defined scheme
    IMF_EXPORT
    static const std::string
        MURMURHASH3_32; // = "MurmurHash3_32" : MurmurHash3 32 bit is used
    IMF_EXPORT
    static const std::string
        MURMURHASH3_64; // = "MurmurHash3_64" : bottom 8 bytes of MurmarHash3_128 (64 bit architecture version) is used

    IMF_EXPORT
    static const std::string
        ID_SCHEME; // ="id" : 32 bit ID stored directly in a UINT channel
    IMF_EXPORT
    static const std::string
        ID2_SCHEME; // ="id2" : 64 bit ID stored in two channels, specified by the ChannelGroup

    IMF_EXPORT
    IDManifest ();

    friend class CompressedIDManifest;

    //
    // decompress a compressed IDManifest into IDManifest for reading
    //
    IMF_EXPORT
    IDManifest (const CompressedIDManifest&);

    //
    // construct manifest from serialized representation stored at 'data'
    //
    IMF_EXPORT
    IDManifest (const char* data, const char* end);

private:
    // internal helper function called by constructors
    IMF_HIDDEN void init (const char* data, const char* end);

public:
    //
    // Description of the information represented by a single group of channels
    //
    class IMF_EXPORT_TYPE ChannelGroupManifest
    {
    private:
        std::set<std::string>
            _channels; // group of channels this manifest represents
        std::vector<std::string>
            _components; // ordered list of components represented by this channel group
        IdLifetime _lifeTime;
        std::string
            _hashScheme; //one of above strings or custom value e.g "nz.co.wetafx.cleverhash2"
        std::string
            _encodingScheme; //string identifying scheme to encode ID numbers within the image

        typedef std::map<uint64_t, std::vector<std::string>> IDTable;
        IDTable                                              _table;

        // used for << operator to work: tracks the last item inserted into the Manifest
        IDTable::iterator _insertionIterator;
        bool
            _insertingEntry; // true if << has been called but not enough strings yet set

    public:
        IMF_EXPORT
        ChannelGroupManifest ();

        IMF_EXPORT
        const std::set<std::string>& getChannels () const;

        IMF_EXPORT
        std::set<std::string>& getChannels ();

        IMF_EXPORT
        void setChannels (const std::set<std::string>& channels);
        IMF_EXPORT
        void setChannel (const std::string& channel);

        // get list of components for this channel group
        IMF_EXPORT
        const std::vector<std::string>& getComponents () const;

        // set components: throws an exception if there are already entries in the table
        // and the component length changes
        IMF_EXPORT
        void setComponents (const std::vector<std::string>& components);

        // set name of single component: throws an exception if there are already entries in the table
        // unless there was previously one component
        IMF_EXPORT
        void setComponent (const std::string& component);

        IdLifetime getLifetime () const { return _lifeTime; }

        void setLifetime (const IdLifetime& lifeTime) { _lifeTime = lifeTime; }

        const std::string& getHashScheme () const { return _hashScheme; }
        void               setHashScheme (const std::string& hashScheme)
        {
            _hashScheme = hashScheme;
        }

        const std::string& getEncodingScheme () const
        {
            return _encodingScheme;
        }
        void setEncodingScheme (const std::string& encodingScheme)
        {
            _encodingScheme = encodingScheme;
        }

        class Iterator;      // iterator which allows modification of the text
        class ConstIterator; // iterator which does not allow modification

        IMF_EXPORT
        Iterator begin ();
        IMF_EXPORT
        ConstIterator begin () const;
        IMF_EXPORT
        Iterator end ();
        IMF_EXPORT
        ConstIterator end () const;

        // return number of entries in manifest - could be 0
        IMF_EXPORT
        size_t size () const;

        // insert a new entry - text must contain same number of items as getComponents
        IMF_EXPORT
        Iterator
        insert (uint64_t idValue, const std::vector<std::string>& text);

        // insert a new entry - getComponents must be a single entry
        IMF_EXPORT
        Iterator insert (uint64_t idValue, const std::string& text);

        // compute hash of given entry, insert into manifest, and return
        // the computed hash. Exception will be thrown if hash scheme isn't recognised
        IMF_EXPORT
        uint64_t insert (const std::vector<std::string>& text);
        IMF_EXPORT
        uint64_t insert (const std::string& text);

        IMF_EXPORT
        Iterator find (uint64_t idValue);

        IMF_EXPORT
        ConstIterator find (uint64_t idValue) const;

        IMF_EXPORT
        void erase (uint64_t idValue);

        // return reference to idName for given idValue. Adds the mapping to the vector if it doesn't exist
        IMF_EXPORT
        std::vector<std::string>& operator[] (uint64_t idValue);

        // add a new entry to the manifest as an insertion operator: <<
        // the component strings must also be inserted using <<
        // throws an exception if the previous insert operation didn't insert the correct number of string components
        IMF_EXPORT
        ChannelGroupManifest& operator<< (uint64_t idValue);

        // insert a string as the next component of a previously inserted attribute
        IMF_EXPORT
        ChannelGroupManifest& operator<< (const std::string& text);

        IMF_EXPORT
        bool operator== (const ChannelGroupManifest& other) const;

        bool operator!= (const ChannelGroupManifest& other) const
        {
            return !(*this == other);
        }

        friend class IDManifest;
    };

private:
    std::vector<ChannelGroupManifest> _manifest;

public:
    // add a new channel group definition to the table, presumably populated with mappings
    // 'table' will be copied to the internal manifest; to further modify use the return value
    IMF_EXPORT
    ChannelGroupManifest& add (const ChannelGroupManifest& table);

    //insert an empty table definition for the given channel / group of channels
    IMF_EXPORT
    ChannelGroupManifest& add (const std::set<std::string>& group);
    IMF_EXPORT
    ChannelGroupManifest& add (const std::string& channel);

    // return number of items in manifest
    IMF_EXPORT
    size_t size () const;

    // find the first manifest ChannelGroupManifest that defines the given channel
    // if channel not find, returns a value equal to size()
    IMF_EXPORT
    size_t find (const std::string& channel) const;

    IMF_EXPORT
    const ChannelGroupManifest& operator[] (size_t index) const;
    IMF_EXPORT
    ChannelGroupManifest& operator[] (size_t index);

    //
    // serialize manifest into data array. Array will be resized to the required size
    //
    IMF_EXPORT
    void serialize (std::vector<char>& data) const;

    IMF_EXPORT
    bool operator== (const IDManifest& other) const;
    IMF_EXPORT
    bool operator!= (const IDManifest& other) const;

    //
    // add entries from 'other' into this manifest if possible
    // * all ChannelGroupsManifests for different ChannelGroups
    //   will be appended.
    // * Where 'other' contains a manifest for the same
    //   ChannelGroup:
    //     * If _components differs, the entire ChannelGroupManifest is skipped
    //     * Otherwise, entries not present in 'this' will be inserted
    //     * _hashScheme, _lifeTime and _encodingScheme will be unchanged
    //
    // returns 'false' if the same ChannelGroupManifest appears in both 'other' and 'this',
    // but with different _components, _hashScheme, _lifeTime or _encodingScheme
    // or if any idValue maps to different strings in 'other' and 'this'
    //
    IMF_EXPORT
    bool merge (const IDManifest& other);

    //
    // static has generation functions
    //
    IMF_EXPORT
    static unsigned int MurmurHash32 (const std::string& idString);
    IMF_EXPORT
    static unsigned int MurmurHash32 (const std::vector<std::string>& idString);

    IMF_EXPORT
    static uint64_t MurmurHash64 (const std::string& idString);
    IMF_EXPORT
    static uint64_t MurmurHash64 (const std::vector<std::string>& idString);
};

//
// zlip compressed version of IDManifest - the IDManifestAttribute encodes this format
// This should be transparent to the user, since there is implicit casting between the two types
//
class CompressedIDManifest
{
public:
    IMF_EXPORT
    CompressedIDManifest ();
    IMF_EXPORT
    CompressedIDManifest (const CompressedIDManifest& other);

    IMF_EXPORT
    CompressedIDManifest& operator= (const CompressedIDManifest& other);

    //
    // construct a compressed version of the given manifest - to decompress it cast to an IDManifest
    //
    IMF_EXPORT
    CompressedIDManifest (const IDManifest& manifest);

    IMF_EXPORT
    ~CompressedIDManifest ();

    int            _compressedDataSize;
    size_t         _uncompressedDataSize;
    unsigned char* _data;
};

//
// Read/Write Iterator object to access individual entries within a manifest
//

class IDManifest::ChannelGroupManifest::Iterator
{
public:
    IMF_EXPORT
    Iterator ();

    IMF_EXPORT
    explicit Iterator (
        const IDManifest::ChannelGroupManifest::IDTable::iterator& i);

    friend class IDManifest::ChannelGroupManifest::ConstIterator;
    IMF_EXPORT
    Iterator& operator++ ();

    IMF_EXPORT
    uint64_t id () const;
    IMF_EXPORT
    std::vector<std::string>& text ();

private:
    std::map<uint64_t, std::vector<std::string>>::iterator _i;
};

//
// Read-only Iterator object to access individual entries within a manifest
//

class IDManifest::ChannelGroupManifest::ConstIterator
{
public:
    IMF_EXPORT
    ConstIterator ();

    // explicit cast from internal map operator (for internal use only)
    IMF_EXPORT
    explicit ConstIterator (
        const IDManifest::ChannelGroupManifest::IDTable::const_iterator& i);
    // cast from non-const to const iterator
    IMF_EXPORT
    ConstIterator (const IDManifest::ChannelGroupManifest::Iterator& other);
    IMF_EXPORT
    ConstIterator& operator++ ();

    IMF_EXPORT
    uint64_t id () const;
    IMF_EXPORT
    const std::vector<std::string>& text () const;

private:
    std::map<uint64_t, std::vector<std::string>>::const_iterator _i;

    friend bool operator== (const ConstIterator&, const ConstIterator&);
    friend bool operator!= (const ConstIterator&, const ConstIterator&);
};

//
// ChannelGroupManifest::Iterator implementation: all inline
//

inline IDManifest::ChannelGroupManifest::Iterator::Iterator ()
{}
inline IDManifest::ChannelGroupManifest::Iterator::Iterator (
    const IDManifest::ChannelGroupManifest::IDTable::iterator& i)
    : _i (i)
{}

inline uint64_t
IDManifest::ChannelGroupManifest::Iterator::id () const
{
    return _i->first;
}

inline std::vector<std::string>&
IDManifest::ChannelGroupManifest::Iterator::text ()
{
    return _i->second;
}

inline IDManifest::ChannelGroupManifest::Iterator&
IDManifest::ChannelGroupManifest::Iterator::operator++ ()
{
    ++_i;
    return *this;
}

//
// ChannelGroupManifest::ConstIterator implementation: all inline
//

inline IDManifest::ChannelGroupManifest::ConstIterator::ConstIterator ()
{}
inline IDManifest::ChannelGroupManifest::ConstIterator::ConstIterator (
    const IDManifest::ChannelGroupManifest::Iterator& other)
    : _i (other._i)
{}
inline IDManifest::ChannelGroupManifest::ConstIterator::ConstIterator (
    const IDManifest::ChannelGroupManifest::IDTable::const_iterator& i)
    : _i (i)
{}

inline uint64_t
IDManifest::ChannelGroupManifest::ConstIterator::id () const
{
    return _i->first;
}

inline const std::vector<std::string>&
IDManifest::ChannelGroupManifest::ConstIterator::text () const
{
    return _i->second;
}

inline IDManifest::ChannelGroupManifest::ConstIterator&
IDManifest::ChannelGroupManifest::ConstIterator::operator++ ()
{
    ++_i;
    return *this;
}

inline bool
operator== (
    const IDManifest::ChannelGroupManifest::ConstIterator& a,
    const IDManifest::ChannelGroupManifest::ConstIterator& b)
{
    return a._i == b._i;
}

inline bool
operator!= (
    const IDManifest::ChannelGroupManifest::ConstIterator& a,
    const IDManifest::ChannelGroupManifest::ConstIterator& b)
{
    return a._i != b._i;
}

OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_EXIT
#endif