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 All options can be abbreviated to their shortest unique prefix. You
41 may use two hyphens instead of one to designate an option. You may use
42 either white space or an equals sign between an option name and its
43 value.
44 -white
48 -black Set pad color. Default is -black.
50 -left=pixels
53 -right=pixels
55 -width=width
57 -halign=ratio
59 -mwidth=pixels
61 Specify amount of left and right padding in pixels.
62 -left and -right directly specify the amount of padding added to
64 the left and right sides, respectively, of the image.
65 Alternatively, you can specify -width and just one of -left and
67 -right and pnmpad calculates the required padding on the other
68 side to make the output width pixels wide. If the -width value
69 is less than the width of the input image plus the specified
70 padding, pnmpad ignores -width.
71 If you specify all three of -width, -left, and -right, you must
73 ensure that the -left and -right padding are sufficient to make
74 the image at least as wide as -width specifies. Otherwise, pnm‐
75 pad fails.
76 When you specify -width without -left or -right, and -width is
78 larger than the input image, pnmpad chooses left and right pad‐
79 ding amounts in a certain ratio. That ratio defaults to half,
80 but you can set it to anything (from 0 to 1) with the -halign
81 option. If the input image is already at least as wide as
82 -width specifies, pnmpad adds no padding.
83 Common values for -halign are:
85 0.0 left aligned
88 0.5 center aligned (default)
91 1.0 right aligned
94 -mwidth=pixels says to pad to a multiple of pixels pixels. E.g.
97 if pixels is 10, the output image width will be a multiple of 10
98 pixels. pnmpad adds to whatever padding the other options say
99 to do to get to this multiple. It divides that padding between
100 the left and right sides of the image to maintain the ratio the
101 other options produce. E.g. if you say -left=10 -right=10
102 -mwidth=50 with a 100-pixel image, you end up with a 150-pixel
103 image with the extra padding split evenly between left and right
104 for a total of 25 pixels of padding on the left and 25 on the
105 right.
106 Before Netpbm 10.23 (July 2004), pnmpad did not allow the -left
108 or -right option together with -width.
109 Before Netpbm 10.72 (September 2015), there is no -mwidth.
111 -top=pixels
114 -bottom=pixels
116 -height=height
118 -valign=ratio
120 -mheight=pixels
122 These options determine the vertical padding. They are analo‐
123 gous to the horizontal padding options above.
124 -reportonly
127 This causes pnmpad to write to Standard Output a description
128 of the
129 padding it would have done instead of producing an output
130 image. See
131 below ⟨#reportonly⟩ for a description of this output and ways
133 to use it.
134 This option was new in Netpbm 10.89 (December 2019).
136 -verbose
139 This causes verbose messages.
140
145 When you specify -reportonly, pnmpad does not produce an
146 output image. Instead, it writes to Standard Output a description of
147 the
148 padding it would have done without -reportonly.
149 That description is one line of text, containing 6 decimal numbers of
151 pixels, separated by spaces:
152 · left padding
156 · right padding
158 · top padding
160 · bottom padding
162 · output width
164 · output height
166 Example:
169 4 3 0 2 100 100
171 One use for this is to make padding which is fancier than the black and
174 white that pnmpad can do.
175 In the following example, we pad an image with 10 pixels of gray all
177 around, without knowing the original image dimensions beforehand. We
178 do
179 this by generating a gray image with pbmmake and then pasting the
180 subject image into the middle of it.
181 The example uses shell arrays, such as exist in Bash, but not Dash.
183 pad=($(pnmpad -reportonly -left=10 -right=10 -top=10 -bottom=10))
186 pbmmake -gray 10 10 | pnmpaste input.ppm ${pad[0]} ${pad[2]} -
187
192 Before February 2002, pnmpad had a different option syntax which was
193 less expressive and not like conventional Netpbm programs. That syntax
194 is still understood by pnmpad for backward compatibility, but not docu‐
195 mented or supported for future use.
196
200 pbmmake(1), pnmpaste(1), pamcut(1), pnmcrop(1), pamcomp(1), pnmmar‐
201 gin(1), pbm(1)
202
206 Copyright (C) 2002 by Martin van Beilen
207 Copyright (C) 1990 by Angus Duggan
209 Copyright (C) 1989 by Jef Poskanzer.
211 Permission to use, copy, modify, and distribute this software and its
213 documentation for any purpose and without fee is hereby granted, pro‐
214 vided that the above copyright notice appear in all copies and that
215 both that copyright notice and this permission notice appear in sup‐
216 porting documentation. This software is provided "as is" without
217 express or implied warranty.
218
220 This manual page was generated by the Netpbm tool 'makeman' from HTML
221 source. The master documentation is at
222 http://netpbm.sourceforge.net/doc/pnmpad.html
224netpbm documentation 05 October 2019 Pnmpad User Manual(0)