1Pnmpad User Manual(0) Pnmpad User Manual(0)
2
6 pnmpad - add borders to a PNM image
7
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
18 This program is part of Netpbm(1).
19 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 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 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 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
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 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 -white
53 -black Set pad color. Default is -black.
55 -left=pixels
58 -right=pixels
60 -width=width
62 -halign=ratio
64 -mwidth=pixels
66 Specify amount of left and right padding in pixels.
67 -left and -right directly specify the amount of padding added to
69 the left and right sides, respectively, of the image.
70 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 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 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 Common values for -halign are:
90 0.0 left aligned
93 0.5 center aligned (default)
96 1.0 right aligned
99 -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. If the other options indicate no padding, pnmpad adds
111 padding in the ratio specified by -halign and if -halign is not
112 specified, equally on both sides.
113 Before Netpbm 10.97 (December 2021), pnmpad does not allow
115 -halign with -mwidth and adds padding only on the right when
116 -mwidth is specified and the other options indicate no padding.
117 Before Netpbm 10.72 (September 2015), there is no -mwidth.
119 Before Netpbm 10.23 (July 2004), pnmpad did not allow the -left
121 or -right option together with -width.
122 -top=pixels
125 -bottom=pixels
127 -height=height
129 -valign=ratio
131 -mheight=pixels
133 These options determine the vertical padding. They are analo‐
134 gous to the horizontal padding options above.
135 -reportonly
138 This causes pnmpad to write to Standard Output a description
139 of the
140 padding it would have done instead of producing an output im‐
141 age. See
142 below ⟨#reportonly⟩ for a description of this output and ways
144 to use it.
145 This option was new in Netpbm 10.89 (December 2019).
147 -verbose
150 This causes verbose messages.
151
156 When you specify -reportonly, pnmpad does not produce an
157 output image. Instead, it writes to Standard Output a description of
158 the
159 padding it would have done without -reportonly.
160 That description is one line of text, containing 6 decimal numbers of
162 pixels, separated by spaces:
163 • left padding
167 • right padding
169 • top padding
171 • bottom padding
173 • output width
175 • output height
177 Example:
180 4 3 0 2 100 100
182 One use for this is to make padding which is fancier than the black and
186 white that pnmpad can do.
187 In the following example, we pad an image with 10 pixels of gray all
189 around, without knowing the original image dimensions beforehand. We
190 do
191 this by generating a gray image with pbmmake and then pasting the
192 subject image into the middle of it.
193 The example uses shell arrays, such as exist in Bash, but not Dash.
195 pad=($(pnmpad -reportonly -left=10 -right=10 -top=10 -bottom=10 input.ppm))
198 pbmmake -gray ${pad[4]} ${pad[5]} | \
199 pnmpaste input.ppm ${pad[0]} ${pad[2]} -
200
206 Before February 2002, pnmpad had a different option syntax which was
207 less expressive and not like conventional Netpbm programs. That syntax
208 is still understood by pnmpad for backward compatibility, but not docu‐
209 mented or supported for future use.
210
214 pbmmake(1), pnmpaste(1), pamcut(1), pnmcrop(1), pamcomp(1), pnmmar‐
215 gin(1), pbm(1)
216
220 Copyright (C) 2002 by Martin van Beilen
221 Copyright (C) 1990 by Angus Duggan
223 Copyright (C) 1989 by Jef Poskanzer.
225 Permission to use, copy, modify, and distribute this software and its
227 documentation for any purpose and without fee is hereby granted, pro‐
228 vided that the above copyright notice appear in all copies and that
229 both that copyright notice and this permission notice appear in sup‐
230 porting documentation. This software is provided "as is" without ex‐
231 press or implied warranty.
232
234 This manual page was generated by the Netpbm tool 'makeman' from HTML
235 source. The master documentation is at
236 http://netpbm.sourceforge.net/doc/pnmpad.html
238netpbm documentation 25 December 2021 Pnmpad User Manual(0)