PAMSTEREOGRAM(1)

📦
version 11.13.03 · 6 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💖 pamstereogram — the manual, but make it make sense 💖

okay bestie, so this is pamstereogram from the Pamstereog...User Manual(1) — General Commands Manual, and no I'm not gonna make you decode the crusty old header, we're diving straight in. she's long, she's iconic, and she's about to make your eyeballs do a trick. 👑✨

✨ NAME ✨

pamstereogram — create a single-image stereogram from a PAM depth map 🦋

🌈 SYNOPSIS 🌈

pamstereogram [-help] [-verbose] [-blackandwhite | -grayscale | -color]
[-maxval=value] [-patfile=pamfile] [-texfile=pamfile] [-bgcolor=color]
[-smoothing=pixels] [-xbegin=pixels] [-xshift=pixels] [-yshift=pixels]
[-yfillshift pixels] [-magnifypat=scale] [-guidetop] [-guidebottom]
[-guidesize=pixels] [-dpi=resolution] [-crosseyed] [-makemask]
[-eyesep=inches] [-depth=fraction] [-planes=near_pixels,far_pixels]
[-randomseed=integer] [-tileable] [infile]
not me listing every single one of these flags and then explaining every single one of these flags. we do not cut corners in this house. 💅

🌸 DESCRIPTION 🌸

hi hi, so pamstereogram is part of Netpbm(1), she's got friends, she's got lore. 💜

here's the tea: pamstereogram takes a depth map as input — that's a map of the distances from your eye of the points in a scene, like a little topographic vibe check of how far away everything is — and it outputs a single-image stereogram (SIS). 🔥

a SIS is a 2-D image that is specially designed to look three dimensional when you view it with relaxed, slightly unfocused eyes. like, you gotta ✨unclench✨ your eye muscles. what's so exciting about single-image stereograms is that they don't require special glasses to view — no 3-D glasses, no red/cyan situation, nothing. though ngl it does require a bit of practice to train your eyes to unfocus properly. 😭 it's giving "trust the process."

the pamstereogram program provides a wealth of control over how the stereogram is generated, including the following:

  • black and white, grayscale, or color output 🖤🤍🌈
  • single-image random-dot stereograms (SIRDS), single-image stereograms (SIS) using a tiled image, or mapped-texture stereograms (MTS) 🎀
  • images targeting a given device resolution and eye separation 🔍
  • optional guide boxes to assist in focusing 📦
  • the ability to trade off depth levels for easier viewing ⚖️
  • choice of wall-eyed or cross-eyed stereograms 👀

the output is a PAM image on standard output. options control the exact format of the PAM. if you want a PNM (PBM, PGM, or PPM) image, use pamtopnm on the output. there is no need to convert if you will use the image as input to a current Netpbm program — but many other programs don't know what a PAM is, so, y'know, read the room. 🙈

wanna make a red/cyan type of stereogram instead (the kind you view with 3-D glasses)? that's a whole different girl. see ppm3d. 🕶️

okay bestie we are SO not done, the flags are coming in the next part and there are a lot of them. stay with me. 🫶

✨ OPTIONS ✨

Okay bestie, here's the tea on flags 💅 You may use either single or double hyphens to denote options. And you may use either whitespace or an equals sign to separate an option name from its value. Whatever vibes, honestly.

On top of the options common to all programs based on libnetpbm (most notably -quiet, see Common Options), pamstereogram recognizes the following command line options:

  • -verbose — Spills the tea about image sizes and formats and properties of the stereogram being generated. Very "tell me everything" of it 💬
  • -blackandwhite — Produce a single-image random-dot black-and-white stereogram. This is the default, no cap. 🖤🤍
  • -grayscale — Produce a single-image random-dot grayscale stereogram. Fifty shades of slay 🩶
  • -color — Produce a single-image random-dot color stereogram. Rainbow mode activated 🌈
  • -maxval=value — Designate the maximum value of each gray/color component, i.e. the color resolution. Smaller values make the output image have smaller numbers of unique grays/colors. If you don't specify -maxval, pamstereogram uses the maxval of the input image. Heads up: this option has no effect with -blackandwhite. ✨
  • -patfile=pamfile — Specify an image to use as a repeated background pattern for the stereogram instead of a random-dot pattern. Intricate images generally produce a crisper 3-D effect that simpler images. The output file will have the same maxval and format (black and white, grayscale or color) as the pattern file. You **cannot specify the -patfile option along with -blackandwhite, -grayscale, -color, or -maxval. The -verbose option will give you information on the ideal dimensions of the pattern file. 🎀
Not me gatekeeping pattern dimensions — that's literally what -verbose is for, bestie.
  • *-xbegin=pixels* — Specify the horizontal coordinate at which to begin stereogram generation. The background pattern will be minimally distorted at this point and more distorted at greater distances. Consider using this in conjunction with -xshift to align the horizontal start of the pattern with the horizontal start of stereogram generation. -xbegin is meaningful only in conjunction with -patfile, -makemask, or -texfile, and pamstereogram actually ignores it with respect to -texfile (but may not in a future version of pamstereogram).

The default is to begin in the center.

This option was new in Netpbm 10.71 (June 2015). 🦋

  • *-texfile=pamfile* — Specify an image to use as the texture for a mapped-texture stereogram. The idea is that the depth-map image provides the depth values of the 3-D object/scene while the texture image provides the true-color values. Consequently, the texture image should align with the depth-map image. (Note that it's required to have the same dimensions.) The texture image's background color is ignored when blending colors. 🧚

This option was new in Netpbm 10.53 (December 2010).

  • *-bgcolor=color* — Use color as the texture image's background color instead of letting pamstereogram determine it automatically. Specify the color as described for the argument of the pnm_parsecolor() library routine. The -bgcolor option is meaningful only in conjunction with -texfile.

This option was new in Netpbm 10.53 (December 2010). 💜

  • *-smoothing=pixels* — When used without -texfile, attempt to eliminate artifacts introduced by edges in the depth map if pixels is greater than zero.

When used with -texfile, horizontally blur non-background colors into background pixels up to a distance of pixels pixels. This helps smooth over distracting glitches introduced by the stereogram's color constraints when producing a mapped-texture stereogram. In this case, the -smoothing option is helpful when the texture image includes smooth color transitions (as in a photograph) but makes crisp texture images (as in a line drawing) appear blurry. 🙈

This option was new in Netpbm 10.53 (December 2010). Before Netpbm 10.61 (December 2012), it has no effect without -texfile.

  • *-xshift=pixels* — Shift the pattern image (designated by -patfile) to the right by pixels pixels (default: 0).

This option is valid only along with -patfile. ➡️

  • -yshift pixels — Shift the pattern image (designated by -patfile) downwards by pixels pixels (default: 0). This option is valid only along with -patfile. ⬇️
  • -yfillshift pixels — Shift the pattern image (designated by -patfile) downwards by pixels pixels (default: 0) but only after the initial population of the pattern. (If used with -yshift the resulting shifts are summed.) A small -yfillshift helps reduce visual artifacts in the 3-D image. Steer's website, referenced under SEE ALSO, recommends a shift of approximately 1/16" (6-7 pixels at pamstereogram's default of 100 DPI).

This option was new in Netpbm 10.94 (March 2021). 🌸

  • -magnifypat=scale — Magnify each pixel in the pattern file or each random dot by integral scaling factor scale. Note that pamstereogram applies the pattern magnification **after pattern shifting (-xshift and -yshift). 🔍
  • -guidebottom — Draw a pair of black squares on a white background underneath the stereogram proper. These squares help you guide your eyes into proper focus to view the 3-D image. The trick is to focus your eyes some distance behind the image, causing you to see four black squares, then continue altering your focus distance until the middle two black squares fuse into a single black square. At that point, a crisp, 3-D image will appear. 👀✨

This option was new in Netpbm 10.61 (December 2012). Before that, the presence of -guidesize, with a positive value, has the same effect.

  • -guidetop — Same as -guidebottom, except the guides go at the top of the image. 🙃

This option was new in Netpbm 10.61 (December 2012). Before that, the presence of -guidesize, with a negative value, has the same effect.

  • *-guidesize=pixels* — The size (width and height) of each guide box.

This is valid only with -guidetop or -guidebottom.

Default is 20.

Before Netpbm 10.61 (December 2012), if you don't specify this option, pamstereogram draws no guides. If you specify it with a positive value, pamstereogram behaves as if you specified -guidebottom too, and if you specify it with a negative value, it behaves as if you specified -guidetop and specified guidesize with the absolute value of that negative value. 🎚️

  • *-dpi=resolution* — Specify the resolution of the output device in dots per inch. The default is 100 DPI, which represents a fairly crisp screen resolution. 🖥️

Before Netpbm 10.53 (December 2010), the default was 96 DPI.

  • -crosseyed — Invert the gray levels in the depth map (input image) so that the 3-D image pops out of the page where it would otherwise sink into the page and vice versa. Some people are unable to diverge their eyes and can only cross them. The -crosseyed option enables such people to see the 3-D image as intended. You can also specify the -crosseyed option if you prefer using depth maps in which darker colors are closer to the eye and lighter colors are farther from the eye. 😵💫

Before Netpbm 10.53 (December 2010), pamstereogram used higher (lighter) numbers for things closer to the eye without -crosseyed and vice versa.

  • -makemask — Instead of a stereogram, output a PAM mask image showing coloring constraints. New pixels will be taken from the pattern file where the mask is black. Copies of existing pixels will be taken from the pattern file where the mask is white. The -makemask option can be used to help create more sophisticated pattern files (to use with -patfile) Note that -makemask ignores -magnifypat; it always produces masks that assume a pattern magnification of 1. 🎭
  • *-eyesep=inches* — Specify the separation in inches between your eyes. The default, 2.5 inches (6.4 cm), should be sufficient for most people and probably doesn't need to be changed. 👁️👁️
  • *-depth=fraction* — Specify the output image's depth of field. That is, fraction represents the fractional distance of the near plane from the far plane. Smaller numbers make the 3-D image easier to perceive but flatter. Larger numbers make the 3-D image more difficult to perceive but deeper. The default, 0.3333, generally works fairly well. 🕳️
  • *-planes=near_pixels,far_pixels* — Explicitly specify the distance between repeated pixels in the near plane and in the far plane. This is an alternative to -eyesep and -depth. The following equalities hold:
    • eyesep = 2 * far
    • depth = 2 * (far - near) / (2 * far - near)

The number of distinct 3-D depths is far - near + 1. One might say that -eyesep and -depth are a more human-friendly way to specify stereoscopic parameters (distance between eyes and tradeoff between perceptibility and depth) while -planes is a more computer-centric way (pixel distances in the resulting stereogram). 🤓

This option was new in Netpbm 10.59 (June 2012).

  • *-randomseed=integer* — Specify a seed to be used for the random number generator. The default is to use a seed based on the time of day, to one second granularity.

It is useful to specify the seed if you want to create reproducible results. With the same random seed, you should get identical results every time you run pamstereogram. 🔁

This is irrelevant if you use a pattern file (-patfile option), because there is no random element to pamstereogram's behavior.

This option was new in Netpbm 10.32 (February 2006). 🍓

  • -tileable — Make the generated image horizontally tileable. This works by blending a left-to-right rendering (the equivalent of -xbegin=0) with a right-to-left rendering (the equivalent of -xbegin=width-1). ♾️

This option was new in Netpbm 10.91 (June 2020).

💖 PARAMETERS 💖

Okay bestie, there's literally just one parameter here and her name is infile 🎀

  • infile — the name of an input file that is a depth map image. And if you don't specify infile at all? No stress, the input just comes straight from standard input. Slay. ✨

The input is a PAM image of depth 1. Every single sample says how far away from the eye the 3-D image at that spot should be. And here's the twist that trips people up: lower (darker) numbers mean further from the eye 👀 yes, it's backwards from what your brain wants, but that's the vibe.

📝 NOTES 📝

🌸 Input Images 🌸

pamstereogram pays zero attention to the image's tuple type, and it ignores all planes other than plane 0. Plane 0 is the main character, the rest are just background dancers 💅

And like any Netpbm program, pamstereogram will accept PNM input as if it were the PAM equivalent. Same energy, different outfit. 🦋

🌈 Mapped-texture Stereograms 🌈

In a mapped-texture stereogram (MTS), the 3-D image can be drawn with true colors. But — and this is the plot twist — unlike a SIRDS or tiled-image SIS, the image portrayed by an MTS is apparent in normal 2-D viewing. It literally shows up repeated multiple times and overlapped with itself, but it is not hidden. No squinting required, bestie 😭

You create an MTS with pamstereogram by passing the filename of a PAM "texture image" with a -texfile option. A texture image portrays the same 3-D object as the depth-map image, but it tells the program which colors to apply to the object. It's giving colorist era. 🎨

Now listen closely, this part matters: pamstereogram ignores the texture image's background color when it overlaps copies of the 3-D object. Why? So that, for example, a bright-red object on a black background doesn't get drawn as a dark-red object (which would be a 50% bright red + 50% black blend 😭). Instead, the program ignores the black and the object stays bright red. Periodt. ✨

⚠️ A consequence of this feature: an MTS looks best when the objects in the texture image have a crisp outline. Smooth transitions to the background color cause unwanted color artifacts around the edges, because the program only ignores exact matches with the background color. It's picky like that 🙈

You should specify a larger-than-normal value for -eyesep (and/or -dpi) when producing an MTS. Otherwise the 3-D object will repeat so many times that most colored pixels will overlap other colored pixels, which reduces the number of true-colored pixels that remain. Basically your beautiful colors get trampled 💀

An MTS can also employ a background pattern (-patfile). In that case, pamstereogram replaces background pixels with pattern pixels in the final step of generating the image. Cute little finishing touch, fr fr. 🌸

🧚 Miscellaneous 🧚

A good initial test is to input an image consisting of a solid shape of distance 0 within a large field of maximum distance (e.g., a white square on a black background). Iconic starter move, ngl. ✨

With the default values for -dpi and -eyesep, pattern images that are 128 pixels wide can tile seamlessly. The math ate, no cap. 🔥

💅 EXAMPLES 💅

Generate a SIRDS out of small, brightly colored squares and prepare it for display on an 87 DPI monitor:

pamstereogram depthmap.pam \
    -dpi 87 -verbose -color -maxval 1 -magnifypat 3 \
    >3d.pam

Generate a SIS by tiling a PPM file (a prior run with -verbose indicates how wide the pattern file should be for seamless tiling, although any width is acceptable for producing SISes):

pamstereogram depthmap.pam -patfile mypattern.ppm >3d.pam

Generate an MTS by associating colors with a depth-mapped object (using a large eye separation to reduce the number of repetitions of the texture image) and twice smoothing over background-colored speckles:

pamstereogram depthmap.pam \
    -texfile colormap.pam -smoothing 2 -eyesep 3.5 \
    >3d.pam

👀 SEE ALSO 👀

  • pam(1)
  • pamsistoaglyph(1)
  • ppm3d(1)
  • Harold W. Thimbleby, Stuart Inglis, and Ian H. Witten. Displaying 3D Images: Algorithms for Single Image Random Dot Stereograms. In IEEE Computer, 27(10):38-48, October 1994. DOI: 10.1109/2.318576 .
  • W. A. Steer. Stereograms: Technical Details. URL: http://www.techmind.org/stereo/stech.html(1).

🕰️ HISTORY 🕰️

pamstereogram was new in Netpbm 10.22 (April 2004), but probably broken beyond usability until Netpbm 10.32 (February 2006) and Netpbm 10.26.23 (January 2006). It was going through a phase, okay, we don't talk about it 😭

A backward incompatible change to the way you request guide boxes (-guidetop, -guidebottom, -guidesize) happened in Netpbm 10.61 (December 2012). So if you're reading ancient forum posts, that's why nothing makes sense. You're welcome 🫶

👑 AUTHOR 👑

Copyright © 2006-2020 Scott Pakin, scott+pbm@pakin.org.

📖 Table Of Contents 📖

  • SYNOPSIS
  • DESCRIPTION
  • OPTIONS
  • PARAMETERS
  • NOTES
  • Input Images
  • Mapped-texture Stereograms
  • Miscellaneous
  • EXAMPLES
  • SEE ALSO
  • HISTORY
  • AUTHOR

🔮 DOCUMENT SOURCE 🔮

This manual page was generated by the Netpbm tool makeman from HTML source. The master documentation is at

http://netpbm.sourceforge.net/doc/pamstereogram.html

And that's the whole page, bestie 🎀 this was the netpbm documentation version dated 2 January 2021, and look at you, Pamstereog...User Manual(1) read all the way to the end like the absolute icon you are 👑💖 go make some stereograms, you got this ✨

📦 where this page comes from