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

> Compare oiiotool vs iconvert for command-line image conversion. Discover oiiotool's powerful processing capabilities vs iconvert's efficient format switching.

- Repository: [Academy Software Foundation/openimageio](https://github.com/academysoftwarefoundation/openimageio)
- Tags: comparison
- Published: 2026-02-23

---

**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`](https://github.com/academysoftwarefoundation/openimageio/blob/main/src/oiiotool/oiiotool.cpp). This design enables complex pipelines where intermediate results persist in memory:

```bash
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`](https://github.com/academysoftwarefoundation/openimageio/blob/main/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:

```bash
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`](https://github.com/academysoftwarefoundation/openimageio/blob/main/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:

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

```

`iconvert` uses a simple **input-output** positional model:

```bash
iconvert input.tif output.tif

```

Or batch mode with `--inplace`:

```bash
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:

```bash

# oiiotool - reads to float buffer, writes EXR

oiiotool input.png -o output.exr

```

```bash

# iconvert - uses copy_image fast path when possible

iconvert input.png output.exr

```

### Converting to Tiled Format

```bash

# oiiotool

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

```

```bash

# iconvert

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

```

In [`src/iconvert/iconvert.cpp`](https://github.com/academysoftwarefoundation/openimageio/blob/main/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`](https://github.com/academysoftwarefoundation/openimageio/blob/main/src/oiiotool/oiiotool.cpp).

### Batch In-Place Conversion

Only `iconvert` supports native in-place batch processing:

```bash
iconvert --inplace *.exr

```

This iterates over filenames and calls `convert_file(s, s)` as shown in [`src/iconvert/iconvert.cpp`](https://github.com/academysoftwarefoundation/openimageio/blob/main/src/iconvert/iconvert.cpp) lines 511-532. `oiiotool` requires shell scripting for equivalent functionality.

### Adding Metadata During Conversion

```bash

# oiiotool

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

```

```bash

# 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`](https://github.com/academysoftwarefoundation/openimageio/blob/main/oiiotool.cpp)), while `iconvert` loops over `attribnames`/`attribvals` in `adjust_spec` (lines 104-106 in [`iconvert.cpp`](https://github.com/academysoftwarefoundation/openimageio/blob/main/iconvert.cpp)).

## Summary

- **`oiiotool`** is a stack-based image processing shell with hundreds of commands for complex workflows, implemented in [`src/oiiotool/oiiotool.cpp`](https://github.com/academysoftwarefoundation/openimageio/blob/main/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`](https://github.com/academysoftwarefoundation/openimageio/blob/main/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`](https://github.com/academysoftwarefoundation/openimageio/blob/main/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`](https://github.com/academysoftwarefoundation/openimageio/blob/main/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`](https://github.com/academysoftwarefoundation/openimageio/blob/main/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`](https://github.com/academysoftwarefoundation/openimageio/blob/main/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.