Create a red-cyan 3D image with ppm3d

You will combine a left-view PPM and a right-view PPM into a PPM anaglyph for red-cyan or red-blue 3D 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, two readable PPM files with identical dimensions, and glasses whose left lens admits red light while the right lens admits blue and green light. The command reads the inputs and writes the result to standard output. It does not modify 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 described as a normal ppm3d feature in the manual, but this installed build reports its Netpbm library and build details. The documented interface is two input filenames, with optional offset and colour-mode options.

Checkpoint: if command -v ppm3d finds nothing, stop and install Netpbm through your normal package-management process. Neither image conversion nor inspection needs elevated privileges when the files are in a directory you can access.

2. Check that the two PPMs match

The inputs must have 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. The useful part is that both dimensions agree. The left file is the view intended for the red lens; the right file is the view intended 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 that 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, even when the input PPMs use a different internal representation.

Checkpoint: confirm that the output exists and has the expected dimensions before deleting or replacing anything. A successful exit status shows that conversion completed; it does not prove that the camera views were aligned correctly.

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 retain more of the original appearance, but each eye cannot receive the whole spectrum. The manual specifically warns that red and cyan do not work well, while many other saturated colours are more successful. 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 the colour mode. A cyan lens is not limited to cyan light, so the name describes its pigment rather than 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 is offset to the right of the right image in the output. Positive values move the entire image forward and negative values move it backward, relative to the picture plane. The most useful value depends on the camera separation, subject distance and alignment, so start with a small change 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 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. The source PPMs are never changed by ppm3d, 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 normally 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

If ppm3d rejects the inputs because their dimensions differ, return to step 2 and create matched copies. If the result looks flat, check that the left and right images are genuinely different views and try a modest offset. If depth appears reversed, verify the left-right order before changing the offset.

The old optional third argument can supply the offset, for example ppm3d left.ppm right.ppm 12, but the manual marks it as deprecated. Use -offset=12 in new commands. The option was introduced in Netpbm 10.38, released in 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. Use sudo only if your chosen input or output directory is deliberately inaccessible to your account, and prefer working in a user-owned directory for image conversion.