phpman > man > ppmshadow(1)

ppmshadow(1)                           General Commands Manual                          ppmshadow(1)



NAME
       ppmshadow - add simulated shadows to a portable pixmap image

SYNOPSIS
       ppmshadow [-b blur_size] [-k] [-t] [-x xoffset] [-y yoffset] [-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 settings  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 set‐
              tings 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.


FILES
       Input  is an anymap named by the pnmfile command line argument; if you don't specify pnmfile,
       the input is the Standard Input file.

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

       pnmfile creates a number of temporary files as it executes.  It creates them in the /tmp  di‐
       rectory, 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 inter‐
       mediate 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


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  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 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 tem‐
       porary 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 edi‐
       tor, 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 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×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 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
       pnmscale  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 obscur‐
       ing the shadow.


EXIT STATUS
       ppmshadow returns status 0 if processing was completed without errors, and a nonzero Unix er‐
       ror 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 documentation for any purpose and without fee is hereby granted, without any
       conditions or restrictions.



                                            12 March 2000                               ppmshadow(1)