diff options
Diffstat (limited to 'upstream/debian-unstable/man1/pnmcrop.1')
| -rw-r--r-- | upstream/debian-unstable/man1/pnmcrop.1 | 427 |
1 files changed, 427 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man1/pnmcrop.1 b/upstream/debian-unstable/man1/pnmcrop.1 new file mode 100644 index 00000000..9134e73d --- /dev/null +++ b/upstream/debian-unstable/man1/pnmcrop.1 @@ -0,0 +1,427 @@ +\ +.\" 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 "Pnmcrop User Manual" 1 "16 August 2020" "netpbm documentation" + +.SH NAME +pnmcrop - crop a Netpbm image + +.UN synopsis +.SH SYNOPSIS + +\fBpnmcrop\fP + +[\fB-white\fP +|\fB-black\fP +|\fB-sides\fP +|\fB-bg-color=\fP\fIcolor\fP +|\fB-bg-corner=\fP{ +\fBtopleft\fP|\fBtopright\fP|\fBbottomleft\fP|\fBbottomright\fP} +] + +[\fB-left\fP] + +[\fB-right\fP] + +[\fB-top\fP] + +[\fB-bottom\fP] + +[\fB-margin=\fP\fIpixels\fP] + +[\fB-closeness=\fP\fIcloseness_percent\fP] + +[\fB-borderfile=\fP\fIfilename\fP] + +[\fB-blank-image=\fP{\fBabort\fP|\fBpass\fP|\fBminimize\fP|\fBmaxcrop\fP}] + +{[\fB-reportfull\fP]|[\fB-reportsize\fP]} + +[\fB-verbose\fP] + +[\fIpnmfile\fP] +.PP +Minimum unique abbreviation of option is acceptable. You may use +double hyphens instead of single hyphen to denote options. You may use +white space in place of the equals sign to separate an option name +from its value. + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBpnmcrop\fP reads a PBM, PGM, or PPM image as input, removes +borders that are the background color, and produces the same type of +image as output. +.PP +If you don't specify otherwise, \fBpnmcrop\fP assumes the +background color is whatever color the top left and right corners of +the image are and if they are different colors, something midway +between them. You can specify that the background is white or black +with the \fB-white\fP and \fB-black\fP options or make +\fBpnmcrop\fP base its guess on all four corners instead of just two +with \fB-sides\fP. +.PP +By default, \fBpnmcrop\fP chops off any stripe of background color +it finds, on all four sides. You can tell \fBpnmcrop\fP to remove +only specific borders with the \fB-left\fP, \fB-right\fP, + \fB-top\fP, and \fB-bottom\fP options. +.PP +But note that \fBpnmcrop\fP's determination of the background color is +independent of which edges you crop, which may not be intuitive. For example, +imagine an image with a blue border at the top and a black border at the +bottom and you say to crop the bottom (\fB-bottom\fP). You may have expected +to crop the black border, but you actually won't crop anything, +because \fBpnmcrop\fP considers the background color to be whatever color the +top two corners are, which is blue, and there is no blue at the bottom of the +image. If you do want \fBpnmcrop\fP to take the background color from the +edges being cropped, use \fB-bg-corner\fP. + +.PP +If you want to leave some border, use the \fB-margin\fP option. It +will not only spare some of the border from cropping, but will fill in +(with what \fBpnmcrop\fP considers the background color) if necessary +to get up to that size. +.PP +If the input is a multi-image stream, \fBpnmcrop\fP processes each +one independently and produces a multi-image stream as output. It chooses +where to crop independently for each image. So if you start with a stream +of images of the same dimensions, you may end up with images of differing +dimensions. Before Netpbm 10.37 (December 2006), \fBpnmcrop\fP ignored +all input images but the first. +.PP +If you want to chop a specific amount off the side of an image, use +\fBpamcut\fP. +.PP +If you want to add different borders after removing the existing ones, +use \fBpamcat\fP or \fBpamcomp\fP. + + +.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 +\&), \fBpnmcrop\fP recognizes the following +command line options: + + +.TP +\fB-white\fP +Take white to be the background color. \fBpnmcrop\fP removes +borders which are white. +.sp +You may specify at most one of \fB-black\fP, \fB-white\fP, \fB-sides\fP, +\fB-bg-color\fP, and \fB-bg-corner\fP. + +.TP +\fB-black\fP +Take black to be the background color. \fBpnmcrop \fP removes +borders which are black. +.sp +You may specify at most one of \fB-black\fP, \fB-white\fP, \fB-sides\fP, +\fB-bg-color\fP, and \fB-bg-corner\fP. + +.TP +\fB-bg-color=\fP\fIcolor\fP +This tells \fBpnmcrop\fP what color is the background - it will crop +areas of this color. \fIcolor\fP is a value that would be used as the +.UR libnetpbm_image.html#colorname +argument of the \fBpnm_parsecolor()\fP library routine +.UE +\&. +.sp +You may specify at most one of \fB-black\fP, \fB-white\fP, \fB-sides\fP, +\fB-bg-color\fP, and \fB-bg-corner\fP. +.sp +This option was new in Netpbm 10.86 (March 2019). + +.TP +\fB-sides\fP +Determine the background color from the colors of the four corners +of the input image. \fBpnmcrop\fP removes borders which are of the +background color. +.sp +If at least three of the four corners are the same color, +\fBpnmcrop \fP takes that as the background color. If not, +\fBpnmcrop\fP looks for two corners of the same color in the +following order, taking the first found as the background color: top, +left, right, bottom. If all four corners are different colors, +\fBpnmcrop\fP assumes an average of the four colors as the background +color. +.sp +The \fB-sides\fP option slows \fBpnmcrop\fP down, as it reads the +entire image to determine the background color in addition to the up +to three times that it would read it without \fB-sides\fP. +.sp +You may specify at most one of \fB-black\fP, \fB-white\fP, \fB-sides\fP, +\fB-bg-color\fP, and \fB-bg-corner\fP. + +.TP +\fB-bg-corner=\fP{\fBtopleft\fP|\fBtopright\fP|\fBbottomleft\fP|\fBbottomright\fP +This option indicates a corner which is background. \fBpnmcrop\fP will +use the color of this corner as the background color and crop edges of that +color. +.sp +You may specify at most one of \fB-black\fP, \fB-white\fP, \fB-sides\fP, +\fB-bg-color\fP, and \fB-bg-corner\fP. +.sp +This option was new in Netpbm 10.86 (March 2019). + +.TP +\fB-left\fP +Remove any left border. + +.TP +\fB-right\fP +Remove any right border. + +.TP +\fB-top\fP +Remove any top border. + +.TP +\fB-bottom\fP +Remove any bottom border. + +.TP +\fB-margin=\fP\fIpixels\fP +Leave \fIpixels\fP pixels of border. Expand the border to this size +if necessary. +.sp +This option was new in Netpbm 10.29 (August 2005). + +.TP +\fB-closeness=\fP\fIcloseness_percent\fP +Any color in the image that is at least this close to the operative +background color is considered to be background. +.sp +You can use this if the image has borders that vary slightly in color, such +as would be the case in a photograph. Consider a photograph against a white +screen. The color of the screen varies slightly with shading and dirt and +such, but is still quite distinct in color from the subject of the +photograph. \fBpnmcrop\fP will choose some particular shade as the +background color and if you specify an appropriate \fB-closeness\fP value, it +will correctly identify all of the screen as background and crop it off. +.sp +To implement more complex rules for identifying background, use +\fB-borderfile\fP. +.sp +The default is zero, which means a pixel's color must exactly match the +background color for the pixel to be considered part of a background border. +.sp +This option was new in Netpbm 10.78 (March 2017). With older Netpbm, +colors must match exactly. + +.TP +\fB-borderfile=\fP\fIfilename\fP +Use the image in the file named \fIfilename\fP instead of the input +image to determine where the borders of the input image are and the +background color. +.sp +Without this option, \fBpnmcrop\fP examines the input image and figures +out what part of the image is border and what part is foreground (not border), +as well as the background color. With this option, \fBpnmcrop\fP finds the +borders in one image, then uses the those four border sizes (left, right, top, +bottom) in cropping a different image. Furthermore, if you use +\fB-margin\fP to add borders, the color of those borders is the background +color \fBpnmcrop\fP detects in the border file. +.sp +The point of this is that you may want to help \fBpnmcrop\fP to come to a +different conclusion as to where the borders are and what the background color +is by preprocessing the input image. For example, consider an image that has +speckles of noise in its borders. \fBpnmcrop\fP isn't smart enough to +recognize these as noise; it sees them as foreground image. So \fBpnmcrop\fP +considers most of your borders to be foreground and does not crop them off as +you want. To fix this, run the image through a despeckler such as +\fBpbmclean\fP and tell \fBpnmcrop\fP to use the despeckled version of the +image as the \fB-borderfile\fP image, but the original speckled version as +the input image. That way, you crop the borders, but retain the true +foreground image, speckles and all. +.sp +The border file must have the same number of images in it as the input +file; the background color determination for image N of the input is based on +the image N of the border file. +.sp +This option was new in Netpbm 10.29 (August 2005). +.sp +Before Netpbm 10.46 (March 2009), the original image and not the +border file determines the background color. \fBpnmcrop\fP +fails if there is no apparent background color in the original image +(i.e. the corners of the image don't have a common color). + +.TP +\fB-blank-image=\fP{\fBabort\fP|\fBpass\fP|\fBminimize\fP|\fBmaxcrop\fP} +This determines how \fBpnmcrop\fP handles an image which is entirely + background (blank), a case where cropping doesn't make much sense. + + +.TP +abort + +program fails, with explanatory message (default) + +.TP +pass + +Output image is the same as the input image. + \fB-margin\fP has no effect. + +.TP +minimize + +output is a single row, column, or pixel (of the background color). + If you crop both vertically and horizontally (the default), it is a + single pixel. If you crop only vertically, a single row, of the + original width. If you crop only horizontally, it is a single column, + of the original height. +.sp +This is a somewhat incongruous result; the mathematically consistent + result of cropping the background from an image that is entirely + background would be an image with no pixels at all. But such a thing + does not exist in the Netpbm formats (and you probably wouldn't want + it anyway, because whoever processes this output may not tolerate + that). +.sp +The background can be more than one color when you specify + \fB-closeness\fP, so it matters which row, column, or pixel remains. + If you crop on the top and not bottom, it is the last row that remains. + If you crop on both the top and bottom, it is the middle row that + remains. The other cases follow similarly. +.sp +If you specify a margin (\fB-margin\fP), the output image consists + entirely of the margins; there is no single row, column, or pixel + between the margins. So with \fB-margin\fP, the incongruity + mentioned above does not exist. But before Netpbm 10.92 (September + 2020), \fB-margin\fP was ignored with \fB-blank-image=minimize\fP. + +.TP +maxcrop + +This odd function selects a hypothetical cropping which is not even + possible, and therefore is valid only with \fB-reportfull\fP or + \fB-reportsize\fP. The cropping that this selects is a crop of the + entire image on every side on which you request cropping. So if you + request cropping only on the left, of a 600 pixel wide image, this + selects a cropping of 600 pixels from the left and none from the other + three sides. Note that were this cropping actually applied, this would + produce an image with no pixels, which is not a valid Netpbm image. But + it gets stranger still if you request cropping on both the right and the + left. In that case, the cropping selected is a cropping of 600 pixels + from both the right and left sides, which would leave a negative-width + image. +.sp + This is actually useful if you are trying to find a single set of + cropping parameters to crop a stream of images. To do this, you could + do a pass with \fB-reportsize\fP and \fB-blank-image=maxcrop\fP to + compute the maximum crop for each edge, and then use those numbers in + \fB-crop\fIxxx\fP\fP options on a \fBpamcut\fP pass to do the crop. + In this scenario, any all-background (blank) images would have no effect + on the cropping parameters you compute. If you do this, you must give + special consideration to a stream with nothing but blank images. + + +.sp +\fB-margin\fP is always ignored when the image is all background. +.sp +This option was new in Netpbm 10.86 (March 2019). + +.TP +\fB-reportfull\fP +With this option, \fBpnmcrop\fP does not actually crop anything. Instead, it +just prints to Standard Output parameters of the cropping it would have done. +The output is a single line per image, like in this example: + +.nf + + 0 +7 -20 -10 200 300 rgb-255:10/0/255 0.0 + + +.fi +.sp +The line is composed of the following blank-delimited tokens: + + +.IP \(bu +how many pixels would be cropped or padded on the left. This is + a signed decimal number, where + means pad and - means crop. If there + would be no change, this is unsigned zero. + +.IP \(bu +same, but for the right side. + +.IP \(bu +same, but for the top. + +.IP \(bu +same, but for the bottom. + +.IP \(bu +the resulting image width in pixels, in decimal. + +.IP \(bu +the resulting image height in pixels, in decimal. + +.IP \(bu +The color \fBpnmcrop\fP took to be the background color, like + 'rgb-255:10/0/255' (This is a format recognized by + the +.UR libnetpbm_image.html#colorname +\fBpnm_parsecolor()\fP +.UE +\& + library routine). The maxval in the color specification is the maxval of + the image. + +.IP \(bu +The closeness value (see \fB-closeness\fP option) \fBpnmcrop\fP + used, in floating point decimal. + +.sp +You cannot use \fB-borderfile\fP together with this option. +.sp +This option was new in Netpbm 10.86 (March 2019). + +.TP +\fB-reportsize\fP +This is like \fB-reportfull\fP, but reports only the left, right, top, +bottom, width, and height. +.sp +You cannot use \fB-borderfile\fP together with this option. +.sp +This option was new in Netpbm 10.86 (March 2019). + +.TP +\fB-verbose\fP +Print on Standard Error information about the processing, +including exactly how much is being cropped off of which sides. + + + +.UN seealso +.SH SEE ALSO +.BR "pamcut" (1)\c +\&, +.BR "pamfile" (1)\c +\&, +.BR "pnm" (1)\c +\& + +.UN author +.SH AUTHOR + +Copyright (C) 1989 by Jef Poskanzer. +.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/pnmcrop.html +.PP
\ No newline at end of file |