| 1 |
\ |
| 2 |
.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. |
| 3 |
.\" Do not hand-hack it! If you have bug fixes or improvements, please find |
| 4 |
.\" the corresponding HTML page on the Netpbm website, generate a patch |
| 5 |
.\" against that, and send it to the Netpbm maintainer. |
| 6 |
.TH "Ppmshadow User Manual" 1 "24 June 2017" "netpbm documentation" |
| 7 |
|
| 8 |
.SH NAME |
| 9 |
ppmshadow - add simulated shadows to a PPM image |
| 10 |
|
| 11 |
.UN synopsis |
| 12 |
.SH SYNOPSIS |
| 13 |
|
| 14 |
\fBppmshadow\fP |
| 15 |
[\fB-b\fP \fIblur_size\fP] |
| 16 |
[\fB-k\fP] |
| 17 |
[\fB-t\fP] |
| 18 |
[\fB-x\fP \fIxoffset\fP] |
| 19 |
[\fB-y\fP \fIyoffset\fP] |
| 20 |
[\fIppmfile\fP] |
| 21 |
|
| 22 |
|
| 23 |
.UN description |
| 24 |
.SH DESCRIPTION |
| 25 |
.PP |
| 26 |
This program is part of |
| 27 |
.BR "Netpbm" (1)\c |
| 28 |
\&. |
| 29 |
.PP |
| 30 |
\fBppmshadow\fP adds a simulated shadow to an image, giving the |
| 31 |
appearance that the contents of the image float above the page, |
| 32 |
casting a diffuse shadow on the background. Shadows can either be |
| 33 |
black, as cast by opaque objects, or translucent, where the shadow |
| 34 |
takes on the color of the object which casts it. You can specify the |
| 35 |
crispness of the shadow and its displacement from the image with command |
| 36 |
line options. |
| 37 |
.PP |
| 38 |
\fBppmshadow\fP sees your image as a foreground on a background. |
| 39 |
The background color is whatever color the top left pixel of your image is. |
| 40 |
The background is all the pixels that are that color and the foreground |
| 41 |
is everything else. The shadow that \fBppmshadow\fP generates is a |
| 42 |
shadow of the foreground, cast on the background. |
| 43 |
.PP |
| 44 |
The shadow is the same size as the foreground, plus some fringes |
| 45 |
as determined by the \fB-b\fP option. It is truncated to fit in your |
| 46 |
image. The output image is the same dimensions as the input image. |
| 47 |
.PP |
| 48 |
You can use \fBpamcomp\fP to place a foreground image over a background |
| 49 |
before running \fBppmshadow\fP on it. You can use \fBppmmake\fP to make |
| 50 |
the background image (just an image of a solid color). |
| 51 |
.PP |
| 52 |
The output has the same dimensions and maxval as the input. |
| 53 |
.PP |
| 54 |
The blurring to make the fringes of the shadow will not have a desirable |
| 55 |
effect if the color depth (maxval) of the image is too low -- you need a high |
| 56 |
maxval to get all the shades needed to create a smooth gradient. So if your |
| 57 |
input has low maxval (including most notably if the input is PBM, which means |
| 58 |
its maxval is 1), run it through \fBpamdepth\fP to raise its maxval. 255 is |
| 59 |
usually a good choice. |
| 60 |
.PP |
| 61 |
Input is a PPM file named by the \fIppmfile\fP command line argument; if |
| 62 |
you don't specify \fIppmfile\fP, the input is Standard Input. |
| 63 |
.PP |
| 64 |
The output is a PPM file, written to Standard Output. |
| 65 |
|
| 66 |
|
| 67 |
.UN options |
| 68 |
.SH OPTIONS |
| 69 |
|
| 70 |
\fBppmshadow\fP recognizes the following command line options: |
| 71 |
|
| 72 |
|
| 73 |
.TP |
| 74 |
\fB-b\fP \fIblur_size\fP |
| 75 |
Sets the distance of the light source from the image. Larger values |
| 76 |
move the light source closer, casting a more diffuse shadow, while |
| 77 |
smaller settings move the light further away, yielding a sharper |
| 78 |
shadow. \fIblur_size\fP is the number of pixels of fringe there is |
| 79 |
on the shadow, beyond where the shadow would be if there were no |
| 80 |
blurring. |
| 81 |
.sp |
| 82 |
The default is 11 pixels. |
| 83 |
.sp |
| 84 |
Note that this option controls only the fringing effect of moving |
| 85 |
the light source closer to the object. It does not make the shadow |
| 86 |
grow or shrink as would happpen in the real world if you moved a point |
| 87 |
light source closer to and further from an object. |
| 88 |
|
| 89 |
.TP |
| 90 |
\fB-k\fP |
| 91 |
Keep the intermediate temporary image files. When debugging, these |
| 92 |
intermediate files provide many clues as to the source of an error. |
| 93 |
See |
| 94 |
.UR #tempfiles |
| 95 |
below |
| 96 |
.UE |
| 97 |
\& for a list of the contents of each file. |
| 98 |
|
| 99 |
.TP |
| 100 |
\fB-t\fP |
| 101 |
Consider the non-background material in the image translucent -- it |
| 102 |
casts shadows of its own color rather than a black shadow, which is |
| 103 |
default. This often results in fuzzy, difficult-to-read images but in |
| 104 |
some circumstances may look better. |
| 105 |
|
| 106 |
.TP |
| 107 |
\fB-x\fP\fI xoffset\fP |
| 108 |
Specifies the displacement of the light source to the left of the |
| 109 |
image. Larger settings of \fBxoffset\fP displace the shadow to the |
| 110 |
right, as would be cast by a light further to the left. If not |
| 111 |
specified, the horizontal offset is half of \fIblur_size \fP (above), |
| 112 |
to the left. |
| 113 |
|
| 114 |
.TP |
| 115 |
\fB-y\fP\fI yoffset\fP |
| 116 |
Specifies the displacement of the light source above the top of |
| 117 |
the image. Larger settings displace the shadow downward, |
| 118 |
corresponding to moving the light further above the top of the image. |
| 119 |
If you don't specify \fB-y\fP, the vertical offset defaults to the |
| 120 |
same as the horizontal offset (above), upward. |
| 121 |
|
| 122 |
|
| 123 |
.PP |
| 124 |
\fBppmshadow\fP does not recognize the options common to all |
| 125 |
programs based on libnetpbm (See |
| 126 |
.UR index.html#commonoptions |
| 127 |
Common Options |
| 128 |
.UE |
| 129 |
\&.) However, the \fB-version\fP option works. |
| 130 |
|
| 131 |
.UN limitations |
| 132 |
.SH LIMITATIONS |
| 133 |
.PP |
| 134 |
The source image must contain sufficient space on the edges in the |
| 135 |
direction in which the shadow is cast to contain the shadow -- if it |
| 136 |
doesn't some of the internal steps may fail. You can usually expand |
| 137 |
the border of a too-tightly-cropped image with \fBpnmmargin\fP before |
| 138 |
processing it with \fBppmshadow\fP. |
| 139 |
.PP |
| 140 |
Black pixels and pixels with the same color as the image |
| 141 |
background don't cast a shadow. If this causes unintentional |
| 142 |
"holes" in the shadow, fill the offending areas with a color |
| 143 |
which differs from black or the background by RGB values of 1, which |
| 144 |
will be imperceptible to the viewer. Since the comparison is exact, |
| 145 |
the modified areas will now cast shadows. |
| 146 |
.PP |
| 147 |
The background color of the source image (which is preserved in |
| 148 |
the output) is deemed to be the color of the pixel at the top left of |
| 149 |
the input image. If that pixel isn't part of the background, simply |
| 150 |
add a one-pixel border at the top of the image, generate the shadow |
| 151 |
image, then delete the border from it. |
| 152 |
.PP |
| 153 |
If something goes wrong along the way, the error messages from the |
| 154 |
various Netpbm programs \fBppmshadow\fP calls will, in general, |
| 155 |
provide little or no clue as to where \fBppmshadow\fP went astray. |
| 156 |
In this case, Specify the \fB-k\fP option and examine the |
| 157 |
intermediate results in the temporary files (which this option causes |
| 158 |
to be preserved). If you manually run the commands that |
| 159 |
\fBppmshadow\fP runs on these files, you can figure out where the |
| 160 |
problem is. In problem cases where you want to manually tweak the |
| 161 |
image generation process along the way, you can keep the intermediate |
| 162 |
files with the \fB-k \fP option, modify them appropriately with an |
| 163 |
image editor, then recombine them with the steps used by the code in |
| 164 |
\fBppmshadow\fP. |
| 165 |
.PP |
| 166 |
Shadows are by default black, as cast by opaque material in the |
| 167 |
image occluding white light. Use the \fB-t\fP option to simulate |
| 168 |
translucent material, where the shadow takes on the color of the |
| 169 |
object that casts it. If the contrast between the image and |
| 170 |
background is insufficient, the \fB-t\fP option may yield |
| 171 |
unattractive results which resemble simple blurring of the original |
| 172 |
image. |
| 173 |
.PP |
| 174 |
Because Netpbm used to have a maximum maxval of 255, which meant |
| 175 |
that the largest convolution kernel \fBpnmconvol\fP could use was 11 |
| 176 |
by 11, \fBppmshadow\fP includes a horrid, CPU-time-burning kludge |
| 177 |
which, if a blur of greater than 11 is requested, performs an initial |
| 178 |
convolution with an 11 x 11 kernel, then calls \fBpnmsmooth\fP |
| 179 |
(which is itself a program that calls \fBpnmconvol\fP with a 3 x 3 |
| 180 |
kernel) as many times as the requested blur exceeds 11. It's ugly, |
| 181 |
but it gets the job done on those rare occasions where you need a blur |
| 182 |
greater than 11. |
| 183 |
.PP |
| 184 |
If you wish to generate an image at high resolution, then scale it |
| 185 |
to publication size with \fBpamscale\fP in order to eliminate jagged |
| 186 |
edges by resampling, it's best to generate the shadow in the original |
| 187 |
high resolution image, prior to scaling it down in size. If you scale |
| 188 |
first and then add the shadow, you'll get an unsightly jagged stripe |
| 189 |
between the edge of material and its shadow, due to resampled pixels |
| 190 |
intermediate between the image and background obscuring the shadow. |
| 191 |
|
| 192 |
.UN exitstatus |
| 193 |
.SH EXIT STATUS |
| 194 |
|
| 195 |
\fBppmshadow\fP returns status 0 if processing was completed without |
| 196 |
errors, and a nonzero Unix error code if an error prevented generation |
| 197 |
of output. Some errors may result in the script aborting, usually |
| 198 |
displaying error messages from various Netpbm components it uses, |
| 199 |
without returning a nonzero error code. When this happens, the output |
| 200 |
file will be empty, so be sure to test this if you need to know if the |
| 201 |
program succeeded. |
| 202 |
|
| 203 |
.UN tempfiles |
| 204 |
.SH TEMPORARY FILES |
| 205 |
.PP |
| 206 |
\fBppmshadow\fP creates a number of temporary files as it executes. It |
| 207 |
creates a new directory for them in the directory named by the |
| 208 |
\fBTMPDIR\fP environment variable, defaulting to \fB/tmp\fP if it is not |
| 209 |
set. |
| 210 |
.PP |
| 211 |
In normal operation, \fBppmshadow\fP finds a unique name for the |
| 212 |
temporary directory and deletes each temporary file as |
| 213 |
soon as it is done with it and leaves no debris around after it |
| 214 |
completes. To preserve the intermediate files for debugging, use the |
| 215 |
\fB-k\fP command line option. In that case, the directory name is |
| 216 |
\fBppmshadow\fP\fIpid\fP, where \fIpid\fP is the process ID of |
| 217 |
the \fBppmshadow\fP process, and the program fails if \fBppmshadow\fP cannot |
| 218 |
create that directory because the name is already in use. |
| 219 |
.PP |
| 220 |
The temporary files are: |
| 221 |
|
| 222 |
|
| 223 |
.TP |
| 224 |
\fBinfile.ppm\fP |
| 225 |
A copy of the input. |
| 226 |
|
| 227 |
.TP |
| 228 |
\fBbackground.ppm\fP |
| 229 |
Blank image with background of source image |
| 230 |
|
| 231 |
.TP |
| 232 |
\fBbgmask.ppm\fP |
| 233 |
Positive binary mask |
| 234 |
|
| 235 |
.TP |
| 236 |
\fBconvkernel.ppm\fP |
| 237 |
Convolution kernel for blurring shadow |
| 238 |
|
| 239 |
.TP |
| 240 |
\fBblurredlackshad.ppm\fP |
| 241 |
Blurred shadow image before coloring |
| 242 |
|
| 243 |
.TP |
| 244 |
\fBblurred.ppm\fP |
| 245 |
Blurred, colored shadow image |
| 246 |
|
| 247 |
.TP |
| 248 |
\fBshadow.ppm\fP |
| 249 |
Clipped shadow image, offset as requested |
| 250 |
|
| 251 |
.TP |
| 252 |
\fBshadback.ppm\fP |
| 253 |
Generated shadow times positive mask |
| 254 |
|
| 255 |
|
| 256 |
|
| 257 |
|
| 258 |
.UN seealso |
| 259 |
.SH SEE ALSO |
| 260 |
.BR "pnm" (1)\c |
| 261 |
\&, |
| 262 |
.BR "pnmmargin" (1)\c |
| 263 |
\&, |
| 264 |
.BR "pnmconvol" (1)\c |
| 265 |
\&, |
| 266 |
.BR "pamscale" (1)\c |
| 267 |
\&, |
| 268 |
.BR "pnmsmooth" (1)\c |
| 269 |
\&, |
| 270 |
.BR "ppm" (1)\c |
| 271 |
\& |
| 272 |
|
| 273 |
.UN author |
| 274 |
.SH AUTHOR |
| 275 |
|
| 276 |
John Walker |
| 277 |
.UR http://www.fourmilab.ch |
| 278 |
http://www.fourmilab.ch |
| 279 |
.UE |
| 280 |
\& August |
| 281 |
8, 1997 |
| 282 |
|
| 283 |
.UN copyright |
| 284 |
.SH COPYRIGHT |
| 285 |
This software is in the public domain. Permission to use, copy, |
| 286 |
modify, and distribute this software and its documentation for any |
| 287 |
purpose and without fee is hereby granted, without any conditions or |
| 288 |
restrictions. |
| 289 |
.SH DOCUMENT SOURCE |
| 290 |
This manual page was generated by the Netpbm tool 'makeman' from HTML |
| 291 |
source. The master documentation is at |
| 292 |
.IP |
| 293 |
.B http://netpbm.sourceforge.net/doc/ppmshadow.html |
| 294 |
.PP |