Debian Codegraph @

upstream/debian-unstable/man1/pnmpad.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 "Pnmpad User Manual" 1 "26 December 2025" "netpbm documentation"
7
8 .SH NAME
9
10 pnmpad - add borders to a PNM image
11
12 .UN synopsis
13 .SH SYNOPSIS
14
15 \fBpnmpad \fP
16 [\fB-color=\fP\fIcolor\fP
17 [\fB-promote=\fP{\fBnone\fP|\fBformat\fP|\fBall\fP}]
18 |\fB-detect-background\fP
19 |\fB-extend-edge\fP
20 |\fB-white\fP
21 |\fB-black\fP
22 ]
23 [\fB-width=\fP\fIpixels\fP]
24 [\fB-halign=\fP\fIratio\fP]
25 [\fB-mwidth=\fP\fIpixels\fP]
26 [\fB-left=\fP\fIpixels\fP]
27 [\fB-right=\fP\fIpixels\fP]
28 [\fB-height=\fP\fIpixels\fP]
29 [\fB-valign=\fP\fIratio\fP]
30 [\fB-mheight=\fP\fIpixels\fP]
31 [\fB-top=\fP\fIpixels\fP]
32 [\fB-bottom=\fP\fIpixels\fP]
33 [\fB-reportonly\fP]
34 [\fB-verbose\fP]
35 [\fIpnmfile\fP]
36
37
38 .UN description
39 .SH DESCRIPTION
40 .PP
41 This program is part of
42 .BR "Netpbm" (1)\c
43 \&.
44 .PP
45 \fBpnmpad\fP reads a Netpbm image as input and outputs a PNM image that is
46 the input image plus borders of the color and sizes specified.
47 .PP
48 You can use \fBpamcomp\fP to add borders of any content - solid color,
49 pattern, or whatever. For example, if you wanted to add 10 pixels of
50 rainbow borders to the top and bottom of a 100x100 image, you could create a
51 100x120 rainbow image (e.g. with \fBppmrainbow\fP) and then
52 use \fBpamcomp\fP to insert your 100x100 image into the center of it.
53
54
55 .UN options
56 .SH OPTIONS
57 .PP
58 In addition to the options common to all programs based on libnetpbm (most
59 notably \fB-quiet\fP, see
60 .UR index.html#commonoptions
61 Common Options
62 .UE
63 \&), \fBpnmpad\fP recognizes the following command line options:
64 .PP
65 All options can be abbreviated to their shortest unique prefix. You
66 may use two hyphens instead of one to designate an option. You may
67 use either white space or an equals sign between an option name and
68 its value.
69
70
71 .TP
72 \fB-color=\fP\fIcolor\fP
73 .TP
74 \fB-detect-background\fP
75 .TP
76 \fB-extend-edge\fP
77 .TP
78 \fB-white\fP
79 .TP
80 \fB-black\fP
81 This specifies the color of the padding. \fIcolor\fP is like
82 the
83 .UR libnetpbm_image.html#colorname
84 argument of the \fBpnm_parsecolor()\fP library routine
85 .UE
86 \&.
87 .sp
88 \fB-detect-background\fP means the program uses the color of the
89 top left pixel of the input as the pad color. Note that this could cause
90 odd results if you aren't padding the top or left of the image.
91 .sp
92 You may specify only one of \fB-white\fP, \fB-black\fP, \fB-color\fP,
93 and \fB-detect-background\fP.
94 .sp
95 \fB-extend-edge\fP says to pad by duplicating the adjacent edge of the
96 image pixel by pixel. E.g. if the top row of the image is 20 white pixels
97 followed by 10 black pixels, every row of padding added to the top of the
98 image is 20 white pixels followed by 20 black pixels.
99 .sp
100 By default, the padding is black.
101 .sp
102 \fB-white\fP and \fB-black\fP are for backward compatibility; they do the
103 same thing as \fB-color=white\fP and \fB-color=black\fP respectively (except
104 that the latter fail if you don't have a color dictionary set up in your
105 environment, so they are really more like \fB-color=rgbi:0/0/0\fP and
106 \fB-color=rgbi:1/1/1\fP. \fB-color\fP, \fB-detect-background\fP, and
107 \fB-extend-edge\fP were new with Netpbm 11.05 (December 2023).
108
109 .TP
110 \fB-left=\fP\fIpixels\fP
111 .TP
112 \fB-right=\fP\fIpixels\fP
113 .TP
114 \fB-width=\fP\fIwidth\fP
115 .TP
116 \fB-halign=\fP\fIratio\fP
117 .TP
118 \fB-mwidth=\fP\fIpixels\fP
119 Specify amount of left and right padding in pixels.
120 .sp
121 \fB-left\fP and \fB-right\fP directly specify the amount of
122 padding added to the left and right sides, respectively, of the image.
123 .sp
124 Alternatively, you can specify \fB-width\fP and just one of
125 \fB-left\fP and \fB-right\fP and \fBpnmpad\fP calculates the required
126 padding on the other side to make the output \fIwidth\fP pixels wide. If
127 the \fB-width\fP value is less than the width of the input image plus the
128 specified padding, \fBpnmpad\fP ignores \fB-width\fP.
129 .sp
130 If you specify all three of \fB-width\fP, \fB-left\fP, and
131 \fB-right\fP, you must ensure that the \fB-left\fP and \fB-right\fP
132 padding are sufficient to make the image at least as wide as
133 \fB-width\fP specifies, and in that case \fB-width\fP has no effect on the
134 output. Otherwise, \fBpnmpad\fP fails.
135 .sp
136 When you specify \fB-width\fP without \fB-left\fP or
137 \fB-right\fP, and \fB-width\fP is larger than the input image,
138 \fBpnmpad\fP chooses left and right padding amounts in a certain
139 ratio. That ratio defaults to half, but you can set it to anything
140 (from 0 to 1) with the \fB-halign\fP option. If the input image is
141 already at least as wide as \fB-width\fP specifies, \fBpnmpad\fP
142 adds no padding.
143 .sp
144 Common values for \fB-halign\fP are:
145
146 .TP
147 \fB0.0\fP
148 left aligned
149
150 .TP
151 \fB0.5\fP
152 center aligned (default)
153
154 .TP
155 \fB1.0\fP
156 right aligned
157
158 .sp
159 \fB-mwidth=\fP\fIpixels\fP says to pad to a multiple of
160 \fIpixels\fP pixels. E.g. if \fIpixels\fP is 10, the output image width
161 will be a multiple of 10 pixels. \fBpnmpad\fP adds to whatever padding the
162 other options say to do to get to this multiple. It divides that padding
163 between the left and right sides of the image to maintain the ratio the other
164 options produce. E.g. if you say \fB-left=10 -right=10 -mwidth=50\fP with a
165 100-pixel image, you end up with a 150-pixel image with the extra padding
166 split evenly between left and right for a total of 25 pixels of padding
167 on the left and 25 on the right. If the other options indicate no
168 padding, \fBpnmpad\fP adds padding in the ratio specified by \fB-halign\fP
169 and if \fB-halign\fP is not specified, equally on both sides.
170 .sp
171 Before Netpbm 10.97 (December 2021), \fBpnmpad\fP does not allow
172 \fB-halign\fP with \fB-mwidth\fP and adds padding only on the right
173 when \fB-mwidth\fP is specified and the other options indicate no padding.
174 .sp
175 Before Netpbm 10.72 (September 2015), there is no \fB-mwidth\fP.
176 .sp
177 Before Netpbm 10.23 (July 2004), \fBpnmpad\fP did not allow the
178 \fB-left\fP or \fB-right\fP option together with \fB-width\fP.
179
180 .TP
181 \fB-top=\fP\fIpixels\fP
182 .TP
183 \fB-bottom=\fP\fIpixels\fP
184 .TP
185 \fB-height=\fP\fIheight\fP
186 .TP
187 \fB-valign=\fP\fIratio\fP
188 .TP
189 \fB-mheight=\fP\fIpixels\fP
190 These options determine the vertical padding. They are analogous to the
191 horizontal padding options above.
192
193 .TP
194 \fB-promote=\fP{\fBnone\fP|\fBformat\fP|\fBall\fP}
195 This option tells what to do when the \fB-color\fP option specifies a
196 color that cannot be represented in the input format, which ordinarily is also
197 the output format. For example, if the input is PGM (which can represent only
198 shades of gray), and you specify \fB-color=red\fP, should \fBpnmpad\fP make
199 the padding gray or make the output PPM?
200
201
202 .TP
203 \fBnone\fP
204
205 Make the output have the same format and maxval as the input.
206 Adjust the pad color to the nearest color possible in that format
207 (black, white, or a shade of gray).
208 .TP
209 \fBformat\fP
210
211 Make the output have the same maxval as the input, but make
212 the output format PPM if the pad color is not black, white, or gray.
213 .TP
214 \fBall\fP
215
216 Make the format and maxval of the output capable of representing the
217 pad color. Make the format the least expressive format capable of
218 representing the pad color. Make the maxval the larger of 255 and
219 the maxval of the input image.
220
221 .sp
222 The default is \fB-promote=all\fP.
223 .sp
224 Note that this promotion happens even if no actual padding happens, meaning
225 it isn't really necessary. The promotion is based on
226 what \fIwould\fP be required to represent padding of the specified color.
227 .sp
228 This option is valid only when you also specify \fB-color\fP.
229 .sp
230 This option was new in Netpbm 11.05 (December 2023).
231
232 .TP
233 \fB-reportonly\fP
234 This causes \fBpnmpad\fP to write to Standard Output a description of the
235 padding it would have done instead of producing an output image. See
236
237 .UR #reportonly
238 below
239 .UE
240 \& for a description of this output and ways
241 to use it.
242 .sp
243 This option was new in Netpbm 10.89 (December 2019).
244
245 .TP
246 \fB-verbose\fP
247 This causes verbose messages.
248
249
250
251 .UN reportonly
252 .SH REPORT ONLY
253 .PP
254 When you specify \fB-reportonly\fP, \fBpnmpad\fP does not produce an
255 output image. Instead, it writes to Standard Output a description of the
256 padding it would have done without \fB-reportonly\fP.
257 .PP
258 That description is one line of text, containing 6 decimal numbers of
259 pixels, separated by spaces:
260
261
262 .IP \(bu
263 left padding
264 .IP \(bu
265 right padding
266 .IP \(bu
267 top padding
268 .IP \(bu
269 bottom padding
270 .IP \(bu
271 output width
272 .IP \(bu
273 output height
274
275 .PP
276 Example:
277 .nf
278
279 4 3 0 2 100 100
280
281
282 .fi
283 .PP
284 One use for this is to make padding which is fancier than the black and
285 white that \fBpnmpad\fP can do.
286 .PP
287 In the following example, we pad an image with 10 pixels of gray all
288 around, without knowing the original image dimensions beforehand. We do
289 this by generating a gray image with \fBpbmmake\fP and then pasting the
290 subject image into the middle of it.
291 .PP
292 The example uses shell arrays, such as exist in Bash, but not Dash.
293
294 .nf
295 \f(CW
296 pad=($(pnmpad -reportonly -left=10 -right=10 -top=10 -bottom=10 input.ppm))
297 pbmmake -gray ${pad[4]} ${pad[5]} | \e
298 pnmpaste input.ppm ${pad[0]} ${pad[2]} -
299 \fP
300
301 .fi
302
303
304 .UN history
305 .SH HISTORY
306 .PP
307 The command line syntax was originally more of a traditional Unix syntax,
308 with single-character margin size options \fB-l\fP, \fB-r\fP, \fB-t\fP,
309 and \fB-b\fP that took arguments concatenated to the option name, such
310 as \fB-l50\fP. This is in contrast to the more modern syntax used by
311 essentially all Netpbm programs, in which an option such as \fB-left\fP
312 (which can still be abbreviated \fB-l\fP) must have its name and value as
313 separate command line arguments (e.g. \fB-l 50\fP).
314
315 The new syntax was accepted and the old syntax deprecated and removed from
316 documentation in Netpbm 9.25 (March 2002), and was no longer accepted in
317 Netpbm 11.05 (December 2023).
318
319 The code was broken for most of that time so that an attempt to use the old
320 syntax would fail anyway. The bug was discovered only in testing; no user
321 ever reported encountering it.
322
323 .UN seealso
324 .SH SEE ALSO
325 .BR "pbmmake" (1)\c
326 \&,
327 .BR "pnmpaste" (1)\c
328 \&,
329 .BR "pamcut" (1)\c
330 \&,
331 .BR "pnmcrop" (1)\c
332 \&,
333 .BR "pamcomp" (1)\c
334 \&,
335 .BR "pnmmargin" (1)\c
336 \&,
337 .BR "pbm" (1)\c
338 \&
339
340
341 .UN author
342 .SH AUTHOR
343 .PP
344 Copyright (C) 2002 by Martin van Beilen
345 .PP
346 Copyright (C) 1990 by Angus Duggan
347 .PP
348 Copyright (C) 1989 by Jef Poskanzer.
349 .PP
350 Permission to use, copy, modify, and distribute this software and
351 its documentation for any purpose and without fee is hereby granted,
352 provided that the above copyright notice appear in all copies and that
353 both that copyright notice and this permission notice appear in
354 supporting documentation. This software is provided "as is"
355 without express or implied warranty.
356 .SH DOCUMENT SOURCE
357 This manual page was generated by the Netpbm tool 'makeman' from HTML
358 source. The master documentation is at
359 .IP
360 .B http://netpbm.sourceforge.net/doc/pnmpad.html
361 .PP