Debian Codegraph @

upstream/debian-trixie/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 "10 August 2024" "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.
103 \fB-color\fP, \fB-detect-background\fP, and \fB-extend-edge\fP were new
104 with Netpbm 11.05 (December 2023).
105
106 .TP
107 \fB-left=\fP\fIpixels\fP
108 .TP
109 \fB-right=\fP\fIpixels\fP
110 .TP
111 \fB-width=\fP\fIwidth\fP
112 .TP
113 \fB-halign=\fP\fIratio\fP
114 .TP
115 \fB-mwidth=\fP\fIpixels\fP
116 Specify amount of left and right padding in pixels.
117 .sp
118 \fB-left\fP and \fB-right\fP directly specify the amount of
119 padding added to the left and right sides, respectively, of the image.
120 .sp
121 Alternatively, you can specify \fB-width\fP and just one of
122 \fB-left\fP and \fB-right\fP and \fBpnmpad\fP calculates the required
123 padding on the other side to make the output \fIwidth\fP pixels wide. If
124 the \fB-width\fP value is less than the width of the input image plus the
125 specified padding, \fBpnmpad\fP ignores \fB-width\fP.
126 .sp
127 If you specify all three of \fB-width\fP, \fB-left\fP, and
128 \fB-right\fP, you must ensure that the \fB-left\fP and \fB-right\fP
129 padding are sufficient to make the image at least as wide as
130 \fB-width\fP specifies, and in that case \fB-width\fP has no effect on the
131 output. Otherwise, \fBpnmpad\fP fails.
132 .sp
133 When you specify \fB-width\fP without \fB-left\fP or
134 \fB-right\fP, and \fB-width\fP is larger than the input image,
135 \fBpnmpad\fP chooses left and right padding amounts in a certain
136 ratio. That ratio defaults to half, but you can set it to anything
137 (from 0 to 1) with the \fB-halign\fP option. If the input image is
138 already at least as wide as \fB-width\fP specifies, \fBpnmpad\fP
139 adds no padding.
140 .sp
141 Common values for \fB-halign\fP are:
142
143 .TP
144 \fB0.0\fP
145 left aligned
146
147 .TP
148 \fB0.5\fP
149 center aligned (default)
150
151 .TP
152 \fB1.0\fP
153 right aligned
154
155 .sp
156 \fB-mwidth=\fP\fIpixels\fP says to pad to a multiple of
157 \fIpixels\fP pixels. E.g. if \fIpixels\fP is 10, the output image width
158 will be a multiple of 10 pixels. \fBpnmpad\fP adds to whatever padding the
159 other options say to do to get to this multiple. It divides that padding
160 between the left and right sides of the image to maintain the ratio the other
161 options produce. E.g. if you say \fB-left=10 -right=10 -mwidth=50\fP with a
162 100-pixel image, you end up with a 150-pixel image with the extra padding
163 split evenly between left and right for a total of 25 pixels of padding
164 on the left and 25 on the right. If the other options indicate no
165 padding, \fBpnmpad\fP adds padding in the ratio specified by \fB-halign\fP
166 and if \fB-halign\fP is not specified, equally on both sides.
167 .sp
168 Before Netpbm 10.97 (December 2021), \fBpnmpad\fP does not allow
169 \fB-halign\fP with \fB-mwidth\fP and adds padding only on the right
170 when \fB-mwidth\fP is specified and the other options indicate no padding.
171 .sp
172 Before Netpbm 10.72 (September 2015), there is no \fB-mwidth\fP.
173 .sp
174 Before Netpbm 10.23 (July 2004), \fBpnmpad\fP did not allow the
175 \fB-left\fP or \fB-right\fP option together with \fB-width\fP.
176
177 .TP
178 \fB-top=\fP\fIpixels\fP
179 .TP
180 \fB-bottom=\fP\fIpixels\fP
181 .TP
182 \fB-height=\fP\fIheight\fP
183 .TP
184 \fB-valign=\fP\fIratio\fP
185 .TP
186 \fB-mheight=\fP\fIpixels\fP
187 These options determine the vertical padding. They are analogous to the
188 horizontal padding options above.
189
190 .TP
191 \fB-promote=\fP{\fBnone\fP|\fBformat\fP|\fBall\fP}
192 This option tells what to do when the \fB-color\fP option specifies a
193 color that cannot be represented in the input format, which ordinarily is also
194 the output format. For example, if the input is PGM (which can represent only
195 shades of gray), and you specify \fB-color=red\fP, should \fBpnmpad\fP make
196 the padding gray or make the output PPM?
197
198
199 .TP
200 \fBnone\fP
201
202 Make the output have the same format and maxval as the input.
203 Adjust the pad color to the nearest color possible in that format
204 (black, white, or a shade of gray).
205 .TP
206 \fBformat\fP
207
208 Make the output have the same maxval as the input, but make
209 the output format PPM if the pad color is not black, white, or gray.
210 .TP
211 \fBall\fP
212
213 Make the format and maxval of the output capable of representing the
214 pad color. Make the format the least expressive format capable of
215 representing the pad color. Make the maxval the larger of 255 and
216 the maxval of the input image.
217
218 .sp
219 The default is \fB-promote=all\fP.
220 .sp
221 Note that this promotion happens even if no actual padding happens, meaning
222 it isn't really necessary. The promotion is based on
223 what \fIwould\fP be required to represent padding of the specified color.
224 .sp
225 This option is valid only when you also specify \fB-color\fP.
226 .sp
227 This option was new in Netpbm 11.05 (December 2023).
228
229 .TP
230 \fB-reportonly\fP
231 This causes \fBpnmpad\fP to write to Standard Output a description of the
232 padding it would have done instead of producing an output image. See
233
234 .UR #reportonly
235 below
236 .UE
237 \& for a description of this output and ways
238 to use it.
239 .sp
240 This option was new in Netpbm 10.89 (December 2019).
241
242 .TP
243 \fB-verbose\fP
244 This causes verbose messages.
245
246
247
248 .UN reportonly
249 .SH REPORT ONLY
250 .PP
251 When you specify \fB-reportonly\fP, \fBpnmpad\fP does not produce an
252 output image. Instead, it writes to Standard Output a description of the
253 padding it would have done without \fB-reportonly\fP.
254 .PP
255 That description is one line of text, containing 6 decimal numbers of
256 pixels, separated by spaces:
257
258
259 .IP \(bu
260 left padding
261 .IP \(bu
262 right padding
263 .IP \(bu
264 top padding
265 .IP \(bu
266 bottom padding
267 .IP \(bu
268 output width
269 .IP \(bu
270 output height
271
272 .PP
273 Example:
274 .nf
275
276 4 3 0 2 100 100
277
278
279 .fi
280 .PP
281 One use for this is to make padding which is fancier than the black and
282 white that \fBpnmpad\fP can do.
283 .PP
284 In the following example, we pad an image with 10 pixels of gray all
285 around, without knowing the original image dimensions beforehand. We do
286 this by generating a gray image with \fBpbmmake\fP and then pasting the
287 subject image into the middle of it.
288 .PP
289 The example uses shell arrays, such as exist in Bash, but not Dash.
290
291 .nf
292 \f(CW
293 pad=($(pnmpad -reportonly -left=10 -right=10 -top=10 -bottom=10 input.ppm))
294 pbmmake -gray ${pad[4]} ${pad[5]} | \e
295 pnmpaste input.ppm ${pad[0]} ${pad[2]} -
296 \fP
297
298 .fi
299
300
301 .UN history
302 .SH HISTORY
303 .PP
304 The command line syntax was originally more of a traditional Unix syntax,
305 with single-character margin size options \fB-l\fP, \fB-r\fP, \fB-t\fP,
306 and \fB-b\fP that took arguments concatenated to the option name, such
307 as \fB-l50\fP. This is in contrast to the more modern syntax used by
308 essentially all Netpbm programs, in which an option such as \fB-left\fP
309 (which can still be abbreviated \fB-l\fP) must have its name and value as
310 separate command line arguments (e.g. \fB-l 50\fP).
311
312 The new syntax was accepted and the old syntax deprecated and removed from
313 documentation in Netpbm 9.25 (March 2002), and was no longer accepted in
314 Netpbm 11.05 (December 2023).
315
316 The code was broken for most of that time so that an attempt to use the old
317 syntax would fail anyway. The bug was discovered only in testing; no user
318 ever reported encountering it.
319
320 .UN seealso
321 .SH SEE ALSO
322 .BR "pbmmake" (1)\c
323 \&,
324 .BR "pnmpaste" (1)\c
325 \&,
326 .BR "pamcut" (1)\c
327 \&,
328 .BR "pnmcrop" (1)\c
329 \&,
330 .BR "pamcomp" (1)\c
331 \&,
332 .BR "pnmmargin" (1)\c
333 \&,
334 .BR "pbm" (1)\c
335 \&
336
337
338 .UN author
339 .SH AUTHOR
340 .PP
341 Copyright (C) 2002 by Martin van Beilen
342 .PP
343 Copyright (C) 1990 by Angus Duggan
344 .PP
345 Copyright (C) 1989 by Jef Poskanzer.
346 .PP
347 Permission to use, copy, modify, and distribute this software and
348 its documentation for any purpose and without fee is hereby granted,
349 provided that the above copyright notice appear in all copies and that
350 both that copyright notice and this permission notice appear in
351 supporting documentation. This software is provided "as is"
352 without express or implied warranty.
353 .SH DOCUMENT SOURCE
354 This manual page was generated by the Netpbm tool 'makeman' from HTML
355 source. The master documentation is at
356 .IP
357 .B http://netpbm.sourceforge.net/doc/pnmpad.html
358 .PP