ppmshadow  -  add  simulated  shadows to a portable pixmap
       image


SYNOPSIS

       ppmshadow [-b blur_size] [-k] [-t] [-x xoffset] [-y  yoff­
       set] [-u] [pnmfile]


DESCRIPTION

       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 colour of the
       object which casts it.  You can specify the extent of  the
       shadow  and  its  displacement from the image with command
       line options.


OPTIONS

       -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  set­
              tings  move  the  light  further  away,  yielding a
              sharper shadow.  blur_size defaults to 11 pixels.

       -k     Keep the intermediate temporary image files.   When
              debugging,  these  intermediate  files provide many
              clues as to the source  of  an  error.   See  FILES
              below 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  colour
              rather than a black shadow, which is default.  This
              often results in  fuzzy,  difficult-to-read  images
              but in some circumstances may look better.

       -u     Print command syntax and a summary of options.

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

              Specifies the  displacement  of  the  light  source
              above  the  top of the image.  Larger settings dis­
              place the shadow downward, corresponding 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.


FILES

       Input is an anymap named by the pnmfile command line argu­
       ment; if you don't specify pnmfile, the input is the Stan­
       dard Input file.

       Output is a always a PPM file, written to Standard Output.

       pnmfile  creates  a  number  of temporary files as it exe­
       cutes.  It creates them in the /tmp directory, with  names
       of the form:

       _PPMshadowpid-N.ppm

       where  pid  is the process number of the ppmshadow process
       and N is a number identifying the file as described below.
       In  normal operation, ppmshadow deletes temporary files as
       soon as it is done with them and leaves no  debris  around
       after  it  completes.   To preserve the intermediate files
       for debugging, use the -k command line option.

       N in the filename means:

       1      Positive binary mask

       2      Convolution kernel for blurring shadow

       3      Blurred shadow image

       4      Clipped shadow image, offset as requested

       5      Blank image with background of source image

       6      Offset shadow

       7      Inverse mask file

       8      Original image times inverse mask

       9      Generated shadow times positive mask

       10     Shadow times background colour

       The source image must  contain  sufficient  space  on  the
       edges in the direction in which the shadow is cast to con­
       tain 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 processing
       it with ppmshadow.

       Black  pixels  and pixels with the same color as the image
       background don't cast a shadow.  If this  causes  uninten­
       tional  "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 pre­
       served 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  bor­
       der  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 various 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 manu­
       ally 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 pro­
       cess  along  the  way, you can keep the intermediate files
       with the -k option,  modify  them  appropriately  with  an
       image  editor,  then recombine them with the steps used by
       the code in ppmshadow.  See the ppmshadow.doc document for
       additional details and examples of the intermediate files.

       Shadows are by default black, as cast by  opaque  material
       in  the image occluding white light.  Use the -t option to
       simulate translucent material, where the shadow  takes  on
       the  colour  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 sim­
       ple 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×11
       kernel,  then  calls pnmsmooth (which is actually a script
       that calls pnmconvol with a 3×3 kernel) as many  times  as
       the requested blur exceeds 11.  It's ugly, but it gets the

       greater than 11.

       If  you wish to generate an image at high resolution, then
       scale it to publication size with  pnmscale  in  order  to
       eliminate  jagged edges by resampling, it's best to gener­
       ate the shadow in  the  original  high  resolution  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 resam­
       pled pixels intermediate between the image and  background
       obscuring the shadow.


EXIT STATUS

       ppmshadow  returns  status  0  if processing was completed
       without errors, and a nonzero Unix error code if an  error
       prevented generation of output.  Some errors may result in
       the script aborting,  usually  displaying  error  messages
       from  various Netpbm components it uses, without returning
       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 succeeded.


SEE ALSO

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


AUTHOR

       John Walker <http://www.fourmilab.ch> August 8, 1997


COPYRIGHT

       This software is in the public domain.  Permission to use,
       copy, modify, and distribute this software and  its  docu­
       mentation  for  any  purpose  and  without  fee  is hereby
       granted, without any conditions or restrictions.


Man(1) output converted with man2html