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 <ImfChromaticitiesAttribute.h> 59 #include <ImfEnvmapAttribute.h> 60 #include <ImfFloatAttribute.h> 61 #include <ImfKeyCodeAttribute.h> 62 #include <ImfMatrixAttribute.h> 63 #include <ImfRationalAttribute.h> 64 #include <ImfStringAttribute.h> 65 #include <ImfStringVectorAttribute.h> 66 #include <ImfTimeCodeAttribute.h> 67 #include <ImfVecAttribute.h> 68 69 #define IMF_STD_ATTRIBUTE_DEF(name,suffix,type) \ 70 \ 71 void add##suffix (Header &header, const type &v); \ 72 bool has##suffix (const Header &header); \ 73 const TypedAttribute<type> & name##Attribute (const Header &header); \ 74 TypedAttribute<type> & name##Attribute (Header &header); \ 75 const type & name (const Header &header); \ 76 type & name (Header &header); 77 78 79 namespace Imf { 80 81 // 82 // chromaticities -- for RGB images, specifies the CIE (x,y) 83 // chromaticities of the primaries and the white point 84 // 85 86 IMF_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 100 IMF_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 110 IMF_STD_ATTRIBUTE_DEF (adoptedNeutral, AdoptedNeutral, Imath::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 119 IMF_STD_ATTRIBUTE_DEF (renderingTransform, RenderingTransform, std::string) 120 IMF_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 128 IMF_STD_ATTRIBUTE_DEF (xDensity, XDensity, float) 129 130 131 // 132 // owner -- name of the owner of the image 133 // 134 135 IMF_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 143 IMF_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 159 IMF_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 169 IMF_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 180 IMF_STD_ATTRIBUTE_DEF (longitude, Longitude, float) 181 IMF_STD_ATTRIBUTE_DEF (latitude, Latitude, float) 182 IMF_STD_ATTRIBUTE_DEF (altitude, Altitude, float) 183 184 185 // 186 // focus -- the camera's focus distance, in meters 187 // 188 189 IMF_STD_ATTRIBUTE_DEF (focus, Focus, float) 190 191 192 // 193 // exposure -- exposure time, in seconds 194 // 195 196 IMF_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 204 IMF_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 212 IMF_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 222 IMF_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 231 IMF_STD_ATTRIBUTE_DEF (keyCode, KeyCode, KeyCode) 232 233 234 // 235 // timeCode -- time and control code 236 // 237 238 IMF_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 269 IMF_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 288 IMF_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 302 IMF_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 319 IMF_STD_ATTRIBUTE_DEF (worldToCamera, WorldToCamera, Imath::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 339 IMF_STD_ATTRIBUTE_DEF (worldToNDC, WorldToNDC, Imath::M44f) 340 341 } // namespace Imf 342 343 #endif 344