| 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 "Pamscale User Manual" 1 "29 June 2020" "netpbm documentation" |
| 7 |
|
| 8 |
.SH NAME |
| 9 |
|
| 10 |
pamscale - scale a Netpbm image |
| 11 |
|
| 12 |
.UN synopsis |
| 13 |
.SH SYNOPSIS |
| 14 |
|
| 15 |
.nf |
| 16 |
\fBpamscale\fP |
| 17 |
[ |
| 18 |
\fIscale_factor\fP |
| 19 |
| |
| 20 |
{\fB-xyfit\fP | \fB-xyfill\fP | \fB-xysize\fP} |
| 21 |
\fIcols\fP \fIrows\fP |
| 22 |
| |
| 23 |
\fB-reduce\fP \fIreduction_factor\fP |
| 24 |
| |
| 25 |
[\fB-xsize=\fP\fIcols\fP | \fB-width=\fP\fIcols\fP | \fB-xscale=\fP\fIfactor\fP] |
| 26 |
[\fB-ysize=\fP\fIrows\fP | \fB-height=\fP\fIrows\fP | \fB-yscale=\fP\fIfactor\fP] |
| 27 |
| |
| 28 |
\fB-pixels\fP \fIn\fP |
| 29 |
] |
| 30 |
[ |
| 31 |
\fB-nomix\fP |
| 32 |
| |
| 33 |
\fB-filter=\fP\fIfunctionName\fP [\fB-window=\fPfunctionName] |
| 34 |
] |
| 35 |
[\fB-linear\fP] |
| 36 |
[\fB-reportonly\fP] |
| 37 |
[\fB-verbose\fP] |
| 38 |
|
| 39 |
[\fIpnmfile\fP] |
| 40 |
|
| 41 |
|
| 42 |
.fi |
| 43 |
.PP |
| 44 |
Minimum unique abbreviation of option is acceptable. You may use |
| 45 |
double hyphens instead of single hyphen to denote options. You may use |
| 46 |
white space in place of the equals sign to separate an option name |
| 47 |
from its value. |
| 48 |
|
| 49 |
.UN description |
| 50 |
.SH DESCRIPTION |
| 51 |
.PP |
| 52 |
This program is part of |
| 53 |
.BR "Netpbm" (1)\c |
| 54 |
\&. |
| 55 |
.PP |
| 56 |
\fBpamscale\fP scales a Netpbm image by a specified factor, or |
| 57 |
scales individually horizontally and vertically by specified factors. |
| 58 |
.PP |
| 59 |
You can either enlarge (scale factor > 1) or reduce (scale factor |
| 60 |
< 1). |
| 61 |
.PP |
| 62 |
\fBpamscale\fP works on multi-image streams, scaling each one |
| 63 |
independently. But before Netpbm 10.49 (December 2009), it scales only the |
| 64 |
first image and ignores the rest of the stream. |
| 65 |
|
| 66 |
.UN scalefactor |
| 67 |
.SS The Scale Factors |
| 68 |
.PP |
| 69 |
The options \fB-width\fP, \fB-height\fP, \fB-xsize\fP, \fB-ysize\fP, |
| 70 |
\fB-xscale\fP, \fB-yscale\fP, \fB-xyfit\fP, \fB-xyfill\fP, \fB-reduce\fP, |
| 71 |
and \fB-pixels\fP control the amount of scaling. For backward compatibility, |
| 72 |
there are also \fB-xysize\fP and the \fIscale_factor\fP argument, but you |
| 73 |
shouldn't use those. |
| 74 |
.PP |
| 75 |
\fB-width\fP and \fB-height\fP specify the width and height in pixels |
| 76 |
you want the resulting image to be. See below for rules when you specify |
| 77 |
one and not the other. |
| 78 |
.PP |
| 79 |
\fB-xsize\fP and \fB-ysize\fP are synonyms for \fB-width\fP and |
| 80 |
\fB-height\fP, respectively. |
| 81 |
.PP |
| 82 |
\fB-xscale\fP and \fB-yscale\fP tell the factor by which you want the |
| 83 |
width and height of the image to change from source to result (e.g. |
| 84 |
\fB-xscale 2\fP means you want to double the width; \fB-xscale .5\fP |
| 85 |
means you want to halve it). See below for rules when you specify one and |
| 86 |
not the other. |
| 87 |
.PP |
| 88 |
When you specify an absolute size or scale factor for both |
| 89 |
dimensions, \fBpamscale\fP scales each dimension independently |
| 90 |
without consideration of the aspect ratio. |
| 91 |
.PP |
| 92 |
If you specify one dimension as a pixel size and don't specify the |
| 93 |
other dimension, \fBpamscale\fP scales the unspecified dimension to |
| 94 |
preserve the aspect ratio. |
| 95 |
.PP |
| 96 |
If you specify one dimension as a scale factor and don't specify |
| 97 |
the other dimension, \fBpamscale\fP leaves the unspecified dimension |
| 98 |
unchanged from the input. |
| 99 |
.PP |
| 100 |
If you specify the \fIscale_factor\fP parameter instead of |
| 101 |
dimension options, that is the scale factor for both dimensions. It |
| 102 |
is equivalent to \fB-xscale=\fP\fIscale_factor\fP\fB |
| 103 |
-yscale=\fP\fIscale_factor\fP. |
| 104 |
.PP |
| 105 |
Specifying the \fB-reduce\fP \fIreduction_factor\fP option is |
| 106 |
equivalent to specifying the \fIscale_factor \fP parameter, where |
| 107 |
\fIscale_factor\fP is the reciprocal of \fIreduction_factor\fP. |
| 108 |
.PP |
| 109 |
\fB-xyfit\fP specifies a bounding box. \fBpamscale\fP scales |
| 110 |
the input image to the largest size that fits within the box, while |
| 111 |
preserving its aspect ratio. \fB-xysize\fP is a synonym for this. |
| 112 |
Before Netpbm 10.20 (January 2004), \fB-xyfit\fP did not exist, but |
| 113 |
\fB-xysize\fP did. |
| 114 |
.PP |
| 115 |
\fB-xyfill\fP is similar, but \fBpamscale\fP scales the input image |
| 116 |
to the smallest size that completely fills the box, while preserving |
| 117 |
its aspect ratio. This option has existed since Netpbm 10.20 (January |
| 118 |
2004). |
| 119 |
.PP |
| 120 |
\fB-pixels\fP specifies a maximum total number of output pixels. |
| 121 |
\fBpamscale\fP scales the image down to that number of pixels. If |
| 122 |
the input image is already no more than that many pixels, |
| 123 |
\fBpamscale\fP just copies it as output; \fBpamscale\fP does not |
| 124 |
scale up with \fB-pixels\fP. |
| 125 |
.PP |
| 126 |
If you enlarge by a factor of 3 or more, you should probably add a |
| 127 |
\fIpnmsmooth\fP step; otherwise, you can see the original pixels in |
| 128 |
the resulting image. |
| 129 |
|
| 130 |
.UN reportonly |
| 131 |
.B \fB-reportonly\fP |
| 132 |
.PP |
| 133 |
The option \fB-reportonly\fP causes \fBpamscale\fP not to scale the |
| 134 |
image, but instead to report to Standard Output what scaling the options and |
| 135 |
the input image dimensions indicate. For example, if you specify |
| 136 |
.nf |
| 137 |
\f(CW -xyfill 100 100 -reportonly \fP |
| 138 |
|
| 139 |
.fi |
| 140 |
and the input image is 500 x 400, \fBpamscale\fP tells you that this means |
| 141 |
scaling by .25 to end up with a 125 x 100 image. |
| 142 |
.PP |
| 143 |
You can use this information with other programs, such as |
| 144 |
\fBpamscalefixed\fP, that don't have as rich facilities as \fBpamscale\fP |
| 145 |
for choosing scale factors. |
| 146 |
.PP |
| 147 |
The output is intended to be convenient for machine processing. In the |
| 148 |
example above, it would be |
| 149 |
|
| 150 |
.nf |
| 151 |
|
| 152 |
500 400 0.250000 0.250000 125 100 |
| 153 |
|
| 154 |
|
| 155 |
.fi |
| 156 |
.PP |
| 157 |
The output is a single line of text per input image, with blank-separated |
| 158 |
tokens as follows. |
| 159 |
|
| 160 |
|
| 161 |
.IP \(bu |
| 162 |
input width in pixels, decimal unsigned integer |
| 163 |
.IP \(bu |
| 164 |
input height in pixels, decimal unsigned integer |
| 165 |
.IP \(bu |
| 166 |
horizontal scale factor, floating point decimal, unsigned |
| 167 |
.IP \(bu |
| 168 |
vertical scale factor, floating point decimal, unsigned |
| 169 |
.IP \(bu |
| 170 |
output width in pixels, decimal unsigned integer |
| 171 |
.IP \(bu |
| 172 |
output height in pixels, decimal unsigned integer |
| 173 |
|
| 174 |
.PP |
| 175 |
\fB-reportonly\fP was new in Netpbm 10.86 (March 2019). |
| 176 |
|
| 177 |
|
| 178 |
.UN usage |
| 179 |
.SS Usage Notes |
| 180 |
.PP |
| 181 |
A useful application of \fBpamscale\fP is to blur an image. Scale |
| 182 |
it down (without \fB-nomix\fP) to discard some information, then |
| 183 |
scale it back up using \fBpamstretch\fP. |
| 184 |
.PP |
| 185 |
Or scale it back up with \fBpamscale\fP and create a "pixelized" image, |
| 186 |
which is sort of a computer-age version of blurring. |
| 187 |
|
| 188 |
|
| 189 |
.UN transparency |
| 190 |
.SS Transparency |
| 191 |
.PP |
| 192 |
\fBpamscale\fP understands transparency and properly mixes pixels |
| 193 |
considering the pixels' transparency. |
| 194 |
.PP |
| 195 |
Proper mixing \fIdoes not\fP mean just mixing the transparency |
| 196 |
value and the color component values separately. In a PAM image, a |
| 197 |
pixel which is not opaque represents a color that contains light of |
| 198 |
the foreground color indicated explicitly in the PAM and light of a |
| 199 |
background color to be named later. But the numerical scale of a |
| 200 |
color component sample in a PAM is as if the pixel is opaque. So a |
| 201 |
pixel that is supposed to contain half-strength red light for the |
| 202 |
foreground plus some light from the background has a red color sample |
| 203 |
that says \fIfull\fP red and a transparency sample that says 50% |
| 204 |
opaque. In order to mix pixels, you have to first convert the color |
| 205 |
sample values to numbers that represent amount of light directly |
| 206 |
(i.e. multiply by the opaqueness) and after mixing, convert back |
| 207 |
(divide by the opaqueness). |
| 208 |
|
| 209 |
.UN imagetype |
| 210 |
.SS Input And Output Image Types |
| 211 |
.PP |
| 212 |
\fBpamscale\fP produces output of the same type (and tuple type if |
| 213 |
the type is PAM) as the input, except if the input is PBM. In that |
| 214 |
case, the output is PGM with maxval 255. The purpose of this is to |
| 215 |
allow meaningful pixel mixing. Note that there is no equivalent |
| 216 |
exception when the input is PAM. If the PAM input tuple type is |
| 217 |
BLACKANDWHITE, the PAM output tuple type is also BLACKANDWHITE, and |
| 218 |
you get no meaningful pixel mixing. |
| 219 |
.PP |
| 220 |
If you want PBM output with PBM input, use \fBpamditherbw\fP to |
| 221 |
convert \fBpamscale\fP's output to PBM. Also consider |
| 222 |
\fBpbmreduce\fP. |
| 223 |
.PP |
| 224 |
\fBpamscale\fP's function is essentially undefined for PAM input |
| 225 |
images that are not of tuple type RGB, GRAYSCALE, BLACKANDWHITE, or |
| 226 |
the _ALPHA variations of those. (By standard Netpbm backward compatibility, |
| 227 |
this includes PBM, PGM, and PPM images). |
| 228 |
.PP |
| 229 |
You might think it would have an obvious effect on other tuple |
| 230 |
types, but remember that the aforementioned tuple types have |
| 231 |
gamma-adjusted sample values, and \fBpamscale\fP uses that fact in |
| 232 |
its calculations. And it treats a transparency plane different from any |
| 233 |
other plane. |
| 234 |
.PP |
| 235 |
\fBpamscale\fP does not simply reject unrecognized tuple types |
| 236 |
because there's a possibility that just by coincidence you can get |
| 237 |
useful function out of it with some other tuple type and the right |
| 238 |
combination of options (consider \fB-linear\fP in particular). |
| 239 |
|
| 240 |
|
| 241 |
.UN methods |
| 242 |
.SS Methods Of Scaling |
| 243 |
.PP |
| 244 |
There are numerous ways to scale an image. \fBpamscale\fP implements |
| 245 |
a bunch of them; you select among them with invocation options. |
| 246 |
|
| 247 |
.UN mixing |
| 248 |
.B Pixel Mixing |
| 249 |
.PP |
| 250 |
Pamscale's default method is pixel mixing. To understand this, imagine the |
| 251 |
source image as composed of square tiles. Each tile is a pixel and has |
| 252 |
uniform color. The tiles are all the same size. Now take a transparent sheet |
| 253 |
the size of the target image, marked with a square grid of tiles the same |
| 254 |
size. Stretch or compress the source image to the size of the sheet and lay |
| 255 |
the sheet over the source. |
| 256 |
.PP |
| 257 |
Each cell in the overlay grid stands for a pixel of the target |
| 258 |
image. For example, if you are scaling a 100x200 image up by 1.5, the |
| 259 |
source image is 100 x 200 tiles, and the transparent sheet is marked |
| 260 |
off in 150 x 300 cells. |
| 261 |
.PP |
| 262 |
Each cell covers parts of multiple tiles. To make the target image, |
| 263 |
just color in each cell with the color which is the average of the colors |
| 264 |
the cell covers -- weighted by the amount of that color it covers. A |
| 265 |
cell in our example might cover 4/9 of a blue tile, 2/9 of a red tile, |
| 266 |
2/9 of a green tile, and 1/9 of a white tile. So the target pixel |
| 267 |
would be somewhat unsaturated blue. |
| 268 |
.PP |
| 269 |
When you are scaling up or down by an integer, the results are |
| 270 |
simple. When scaling up, pixels get duplicated. When scaling down, |
| 271 |
pixels get thrown away. In either case, the colors in the target |
| 272 |
image are a subset of those in the source image. |
| 273 |
.PP |
| 274 |
When the scale factor is weirder than that, the target image can |
| 275 |
have colors that didn't exist in the original. For example, a red |
| 276 |
pixel next to a white pixel in the source might become a red pixel, |
| 277 |
a pink pixel, and a white pixel in the target. |
| 278 |
.PP |
| 279 |
This method tends to replicate what the human eye does as it moves |
| 280 |
closer to or further away from an image. It also tends to replicate |
| 281 |
what the human eye sees, when far enough away to make the pixelization |
| 282 |
disappear, if an image is not made of pixels and simply stretches |
| 283 |
or shrinks. |
| 284 |
|
| 285 |
.UN sampling |
| 286 |
.B Discrete Sampling |
| 287 |
.PP |
| 288 |
Discrete sampling is basically the same thing as pixel mixing except |
| 289 |
that, in the model described above, instead of averaging the colors of |
| 290 |
the tiles the cell covers, you pick the one color that covers the most |
| 291 |
area. |
| 292 |
.PP |
| 293 |
The result you see is that when you enlarge an image, pixels |
| 294 |
get duplicated and when you reduce an image, some pixels get discarded. |
| 295 |
.PP |
| 296 |
The advantage of this is that you end up with an image made from the |
| 297 |
same color palette as the original. Sometimes that's important. |
| 298 |
.PP |
| 299 |
The disadvantage is that it distorts the picture. If you scale up |
| 300 |
by 1.5 horizontally, for example, the even numbered input pixels are |
| 301 |
doubled in the output and the odd numbered ones are copied singly. If |
| 302 |
you have a bunch of one pixel wide lines in the source, you may find |
| 303 |
that some of them stretch to 2 pixels, others remain 1 pixel when you |
| 304 |
enlarge. When you reduce, you may find that some of the lines |
| 305 |
disappear completely. |
| 306 |
.PP |
| 307 |
You select discrete sampling with \fBpamscale\fP's \fB-nomix\fP |
| 308 |
option. |
| 309 |
.PP |
| 310 |
Actually, \fB-nomix\fP doesn't do exactly what I described above. |
| 311 |
It does the scaling in two passes - first horizontal, then vertical. |
| 312 |
This can produce slightly different results. |
| 313 |
.PP |
| 314 |
There is one common case in which one often finds it burdensome to |
| 315 |
have \fBpamscale\fP make up colors that weren't there originally: |
| 316 |
Where one is working with an image format such as GIF that has a |
| 317 |
limited number of possible colors per image. If you take a GIF with |
| 318 |
256 colors, convert it to PPM, scale by .625, and convert back to GIF, |
| 319 |
you will probably find that the reduced image has way more than 256 |
| 320 |
colors, and therefore cannot be converted to GIF. One way to solve |
| 321 |
this problem is to do the reduction with discrete sampling instead of |
| 322 |
pixel mixing. Probably a better way is to do the pixel mixing, but |
| 323 |
then color quantize the result with \fBpnmquant\fP before converting |
| 324 |
to GIF. |
| 325 |
.PP |
| 326 |
When the scale factor is an integer (which means you're scaling |
| 327 |
up), discrete sampling and pixel mixing are identical -- output pixels |
| 328 |
are always just N copies of the input pixels. In this case, though, |
| 329 |
consider using \fBpamstretch\fP instead of \fBpamscale\fP to get the |
| 330 |
added pixels interpolated instead of just copied and thereby get a |
| 331 |
smoother enlargement. |
| 332 |
.PP |
| 333 |
\fBpamscale\fP's discrete sampling is faster than pixel mixing, |
| 334 |
but \fBpamenlarge\fP is faster still. \fBpamenlarge\fP works only |
| 335 |
on integer enlargements. |
| 336 |
.PP |
| 337 |
discrete sampling (\fB-nomix\fP) was new in Netpbm 9.24 (January 2002). |
| 338 |
|
| 339 |
|
| 340 |
.UN resampling |
| 341 |
.B Resampling |
| 342 |
.PP |
| 343 |
Resampling assumes that the source image is a discrete sampling of some |
| 344 |
original continuous image. That is, it assumes there is some non-pixelized |
| 345 |
original image and each pixel of the source image is simply the color of |
| 346 |
that image at a particular point. Those points, naturally, are the |
| 347 |
intersections of a square grid. |
| 348 |
.PP |
| 349 |
The idea of resampling is just to compute that original image, then |
| 350 |
sample it at a different frequency (a grid of a different scale). |
| 351 |
.PP |
| 352 |
The problem, of course, is that sampling necessarily throws away the |
| 353 |
information you need to rebuild the original image. So we have to make |
| 354 |
a bunch of assumptions about the makeup of the original image. |
| 355 |
.PP |
| 356 |
You tell \fBpamscale\fP to use the resampling method by specifying |
| 357 |
the \fB-filter\fP option. The value of this option is the name of a |
| 358 |
function, from the set listed below. |
| 359 |
.PP |
| 360 |
\fBTo explain resampling, we are going to talk about a simple |
| 361 |
one dimensional scaling\fP -- scaling a single row of grayscale |
| 362 |
pixels horizontally. If you can understand that, you can easily |
| 363 |
understand how to do a whole image: Scale each of the rows of the |
| 364 |
image, then scale each of the resulting columns. And scale each of the |
| 365 |
color component planes separately. |
| 366 |
.PP |
| 367 |
As a first step in resampling, \fBpamscale\fP converts the source |
| 368 |
image, which is a set of discrete pixel values, into a continuous step |
| 369 |
function. A step function is a function whose graph is a staircase-y |
| 370 |
thing. |
| 371 |
.PP |
| 372 |
Now, we convolve the step function with a proper scaling of the |
| 373 |
filter function that you identified with \fB-filter\fP. If you don't |
| 374 |
know what the mathematical concept of convolution (convolving) is, you |
| 375 |
are officially lost. You cannot understand this explanation. The |
| 376 |
result of this convolution is the imaginary original continuous image |
| 377 |
we've been talking about. |
| 378 |
.PP |
| 379 |
Finally, we make target pixels by picking values from that function. |
| 380 |
.PP |
| 381 |
To understand what is going on, we use Fourier analysis: |
| 382 |
.PP |
| 383 |
The idea is that the only difference between our step function and |
| 384 |
the original continuous function (remember that we constructed the |
| 385 |
step function from the source image, which is itself a sampling of the |
| 386 |
original continuous function) is that the step function has a bunch of |
| 387 |
high frequency Fourier components added. If we could chop out all the |
| 388 |
higher frequency components of the step function, and know that |
| 389 |
they're all higher than any frequency in the original function, we'd |
| 390 |
have the original function back. |
| 391 |
.PP |
| 392 |
The resampling method \fIassumes\fP that the original function |
| 393 |
was sampled at a high enough frequency to form a perfect sampling. A |
| 394 |
perfect sampling is one from which you can recover exactly the |
| 395 |
original continuous function. The Nyquist theorem says that as long |
| 396 |
as your sample rate is at least twice the highest frequency in your |
| 397 |
original function, the sampling is perfect. So we \fIassume\fP |
| 398 |
that the image is a sampling of something whose highest frequency is |
| 399 |
half the sample rate (pixel resolution) or less. Given that, our |
| 400 |
filtering does in fact recover the original continuous image from the |
| 401 |
samples (pixels). |
| 402 |
.PP |
| 403 |
To chop out all the components above a certain frequency, we just |
| 404 |
multiply the Fourier transform of the step function by a rectangle |
| 405 |
function. |
| 406 |
.PP |
| 407 |
We could find the Fourier transform of the step function, multiply |
| 408 |
it by a rectangle function, and then Fourier transform the result |
| 409 |
back, but there's an easier way. Mathematicians tell us that |
| 410 |
multiplying in the frequency domain is equivalent to convolving in the |
| 411 |
time domain. That means multiplying the Fourier transform of F by a |
| 412 |
rectangle function R is the same as convolving F with the Fourier |
| 413 |
transform of R. It's a lot better to take the Fourier transform of |
| 414 |
R, and build it into \fBpamscale\fP than to have \fBpamscale\fP |
| 415 |
take the Fourier transform of the input image dynamically. |
| 416 |
.PP |
| 417 |
That leaves only one question: What \fIis\fP the Fourier |
| 418 |
transform of a rectangle function? Answer: sinc. Recall from |
| 419 |
math that sinc is defined as sinc(x) = sin(PI*x)/PI*x. |
| 420 |
.PP |
| 421 |
Hence, when you specify \fB-filter=sinc\fP, you are effectively |
| 422 |
passing the step function of the source image through a low pass |
| 423 |
frequency filter and recovering a good approximation of the original |
| 424 |
continuous image. |
| 425 |
|
| 426 |
.B Refiltering |
| 427 |
.PP |
| 428 |
There's another twist: If you simply sample the reconstructed |
| 429 |
original continuous image at the new sample rate, and that new sample |
| 430 |
rate isn't at least twice the highest frequency in the original |
| 431 |
continuous image, you won't get a perfect sampling. In fact, you'll |
| 432 |
get something with ugly aliasing in it. Note that this can't be a |
| 433 |
problem when you're scaling up (increasing the sample rate), because |
| 434 |
the fact that the old sample rate was above the Nyquist level means so |
| 435 |
is the new one. But when scaling down, it's a problem. Obviously, |
| 436 |
you have to give up image quality when scaling down, but aliasing is |
| 437 |
not the best way to do it. It's better just to remove high frequency |
| 438 |
components from the original continuous image before sampling, and |
| 439 |
then get a perfect sampling of that. |
| 440 |
.PP |
| 441 |
Therefore, \fBpamscale\fP filters out frequencies above half the |
| 442 |
new sample rate before picking the new samples. |
| 443 |
|
| 444 |
.B Approximations |
| 445 |
.PP |
| 446 |
Unfortunately, \fBpamscale\fP doesn't do the convolution |
| 447 |
precisely. Instead of evaluating the filter function at every point, |
| 448 |
it samples it -- assumes that it doesn't change any more often than |
| 449 |
the step function does. \fBpamscale\fP could actually do the true |
| 450 |
integration fairly easily. Since the filter functions are built into |
| 451 |
the program, the integrals of them could be too. Maybe someday it |
| 452 |
will. |
| 453 |
.PP |
| 454 |
There is one more complication with the Fourier analysis. sinc |
| 455 |
has nonzero values on out to infinity and minus infinity. That makes |
| 456 |
it hard to compute a convolution with it. So instead, there are |
| 457 |
filter functions that approximate sinc but are nonzero only within a |
| 458 |
manageable range. To get those, you multiply the sinc function by a |
| 459 |
\fIwindow function\fP, which you select with the \fB-window\fP option. The |
| 460 |
same holds for other filter functions that go on forever like sinc. By |
| 461 |
default, for a filter that needs a window function, the window function is the |
| 462 |
Blackman function. Hanning, Hamming, and Kaiser are alternatives. |
| 463 |
|
| 464 |
.B Filter Functions Besides Sinc |
| 465 |
.PP |
| 466 |
The math described above works only with sinc as the filter |
| 467 |
function. \fBpamscale\fP offers many other filter functions, though. |
| 468 |
Some of these approximate sinc and are faster to compute. For most of |
| 469 |
them, I have no idea of the mathematical explanation for them, but |
| 470 |
people do find they give pleasing results. They may not be based on |
| 471 |
resampling at all, but just exploit the convolution that is |
| 472 |
coincidentally part of a resampling calculation. |
| 473 |
.PP |
| 474 |
For some filter functions, you can tell just by looking at the |
| 475 |
convolution how they vary the resampling process from the perfect one |
| 476 |
based on sinc: |
| 477 |
.PP |
| 478 |
The impulse filter assumes that the original continuous image is in |
| 479 |
fact a step function -- the very one we computed as the first step in |
| 480 |
the resampling. This is mathematically equivalent to the discrete |
| 481 |
sampling method. |
| 482 |
.PP |
| 483 |
The box (rectangle) filter assumes the original image is a |
| 484 |
piecewise linear function. Its graph just looks like straight lines |
| 485 |
connecting the pixel values. This is mathematically equivalent to the |
| 486 |
pixel mixing method (but mixing brightness, not light intensity, so |
| 487 |
like \fBpamscale -linear\fP) when scaling down, and interpolation |
| 488 |
(ala \fBpamstretch\fP) when scaling up. |
| 489 |
|
| 490 |
.B Gamma |
| 491 |
.PP |
| 492 |
\fBpamscale\fP assumes the underlying continuous function is a |
| 493 |
function of brightness (as opposed to light intensity), and therefore |
| 494 |
does all this math using the gamma-adjusted numbers found in a PNM or |
| 495 |
PAM image. The \fB-linear\fP option is not available with resampling |
| 496 |
(it causes \fBpamscale\fP to fail), because it wouldn't be useful enough |
| 497 |
to justify the implementation effort. |
| 498 |
.PP |
| 499 |
Resampling (\fB-filter\fP) was new in Netpbm 10.20 (January 2004). |
| 500 |
|
| 501 |
.B The filter and window functions |
| 502 |
.PP |
| 503 |
Here is a list of the function names you can specify for the |
| 504 |
\fB-filter\fP or \fB-window\fPoption. For most of them, you're on your own |
| 505 |
to figure out just what the function is and what kind of scaling it does. |
| 506 |
These are common functions from mathematics. Note that some of these make |
| 507 |
sense only as filter functions and some make sense only as window functions. |
| 508 |
|
| 509 |
|
| 510 |
.TP |
| 511 |
point |
| 512 |
The graph of this is a single point at X=0, Y=1. |
| 513 |
|
| 514 |
.TP |
| 515 |
box |
| 516 |
The graph of this is a rectangle sitting on the X axis and centered |
| 517 |
on the Y axis with height 1 and base 1. |
| 518 |
|
| 519 |
.TP |
| 520 |
triangle |
| 521 |
The graph of this is an isosceles triangle sitting on the X axis |
| 522 |
and centered on the Y axis with height 1 and base 2. |
| 523 |
|
| 524 |
.TP |
| 525 |
quadratic |
| 526 |
.TP |
| 527 |
cubic |
| 528 |
.TP |
| 529 |
catrom |
| 530 |
.TP |
| 531 |
mitchell |
| 532 |
.TP |
| 533 |
gauss |
| 534 |
.TP |
| 535 |
sinc |
| 536 |
.TP |
| 537 |
bessel |
| 538 |
.TP |
| 539 |
hanning |
| 540 |
.TP |
| 541 |
hamming |
| 542 |
.TP |
| 543 |
blackman |
| 544 |
.TP |
| 545 |
kaiser |
| 546 |
.TP |
| 547 |
normal |
| 548 |
.TP |
| 549 |
hermite |
| 550 |
.TP |
| 551 |
lanczos |
| 552 |
Not documented |
| 553 |
|
| 554 |
|
| 555 |
|
| 556 |
.UN linear |
| 557 |
.SS Linear vs Gamma-adjusted |
| 558 |
.PP |
| 559 |
The pixel mixing scaling method described above involves intensities |
| 560 |
of pixels (more precisely, it involves individual intensities of |
| 561 |
primary color components of pixels). But the PNM and PNM-equivalent |
| 562 |
PAM image formats represent intensities with gamma-adjusted numbers |
| 563 |
that are not linearly proportional to intensity. So \fBpamscale\fP, |
| 564 |
by default, performs a calculation on each sample read from its input |
| 565 |
and each sample written to its output to convert between these |
| 566 |
gamma-adjusted numbers and internal intensity-proportional numbers. |
| 567 |
.PP |
| 568 |
Sometimes you are not working with true PNM or PAM images, but |
| 569 |
rather a variation in which the sample values are in fact directly |
| 570 |
proportional to intensity. If so, use the \fB-linear\fP option to |
| 571 |
tell \fBpamscale\fP this. \fBpamscale\fP then will skip the |
| 572 |
conversions. |
| 573 |
.PP |
| 574 |
The conversion takes time. In one experiment, it increased by a factor of |
| 575 |
10 the time required to reduce an image. And the difference between |
| 576 |
intensity-proportional values and gamma-adjusted values may be small enough |
| 577 |
that you would barely see a difference in the result if you just pretended |
| 578 |
that the gamma-adjusted values were in fact intensity-proportional. So just |
| 579 |
to save time, at the expense of some image quality, you can specify |
| 580 |
\fB-linear\fP even when you have true PPM input and expect true PPM output. |
| 581 |
.PP |
| 582 |
For the first 13 years of Netpbm's life, until Netpbm 10.20 |
| 583 |
(January 2004), \fBpamscale\fP's predecessor \fBpnmscale\fP always |
| 584 |
treated the PPM samples as intensity-proportional even though they |
| 585 |
were not, and drew few complaints. So using \fB-linear\fP as a lie |
| 586 |
is a reasonable thing to do if speed is important to you. But if |
| 587 |
speed is important, you also should consider the \fB-nomix\fP option |
| 588 |
and \fBpnmscalefixed\fP. |
| 589 |
.PP |
| 590 |
Another technique to consider is to convert your PNM image to the |
| 591 |
linear variation with \fBpnmgamma\fP, run \fBpamscale\fP on it and |
| 592 |
other transformations that like linear PNM, and then convert it back |
| 593 |
to true PNM with \fBpnmgamma -ungamma\fP. \fBpnmgamma\fP is often |
| 594 |
faster than \fBpamscale\fP in doing the conversion. |
| 595 |
.PP |
| 596 |
With \fB-nomix\fP, \fB-linear\fP has no effect. That's because |
| 597 |
\fBpamscale\fP does not concern itself with the meaning of the sample |
| 598 |
values in this method; \fBpamscale\fP just copies numbers from its |
| 599 |
input to its output. |
| 600 |
|
| 601 |
|
| 602 |
.UN precision |
| 603 |
.SS Precision |
| 604 |
.PP |
| 605 |
\fBpamscale\fP uses floating point arithmetic internally. There |
| 606 |
is a speed cost associated with this. For some images, you can get |
| 607 |
the acceptable results (in fact, sometimes identical results) faster |
| 608 |
with \fBpnmscalefixed\fP, which uses fixed point arithmetic. |
| 609 |
\fBpnmscalefixed\fP may, however, distort your image a little. See |
| 610 |
the \fBpnmscalefixed\fP user manual for a complete discussion of the |
| 611 |
difference. |
| 612 |
|
| 613 |
.UN options |
| 614 |
.SH OPTIONS |
| 615 |
.PP |
| 616 |
In addition to the options common to all programs based on libnetpbm |
| 617 |
(most notably \fB-quiet\fP, see |
| 618 |
.UR index.html#commonoptions |
| 619 |
Common Options |
| 620 |
.UE |
| 621 |
\&), \fBpamscale\fP recognizes the following |
| 622 |
command line options: |
| 623 |
|
| 624 |
|
| 625 |
|
| 626 |
.TP |
| 627 |
\fB-width\fP |
| 628 |
.TP |
| 629 |
\fB-height\fP |
| 630 |
.TP |
| 631 |
\fB-xsize\fP |
| 632 |
.TP |
| 633 |
\fB-ysize\fP |
| 634 |
.TP |
| 635 |
\fB-xscale\fP |
| 636 |
.TP |
| 637 |
\fB-yscale\fP |
| 638 |
.TP |
| 639 |
\fB-xyfit\fP |
| 640 |
.TP |
| 641 |
\fB-xyfill\fP |
| 642 |
.TP |
| 643 |
\fB-reduce\fP |
| 644 |
.TP |
| 645 |
\fB-pixels\fP |
| 646 |
.TP |
| 647 |
\fB-xysize\fP |
| 648 |
These options determine the horizontal and vertical scale factors. |
| 649 |
.sp |
| 650 |
See |
| 651 |
.UR #scalefactor |
| 652 |
The Scale Factors |
| 653 |
.UE |
| 654 |
\&. |
| 655 |
|
| 656 |
.TP |
| 657 |
\fB-reportonly\fP |
| 658 |
This causes \fBpamscale\fP not to scale the image, but instead to |
| 659 |
report to Standard Output what scaling the options and the input image |
| 660 |
dimensions indicate. |
| 661 |
.sp |
| 662 |
See |
| 663 |
.UR #reportonly |
| 664 |
-reportonly |
| 665 |
.UE |
| 666 |
\&. |
| 667 |
|
| 668 |
.TP |
| 669 |
\fB-nomix\fP |
| 670 |
This option selects |
| 671 |
.UR #sampling |
| 672 |
discrete sampling |
| 673 |
.UE |
| 674 |
\& as the |
| 675 |
|
| 676 |
.UR #methods |
| 677 |
method of scaling |
| 678 |
.UE |
| 679 |
\&. |
| 680 |
|
| 681 |
.TP |
| 682 |
\fB-filter=\fP\fIfunctionName\fP |
| 683 |
This option selects |
| 684 |
.UR #resampling |
| 685 |
resampling |
| 686 |
.UE |
| 687 |
\& as the |
| 688 |
|
| 689 |
.UR #methods |
| 690 |
method of scaling |
| 691 |
.UE |
| 692 |
\&. |
| 693 |
|
| 694 |
.TP |
| 695 |
\fB-window=\fP\fIfunctionName\fP |
| 696 |
This option selects a window function to modify the filter function |
| 697 |
specified with \fB-filter\fP. |
| 698 |
.sp |
| 699 |
See |
| 700 |
.UR #resampling |
| 701 |
Resampling |
| 702 |
.UE |
| 703 |
\&. |
| 704 |
|
| 705 |
.TP |
| 706 |
\fB-verbose\fP |
| 707 |
This option causes \fBpamscale\fP to issue messages to Standard Error about |
| 708 |
the scaling. |
| 709 |
|
| 710 |
|
| 711 |
|
| 712 |
|
| 713 |
.UN seealso |
| 714 |
.SH SEE ALSO |
| 715 |
.BR "pnmscalefixed" (1)\c |
| 716 |
\&, |
| 717 |
.BR "pamstretch" (1)\c |
| 718 |
\&, |
| 719 |
.BR "pamstretch-gen" (1)\c |
| 720 |
\&, |
| 721 |
.BR "pamditherbw" (1)\c |
| 722 |
\&, |
| 723 |
.BR "pbmreduce" (1)\c |
| 724 |
\&, |
| 725 |
.BR "pbmpscale" (1)\c |
| 726 |
\&, |
| 727 |
.BR "pamenlarge" (1)\c |
| 728 |
\&, |
| 729 |
.BR "pnmsmooth" (1)\c |
| 730 |
\&, |
| 731 |
.BR "pamcut" (1)\c |
| 732 |
\&, |
| 733 |
.BR "pnmgamma" (1)\c |
| 734 |
\&, |
| 735 |
.BR "pnmscale" (1)\c |
| 736 |
\&, |
| 737 |
.BR "pnm" (1)\c |
| 738 |
\&, |
| 739 |
.BR "pam" (1)\c |
| 740 |
\& |
| 741 |
|
| 742 |
.UN history |
| 743 |
.SH HISTORY |
| 744 |
.PP |
| 745 |
\fBpamscale\fP was new in Netpbm 10.20 (January 2004). It was |
| 746 |
adapted from, and obsoleted, \fBpnmscale\fP. \fBpamscale\fP's |
| 747 |
primary difference from \fBpnmscale\fP is that it handles the PAM |
| 748 |
format and uses the "pam" facilities of the Netpbm programming |
| 749 |
library. But it also added the resampling class of scaling method. |
| 750 |
Furthermore, it properly does its pixel mixing arithmetic (by default) |
| 751 |
using intensity-proportional values instead of the gamma-adjusted |
| 752 |
values the \fBpnmscale\fP uses. To get the old \fBpnmscale\fP |
| 753 |
arithmetic, you can specify the \fB-linear\fP option. |
| 754 |
.PP |
| 755 |
The intensity proportional stuff came out of suggestions by \fIAdam M Costello\fP in January |
| 756 |
2004. |
| 757 |
.PP |
| 758 |
The resampling algorithms are mostly taken from code contributed by |
| 759 |
\fIMichael Reinelt\fP in December 2003. |
| 760 |
.PP |
| 761 |
The version of \fBpnmscale\fP from which \fBpamscale\fP was |
| 762 |
derived, itself evolved out of the original Pbmplus version of |
| 763 |
\fBpnmscale\fP by Jef Poskanzer (1989, 1991). But none of that |
| 764 |
original code remains. |
| 765 |
.SH DOCUMENT SOURCE |
| 766 |
This manual page was generated by the Netpbm tool 'makeman' from HTML |
| 767 |
source. The master documentation is at |
| 768 |
.IP |
| 769 |
.B http://netpbm.sourceforge.net/doc/pamscale.html |
| 770 |
.PP |