How Does Oiiotool Compare to Iconvert for Command-Line Image Format Conversion in OpenImageIO

While both oiiotool and iconvert convert images between formats in OpenImageIO, oiiotool is a stack-based Swiss-army knife for complex image processing workflows, whereas iconvert is a lightweight single-purpose tool optimized for fast, memory-efficient format conversion.

Both utilities ship with the Academy Software Foundation's OpenImageIO (OIIO) library and leverage the same ImageInput and ImageOutput APIs. However, they differ fundamentally in architecture, performance characteristics, and intended use cases. Understanding how oiiotool compares to iconvert helps you choose the right tool for command-line image format conversion tasks.

Architectural Differences

The primary distinction lies in how each tool processes pixel data and manages memory.

Oiiotool's Stack-Based Architecture

oiiotool implements an Oiiotool class that maintains an image stack (std::vector<ImageRecRef> image_stack). Each command-line argument represents an action that pops one or more images from the stack, executes an OiiotoolOp, and pushes the result back.

Actions register via macros like OIIOTOOL_OP and OIIOTOOL_INPLACE_OP defined in src/oiiotool/oiiotool.cpp. This design enables complex pipelines where intermediate results persist in memory:

oiiotool input.exr --resize 640x480 --colorconvert sRGB linear -o output.exr

Here, the resize operation pushes a new image onto the stack, which the color conversion then processes.

Iconvert's Single-Pass Pipeline

iconvert follows a single-pass model implemented entirely in src/iconvert/iconvert.cpp. After parsing arguments with getargs, the convert_file function opens the input via ImageInput::open, creates an ImageOutput, and either calls copy_image for fast transfer or falls back to a manual read/write loop.

Unlike oiiotool, iconvert does not maintain intermediate state. It processes the image exactly once, making it memory-efficient for simple format conversion:

iconvert input.exr output.png

Performance and Memory Characteristics

Fast Copy Optimization in Iconvert

iconvert optimizes for the common case where only the container format changes. In src/iconvert/iconvert.cpp, the convert_file function first attempts out->copy_image(in.get()) when input and output specs are compatible. This bypasses pixel-wise copying entirely, resulting in significantly faster conversions and lower memory usage.

If the output spec differs (different data format, tile size, or compression), iconvert sets nocopy and falls back to in->read_image followed by out->write_image.

ImageCache and Float Buffers in Oiiotool

oiiotool uses ImageCache by default (unless --native is specified) to lazily load images. While this enables processing of images larger than physical memory, it introduces overhead. Each operation typically converts pixels to float buffers for processing, which adds computational cost compared to iconvert's direct copy path.

For pure format conversion without processing, oiiotool is generally slower than iconvert due to this architectural overhead.

Feature Comparison

Command-Line Models

oiiotool uses a stack-based positional model where filenames push images and flags trigger operations:

oiiotool input.tif --resize 50% -o output.tif

iconvert uses a simple input-output positional model:

iconvert input.tif output.tif

Or batch mode with --inplace:

iconvert --inplace *.exr

Metadata and Sub-image Handling

Both tools support metadata manipulation, but oiiotool provides granular control via --attrib, --eraseattrib, and --printinfo. It also handles sub-images and MIP levels explicitly via :subimages= modifiers.

iconvert supports basic attribute setting via --attrib and copies all sub-images by default, but lacks the fine-grained control of oiiotool.

When to Use Each Tool

Choose oiiotool when you need:

• Image processing operations (resize, color convert, composite)
• Complex workflows with multiple intermediate steps
• Fine-grained metadata editing
• Scripting with control flow (--if, --for)
• Sub-image or MIP-level manipulation

Choose iconvert when you need:

• Fast, memory-efficient format conversion
• Batch processing with minimal overhead
• Simple output parameter adjustment (tile size, compression)
• In-place conversion of multiple files

Practical Code Examples

Simple Format Conversion

Both tools handle basic conversion, but iconvert is faster for this specific task:

# oiiotool - reads to float buffer, writes EXR

oiiotool input.png -o output.exr

# iconvert - uses copy_image fast path when possible

iconvert input.png output.exr

Converting to Tiled Format

# oiiotool

oiiotool scanline.tif --tile 64 64 -o tiled.tif

# iconvert

iconvert --tile 64 64 scanline.tif tiled.tif

In src/iconvert/iconvert.cpp, the adjust_spec function sets outspec.tile_width and tile_height (lines 332-338), while oiiotool handles this in adjust_output_options in src/oiiotool/oiiotool.cpp.

Batch In-Place Conversion

Only iconvert supports native in-place batch processing:

iconvert --inplace *.exr

This iterates over filenames and calls convert_file(s, s) as shown in src/iconvert/iconvert.cpp lines 511-532. oiiotool requires shell scripting for equivalent functionality.

Adding Metadata During Conversion

# oiiotool

oiiotool img.exr --attrib "Artist" "John Doe" -o img_with_artist.exr

# iconvert

iconvert --attrib Artist "John Doe" img.exr img_with_artist.exr

Both ultimately invoke attribute setting logic—oiiotool uses set_attribute_helper (lines 1319-1360 in oiiotool.cpp), while iconvert loops over attribnames/attribvals in adjust_spec (lines 104-106 in iconvert.cpp).

Summary

• oiiotool is a stack-based image processing shell with hundreds of commands for complex workflows, implemented in src/oiiotool/oiiotool.cpp using an Oiiotool class and OiiotoolOp actions.
• iconvert is a lightweight format converter optimized for speed, implemented in src/iconvert/iconvert.cpp with a single-pass pipeline that uses ImageOutput::copy_image for fast container changes.
• Use oiiotool when you need image manipulation, metadata editing, or complex pipelines; use iconvert for fast, memory-efficient format conversion with minimal overhead.

Frequently Asked Questions

Can iconvert perform image resizing or color space conversion?

No. iconvert is designed specifically for format conversion and output parameter adjustment (tile size, compression, data format). It does not implement image processing algorithms like resizing or color conversion. For these operations, use oiiotool with flags like --resize or --colorconvert, which leverage ImageBufAlgo functions implemented in src/oiiotool/oiiotool.cpp.

Why is iconvert faster than oiiotool for simple format conversion?

iconvert uses a fast path via ImageOutput::copy_image when input and output specs are compatible, bypassing pixel-wise memory copies entirely. This is implemented in src/iconvert/iconvert.cpp around lines 93-104. In contrast, oiiotool reads images into float buffers (or uses ImageCache with overhead) and processes them through its stack-based architecture, adding computational cost even for simple conversions.

Does oiiotool support batch in-place conversion like iconvert?

No. iconvert provides the --inplace flag that processes multiple files in a loop, calling convert_file(s, s) for each filename as shown in src/iconvert/iconvert.cpp lines 511-532. oiiotool operates on a stack-based model where each filename pushes a new image; it has no built-in batch in-place mode. You would need to write a shell loop or use --run scripts to achieve similar batch processing with oiiotool.

Which tool should I use for converting tiled images to scanline format?

Both tools handle this conversion effectively. Use iconvert --scanline input.tif output.tif for a fast, memory-efficient conversion that modifies the ImageSpec in adjust_spec (src/iconvert/iconvert.cpp lines 340-343). Alternatively, use oiiotool input.tif --scanline -o output.tif if you need to combine this with other operations like metadata editing or resizing. For pure format conversion without additional processing, iconvert offers better performance.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}