Create a Reproducible PAM Stereogram from a Depth Map

You will turn a PAM or PNM depth map into a single-image stereogram (SIS), save the PAM output, and verify that repeated runs are identical. Allow about 15 minutes if your depth map already exists. The examples use the installed Netpbm 11.5.2 package on Linux.

1. Check the input and installed command

pamstereogram reads a depth map and writes a PAM image to standard output. Each input sample is one depth value: lower, darker values are farther from the eye, while higher values are nearer. The command ignores the input tuple type and uses only plane 0. Netpbm also accepts PNM input as if it were the equivalent PAM image.

Keep the input somewhere you can read and do the conversion as an ordinary user. No service change or elevated privilege is needed.

$ command -v pamstereogram
/usr/bin/pamstereogram
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1

Checkpoint: you have a readable depth map and the command comes from the expected Netpbm installation. If the version differs, confirm the local manual before relying on defaults.

2. Generate a deterministic black-and-white stereogram

The default output is a black-and-white random-dot stereogram. Randomness normally uses a time-based seed, so two runs can differ. Pass -randomseed when you need a reproducible file, such as for a test fixture or a documented build.

$ pamstereogram /path/to/depthmap.pam \
    -randomseed=42 > stereogram.pam

The input path is optional: omitting it makes the command read the depth map from standard input. The equals sign is optional for valued options, but keeping it makes the option boundary obvious. Standard output is binary image data, so redirect it to a file rather than letting it fill your terminal.

Checkpoint: the command exits without an error and stereogram.pam exists. The output is not a normal text report, so a blank terminal is expected when standard output is redirected.

3. Inspect the PAM header and dimensions

Use Netpbm's inspection tool before opening or converting the image. This confirms that the output is a PAM and records its dimensions, depth and maximum sample value.

$ pamfile stereogram.pam
stereogram.pam:	PAM, 64 by 48 by 1 maxval 1
    Tuple type: BLACKANDWHITE
$ file stereogram.pam
stereogram.pam: Netpbm PAM image file, size = 64 x 48

Your dimensions will match the depth map unless you add an option that changes the generated layout. The black-and-white default has maxval 1. If another application does not understand PAM, convert a verified result with pamtopnm:

$ pamtopnm stereogram.pam > stereogram.pnm
$ file stereogram.pnm
stereogram.pnm: Netpbm image data, size = 64 x 48, rawbits, bitmap

Checkpoint: the reported dimensions are the ones you expect, and the converted file is non-empty. A PNM conversion is a separate step; it does not alter the original PAM.

4. Make output easier to see

For grey dots, use -grayscale. For random colour dots, use the colour mode option. These modes are alternatives to the default -blackandwhite. With either grey or colour output, -maxval controls the component resolution; it has no effect on black-and-white output.

$ pamstereogram /path/to/depthmap.pam \
    -grayscale -maxval=255 -randomseed=42 > stereogram-grey.pam
$ pamfile stereogram-grey.pam
stereogram-grey.pam:	PAM, 64 by 48 by 1 maxval 255
    Tuple type: GRAYSCALE

Use -magnifypat=3 if individual random dots need enlarging by an integral scale factor. This increases the apparent dot size and therefore the output dimensions. The installed manual also documents -dpi, which defaults to 100, and -eyesep, which defaults to 2.5 inches. Those values affect the stereoscopic geometry, not the input file.

5. Add focusing guides or choose viewing geometry

Guide boxes can make the image easier to fuse: -guidebottom places them below the stereogram and -guidetop places them above it. Their default size is 20 pixels; use -guidesize only with one of those guide options.

$ pamstereogram /path/to/depthmap.pam \
    -guidebottom -guidesize=20 -randomseed=42 > stereogram-guided.pam

The default depth fraction is 0.3333. Smaller values make the 3-D effect flatter but easier to perceive; larger values increase apparent depth and make viewing harder. -crosseyed inverts the depth relationship for cross-eyed viewing or for a depth map whose nearer regions use darker values. Test the result visually rather than assuming that a successful exit means the chosen viewing convention is comfortable.

Checkpoint: the output has the intended viewing arrangement. If the subject appears reversed, try a copy with -crosseyed and compare it, keeping the original output.

6. Use patterns or a colour texture carefully

-patfile repeats an image as the stereogram pattern. It cannot be combined with the black-and-white, grayscale or colour mode options, or with -maxval; the pattern determines the output format and maxval. Run with -verbose when you need the ideal pattern width for seamless tiling.

$ pamstereogram /path/to/depthmap.pam \
    -patfile=/path/to/pattern.ppm -verbose > patterned.pam

For a mapped-texture stereogram, pair the depth map with an aligned texture image using -texfile. The two images must have the same dimensions. The manual recommends a larger-than-normal eye separation or DPI for this mode, because otherwise the texture repeats heavily and coloured pixels overlap. If the texture has a known background, -bgcolor can specify it; that option is meaningful only with -texfile.

7. Avoid overwriting a useful image

Shell redirection with > truncates its destination before pamstereogram starts. Use a new name first when replacing a result:

$ pamstereogram /path/to/depthmap.pam \
    -randomseed=42 > stereogram.pam.new
$ pamfile stereogram.pam.new
$ mv stereogram.pam.new stereogram.pam

Only run mv after the inspection succeeds. If generation fails, remove the incomplete stereogram.pam.new and leave the existing file alone. Do not delete the input depth map as part of this workflow.