oiiotool(1)
π oiiotool β from the OpenImageIO manual, bestie edition π
okay so. sit down. hydrate. we're doing oiiotool(1) from the OpenImageIO manual and honestly? it's a whole lifestyle. no cap.
β¨ NAME β¨
oiiotool β simple image processing operations π
π SYNOPSIS π
Usage: oiiotool [filename|command]...
π¦ DESCRIPTION π¦
so this program is part of the OpenImageIO tool suite (http://www.openimageio.org) and the detailed documentation ships as a pdf with the OpenImageIO distribution. literally the whole lore is in there.
important usage tips: (read these, fr fr, they're the vibe check of the whole tool π)
- The
oiiotoolcommand line is processed in order, LEFT to RIGHT. no skipping, no shuffling, it's a queue bestie π - The command line consists of image NAMES (
image.tif) and COMMANDS (--over). Commands start with dashes (one or two dashes are equivalent, they're the same thing, we don't gatekeep dash counts). Some commands have required arguments which must follow on the command line. For example, the-ocommand is followed by a filename. π«Ά oiiotoolis STACK-based: naming an image pushes it on the stack, and most commands pop the top image (or sometimes more than one image), perform a calculation, and push the result image back on the stack. For example, the--overcommand pops the top two images off the stack, composites them, then pushes the result back onto the stack. it's giving β¨stack of plates at a buffetβ¨ energy.- Some commands allow one or more optional MODIFIERS in the form
name=value, which are appended directly to the command itself (no spaces), separated by colons:. For example:
oiiotool in.tif --text:x=100:y=200:color=1,0,0 "Hello" -o out.tif
- Using numerical wildcards will run the whole command line on each of several sequentially-named files, for example:
oiiotool fg.#.tif bg.#.tif -over -o comp.#.tif
See the manual for info about subranges, number of digits, etc. π§
- Command line arguments containing substrings enclosed in braces
{}are replaced by evaluating their contents as expressions. Simple math is allowed as well as retrieving metadata such as{TOP.'foo:bar'},{IMG[0].filename}, or{FRAME_NUMBER/24.0}. it's giving calculator that also knows secrets π
π OPTIONS π
πΈ Options (general flags) πΈ
--helpβ Print help message. your little emergency button π--versionβ Print version.-vβ Verbose status messages. it will yap (affectionately) π¬-qβ Quiet mode (turn verbose off and reduce printed output). shhh era π€«-nβ No saved output (dry run). you're just pretending, no files were harmed π--no-error-exitβ Do not exit upon error, try to process additional commands (danger!). this one is spicy, she said danger, believe her π₯-aβ Do operations on all subimages/miplevels.--debugβ Debug mode. detective hat on π΅οΈ--runstatsβ Print runtime statistics.--buildinfoβ Print OIIO build information.--infoβ Print resolution and basic info on all inputs, detailed metadata if-vis also used (options:format=xml:verbose=1).--list-formatsβ List all supported file formats and their filename extensions.--metamatch REGEXβ Which metadata is printed with-info -v.--no-metamatch REGEXβ Which metadata is excluded with-info -v.--statsβ Print pixel statistics of all inputs files.--dumpdataβ Print all pixel data values of input files (options:empty=1,C=arrayname).--hashβ Print SHA-1 hash of each input image.-uβ Update mode: skip outputs when the file exists and is newer than all inputs. she's efficient, she's booked, she's not redoing work π--no-clobberβ Do not overwrite existing files. respect the existing files, periodt β--create-dirβ Create output directories if it doesn't exists. (yes that's what it says, we keep it verbatim, no editing the queen's grammar π)--threads Nβ Number of threads (default0== #cores). default0means "use all the cores, go feral" π₯--gpuβ [EXPERIMENTAL] Use GPU if available (options:device=...).--no-autopremultβ Turn off automatic premultiplication of images with unassociated alpha.--autopremultβ Turn on automatic premultiplication of images with unassociated alpha.--autoorientβ Automatically--reorientall images upon input.--autoccβ Automatically color convert based on filename (options:unpremult=).--noautoccβ Turn off automatic color conversion.--nativeβ Keep native pixel data type (bypass cache if necessary).--cache MBβ ImageCache size (in MB: default=4096).--autotile TILESIZEβ Autotile enable for cached images (the argument is the tile size, default0means no autotile).--metamergeβ Always merge metadata of all inputs into output.--oiioattrib NAME VALUEβ Sets global OpenImageIO attribute (options:type=...).--experimentalβ Allow experimental features. buckle up π’
π Control flow and scripting π
she's a whole programming language now, slay π
--set NAME VALUEβ Set a user variable (options:type=...).--if VALUEβ IfVALUEis not 0 or empty, execute commands until--endif.--elseβ Else clause of the current 'if' block.--endifβ End the current 'if' block.--while VALUEβ IfVALUEis not 0 or empty, execute commands until--endwhileand loop. round and round bestie π--endwhileβ End the current 'while' block.--for VARIABLE RANGEβ Iterate over a range the commands between here and--endfor. The range may beEND(implied begin0and step1),START,END(implied step1) orSTART,END,STEP.--endforβ End the current 'for' block.--frames FRAMERANGEβ Frame range for#or printf-style wildcards.--framepadding NDIGITSβ Frame number padding digits (ignored when using printf-style wildcards).--views VIEWNAMESβ Views for%V/%vwildcards (comma-separated, defaults to"left,right").--skip-bad-framesβ Skip to next frame in range if there's an error, rather than exiting. we forgive and we move on π«Ά--parallel-framesβ Parallelize evaluation of frame range.--wildcardoffβ Disable numeric wildcard expansion for subsequent command line arguments.--wildcardonβ Enable numeric wildcard expansion for subsequent command line arguments.--evaloffβ Disable{expression}evaluation for subsequent command line arguments.--evalonβ Enable{expression}evaluation for subsequent command line arguments.
πΈ Commands that read images πΈ
-i FILENAMEβ Input file (options:autocc=,ch=,get_thumbnail=,info=,infoformat=,native=,now=,type=,unpremult=).--iconfig NAME VALUEβ Sets input config attribute (options:type=...).--missingfile OPTIONβ Set policy for missing input files:'error'(default),'black','checker'. three flavors of "where'd the file go" π--testread FILENAMEβ Test file read (do not keep image; used for debugging).
πΎ Commands that write images πΎ
-o FILENAMEβ Output the current image to the named file (options:all=,autocc=,autocrop=,autotrim=,bits=,contig=,datatype=,dither=,fileformatname=,scanline=,separate=,tile=,unpremult=).-otex FILENAMEβ Output the current image as a texture.-oenv FILENAMEβ Output the current image as a latlong env map.-obump FILENAMEβ Output the current bump texture map as a 6 channels texture including the first and second moment of the bump slopes (options:bumpformat=height|normal|auto,uvslopes_scale=val>=0,bumpscale=%f,bumpinverts=false,bumpinvertt=false,slopefilter=sobel|centraldiff,bumprange=centered|positive|auto).
πΌοΈ Options that affect subsequent image output πΌοΈ
-d TYPEββ-d TYPE'sets the output data format of all channels,β-d CHAN=TYPE'overrides a single named channel (multiple-dargs are allowed). Data types include:uint8,sint8,uint10,uint12,uint16,sint16,uint32,sint32,half,float,double.--scanlineβ Output scanline images.--tile WIDTH HEIGHTβ Output tiled images with this tile size.--compression NAMEβ Set the compression method (in the form"name"or"name:quality").--ditherβ Add dither when writing <= 8-bit output from > 8 bit input.--planarconfig CONFIGβ Force planarconfig (contig,separate,default).--adjust-timeβ Adjust file times to match DateTime metadata. she keeps her timestamps in sync, queen behavior β°--noautocropβ Do not automatically crop images whose formats don't support separate pixel data and full/display windows.--autotrimβ Automatically trim black borders upon output to file formats that support separate pixel data and full/display windows.
π Options that print data (usually about the current image) π
--echo TEXTβ Echo message to console (options:newline=0).--printinfoβ Print info and metadata of the current top image (options:allsubimages=,native=1,stats=1,verbose=0).--printstatsβ Print pixel statistics of the current top image (options:allsubimages=,window=<geom>).--colorcount COLORLISTβ Count of how many pixels have the given color (argument:color;color;...) (options:eps=color).--rangecheck MIN MAXβ Count of how many pixels are outside the min/max color range (each is a comma-separated color value list).
π·οΈ Options that change current image metadata (but not pixel values) π·οΈ
key detail bestie: metadata only. the pixels are UNTOUCHED. she's just rearranging the little name tags, not the artwork. π
--attrib NAME VALUEβ Sets metadata attribute (options:type=...).--sattrib NAME VALUEβ Sets string metadata attribute.--eraseattrib REGEXβ Yeet attributes matching a regex, bestie.(options: fromfile=1 filename-containing-patternsπ--caption TEXTβ Sets the caption, which is theImageDescriptionmetadata β¨--keyword KEYWORDβ Adds a keyword, periodt π--clear-keywordsβ Clears all the keywords, bye bestie π--historyβ Writes the full command line intoExif:ImageHistoryandSoftwaremetadata attributes π«Ά--no-historyβ Does NOT write the full command line intoExif:ImageHistoryandSoftwaremetadata attributes π--nosoftwareattribβ Writes noExif:ImageHistoryorSoftwaremetadata attributes at all, periodt π«--sansattribβ Writes the command line intoSoftware&ImageHistorybut removes the--sattriband--attriboptions π§--orientation ORIENTβ Sets the assumed orientation π--orientcwβ Rotates the orientation metadata 90 degrees clockwise π--orientccwβ Rotates the orientation metadata 90 degrees counter-clockwise π--orient180β Rotates the orientation metadata 180 degrees π--origin +X+Yβ Sets the pixel data window origin, like+20+10or-16-16π--originoffset +X+Yβ Offsets the pixel data window origin from where it is now, like+20+10or-16-16π--fullsize GEOMβ Sets the display window, e.g.1920x1080,1024x768+100+0,-20-30πΌοΈ--fullpixelsβ Sets the'full'image range to be the pixel data window π--chnames NAMELISTβ Sets the channel names, comma-separated π
β¨ Options that affect subsequent actions: β¨
--fail THRESHβ Failure threshold difference, default0.000001π--failpercent PCNTβ Allow this percentage of failures in diff, default0π--hardfail THRESHβ Fail diff if any one pixel exceeds this error, defaultinfinityπ--warn THRESHβ Warning threshold difference, default0.00001β οΈ--warnpercent PCNTβ Allow this percentage of warnings in diff, default0β οΈ--hardwarn THRESHβ Warn if any one pixel difference exceeds this error, defaultinfinityβ οΈ
π Actions: π
--create GEOM NCHANSβ Create a blank image β¨--pattern NAME GEOM NCHANSβ Create a patterned image. Pattern name choices:black,constant,fill,checker,noiseπ¨--kernel NAME GEOMβ Create a centered convolution kernel π§--captureβ Capture an image (options:camera=%d) πΈ--diffβ Print report on the difference of two images (modified by--fail,--failpercent,--hardfail,--warn,--warnpercent--hardwarn) π--pdiffβ Print report on the Yee perceptual difference of two images (modified by--fail,--failpercent,--hardfail,--warn,--warnpercent--hardwarn) π--flipdiffβ[EXPERIMENTAL]Compute FLIP perceptual difference of two images (options:hdr=1,colormap=NAME,ppd=67.02,maxluminance=2.0) π§ͺ--addβ Add two images β--addc VALβ Add to all channels a scalar or per-channel constants (e.g.:0.5or1,1.25,0.5) β--subβ Subtract two images β--subc VALβ Subtract from all channels a scalar or per-channel constants (e.g.:0.5or1,1.25,0.5) β--scaleβ Scale all channels of one image by the single channel of another image βοΈ--mulβ Multiply two images βοΈ--mulc VALβ Multiply the image values by a scalar or per-channel constants (e.g.:0.5or1,1.25,0.5) βοΈ--divβ Divide first image by second image β--divc VALβ Divide the image values by a scalar or per-channel constants (e.g.:0.5or1,1.25,0.5) β--madβ Multiply two images, add a third β¨--invertβ Take the color inverse (subtract from 1) (options:chbegin=0,chend=3π--absβ Take the absolute value of the image pixels π―--absdiffβ Absolute difference between two images π―--absdiffc VALβ Absolute difference versus a scalar or per-channel constant (e.g.:0.5or1,1.25,0.5) π―--powc VALβ Raise the image values to a scalar or per-channel power (e.g.:2.2or2.2,2.2,2.2,1.0) β‘--noiseβ Add noise to an image (options:type=gaussian:mean=0:stddev=0.1,type=uniform:min=0:max=0.1,type=salt:value=0:portion=0.1,seed=0ποΈ--chsumβ Turn into 1-channel image by summing channels (options:weight=r,g,...) ποΈ--colormap MAPNAMEβ Color map based on channel 0 (arg:"inferno","viridis","magma","turbo","plasma","blue-red","spectrum","heat", or comma-separated list of RGB triples) π--cryptomatte-colors NAMEβ Convert the named cryptomatte channels into a color matte image π¨--crop GEOMβ Set pixel data resolution and offset, cropping or padding if necessary (WxH+X+Yorxmin,ymin,xmax,ymax) βοΈ--croptofullβ Crop or pad to make pixel data region match the"full"region πΌοΈ--trimβ Crop to the minimal ROI containing nonzero pixel values βοΈ--cut GEOMβ Cut out the ROI and reposition to the origin (WxH+X+Yorxmin,ymin,xmax,ymax) βοΈ--paste +X+Yβ Paste fg over bg at the given position (e.g.,+100+50;'-'or'auto'indicates using the data window position as-is; options:all=%d,mergeroi=%d) π--pastemetaβ Paste the metadata from the first image into the second image (options:merge=%d,pattern=REGEX) π--mosaic WxHβ Assemble images into a mosaic (arg:WxH; options:pad=0,fit=WxH) π§©--overββOver'composite of two images π--zoverβ Depth composite two images with Z channels (options:zeroisinf=%d) π--deepmergeβ Merge/composite two deep images π--deepholdoutβ Hold out one deep image by another π--rotate90β Rotate the image 90 degrees clockwise π--rotate180β Rotate the image 180 degrees π--rotate270β Rotate the image 270 degrees clockwise (or 90 degrees CCW) π--flipβ Flip the image vertically (top<->bottom) π--flopβ Flop the image horizontally (left<->right) π--reorientβ Rotate and/or flop the image to transform the pixels to match the Orientation metadata π--transposeβ Transpose the image π--cshift +X+Yβ Circular shift the image (e.g.:+20-10) π--resample GEOMβ Resample (640x480,50%) (options:interp=0) π--resize GEOMβ Resize (640x480,50%) (options:from=<geom>,to=<geom>,filter=%s,highlightcomp=%d,edgeclamp=%d) π--fit GEOMβ Resize to fit within a window size (options:filter=%s,pad=%d,fillmode=%s,exact=%d,highlightcomp=%d) π--pixelaspect ASPECTβ Scale up the image's width or height to match the given pixel aspect ratio (options:filter=%s,highlightcomp=%d) π--rotate DEGREESβ Rotate pixels (degrees clockwise) around the center of the display window (options:filter=%s,center=%f,%f,recompute_roi=%d,highlightcomp=%dπ--warp MATRIXβ Warp pixels (argument is a 3x3 matrix, separated by commas) (options:filter=%s,recompute_roi=%d,highlightcomp=%d) π--st_warpβ Warp the first image using normalized"st"coordinates from the second image (options:filter=%s,chan_s=0,chan_t=1,flip_s=0,flip_t=0) π--convolveβ Convolve with a kernel π§--blur WxHβ Blur the image (options:kernel=name) π«οΈ--median WxHβ Median filter the image π«οΈ--dilate WxHβ Dilate (area maximum) the image π«οΈ--erode WxHβ Erode (area minimum) the image π«οΈ--unsharpβ Unsharp mask (options:kernel=gaussian,width=3,contrast=1,threshold=0) π«οΈ--laplacianβ Laplacian filter the image π«οΈ--normalizeβ Normalize the image (options:incenter=0.5,outcenter=0.5,scale=0.5) π--fftβ Take the FFT of the image π--ifftβ Take the inverse FFT of the image π--polarβ Convert complex (real,imag) to polar (amplitude,phase) π§--unpolarβ Convert polar (amplitude,phase) to complex (real,imag) π§--fixnan STRATEGYβ Fix NaN/Inf values in the image (choices:none,black,box3,error) π--fillholesβ Fill in holes (where alpha is not 1) π³οΈ--maxβ Pixel-by-pixel max of two images π--maxc VALβ Max all values with a scalar or per-channel constants (e.g.:0.5or1,1.25,0.5) π--maxchanβ Maximum of all channels of the image π--minβ Pixel-by-pixel min of two images π--minc VALβ Min all values with a scalar or per-channel constants (e.g.:0.5or1,1.25,0.5) π--minchanβ Minimum of all channels of the image π--clampβ Clamp values (options:min=...,max=...,clampalpha=0) π--contrastβ Remap values (options:black=0...,white=1...,sthresh=0.5...,scontrast=1.0...,gamma=1,clamp=0|1) ποΈ--saturate SCALEβ Scale saturation of the color channels π--rangecompressβ Compress the range of pixel values with a log scale (options:luma=0|1) π--rangeexpandβ un-rangecompresses your pixel values right back onto a linear scale (options:luma=0|1)--line X1,Y1,X2,Y2,...β renders a poly-line, so a whole string of connected segments (options:color=)--point X1,Y1,X2,Y2,...β renders points, lil dots, no connecting line bestie (options:color=)--box X1,Y1,X2,Y2β renders a box (options:color=)--fill GEOMβ fills a region (options:color=)--text TEXTβ renders text straight into the current image (options:x=,y=,size=,color=)--demosaicβ demosaics, obviously (options:pattern=%s,algorithm=%s,layout=%s,white_balance=%f:R,G1,G2,B)
π Manipulating channels or subimages π
--ch CHANLISTβ selects or shuffles channels. Think"R,G,B","B,G,R","2,3,4"β yes you can go by name or by number, we don't gatekeep--nchannels Nβ forces the current image to have exactlyNchannels (it pads with0.0wherever it needs to, no drama)--chappendβ appends the channels of the last two images together--unmipβ discards everything except the top level of a MIPmap--selectmip MIPLEVELβ picks out just one MIP level (0= highest res, so level 0 is the main character)--subimage SUBIMAGEINDEXβ selects just one subimage, by index or by name (options:delete=1)--sisplitβ splits the top image's subimages out into separate images--siappendβ appends the last two images into one multi-subimage image--siappendallβ appends all the images on the stack into a single multi-subimage image--layersplitβ splits the top image's channel-name-based layers into separate images sitting on the stack--deepenβ deepens a normal 2D image into deep--flattenβ flattens a deep image back to non-deep--thumbnail-getβ extracts an embedded thumbnail (options:fail=,index=)--thumbnail-setβ attaches the top image as the thumbnail of the image sitting below it
π Image stack manipulation π
--label %sβ labels the top image--dupβ duplicates the current image (pushes a copy onto the stack)--swapβ swaps the top two images on the stack.--popβ throws away the current image--popbottomβ throws away the image on the bottom of the stack--stackreverseβ throws away the image on the bottom of the stack (yeah, same wording as--popbottom, the manpage said what it said π)--stackextract INDEXβ moves an indexed stack item to the top of the stack--stackclearβ removes all images from the stack, leaving it completely empty
π Color management π
--colorconfiginfoβ prints extensive details about your color management configuration--colorconfig FILENAMEβ explicitly specifies an OCIO configuration file--iscolorspace COLORSPACEβ sets the assumed color space, and note: it does not alter any pixels--tocolorspace COLORSPACEβ converts the current image's pixels to a named color space--colorconvert SRC DSTβ converts pixels fromsrctodstcolor space (options:key=,value=,unpremult=,strict=)--ccmatrix MATRIXVALSβ color converts pixels with a 3x3 or 4x4 matrix (options:unpremult=,transpose=)--ociolook LOOKβ applies the named OCIO look (options:from=,to=,inverse=,key=,value=,unpremult=)--ociodisplay DISPLAY VIEWβ applies the named OCIO display and view (options:from=,looks=,key=,value=,unpremult=,inverse=)--ociofiletransform FILENAMEβ applies the named OCIO filetransform (options:inverse=,unpremult=)--ocionamedtransform NAMEβ applies the named OCIO namedtransform (options:inverse=,key=,value=,unpremult=)--unpremultβ divides all the color channels of the current image by the alpha, which is how you "un-premultiply"--premultβ multiplies all the color channels of the current image by the alpha--repremultβ multiplies all the color channels of the current image by the alpha, but it does not crushalpha=0pixels to black. subtle but iconic, honestly--iccwrite FILENAMEβ outputs the current image's ICC profile as its own separate file--iccread FILENAMEβ adds the contents of that file to the top image as its ICC profile--cicp CICPβ sets or modifiy CICP metadata for the output formats that support it (e.g.,"12,16,0,1")
okay and now for the receipts, the build deets, the whole "who even am I" of this particular binary π
Input formats supported:
bmp, cineon, dds, dicom, dpx, fits, gif, hdr, heif, ico, iff, jpeg, jpeg2000, jpegxl, null, openexr, openvdb, png, pnm, psd, ptex, raw, rla, sgi, softimage, targa, tiff, webp, zfile
Output formats supported:
bmp, dpx, fits, gif, hdr, heif, ico, iff, jpeg, jpeg2000, jpegxl, null, openexr, png, pnm, rla, sgi, targa, term, tiff, webp, zfile
OpenColorIO 2.4.2 Color config: ocio://default β run oiiotool --colorconfiginfo for a full color management inventory.
Filters available:
box, triangle, gaussian, sharp-gaussian, catmull-rom, blackman-harris, sinc, lanczos3, radial-lanczos3, nuke-lanczos6, mitchell, bspline, disk, cubic, keys, simon, rifman
And here's the build report card π«Ά
OIIO 3.1.18.1 | Linux/x86_64 Build compiler: gcc 16.2 |
C++17/201703 HW features enabled at build: sse2 No CUDA support
(disabled / unavailable at build time)
Dependencies:
BZip2 1.0.8, DCMTK 3.6.9, FFmpeg NONE, fmt 11.2.0,
Freetype 2.14.3, GIF 6.1.3, Imath 3.1.12, JXL 0.11.2, libdeflate
1.26, Libheif 1.23.5, libjpeg-turbo 3.1.3, LibRaw 0.22.2, libuhdr
1.4.0, OpenColorIO 2.4.2, OpenCV 4.13.0, OpenEXR 3.2.4, OpenGL,
OpenJPEG 2.5.4, openjph 0.25.3, OpenVDB 13.0.0, PNG 1.6.58, Ptex
2.5, pugixml 1.16, pybind11 3.0.4, Python3 3.14.7, Qt6 6.11.2,
Robinmap, TBB 2020.3, TIFF 4.7.2, WebP 1.6.0, ZLIB 1.3.1
Running on 8 cores 29.3GB
sse2,sse3,ssse3,sse41,sse42,avx,avx2,avx512f,avx512dq,avx512ifma,avx512cd,avx512bw,avx512vl,fma,f16c,popcnt,rdrand
No compute specific hardware enabled.
Full OIIO documentation can be found at https://docs.openimageio.org
π no cap, the CUDA thing is real β no CUDA support (disabled / unavailable at build time), so don't go expecting GPU compute magic from this build.
okay that's genuinely the whole page bestie, and it's oiiotool(1) from the oiiotool source, dated 05 October 2026 β¨ go forth and composite, you absolute legend ππ
π¦
π¦ where this page comes from
- fedora 44: OpenImageIO-utils 1:3.1.18.1-1.fc44 Β· BSD-3-Clause AND MIT
- π girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms