382 lines
9.4 KiB
HTML
382 lines
9.4 KiB
HTML
|
||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
<HTML><HEAD><TITLE>Man page of ppmshadow</TITLE>
|
||
</HEAD><BODY>
|
||
<H1>ppmshadow</H1>
|
||
Section: User Commands (1)<BR>Updated: 12 March 2000<BR><A HREF="#index">Index</A>
|
||
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
||
|
||
<A NAME="ixAAB"></A>
|
||
<A NAME="lbAB"> </A>
|
||
<H2>NAME</H2>
|
||
|
||
ppmshadow - add simulated shadows to a portable pixmap image
|
||
<A NAME="lbAC"> </A>
|
||
<H2>SYNOPSIS</H2>
|
||
|
||
<B>ppmshadow</B>
|
||
|
||
[<B>-b</B>
|
||
|
||
<I>blur_size</I>]
|
||
|
||
[<B>-k</B>]
|
||
|
||
[<B>-t</B>]
|
||
|
||
[<B>-x</B>
|
||
|
||
<I>xoffset</I>]
|
||
|
||
[<B>-y</B>
|
||
|
||
<I>yoffset</I>]
|
||
|
||
[<B>-u</B>]
|
||
|
||
[<I>pnmfile</I>]
|
||
|
||
<P>
|
||
<A NAME="ixAAC"></A>
|
||
<P>
|
||
<A NAME="lbAD"> </A>
|
||
<H2>DESCRIPTION</H2>
|
||
|
||
<B>ppmshadow</B>
|
||
|
||
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.
|
||
<P>
|
||
<A NAME="lbAE"> </A>
|
||
<H2>OPTIONS</H2>
|
||
|
||
<P>
|
||
<DL COMPACT>
|
||
<DT id="1"><B>-b</B><I> blur_size</I>
|
||
|
||
<DD>
|
||
<P>
|
||
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.
|
||
<I>blur_size</I>
|
||
|
||
defaults to 11 pixels.
|
||
<BR>
|
||
<DT id="2"><B>-k</B>
|
||
|
||
<DD>
|
||
Keep the intermediate temporary image files. When debugging, these
|
||
intermediate files provide many clues as to the source of an error.
|
||
See
|
||
<B>FILES </B>
|
||
|
||
below for a list of the contents of each file.
|
||
<BR>
|
||
<DT id="3"><B>-t</B>
|
||
|
||
<DD>
|
||
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.
|
||
<BR>
|
||
<DT id="4"><B>-u</B>
|
||
|
||
<DD>
|
||
Print command syntax and a summary of options.
|
||
<BR>
|
||
<DT id="5"><B>-x</B><I> xoffset</I>
|
||
|
||
<DD>
|
||
Specifies the displacement of the light source to the left of the
|
||
image. Larger settings of
|
||
<B>xoffset</B>
|
||
|
||
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
|
||
<I>blur_size </I>
|
||
|
||
(above), to the left.
|
||
<BR>
|
||
<DT id="6"><B>-y</B><I> yoffset</I>
|
||
|
||
<DD>
|
||
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
|
||
<B>-y</B>,
|
||
|
||
the vertical offset defaults to the same as the horizontal offset (above),
|
||
upward.
|
||
<P>
|
||
</DL>
|
||
<A NAME="lbAF"> </A>
|
||
<H2>FILES</H2>
|
||
|
||
Input is an anymap named by the
|
||
<I>pnmfile</I>
|
||
|
||
command line argument; if you don't specify
|
||
<I>pnmfile</I>,
|
||
|
||
the input is the Standard Input file.
|
||
<P>
|
||
|
||
Output is a always a PPM file, written to Standard Output.
|
||
<P>
|
||
|
||
<B>pnmfile</B>
|
||
|
||
creates a number of temporary files as it executes. It creates them
|
||
in the /tmp directory, with names of the form:
|
||
<P>
|
||
|
||
<B>_PPMshadow</B><I>pid</I><B>-</B><I>N</I><B>.ppm</B>
|
||
|
||
<P>
|
||
|
||
where
|
||
<I>pid</I>
|
||
|
||
is the process number of the
|
||
<B>ppmshadow</B>
|
||
|
||
process and
|
||
<I>N </I>
|
||
|
||
is a number identifying the file as described below. In normal
|
||
operation,
|
||
<B>ppmshadow</B>
|
||
|
||
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
|
||
<B>-k </B>
|
||
|
||
command line option.
|
||
<P>
|
||
|
||
<I>N</I>
|
||
|
||
in the filename means:
|
||
<DL COMPACT>
|
||
<DT id="7"><B>1</B>
|
||
|
||
<DD>
|
||
Positive binary mask
|
||
<DT id="8"><B>2</B>
|
||
|
||
<DD>
|
||
Convolution kernel for blurring shadow
|
||
<DT id="9"><B>3</B>
|
||
|
||
<DD>
|
||
Blurred shadow image
|
||
<DT id="10"><B>4</B>
|
||
|
||
<DD>
|
||
Clipped shadow image, offset as requested
|
||
<DT id="11"><B>5</B>
|
||
|
||
<DD>
|
||
Blank image with background of source image
|
||
<DT id="12"><B>6</B>
|
||
|
||
<DD>
|
||
Offset shadow
|
||
<DT id="13"><B>7</B>
|
||
|
||
<DD>
|
||
Inverse mask file
|
||
<DT id="14"><B>8</B>
|
||
|
||
<DD>
|
||
Original image times inverse mask
|
||
<DT id="15"><B>9</B>
|
||
|
||
<DD>
|
||
Generated shadow times positive mask
|
||
<DT id="16"><B>10</B>
|
||
|
||
<DD>
|
||
Shadow times background colour
|
||
<P>
|
||
</DL>
|
||
<A NAME="lbAG"> </A>
|
||
<H2>LIMITATIONS</H2>
|
||
|
||
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
|
||
<B>pnmmargin</B>
|
||
|
||
before processing it with
|
||
<B>ppmshadow</B>.
|
||
|
||
<P>
|
||
|
||
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.
|
||
<P>
|
||
|
||
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.
|
||
<P>
|
||
|
||
If something goes wrong along the way, the error messages from the
|
||
various Netpbm programs
|
||
<B>ppmshadow</B>
|
||
|
||
calls will, in general, provide little or no clue as to where
|
||
<B>ppmshadow</B>
|
||
|
||
went astray.
|
||
In this case,
|
||
Specify the
|
||
<B>-k</B>
|
||
|
||
option and examine the intermediate results in the temporary files
|
||
(which this option causes to be preserved). If you manually run the
|
||
commands that
|
||
<B>ppmshadow</B>
|
||
|
||
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
|
||
<B>-k </B>
|
||
|
||
option, modify them appropriately with an
|
||
image editor, then recombine them with the steps used by the code in
|
||
<B>ppmshadow</B>.
|
||
|
||
See the
|
||
<B>ppmshadow.doc</B>
|
||
|
||
document for additional details and examples of the intermediate
|
||
files.
|
||
<P>
|
||
|
||
Shadows are by default black, as cast by opaque material in the image
|
||
occluding white light. Use the
|
||
<B>-t</B>
|
||
|
||
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
|
||
<B>-t</B>
|
||
|
||
option may yield unattractive results which resemble simple blurring
|
||
of the original image.
|
||
<P>
|
||
|
||
Because Netpbm used to have a maximum maxval of 255, which meant that
|
||
the largest convolution kernel
|
||
<B>pnmconvol</B>
|
||
|
||
could use was 11 by 11,
|
||
<B>ppmshadow</B>
|
||
|
||
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
|
||
<B>pnmsmooth</B>
|
||
|
||
(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.
|
||
<P>
|
||
|
||
If you wish to generate an image at high resolution, then
|
||
scale it to publication size with
|
||
<B>pnmscale</B>
|
||
|
||
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.
|
||
<P>
|
||
<A NAME="lbAH"> </A>
|
||
<H2>EXIT STATUS</H2>
|
||
|
||
<B>ppmshadow</B>
|
||
|
||
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.
|
||
<P>
|
||
<A NAME="lbAI"> </A>
|
||
<H2>SEE ALSO</H2>
|
||
|
||
<B><A HREF="/cgi-bin/man/man2html?5+pnm">pnm</A></B>(5),
|
||
|
||
<B><A HREF="/cgi-bin/man/man2html?1+pnmmargin">pnmmargin</A></B>(1),
|
||
|
||
<B><A HREF="/cgi-bin/man/man2html?1+pnmconvol">pnmconvol</A></B>(1),
|
||
|
||
<B><A HREF="/cgi-bin/man/man2html?1+pnmscale">pnmscale</A></B>(1),
|
||
|
||
<B><A HREF="/cgi-bin/man/man2html?1+pnmsmooth">pnmsmooth</A></B>(1),
|
||
|
||
<B><A HREF="/cgi-bin/man/man2html?5+ppm">ppm</A></B>(5)
|
||
|
||
<P>
|
||
<A NAME="lbAJ"> </A>
|
||
<H2>AUTHOR</H2>
|
||
|
||
John Walker <<A HREF="http://www.fourmilab.ch">http://www.fourmilab.ch</A>> August 8, 1997
|
||
<A NAME="lbAK"> </A>
|
||
<H2>COPYRIGHT</H2>
|
||
|
||
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.
|
||
<P>
|
||
|
||
<HR>
|
||
<A NAME="index"> </A><H2>Index</H2>
|
||
<DL>
|
||
<DT id="17"><A HREF="#lbAB">NAME</A><DD>
|
||
<DT id="18"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
||
<DT id="19"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
||
<DT id="20"><A HREF="#lbAE">OPTIONS</A><DD>
|
||
<DT id="21"><A HREF="#lbAF">FILES</A><DD>
|
||
<DT id="22"><A HREF="#lbAG">LIMITATIONS</A><DD>
|
||
<DT id="23"><A HREF="#lbAH">EXIT STATUS</A><DD>
|
||
<DT id="24"><A HREF="#lbAI">SEE ALSO</A><DD>
|
||
<DT id="25"><A HREF="#lbAJ">AUTHOR</A><DD>
|
||
<DT id="26"><A HREF="#lbAK">COPYRIGHT</A><DD>
|
||
</DL>
|
||
<HR>
|
||
This document was created by
|
||
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
||
using the manual pages.<BR>
|
||
Time: 00:05:25 GMT, March 31, 2021
|
||
</BODY>
|
||
</HTML>
|