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