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