| 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 "Pnmcrop User Manual" 1 "16 August 2020" "netpbm documentation" |
| 7 |
|
| 8 |
.SH NAME |
| 9 |
pnmcrop - crop a Netpbm image |
| 10 |
|
| 11 |
.UN synopsis |
| 12 |
.SH SYNOPSIS |
| 13 |
|
| 14 |
\fBpnmcrop\fP |
| 15 |
|
| 16 |
[\fB-white\fP |
| 17 |
|\fB-black\fP |
| 18 |
|\fB-sides\fP |
| 19 |
|\fB-bg-color=\fP\fIcolor\fP |
| 20 |
|\fB-bg-corner=\fP{ |
| 21 |
\fBtopleft\fP|\fBtopright\fP|\fBbottomleft\fP|\fBbottomright\fP} |
| 22 |
] |
| 23 |
|
| 24 |
[\fB-left\fP] |
| 25 |
|
| 26 |
[\fB-right\fP] |
| 27 |
|
| 28 |
[\fB-top\fP] |
| 29 |
|
| 30 |
[\fB-bottom\fP] |
| 31 |
|
| 32 |
[\fB-margin=\fP\fIpixels\fP] |
| 33 |
|
| 34 |
[\fB-closeness=\fP\fIcloseness_percent\fP] |
| 35 |
|
| 36 |
[\fB-borderfile=\fP\fIfilename\fP] |
| 37 |
|
| 38 |
[\fB-blank-image=\fP{\fBabort\fP|\fBpass\fP|\fBminimize\fP|\fBmaxcrop\fP}] |
| 39 |
|
| 40 |
{[\fB-reportfull\fP]|[\fB-reportsize\fP]} |
| 41 |
|
| 42 |
[\fB-verbose\fP] |
| 43 |
|
| 44 |
[\fIpnmfile\fP] |
| 45 |
.PP |
| 46 |
Minimum unique abbreviation of option is acceptable. You may use |
| 47 |
double hyphens instead of single hyphen to denote options. You may use |
| 48 |
white space in place of the equals sign to separate an option name |
| 49 |
from its value. |
| 50 |
|
| 51 |
.UN description |
| 52 |
.SH DESCRIPTION |
| 53 |
.PP |
| 54 |
This program is part of |
| 55 |
.BR "Netpbm" (1)\c |
| 56 |
\&. |
| 57 |
.PP |
| 58 |
\fBpnmcrop\fP reads a PBM, PGM, or PPM image as input, removes |
| 59 |
borders that are the background color, and produces the same type of |
| 60 |
image as output. |
| 61 |
.PP |
| 62 |
If you don't specify otherwise, \fBpnmcrop\fP assumes the |
| 63 |
background color is whatever color the top left and right corners of |
| 64 |
the image are and if they are different colors, something midway |
| 65 |
between them. You can specify that the background is white or black |
| 66 |
with the \fB-white\fP and \fB-black\fP options or make |
| 67 |
\fBpnmcrop\fP base its guess on all four corners instead of just two |
| 68 |
with \fB-sides\fP. |
| 69 |
.PP |
| 70 |
By default, \fBpnmcrop\fP chops off any stripe of background color |
| 71 |
it finds, on all four sides. You can tell \fBpnmcrop\fP to remove |
| 72 |
only specific borders with the \fB-left\fP, \fB-right\fP, |
| 73 |
\fB-top\fP, and \fB-bottom\fP options. |
| 74 |
.PP |
| 75 |
But note that \fBpnmcrop\fP's determination of the background color is |
| 76 |
independent of which edges you crop, which may not be intuitive. For example, |
| 77 |
imagine an image with a blue border at the top and a black border at the |
| 78 |
bottom and you say to crop the bottom (\fB-bottom\fP). You may have expected |
| 79 |
to crop the black border, but you actually won't crop anything, |
| 80 |
because \fBpnmcrop\fP considers the background color to be whatever color the |
| 81 |
top two corners are, which is blue, and there is no blue at the bottom of the |
| 82 |
image. If you do want \fBpnmcrop\fP to take the background color from the |
| 83 |
edges being cropped, use \fB-bg-corner\fP. |
| 84 |
|
| 85 |
.PP |
| 86 |
If you want to leave some border, use the \fB-margin\fP option. It |
| 87 |
will not only spare some of the border from cropping, but will fill in |
| 88 |
(with what \fBpnmcrop\fP considers the background color) if necessary |
| 89 |
to get up to that size. |
| 90 |
.PP |
| 91 |
If the input is a multi-image stream, \fBpnmcrop\fP processes each |
| 92 |
one independently and produces a multi-image stream as output. It chooses |
| 93 |
where to crop independently for each image. So if you start with a stream |
| 94 |
of images of the same dimensions, you may end up with images of differing |
| 95 |
dimensions. Before Netpbm 10.37 (December 2006), \fBpnmcrop\fP ignored |
| 96 |
all input images but the first. |
| 97 |
.PP |
| 98 |
If you want to chop a specific amount off the side of an image, use |
| 99 |
\fBpamcut\fP. |
| 100 |
.PP |
| 101 |
If you want to add different borders after removing the existing ones, |
| 102 |
use \fBpamcat\fP or \fBpamcomp\fP. |
| 103 |
|
| 104 |
|
| 105 |
.UN options |
| 106 |
.SH OPTIONS |
| 107 |
.PP |
| 108 |
In addition to the options common to all programs based on libnetpbm |
| 109 |
(most notably \fB-quiet\fP, see |
| 110 |
.UR index.html#commonoptions |
| 111 |
Common Options |
| 112 |
.UE |
| 113 |
\&), \fBpnmcrop\fP recognizes the following |
| 114 |
command line options: |
| 115 |
|
| 116 |
|
| 117 |
.TP |
| 118 |
\fB-white\fP |
| 119 |
Take white to be the background color. \fBpnmcrop\fP removes |
| 120 |
borders which are white. |
| 121 |
.sp |
| 122 |
You may specify at most one of \fB-black\fP, \fB-white\fP, \fB-sides\fP, |
| 123 |
\fB-bg-color\fP, and \fB-bg-corner\fP. |
| 124 |
|
| 125 |
.TP |
| 126 |
\fB-black\fP |
| 127 |
Take black to be the background color. \fBpnmcrop \fP removes |
| 128 |
borders which are black. |
| 129 |
.sp |
| 130 |
You may specify at most one of \fB-black\fP, \fB-white\fP, \fB-sides\fP, |
| 131 |
\fB-bg-color\fP, and \fB-bg-corner\fP. |
| 132 |
|
| 133 |
.TP |
| 134 |
\fB-bg-color=\fP\fIcolor\fP |
| 135 |
This tells \fBpnmcrop\fP what color is the background - it will crop |
| 136 |
areas of this color. \fIcolor\fP is a value that would be used as the |
| 137 |
.UR libnetpbm_image.html#colorname |
| 138 |
argument of the \fBpnm_parsecolor()\fP library routine |
| 139 |
.UE |
| 140 |
\&. |
| 141 |
.sp |
| 142 |
You may specify at most one of \fB-black\fP, \fB-white\fP, \fB-sides\fP, |
| 143 |
\fB-bg-color\fP, and \fB-bg-corner\fP. |
| 144 |
.sp |
| 145 |
This option was new in Netpbm 10.86 (March 2019). |
| 146 |
|
| 147 |
.TP |
| 148 |
\fB-sides\fP |
| 149 |
Determine the background color from the colors of the four corners |
| 150 |
of the input image. \fBpnmcrop\fP removes borders which are of the |
| 151 |
background color. |
| 152 |
.sp |
| 153 |
If at least three of the four corners are the same color, |
| 154 |
\fBpnmcrop \fP takes that as the background color. If not, |
| 155 |
\fBpnmcrop\fP looks for two corners of the same color in the |
| 156 |
following order, taking the first found as the background color: top, |
| 157 |
left, right, bottom. If all four corners are different colors, |
| 158 |
\fBpnmcrop\fP assumes an average of the four colors as the background |
| 159 |
color. |
| 160 |
.sp |
| 161 |
The \fB-sides\fP option slows \fBpnmcrop\fP down, as it reads the |
| 162 |
entire image to determine the background color in addition to the up |
| 163 |
to three times that it would read it without \fB-sides\fP. |
| 164 |
.sp |
| 165 |
You may specify at most one of \fB-black\fP, \fB-white\fP, \fB-sides\fP, |
| 166 |
\fB-bg-color\fP, and \fB-bg-corner\fP. |
| 167 |
|
| 168 |
.TP |
| 169 |
\fB-bg-corner=\fP{\fBtopleft\fP|\fBtopright\fP|\fBbottomleft\fP|\fBbottomright\fP |
| 170 |
This option indicates a corner which is background. \fBpnmcrop\fP will |
| 171 |
use the color of this corner as the background color and crop edges of that |
| 172 |
color. |
| 173 |
.sp |
| 174 |
You may specify at most one of \fB-black\fP, \fB-white\fP, \fB-sides\fP, |
| 175 |
\fB-bg-color\fP, and \fB-bg-corner\fP. |
| 176 |
.sp |
| 177 |
This option was new in Netpbm 10.86 (March 2019). |
| 178 |
|
| 179 |
.TP |
| 180 |
\fB-left\fP |
| 181 |
Remove any left border. |
| 182 |
|
| 183 |
.TP |
| 184 |
\fB-right\fP |
| 185 |
Remove any right border. |
| 186 |
|
| 187 |
.TP |
| 188 |
\fB-top\fP |
| 189 |
Remove any top border. |
| 190 |
|
| 191 |
.TP |
| 192 |
\fB-bottom\fP |
| 193 |
Remove any bottom border. |
| 194 |
|
| 195 |
.TP |
| 196 |
\fB-margin=\fP\fIpixels\fP |
| 197 |
Leave \fIpixels\fP pixels of border. Expand the border to this size |
| 198 |
if necessary. |
| 199 |
.sp |
| 200 |
This option was new in Netpbm 10.29 (August 2005). |
| 201 |
|
| 202 |
.TP |
| 203 |
\fB-closeness=\fP\fIcloseness_percent\fP |
| 204 |
Any color in the image that is at least this close to the operative |
| 205 |
background color is considered to be background. |
| 206 |
.sp |
| 207 |
You can use this if the image has borders that vary slightly in color, such |
| 208 |
as would be the case in a photograph. Consider a photograph against a white |
| 209 |
screen. The color of the screen varies slightly with shading and dirt and |
| 210 |
such, but is still quite distinct in color from the subject of the |
| 211 |
photograph. \fBpnmcrop\fP will choose some particular shade as the |
| 212 |
background color and if you specify an appropriate \fB-closeness\fP value, it |
| 213 |
will correctly identify all of the screen as background and crop it off. |
| 214 |
.sp |
| 215 |
To implement more complex rules for identifying background, use |
| 216 |
\fB-borderfile\fP. |
| 217 |
.sp |
| 218 |
The default is zero, which means a pixel's color must exactly match the |
| 219 |
background color for the pixel to be considered part of a background border. |
| 220 |
.sp |
| 221 |
This option was new in Netpbm 10.78 (March 2017). With older Netpbm, |
| 222 |
colors must match exactly. |
| 223 |
|
| 224 |
.TP |
| 225 |
\fB-borderfile=\fP\fIfilename\fP |
| 226 |
Use the image in the file named \fIfilename\fP instead of the input |
| 227 |
image to determine where the borders of the input image are and the |
| 228 |
background color. |
| 229 |
.sp |
| 230 |
Without this option, \fBpnmcrop\fP examines the input image and figures |
| 231 |
out what part of the image is border and what part is foreground (not border), |
| 232 |
as well as the background color. With this option, \fBpnmcrop\fP finds the |
| 233 |
borders in one image, then uses the those four border sizes (left, right, top, |
| 234 |
bottom) in cropping a different image. Furthermore, if you use |
| 235 |
\fB-margin\fP to add borders, the color of those borders is the background |
| 236 |
color \fBpnmcrop\fP detects in the border file. |
| 237 |
.sp |
| 238 |
The point of this is that you may want to help \fBpnmcrop\fP to come to a |
| 239 |
different conclusion as to where the borders are and what the background color |
| 240 |
is by preprocessing the input image. For example, consider an image that has |
| 241 |
speckles of noise in its borders. \fBpnmcrop\fP isn't smart enough to |
| 242 |
recognize these as noise; it sees them as foreground image. So \fBpnmcrop\fP |
| 243 |
considers most of your borders to be foreground and does not crop them off as |
| 244 |
you want. To fix this, run the image through a despeckler such as |
| 245 |
\fBpbmclean\fP and tell \fBpnmcrop\fP to use the despeckled version of the |
| 246 |
image as the \fB-borderfile\fP image, but the original speckled version as |
| 247 |
the input image. That way, you crop the borders, but retain the true |
| 248 |
foreground image, speckles and all. |
| 249 |
.sp |
| 250 |
The border file must have the same number of images in it as the input |
| 251 |
file; the background color determination for image N of the input is based on |
| 252 |
the image N of the border file. |
| 253 |
.sp |
| 254 |
This option was new in Netpbm 10.29 (August 2005). |
| 255 |
.sp |
| 256 |
Before Netpbm 10.46 (March 2009), the original image and not the |
| 257 |
border file determines the background color. \fBpnmcrop\fP |
| 258 |
fails if there is no apparent background color in the original image |
| 259 |
(i.e. the corners of the image don't have a common color). |
| 260 |
|
| 261 |
.TP |
| 262 |
\fB-blank-image=\fP{\fBabort\fP|\fBpass\fP|\fBminimize\fP|\fBmaxcrop\fP} |
| 263 |
This determines how \fBpnmcrop\fP handles an image which is entirely |
| 264 |
background (blank), a case where cropping doesn't make much sense. |
| 265 |
|
| 266 |
|
| 267 |
.TP |
| 268 |
abort |
| 269 |
|
| 270 |
program fails, with explanatory message (default) |
| 271 |
|
| 272 |
.TP |
| 273 |
pass |
| 274 |
|
| 275 |
Output image is the same as the input image. |
| 276 |
\fB-margin\fP has no effect. |
| 277 |
|
| 278 |
.TP |
| 279 |
minimize |
| 280 |
|
| 281 |
output is a single row, column, or pixel (of the background color). |
| 282 |
If you crop both vertically and horizontally (the default), it is a |
| 283 |
single pixel. If you crop only vertically, a single row, of the |
| 284 |
original width. If you crop only horizontally, it is a single column, |
| 285 |
of the original height. |
| 286 |
.sp |
| 287 |
This is a somewhat incongruous result; the mathematically consistent |
| 288 |
result of cropping the background from an image that is entirely |
| 289 |
background would be an image with no pixels at all. But such a thing |
| 290 |
does not exist in the Netpbm formats (and you probably wouldn't want |
| 291 |
it anyway, because whoever processes this output may not tolerate |
| 292 |
that). |
| 293 |
.sp |
| 294 |
The background can be more than one color when you specify |
| 295 |
\fB-closeness\fP, so it matters which row, column, or pixel remains. |
| 296 |
If you crop on the top and not bottom, it is the last row that remains. |
| 297 |
If you crop on both the top and bottom, it is the middle row that |
| 298 |
remains. The other cases follow similarly. |
| 299 |
.sp |
| 300 |
If you specify a margin (\fB-margin\fP), the output image consists |
| 301 |
entirely of the margins; there is no single row, column, or pixel |
| 302 |
between the margins. So with \fB-margin\fP, the incongruity |
| 303 |
mentioned above does not exist. But before Netpbm 10.92 (September |
| 304 |
2020), \fB-margin\fP was ignored with \fB-blank-image=minimize\fP. |
| 305 |
|
| 306 |
.TP |
| 307 |
maxcrop |
| 308 |
|
| 309 |
This odd function selects a hypothetical cropping which is not even |
| 310 |
possible, and therefore is valid only with \fB-reportfull\fP or |
| 311 |
\fB-reportsize\fP. The cropping that this selects is a crop of the |
| 312 |
entire image on every side on which you request cropping. So if you |
| 313 |
request cropping only on the left, of a 600 pixel wide image, this |
| 314 |
selects a cropping of 600 pixels from the left and none from the other |
| 315 |
three sides. Note that were this cropping actually applied, this would |
| 316 |
produce an image with no pixels, which is not a valid Netpbm image. But |
| 317 |
it gets stranger still if you request cropping on both the right and the |
| 318 |
left. In that case, the cropping selected is a cropping of 600 pixels |
| 319 |
from both the right and left sides, which would leave a negative-width |
| 320 |
image. |
| 321 |
.sp |
| 322 |
This is actually useful if you are trying to find a single set of |
| 323 |
cropping parameters to crop a stream of images. To do this, you could |
| 324 |
do a pass with \fB-reportsize\fP and \fB-blank-image=maxcrop\fP to |
| 325 |
compute the maximum crop for each edge, and then use those numbers in |
| 326 |
\fB-crop\fIxxx\fP\fP options on a \fBpamcut\fP pass to do the crop. |
| 327 |
In this scenario, any all-background (blank) images would have no effect |
| 328 |
on the cropping parameters you compute. If you do this, you must give |
| 329 |
special consideration to a stream with nothing but blank images. |
| 330 |
|
| 331 |
|
| 332 |
.sp |
| 333 |
\fB-margin\fP is always ignored when the image is all background. |
| 334 |
.sp |
| 335 |
This option was new in Netpbm 10.86 (March 2019). |
| 336 |
|
| 337 |
.TP |
| 338 |
\fB-reportfull\fP |
| 339 |
With this option, \fBpnmcrop\fP does not actually crop anything. Instead, it |
| 340 |
just prints to Standard Output parameters of the cropping it would have done. |
| 341 |
The output is a single line per image, like in this example: |
| 342 |
|
| 343 |
.nf |
| 344 |
|
| 345 |
0 +7 -20 -10 200 300 rgb-255:10/0/255 0.0 |
| 346 |
|
| 347 |
|
| 348 |
.fi |
| 349 |
.sp |
| 350 |
The line is composed of the following blank-delimited tokens: |
| 351 |
|
| 352 |
|
| 353 |
.IP \(bu |
| 354 |
how many pixels would be cropped or padded on the left. This is |
| 355 |
a signed decimal number, where + means pad and - means crop. If there |
| 356 |
would be no change, this is unsigned zero. |
| 357 |
|
| 358 |
.IP \(bu |
| 359 |
same, but for the right side. |
| 360 |
|
| 361 |
.IP \(bu |
| 362 |
same, but for the top. |
| 363 |
|
| 364 |
.IP \(bu |
| 365 |
same, but for the bottom. |
| 366 |
|
| 367 |
.IP \(bu |
| 368 |
the resulting image width in pixels, in decimal. |
| 369 |
|
| 370 |
.IP \(bu |
| 371 |
the resulting image height in pixels, in decimal. |
| 372 |
|
| 373 |
.IP \(bu |
| 374 |
The color \fBpnmcrop\fP took to be the background color, like |
| 375 |
'rgb-255:10/0/255' (This is a format recognized by |
| 376 |
the |
| 377 |
.UR libnetpbm_image.html#colorname |
| 378 |
\fBpnm_parsecolor()\fP |
| 379 |
.UE |
| 380 |
\& |
| 381 |
library routine). The maxval in the color specification is the maxval of |
| 382 |
the image. |
| 383 |
|
| 384 |
.IP \(bu |
| 385 |
The closeness value (see \fB-closeness\fP option) \fBpnmcrop\fP |
| 386 |
used, in floating point decimal. |
| 387 |
|
| 388 |
.sp |
| 389 |
You cannot use \fB-borderfile\fP together with this option. |
| 390 |
.sp |
| 391 |
This option was new in Netpbm 10.86 (March 2019). |
| 392 |
|
| 393 |
.TP |
| 394 |
\fB-reportsize\fP |
| 395 |
This is like \fB-reportfull\fP, but reports only the left, right, top, |
| 396 |
bottom, width, and height. |
| 397 |
.sp |
| 398 |
You cannot use \fB-borderfile\fP together with this option. |
| 399 |
.sp |
| 400 |
This option was new in Netpbm 10.86 (March 2019). |
| 401 |
|
| 402 |
.TP |
| 403 |
\fB-verbose\fP |
| 404 |
Print on Standard Error information about the processing, |
| 405 |
including exactly how much is being cropped off of which sides. |
| 406 |
|
| 407 |
|
| 408 |
|
| 409 |
.UN seealso |
| 410 |
.SH SEE ALSO |
| 411 |
.BR "pamcut" (1)\c |
| 412 |
\&, |
| 413 |
.BR "pamfile" (1)\c |
| 414 |
\&, |
| 415 |
.BR "pnm" (1)\c |
| 416 |
\& |
| 417 |
|
| 418 |
.UN author |
| 419 |
.SH AUTHOR |
| 420 |
|
| 421 |
Copyright (C) 1989 by Jef Poskanzer. |
| 422 |
.SH DOCUMENT SOURCE |
| 423 |
This manual page was generated by the Netpbm tool 'makeman' from HTML |
| 424 |
source. The master documentation is at |
| 425 |
.IP |
| 426 |
.B http://netpbm.sourceforge.net/doc/pnmcrop.html |
| 427 |
.PP |