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

FreeBSD Manual Pages


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

       ppmshadow - add simulated shadows to a PPM image

       ppmshadow [-b blur_size]	[-k] [-t] [-x xoffset] [-y yoffset] [ppmfile]

       This program is part of Netpbm(1).

       ppmshadow  adds	a  simulated shadow to an image, giving	the appearance
       that the	contents of the	image float above the page, casting a  diffuse
       shadow  on  the	background.   Shadows  can either be black, as cast by
       opaque objects, or translucent, where the shadow	takes on the color  of
       the object which	casts it.  You can specify the crispness of the	shadow
       and its displacement from the image with	command	line options.

       ppmshadow sees your image as a foreground on a background.   The	 back-
       ground  color  is  whatever  color the top left pixel of	your image is.
       The background is all the pixels	that are that color and	the foreground
       is everything else.  The	shadow that ppmshadow generates	is a shadow of
       the foreground, cast on the background.

       The shadow is the same size as the foreground, plus some	fringes	as de-
       termined	 by the	-b option.  It is truncated to fit in your image.  The
       output image is the same	dimensions as the input	image.

       You can use pamcomp to place a foreground image over a  background  be-
       fore  running  ppmshadow	 on it.	 You can use ppmmake to	make the back-
       ground image (just an image of a	solid color).

       The output has the same dimensions and maxval as	the input.

       The blurring to make the	fringes	of the shadow will not have  a	desir-
       able  effect if the color depth (maxval)	of the image is	too low	-- you
       need a high maxval to get all the shades	needed to create a smooth gra-
       dient.	So if your input has low maxval	(including most	notably	if the
       input is	PBM, which means its maxval is 1), run it through pamdepth  to
       raise its maxval.  255 is usually a good	choice.

       Input  is a PPM file named by the ppmfile command line argument;	if you
       don't specify ppmfile, the input	is Standard Input.

       The output is a PPM file, written to Standard Output.

       -b blur_size
	      Sets the distance	of the light source from  the  image.	Larger
	      values  move  the	 light	source	closer,	casting	a more diffuse
	      shadow, while smaller settings  move  the	 light	further	 away,
	      yielding a sharper shadow.  blur_size is the number of pixels of
	      fringe there is on the shadow, beyond where the shadow would  be
	      if there were no blurring.

	      The default is 11	pixels.

	      Note  that this option controls only the fringing	effect of mov-
	      ing the light source closer to the object.  It does not make the
	      shadow  grow or shrink as	would happpen in the real world	if you
	      moved a point light source closer	to and further from an object.

       -k     Keep the intermediate temporary image  files.   When  debugging,
	      these  intermediate files	provide	many clues as to the source of
	      an error.	 See below <#files>  for a list	 of  the  contents  of
	      each file.

       -t     Consider the non-background material in the image	translucent --
	      it casts shadows of its own color	rather than  a	black  shadow,
	      which  is	 default.   This often results in fuzzy, difficult-to-
	      read images but in some circumstances may	look better.

       -x xoffset
	      Specifies	the displacement of the	light source to	 the  left  of
	      the  image.   Larger  settings of	xoffset	displace the shadow to
	      the right, as would be cast by a light further to	the left.   If
	      not  specified,  the  horizontal	offset	is  half  of blur_size
	      (above), to the left.

       -y yoffset
	       Specifies the displacement of the light source above the	top of
	      the image.  Larger settings displace the shadow downward,	corre-
	      sponding to moving the light further above the top of the	image.
	      If  you  don't  specify  -y, the vertical	offset defaults	to the
	      same as the horizontal offset (above), upward.

       The source image	must contain sufficient	space on the edges in the  di-
       rection	in  which  the	shadow	is cast	to contain the shadow -- if it
       doesn't some of the internal steps may fail.  You  can  usually	expand
       the  border  of	a too-tightly-cropped image with pnmmargin before pro-
       cessing it with ppmshadow.

       Black pixels and	pixels with the	same color  as	the  image  background
       don't  cast  a  shadow.	 If  this  causes unintentional	"holes"	in the
       shadow, fill the	offending areas	with a color which differs from	 black
       or  the	background  by RGB values of 1,	which will be imperceptible to
       the viewer.  Since the comparison is exact, the modified	areas will now
       cast shadows.

       The  background	color  of  the source image (which is preserved	in the
       output) is deemed to be the color of the	pixel at the top left  of  the
       input  image.  If that pixel isn't part of the background, simply add a
       one-pixel border	at the top of the image, generate  the	shadow	image,
       then delete the border from it.

       If something goes wrong along the way, the error	messages from the var-
       ious Netpbm programs ppmshadow calls will, in general,  provide	little
       or  no  clue  as	to where ppmshadow went	astray.	 In this case, Specify
       the -k option and examine the intermediate  results  in	the  temporary
       files  (which this option causes	to be preserved).  If you manually run
       the commands that ppmshadow runs	on these files,	 you  can  figure  out
       where  the  problem  is.	  In  problem cases where you want to manually
       tweak the image generation process along	the way, you can keep the  in-
       termediate files	with the -k  option, modify them appropriately with an
       image editor, then recombine them with the steps	used by	 the  code  in

       Shadows	are  by	default	black, as cast by opaque material in the image
       occluding white light.  Use the -t option to simulate translucent mate-
       rial,  where the	shadow takes on	the color of the object	that casts it.
       If the contrast between the image and background	is  insufficient,  the
       -t option may yield unattractive	results	which resemble simple blurring
       of the original image.

       Because Netpbm used to have a maximum maxval of 255, which  meant  that
       the  largest  convolution  kernel  pnmconvol  could  use	 was 11	by 11,
       ppmshadow includes a horrid, CPU-time-burning kludge which, if  a  blur
       of  greater  than 11 is requested, performs an initial convolution with
       an 11 x 11 kernel, then calls pnmsmooth (which is itself	a program that
       calls  pnmconvol	 with  a  3 x 3	kernel)	as many	times as the requested
       blur exceeds 11.	 It's ugly, but	it gets	the job	done on	those rare oc-
       casions where you need a	blur greater than 11.

       If  you	wish to	generate an image at high resolution, then scale it to
       publication size	with pamscale in order to eliminate  jagged  edges  by
       resampling, it's	best to	generate the shadow in the original high reso-
       lution image, prior to scaling it down in size.	If you scale first and
       then  add the shadow, you'll get	an unsightly jagged stripe between the
       edge of material	and its	shadow,	due to resampled  pixels  intermediate
       between the image and background	obscuring the shadow.

       ppmshadow  returns status 0 if processing was completed without errors,
       and a nonzero Unix error	code if	an error prevented generation of  out-
       put.  Some errors may result in the script aborting, usually displaying
       error messages from various Netpbm components it	uses, without  return-
       ing  a  nonzero error code.  When this happens, the output file will be
       empty, so be sure to test this if you need to know if the program  suc-

       pnm(5), pnmmargin(1), pnmconvol(1), pamscale(1),	pnmsmooth(1), ppm(5)

       ppmshadow  creates a number of temporary	files as it executes.  It cre-
       ates a new directory for	them in	the directory named by the TMPDIR  en-
       vironment variable, defaulting to /tmp if it is not set.

       In  normal  operation,  ppmshadow finds a unique	name for the temporary
       directory and deletes each temporary file as soon as it is done with it
       and leaves no debris around after it completes.	To preserve the	inter-
       mediate files for debugging, use	the -k command line option.   In  that
       case,  the  directory name is ppmshadowpid, where pid is	the process ID
       of the ppmshadow	process, and the program  fails	 if  ppmshadow	cannot
       create that directory because the name is already in use.

       The temporary files are:

	      A	copy of	the input.

	      Blank image with background of source image

	      Positive binary mask

	      Convolution kernel for blurring shadow

	      Blurred shadow image before coloring

	      Blurred, colored shadow image

	      Clipped shadow image, offset as requested

	      Generated	shadow times positive mask

       John  Walker <>	August
       8, 1997

       This software is	in the public domain.  Permission to use,  copy,  mod-
       ify, and	distribute this	software and its documentation for any purpose
       and without fee is hereby granted, without any conditions  or  restric-

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

netpbm documentation		 24 June 2017	      Ppmshadow	User Manual(0)


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

home | help