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 ⟨#tempfiles⟩  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 ⟨index.html#commonoptions⟩ .)  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 ⟨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