| 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 |