path: root/upstream/mageia-cauldron/man1/ppmshadow.1

\
.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
.\" the corresponding HTML page on the Netpbm website, generate a patch
.\" against that, and send it to the Netpbm maintainer.
.TH "Ppmshadow User Manual" 0 "24 June 2017" "netpbm documentation"

.SH NAME
ppmshadow - add simulated shadows to a PPM image

.UN synopsis
.SH SYNOPSIS

\fBppmshadow\fP
[\fB-b\fP \fIblur_size\fP]
[\fB-k\fP]
[\fB-t\fP]
[\fB-x\fP \fIxoffset\fP]
[\fB-y\fP \fIyoffset\fP]
[\fIppmfile\fP]


.UN description
.SH DESCRIPTION
.PP
This program is part of
.BR "Netpbm" (1)\c
\&.
.PP
\fBppmshadow\fP 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.
.PP
\fBppmshadow\fP 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 \fBppmshadow\fP generates is a
shadow of the foreground, cast on the background.
.PP
The shadow is the same size as the foreground, plus some fringes
as determined by the \fB-b\fP option.  It is truncated to fit in your
image.  The output image is the same dimensions as the input image.
.PP
You can use \fBpamcomp\fP to place a foreground image over a background
before running \fBppmshadow\fP on it.  You can use \fBppmmake\fP to make
the background image (just an image of a solid color).
.PP
The output has the same dimensions and maxval as the input.
.PP
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 \fBpamdepth\fP to raise its maxval.  255 is
usually a good choice.
.PP
Input is a PPM file named by the \fIppmfile\fP command line argument; if
you don't specify \fIppmfile\fP, the input is Standard Input.
.PP
The output is a PPM file, written to Standard Output.


.UN options
.SH OPTIONS

\fBppmshadow\fP recognizes the following command line options:


.TP
\fB-b\fP \fIblur_size\fP
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.  \fIblur_size\fP is the number of pixels of fringe there is
on the shadow, beyond where the shadow would be if there were no
blurring.
.sp
The default is 11 pixels.
.sp
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.

.TP
\fB-k\fP
Keep the intermediate temporary image files.  When debugging, these
intermediate files provide many clues as to the source of an error.
See 
.UR #tempfiles
below
.UE
\& for a list of the contents of each file.

.TP
\fB-t\fP
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.

.TP
\fB-x\fP\fI xoffset\fP
Specifies the displacement of the light source to the left of the
image.  Larger settings of \fBxoffset\fP 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 \fIblur_size \fP (above),
to the left.

.TP
\fB-y\fP\fI yoffset\fP
 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 \fB-y\fP, the vertical offset defaults to the
same as the horizontal offset (above), upward.


.PP
\fBppmshadow\fP does not recognize the options common to all
programs based on libnetpbm (See 
.UR index.html#commonoptions
 Common Options
.UE
\&.)  However, the \fB-version\fP option works.

.UN limitations
.SH LIMITATIONS
.PP
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 \fBpnmmargin\fP before
processing it with \fBppmshadow\fP.
.PP
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.  
.PP
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.
.PP
If something goes wrong along the way, the error messages from the
various Netpbm programs \fBppmshadow\fP calls will, in general,
provide little or no clue as to where \fBppmshadow\fP went astray.
In this case, Specify the \fB-k\fP option and examine the
intermediate results in the temporary files (which this option causes
to be preserved).  If you manually run the commands that
\fBppmshadow\fP 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 \fB-k \fP option, modify them appropriately with an
image editor, then recombine them with the steps used by the code in
\fBppmshadow\fP.
.PP
Shadows are by default black, as cast by opaque material in the
image occluding white light.  Use the \fB-t\fP 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 \fB-t\fP option may yield
unattractive results which resemble simple blurring of the original
image.
.PP
Because Netpbm used to have a maximum maxval of 255, which meant
that the largest convolution kernel \fBpnmconvol\fP could use was 11
by 11, \fBppmshadow\fP 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 \fBpnmsmooth\fP
(which is itself a program that calls \fBpnmconvol\fP 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.
.PP
If you wish to generate an image at high resolution, then scale it
to publication size with \fBpamscale\fP 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.

.UN exitstatus
.SH EXIT STATUS

\fBppmshadow\fP 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.

.UN tempfiles
.SH TEMPORARY FILES
.PP
\fBppmshadow\fP creates a number of temporary files as it executes.  It
creates a new directory for them in the directory named by the
\fBTMPDIR\fP environment variable, defaulting to \fB/tmp\fP if it is not
set.
.PP
In normal operation, \fBppmshadow\fP 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
\fB-k\fP command line option.  In that case, the directory name is
\fBppmshadow\fP\fIpid\fP, where \fIpid\fP is the process ID of
the \fBppmshadow\fP process, and the program fails if \fBppmshadow\fP cannot
create that directory because the name is already in use.
.PP
The temporary files are: 


.TP
\fBinfile.ppm\fP
A copy of the input.

.TP
\fBbackground.ppm\fP
Blank image with background of source image

.TP
\fBbgmask.ppm\fP
Positive binary mask

.TP
\fBconvkernel.ppm\fP
Convolution kernel for blurring shadow

.TP
\fBblurredlackshad.ppm\fP
Blurred shadow image before coloring

.TP
\fBblurred.ppm\fP
Blurred, colored shadow image

.TP
\fBshadow.ppm\fP
Clipped shadow image, offset as requested

.TP
\fBshadback.ppm\fP
Generated shadow times positive mask




.UN seealso
.SH SEE ALSO
.BR "pnm" (1)\c
\&,
.BR "pnmmargin" (1)\c
\&,
.BR "pnmconvol" (1)\c
\&,
.BR "pamscale" (1)\c
\&,
.BR "pnmsmooth" (1)\c
\&,
.BR "ppm" (1)\c
\&

.UN author
.SH AUTHOR

John Walker 
.UR http://www.fourmilab.ch
http://www.fourmilab.ch
.UE
\& August
8, 1997

.UN copyright
.SH 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.
.SH DOCUMENT SOURCE
This manual page was generated by the Netpbm tool 'makeman' from HTML
source.  The master documentation is at
.IP
.B http://netpbm.sourceforge.net/doc/ppmshadow.html
.PP