NAME

       ppmshadow - add simulated shadows to a PPM image

SYNOPSIS

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

DESCRIPTION

       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 background 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 determined 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 before running ppmshadow  on  it.   You
       can use ppmmake to make the background 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 desirable 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  gradient.   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.

OPTIONS

       ppmshadow recognizes the following command line 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 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 moving 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  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,  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.

       ppmshadow does not recognize the options common to all programs based on libnetpbm  (See   Common Options
       .)  However, the -version option works.

LIMITATIONS

       The  source image must contain sufficient space on the edges in the direction 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 processing 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  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 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 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.

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

TEMPORARY FILES

       ppmshadow creates a number of temporary files as it executes.  It creates a new directory for them in the
       directory named by the TMPDIR environment 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
       intermediate 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:

       infile.ppm
              A copy of the input.

       background.ppm
              Blank image with background of source image

       bgmask.ppm
              Positive binary mask

       convkernel.ppm
              Convolution kernel for blurring shadow

       blurredlackshad.ppm
              Blurred shadow image before coloring

       blurred.ppm
              Blurred, colored shadow image

       shadow.ppm
              Clipped shadow image, offset as requested

       shadback.ppm
              Generated shadow times positive mask

SEE ALSO

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

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 documentation for any  purpose  and  without  fee  is  hereby  granted,  without  any  conditions  or
       restrictions.

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/ppmshadow.html

netpbm documentation                              24 June 2017                          Ppmshadow User Manual(1)