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

NAME

6       pnmpad - add borders to a PNM image
7
8

SYNOPSIS

10       pnmpad [-white|-black] [-width=pixels] [-halign=ratio] [-mwidth=pixels]
11       [-left=pixels]   [-right=pixels]    [-height=pixels]    [-valign=ratio]
12       [-mheight=pixels]  [-top=pixels]  [-bottom=pixels] [-reportonly] [-ver‐
13       bose] [pnmfile]
14
15
16

DESCRIPTION

18       This program is part of Netpbm(1).
19
20       pnmpad reads a PNM image as input and outputs a PNM image that  is  the
21       input image plus black or white borders of the sizes specified.
22
23       If  you  just  need to convert an image to a certain size regardless of
24       the original dimensions, pamcut with the -pad option may  be  a  better
25       choice.
26
27       pnmmargin  does  essentially the same thing, but allows you to add bor‐
28       ders of any color and requires all four borders to be the same size.
29
30       You can use pamcomp to add borders of any content - solid color,
31         pattern, or whatever.  For example, if you wanted to add 10 pixels of
32       red
33         borders to the top and bottom of a 100x100 image, you could create a
34         100x120 red image (e.g. with ppmmake) and then use pamcomp
35         to insert your 100x100 image into the center of it.
36
37
38

OPTIONS

40       In  addition  to  the options common to all programs based on libnetpbm
41       (most notably -quiet, see
42        Common Options ⟨index.html#commonoptions⟩  ),  pnmpad  recognizes  the
43       following command line options:
44
45       All  options  can  be abbreviated to their shortest unique prefix.  You
46       may use two hyphens instead of one to designate an option.  You may use
47       either  white  space  or  an equals sign between an option name and its
48       value.
49
50
51
52       -white
53
54       -black Set pad color.  Default is -black.
55
56
57       -left=pixels
58
59       -right=pixels
60
61       -width=width
62
63       -halign=ratio
64
65       -mwidth=pixels
66              Specify amount of left and right padding in pixels.
67
68              -left and -right directly specify the amount of padding added to
69              the left and right sides, respectively, of the image.
70
71              Alternatively,  you can specify -width and just one of -left and
72              -right and pnmpad calculates the required padding on  the  other
73              side  to make the output width pixels wide.  If the -width value
74              is less than the width of the input  image  plus  the  specified
75              padding, pnmpad ignores -width.
76
77              If  you specify all three of -width, -left, and -right, you must
78              ensure that the -left and -right padding are sufficient to  make
79              the image at least as wide as -width specifies.  Otherwise, pnm‐
80              pad fails.
81
82              When you specify -width without -left or -right, and  -width  is
83              larger  than the input image, pnmpad chooses left and right pad‐
84              ding amounts in a certain ratio.  That ratio defaults  to  half,
85              but  you  can  set it to anything (from 0 to 1) with the -halign
86              option.  If the input image is  already  at  least  as  wide  as
87              -width specifies, pnmpad adds no padding.
88
89              Common values for -halign are:
90
91
92       0.0    left aligned
93
94
95       0.5    center aligned (default)
96
97
98       1.0    right aligned
99
100
101              -mwidth=pixels says to pad to a multiple of pixels pixels.  E.g.
102              if pixels is 10, the output image width will be a multiple of 10
103              pixels.   pnmpad  adds to whatever padding the other options say
104              to do to get to this multiple.  It divides that padding  between
105              the  left and right sides of the image to maintain the ratio the
106              other options produce.   E.g.  if  you  say  -left=10  -right=10
107              -mwidth=50  with  a 100-pixel image, you end up with a 150-pixel
108              image with the extra padding split evenly between left and right
109              for  a  total  of 25 pixels of padding on the left and 25 on the
110              right.
111
112              Before Netpbm 10.23 (July 2004), pnmpad did not allow the  -left
113              or -right option together with -width.
114
115              Before Netpbm 10.72 (September 2015), there is no -mwidth.
116
117
118       -top=pixels
119
120       -bottom=pixels
121
122       -height=height
123
124       -valign=ratio
125
126       -mheight=pixels
127              These  options  determine the vertical padding.  They are analo‐
128              gous to the horizontal padding options above.
129
130
131       -reportonly
132                This causes pnmpad to write to Standard Output  a  description
133              of the
134                padding  it  would  have  done  instead of producing an output
135              image.  See
136
137              below ⟨#reportonly⟩  for a description of this output and ways
138                to use it.
139
140              This option was new in Netpbm 10.89 (December 2019).
141
142
143       -verbose
144              This causes verbose messages.
145
146
147
148

REPORT ONLY

150       When you specify -reportonly, pnmpad does not produce an
151         output image.  Instead, it writes to Standard Output a description of
152       the
153         padding it would have done without -reportonly.
154
155       That description is one line of text, containing 6 decimal numbers of
156         pixels, separated by spaces:
157
158
159
160       ·      left padding
161
162       ·      right padding
163
164       ·      top padding
165
166       ·      bottom padding
167
168       ·      output width
169
170       ·      output height
171
172
173       Example:
174           <span style="font-family: monospace">
175             4 3 0 2 100 100
176           </span>
177
178       One use for this is to make padding which is fancier than the black and
179         white that pnmpad can do.
180
181       In the following example, we pad an image with 10 pixels of gray all
182         around, without knowing the original image dimensions beforehand.  We
183       do
184         this by generating a gray image with pbmmake and then pasting the
185         subject image into the middle of it.
186
187       The example uses shell arrays, such as exist in Bash, but not Dash.
188
189
190           pad=($(pnmpad -reportonly -left=10 -right=10 -top=10 -bottom=10 input.ppm))
191           pbmmake -gray ${pad[4]} ${pad[5]} | \
192             pnmpaste input.ppm ${pad[0]} ${pad[2]} -
193
194
195
196

HISTORY

198       Before February 2002, pnmpad had a different option  syntax  which  was
199       less expressive and not like conventional Netpbm programs.  That syntax
200       is still understood by pnmpad for backward compatibility, but not docu‐
201       mented or supported for future use.
202
203
204

SEE ALSO

206       pbmmake(1),  pnmpaste(1),  pamcut(1),  pnmcrop(1),  pamcomp(1), pnmmar‐
207       gin(1), pbm(1)
208
209
210

AUTHOR

212       Copyright (C) 2002 by Martin van Beilen
213
214       Copyright (C) 1990 by Angus Duggan
215
216       Copyright (C) 1989 by Jef Poskanzer.
217
218       Permission to use, copy, modify, and distribute this software  and  its
219       documentation  for  any purpose and without fee is hereby granted, pro‐
220       vided that the above copyright notice appear in  all  copies  and  that
221       both  that  copyright  notice and this permission notice appear in sup‐
222       porting documentation.  This  software  is  provided  "as  is"  without
223       express or implied warranty.
224

DOCUMENT SOURCE

226       This  manual  page was generated by the Netpbm tool 'makeman' from HTML
227       source.  The master documentation is at
228
229              http://netpbm.sourceforge.net/doc/pnmpad.html
230
231netpbm documentation            05 October 2019          Pnmpad User Manual(0)
Impressum