1//
2// SPDX-License-Identifier: BSD-3-Clause
3// Copyright (c) Contributors to the OpenEXR Project.
4//
5
6#ifndef INCLUDED_IMF_STANDARD_ATTRIBUTES_H
7#define INCLUDED_IMF_STANDARD_ATTRIBUTES_H
8
9//-----------------------------------------------------------------------------
10//
11// Optional Standard Attributes -- these attributes are "optional"
12// because not every image file header has them, but they define a
13// "standard" way to represent commonly used data in the file header.
14//
15// For each attribute, with name "foo", and type "T", the following
16// functions are automatically generated via macros:
17//
18// void addFoo (Header &header, const T &value);
19// bool hasFoo (const Header &header);
20// const TypedAttribute<T> & fooAttribute (const Header &header);
21// TypedAttribute<T> & fooAttribute (Header &header);
22// const T & foo (const Header &Header);
23// T & foo (Header &Header);
24//
25//-----------------------------------------------------------------------------
26
27#include "ImfHeader.h"
28#include "ImfBoxAttribute.h"
29#include "ImfChromaticitiesAttribute.h"
30#include "ImfEnvmapAttribute.h"
31#include "ImfDeepImageStateAttribute.h"
32#include "ImfFloatAttribute.h"
33#include "ImfKeyCodeAttribute.h"
34#include "ImfMatrixAttribute.h"
35#include "ImfRationalAttribute.h"
36#include "ImfStringAttribute.h"
37#include "ImfStringVectorAttribute.h"
38#include "ImfTimeCodeAttribute.h"
39#include "ImfVecAttribute.h"
40#include "ImfNamespace.h"
41#include "ImfExport.h"
42#include "ImfIDManifestAttribute.h"
43
44#define IMF_ADD_SUFFIX(suffix) add##suffix
45#define IMF_HAS_SUFFIX(suffix) has##suffix
46#define IMF_NAME_ATTRIBUTE(name) name##Attribute
47
48#define IMF_STD_ATTRIBUTE_DEF(name, suffix, object) \
49 \
50 OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER \
51 IMF_EXPORT void IMF_ADD_SUFFIX (suffix) ( \
52 Header & header, const object& v); \
53 IMF_EXPORT bool IMF_HAS_SUFFIX (suffix) (const Header& header); \
54 IMF_EXPORT const TypedAttribute<object>& IMF_NAME_ATTRIBUTE (name) ( \
55 const Header& header); \
56 IMF_EXPORT TypedAttribute<object>& IMF_NAME_ATTRIBUTE (name) ( \
57 Header & header); \
58 IMF_EXPORT const object& name (const Header& header); \
59 IMF_EXPORT object& name (Header& header); \
60 OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_EXIT
61
62#define IMF_STD_ATTRIBUTE_DEF_DEPRECATED(name, suffix, object, msg) \
63 \
64 OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER \
65 OPENEXR_DEPRECATED (msg) \
66 IMF_EXPORT void IMF_ADD_SUFFIX (suffix) ( \
67 Header & header, const object& v); \
68 OPENEXR_DEPRECATED (msg) \
69 IMF_EXPORT bool IMF_HAS_SUFFIX (suffix) (const Header& header); \
70 OPENEXR_DEPRECATED (msg) \
71 IMF_EXPORT const TypedAttribute<object>& IMF_NAME_ATTRIBUTE (name) ( \
72 const Header& header); \
73 OPENEXR_DEPRECATED (msg) \
74 IMF_EXPORT TypedAttribute<object>& IMF_NAME_ATTRIBUTE (name) ( \
75 Header & header); \
76 OPENEXR_DEPRECATED (msg) \
77 IMF_EXPORT const object& name (const Header& header); \
78 OPENEXR_DEPRECATED (msg) IMF_EXPORT object& name (Header& header); \
79 OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_EXIT
80
81//
82// chromaticities -- for RGB images, specifies the CIE (x,y)
83// chromaticities of the primaries and the white point
84//
85
86IMF_STD_ATTRIBUTE_DEF (chromaticities, Chromaticities, Chromaticities)
87
88
89//
90// whiteLuminance -- for RGB images, defines the luminance, in Nits
91// (candelas per square meter) of the RGB value (1.0, 1.0, 1.0).
92//
93// If the chromaticities and the whiteLuminance of an RGB image are
94// known, then it is possible to convert the image's pixels from RGB
95// to CIE XYZ tristimulus values (see function RGBtoXYZ() in header
96// file ImfChromaticities.h).
97//
98//
99
100IMF_STD_ATTRIBUTE_DEF (whiteLuminance, WhiteLuminance, float)
101
102
103//
104// adoptedNeutral -- specifies the CIE (x,y) coordinates that should
105// be considered neutral during color rendering. Pixels in the image
106// file whose (x,y) coordinates match the adoptedNeutral value should
107// be mapped to neutral values on the display.
108//
109
110IMF_STD_ATTRIBUTE_DEF (adoptedNeutral, AdoptedNeutral, IMATH_NAMESPACE::V2f)
111
112
113//
114// renderingTransform, lookModTransform -- specify the names of the
115// CTL functions that implements the intended color rendering and look
116// modification transforms for this image.
117//
118
119IMF_STD_ATTRIBUTE_DEF (renderingTransform, RenderingTransform, std::string)
120IMF_STD_ATTRIBUTE_DEF (lookModTransform, LookModTransform, std::string)
121
122
123//
124// xDensity -- horizontal output density, in pixels per inch.
125// The image's vertical output density is xDensity * pixelAspectRatio.
126//
127
128IMF_STD_ATTRIBUTE_DEF (xDensity, XDensity, float)
129
130
131//
132// owner -- name of the owner of the image
133//
134
135IMF_STD_ATTRIBUTE_DEF (owner, Owner, std::string)
136
137
138//
139// comments -- additional image information in human-readable
140// form, for example a verbal description of the image
141//
142
143IMF_STD_ATTRIBUTE_DEF (comments, Comments, std::string)
144
145
146//
147// capDate -- the date when the image was created or captured,
148// in local time, and formatted as
149//
150// YYYY:MM:DD hh:mm:ss
151//
152// where YYYY is the year (4 digits, e.g. 2003), MM is the month
153// (2 digits, 01, 02, ... 12), DD is the day of the month (2 digits,
154// 01, 02, ... 31), hh is the hour (2 digits, 00, 01, ... 23), mm
155// is the minute, and ss is the second (2 digits, 00, 01, ... 59).
156//
157//
158
159IMF_STD_ATTRIBUTE_DEF (capDate, CapDate, std::string)
160
161
162//
163// utcOffset -- offset of local time at capDate from
164// Universal Coordinated Time (UTC), in seconds:
165//
166// UTC == local time + utcOffset
167//
168
169IMF_STD_ATTRIBUTE_DEF (utcOffset, UtcOffset, float)
170
171
172//
173// longitude, latitude, altitude -- for images of real objects, the
174// location where the image was recorded. Longitude and latitude are
175// in degrees east of Greenwich and north of the equator. Altitude
176// is in meters above sea level. For example, Kathmandu, Nepal is
177// at longitude 85.317, latitude 27.717, altitude 1305.
178//
179
180IMF_STD_ATTRIBUTE_DEF (longitude, Longitude, float)
181IMF_STD_ATTRIBUTE_DEF (latitude, Latitude, float)
182IMF_STD_ATTRIBUTE_DEF (altitude, Altitude, float)
183
184
185//
186// focus -- the camera's focus distance, in meters
187//
188
189IMF_STD_ATTRIBUTE_DEF (focus, Focus, float)
190
191
192//
193// exposure -- exposure time, in seconds
194//
195
196IMF_STD_ATTRIBUTE_DEF (expTime, ExpTime, float)
197
198
199//
200// aperture -- the camera's lens aperture, in f-stops (focal length
201// of the lens divided by the diameter of the iris opening)
202//
203
204IMF_STD_ATTRIBUTE_DEF (aperture, Aperture, float)
205
206
207//
208// isoSpeed -- the ISO speed of the film or image sensor
209// that was used to record the image
210//
211
212IMF_STD_ATTRIBUTE_DEF (isoSpeed, IsoSpeed, float)
213
214
215//
216// envmap -- if this attribute is present, the image represents
217// an environment map. The attribute's value defines how 3D
218// directions are mapped to 2D pixel locations. For details
219// see header file ImfEnvmap.h
220//
221
222IMF_STD_ATTRIBUTE_DEF (envmap, Envmap, Envmap)
223
224
225//
226// keyCode -- for motion picture film frames. Identifies film
227// manufacturer, film type, film roll and frame position within
228// the roll.
229//
230
231IMF_STD_ATTRIBUTE_DEF (keyCode, KeyCode, KeyCode)
232
233
234//
235// timeCode -- time and control code
236//
237
238IMF_STD_ATTRIBUTE_DEF (timeCode, TimeCode, TimeCode)
239
240
241//
242// wrapmodes -- determines how texture map images are extrapolated.
243// If an OpenEXR file is used as a texture map for 3D rendering,
244// texture coordinates (0.0, 0.0) and (1.0, 1.0) correspond to
245// the upper left and lower right corners of the data window.
246// If the image is mapped onto a surface with texture coordinates
247// outside the zero-to-one range, then the image must be extrapolated.
248// This attribute tells the renderer how to do this extrapolation.
249// The attribute contains either a pair of comma-separated keywords,
250// to specify separate extrapolation modes for the horizontal and
251// vertical directions; or a single keyword, to specify extrapolation
252// in both directions (e.g. "clamp,periodic" or "clamp"). Extra white
253// space surrounding the keywords is allowed, but should be ignored
254// by the renderer ("clamp, black " is equivalent to "clamp,black").
255// The keywords listed below are predefined; some renderers may support
256// additional extrapolation modes:
257//
258// black pixels outside the zero-to-one range are black
259//
260// clamp texture coordinates less than 0.0 and greater
261// than 1.0 are clamped to 0.0 and 1.0 respectively
262//
263// periodic the texture image repeats periodically
264//
265// mirror the texture image repeats periodically, but
266// every other instance is mirrored
267//
268
269IMF_STD_ATTRIBUTE_DEF (wrapmodes, Wrapmodes, std::string)
270
271
272//
273// framesPerSecond -- defines the nominal playback frame rate for image
274// sequences, in frames per second. Every image in a sequence should
275// have a framesPerSecond attribute, and the attribute value should be
276// the same for all images in the sequence. If an image sequence has
277// no framesPerSecond attribute, playback software should assume that
278// the frame rate for the sequence is 24 frames per second.
279//
280// In order to allow exact representation of NTSC frame and field rates,
281// framesPerSecond is stored as a rational number. A rational number is
282// a pair of integers, n and d, that represents the value n/d.
283//
284// For the exact values of commonly used frame rates, please see header
285// file ImfFramesPerSecond.h.
286//
287
288IMF_STD_ATTRIBUTE_DEF (framesPerSecond, FramesPerSecond, Rational)
289
290
291//
292// multiView -- defines the view names for multi-view image files.
293// A multi-view image contains two or more views of the same scene,
294// as seen from different viewpoints, for example a left-eye and
295// a right-eye view for stereo displays. The multiView attribute
296// lists the names of the views in an image, and a naming convention
297// identifies the channels that belong to each view.
298//
299// For details, please see header file ImfMultiView.h
300//
301
302IMF_STD_ATTRIBUTE_DEF (multiView , MultiView, StringVector)
303
304
305//
306// worldToCamera -- for images generated by 3D computer graphics rendering,
307// a matrix that transforms 3D points from the world to the camera coordinate
308// space of the renderer.
309//
310// The camera coordinate space is left-handed. Its origin indicates the
311// location of the camera. The positive x and y axes correspond to the
312// "right" and "up" directions in the rendered image. The positive z
313// axis indicates the camera's viewing direction. (Objects in front of
314// the camera have positive z coordinates.)
315//
316// Camera coordinate space in OpenEXR is the same as in Pixar's Renderman.
317//
318
319IMF_STD_ATTRIBUTE_DEF (worldToCamera, WorldToCamera, IMATH_NAMESPACE::M44f)
320
321
322//
323// worldToNDC -- for images generated by 3D computer graphics rendering, a
324// matrix that transforms 3D points from the world to the Normalized Device
325// Coordinate (NDC) space of the renderer.
326//
327// NDC is a 2D coordinate space that corresponds to the image plane, with
328// positive x and pointing to the right and y positive pointing down. The
329// coordinates (0, 0) and (1, 1) correspond to the upper left and lower right
330// corners of the OpenEXR display window.
331//
332// To transform a 3D point in word space into a 2D point in NDC space,
333// multiply the 3D point by the worldToNDC matrix and discard the z
334// coordinate.
335//
336// NDC space in OpenEXR is the same as in Pixar's Renderman.
337//
338
339IMF_STD_ATTRIBUTE_DEF (worldToNDC, WorldToNDC, IMATH_NAMESPACE::M44f)
340
341
342//
343// deepImageState -- specifies whether the pixels in a deep image are
344// sorted and non-overlapping.
345//
346// Note: this attribute can be set by application code that writes a file
347// in order to tell applications that read the file whether the pixel data
348// must be cleaned up prior to image processing operations such as flattening.
349// The OpenEXR library does not verify that the attribute is consistent with
350// the actual state of the pixels. Application software may assume that the
351// attribute is valid, as long as the software will not crash or lock up if
352// any pixels are inconsistent with the deepImageState attribute.
353//
354
355IMF_STD_ATTRIBUTE_DEF (deepImageState, DeepImageState, DeepImageState)
356
357
358//
359// originalDataWindow -- if application software crops an image, then it
360// should save the data window of the original, un-cropped image in the
361// originalDataWindow attribute.
362//
363
364IMF_STD_ATTRIBUTE_DEF
365 (originalDataWindow, OriginalDataWindow, IMATH_NAMESPACE::Box2i)
366
367
368//
369// dwaCompressionLevel -- sets the quality level for images compressed
370// with the DWAA or DWAB method.
371//
372// DEPRECATED: use the methods directly in the header
373IMF_STD_ATTRIBUTE_DEF_DEPRECATED (
374 dwaCompressionLevel,
375 DwaCompressionLevel,
376 float,
377 "use compression method in ImfHeader")
378
379//
380// ID Manifest
381//
382
383IMF_STD_ATTRIBUTE_DEF( idManifest,IDManifest,CompressedIDManifest)
384
385#endif
386

source code of include/OpenEXR/ImfStandardAttributes.h