diff options
Diffstat (limited to 'upstream/debian-unstable/man1/pnmpad.1')
| -rw-r--r-- | upstream/debian-unstable/man1/pnmpad.1 | 368 |
1 files changed, 368 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man1/pnmpad.1 b/upstream/debian-unstable/man1/pnmpad.1 new file mode 100644 index 00000000..74e5dec6 --- /dev/null +++ b/upstream/debian-unstable/man1/pnmpad.1 @@ -0,0 +1,368 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Pnmpad User Manual" 1 "09 December 2023" "netpbm documentation" + +.SH NAME + +pnmpad - add borders to a PNM image + +.UN synopsis +.SH SYNOPSIS + +\fBpnmpad \fP +[\fB-color=\fP\fIcolor\fP +[\fB-promote=\fP{\fBnone\fP|\fBformat\fP|\fBall\fP}] +|\fB-detect-background\fP +|\fB-extend-edge\fP +|\fB-white\fP +|\fB-black\fP +] +[\fB-width=\fP\fIpixels\fP] +[\fB-halign=\fP\fIratio\fP] +[\fB-mwidth=\fP\fIpixels\fP] +[\fB-left=\fP\fIpixels\fP] +[\fB-right=\fP\fIpixels\fP] +[\fB-height=\fP\fIpixels\fP] +[\fB-valign=\fP\fIratio\fP] +[\fB-mheight=\fP\fIpixels\fP] +[\fB-top=\fP\fIpixels\fP] +[\fB-bottom=\fP\fIpixels\fP] +[\fB-reportonly\fP] +[\fB-verbose\fP] +[\fIpnmfile\fP] + + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBpnmpad\fP reads a PNM image as input and outputs a PNM image +that is the input image plus black or white borders of the sizes +specified. +.PP +If you just need to convert an image to a certain size regardless +of the original dimensions, \fBpamcut\fP with the \fB-pad\fP option +may be a better choice. +.PP +\fBpnmmargin\fP does essentially the same thing, but allows you to +add borders of any color and requires all four borders to be the same +size. +.PP +You can use \fBpamcomp\fP to add borders of any content - solid color, + pattern, or whatever. For example, if you wanted to add 10 pixels of red + borders to the top and bottom of a 100x100 image, you could create a + 100x120 red image (e.g. with \fBppmmake\fP) and then use \fBpamcomp\fP + to insert your 100x100 image into the center of it. + + +.UN options +.SH OPTIONS +.PP +In addition to the options common to all programs based on libnetpbm +(most notably \fB-quiet\fP, see +.UR index.html#commonoptions + Common Options +.UE +\&), \fBpnmpad\fP recognizes the following +command line options: +.PP +All options can be abbreviated to their shortest unique prefix. You +may use two hyphens instead of one to designate an option. You may +use either white space or an equals sign between an option name and +its value. + + +.TP +\fB-color=\fP\fIcolor\fP +.TP +\fB-detect-background\fP +.TP +\fB-extend-edge\fP +.TP +\fB-white\fP +.TP +\fB-black\fP +This specifies the color of the padding. \fIcolor\fP is like +the +.UR libnetpbm_image.html#colorname +argument of the \fBpnm_parsecolor()\fP library routine +.UE +\&. +.sp +\fB-detect-background\fP means the program uses the color of the +top left pixel of the input as the pad color. Note that this could cause +odd results if you aren't padding the top or left of the image. +.sp +You may specify only one of \fB-white\fP, \fB-black\fP, \fB-color\fP, +and \fB-detect-background\fP. +.sp +\fB-extend-edge\fP says to pad by duplicating the adjacent edge of the +image pixel by pixel. E.g. if the top row of the image is 20 white pixels +followed by 10 black pixels, every row of padding added to the top of the +image is 20 white pixels followed by 20 black pixels. +.sp +By default, the padding is black. +.sp +\fB-white\fP and \fB-black\fP are for backward compatibility. +\fB-color\fP, \fB-detect-background\fP, and \fB-extend-edge\fP were new +with Netpbm 11.05 (December 2023). + +.TP +\fB-left=\fP\fIpixels\fP +.TP +\fB-right=\fP\fIpixels\fP +.TP +\fB-width=\fP\fIwidth\fP +.TP +\fB-halign=\fP\fIratio\fP +.TP +\fB-mwidth=\fP\fIpixels\fP +Specify amount of left and right padding in pixels. +.sp +\fB-left\fP and \fB-right\fP directly specify the amount of +padding added to the left and right sides, respectively, of the image. +.sp +Alternatively, you can specify \fB-width\fP and just one of +\fB-left\fP and \fB-right\fP and \fBpnmpad\fP calculates the required +padding on the other side to make the output \fIwidth\fP pixels wide. If +the \fB-width\fP value is less than the width of the input image plus the +specified padding, \fBpnmpad\fP ignores \fB-width\fP. +.sp +If you specify all three of \fB-width\fP, \fB-left\fP, and +\fB-right\fP, you must ensure that the \fB-left\fP and \fB-right\fP +padding are sufficient to make the image at least as wide as +\fB-width\fP specifies, and in that case \fB-width\fP has no effect on the +output. Otherwise, \fBpnmpad\fP fails. +.sp +When you specify \fB-width\fP without \fB-left\fP or +\fB-right\fP, and \fB-width\fP is larger than the input image, +\fBpnmpad\fP chooses left and right padding amounts in a certain +ratio. That ratio defaults to half, but you can set it to anything +(from 0 to 1) with the \fB-halign\fP option. If the input image is +already at least as wide as \fB-width\fP specifies, \fBpnmpad\fP +adds no padding. +.sp +Common values for \fB-halign\fP are: + +.TP +\fB0.0\fP +left aligned + +.TP +\fB0.5\fP +center aligned (default) + +.TP +\fB1.0\fP +right aligned + +.sp +\fB-mwidth=\fP\fIpixels\fP says to pad to a multiple of +\fIpixels\fP pixels. E.g. if \fIpixels\fP is 10, the output image width +will be a multiple of 10 pixels. \fBpnmpad\fP adds to whatever padding the +other options say to do to get to this multiple. It divides that padding +between the left and right sides of the image to maintain the ratio the other +options produce. E.g. if you say \fB-left=10 -right=10 -mwidth=50\fP with a +100-pixel image, you end up with a 150-pixel image with the extra padding +split evenly between left and right for a total of 25 pixels of padding +on the left and 25 on the right. If the other options indicate no +padding, \fBpnmpad\fP adds padding in the ratio specified by \fB-halign\fP +and if \fB-halign\fP is not specified, equally on both sides. +.sp +Before Netpbm 10.97 (December 2021), \fBpnmpad\fP does not allow +\fB-halign\fP with \fB-mwidth\fP and adds padding only on the right +when \fB-mwidth\fP is specified and the other options indicate no padding. +.sp +Before Netpbm 10.72 (September 2015), there is no \fB-mwidth\fP. +.sp +Before Netpbm 10.23 (July 2004), \fBpnmpad\fP did not allow the +\fB-left\fP or \fB-right\fP option together with \fB-width\fP. + +.TP +\fB-top=\fP\fIpixels\fP +.TP +\fB-bottom=\fP\fIpixels\fP +.TP +\fB-height=\fP\fIheight\fP +.TP +\fB-valign=\fP\fIratio\fP +.TP +\fB-mheight=\fP\fIpixels\fP +These options determine the vertical padding. They are analogous to the +horizontal padding options above. + +.TP +\fB-promote=\fP{\fBnone\fP|\fBformat\fP|\fBall\fP} +This option tells what to do when the \fB-color\fP option specifies a +color that cannot be represented in the input format, which ordinarily is also +the output format. For example, if the input is PGM (which can represent only +shades of gray), and you specify \fB-color=red\fP, should \fBpnmpad\fP make +the padding gray or make the output PPM? + + +.TP +\fBnone\fP + +Make the output have the same format and maxval as the input. + Adjust the pad color to the nearest color possible in that format + (black, white, or a shade of gray). +.TP +\fBformat\fP + +Make the output have the same maxval as the input, but make + the output format PPM if the pad color is not black, white, or gray. +.TP +\fBall\fP + +Make the format and maxval of the output capable of representing the + pad color. Make the format the least expressive format capable of + representing the pad color. Make the maxval the larger of 255 and + the maxval of the input image. + +.sp +The default is \fB-promote=all\fP. +.sp +Note that this promotion happens even if no actual padding happens, meaning +it isn't really necessary. The promotion is based on +what \fIwould\fP be required to represent padding of the specified color. +.sp +This option is valid only when you also specify \fB-color\fP. +.sp +This option was new in Netpbm 11.05 (December 2023). + +.TP +\fB-reportonly\fP + This causes \fBpnmpad\fP to write to Standard Output a description of the + padding it would have done instead of producing an output image. See + +.UR #reportonly +below +.UE +\& for a description of this output and ways + to use it. +.sp +This option was new in Netpbm 10.89 (December 2019). + +.TP +\fB-verbose\fP +This causes verbose messages. + + + +.UN reportonly +.SH REPORT ONLY +.PP +When you specify \fB-reportonly\fP, \fBpnmpad\fP does not produce an + output image. Instead, it writes to Standard Output a description of the + padding it would have done without \fB-reportonly\fP. +.PP +That description is one line of text, containing 6 decimal numbers of + pixels, separated by spaces: + + +.IP \(bu +left padding +.IP \(bu +right padding +.IP \(bu +top padding +.IP \(bu +bottom padding +.IP \(bu +output width +.IP \(bu +output height + +.PP +Example: +.nf + + 4 3 0 2 100 100 + + +.fi +.PP +One use for this is to make padding which is fancier than the black and + white that \fBpnmpad\fP can do. +.PP +In the following example, we pad an image with 10 pixels of gray all + around, without knowing the original image dimensions beforehand. We do + this by generating a gray image with \fBpbmmake\fP and then pasting the + subject image into the middle of it. +.PP +The example uses shell arrays, such as exist in Bash, but not Dash. + +.nf + \f(CW + pad=($(pnmpad -reportonly -left=10 -right=10 -top=10 -bottom=10 input.ppm)) + pbmmake -gray ${pad[4]} ${pad[5]} | \e + pnmpaste input.ppm ${pad[0]} ${pad[2]} - + \fP + +.fi + + +.UN history +.SH HISTORY +.PP +The command line syntax was originally more of a traditional Unix syntax, + with single-character margin size options \fB-l\fP, \fB-r\fP, \fB-t\fP, + and \fB-b\fP that took arguments concatenated to the option name, such + as \fB-l50\fP. This is in contrast to the more modern syntax used by + essentially all Netpbm programs, in which an option such as \fB-left\fP + (which can still be abbreviated \fB-l\fP) must have its name and value as + separate command line arguments (e.g. \fB-l 50\fP). + + The new syntax was accepted and the old syntax deprecated and removed from + documentation in Netpbm 9.25 (March 2002), and was no longer accepted in + Netpbm 11.05 (December 2023). + + The code was broken for most of that time so that an attempt to use the old + syntax would fail anyway. The bug was discovered only in testing; no user + ever reported encountering it. + +.UN seealso +.SH SEE ALSO +.BR "pbmmake" (1)\c +\&, +.BR "pnmpaste" (1)\c +\&, +.BR "pamcut" (1)\c +\&, +.BR "pnmcrop" (1)\c +\&, +.BR "pamcomp" (1)\c +\&, +.BR "pnmmargin" (1)\c +\&, +.BR "pbm" (1)\c +\& + + +.UN author +.SH AUTHOR +.PP +Copyright (C) 2002 by Martin van Beilen +.PP +Copyright (C) 1990 by Angus Duggan +.PP +Copyright (C) 1989 by Jef Poskanzer. +.PP +Permission to use, copy, modify, and distribute this software and +its documentation for any purpose and without fee is hereby granted, +provided that the above copyright notice appear in all copies and that +both that copyright notice and this permission notice appear in +supporting documentation. This software is provided "as is" +without express or implied warranty. +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/pnmpad.html +.PP
\ No newline at end of file |