| 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 "Pamcomp User Manual" 1 "13 August 2011" "netpbm documentation" |
| 7 |
.PP |
| 8 |
.SH NAME |
| 9 |
pamcomp - composite (overlay) two Netpbm images together |
| 10 |
|
| 11 |
.UN synopsis |
| 12 |
.SH SYNOPSIS |
| 13 |
|
| 14 |
\fBpamcomp\fP |
| 15 |
|
| 16 |
[\fB-align=\fP{\fBleft\fP | \fBcenter\fP | \fBright\fP | |
| 17 |
\fBbeyondleft\fP | \fBbeyondright\fP}] |
| 18 |
[\fB-valign=\fP{\fBtop\fP | \fBmiddle\fP | \fBbottom\fP| |
| 19 |
\fBabove\fP | \fBbelow\fP}] |
| 20 |
[\fB-xoff=\fP\fIX\fP] |
| 21 |
[\fB-yoff=\fP\fIY\fP] |
| 22 |
[\fB-alpha=\fP\fIalpha-pgmfile\fP] |
| 23 |
[\fB-invert\fP] |
| 24 |
[\fB-opacity=\fP\fIopacity\fP] |
| 25 |
[\fB-mixtransparency\fP] |
| 26 |
[\fB-linear\fP] |
| 27 |
\fIoverlay_file\fP |
| 28 |
[\fIunderlying_file\fP [\fIoutput_file\fP]] |
| 29 |
.PP |
| 30 |
Minimum unique abbreviation of option is acceptable. You may use double |
| 31 |
hyphens instead of single hyphen to denote options. You may use white |
| 32 |
space in place of the equals sign to separate an option name from its value. |
| 33 |
|
| 34 |
.UN description |
| 35 |
.SH DESCRIPTION |
| 36 |
.PP |
| 37 |
This program is part of |
| 38 |
.BR "Netpbm" (1)\c |
| 39 |
\&. |
| 40 |
|
| 41 |
\fBpamcomp\fP reads two images and produces a composite image with |
| 42 |
one of the images overlayed on top of the other, possible |
| 43 |
translucently. The images need not be the same size. The input and |
| 44 |
outputs are Netpbm format image files. |
| 45 |
.PP |
| 46 |
In its simplest use, \fBpamcomp\fP simply places the image in the |
| 47 |
file \fIoverlay_file\fP on top of the image in the file |
| 48 |
\fIunderlying_file\fP, blocking out the part of \fIunderlying_file\fP |
| 49 |
beneath it. |
| 50 |
.PP |
| 51 |
If you add the \fB-alpha\fP option, then \fBpamcomp\fP uses the |
| 52 |
image in file \fIalpha-pgmfile\fP as a transparency mask, which means it |
| 53 |
determines the level of transparency of each point in the overlay |
| 54 |
image. The transparency mask must have the same dimensions as the overlay |
| 55 |
image. In places where the transparency mask defines the overlay image to be |
| 56 |
opaque, the composite output contains only the contents of the overlay |
| 57 |
image; the underlying image is totally blocked out. In places where |
| 58 |
the transparency mask defines the overlay image to be transparent, the |
| 59 |
composite output contains none of the overlay image; the underlying |
| 60 |
image shows through completely. In places where the transparency mask shows |
| 61 |
a value in between opaque and transparent (translucence), the |
| 62 |
composite image contains a mixture of the overlay image and the |
| 63 |
underlying image and the level of translucence determines how much of |
| 64 |
each. |
| 65 |
.PP |
| 66 |
The transparency mask is a PGM file in which a white pixel represents |
| 67 |
opaqueness and a black pixel transparency. Anything in between is |
| 68 |
translucent. (Like any Netpbm program, \fBpamcomp\fP will see a PBM |
| 69 |
file as if it is PGM). |
| 70 |
.PP |
| 71 |
If the overlay image is a PAM image of tuple type RGB_ALPHA or |
| 72 |
GRAYSCALE_ALPHA, then the overlay image contains transparency |
| 73 |
information itself and \fBpamcomp\fP uses it the same way as the |
| 74 |
transparency mask described above. If you supply both an overlay image that |
| 75 |
has transparency information and a transparency mask, \fBpamcomp\fP |
| 76 |
multiplies the two opacities to get the opacity of the overlay pixel. |
| 77 |
.PP |
| 78 |
Before Netpbm 10.25 (October 2004), \fBpamcomp\fP did not recognize the |
| 79 |
transparency information in a PAM image -- it just ignored it. So people had |
| 80 |
to make appropriate transparency masks in order to have a non-opaque overlay. Some |
| 81 |
Netpbm programs that convert from image formats that contain transparency |
| 82 |
information are not able to create RGB_ALPHA or GRAYSCALE_ALPHA PAM output, so |
| 83 |
you have to use the old method -- extract the transparency information from |
| 84 |
the original into a separate transparency mask and use that as input to |
| 85 |
\fBpamcomp\fP. |
| 86 |
.PP |
| 87 |
The output image is always of the same dimensions as the underlying |
| 88 |
image. \fBpamcomp\fP uses only parts of the overlay image that fit |
| 89 |
within the underlying image. |
| 90 |
.PP |
| 91 |
The output image is a PAM image. Its tuples are color, grayscale, or black |
| 92 |
and white, whichever is the "highest" format between the two input |
| 93 |
images. The maxval of the output is the least common multiple of the maxvals |
| 94 |
of the input, up to the maximum possible PAM maxval, 65535. |
| 95 |
.PP |
| 96 |
The output has an opacity channel if and only if the underlying image does, |
| 97 |
and then the opacities are as described under the \fB-mixtransparency\fP |
| 98 |
option. Before Netpbm 10.56 (September 2011), the output never has an opacity |
| 99 |
channel. |
| 100 |
.PP |
| 101 |
To specify where on the underlying image to place the overlay |
| 102 |
image, use the \fB-align\fP, \fB-valign\fP, \fB-xoff\fP, and |
| 103 |
\fB-yoff\fP options. Without these options, the default horizontal |
| 104 |
position is flush left and the default vertical position is flush top. |
| 105 |
.PP |
| 106 |
The overlay image, in the position you specify, need not fit entirely |
| 107 |
within the underlying image. \fBpamcomp\fP uses only the parts of the |
| 108 |
overlay image that appear above the underlying image. It is possible to |
| 109 |
specify positioning such that \fInone\fP of the overlay image is |
| 110 |
over the underlying image -- i.e. the overlay is out of frame. If you |
| 111 |
do that, \fBpamcomp\fP issues a warning. |
| 112 |
.PP |
| 113 |
The overlay and underlying images may be of different formats |
| 114 |
(e.g. overlaying a PBM text image over a full color PPM image) and |
| 115 |
have different maxvals. The output image has the more general of the |
| 116 |
two input formats and a maxval that is the least common multiple the |
| 117 |
two maxvals (or the maximum maxval allowable by the format, if the LCM |
| 118 |
is more than that). |
| 119 |
|
| 120 |
|
| 121 |
.UN arguments |
| 122 |
.SH ARGUMENTS |
| 123 |
.PP |
| 124 |
The \fIoverlay_file\fP argument is the name of the file containing the |
| 125 |
overly image, while \fIunderlying_file\fP is the name of the file |
| 126 |
containing the underlying image. For either, you may specify '-' |
| 127 |
to indicate Standard Input, and \fIunderlying\fP file defaults to Standard |
| 128 |
Input. Make sure you aren't specifying (or defaulting) Standard Input as |
| 129 |
both. |
| 130 |
.PP |
| 131 |
Note that there may be a third input file, identified by an |
| 132 |
\fB-alphafile\fP option. |
| 133 |
.PP |
| 134 |
The \fIoutput_file\fP argument is the name of the file to which |
| 135 |
\fBpamcomp\fP writes the output, creating or truncating it first. You may |
| 136 |
specify '-' to indicate Standard Output, in which |
| 137 |
case \fBpamcomp\fP does not truncate it. Note that \fBpamcomp\fP is |
| 138 |
unusual among Netpbm programs, as a historical accident, in having an output |
| 139 |
file argument; Netpbm programs normally write to Standard Output only. |
| 140 |
|
| 141 |
|
| 142 |
.UN options |
| 143 |
.SH OPTIONS |
| 144 |
.PP |
| 145 |
In addition to the options common to all programs based on libnetpbm |
| 146 |
(most notably \fB-quiet\fP, see |
| 147 |
.UR index.html#commonoptions |
| 148 |
Common Options |
| 149 |
.UE |
| 150 |
\&), \fBpamcomp\fP recognizes the following |
| 151 |
command line options: |
| 152 |
|
| 153 |
|
| 154 |
.TP |
| 155 |
\fB-align=\fP\fIalignment\fP |
| 156 |
This option selects the basic horizontal position of the overlay image |
| 157 |
with respect to the underlying image, in syntax reminiscent of HTML. |
| 158 |
\fBleft\fP means flush left, \fBcenter\fP means centered, and \fBright\fP |
| 159 |
means flush right. |
| 160 |
.sp |
| 161 |
The \fB-xoff\fP option modifies this position. |
| 162 |
|
| 163 |
\fBbeyondleft\fP means just out of frame to the left -- the right edge of |
| 164 |
the overlay is flush with the left edge of the underlying image. |
| 165 |
\fBbeyondright\fP means just out of frame to the right. These alignments |
| 166 |
are useful only if you add a \fB-xoff\fP option. These two values were |
| 167 |
added in Netpbm 10.10 (October 2002). |
| 168 |
.sp |
| 169 |
The default is \fBleft\fP. |
| 170 |
|
| 171 |
.TP |
| 172 |
\fB-valign=\fP\fIalignment\fP |
| 173 |
This option selects the basic vertical position of the overlay image |
| 174 |
with respect to the underlying image, in syntax reminiscent of HTML. |
| 175 |
\fBtop\fP means flush top, \fBmiddle\fP means centered, and \fBbottom\fP |
| 176 |
means flush bottom. |
| 177 |
.sp |
| 178 |
The \fB-yoff\fP option modifies this position. |
| 179 |
|
| 180 |
\fBabove\fP means just out of frame to the top -- the bottom edge of |
| 181 |
the overlay is flush with the top edge of the underlying image. |
| 182 |
\fBbelow\fP means just out of frame to the bottom. These alignments |
| 183 |
are useful only if you add a \fB-yoff\fP option. These two values were |
| 184 |
added in Netpbm 10.10 (October 2002). |
| 185 |
.sp |
| 186 |
The default is \fBtop\fP. |
| 187 |
|
| 188 |
.TP |
| 189 |
\fB-xoff=\fP\fIx\fP |
| 190 |
This option modifies the horizontal positioning of the overlay |
| 191 |
image with respect to the underlying image as selected by the |
| 192 |
\fB-align\fP option. \fBpamcomp\fP shifts the overlay image from |
| 193 |
that basic position \fIx\fP pixels to the right. \fIx\fP can be |
| 194 |
negative to indicate shifting to the left. |
| 195 |
.sp |
| 196 |
The overlay need not fit entirely (or at all) on the underlying image. |
| 197 |
\fBpamcomp\fP uses only the parts that lie over the underlying image. |
| 198 |
.sp |
| 199 |
Before Netpbm 10.10 (October 2002), \fB-xoff\fP was mutually |
| 200 |
exclusive with \fB-align\fP and always measured from the left edge. |
| 201 |
|
| 202 |
.TP |
| 203 |
\fB-yoff=\fP\fIy\fP |
| 204 |
This option modifies the vertical positioning of the overlay |
| 205 |
image with respect to the underlying image as selected by the |
| 206 |
\fB-valign\fP option. \fBpamcomp\fP shifts the overlay image from |
| 207 |
that basic position \fIy\fP pixels downward. \fIy\fP can be |
| 208 |
negative to indicate shifting upward. |
| 209 |
.sp |
| 210 |
The overlay need not fit entirely (or at all) on the underlying image. |
| 211 |
\fBpamcomp\fP uses only the parts that lie over the underlying image. |
| 212 |
.sp |
| 213 |
Before Netpbm 10.10 (October 2002), \fB-xoff\fP was mutually |
| 214 |
exclusive with \fB-valign\fP and always measured from the top edge. |
| 215 |
|
| 216 |
.TP |
| 217 |
\fB-alpha=\fP\fIalpha-pgmfile\fP |
| 218 |
This option names a file that contains the transparency mask. If you don't |
| 219 |
specify this option, there is no transparency mask, which is equivalent to |
| 220 |
having a transparency mask specify total opaqueness everywhere. |
| 221 |
.sp |
| 222 |
You can specify \fB-\fP as the value of this option and the transparency |
| 223 |
mask will come from Standard Input. If you do this, don't specify |
| 224 |
Standard Input as the source of any other input image. |
| 225 |
|
| 226 |
.TP |
| 227 |
\fB-invert\fP |
| 228 |
This option inverts the sense of the values in the transparency mask, which |
| 229 |
effectively switches the roles of the overlay image and the underlying |
| 230 |
image in places where the two intersect. |
| 231 |
|
| 232 |
.TP |
| 233 |
\fB-opacity=\fP\fIopacity\fP |
| 234 |
This option tells how opaque the overlay image is to be, i.e. how much |
| 235 |
of the composite image should be from the overlay image, as opposed to |
| 236 |
the underlying image. \fIopacity\fP is a floating point number, with |
| 237 |
1.0 meaning the overlay image is totally opaque and 0.0 meaning it is |
| 238 |
totally transparent. The default is 1.0. |
| 239 |
.sp |
| 240 |
If you specify a transparency mask (the \fB-alpha\fP option), |
| 241 |
\fBpamcomp\fP uses the product of the opacity indicated by the transparency |
| 242 |
mask (as modified by the \fB-invert\fP option, as a fraction, and |
| 243 |
this opacity value. The \fB-invert\fP option does not apply to this |
| 244 |
opacity value. |
| 245 |
.sp |
| 246 |
As a simple opacity value, the value makes sense only if it is |
| 247 |
between 0 and 1, inclusive. However, \fBpamcomp\fP accepts all |
| 248 |
values and performs the same arithmetic computation using whatever |
| 249 |
value you provide. An opacity value less than zero means the underlay |
| 250 |
image is intensified and then the overlay image is "subtracted" from |
| 251 |
it. An opacity value greater than unity means the overlay image is |
| 252 |
intensified and the underlay image subtracted from it. In either |
| 253 |
case, \fBpamcomp\fP clips the resulting color component intensities |
| 254 |
so they are nonnegative and don't exceed the output image's maxval. |
| 255 |
.sp |
| 256 |
This may seem like a strange thing to do, but it has uses. You can use it |
| 257 |
to brighten or darken or saturate or desaturate areas of the underlay image. |
| 258 |
See |
| 259 |
.BR " this description" (1)\c |
| 260 |
\& of the technique. |
| 261 |
.sp |
| 262 |
This option was added in Netpbm 10.6 (July 2002). Before Netpbm 10.15 |
| 263 |
(April 2003), values less than zero or greater than unity were not allowed. |
| 264 |
|
| 265 |
.TP |
| 266 |
\fB-mixtransparency\fP |
| 267 |
This option controls what \fBpamcomp\fP does where both the underlying and |
| 268 |
overlay image are non-opaque. |
| 269 |
.sp |
| 270 |
By default, the output image has the same transparency as the underlying |
| 271 |
image and the transparency of the underlying image has no effect on the |
| 272 |
composition of color. |
| 273 |
.sp |
| 274 |
But with this option, \fBpamcomp\fP composes the image according to a |
| 275 |
plastic transparency metaphor: the underlying and overlay images are plastic |
| 276 |
slides. The output image is the slide you get when you stack up those two |
| 277 |
slides. So the transparency of the output is a combination of the |
| 278 |
transparency of the inputs and the transparency of the underlying image |
| 279 |
affects the underlying image's contribution to the output image's color. |
| 280 |
.sp |
| 281 |
Unlike the metaphorical slide, a PAM pixel has a color even where it is |
| 282 |
completely transparent, so \fBpamcomp\fP departs from the metaphor in that |
| 283 |
case and makes the output color identical to the underlying image. |
| 284 |
.sp |
| 285 |
This option was new in Netpbm 10.56 (September 2011). Before that, the |
| 286 |
output is always opaque and the \fBpamcomp\fP ignores the transparency of the |
| 287 |
underlying image. |
| 288 |
|
| 289 |
.TP |
| 290 |
\fB-linear\fP |
| 291 |
This option indicates that the inputs are not true Netpbm images but |
| 292 |
rather a light-intesity-proportional variation. This is relevant only when |
| 293 |
you mix pixels, using the \fB-opacity\fP option or a transparency mask |
| 294 |
(the \fB-alpha\fP option). |
| 295 |
.sp |
| 296 |
The transparency mask and \fB-opacity\fP values indicate a fraction of |
| 297 |
the light intensity of a pixel. But the PNM and PNM-equivalent PAM |
| 298 |
image formats represent intensities with gamma-adjusted numbers that |
| 299 |
are not linearly proportional to intensity. So \fBpamcomp\fP, by |
| 300 |
default, performs a calculation on each sample read from its input and |
| 301 |
each sample written to its output to convert between these |
| 302 |
gamma-adjusted numbers and internal intensity-proportional numbers. |
| 303 |
.sp |
| 304 |
Sometimes you are not working with true PNM or PAM images, but |
| 305 |
rather a variation in which the sample values are in fact directly |
| 306 |
proportional to intensity. If so, use the \fB-linear\fP option to |
| 307 |
tell \fBpamcomp\fP this. \fBpamcomp\fP then will skip the |
| 308 |
conversions. |
| 309 |
.sp |
| 310 |
The conversion takes time. And the difference between |
| 311 |
intensity-proportional values and gamma-adjusted values may be small |
| 312 |
enough that you would barely see a difference in the result if you |
| 313 |
just pretended that the gamma-adjusted values were in fact |
| 314 |
intensity-proportional. So just to save time, at the expense of some |
| 315 |
image quality, you can specify \fB-linear\fP even when you have true |
| 316 |
PPM input and expect true PPM output. |
| 317 |
.sp |
| 318 |
For the first 13 years of Netpbm's life, until Netpbm 10.20 |
| 319 |
(January 2004), \fBpamcomp\fP's predecessor \fBpnmcomp\fP always |
| 320 |
treated the PPM samples as intensity-proportional even though they |
| 321 |
were not, and drew few complaints. So using \fB-linear\fP as a lie |
| 322 |
is a reasonable thing to do if speed is important to you. |
| 323 |
.sp |
| 324 |
Another technique to consider is to convert your PNM image to the |
| 325 |
linear variation with \fBpnmgamma\fP, run \fBpamcomp\fP on it and |
| 326 |
other transformations that like linear PNM, and then convert it back |
| 327 |
to true PNM with \fBpnmgamma -ungamma\fP. \fBpnmgamma\fP is often |
| 328 |
faster than \fBpamcomp\fP in doing the conversion. |
| 329 |
|
| 330 |
|
| 331 |
|
| 332 |
|
| 333 |
.UN seealso |
| 334 |
.SH SEE ALSO |
| 335 |
.PP |
| 336 |
.BR "pammixmulti.html" (1)\c |
| 337 |
\& mixes together |
| 338 |
two or more images of the same size, in various ways. |
| 339 |
.PP |
| 340 |
.BR "ppmmix" (1)\c |
| 341 |
\& and |
| 342 |
.BR "pnmpaste" (1)\c |
| 343 |
\& are simpler, less general |
| 344 |
versions of the same tool. |
| 345 |
.PP |
| 346 |
.BR "ppmcolormask" (1)\c |
| 347 |
\& and |
| 348 |
.BR "pbmmask" (1)\c |
| 349 |
\&, and |
| 350 |
.BR "\fBpambackground\fP" (1)\c |
| 351 |
\& can help with |
| 352 |
generating a transparency mask. |
| 353 |
.PP |
| 354 |
.BR "pnmcomp" (1)\c |
| 355 |
\& is an older program that |
| 356 |
runs faster, but has less function. |
| 357 |
.PP |
| 358 |
.BR "pnm" (1)\c |
| 359 |
\& |
| 360 |
|
| 361 |
|
| 362 |
.UN history |
| 363 |
.SH HISTORY |
| 364 |
.PP |
| 365 |
\fBpamcomp\fP was new in Netpbm 10.21 (March 2004). Its predecessor, |
| 366 |
\fBpnmcomp\fP, was one of the first programs added to Netpbm when the |
| 367 |
project went global in 1993. |
| 368 |
|
| 369 |
|
| 370 |
.UN author |
| 371 |
.SH AUTHOR |
| 372 |
|
| 373 |
Copyright (C) 1992 by David Koblas (\[email protected]\fP). |
| 374 |
.SH DOCUMENT SOURCE |
| 375 |
This manual page was generated by the Netpbm tool 'makeman' from HTML |
| 376 |
source. The master documentation is at |
| 377 |
.IP |
| 378 |
.B http://netpbm.sourceforge.net/doc/pamcomp.html |
| 379 |
.PP |