1Pamscale User Manual(0)                                Pamscale User Manual(0)
2
3
4

NAME

6       pamscale - scale a Netpbm image
7
8

SYNOPSIS

10          pamscale
11             [
12                scale_factor
13                |
14                {-xyfit | -xyfill | -xysize}
15                  cols rows
16                |
17                -reduce reduction_factor
18                |
19                [-xsize=cols | -width=cols | -xscale=factor]
20                [-ysize=rows | -height=rows | -yscale=factor]
21                |
22                -pixels n
23             ]
24             [
25                [-verbose]
26                [
27                   -nomix
28                   |
29                   -filter=functionName [-window=functionName]
30                ]
31                [-linear]
32             }
33             [-reportonly]
34             [pnmfile]
35
36
37       Minimum  unique abbreviation of option is acceptable.  You may use dou‐
38       ble hyphens instead of single hyphen to denote options.   You  may  use
39       white space in place of the equals sign to separate an option name from
40       its value.
41
42

DESCRIPTION

44       This program is part of Netpbm(1).
45
46       pamscale scales a Netpbm image by a specified factor, or  scales  indi‐
47       vidually horizontally and vertically by specified factors.
48
49       You can either enlarge (scale factor > 1) or reduce (scale factor < 1).
50
51       pamscale  work  on multi-image streams, scaling each one independently.
52       But before Netpbm 10.49 (December 2009), it scales only the first image
53       and ignores the rest of the stream.
54
55
56   The Scale Factors
57       The  options -width, -height, -xsize, -ysize, -xscale, -yscale, -xyfit,
58       -xyfill, -reduce, and -pixels control the amount of scaling.  For back‐
59       ward  compatibility,  there  is also -xysize and the scale_factor argu‐
60       ment, but you shouldn't use those.
61
62       -width and -height specify the width and height in pixels you want  the
63       resulting  image  to  be.  See below for rules when you specify one and
64       not the other.
65
66       -xsize and -ysize are synonyms for -width and -height, respectively.
67
68       -xscale and -yscale tell the factor by which you  want  the  width  and
69       height  of  the  image to change from source to result (e.g.  -xscale 2
70       means you want to double the width; -xscale .5 means you want to  halve
71       it).  See below for rules when you specify one and not the other.
72
73       When  you specify an absolute size or scale factor for both dimensions,
74       pamscale scales each dimension independently without  consideration  of
75       the aspect ratio.
76
77       If  you  specify  one  dimension  as a pixel size and don't specify the
78       other dimension, pamscale scales the unspecified dimension to  preserve
79       the aspect ratio.
80
81       If  you  specify  one dimension as a scale factor and don't specify the
82       other dimension, pamscale leaves the  unspecified  dimension  unchanged
83       from the input.
84
85       If you specify the scale_factor parameter instead of dimension options,
86       that is the scale factor for both  dimensions.   It  is  equivalent  to
87       -xscale=scale_factor -yscale=scale_factor.
88
89       Specifying  the -reduce reduction_factor option is equivalent to speci‐
90       fying the scale_factor  parameter, where scale_factor is the reciprocal
91       of reduction_factor.
92
93       -xyfit  specifies  a  bounding box.  pamscale scales the input image to
94       the largest size that fits within the box, while preserving its  aspect
95       ratio.   -xysize  is  a synonym for this.  Before Netpbm 10.20 (January
96       2004), -xyfit did not exist, but -xysize did.
97
98       -xyfill is similar, but pamscale scales the input image to the smallest
99       size  that completely fills the box, while preserving its aspect ratio.
100       This option has existed since Netpbm 10.20 (January 2004).
101
102       -pixels specifies a maximum total number of  output  pixels.   pamscale
103       scales  the image down to that number of pixels.  If the input image is
104       already no more than that many pixels, pamscale just copies it as  out‐
105       put; pamscale does not scale up with -pixels.
106
107       If  you  enlarge  by  a  factor of 3 or more, you should probably add a
108       pnmsmooth step; otherwise, you can  see  the  original  pixels  in  the
109       resulting image.
110
111       -reportonly
112
113       The  option  -reportonly  causes  pamscale  not to scale the image, but
114       instead to report to Standard Output what scaling the options  and  the
115       input image dimensions indicate.  For example, if you specify
116           -xyfill 100 100 -reportonly
117       and  the  input  image is 500 x 400, pamscale tells you that this means
118       scaling by .25 to end up with a 125 x 100 image.
119
120       The output is intended to be convenient for machine processing.  In the
121       example above, it would be
122
123           500 400 0.250000 0.250000 125 100
124
125       The  output  is a single line of text per input image, with blank-sepa‐
126       rated tokens as follows.
127
128
129
130       ·      input width in pixels, decimal unsigned integer
131
132       ·      input height in pixels, decimal unsigned integer
133
134       ·      horizontal scale factor, floating point decimal, unsigned
135
136       ·      vertical scale factor, floating point decimal, unsigned
137
138       ·      output width in pixels, decimal unsigned integer
139
140       ·      output height in pixels, decimal unsigned integer
141
142
143       -reportonly was new in Netpbm 10.86 (March 2019).
144
145
146
147   Usage Notes
148       A useful application of pamscale is to blur an image.   Scale  it  down
149       (without  -nomix)  to  discard  some information, then scale it back up
150       using pamstretch.
151
152       Or scale it back up with pamscale and create a "pixelized" image, which
153       is sort of a computer-age version of blurring.
154
155
156
157   Transparency
158       pamscale understands transparency and properly mixes pixels considering
159       the pixels' transparency.
160
161       Proper mixing does not mean just mixing the transparency value and  the
162       color  component  values  separately.  In a PAM image, a pixel which is
163       not opaque represents a color that contains  light  of  the  foreground
164       color  indicated  explicitly in the PAM and light of a background color
165       to be named later.  But the numerical scale of a color component sample
166       in  a PAM is as if the pixel is opaque.  So a pixel that is supposed to
167       contain half-strength red light for the foreground plus some light from
168       the  background  has a red color sample that says full red and a trans‐
169       parency sample that says 50% opaque.  In order to mix pixels, you  have
170       to  first  convert  the  color  sample values to numbers that represent
171       amount of light directly (i.e. multiply by the  opaqueness)  and  after
172       mixing, convert back (divide by the opaqueness).
173
174
175   Input And Output Image Types
176       pamscale  produces  output of the same type (and tuple type if the type
177       is PAM) as the input, except if the input is PBM.  In  that  case,  the
178       output  is  PGM with maxval 255.  The purpose of this is to allow mean‐
179       ingful pixel mixing.  Note that there is no equivalent  exception  when
180       the  input  is  PAM.  If the PAM input tuple type is BLACKANDWHITE, the
181       PAM output tuple type is also BLACKANDWHITE, and you get no  meaningful
182       pixel mixing.
183
184       If  you want PBM output with PBM input, use pamditherbw to convert pam‐
185       scale's output to PBM.  Also consider pbmreduce.
186
187       pamscale's function is essentially undefined for PAM input images  that
188       are  not  of  tuple  type  RGB, GRAYSCALE, BLACKANDWHITE, or the _ALPHA
189       variations of those.  (By standard Netpbm backward compatibility,  this
190       includes PBM, PGM, and PPM images).
191
192       You  might  think it would have an obvious effect on other tuple types,
193       but remember that the aforementioned tuple  types  have  gamma-adjusted
194       sample values, and pamscale uses that fact in its calculations.  And it
195       treats a transparency plane different from any other plane.
196
197       pamscale does  not  simply  reject  unrecognized  tuple  types  because
198       there's a possibility that just by coincidence you can get useful func‐
199       tion out of it with some other tuple type and the right combination  of
200       options (consider -linear in particular).
201
202
203
204   Methods Of Scaling
205       There are numerous ways to scale an image.  pamscale implements a bunch
206       of them; you select among them with invocation options.
207
208       Pixel Mixing
209
210       Pamscale's default method is pixel mixing.  To understand this, imagine
211       the source image as composed of square tiles.  Each tile is a pixel and
212       has uniform color.  The tiles are all the same size.  Now take a trans‐
213       parent sheet the size of the target image, marked with a square grid of
214       tiles the same size.  Stretch or compress the source image to the  size
215       of the sheet and lay the sheet over the source.
216
217       Each  cell  in the overlay grid stands for a pixel of the target image.
218       For example, if you are scaling a 100x200 image up by 1.5,  the  source
219       image  is  100  x 200 tiles, and the transparent sheet is marked off in
220       150 x 300 cells.
221
222       Each cell covers parts of multiple tiles.  To make  the  target  image,
223       just color in each cell with the color which is the average of the col‐
224       ors the cell covers -- weighted by the amount of that color it  covers.
225       A  cell  in  our  example  might cover 4/9 of a blue tile, 2/9 of a red
226       tile, 2/9 of a green tile, and 1/9 of a  white  tile.   So  the  target
227       pixel would be somewhat unsaturated blue.
228
229       When  you are scaling up or down by an integer, the results are simple.
230       When scaling up, pixels get duplicated.  When scaling down, pixels  get
231       thrown away.  In either case, the colors in the target image are a sub‐
232       set of those in the source image.
233
234       When the scale factor is weirder than that, the target image  can  have
235       colors  that  didn't  exist  in the original.  For example, a red pixel
236       next to a white pixel in the source might become a red  pixel,  a  pink
237       pixel, and a white pixel in the target.
238
239       This  method  tends  to  replicate  what the human eye does as it moves
240       closer to or further away from an image.  It also  tends  to  replicate
241       what  the human eye sees, when far enough away to make the pixelization
242       disappear, if an image is not made of pixels and  simply  stretches  or
243       shrinks.
244
245       Discrete Sampling
246
247       Discrete  sampling  is  basically the same thing as pixel mixing except
248       that, in the model described above, instead of averaging the colors  of
249       the  tiles the cell covers, you pick the one color that covers the most
250       area.
251
252       The result you see is that when you enlarge an image, pixels get dupli‐
253       cated and when you reduce an image, some pixels get discarded.
254
255       The  advantage  of  this is that you end up with an image made from the
256       same color palette as the original.  Sometimes that's important.
257
258       The disadvantage is that it distorts the picture.  If you scale  up  by
259       1.5  horizontally, for example, the even numbered input pixels are dou‐
260       bled in the output and the odd numbered ones are copied singly.  If you
261       have  a  bunch of one pixel wide lines in the source, you may find that
262       some of them stretch to 2  pixels,  others  remain  1  pixel  when  you
263       enlarge.   When  you reduce, you may find that some of the lines disap‐
264       pear completely.
265
266       You select discrete sampling with pamscale's -nomix option.
267
268       Actually, -nomix doesn't do exactly what I described  above.   It  does
269       the  scaling in two passes - first horizontal, then vertical.  This can
270       produce slightly different results.
271
272       There is one common case in which one often finds it burdensome to have
273       pamscale  make  up  colors  that weren't there originally: Where one is
274       working with an image format such as GIF that has a limited  number  of
275       possible  colors per image.  If you take a GIF with 256 colors, convert
276       it to PPM, scale by .625, and convert back to GIF,  you  will  probably
277       find that the reduced image has way more than 256 colors, and therefore
278       cannot be converted to GIF.  One way to solve this problem is to do the
279       reduction  with  discrete sampling instead of pixel mixing.  Probably a
280       better way is to do the pixel  mixing,  but  then  color  quantize  the
281       result with pnmquant before converting to GIF.
282
283       When  the  scale  factor is an integer (which means you're scaling up),
284       discrete sampling and pixel mixing are identical -- output  pixels  are
285       always  just  N copies of the input pixels.  In this case, though, con‐
286       sider using pamstretch instead of pamscale  to  get  the  added  pixels
287       interpolated instead of just copied and thereby get a smoother enlarge‐
288       ment.
289
290       pamscale's discrete sampling is faster than pixel  mixing,  but  pamen‐
291       large is faster still.  pamenlarge works only on integer enlargements.
292
293       discrete sampling (-nomix) was new in Netpbm 9.24 (January 2002).
294
295
296       Resampling
297
298       Resampling assumes that the source image is a discrete sampling of some
299       original continuous image.  That is, it assumes there is some  non-pix‐
300       elized  original image and each pixel of the source image is simply the
301       color of that image at a particular point.   Those  points,  naturally,
302       are the intersections of a square grid.
303
304       The  idea  of  resampling  is just to compute that original image, then
305       sample it at a different frequency (a grid of a different scale).
306
307       The problem, of course, is that sampling necessarily  throws  away  the
308       information you need to rebuild the original image.  So we have to make
309       a bunch of assumptions about the makeup of the original image.
310
311       You tell pamscale to use the resampling method by specifying the  -fil‐
312       ter  option.   The value of this option is the name of a function, from
313       the set listed below.
314
315       To explain resampling, we are going to talk about a simple  one  dimen‐
316       sional  scaling  --  scaling  a single row of grayscale pixels horizon‐
317       tally.  If you can understand that, you can easily understand how to do
318       a  whole image: Scale each of the rows of the image, then scale each of
319       the resulting columns.  And scale each of the  color  component  planes
320       separately.
321
322       As  a  first  step  in  resampling, pamscale converts the source image,
323       which is a set of discrete pixel values, into a continuous  step  func‐
324       tion.   A  step  function  is  a  function whose graph is a staircase-y
325       thing.
326
327       Now, we convolve the step function with a proper scaling of the  filter
328       function  that you identified with -filter.  If you don't know what the
329       mathematical concept of convolution (convolving) is, you are officially
330       lost.  You cannot understand this explanation.  The result of this con‐
331       volution is the imaginary original continuous image we've been  talking
332       about.
333
334       Finally, we make target pixels by picking values from that function.
335
336       To understand what is going on, we use Fourier analysis:
337
338       The  idea is that the only difference between our step function and the
339       original continuous function (remember that  we  constructed  the  step
340       function from the source image, which is itself a sampling of the orig‐
341       inal continuous function) is that the step function has a bunch of high
342       frequency  Fourier  components  added.   If  we  could chop out all the
343       higher frequency components of the step function, and know that they're
344       all  higher  than any frequency in the original function, we'd have the
345       original function back.
346
347       The resampling method assumes that the original function was sampled at
348       a high enough frequency to form a perfect sampling.  A perfect sampling
349       is one from which you can recover exactly the original continuous func‐
350       tion.   The Nyquist theorem says that as long as your sample rate is at
351       least twice the highest frequency in your original function,  the  sam‐
352       pling  is  perfect.  So we assume that the image is a sampling of some‐
353       thing whose highest frequency is half the sample  rate  (pixel  resolu‐
354       tion)  or  less.   Given  that,  our filtering does in fact recover the
355       original continuous image from the samples (pixels).
356
357       To chop out all the components above a certain frequency, we just  mul‐
358       tiply  the  Fourier transform of the step function by a rectangle func‐
359       tion.
360
361       We could find the Fourier transform of the step function,  multiply  it
362       by  a  rectangle  function, and then Fourier transform the result back,
363       but there's an easier way.  Mathematicians tell us that multiplying  in
364       the  frequency  domain  is equivalent to convolving in the time domain.
365       That means multiplying the Fourier transform of F by a rectangle  func‐
366       tion  R  is  the  same as convolving F with the Fourier transform of R.
367       It's a lot better to take the Fourier transform of R, and build it into
368       pamscale  than to have pamscale take the Fourier transform of the input
369       image dynamically.
370
371       That leaves only one question:  What is the Fourier transform of a rec‐
372       tangle  function?  Answer: sinc.  Recall from math that sinc is defined
373       as sinc(x) = sin(PI*x)/PI*x.
374
375       Hence, when you specify -filter=sinc, you are effectively  passing  the
376       step  function  of the source image through a low pass frequency filter
377       and recovering a good approximation of the original continuous image.
378
379       Refiltering
380
381       There's another twist: If you simply sample the reconstructed  original
382       continuous image at the new sample rate, and that new sample rate isn't
383       at least twice the highest frequency in the original continuous  image,
384       you  won't  get a perfect sampling.  In fact, you'll get something with
385       ugly aliasing in it.  Note that this can't be  a  problem  when  you're
386       scaling  up (increasing the sample rate), because the fact that the old
387       sample rate was above the Nyquist level means so is the new  one.   But
388       when  scaling  down,  it's  a  problem.  Obviously, you have to give up
389       image quality when scaling down, but aliasing is not the best way to do
390       it.   It's  better  just  to  remove high frequency components from the
391       original continuous image before sampling, and then get a perfect  sam‐
392       pling of that.
393
394       Therefore,  pamscale  filters out frequencies above half the new sample
395       rate before picking the new samples.
396
397       Approximations
398
399       Unfortunately, pamscale doesn't do the convolution precisely.   Instead
400       of  evaluating  the  filter  function  at every point, it samples it --
401       assumes that it doesn't change any more often than  the  step  function
402       does.   pamscale  could actually do the true integration fairly easily.
403       Since the filter functions are built into the program, the integrals of
404       them could be too.  Maybe someday it will.
405
406       There  is  one  more  complication with the Fourier analysis.  sinc has
407       nonzero values on out to infinity and minus infinity.   That  makes  it
408       hard  to  compute  a convolution with it.  So instead, there are filter
409       functions that approximate sinc but are nonzero only within  a  manage‐
410       able  range.   To get those, you multiply the sinc function by a window
411       function, which you select with the -window option.  The same holds for
412       other filter functions that go on forever like sinc.  By default, for a
413       filter that needs a window function, the window function is the  Black‐
414       man function.  Hanning, Hamming, and Kaiser are alternatives.
415
416       Filter Functions Besides Sinc
417
418       The  math  described above works only with sinc as the filter function.
419       pamscale offers many other filter functions,  though.   Some  of  these
420       approximate  sinc  and are faster to compute.  For most of them, I have
421       no idea of the mathematical explanation for them, but  people  do  find
422       they  give  pleasing  results.   They may not be based on resampling at
423       all, but just exploit the convolution that is coincidentally part of  a
424       resampling calculation.
425
426       For some filter functions, you can tell just by looking at the convolu‐
427       tion how they vary the resampling process from the perfect one based on
428       sinc:
429
430       The  impulse  filter  assumes  that the original continuous image is in
431       fact a step function -- the very one we computed as the first  step  in
432       the resampling.  This is mathematically equivalent to the discrete sam‐
433       pling method.
434
435       The box (rectangle) filter assumes the original image  is  a  piecewise
436       linear  function.   Its graph just looks like straight lines connecting
437       the pixel values.  This is mathematically equivalent to the pixel  mix‐
438       ing  method  (but  mixing brightness, not light intensity, so like pam‐
439       scale -linear) when scaling down, and  interpolation  (ala  pamstretch)
440       when scaling up.
441
442       Gamma
443
444       pamscale  assumes  the  underlying continuous function is a function of
445       brightness (as opposed to light intensity), and therefore does all this
446       math using the gamma-adjusted numbers found in a PNM or PAM image.  The
447       -linear option is not available with resampling (it causes pamscale  to
448       fail),  because it wouldn't be useful enough to justify the implementa‐
449       tion effort.
450
451       Resampling (-filter) was new in Netpbm 10.20 (January 2004).
452
453       The filter and window functions
454
455       Here is a list of the function names you can specify for the -filter or
456       -windowoption.  For most of them, you're on your own to figure out just
457       what the function is and what kind of scaling it does.  These are  com‐
458       mon  functions  from  mathematics.   Note that some of these make sense
459       only as filter functions and some make sense only as window funcions.
460
461
462
463       point  The graph of this is a single point at X=0, Y=1.
464
465
466       box    The graph of this is a rectangle sitting on the X axis and  cen‐
467              tered on the Y axis with height 1 and base 1.
468
469
470       triangle
471              The graph of this is an isosceles triangle sitting on the X axis
472              and centered on the Y axis with height 1 and base 2.
473
474
475       quadratic
476
477       cubic
478
479       catrom
480
481       mitchell
482
483       gauss
484
485       sinc
486
487       bessel
488
489       hanning
490
491       hamming
492
493       blackman
494
495       kaiser
496
497       normal
498
499       hermite
500
501       lanczos
502              Not documented
503
504
505
506
507   Linear vs Gamma-adjusted
508       The pixel mixing scaling method described above involves intensities of
509       pixels  (more  precisely, it involves individual intensities of primary
510       color components of pixels).  But the PNM and PNM-equivalent PAM  image
511       formats  represent intensities with gamma-adjusted numbers that are not
512       linearly proportional to intensity.  So pamscale, by default,  performs
513       a  calculation on each sample read from its input and each sample writ‐
514       ten to its output to convert between these gamma-adjusted  numbers  and
515       internal intensity-proportional numbers.
516
517       Sometimes you are not working with true PNM or PAM images, but rather a
518       variation in which the sample values are in fact directly  proportional
519       to  intensity.   If  so,  use the -linear option to tell pamscale this.
520       pamscale then will skip the conversions.
521
522       The conversion takes time.  In one experiment, it increased by a factor
523       of 10 the time required to reduce an image.  And the difference between
524       intensity-proportional values and gamma-adjusted values  may  be  small
525       enough that you would barely see a difference in the result if you just
526       pretended that the gamma-adjusted values were in fact intensity-propor‐
527       tional.   So  just  to save time, at the expense of some image quality,
528       you can specify -linear even when you have true PPM  input  and  expect
529       true PPM output.
530
531       For  the  first  13 years of Netpbm's life, until Netpbm 10.20 (January
532       2004), pamscale's predecessor pnmscale always treated the  PPM  samples
533       as  intensity-proportional even though they were not, and drew few com‐
534       plaints.  So using -linear as a lie is a  reasonable  thing  to  do  if
535       speed  is important to you.  But if speed is important, you also should
536       consider the -nomix option and pnmscalefixed.
537
538       Another technique to consider is to convert your PNM image to the  lin‐
539       ear  variation  with pnmgamma, run pamscale on it and other transforma‐
540       tions that like linear PNM, and then convert it back to true  PNM  with
541       pnmgamma -ungamma.  pnmgamma is often faster than pamscale in doing the
542       conversion.
543
544       With -nomix, -linear has no effect.  That's because pamscale  does  not
545       concern  itself  with  the meaning of the sample values in this method;
546       pamscale just copies numbers from its input to its output.
547
548
549
550   Precision
551       pamscale uses floating point arithmetic internally.  There is  a  speed
552       cost associated with this.  For some images, you can get the acceptable
553       results (in fact, sometimes identical results)  faster  with  pnmscale‐
554       fixed,  which uses fixed point arithmetic.  pnmscalefixed may, however,
555       distort your image a little.  See the pnmscalefixed user manual  for  a
556       complete discussion of the difference.
557
558

SEE ALSO

560       pnmscalefixed(1),  pamstretch(1),  pamditherbw(1),  pbmreduce(1), pbmp‐
561       scale(1), pamenlarge(1),  pnmsmooth(1),  pamcut(1),  pnmgamma(1),  pnm‐
562       scale(1), pnm(1), pam(1)
563
564

HISTORY

566       pamscale  was new in Netpbm 10.20 (January 2004).  It was adapted from,
567       and obsoleted, pnmscale.  pamscale's primary difference  from  pnmscale
568       is  that it handles the PAM format and uses the "pam" facilities of the
569       Netpbm programming library.  But it also added the resampling class  of
570       scaling  method.  Furthermore, it properly does its pixel mixing arith‐
571       metic (by default) using intensity-proportional values instead  of  the
572       gamma-adjusted  values  the  pnmscale  uses.   To  get the old pnmscale
573       arithmetic, you can specify the -linear option.
574
575       The intensity proportional stuff came out  of  suggestions  by  Adam  M
576       Costello in January 2004.
577
578       The  resampling  algorithms  are  mostly taken from code contributed by
579       Michael Reinelt in December 2003.
580
581       The version of pnmscale from which pamscale was derived, itself evolved
582       out of the original Pbmplus version of pnmscale by Jef Poskanzer (1989,
583       1991).  But none of that original code remains.
584

DOCUMENT SOURCE

586       This manual page was generated by the Netpbm tool 'makeman'  from  HTML
587       source.  The master documentation is at
588
589              http://netpbm.sourceforge.net/doc/pamscale.html
590
591netpbm documentation            03 January 2019        Pamscale User Manual(0)
Impressum