HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
IMG_Metadata.h
Go to the documentation of this file.
1 /*
2  * PROPRIETARY INFORMATION. This software is proprietary to
3  * Side Effects Software Inc., and is not to be reproduced,
4  * transmitted, or disclosed in any way without written permission.
5  *
6  * NAME: IMG_Metadata.h (IMG Library, C++)
7  *
8  * COMMENTS:
9  */
10 
11 #ifndef __IMG_Metadata__
12 #define __IMG_Metadata__
13 
14 #include "IMG_API.h"
15 #include <UT/UT_JSONValue.h>
16 #include <initializer_list>
17 
19 {
20  enum class Scope
21  {
22  MD_Read = 0x01,
23  MD_Write = 0x02,
24  MD_RGBA = 0x04, // Only RGBA images (no AOVs)
25 
26  MD_ReadWrite = MD_Read|MD_Write,
27  MD_ReadRGBA = MD_Read|MD_RGBA,
28 
29  MD_Default = MD_Write
30  };
31  /// @{
32  /// Map enum to text string
33  static const char *scope(Scope s);
34  static Scope scope(const char *s);
35  static bool isWriteOnly(Scope s)
36  {
37  return (uint(s) & uint(Scope::MD_Read)) == 0;
38  }
39  static bool isReadOnly(Scope s)
40  {
41  return s == Scope::MD_Read || s == Scope::MD_ReadRGBA;
42  }
43  /// @}
44  enum class Storage
45  {
46  MD_Unknown = -1,
47  MD_Bool,
48  MD_Int8,
49  MD_Int16,
50  MD_Int32,
51  MD_Int64,
52  MD_UInt8,
53  MD_UInt16,
54  MD_UInt32,
55  MD_UInt64,
56  MD_Real16,
57  MD_Real32,
58  MD_Real64,
59  MD_String,
60  };
61  constexpr static bool isInteger(Storage s)
62  {
63  return s == Storage::MD_Bool
64  || s == Storage::MD_Int8
65  || s == Storage::MD_Int16
66  || s == Storage::MD_Int32
67  || s == Storage::MD_Int64
68  || s == Storage::MD_UInt8
69  || s == Storage::MD_UInt16
70  || s == Storage::MD_UInt32
71  || s == Storage::MD_UInt64;
72  }
73  constexpr static bool isFloat(Storage s)
74  {
75  return s == Storage::MD_Real16
76  || s == Storage::MD_Real32
77  || s == Storage::MD_Real64;
78  }
79  constexpr static bool isString(Storage s)
80  {
81  return s == Storage::MD_String;
82  }
83  /// @{
84  /// Map enum to text string
85  static const char *storage(Storage s);
86  static Storage storage(const char *s);
87  /// @}
88 
89  enum class TypeInfo
90  {
91  MD_None,
92  MD_Color,
93  MD_Point,
94  MD_Vector,
95  MD_Normal,
96  MD_Quaternion,
97  MD_Matrix,
98  MD_Box,
99 
100  // Some weird ones
101  MD_Memory, // int representing memory
102  MD_Time, // float representing time (in seconds)
103  MD_Timecode, // two int32 for 4-byte encoding of SMPTE time code
104  MD_Rational, // two int32 for numerator/denominator
105  MD_Keycode, // int[7] for the 28 byte encoding of SMPTE keycode
106  };
107  /// @{
108  /// Map enum to text string
109  static const char *typeInfo(TypeInfo t);
110  static TypeInfo typeInfo(const char *t);
111  /// @}
112 
113  IMG_MetadataItem() = default;
115  Storage store = Storage::MD_Unknown,
116  TypeInfo type = TypeInfo::MD_None)
117  {
118  myValue = value;
119  myStorage = store;
120  myTypeInfo = type;
121  }
122 
123  /// Encode into a UT_JSONValue as a dict
124  UT_JSONValue encode() const;
125  /// Decode from a UT_JSONValue dictionary
126  bool decode(const UT_JSONValue &dict);
127 
128  /// Set value from an encoded "typed" string (see IMG_Metadata for more info)
129  /// The @c new_key will be the key name stripped of the type information
130  void setFromTypedString(const UT_StringHolder &typed_key,
131  const char *value,
132  UT_StringHolder &new_key);
133 
134  /// @{
135  /// Set UI elements
136  void setLabel(const UT_StringHolder &label);
137  void setMenu(const UT_StringArray &tokens,
138  const UT_StringArray &labels,
139  bool strict);
140  void setRange(fpreal64 min, bool strict_min,
141  fpreal64 max, bool strict_max);
142  void setScope(Scope scope);
143  /// @}
144 
145  /// @{
146  /// Query UI elements - returns true of the UI element is defined
147  bool getLabel(UT_StringHolder &label) const;
148  bool hasMenu() const;
149  bool getMenu(UT_StringArray &tokens,
150  UT_StringArray &labels,
151  bool &strict) const;
152  bool hasRange() const;
153  bool getRange(fpreal64 &min, bool &strict_min,
154  fpreal64 &max, bool &strict_max) const;
155  Scope getScope() const;
156 
157  int menuSize() const;
158  int menuIndex(const UT_StringRef &token) const;
159  UT_StringHolder menuToken(int index) const;
160  UT_StringHolder menuLabel(int index) const;
161  UT_StringHolder menuLabel(const UT_StringRef &token) const;
162  /// @}
163 
164  /// Convert metadata to a string value. When @c pretty_print is @c true:
165  /// - If there's a menu, the corresponding label will be returned
166  /// - If there's type information, it will be used (i.e. printing a time or
167  /// memory)
168  UT_StringHolder toString(bool pretty_print) const;
169 
170  void clear()
171  {
172  myValue.setNull();
173  myUI.setNull();
174  myStorage = Storage::MD_Unknown;
175  myTypeInfo = TypeInfo::MD_None;
176  }
177 
178  /// Get the JSON value type. This uses the storage type first, but then
179  /// will fall back to the type of myValue.
180  UT_JSONValue::Type jsonType() const;
181 
182  bool intStorage() const { return isInteger(myStorage); }
183  bool floatStorage() const { return isFloat(myStorage); }
184  bool stringStorage() const { return isString(myStorage); }
185 
186  /// Save the value to a JSON writer
187  bool save(UT_JSONWriter &os) const;
188 
189  /// Debug print
190  void dump() const;
191 
192  UT_JSONValue myValue; // Value of the data
193  UT_JSONValue myUI; // Dictionary of UI hints
196 private:
197  void setUI(const UT_StringHolder &key, const UT_JSONValue &value);
198  const UT_JSONValue *getUI(const UT_StringRef &key) const;
199 };
200 
201 static bool
203 {
204  return int(a) & int(b);
205 }
206 
207 /// Map of metadata items
209 {
210 public:
213 
214  /// Clear the table
215  void clear() { myTable.clear(); }
216 
217  /// Merge from other metadata. If @c overwrite is enabled, any data in the
218  /// source will overwrite existing keys.
219  void merge(const IMG_Metadata &src, bool overwrite = true);
220 
221  /// Add named metadata.
222  /// @note this will overwrite existing keys
223  bool add(const UT_StringHolder &key, const IMG_MetadataItem &item);
224 
225  /// Set value from old-style metadata. This mimics the interface before
226  /// H20 (see @c IMG_File::setOption). Normally when calling @c
227  /// IMG_File::setOption, the value would be passed directly as a string.
228  /// For example: @code
229  /// fp->setOption("artist", "Van Gough");
230  /// fp->setOption("compression", "75");
231  /// fp->setOption("worldToCamera", "[1,0,0,0,0,1,0,0,...]");
232  /// @endcode
233  /// But, alternatively, the string could be encoded with type information.
234  /// For example: @code
235  /// fp->setOption("string artist", "Van Gough");
236  /// fp->setOption("int32 compression", "75");
237  /// fp->setOption("matrix4d worldToCamera", "[1,0,0...");
238  /// @endcode
239  /// The possible encoding type information was:
240  /// - bool Bool
241  /// - int8 Int8
242  /// - int16 Int16
243  /// - int32 Int32
244  /// - int64 Int64
245  /// - vec2i Int32[2] (no type info)
246  /// - vec3i Int32[3] (no type info)
247  /// - vec4i Int32[4] (no type info)
248  /// - uint8 UInt8
249  /// - uint16 UInt16
250  /// - uint32 UInt32
251  /// - uint64 UInt64
252  /// - vec2i UInt32[2] (no type info)
253  /// - vec3i UInt32[3] (no type info)
254  /// - vec4i UInt32[4] (no type info)
255  /// - half Real16
256  /// - vec2h Real16[2] (no type info)
257  /// - vec3h Real16[3] (no type info)
258  /// - vec4h Real16[4] (no type info)
259  /// - float Real32
260  /// - vec2f Real32[2] (no type info)
261  /// - vec3f Real32[3] (no type info)
262  /// - vec4f Real32[4] (no type info)
263  /// - mat3f <MATRIX> Real32[9]
264  /// - mat4f <MATRIX> Real32[16]
265  /// - matrix3f <MATRIX> Real32[9]
266  /// - matrix4f <MATRIX> Real32[16]
267  /// - double Real64
268  /// - vec2d Real64[2]
269  /// - vec3d Real64[3]
270  /// - vec4d Real64[4]
271  /// - mat3d <MATRIX> Real64[9]
272  /// - mat4d <MATRIX> Real64[16]
273  /// - matrix3d <MATRIX> Real64[9]
274  /// - matrix4d <MATRIX> Real64[16]
275  /// - string String
276  /// - clr3u8 <Color> UInt8[3]
277  /// - clr4u8 <Color> UInt8[4]
278  /// - clr3f <Color> Real32[3]
279  /// - clr4f <Color> Real32[4]
280  /// - clr3d <Color> Real64[3]
281  /// - clr4d <Color> Real64[4]
282  /// - point3f <Point> Real32[3]
283  /// - point3d <Point> Real64[3]
284  /// - normal3f <Normal> Real32[3]
285  /// - normal3d <Normal> Real64[3]
286  /// - vector3f <Vector> Real32[3]
287  /// - vector3d <Vector> Real64[3]
288  /// - timecode <Timecode> Int32[2]
289  /// - keycode <Keycode> Int32[7]
290  /// - rational <Rational> Int32[2]
291  /// - box2i <Box> Int32[4]
292  /// - box2f <Box> Real32[4]
293  /// - box3i <Box> Int32[6]
294  /// - box3f <Box> Real32[6]
295  /// - memory <Memory> Int64
296  /// - time <Time> Real64
297  /// - seconds <Time> Real64
298  ///
299  /// If there is no type information encoded in the string, the string will
300  /// be added verbatim.
301  bool addTypedString(const UT_StringHolder &name, const char *val);
302 
303  /// Find an item in the map and return it's representation
304  bool find(const UT_StringRef &name,
306  const char *format_prefix = nullptr) const;
307 
308  /// Test if a key exists in the metadata
309  bool contains(const UT_StringRef &key) const
310  { return myTable.contains(key); }
311 
312  /// Old style getOption() call that gets the value as a string
313  bool getOption(const UT_StringRef &name,
315  const char *prefix = nullptr) const;
316 
317  /// Remove metadata
318  void erase(const UT_StringRef &name) { myTable.erase(name); }
319 
320  /// Number of items
321  exint size() const { return myTable.size(); }
322 
323  /// @{
324  /// Iteration interface
326  const_iterator begin() const { return myTable.begin(); }
327  const_iterator end() const { return myTable.end(); }
328  /// @}
329 
330  /// @{
331  /// Import items
332  bool import(const UT_StringRef &name, bool &value,
333  const char *format = nullptr) const;
334  bool import(const UT_StringRef &n, UT_StringHolder &v,
335  const char *format = nullptr) const;
336  bool import(const UT_StringRef &name, int32 &val,
337  const char *format = nullptr) const;
338  bool import(const UT_StringRef &name, int64 &val,
339  const char *format = nullptr) const;
340  bool import(const UT_StringRef &name, fpreal32 &val,
341  const char *format = nullptr) const;
342  bool import(const UT_StringRef &name, fpreal64 &val,
343  const char *format = nullptr) const;
344  bool import(const UT_StringRef &name, UT_Matrix4F &m,
345  const char *format = nullptr) const;
346  bool import(const UT_StringRef &name, UT_Matrix4D &m,
347  const char *format = nullptr) const;
348  /// @}
349 
350  /// Convert metadata to a string value. When @c pretty_print is @c true:
351  /// - If there's a menu, the corresponding label will be returned
352  /// - If there's type information, it will be used (i.e. printing a time or
353  /// memory)
354  bool toString(const UT_StringRef &name,
356  const char *format = nullptr,
357  bool pretty_print = true) const;
358 
359  /// Save the value to a JSON writer
360  bool save(UT_JSONWriter &os) const;
361 
362  /// Debug print
363  void dump() const;
364 
365 private:
367 };
368 
369 /// A list of well-known metdata that a format understands. The list is ordered.
371 {
372 public:
376 
378  struct IMG_API Item
379  {
380  Item() = default;
382  const IMG_MetadataItem &item)
383  : myName(name)
384  , myItem(item)
385  {
386  }
387  /// Construct with storage/type info, but no UI
388  Item(const UT_StringHolder &name,
389  const UT_StringHolder &label,
390  const UT_JSONValue &value,
392  TypeInfo typeInfo);
393  /// Full constructor with UI elements and type information
394  Item(const UT_StringHolder &name,
395  const UT_StringHolder &label,
396  const UT_JSONValue &value,
397  const MenuCreator &menu = MenuCreator(),
398  fpreal64 range_min = 1,
399  fpreal64 range_max = -1,
400  Scope scope = Scope::MD_Default,
401  Storage storage = Storage::MD_Unknown,
402  TypeInfo typeInfo = TypeInfo::MD_None);
403 
406  };
407  explicit IMG_MetadataOptions() = default;
408  explicit IMG_MetadataOptions(std::initializer_list<Item> init)
409  : myList(init)
410  {
411  }
412 
413  void append(const Item &item) { myList.append(item); }
415  const IMG_MetadataItem &item)
416  {
417  myList.append(Item(name, item));
418  }
419 
420  /// @{
421  /// Lookup item
422  exint size() const { return myList.size(); }
423  int index(const UT_StringRef &name) const;
424  Item &get(int idx) { return myList[idx]; }
425  const Item &get(int idx) const { return myList[idx]; }
426  Item &operator[](int idx) { return myList[idx]; }
427  const Item &operator[](int idx) const { return myList[idx]; }
428  Item &get(const UT_StringRef &name) { return myList[index(name)]; }
429  const Item &get(const UT_StringRef &name) const { return myList[index(name)]; }
430  Item &operator[](const UT_StringRef &name) { return myList[index(name)]; }
431  const Item &operator[](const UT_StringRef &name) const { return myList[index(name)]; }
432  /// @}
433 
434  /// @{
435  /// Find the corresponding menu index for the value of a given parameter
436  int menuIndex(int parm_index,
437  const UT_StringRef &menu_token) const;
438  int menuIndex(const UT_StringRef &parm_name,
439  const UT_StringRef &menu_token) const
440  { return menuIndex(index(parm_name), menu_token); }
441  /// @}
442  /// @{
443  /// Get the token/label from the menu of a given parameter
444  UT_StringHolder menuToken(int parm_index, int menu_index) const;
446  { return menuToken(index(name), idx); }
447  UT_StringHolder menuLabel(int parm_index, int menu_index) const;
449  { return menuLabel(index(name), idx); }
450  /// @}
451 
452  /// @{
453  /// Iteration interface
455  const_iterator begin() const { return myList.begin(); }
456  const_iterator end() const { return myList.end(); }
457  /// @}
458 
459  /// Debug printing
460  void dump() const;
461  bool save(UT_JSONWriter &w) const;
462 
463 private:
464  UT_Array<Item> myList;
465 };
466 
467 #endif
bool isString(const AttributeArray &array)
typedef int(APIENTRYP RE_PFNGLXSWAPINTERVALSGIPROC)(int)
void append(const UT_StringHolder &name, const IMG_MetadataItem &item)
Definition: IMG_Metadata.h:414
int int32
Definition: SYS_Types.h:39
GLuint GLsizei const GLchar * label
Definition: glcorearb.h:2545
static bool isWriteOnly(Scope s)
Definition: IMG_Metadata.h:35
Storage
Definition: oidn.hpp:136
getFileOption("OpenEXR:storage") storage
Definition: HDK_Image.dox:276
const GLdouble * v
Definition: glcorearb.h:837
Item & operator[](int idx)
Definition: IMG_Metadata.h:426
GLsizei const GLfloat * value
Definition: glcorearb.h:824
UT_JSONValue myUI
Definition: IMG_Metadata.h:193
static constexpr bool isString(Storage s)
Definition: IMG_Metadata.h:79
int64 exint
Definition: SYS_Types.h:125
GLboolean GLboolean GLboolean GLboolean a
Definition: glcorearb.h:1222
GLdouble s
Definition: glad.h:3009
ImageBuf OIIO_API min(Image_or_Const A, Image_or_Const B, ROI roi={}, int nthreads=0)
Class which writes ASCII or binary JSON streams.
Definition: UT_JSONWriter.h:37
void clear()
Clear the table.
Definition: IMG_Metadata.h:215
TypeInfo myTypeInfo
Definition: IMG_Metadata.h:195
const_iterator begin() const
Definition: IMG_Metadata.h:455
float fpreal32
Definition: SYS_Types.h:200
const_iterator end() const
Definition: IMG_Metadata.h:327
int menuIndex(const UT_StringRef &parm_name, const UT_StringRef &menu_token) const
Definition: IMG_Metadata.h:438
static constexpr bool isFloat(Storage s)
Definition: IMG_Metadata.h:73
bool stringStorage() const
Definition: IMG_Metadata.h:184
double fpreal64
Definition: SYS_Types.h:201
#define IMG_API
Definition: IMG_API.h:10
UT_StringMap< IMG_MetadataItem >::const_iterator const_iterator
Definition: IMG_Metadata.h:325
GLdouble n
Definition: glcorearb.h:2008
const_iterator end() const
Definition: IMG_Metadata.h:456
const_iterator begin() const
Definition: IMG_Metadata.h:326
void erase(const UT_StringRef &name)
Remove metadata.
Definition: IMG_Metadata.h:318
exint size() const
Number of items.
Definition: IMG_Metadata.h:321
static constexpr bool isInteger(Storage s)
Definition: IMG_Metadata.h:61
bool floatStorage() const
Definition: IMG_Metadata.h:183
bool intStorage() const
Definition: IMG_Metadata.h:182
GLint GLint GLsizei GLint GLenum format
Definition: glcorearb.h:108
long long int64
Definition: SYS_Types.h:116
static bool isReadOnly(Scope s)
Definition: IMG_Metadata.h:39
UT_JSONValue myValue
Definition: IMG_Metadata.h:192
GLuint const GLchar * name
Definition: glcorearb.h:786
GLboolean GLboolean GLboolean b
Definition: glcorearb.h:1222
UT_StringHolder myName
Definition: IMG_Metadata.h:404
Item & operator[](const UT_StringRef &name)
Definition: IMG_Metadata.h:430
GLdouble t
Definition: glad.h:2397
const Item & operator[](int idx) const
Definition: IMG_Metadata.h:427
A list of well-known metdata that a format understands. The list is ordered.
Definition: IMG_Metadata.h:370
bool contains(const UT_StringRef &key) const
Test if a key exists in the metadata.
Definition: IMG_Metadata.h:309
IMG_MetadataItem myItem
Definition: IMG_Metadata.h:405
__hostdev__ bool isInteger(GridType gridType)
Return true if the GridType maps to a POD integer type.
Definition: NanoVDB.h:820
Item(const UT_StringHolder &name, const IMG_MetadataItem &item)
Definition: IMG_Metadata.h:381
exint size() const
Definition: IMG_Metadata.h:422
IMG_MetadataItem(const UT_JSONValue &value, Storage store=Storage::MD_Unknown, TypeInfo type=TypeInfo::MD_None)
Definition: IMG_Metadata.h:114
GLuint index
Definition: glcorearb.h:786
UT_StringHolder menuLabel(const UT_StringRef &name, int idx) const
Definition: IMG_Metadata.h:448
GLuint GLfloat * val
Definition: glcorearb.h:1608
ImageBuf OIIO_API max(Image_or_Const A, Image_or_Const B, ROI roi={}, int nthreads=0)
Class to store JSON objects as C++ objects.
Definition: UT_JSONValue.h:99
Map of metadata items.
Definition: IMG_Metadata.h:208
void append(const Item &item)
Definition: IMG_Metadata.h:413
GLubyte GLubyte GLubyte GLubyte w
Definition: glcorearb.h:857
Definition: core.h:1131
ImageBuf OIIO_API add(Image_or_Const A, Image_or_Const B, ROI roi={}, int nthreads=0)
type
Definition: core.h:1059
unsigned int uint
Definition: SYS_Types.h:45
const Item & operator[](const UT_StringRef &name) const
Definition: IMG_Metadata.h:431
IMG_MetadataOptions(std::initializer_list< Item > init)
Definition: IMG_Metadata.h:408
FMT_CONSTEXPR auto find(Ptr first, Ptr last, T value, Ptr &out) -> bool
Definition: core.h:2089
GLenum src
Definition: glcorearb.h:1793
UT_StringHolder menuToken(const UT_StringRef &name, int idx) const
Definition: IMG_Metadata.h:445