1.. _chap-bundledplugins: 2 3Bundled ImageIO Plugins 4####################### 5 6This chapter lists all the image format plugins that are bundled with 7OpenImageIO. For each plugin, we delineate any limitations, custom 8attributes, etc. The plugins are listed alphabetically by format name. 9 10 11 12| 13 14.. _sec-bundledplugins-bmp: 15 16BMP 17=============================================== 18 19BMP is a bitmap image file format used mostly on Windows systems. 20BMP files use the file extension :file:`.bmp`. 21 22BMP is not a nice format for high-quality or high-performance images. 23It only supports unsigned integer 1-, 2-, 4-, and 8- bits per channel; only 24grayscale, RGB, and RGBA; does not support MIPmaps, multiimage, or 25tiles. 26 27**Configuration settings for BMP input** 28 29When opening a BMP ImageInput with a *configuration* (see 30Section :ref:`sec-inputwithconfig`), the following special configuration 31options are supported: 32 33.. list-table:: 34 :widths: 30 10 65 35 :header-rows: 1 36 37 * - Input Configuration Attribute 38 - Type 39 - Meaning 40 * - ``bmp:monochrome_detect`` 41 - int 42 - If nonzero, try to detect when all palette entries are gray and pretend 43 that it's a 1-channel image to allow the calling app to save memory 44 and time (even though the BMP format does not actually support 45 grayscale images per se. It is 1 by default, but by setting the hint 46 to 0, you can disable this behavior. 47 48**BMP Attributes** 49 50.. list-table:: 51 :widths: 30 10 65 52 :header-rows: 1 53 54 * - ImageSpec Attribute 55 - Type 56 - BMP header data or explanation 57 * - ``XResolution`` 58 - float 59 - hres 60 * - ``YResolution`` 61 - float 62 - vres 63 * - ``ResolutionUnit`` 64 - string 65 - always ``"m"`` (pixels per meter) 66 * - ``bmp:bitsperpixel`` 67 - int 68 - When not a whole number of bytes per channel, this describes the 69 bits per pixel in the file (16 for R4G4B4, 8 for a 256-color palette 70 image, 4 for a 16-color palette image, 1 for a 2-color palette image). 71 * - ``bmp:version`` 72 - int 73 - Version of the BMP file format 74 75**BMP Limitations** 76 77* OIIO's current implementation will only write uncompessed 8bpp (from a 78 1-channel source), 24bpp (if 3 channel), or 32bpp (if 4 channel). Reads, 79 however, can handle RLE compression as well as 1, 4, or 16 bpp input. 80* Only 1, 3, and 4-channel images are supported with BMP due to limitations 81 of the file format itself. 82* BMP only supports uint8 pixel data types. Requests for other pixel data 83 types will automatically be converted to uint8. 84 85| 86 87.. _sec-bundledplugins-cineon: 88 89Cineon 90=============================================== 91 92Cineon is an image file format developed by Kodak that is commonly 93used for scanned motion picture film and digital intermediates. 94Cineon files use the file extension :file:`.cin`. 95 96 97 98| 99 100.. _sec-bundledplugins-dds: 101 102DDS 103=============================================== 104 105DDS (Direct Draw Surface) is an image file format designed by Microsoft 106for use in Direct3D graphics. DDS files use the extension :file:`.dds`. 107 108DDS is an awful format, with several compression modes that are all so 109lossy as to be completely useless for high-end graphics. Nevertheless, 110they are widely used in games and graphics hardware directly supports 111these compression modes. Alas. 112 113OpenImageIO currently only supports reading DDS files, not writing them. 114 115.. list-table:: 116 :widths: 30 10 65 117 :header-rows: 1 118 119 * - ImageSpec Attribute 120 - Type 121 - DDS header data or explanation 122 * - ``compression`` 123 - string 124 - Compression type 125 * - ``oiio:BitsPerSample`` 126 - int 127 - bits per sample 128 * - ``textureformat`` 129 - string 130 - Set correctly to one of ``"Plain Texture"``, ``"Volume Texture"``, or 131 ``"CubeFace Environment"``. 132 * - ``texturetype`` 133 - string 134 - Set correctly to one of ``"Plain Texture"``, ``"Volume Texture"``, 135 or ``"Environment"``. 136 * - ``dds:CubeMapSides`` 137 - string 138 - For environment maps, which cube faces are present (e.g., ``"+x -x 139 +y -y"`` if *x* & *y* faces are present, but not *z*). 140 141 142 143 144| 145 146.. _sec-bundledplugins-dicom: 147 148DICOM 149=============================================== 150 151DICOM (Digital Imaging and Communications in Medicine) is the standard 152format used for medical images. DICOM files usually have the extension 153:file:`.dcm`. 154 155OpenImageIO currently only supports reading DICOM files, not writing them. 156 157 158.. list-table:: 159 :widths: 30 10 65 160 :header-rows: 1 161 162 * - ImageSpec Attribute 163 - Type 164 - DDS header data or explanation 165 * - ``oiio:BitsPerSample`` 166 - int 167 - Bits per sample. 168 * - ``dicom:*`` 169 - *any* 170 - DICOM header information and metadata is currently all 171 preceded by the ``dicom:`` prefix. 172 173 174 175| 176 177.. _sec-bundledplugins-dpx: 178 179DPX 180=============================================== 181 182DPX (Digital Picture Exchange) is an image file format used for 183motion picture film scanning, output, and digital intermediates. 184DPX files use the file extension :file:`.dpx`. 185 186 187**Configuration settings for DPX input** 188 189When opening a DPX ImageInput with a *configuration* (see 190Section :ref:`sec-inputwithconfig`), the following special configuration 191options are supported: 192 193.. list-table:: 194 :widths: 30 10 65 195 :header-rows: 1 196 197 * - Input Configuration Attribute 198 - Type 199 - Meaning 200 * - ``oiio:RawColor`` 201 - int 202 - If nonzero, reading images with non-RGB color models (such as YCbCr) 203 will return unaltered pixel values (versus the default OIIO behavior 204 of automatically converting to RGB). 205 * - ``oiio:ioproxy`` 206 - ptr 207 - Pointer to a ``Filesystem::IOProxy`` that will handle the I/O, for 208 example by reading from memory rather than the file system. 209 210 211**Configuration settings for DPX output** 212 213When opening a DPX ImageOutput, the following special metadata tokens 214control aspects of the writing itself: 215 216.. list-table:: 217 :widths: 30 10 65 218 :header-rows: 1 219 220 * - Output configuration Attribute 221 - Type 222 - Meaning 223 * - ``oiio:RawColor`` 224 - int 225 - If nonzero, writing images with non-RGB color models (such as YCbCr) 226 will keep unaltered pixel values (versus the default OIIO behavior 227 of automatically converting from RGB to the designated color space 228 as the pixels are written). 229 230**Custom I/O Overrides** 231 232DPX input (but, currently, not output) supports the "custom I/O" feature 233via the `ImageInput::set_ioproxy()` method and the special 234``"oiio:ioproxy"`` attributes (see Section :ref:`sec-imageinput-ioproxy`). 235 236**DPX Attributes** 237 238.. list-table:: 239 :widths: 30 10 65 240 :header-rows: 1 241 242 * - ImageSpec Attribute 243 - Type 244 - DPX header data or explanation 245 * - ``ImageDescription`` 246 - string 247 - Description of image element 248 * - ``Copyright`` 249 - string 250 - Copyright statement 251 * - ``Software`` 252 - string 253 - Creator 254 * - ``DocumentName`` 255 - string 256 - Project name 257 * - ``DateTime`` 258 - string 259 - Creation date/time 260 * - ``Orientation`` 261 - int 262 - the orientation of the DPX image data (see ``metadata:orientation``) 263 * - ``compression`` 264 - string 265 - The compression type 266 * - ``PixelAspectRatio`` 267 - float 268 - pixel aspect ratio 269 * - ``oiio:BitsPerSample`` 270 - int 271 - the true bits per sample of the DPX file. 272 * - ``oiio:Endian`` 273 - string 274 - When writing, force a particular endianness for the output ``"little"`` or ``"big"``) 275 * - ``smpte:TimeCode`` 276 - int[2] 277 - SMPTE time code (vecsemantics will be marked as TIMECODE) 278 * - ``smpte:KeyCode`` 279 - int[7] 280 - SMPTE key code (vecsemantics will be marked as KEYCODE) 281 * - ``dpx:Transfer`` 282 - string 283 - Transfer characteristic 284 * - ``dpx:Colorimetric`` 285 - string 286 - Colorimetric specification 287 * - ``dpx:ImageDescriptor`` 288 - string 289 - ImageDescriptor 290 * - ``dpx:Packing`` 291 - string 292 - Image packing method 293 * - ``dpx:TimeCode`` 294 - int 295 - SMPTE time code 296 * - ``dpx:UserBits`` 297 - int 298 - SMPTE user bits 299 * - ``dpx:SourceDateTime`` 300 - string 301 - source time and date 302 * - ``dpx:FilmEdgeCode`` 303 - string 304 - FilmEdgeCode 305 * - ``dpx:Signal`` 306 - string 307 - Signal (``"Undefined"``, ``"NTSC"``, ``"PAL"``, etc.) 308 * - ``dpx:UserData`` 309 - UCHAR[*] 310 - User data (stored in an array whose length is whatever it it was in the DPX file) 311 * - ``dpx:EncryptKey`` 312 - int 313 - Encryption key (-1 is not encrypted) 314 * - ``dpx:DittoKey`` 315 - int 316 - Ditto (0 = same as previous frame, 1 = new) 317 * - ``dpx:LowData`` 318 - int 319 - reference low data code value 320 * - ``dpx:LowQuantity`` 321 - float 322 - reference low quantity 323 * - ``dpx:HighData`` 324 - int 325 - reference high data code value 326 * - ``dpx:HighQuantity`` 327 - float 328 - reference high quantity 329 * - ``dpx:XScannedSize`` 330 - float 331 - X scanned size 332 * - ``dpx:YScannedSize`` 333 - float 334 - Y scanned size 335 * - ``dpx:FramePosition`` 336 - int 337 - frame position in sequence 338 * - ``dpx:SequenceLength`` 339 - int 340 - sequence length (frames) 341 * - ``dpx:HeldCount`` 342 - int 343 - held count (1 = default) 344 * - ``dpx:FrameRate`` 345 - float 346 - frame rate of original (frames/s) 347 * - ``dpx:ShutterAngle`` 348 - float 349 - shutter angle of camera (deg) 350 * - ``dpx:Version`` 351 - string 352 - version of header format 353 * - ``dpx:Format`` 354 - string 355 - format (e.g., ``"Academy"``) 356 * - ``dpx:FrameId`` 357 - string 358 - frame identification 359 * - ``dpx:SlateInfo`` 360 - string 361 - slate information 362 * - ``dpx:SourceImageFileName`` 363 - string 364 - source image filename 365 * - ``dpx:InputDevice`` 366 - string 367 - input device name 368 * - ``dpx:InputDeviceSerialNumber`` 369 - string 370 - input device serial number 371 * - ``dpx:Interlace`` 372 - int 373 - interlace (0 = noninterlace, 1 = 2:1 interlace 374 * - ``dpx:FieldNumber`` 375 - int 376 - field number 377 * - ``dpx:HorizontalSampleRate`` 378 - float 379 - horizontal sampling rate (Hz) 380 * - ``dpx:VerticalSampleRate`` 381 - float 382 - vertical sampling rate (Hz) 383 * - ``dpx:TemporalFrameRate`` 384 - float 385 - temporal sampling rate (Hz) 386 * - ``dpx:TimeOffset`` 387 - float 388 - time offset from sync to first pixel (ms) 389 * - ``dpx:BlackLevel`` 390 - float 391 - black level code value 392 * - ``dpx:BlackGain`` 393 - float 394 - black gain 395 * - ``dpx:BreakPoint`` 396 - float 397 - breakpoint 398 * - ``dpx:WhiteLevel`` 399 - float 400 - reference white level code value 401 * - ``dpx:IntegrationTimes`` 402 - float 403 - integration time (s) 404 * - ``dpx:EndOfLinePadding`` 405 - int 406 - Padded bytes at the end of each line 407 * - ``dpx:EndOfImagePadding`` 408 - int 409 - Padded bytes at the end of each image 410 411 412| 413 414.. _sec-bundledplugins-field3d: 415 416Field3D 417=============================================== 418 419Field3d is an open-source volume data file format. Field3d files commonly 420use the extension :file:`.f3d`. The official Field3D site is: 421https://github.com/imageworks/Field3D Currently, OpenImageIO only reads 422Field3d files, and does not write them. 423 424Fields are comprised of multiple *layers* (which appear to OpenImageIO 425as subimages). Each layer/subimage may have a different name, resolution, 426and coordinate mapping. Layers may be scalar (1 channel) or vector (3 427channel) fields, and the data may be ``half``, `float`, or ``double``. 428 429OpenImageIO always reports Field3D files as tiled. If the Field3d file has 430a "block size", the block size will be reported as the tile size. Otherwise, 431the tile size will be the size of the entire volume. 432 433.. list-table:: 434 :widths: 30 10 65 435 :header-rows: 1 436 437 * - ImageSpec Attribute 438 - Type 439 - Field3d header data or explanation 440 * - ``ImageDescription`` 441 - string 442 - unique layer name 443 * - ``oiio:subimagename`` 444 - string 445 - unique layer name 446 * - ``field3d:partition`` 447 - string 448 - the partition name 449 * - ``field3d:layer`` 450 - string 451 - the layer (a.k.a. attribute) name 452 * - ``field3d:fieldtype`` 453 - string 454 - field type, one of: ``"dense"``, ``"sparse"``, or ``"MAC"`` 455 * - ``field3d:mapping`` 456 - string 457 - the coordinate mapping type 458 * - ``field3d:localtoworld`` 459 - matrix of doubles 460 - if a matrixMapping, the local-to-world transformation matrix 461 * - ``worldtolocal`` 462 - matrix 463 - if a matrixMapping, the world-to-local coordinate mapping 464 465 466The "unique layer name" is generally the partition name + ``:`` + attribute 467name (example: ``"defaultfield:density"``), with the following exceptions: 468(1) if the partition and attribute names are identical, just one is used 469rather than it being pointlessly concatenated (e.g., ``"density"``, not 470``"density:density"``); (2) if there are mutiple partitions + attribute 471combinations with identical names in the same file, "*number*" will be added 472after the partition name for subsequent layers (e.g., ``"default:density"``, 473``"default.2:density"``, ``"default.3:density"``). 474 475| 476 477.. _sec-bundledplugins-fits: 478 479FITS 480=============================================== 481 482FITS (Flexible Image Transport System) is an image file format used for 483scientific applications, particularly professional astronomy. FITS files use 484the file extension :file:`.fits`. Official FITS specs and other info may be 485found at: http://fits.gsfc.nasa.gov/ 486 487OpenImageIO supports multiple images in FITS files, and supports the 488following pixel data types: UINT8, UINT16, UINT32, FLOAT, DOUBLE. 489 490FITS files can store various kinds of arbitrary data arrays, but 491OpenImageIO's support of FITS is mostly limited using FITS for image 492storage. Currently, OpenImageIO only supports 2D FITS data (images), not 3D 493(volume) data, nor 1-D or higher-dimensional arrays. 494 495 496 497.. list-table:: 498 :widths: 30 10 65 499 :header-rows: 1 500 501 * - ImageSpec Attribute 502 - Type 503 - FITS header data or explanation 504 * - ``Orientation`` 505 - int 506 - derived from FITS "ORIENTAT" field. 507 * - ``DateTime`` 508 - string 509 - derived from the FITS "DATE" field. 510 * - ``Comment`` 511 - string 512 - FITS "COMMENT" (*) 513 * - ``History`` 514 - string 515 - FITS "HISTORY" (*) 516 * - ``Hierarch`` 517 - string 518 - FITS "HIERARCH" (*) 519 * - *other* 520 - 521 - all other FITS keywords will be added to the ImageSpec as arbitrary 522 named metadata. 523 524.. note:: If the file contains multiple COMMENT, HISTORY, or HIERARCH 525 fields, their text will be appended to form a single attribute (of 526 each) in OpenImageIO's ImageSpec. 527 528 529| 530 531.. _sec-bundledplugins-gif: 532 533GIF 534=============================================== 535 536GIF (Graphics Interchange Format) is an image file format developed by 537CompuServe in 1987. Nowadays it is widely used to display basic animations 538despite its technical limitations. 539 540.. list-table:: 541 :widths: 30 10 65 542 :header-rows: 1 543 544 * - ImageSpec Attribute 545 - Type 546 - GIF header data or explanation 547 * - ``gif:Interlacing`` 548 - int 549 - Specifies if image is interlaced (0 or 1). 550 * - ``FramesPerSecond`` 551 - int[2] (rational) 552 - Frames per second 553 * - ``oiio:Movie`` 554 - int 555 - If nonzero, indicates that it's a multi-subimage file indended to represent an animation. 556 * - ``oiio:LoopCount`` 557 - int 558 - Number of times the animation should be played (0-65535, 0 stands for infinity). 559 * - ``gif:LoopCount`` 560 - int 561 - Deprecated synonym for ``oiio:LoopCount``. 562 * - ``ImageDescription`` 563 - string 564 - The GIF comment field. 565 566**Limitations** 567 568* GIF only supports 3-channel (RGB) images and at most 8 bits per channel. 569* Each subimage can include its own palette or use global palette. Palettes 570 contain up to 256 colors of which one can be used as background color. It 571 is then emulated with additional Alpha channel by OpenImageIO's reader. 572 573| 574 575.. _sec-bundledplugins-hdr: 576 577HDR/RGBE 578=============================================== 579 580HDR (High Dynamic Range), also known as RGBE (rgb with extended range), 581is a simple format developed for the Radiance renderer to store high 582dynamic range images. HDR/RGBE files commonly use the file extensions 583:file:`.hdr`. The format is described in this section of the Radiance 584documentation: http://radsite.lbl.gov/radiance/refer/filefmts.pdf 585 586RGBE does not support tiles, multiple subimages, mipmapping, true half or 587float pixel values, or arbitrary metadata. Only RGB (3 channel) files are 588supported. 589 590RGBE became important because it was developed at a time when no standard 591file formats supported high dynamic range, and is still used for many legacy 592applications and to distribute HDR environment maps. But newer formats with 593native HDR support, such as OpenEXR, are vastly superior and should be 594preferred except when legacy file access is required. 595 596 597.. list-table:: 598 :widths: 30 10 65 599 :header-rows: 1 600 601 * - ImageSpec Attribute 602 - Type 603 - RGBE header data or explanation 604 * - ``Orientation`` 605 - int 606 - encodes the orientation (see Section :ref:`sec-metadata-orientation`) 607 * - ``oiio:ColorSpace`` 608 - string 609 - Color space (see Section :ref:`sec-metadata-color`). 610 * - ``oiio:Gamma`` 611 - float 612 - the gamma correction specified in the RGBE header (if it's gamma corrected). 613 614 615 616| 617 618.. _sec-bundledplugins-heif: 619 620HEIF/HEIC/AVIF 621=============================================== 622 623HEIF is a container format for images compressed with various compression 624standards (HEIC is based on HEVC/H.265, AVIF is based on AV1). HEIC is used 625commonly for iPhone camera pictures, but it is not Apple-specific and will 626probably become more popular on other platforms in coming years. HEIF files 627usually use the file extension :file:`.HEIC` or :file:`.AVIF` depending on their 628main compression type. 629 630HEIC and AVIF compression formats are lossy, but are higher visual quality than 631JPEG while taking <= half the file size. Currently, OIIO's HEIF reader supports 632reading files as RGB or RGBA, uint8 pixel values. Multi-image files are 633currently supported for reading, but not yet writing. All pixel data is 634uint8, though we hope to add support for HDR (more than 8 bits) in the 635future. 636 637**Configuration settings for HEIF output** 638 639When opening an HEIF ImageOutput, the following special metadata tokens 640control aspects of the writing itself: 641 642 643.. list-table:: 644 :widths: 30 10 65 645 :header-rows: 1 646 647 * - ImageSpec Attribute 648 - Type 649 - HEIF header data or explanation 650 * - ``Compression`` 651 - string 652 - If supplied, can be ``"heic"`` or ``"avif"``, but may optionally have a 653 quality value appended, like ``"heic:90"``. Quality can be 1-100, with 654 100 meaning lossless. The default is 75. 655 656 657 658| 659 660.. _sec-bundledplugins-ico: 661 662ICO 663=============================================== 664 665ICO is an image file format used for small images (usually icons) on 666Windows. ICO files use the file extension :file:`.ico`. 667 668 669.. list-table:: 670 :widths: 30 10 65 671 :header-rows: 1 672 673 * - ImageSpec Attribute 674 - Type 675 - ICO header data or explanation 676 * - ``oiio:BitsPerSample`` 677 - int 678 - the true bits per sample in the ICO file. 679 * - ``ico:PNG`` 680 - int 681 - if nonzero, will cause the ICO to be written out using PNG format. 682 683**Limitations** 684 685* ICO only supports UINT8 and UINT16 formats; all output images will 686 be silently converted to one of these. 687* ICO only supports *small* images, up to 256 x 256. 688 Requests to write larger images will fail their ``open()`` call. 689 690 691 692| 693 694.. _sec-bundledplugins-iff: 695 696IFF 697=============================================== 698 699IFF files are used by Autodesk Maya and use the file extension :file:`.iff`. 700 701.. list-table:: 702 :widths: 30 10 65 703 :header-rows: 1 704 705 * - ImageSpec Attribute 706 - Type 707 - IFF header data or explanation 708 * - ``Artist`` 709 - string 710 - The IFF "author" 711 * - ``DateTime`` 712 - string 713 - Creation date/time 714 * - ``compression`` 715 - string 716 - The compression type (``"none"`` or ``"rle"`` [default]) 717 * - ``oiio:BitsPerSample`` 718 - int 719 - the true bits per sample of the IFF file. 720 721 722 723| 724 725.. _sec-bundledplugins-jpeg: 726 727JPEG 728=============================================== 729 730JPEG (Joint Photographic Experts Group), or more properly the JFIF file 731format containing JPEG-compressed pixel data, is one of the most popular 732file formats on the Internet, with applications, and from digital 733cameras, scanners, and other image acquisition devices. JPEG/JFIF files 734usually have the file extension :file:`.jpg`, :file:`.jpe`, :file:`.jpeg`, 735:file:`.jif`, :file:`.jfif`, or :file:`.jfi`. The JFIF file format is 736described by http://www.w3.org/Graphics/JPEG/jfif3.pdf. 737 738Although we strive to support JPEG/JFIF because it is so widely used, we 739acknowledge that it is a poor format for high-end work: it supports only 7401- and 3-channel images, has no support for alpha channels, no support 741for high dynamic range or even 16 bit integer pixel data, by convention 742stores sRGB data and is ill-suited to linear color spaces, and does not 743support multiple subimages or MIPmap levels. There are newer formats 744also blessed by the Joint Photographic Experts Group that attempt to 745address some of these issues, such as JPEG-2000, but these do not have 746anywhere near the acceptance of the original JPEG/JFIF format. 747 748 749 750.. list-table:: 751 :widths: 30 10 65 752 :header-rows: 1 753 754 * - ImageSpec Attribute 755 - Type 756 - JPEG header data or explanation 757 * - ``ImageDescription`` 758 - string 759 - the JPEG Comment field 760 * - ``Orientation`` 761 - int 762 - the image orientation 763 * - ``XResolution``, ``YResolution``, ``ResolutionUnit`` 764 - 765 - The resolution and units from the Exif header 766 * - ``Compression`` 767 - string 768 - If supplied, must be ``"jpeg"``, but may optionally have a quality 769 value appended, like ``"jpeg:90"``. Quality can be 1-100, with 100 770 meaning lossless. 771 * - ``ICCProfile`` 772 - uint8[] 773 - The ICC color profile 774 * - ``jpeg:subsampling`` 775 - string 776 - Describes the chroma subsampling, e.g., ``"4:2:0"`` (the default), 777 ``"4:4:4"``, ``"4:2:2"``, ``"4:2:1"``. 778 * - ``Exif:*``, ``IPTC:*``, ``XMP:*``, ``GPS:*`` 779 - 780 - Extensive Exif, IPTC, XMP, and GPS data are supported by the 781 reader/writer, and you should assume that nearly everything described 782 Appendix :ref:`chap-stdmetadata` is properly translated when using 783 JPEG files. 784 785**Configuration settings for JPEG output** 786 787When opening a JPEG ImageOutput, the following special metadata tokens 788control aspects of the writing itself: 789 790.. list-table:: 791 :widths: 30 10 65 792 :header-rows: 1 793 794 * - Output Configuration Attribute 795 - Type 796 - Meaning 797 * - ``oiio:dither`` 798 - int 799 - If nonzero and outputting UINT8 values in the file, will add a small 800 amount of random dither to combat the appearance of banding. 801 * - ``oiio:ioproxy`` 802 - ptr 803 - Pointer to a ``Filesystem::IOProxy`` that will handle the I/O, for 804 example by reading from memory rather than the file system. 805 * - ``jpeg:progressive`` 806 - int 807 - If nonzero, will write a progressive JPEG file. 808 809 810**Custom I/O Overrides** 811 812JPEG input (but, currently, not output) supports the "custom I/O" feature 813via the `ImageInput::set_ioproxy()` method and the special 814``"oiio:ioproxy"`` attributes (see Section :ref:`sec-imageinput-ioproxy`). 815 816**Limitations** 817 818* JPEG/JFIF only supports 1- (grayscale) and 3-channel (RGB) images. As a 819 special case, OpenImageIO's JPEG writer will accept n-channel image 820 data, but will only output the first 3 channels (if n >= 3) or the first 821 channel (if n <= 2), silently drop any extra channels from the output. 822* Since JPEG/JFIF only supports 8 bits per channel, OpenImageIO's 823 JPEG/JFIF writer will silently convert to UINT8 upon output, 824 regardless of requests to the contrary from the calling program. 825* OpenImageIO's JPEG/JFIF reader and writer always operate in scanline 826 mode and do not support tiled image input or output. 827 828 829 830| 831 832.. _sec-bundledplugins-jpeg2000: 833 834JPEG-2000 835=============================================== 836 837JPEG-2000 is a successor to the popular JPEG/JFIF format, that supports 838better (wavelet) compression and a number of other extensions. It's geared 839toward photography. JPEG-2000 files use the file extensions :file:`.jp2` or 840:file:`.j2k`. The official JPEG-2000 format specification and other helpful 841info may be found at: http://www.jpeg.org/JPEG2000.htm 842 843JPEG-2000 is not yet widely used, so OpenImageIO's support of it is 844preliminary. In particular, we are not yet very good at handling the 845metadata robustly. 846 847 848.. list-table:: 849 :widths: 30 10 65 850 :header-rows: 1 851 852 * - ImageSpec Attribute 853 - Type 854 - JPEG-2000 header data or explanation 855 * - ``jpeg2000:streamformat`` 856 - string 857 - specifies the JPEG-2000 stream format (``"none"`` or ``"jpc"``) 858 859 860 861 862| 863 864.. _sec-bundledplugins-ffmpeg: 865 866Movie formats (using ffmpeg) 867=============================================== 868 869The :program:`ffmpeg`-based reader is capable of reading the individual 870frames from a variety of movie file formats, including: 871 872 873===================== ==================================================== 874Format Extensions 875===================== ==================================================== 876AVI :file:`.avi` 877QuickTime :file:`.qt`, :file:`.mov` 878MPEG-4 :file:`.mp4`, :file:`.m4a`, :file:`.m4v` 8793GPP files :file:`.3gp`, :file:`.3g2` 880Motion JPEG-2000 :file:`.mj2` 881Apple M4V :file:`.m4v` 882MPEG-1/MPEG-2 :file:`.mpg` 883===================== ==================================================== 884 885 886Currently, these files may only be read. Write support may be added in a 887future release. Also, currently, these files simply look to OIIO like 888simple multi-image files and not much support is given to the fact that they 889are technically *movies* (for example, there is no support for reading audio 890information). 891 892Some special attributes are used for movie files: 893 894 895.. list-table:: 896 :widths: 30 10 65 897 :header-rows: 1 898 899 * - ImageSpec Attribute 900 - Type 901 - Header data or explanation 902 * - ``oiio:Movie`` 903 - int 904 - Nonzero value for movie files 905 * - ``oiio:subimages`` 906 - int 907 - The number of frames in the movie, positive if it can be known 908 without reading the entire file. Zero or not present if the number 909 of frames cannot be determinend from reading from just the file 910 header. 911 * - ``FramesPerSecond`` 912 - int[2] (rational) 913 - Frames per second 914 915 916 917| 918 919.. _sec-bundledplugins-null: 920 921Null format 922=============================================== 923 924The ``nullptr`` reader/writer is a mock-up that does not perform any actual 925I/O. The reader just returns constant-colored pixels, and the writer just 926returns directly without saving any data. This has several uses: 927 928* Benchmarking, if you want to have OIIO's input or output truly take as 929 close to no time whatsoever. 930 931* "Dry run" of applications where you don't want it to produce any real 932 output (akin to a Unix command that you redirect output to 933 :file:`/dev/null`). 934 935* Make "fake" input that looks like a file, but the file doesn't exist (if 936 you are happy with constant-colored pixels). 937 938The filename allows a REST-ful syntax, where you can append modifiers 939that specify things like resolution (of the non-existent file), etc. 940For example:: 941 942 foo.null?RES=640x480&CHANNELS=3 943 944would specify a null file with resolution 640x480 and 3 channels. 945Token/value pairs accepted are: 946 947===================== ==================================================== 948``RES=1024x1024`` Set resolution (3D example: 256x256x100) 949``CHANNELS=4`` Set number of channels 950``TILES=64x64`` Makes it look like a tiled image with tile size 951``TYPE=uint8`` Set the pixel data type 952``PIXEL=r,g,b,...`` Set pixel values (comma separates channel values) 953``TEX=1`` Make it look like a full MIP-mapped texture 954``attrib=value`` Anything else will set metadata 955===================== ==================================================== 956 957 958 959 960| 961 962.. _sec-bundledplugins-openexr: 963 964OpenEXR 965=============================================== 966 967OpenEXR is an image file format developed by Industrial Light & Magic, 968and subsequently open-sourced. OpenEXR's strengths include support of 969high dynamic range imagery (``half`` and `float` pixels), tiled 970images, explicit support of MIPmaps and cubic environment maps, 971arbitrary metadata, and arbitrary numbers of color channels. OpenEXR 972files use the file extension :file:`.exr`. 973The official OpenEXR site is http://www.openexr.com/. 974 975**Attributes** 976 977.. list-table:: 978 :widths: 30 10 65 979 :header-rows: 1 980 981 * - ImageSpec Attribute 982 - Type 983 - OpeneEXR header data or explanation 984 985 * - ``width``, ``height``, ``x``, ``y`` 986 - int 987 - ``dataWindow`` 988 * - ``full_width``, ``full_height``, ``full_x``, ``full_y`` 989 - int 990 - ``displayWindow`` 991 * - ``worldtocamera`` 992 - matrix 993 - worldToCamera 994 * - ``worldtoscreen`` 995 - matrix 996 - worldToScreen 997 * - ``worldtoNDC`` 998 - matrix 999 - worldToNDC 1000 * - ``ImageDescription`` 1001 - string 1002 - comments 1003 * - ``Copyright`` 1004 - string 1005 - owner 1006 * - ``DateTime`` 1007 - string 1008 - capDate 1009 * - ``PixelAspectRatio`` 1010 - float 1011 - pixelAspectRatio 1012 * - ``ExposureTime`` 1013 - float 1014 - expTime 1015 * - ``FNumber`` 1016 - float 1017 - aperture 1018 * - ``compression`` 1019 - string 1020 - one of: ``"none"``, ``"rle"``, ``"zip"``, ``"zips"``, ``"piz"``, 1021 ``"pxr24"``, ``"b44"``, ``"b44a"``, ``"dwaa"``, or ``"dwab"``. If 1022 the writer receives a request for a compression type it does not 1023 recognize or is not supported by the version of OpenEXR on the 1024 system, it will use ``"zip"`` by default. For ``"dwaa"`` and 1025 ``"dwab"``, the dwaCompressionLevel may be optionally appended to the 1026 compression name after a colon, like this: ``"dwaa:200"``. (The 1027 default DWA compression value is 45.) 1028 * - ``textureformat`` 1029 - string 1030 - ``"Plain Texture"`` for MIP-mapped OpenEXR files, ``"CubeFace 1031 Environment"`` or ``"Latlong Environment"`` for OpenEXR environment 1032 maps. Non-environment non-MIP-mapped OpenEXR files will not set this 1033 attribute. 1034 * - ``wrapmodes`` 1035 - string 1036 - wrapmodes 1037 * - ``FramesPerSecond`` 1038 - int[2] 1039 - Frames per second playback rate (vecsemantics will be marked as RATIONAL) 1040 * - ``captureRate`` 1041 - int[2] 1042 - Frames per second capture rate (vecsemantics will be marked as RATIONAL) 1043 * - ``smpte:TimeCode`` 1044 - int[2] 1045 - SMPTE time code (vecsemantics will be marked as TIMECODE) 1046 * - ``smpte:KeyCode`` 1047 - int[7] 1048 - SMPTE key code (vecsemantics will be marked as KEYCODE) 1049 * - ``openexr:lineOrder`` 1050 - string 1051 - OpenEXR lineOrder attribute: ``"increasingY"``, ``"randomY"``, or 1052 ``"decreasingY"``. 1053 * - ``openexr:roundingmode`` 1054 - int 1055 - the MIPmap rounding mode of the file. 1056 * - ``openexr:dwaCompressionLevel`` 1057 - float 1058 - compression level for dwaa or dwab compression (default: 45.0). 1059 * - *other* 1060 - 1061 - All other attributes will be added to the ImageSpec by their name and 1062 apparent type. 1063 1064 1065**Configuration settings for OpenEXR input** 1066 1067When opening an OpenEXR ImageInput with a *configuration* (see 1068Section :ref:`sec-inputwithconfig`), the following special configuration 1069attributes are supported: 1070 1071.. list-table:: 1072 :widths: 30 10 65 1073 :header-rows: 1 1074 1075 * - Input Configuration Attribute 1076 - Type 1077 - Meaning 1078 * - ``oiio:ioproxy`` 1079 - ptr 1080 - Pointer to a ``Filesystem::IOProxy`` that will handle the I/O, for 1081 example by reading from memory rather than the file system. 1082 * - ``oiio:missingcolor`` 1083 - float *or* string 1084 - Either an array of float values or a string holding a comma-separated 1085 list of values, if present this is a request to use this color for 1086 pixels of any missing tiles or scanlines, rather than considering a 1087 tile/scanline read failure to be an error. This can be helpful when 1088 intentionally reading partially-written or incomplete files (such as 1089 an in-progress render). 1090 1091**Configuration settings for OpenEXR output** 1092 1093When opening an OpenEXR ImageOutput, the following special metadata tokens 1094control aspects of the writing itself: 1095 1096.. list-table:: 1097 :widths: 30 10 65 1098 :header-rows: 1 1099 1100 * - Output Configuration Attribute 1101 - Type 1102 - Meaning 1103 * - ``oiio:RawColor`` 1104 - int 1105 - If nonzero, writing images with non-RGB color models (such as YCbCr) 1106 will keep unaltered pixel values (versus the default OIIO behavior 1107 of automatically converting from RGB to the designated color space 1108 as the pixels are written). 1109 * - ``oiio:ioproxy`` 1110 - ptr 1111 - Pointer to a ``Filesystem::IOProxy`` that will handle the I/O, for 1112 example by writing to a memory buffer. 1113 1114 1115**Custom I/O Overrides** 1116 1117OpenEXR input and output both support the "custom I/O" feature via the 1118special ``"oiio:ioproxy"`` attributes (see Sections 1119:ref:`sec-imageoutput-ioproxy` and :ref:`sec-imageinput-ioproxy`) as well as 1120the `set_ioproxy()` methods. 1121 1122**A note on channel names** 1123 1124The underlying OpenEXR library (:file:`libIlmImf`) always saves channels 1125into lexicographic order, so the channel order on disk (and thus when read!) 1126will NOT match the order when the image was created. 1127 1128But in order to adhere to OIIO's convention that RGBAZ will always be the 1129first channels (if they exist), OIIO's OpenEXR reader will automatically 1130reorder just those channels to appear at the front and in that order. All 1131other channel names will remain in their relative order as presented to OIIO 1132by :file:`libIlmImf`. 1133 1134**Limitations** 1135 1136* The OpenEXR format only supports HALF, FLOAT, and UINT32 pixel 1137 data. OpenImageIO's OpenEXR writer will silently convert data in formats 1138 (including the common UINT8 and UINT16 cases) to HALF data for output. 1139 1140 1141 1142| 1143 1144.. _sec-bundledplugins-openvdb: 1145 1146OpenVDB 1147=============================================== 1148 1149OpenVDB is an open-source volume data file format. OpenVDB files commonly 1150use the extension :file:`.vdb`. The official OpenVDB site is: 1151http://www.openvdb.org/ Currently, OpenImageIO only reads OpenVDB files, and 1152does not write them. 1153 1154Volumes are comprised of multiple *layers* (which appear to OpenImageIO as 1155subimages). Each layer/subimage may have a different name, resolution, and 1156coordinate mapping. Layers may be scalar (1 channel) or vector (3 channel) 1157fields, and the voxel data are always `float`. OpenVDB files always 1158report as tiled, using the leaf dimension size. 1159 1160.. list-table:: 1161 :widths: 30 10 65 1162 :header-rows: 1 1163 1164 * - ImageSpec Attribute 1165 - Type 1166 - OpenVDB header data or explanation 1167 * - ``ImageDescription`` 1168 - string 1169 - Description of image element 1170 * - ``oiio:subimagename`` 1171 - string 1172 - unique layer name 1173 * - ``openvdb:indextoworld`` 1174 - matrix of doubles 1175 - conversion of voxel index to world space coordinates. 1176 * - ``openvdb:worldtoindex`` 1177 - matrix of doubles 1178 - conversion of world space coordinates to voxel index. 1179 * - ``worldtocamera`` 1180 - matrix 1181 - World-to-local coordinate mapping. 1182 1183 1184 1185| 1186 1187.. _sec-bundledplugins-png: 1188 1189PNG 1190=============================================== 1191 1192PNG (Portable Network Graphics) is an image file format developed by the 1193open source community as an alternative to the GIF, after Unisys started 1194enforcing patents allegedly covering techniques necessary to use GIF. PNG 1195files use the file extension :file:`.png`. 1196 1197**Attributes** 1198 1199.. list-table:: 1200 :widths: 30 10 65 1201 :header-rows: 1 1202 1203 * - ImageSpec Attribute 1204 - Type 1205 - PNG header data or explanation 1206 * - ``ImageDescription`` 1207 - string 1208 - Description 1209 * - ``Artist`` 1210 - string 1211 - Author 1212 * - ``DocumentName`` 1213 - string 1214 - Title 1215 * - ``DateTime`` 1216 - string 1217 - the timestamp in the PNG header 1218 * - ``PixelAspectRatio`` 1219 - float 1220 - pixel aspect ratio 1221 * - ``XResolution``, ``YResolution``, ``ResolutionUnit`` 1222 - 1223 - resolution and units from the PNG header. 1224 * - ``oiio:ColorSpace`` 1225 - string 1226 - Color space (see Section :ref:`sec-metadata-color`). 1227 * - ``oiio:Gamma`` 1228 - float 1229 - the gamma correction value (if specified). 1230 * - ``ICCProfile`` 1231 - uint8[] 1232 - The ICC color profile 1233 1234**Configuration settings for PNG input** 1235 1236When opening an PNG ImageInput with a *configuration* (see 1237Section :ref:`sec-inputwithconfig`), the following special configuration 1238attributes are supported: 1239 1240.. list-table:: 1241 :widths: 30 10 65 1242 :header-rows: 1 1243 1244 * - Input Configuration Attribute 1245 - Type 1246 - Meaning 1247 * - ``oiio:UnassociatedAlpha`` 1248 - int 1249 - If nonzero, will leave alpha unassociated (versus the default of 1250 premultiplying color channels by alpha if the alpha channel is 1251 unassociated). 1252 * - ``oiio:ioproxy`` 1253 - ptr 1254 - Pointer to a ``Filesystem::IOProxy`` that will handle the I/O, for 1255 example by reading from memory rather than the file system. 1256 1257**Configuration settings for PNG output** 1258 1259When opening an PNG ImageOutput, the following special metadata tokens 1260control aspects of the writing itself: 1261 1262.. list-table:: 1263 :widths: 30 10 65 1264 :header-rows: 1 1265 1266 * - Output Configuration Attribute 1267 - Type 1268 - Meaning 1269 * - ``png:compressionLevel`` 1270 - int 1271 - Compression level for zip/deflate compression, on a scale from 0 1272 (fastest, minimal compression) to 9 (slowest, maximal compression). 1273 The default is 6. PNG compression is always lossless. 1274 * - ``png:filter`` 1275 - int 1276 - Controls the "row filters" that prepare the image for optimal 1277 compression. The default is 0 (``PNG_NO_FILTERS``), but other values 1278 (which may be "or-ed" or summed to combine their effects) are 8 1279 (``PNG_FILTER_NONE``), 16 (``PNG_FILTER_SUB``), 32 1280 (``PNG_FILTER_UP``), 64 (``PNG_FILTER_AVG``), or 128 1281 (``PNG_FILTER_PAETH``). 1282 * - ``oiio:ioproxy`` 1283 - ptr 1284 - Pointer to a ``Filesystem::IOProxy`` that will handle the I/O, for 1285 example by writing to a memory buffer. 1286 * - ``oiio:dither`` 1287 - int 1288 - If nonzero and outputting UINT8 values in the file, will add a small 1289 amount of random dither to combat the appearance of banding 1290 1291**Custom I/O Overrides** 1292 1293PNG input and output both support the "custom I/O" feature via the special 1294``"oiio:ioproxy"`` attributes (see Sections :ref:`sec-imageoutput-ioproxy` 1295and :ref:`sec-imageinput-ioproxy`) as well as the `set_ioproxy()` methods. 1296 1297 1298 1299**Limitations** 1300 1301* PNG stupidly specifies that any alpha channel is "unassociated" (i.e., 1302 that the color channels are not "premultiplied" by alpha). This is a 1303 disaster, since it results in bad loss of precision for alpha image 1304 compositing, and even makes it impossible to properly represent certain 1305 additive glows and other desirable pixel values. OpenImageIO automatically 1306 associates alpha (i.e., multiplies colors by alpha) upon input and 1307 deassociates alpha (divides colors by alpha) upon output in order to 1308 properly conform to the OIIO convention (and common sense) that all pixel 1309 values passed through the OIIO APIs should use associated alpha. 1310 1311* PNG only supports UINT8 and UINT16 output; other requested formats will be 1312 automatically converted to one of these. 1313 1314 1315 1316| 1317 1318.. _sec-bundledplugins-pnm: 1319 1320PNM / Netpbm 1321=============================================== 1322 1323The Netpbm project, a.k.a. PNM (portable "any" map) defines PBM, PGM, 1324and PPM (portable bitmap, portable graymap, portable pixmap) files. 1325Without loss of generality, we will refer to these all collectively as 1326"PNM." These files have extensions :file:`.pbm`, :file:`.pgm`, and 1327:file:`.ppm` and customarily correspond to bi-level bitmaps, 1-channel 1328grayscale, and 3-channel RGB files, respectively, or :file:`.pnm` for 1329those who reject the nonsense about naming the files depending on the 1330number of channels and bitdepth. 1331 1332PNM files are not much good for anything, but because of their 1333historical significance and extreme simplicity (that causes many 1334"amateur" programs to write images in these formats), OpenImageIO 1335supports them. PNM files do not support floating point images, anything 1336other than 1 or 3 channels, no tiles, no multi-image, no MIPmapping. 1337It's not a smart choice unless you are sending your images back to the 13381980's via a time machine. 1339 1340.. list-table:: 1341 :widths: 30 10 65 1342 :header-rows: 1 1343 1344 * - ImageSpec Attribute 1345 - Type 1346 - PNM header data or explanation 1347 * - ``oiio:BitsPerSample`` 1348 - int 1349 - The true bits per sample of the file (1 for true PBM files, even 1350 though OIIO will report the ``format`` as UINT8). 1351 * - ``pnm:binary`` 1352 - int 1353 - nonzero if the file itself used the PNM binary format, 0 if it used 1354 ASCII. The PNM writer honors this attribute in the ImageSpec to 1355 determine whether to write an ASCII or binary file. 1356 1357 1358 1359| 1360 1361.. _sec-bundledplugins-psd: 1362 1363PSD 1364=============================================== 1365 1366PSD is the file format used for storing Adobe PhotoShop images. OpenImageIO 1367provides limited read abilities for PSD, but not currently the ability to 1368write PSD files. 1369 1370**Configuration settings for PSD input** 1371 1372When opening an ImageInput with a *configuration* (see 1373Section :ref:`sec-inputwithconfig`), the following special configuration 1374options are supported: 1375 1376.. list-table:: 1377 :widths: 30 10 65 1378 :header-rows: 1 1379 1380 * - Input Configuration Attribute 1381 - Type 1382 - Meaning 1383 * - ``oiio:RawColor`` 1384 - int 1385 - If nonzero, reading images with non-RGB color models (such as YCbCr 1386 or CMYK) will return unaltered pixel values (versus the default OIIO 1387 behavior of automatically converting to RGB). 1388 1389Currently, the PSD format reader supports color modes RGB, CMYK, 1390multichannel, grayscale, indexed, and bitmap. It does NOT currenty support 1391Lab or duotone modes. 1392 1393 1394 1395| 1396 1397.. _sec-bundledplugins-ptex: 1398 1399Ptex 1400=============================================== 1401 1402Ptex is a special per-face texture format developed by Walt Disney 1403Feature Animation. The format and software to read/write it are open 1404source, and available from http://ptex.us/. Ptex files commonly 1405use the file extension :file:`.ptex`. 1406 1407OpenImageIO's support of Ptex is still incomplete. We can read pixels from 1408Ptex files, but the TextureSystem doesn't properly filter across face 1409boundaries when using it as a texture. OpenImageIO currently does not write 1410Ptex files at all. 1411 1412 1413.. list-table:: 1414 :widths: 30 10 65 1415 :header-rows: 1 1416 1417 * - ImageSpec Attribute 1418 - Type 1419 - Ptex header data or explanation 1420 * - ``ptex:meshType`` 1421 - string 1422 - the mesh type, either ``"triangle"`` or ``"quad"``. 1423 * - ``ptex:hasEdits`` 1424 - int 1425 - nonzero if the Ptex file has edits. 1426 * - ``wrapmode`` 1427 - string 1428 - the wrap mode as specified by the Ptex file. 1429 * - *other* 1430 - 1431 - Any other arbitrary metadata in the Ptex file will be stored directly 1432 as attributes in the ImageSpec. 1433 1434 1435 1436| 1437 1438.. _sec-bundledplugins-raw: 1439 1440RAW digital camera files 1441=============================================== 1442 1443A variety of digital camera "raw" formats are supported via this 1444plugin that is based on the LibRaw library (http://www.libraw.org/). 1445 1446**Configuration settings for RAW input** 1447 1448When opening an ImageInput with a *configuration* (see 1449Section :ref:`sec-inputwithconfig`), the following special configuration 1450options are supported: 1451 1452.. list-table:: 1453 :widths: 30 10 65 1454 :header-rows: 1 1455 1456 * - Input Configuration Attribute 1457 - Type 1458 - Meaning 1459 * - ``raw:auto_bright`` 1460 - int 1461 - If nonzero, will use libraw's exposure correction. (Default: 0) 1462 * - ``raw:use_camera_wb`` 1463 - int 1464 - If 1, use libraw's camera white balance adjustment. (Default: 1) 1465 * - ``raw:use_camera_matrix`` 1466 - int 1467 - Whether to use the embedded color profile, if it's present: 0 = 1468 never, 1 (default) = only for DNG files, 3 = always. 1469 * - ``raw:adjust_maximum_thr`` 1470 - float 1471 - If nonzero, auto-adjusting maximum value. (Default:0.0) 1472 * - ``raw:user_sat`` 1473 - int 1474 - If nonzero, sets the camera maximum value that will be normalized to 1475 appear saturated. (Default: 0) 1476 * - ``raw:aber`` 1477 - float[2] 1478 - Red and blue scale factors for chromatic aberration correction when 1479 decoding the raw image. The default (1,1) means to perform no 1480 correction. This is an overall spatial scale, sensible values will be 1481 very close to 1.0. 1482 * - ``raw:half_size`` 1483 - int 1484 - If nonzero, outputs the image in half size. (Default: 0) 1485 * - ``raw:user_mul`` 1486 - float[4] 1487 - Sets user white balance coefficients. Only applies if ``raw:use_camera_wb`` 1488 is not equal to 0. 1489 * - ``raw:ColorSpace`` 1490 - string 1491 - Which color primaries to use: ``raw``, ``sRGB``, ``Adobe``, ``Wide``, 1492 ``ProPhoto``, ``ACES``, ``XYZ``. (Default: ``sRGB``) 1493 * - ``raw:Exposure`` 1494 - float 1495 - Amount of exposure before de-mosaicing, from 0.25 (2 stop darken) to 1496 8 (3 stop brighten). (Default: 0, meaning no correction.) 1497 * - ``raw:Demosaic`` 1498 - string 1499 - Force a demosaicing algorithm: ``linear``, ``VNG``, ``PPG``, ``AHD`` 1500 (default), ``DCB``, ``AHD-Mod``, ``AFD``, ``VCD``, ``Mixed``, 1501 ``LMMSE``, ``AMaZE``, ``DHT``, ``AAHD``, ``none``. 1502 * - ``raw:HighlightMode`` 1503 - int 1504 - Set libraw highlight mode processing: 0 = clip, 1 = unclip, 2 = 1505 blend, 3+ = rebuild. (Default: 0.) 1506 * - ``raw:user_flip`` 1507 - int 1508 - Set libraw user flip value : -1 ignored, other values are between [0; 8] with the same 1509 definition than the Exif orientation code. 1510 1511 1512 1513 1514| 1515 1516.. _sec-bundledplugins-rla: 1517 1518RLA 1519=============================================== 1520 1521RLA (Run-Length encoded, version A) is an early CGI renderer output format, 1522originating from Wavefront Advanced Visualizer and used primarily by 1523software developed at Wavefront. RLA files commonly use the file extension 1524:file:`.rla`. 1525 1526.. list-table:: 1527 :widths: 30 10 65 1528 :header-rows: 1 1529 1530 * - ImageSpec Attribute 1531 - Type 1532 - RLA header data or explanation 1533 * - ``width``, ``height``, ``x``, ``y`` 1534 - int 1535 - RLA "active/viewable" window. 1536 * - ``full_width``, ``full_height``, ``full_x``, 1537 ``full_y`` 1538 - int 1539 - RLA "full" window. 1540 * - ``rla:FrameNumber`` 1541 - int 1542 - frame sequence number. 1543 * - ``rla:Revision`` 1544 - int 1545 - file format revision number, currently ``0xFFFE``. 1546 * - ``rla:JobNumber`` 1547 - int 1548 - job number ID of the file. 1549 * - ``rla:FieldRendered`` 1550 - int 1551 - whether the image is a field-rendered (interlaced) one ``0`` for false, non-zero for true. 1552 * - ``rla:FileName`` 1553 - string 1554 - name under which the file was orignally saved. 1555 * - ``ImageDescription`` 1556 - string 1557 - RLA "Description" of the image. 1558 * - ``Software`` 1559 - string 1560 - name of software used to save the image. 1561 * - ``HostComputer`` 1562 - string 1563 - name of machine used to save the image. 1564 * - ``Artist`` 1565 - string 1566 - RLA "UserName": logon name of user who saved the image. 1567 * - ``rla:Aspect`` 1568 - string 1569 - aspect format description string. 1570 * - ``rla:ColorChannel`` 1571 - string 1572 - textual description of color channel data format (usually ``rgb``). 1573 * - ``rla:Time`` 1574 - string 1575 - description (format not standardized) of amount of time spent on creating the image. 1576 * - ``rla:Filter`` 1577 - string 1578 - name of post-processing filter applied to the image. 1579 * - ``rla:AuxData`` 1580 - string 1581 - textual description of auxiliary channel data format. 1582 * - ``rla:AspectRatio`` 1583 - float 1584 - image aspect ratio. 1585 * - ``rla:RedChroma`` 1586 - vec2 or vec3 of floats 1587 - red point XY (vec2) or XYZ (vec3) coordinates. 1588 * - ``rla:GreenChroma`` 1589 - vec2 or vec3 of floats 1590 - green point XY (vec2) or XYZ (vec3) coordinates. 1591 * - ``rla:BlueChroma`` 1592 - vec2 or vec3 of floats 1593 - blue point XY (vec2) or XYZ (vec3) coordinates. 1594 * - ``rla:WhitePoint`` 1595 - vec2 or vec3 of floats 1596 - white point XY (vec2) or XYZ (vec3) coordinates. 1597 * - ``oiio:ColorSpace`` 1598 - string 1599 - Color space (see Section :ref:`sec-metadata-color`). 1600 * - ``oiio:Gamma`` 1601 - float 1602 - the gamma correction value (if specified). 1603 1604 1605**Limitations** 1606 1607* OpenImageIO will only write a single image to each file, multiple 1608 subimages are not supported by the writer (but are supported by the 1609 reader). 1610 1611 1612 1613| 1614 1615.. _sec-bundledplugins-sgi: 1616 1617SGI 1618=============================================== 1619 1620The SGI image format was a simple raster format used long ago on SGI 1621machines. SGI files use the file extensions ``sgi``, ``rgb``, ``rgba``, 1622``bw``, `int`, and ``inta``. 1623 1624The SGI format is sometimes used for legacy apps, but has little merit 1625otherwise: no support for tiles, no MIPmaps, no multi-subimage, only 8- and 162616-bit integer pixels (no floating point), only 1-4 channels. 1627 1628 1629.. list-table:: 1630 :widths: 30 10 65 1631 :header-rows: 1 1632 1633 * - ImageSpec Attribute 1634 - Type 1635 - SGI header data or explanation 1636 * - ``compression`` 1637 - string 1638 - The compression of the SGI file (``rle``, if RLE compression is used). 1639 * - ``ImageDescription`` 1640 - string 1641 - Image name. 1642 1643 1644 1645| 1646 1647.. _sec-bundledplugins-pic: 1648 1649Softimage PIC 1650=============================================== 1651 1652Softimage PIC is an image file format used by the SoftImage 3D application, 1653and some other programs that needed to be compatible with it. Softimage 1654files use the file extension :file:`.pic`. 1655 1656The Softimage PIC format is sometimes used for legacy apps, but has little 1657merit otherwise, so currently OpenImageIO only reads Softimage files and is 1658unable to write them. 1659 1660.. list-table:: 1661 :widths: 30 10 65 1662 :header-rows: 1 1663 1664 * - ImageSpec Attribute 1665 - Type 1666 - PIC header data or explanation 1667 * - ``compression`` 1668 - string 1669 - The compression of the SGI file (``rle``, if RLE compression is used). 1670 * - ``ImageDescription`` 1671 - string 1672 - Comment 1673 * - ``oiio:BitsPerSample`` 1674 - int 1675 - the true bits per sample of the PIC file. 1676 1677 1678 1679| 1680 1681.. _sec-bundledplugins-targa: 1682 1683Targa 1684=============================================== 1685 1686Targa (a.k.a. Truevision TGA) is an image file format with little merit 1687except that it is very simple and is used by many legacy applications. Targa 1688files use the file extension :file:`.tga`, or, much more rarely, 1689:file:`.tpic`. The official Targa format specification may be found at: 1690http://www.dca.fee.unicamp.br/~martino/disciplinas/ea978/tgaffs.pdf 1691 1692 1693.. list-table:: 1694 :widths: 30 10 65 1695 :header-rows: 1 1696 1697 * - ImageSpec Attribute 1698 - Type 1699 - TGA header data or explanation 1700 * - ``ImageDescription`` 1701 - string 1702 - Comment 1703 * - ``Artist`` 1704 - string 1705 - author 1706 * - ``DocumentName`` 1707 - string 1708 - job name/ID 1709 * - ``Software`` 1710 - string 1711 - software name 1712 * - ``DateTime`` 1713 - string 1714 - TGA time stamp 1715 * - ``targa:JobTime`` 1716 - string 1717 - TGA "job time." 1718 * - ``compression`` 1719 - string 1720 - values of ``none`` and ``rle`` are supported. The writer will use 1721 RLE compression if any unknown compression methods are requested. 1722 * - ``targa:ImageID`` 1723 - string 1724 - Image ID 1725 * - ``PixelAspectRatio`` 1726 - float 1727 - pixel aspect ratio 1728 * - ``oiio:BitsPerSample`` 1729 - int 1730 - the true bits per sample of the PIC file. 1731 * - ``oiio:ColorSpace`` 1732 - string 1733 - Color space (see Section :ref:`sec-metadata-color`). 1734 * - ``oiio:Gamma`` 1735 - float 1736 - the gamma correction value (if specified). 1737 1738 1739If the TGA file contains a thumbnail, its dimensions will be stored in the 1740attributes ``"thumbnail_width"``, ``"thumbnail_height"``, and 1741``"thumbnail_nchannels"``, and the thumbnail pixels themselves will be 1742stored in ``"thumbnail_image"`` (as an array of UINT8 values, whose length 1743is the total number of channel samples in the thumbnail). 1744 1745**Limitations** 1746 1747* The Targa reader reserves enough memory for the entire image. Therefore it 1748 is not a good choice for high-performance image use such as would be used 1749 for ImageCache or TextureSystem. 1750* Targa files only support 8- and 16-bit unsigned integers (no signed, 1751 floating point, or HDR capabilities); the OpenImageIO TGA writer will 1752 silently convert all output images to UINT8 (except if UINT16 is 1753 explicitly requested). 1754* Targa only supports grayscale, RGB, and RGBA; the OpenImageIO TGA writer 1755 will fail its call to ``open()`` if it is asked create a file with more 1756 than 4 color channels. 1757 1758 1759| 1760 1761.. _sec-bundledplugins-term: 1762 1763Term (Terminal) 1764=============================================== 1765 1766This *experimental* output-only "format" is actually a procedural output 1767that writes a low-res representation of the image to the console output. It 1768requires a terminal application that supports Unicode and 24 bit color 1769extensions. 1770 1771The `term` ImageOutput supports the following special metadata tokens to 1772control aspects of the writing itself: 1773 1774.. list-table:: 1775 :widths: 30 10 65 1776 :header-rows: 1 1777 1778 * - Output Configuration Attribute 1779 - Type 1780 - Meaning 1781 * - ``term:method`` 1782 - string 1783 - May be one of `iterm2`, `24bit` (default), `24bit-space`, `256color`, 1784 or `dither`. 1785 * - ``term:fit`` 1786 - int 1787 - If 1 (the default), the image will be resized to fit on the console 1788 window. 1789 1790 1791 1792The `iterm2` mode is the best quality and is the default mode when actually 1793running on a Mac and launching using iTerm2 as the terminal. This mode uses 1794iTerm2's nonstandard extension to directly output an pixel array to be 1795visible in the terminal. 1796 1797The default in other circumstances is the `24bit` mode, which displays two 1798approximately square pixels vertically in each character cell, by outputting 1799the Unicode "upper half block" glyph (`\u2508`) with the foreground color 1800set to the top pixel's color and the background color set to the bottom 1801pixel's color. 1802 1803If this doesn't look right, or your terminal doesn't support Unicode, 1804the `24bit-space` is an alternate mode that displays one elongated pixel 1805in each character cell, writing a space character with the correct color. 1806 1807There's also a `256color` method that just uses the 6x6x6 color space in the 1808256 color palette -- which looks horrible -- and an experimental `dither` 1809which does a half-assed Floyd-Steinberg dithering, horizontally only, and 1810frankly is not an improvement unless you squint really hard. These may 1811change or be eliminted in the future. 1812 1813In all cases, the image will automatically be resized to fit in the terminal 1814and keep approximately the correct aspect ratio, as well as converted to 1815sRGB so it looks kinda ok. 1816 1817| 1818 1819.. _sec-bundledplugins-tiff: 1820 1821TIFF 1822=============================================== 1823 1824TIFF (Tagged Image File Format) is a flexible file format created by Aldus, 1825now controlled by Adobe. TIFF supports nearly everything anybody could want 1826in an image format (and has extactly the complexity you would expect from 1827such a requirement). TIFF files commonly use the file extensions 1828:file:`.tif` or, :file:`.tiff`. Additionally, OpenImageIO associates the 1829following extensions with TIFF files by default: :file:`.tx`, :file:`.env`, 1830:file:`.sm`, :file:`.vsm`. 1831 1832The official TIFF format specification may be found here: 1833http://partners.adobe.com/public/developer/tiff/index.html The most popular 1834library for reading TIFF directly is :file:`libtiff`, available here: 1835http://www.remotesensing.org/libtiff/ OpenImageIO uses :file:`libtiff` for 1836its TIFF reading/writing. 1837 1838We like TIFF a lot, especially since its complexity can be nicely hidden 1839behind OIIO's simple APIs. It supports a wide variety of data formats 1840(though unfortunately not ``half``), an arbitrary number of channels, tiles 1841and multiple subimages (which makes it our preferred texture format), and a 1842rich set of metadata. 1843 1844OpenImageIO supports the vast majority of TIFF features, including: tiled 1845images (``tiled``) as well as scanline images; multiple subimages per file 1846(``multiimage``); MIPmapping (using multi-subimage; that means you can't use 1847multiimage and MIPmaps simultaneously); data formats 8- 16, and 32 bit 1848integer (both signed and unsigned), and 32- and 64-bit floating point; 1849palette images (will convert to RGB); "miniswhite" photometric mode (will 1850convert to "minisblack"). 1851 1852The TIFF plugin attempts to support all the standard Exif, IPTC, and XMP 1853metadata if present. 1854 1855**Configuration settings for TIFF input** 1856 1857When opening an ImageInput with a *configuration* (see 1858Section :ref:`sec-inputwithconfig`), the following special configuration 1859options are supported: 1860 1861.. list-table:: 1862 :widths: 30 10 65 1863 :header-rows: 1 1864 1865 * - Input Configuration Attribute 1866 - Type 1867 - Meaning 1868 * - ``oiio:UnassociatedAlpha`` 1869 - int 1870 - If nonzero, will leave alpha unassociated (versus the default of 1871 premultiplying color channels by alpha if the alpha channel is 1872 unassociated). 1873 * - ``oiio:RawColor`` 1874 - int 1875 - If nonzero, reading images with non-RGB color models (such as YCbCr) 1876 will return unaltered pixel values (versus the default OIIO behavior 1877 of automatically converting to RGB). 1878 * - ``oiio:ioproxy`` 1879 - ptr 1880 - Pointer to a ``Filesystem::IOProxy`` that will handle the I/O, for 1881 example by reading from memory rather than the file system. 1882 1883**Configuration settings for TIFF output** 1884 1885When opening an ImageOutput, the following special metadata tokens control 1886aspects of the writing itself: 1887 1888 1889.. list-table:: 1890 :widths: 30 10 65 1891 :header-rows: 1 1892 1893 * - Output Configuration Attribute 1894 - Type 1895 - Meaning 1896 * - ``oiio:UnassociatedAlpha`` 1897 - int 1898 - If nonzero, any alpha channel is understood to be unassociated, and 1899 the EXTRASAMPLES tag in the TIFF file will be set to reflect this). 1900 * - ``oiio:BitsPerSample`` 1901 - int 1902 - Requests a rescaling to a specific bits per sample (such as writing 1903 12-bit TIFFs). 1904 * - ``tiff:write_exif`` 1905 - int 1906 - If zero, will not write any Exif data to the TIFF file. (The default 1907 is 1.) 1908 * - ``tiff:half`` 1909 - int 1910 - If nonzero, allow writing TIFF files with `half` (16 bit float) 1911 pixels. The default of 0 will automatically translate to float 1912 pixels, since most non-OIIO applications will not properly read half 1913 TIFF files despite their being legal. 1914 * - ``tiff:ColorSpace`` 1915 - string 1916 - Requests that the file be saved with a non-RGB color spaces. Choices 1917 are ``RGB``, ``CMYK``. % , ``YCbCr``, ``CIELAB``, ``ICCLAB``, 1918 ``ITULAB``. 1919 * - ``tiff:zipquality`` 1920 - int 1921 - A time-vs-quality knob for ``zip`` compression, ranging from 1-9 1922 (default is 6). Higher means compress to less space, but taking 1923 longer to do so. It is strictly a time vs space tradeoff, the quality 1924 is identical (lossless) no matter what the setting. 1925 * - ``tiff:RowsPerStrip`` 1926 - int 1927 - Overrides TIFF scanline rows per strip with a specific request (if 1928 not supplied, OIIO will choose a reasonable default). 1929 1930 1931**TIFF compression modes** 1932 1933The full list of possible TIFF compression mode values are as 1934follows ($ ^*$ indicates that OpenImageIO can write that format, and is not 1935part of the format name): 1936 1937 ``none`` $ ^*$ 1938 ``lzw`` $ ^*$ 1939 ``zip`` $ ^*$ 1940 ``ccitt_t4`` 1941 ``ccitt_t6`` 1942 ``ccittfax3`` 1943 ``ccittfax4`` 1944 ``ccittrle2`` 1945 ``ccittrle`` $ ^*$ 1946 ``dcs`` 1947 ``isojbig`` 1948 ``IT8BL`` 1949 ``IT8CTPAD`` 1950 ``IT8LW`` 1951 ``IT8MP`` 1952 ``jp2000`` 1953 ``jpeg`` $ ^*$ 1954 ``lzma`` 1955 ``next`` 1956 ``ojpeg`` 1957 ``packbits`` $ ^*$ 1958 ``pixarfilm`` 1959 ``pixarlog`` 1960 ``sgilog24`` 1961 ``sgilog`` 1962 ``T43`` 1963 ``T85`` 1964 ``thunderscan`` 1965 1966**Custom I/O Overrides** 1967 1968TIFF input (but, currently, not output) supports the "custom I/O" feature 1969via the `ImageInput::set_ioproxy()` method and the special 1970``"oiio:ioproxy"`` attributes (see Section :ref:`sec-imageinput-ioproxy`). 1971 1972**Limitations** 1973 1974OpenImageIO's TIFF reader and writer have some limitations you should be 1975aware of: 1976 1977* No separate per-channel data formats (not supported by :file:`libtiff`). 1978* Only multiples of 8 bits per pixel may be passed through OpenImageIO's 1979 APIs, e.g., 1-, 2-, and 4-bits per pixel will be passed by OIIO as 8 bit 1980 images; 12 bits per pixel will be passed as 16, etc. But the 1981 ``oiio:BitsPerSample`` attribute in the ImageSpec will correctly report 1982 the original bit depth of the file. Similarly for output, you must pass 8 1983 or 16 bit output, but ``oiio:BitsPerSample`` gives a hint about how you 1984 want it to be when written to the file, and it will try to accommodate the 1985 request (for signed integers, TIFF output can accommodate 2, 4, 8, 10, 12, 1986 and 16 bits). 1987* JPEG compression is limited to 8-bit per channel, 3-channel files. 1988 1989 1990**TIFF Attributes** 1991 1992.. list-table:: 1993 :widths: 30 10 65 1994 :header-rows: 1 1995 1996 * - ImageSpec Attribute 1997 - Type 1998 - TIFF header data or explanation 1999 2000 * - ``ImageSpec::x`` 2001 - int 2002 - XPosition 2003 * - ``ImageSpec::y`` 2004 - int 2005 - YPosition 2006 * - ``ImageSpec::full_width`` 2007 - int 2008 - PIXAR_IMAGEFULLWIDTH 2009 * - ``ImageSpec::full_length`` 2010 - int 2011 - PIXAR_IMAGEFULLLENGTH 2012 * - ``ImageDescription`` 2013 - string 2014 - ImageDescription 2015 * - ``DateTime`` 2016 - string 2017 - DateTime 2018 * - ``Software`` 2019 - string 2020 - Software 2021 * - ``Artist`` 2022 - string 2023 - Artist 2024 * - ``Copyright`` 2025 - string 2026 - Copyright 2027 * - ``Make`` 2028 - string 2029 - Make 2030 * - ``Model`` 2031 - string 2032 - Model 2033 * - ``DocumentName`` 2034 - string 2035 - DocumentName 2036 * - ``HostComputer`` 2037 - string 2038 - HostComputer 2039 * - ``XResultion``, ``YResolution`` 2040 - float 2041 - XResolution, YResolution 2042 * - ``ResolutionUnit`` 2043 - string 2044 - ResolutionUnit (``in`` or ``cm``). 2045 * - ``Orientation`` 2046 - int 2047 - Orientation 2048 * - ``ICCProfile`` 2049 - uint8[] 2050 - The ICC color profile 2051 * - ``textureformat`` 2052 - string 2053 - PIXAR_TEXTUREFORMAT 2054 * - ``wrapmodes`` 2055 - string 2056 - PIXAR_WRAPMODES 2057 * - ``fovcot`` 2058 - float 2059 - PIXAR_FOVCOT 2060 * - ``worldtocamera`` 2061 - matrix 2062 - PIXAR_MATRIX_WORLDTOCAMERA 2063 * - ``worldtoscreen`` 2064 - matrix 2065 - PIXAR_MATRIX_WORLDTOSCREEN 2066 * - ``compression`` 2067 - string 2068 - based on TIFF Compression (one of ``none``, ``lzw``, ``zip``, or others listed above). 2069 * - ``tiff:compression`` 2070 - int 2071 - the original integer code from the TIFF Compression tag. 2072 * - ``tiff:planarconfig`` 2073 - string 2074 - PlanarConfiguration (``separate`` or ``contig``). The OpenImageIO TIFF writer will honor such a request in the ImageSpec. 2075 * - ``tiff:PhotometricInterpretation`` 2076 - int 2077 - Photometric 2078 * - ``tiff:PageName`` 2079 - string 2080 - PageName 2081 * - ``tiff:PageNumber`` 2082 - int 2083 - PageNumber 2084 * - ``tiff:RowsPerStrip`` 2085 - int 2086 - RowsPerStrip 2087 * - ``tiff:subfiletype`` 2088 - int 2089 - SubfileType 2090 * - ``Exif:*`` 2091 - 2092 - A wide variety of EXIF data are honored, and are all prefixed with `Exif`. 2093 * - ``oiio:BitsPerSample`` 2094 - int 2095 - The actual bits per sample in the file (may differ from `ImageSpec::format`). 2096 * - ``oiio:UnassociatedAlpha`` 2097 - int 2098 - Nonzero if the alpha channel contained "unassociated" alpha. 2099 2100 2101 2102 2103 2104 2105| 2106 2107.. _sec-bundledplugins-webp: 2108 2109Webp 2110=============================================== 2111 2112WebP is an image file format developed by Google that is intended to be an 2113open standard for lossy-compressed images for use on the web. 2114 2115.. list-table:: 2116 :widths: 30 10 65 2117 :header-rows: 1 2118 2119 * - ImageSpec Attribute 2120 - Type 2121 - WebP header data or explanation 2122 * - ``oiio:Movie`` 2123 - int 2124 - If nonzero, indicates that it's a multi-subimage file indended to 2125 represent an animation. 2126 * - ``oiio:LoopCount`` 2127 - int 2128 - Number of times the animation should be played (0-65535, 0 stands for infinity). 2129 * - ``gif:LoopCount`` 2130 - int 2131 - Deprecated synonym for ``oiio:LoopCount``. 2132 2133**Limitations** 2134 2135* WebP only supports 3-channel (RGB) or 4-channel (RGBA) images and must 2136 be 8-bit unsigned integer pixel values (uint8). 2137 2138 2139| 2140 2141.. _sec-bundledplugins-zfile: 2142 2143Zfile 2144=============================================== 2145 2146Zfile is a very simple format for writing a depth (*z*) image, originally 2147from Pixar's PhotoRealistic RenderMan but now supported by many other 2148renderers. It's extremely minimal, holding only a width, height, 2149world-to-screen and camera-to-screen matrices, and uncompressed float pixels 2150of the z-buffer. Zfile files use the file extension :file:`.zfile`. 2151 2152 2153.. list-table:: 2154 :widths: 30 10 65 2155 :header-rows: 1 2156 2157 * - ImageSpec Attribute 2158 - Type 2159 - Zfile header data or explanation 2160 * - ``worldtocamera`` 2161 - matrix 2162 - NP 2163 * - ``worldtoscreen`` 2164 - matrix 2165 - Nl 2166 2167