Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Pamstereogram User Manual(0)			  Pamstereogram	User Manual(0)

       Table Of	Contents <#contents>

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

       pamstereogram [-help] [-verbose]	[-blackandwhite	| -grayscale | -color]
       [-maxval=value] [-patfile=pamfile] [-texfile=pamfile]  [-bgcolor=color]
       [-smoothing=pixels]  [-xbegin=pixels] [-xshift=pixels] [-yshift=pixels]
       [-magnifypat=scale]  [-guidetop]	  [-guidebottom]   [-guidesize=pixels]
       [-dpi=resolution]     [-crosseyed]     [-makemask]     [-eyesep=inches]
       [-depth=fraction]  [-planes=near_pixels,far_pixels]  [-randomseed=inte-
       ger] [-tileable]	[infile]

       This program is part of Netpbm(1).

       pamstereogram  inputs a depth map (a map	of the distances from your eye
       of the points in	a scene) and outputs a single-image stereogram	(SIS).
       A  SIS  is  a  2-D image	specially designed to appear three dimensional
       when viewed with	relaxed,  slightly  unfocused  eyes.  What's  exciting
       about  single-image  stereograms	 is  that  they	 don't require special
       glasses to view,	although it does require a bit of  practice  to	 train
       your  eyes  to  unfocus properly.  The pamstereogram program provides a
       wealth of control over how the stereogram is generated,	including  the

       o      black and	white, grayscale, or color output

       o      single-image random-dot stereograms (SIRDS), single-image	stere-
	      ograms (SIS) using a tiled image,	or mapped-texture  stereograms

       o      images targeting a given device resolution and eye separation

       o      optional guide boxes to assist in	focusing

       o      the ability to trade off depth levels for	easier viewing

       o      choice of	wall-eyed or cross-eyed	stereograms

       The  output is a	PAM image on standard output.  Options control the ex-
       act 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.

       To make a red/green type	of stereogram (that you	view with 3-D glasses)
       instead,	see ppm3d.

       You may use either single or double hyphens to denote options.  You may
       use either whitespace or	an equals sign to separate an option name from
       its value.

	      Display messages about image sizes and formats and properties of
	      the stereogram being generated.

	      Produce  a  single-image	random-dot black-and-white stereogram.
	      This is the default.

	      Produce a	single-image random-dot	grayscale stereogram.

       -color Produce a	single-image random-dot	color stereogram.

	      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. This
	      option has no effect with	-blackandwhite.

	      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 spec-
	      ify  the	-patfile option	along with -blackandwhite, -grayscale,
	      -color, or -maxval.

	      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 -pat-
	      file, -makemask, or -texfile, and	pamstereogram actually ignores
	      it  with respect to -texfile (but	may not	in a future version of

	      The default is to	begin in the center.

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

	      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).

	      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 <libnetpbm_image.html#colorname> .  The -bgcolor
	      option is	meaningful only	in conjunction with -texfile.

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

	      When used	without	-texfile, attempt to eliminate	artifacts  in-
	      troduced	by  edges  in  the depth map if	pixels is greater than

	      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	stere-
	      ogram's color constraints	when producing a mapped-texture	stere-
	      ogram.  In this case, the	-smoothing option is helpful when  the
	      texture  image includes smooth color transitions (as in a	photo-
	      graph) but makes crisp texture images (as	in a line drawing) ap-
	      pear blurry.

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

	      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

	      Magnify each pixel in the	pattern	file or	each random dot	by in-
	      tegral scaling factor scale. Note	that pamstereogram applies the
	      pattern	magnification  after  pattern  shifting	 (-xshift  and

	      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.

	      Same as -guidebottom, except the guides go at the	top of the im-

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

	      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.

	      Specify the resolution of	the output device in  dots  per	 inch.
	      The  default  is 100 DPI,	which represents a fairly crisp	screen

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

	      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 en-
	      ables 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.

	      Instead  of a stereogram,	output a PAM mask image	showing	color-
	      ing 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 op-
	      tion 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

	      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.

	      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

	      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:

       o      eyesep = 2 * far

       o      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

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

	      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

	      It is useful to specify the seed if you want  to	create	repro-
	      ducible  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).

	      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	 -xbe-

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

       The only	parameter, infile, is the name of an  input  file  that	 is  a
       depth  map  image. If you don't specify infile, the input is from stan-
       dard input.

       The input is a PAM image	of depth 1. Each sample	 represents  the  dis-
       tance  from  the	 eye  that  the	 3-D image at that location should be.
       Lower (darker) numbers mean further from	the eye.

   Input Images
       pamstereogram pays no attention to the image's tuple type  and  ignores
       all planes other	than plane 0.

       Like  any  Netpbm program, pamstereogram	will accept PNM	input as if it
       were the	PAM equivalent.

   Mapped-texture Stereograms
       In a mapped-texture stereogram (MTS), the 3-D image can be  drawn  with
       true  colors.   Unlike  a  SIRDS	or tiled-image SIS, however, the image
       portrayed by an MTS is apparent in normal 2-D viewing.  It appears  re-
       peated multiple times and overlapped with itself, but it	is not hidden.

       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 indicates the colors that
       the program should apply	to the object.

       pamstereogram ignores the texture  image's  background  color  when  it
       overlaps	 copies	 of  the  3-D  object.	 This prevents,	for example, a
       bright-red object on a black background from being drawn	as a  dark-red
       object  (a blend	of 50% bright red and 50% black); instead, the program
       ignores the black and the object	remains	bright red.  A consequence  of
       this  feature is	that an	MTS looks best when the	objects	in the texture
       image have a crisp outline.  Smooth transitions to the background color
       result in unwanted color	artifacts around edges because the program ig-
       nores only exact	matches	with the background color.

       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,  re-
       ducing the number of true-colored pixels	that remain.

       An  MTS can employ a background pattern (-patfile).  In this case, pam-
       stereogram replaces background pixels with pattern pixels in the	 final
       step of generating the image.

       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).

       With  the  default values for -dpi and -eyesep, pattern images that are
       128 pixels wide can tile	seamlessly.

       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 \

       Generate	 a  SIS	 by tiling a PPM file (a prior run with	-verbose indi-
       cates 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  tex-
       ture image) and twice smoothing over background-colored speckles:

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







       o      Harold W.	Thimbleby, Stuart Inglis, and Ian H. Witten.  Display-
	      ing 3D Images: Algorithms	for Single  Image  Random  Dot	Stere-
	      ograms.  In  IEEE	 Computer,  27(10):38-48,  October 1994.  DOI:
	      10.1109/2.318576 <> .

       o      W.   A.	Steer.	  Stereograms:	 Technical   Details.	  URL:

       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).

       A  backward  incompatible  change  to  the  way you request guide boxes
       (-guidetop, -guidebottom, -guidesize happened in	Netpbm 10.61 (December

       Copyright (C) 2006-2020 Scott Pakin,

Table Of Contents

	      SYNOPSIS <#synopsis>


	      DESCRIPTION <#description>


	      OPTIONS <#options>


	      PARAMETERS <#parameters>


	      NOTES <#notes>


	      Input Images <#inputimages>


	      Mapped-texture Stereograms <#mappedtexture>


	      Miscellaneous <#notes_misc>


	      EXAMPLES <#examples>


	      SEE ALSO <#seealso>


	      HISTORY <#history>


	      AUTHOR <#author>

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

netpbm documentation		  10 May 2020	  Pamstereogram	User Manual(0)


Want to link to this manual page? Use this URL:

home | help