Debian Codegraph @

upstream/debian-unstable/man1/pamscale.1

raw
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