Make a Red-Cyan 3D Image with ppm3d

ppm3d turns a left-view PPM and a right-view PPM into a single anaglyph you can view through red-cyan or red-blue glasses. The guide uses Netpbm 11.5.2, installed here as package version 11.05.02-1.1build1. Allow about fifteen minutes if the two source images already exist.

• You need the netpbm package.
• You need two readable PPM files with identical dimensions.
• You need glasses whose left lens admits red light while the right lens admits blue and green.

The command reads the inputs and writes the result to standard output. It never modifies either source image.

1. Check the Installed Command

Confirm which executable will run and record the local Netpbm build:

$ command -v ppm3d
/usr/bin/ppm3d
$ ppm3d --version
ppm3d: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
ppm3d: Built from source dated 2024-03-31 09:09:47

The version option is not a documented ppm3d feature, but this installed build happens to report its Netpbm library and build details anyway. The documented interface is two input filenames, with optional offset and colour-mode options.

2. Check That the Two PPMs Match

The inputs must share the same width and height. Use file as a quick check:

$ file /path/to/left.ppm /path/to/right.ppm
/path/to/left.ppm:  Netpbm image data, size 1920 x 1080, rawbits, pixmap
/path/to/right.ppm: Netpbm image data, size 1920 x 1080, rawbits, pixmap

Your file wording can differ; what matters is that both dimensions agree. The left file is the view meant for the red lens, the right file for the blue-green lens. If the dimensions differ, resize or crop a copy with an image tool first. Do not overwrite the originals while experimenting.

If file does not identify one of the inputs as PPM, inspect it with a Netpbm reader or convert it to PPM before calling ppm3d. A filename ending in .ppm is not proof the contents are a valid PPM.

3. Make the Default Monochrome Anaglyph

Run the two filenames in left-then-right order and redirect standard output to a new destination:

$ ppm3d /path/to/left.ppm /path/to/right.ppm > /path/to/anaglyph.ppm
$ file /path/to/anaglyph.ppm
/path/to/anaglyph.ppm: Netpbm image data, size 1920 x 1080, rawbits, pixmap

Without the colour option, ppm3d produces a monochrome anaglyph. The manual describes the result as appearing yellow through red-green glasses, while the lack of other colours tends to make it look greyscale to the unaided brain. The output is a PPM regardless of the internal representation the input PPMs used.

4. Keep Colour When the Subject Suits It

Add the colour option for a colour anaglyph:

$ ppm3d -color /path/to/left.ppm /path/to/right.ppm > /path/to/anaglyph-colour.ppm
$ file /path/to/anaglyph-colour.ppm
/path/to/anaglyph-colour.ppm: Netpbm image data, size 1920 x 1080, rawbits, pixmap

Colour anaglyphs keep more of the original appearance, but each eye still cannot receive the whole spectrum. The manual specifically warns that red and cyan do not work well, while many other saturated colours fare better. Test the result through the glasses you actually intend to use.

Use glasses with a red left lens and a blue-green right lens for colour mode. A cyan lens is not limited to cyan light: the name describes its pigment, not every wavelength it passes.

5. Adjust Depth With an Offset

The default horizontal offset is zero. Set a positive or negative number of pixels when the two views need a different perceived depth:

$ ppm3d -color -offset=12 /path/to/left.ppm /path/to/right.ppm > /path/to/anaglyph-12.ppm
$ ppm3d -color -offset=-8 /path/to/left.ppm /path/to/right.ppm > /path/to/anaglyph-minus-8.ppm

The option describes how far the left image sits offset to the right of the right image in the output. Positive values move the whole image forward and negative values move it back, relative to the picture plane. The most useful value depends on camera separation, subject distance and alignment, so start small and inspect it.

Do not treat the number as a crop or resize request: it changes the overlap relationship. Keep the input dimensions equal and compare a few separately named outputs until one is comfortable to view.

6. Avoid Overwriting a Good Result

Shell redirection with > truncates an existing destination before ppm3d even starts. Use a temporary output, then replace the old file only after checking it:

$ ppm3d -color -offset=12 /path/to/left.ppm /path/to/right.ppm > /path/to/anaglyph.ppm.new
$ file /path/to/anaglyph.ppm.new
/path/to/anaglyph.ppm.new: Netpbm image data, size 1920 x 1080, rawbits, pixmap
$ mv /path/to/anaglyph.ppm.new /path/to/anaglyph.ppm

The final mv replaces the old output after conversion and inspection. If ppm3d fails, remove only the incomplete .new file and the previous output remains untouched. ppm3d never changes the source PPMs, so keep them until the new anaglyph has been checked with a viewer.

7. Handle the Common Failure Cases

An error about opening a file usually means the path is wrong or the file is not readable. Check without changing state:

$ ls -l /path/to/left.ppm /path/to/right.ppm
$ test -r /path/to/left.ppm && echo left-readable
$ test -r /path/to/right.ppm && echo right-readable

• Rejected for mismatched dimensions? Return to step 2 and create matched copies.
• Result looks flat? Check that the left and right images are genuinely different views, then try a modest offset.
• Depth looks reversed? Verify the left-right order before touching the offset.

The old optional third argument can supply the offset, for example ppm3d left.ppm right.ppm 12, but the manual marks it deprecated: use -offset=12 in new commands. The option arrived in Netpbm 10.38, released March 2007; older installations used the third argument and had a default offset of 30 pixels. This guide targets the installed Netpbm 11.5.2 behaviour, whose documented default is zero.

There is no need to run ppm3d as root. Reach for sudo only if your chosen input or output directory is deliberately locked down, and prefer a user-owned directory for image conversion.