OpenImageIO 1.7 Programmer Documentation (in progress) Editor: Larry Gritz [email protected] Date: 31 Mar 2016 ii The OpenImageIO source code and documentation are: Copyright (c) 2008-2016 Larry Gritz, et al. All Rights Reserved. The code that implements OpenImageIO is licensed under the BSD 3-clause (also some- times known as “new BSD” or “modified BSD”) license: Redistribution and use in source and binary forms, with or without modification, are per- mitted provided that the following conditions are met: • Redistributions of source code must retain the above copyright notice, this list of condi- tions and the following disclaimer. • Redistributions in binary form must reproduce the above copyright notice, this list of con- ditions and the following disclaimer in the documentation and/or other materials provided with the distribution. • Neither the name of the software’s owners nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIB- UTORS ”AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FIT- NESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUD- ING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABIL- ITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. This manual and other text documentation about OpenImageIO are licensed under the Cre- ative Commons Attribution 3.0 Unported License. http://creativecommons.org/licenses/by/3.0/ OpenImageIO Programmer’s Documentation iii I kinda like “Oy-e-oh” with a bit of a groaning Yiddish accent, as in “OIIO, did you really write yet another file I/O library?” Dan Wexler OpenImageIO Programmer’s Documentation iv OpenImageIO Programmer’s Documentation Contents 1 Introduction 1 1.1 Overview . 1 1.2 Simplifying Assumptions . 2 I The OpenImageIO Library APIs 7 2 Image I/O API Helper Classes 9 2.1 Data Type Descriptions: TypeDesc ........................ 9 2.2 Efficient unique strings: ustring ........................ 11 2.3 Non-owning string views: string view .................... 12 2.4 Non-owning array views: array view ..................... 13 2.5 Image Specification: ImageSpec ......................... 14 2.6 “Deep” pixel data: DeepData ........................... 20 3 ImageOutput: Writing Images 27 3.1 Image Output Made Simple . 27 3.2 Advanced Image Output . 29 3.3 ImageOutput Class Reference . 47 4 Image I/O: Reading Images 55 4.1 Image Input Made Simple . 55 4.2 Advanced Image Input . 56 4.3 ImageInput Class Reference . 68 5 Writing ImageIO Plugins 75 5.1 Plugin Introduction . 75 5.2 Image Readers . 75 5.3 Image Writers . 84 5.4 Tips and Conventions . 94 5.5 Building ImageIO Plugins . 95 6 Bundled ImageIO Plugins 97 6.1 BMP . 97 6.2 Cineon . 97 v vi CONTENTS 6.3 DDS . 97 6.4 DPX . 98 6.5 Field3D . 100 6.6 FITS . 100 6.7 GIF . 101 6.8 HDR/RGBE . 101 6.9 ICO . 102 6.10 IFF . 102 6.11 JPEG . 102 6.12 JPEG-2000 . 104 6.13 Movie formats (using ffmpeg) . 104 6.14 OpenEXR . 104 6.15 PNG . 106 6.16 PNM / Netpbm . 106 6.17 PSD . 107 6.18 Ptex . 107 6.19 RLA . 107 6.20 SGI . 109 6.21 Softimage PIC . 109 6.22 RAW digital camera files . 109 6.23 Targa . 109 6.24 TIFF . 110 6.25 Webp . 115 6.26 Zfile . 115 7 Cached Images 117 7.1 Image Cache Introduction and Theory of Operation . 117 7.2 ImageCache API . 119 8 Texture Access: TextureSystem 131 8.1 Texture System Introduction and Theory of Operation . 131 8.2 Helper Classes . 131 8.3 TextureSystem API . 137 9 Image Buffers 155 9.1 ImageBuf Introduction and Theory of Operation . 155 9.2 Constructing, reading, and writing an ImageBuf . 157 9.3 Getting and setting basic information about an ImageBuf . 160 9.4 Copying ImageBuf’s and blocks of pixels . 162 9.5 Getting and setting individual pixel values – simple but slow . 164 9.6 Miscellaneous . 166 9.7 Iterators – the fast way of accessing individual pixels . 167 9.8 Dealing with buffer data types . 170 OpenImageIO Programmer’s Documentation CONTENTS vii 10 Image Processing 173 10.1 ImageBufAlgo general principles . 173 10.2 Pattern generation . 174 10.3 Image transformations and data movement . 179 10.4 Image arithmetic . 187 10.5 Image comparison and statistics . 194 10.6 Convolutions . 199 10.7 Image Enhancement / Restoration . 202 10.8 Color manipulation . 204 10.9 Import / export . 207 10.10Deep images . 211 11 Python Bindings 215 11.1 Overview . 215 11.2 TypeDesc . 215 11.3 ROI . 218 11.4 ImageSpec . 220 11.5 DeepData . 225 11.6 ImageInput . 227 11.7 ImageOutput . 232 11.8 ImageBuf . 236 11.9 ImageBufAlgo . 244 11.10Miscellaneous Utilities . 262 11.11Python Recipes . 262 II Image Utilities 267 12 oiiotool: the OIIO Swiss Army Knife 269 12.1 Overview . 269 12.2 oiiotool Tutorial / Recipes . 272 12.3 oiiotool commands: general and image information . 278 12.4 oiiotool commands: reading and writing images . 281 12.5 oiiotool commands that change the current image metadata . 287 12.6 oiiotool commands that shuffle channels or subimages . 289 12.7 oiiotool commands that adjust the image stack . 291 12.8 oiiotool commands that make entirely new images . 291 12.9 oiiotool commands that do image processing . 294 12.10oiiotool commands for color management . 311 12.11oiiotool commands for deep images . 313 13 The iv Image Viewer 317 14 Getting Image information With iinfo 319 14.1 Using iinfo ....................................319 14.2 iinfo command-line options . 321 OpenImageIO Programmer’s Documentation viii CONTENTS 15 Converting Image Formats With iconvert 323 15.1 Overview . 323 15.2 iconvert Recipes . 323 15.3 iconvert command-line options . 325 16 Searching Image Metadata With igrep 329 16.1 Using igrep ....................................329 16.2 igrep.