| 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 "Pamcut User Manual" 1 "26 February 2024" "netpbm documentation" |
| 7 |
|
| 8 |
.SH NAME |
| 9 |
pamcut - select a rectangular region of a PAM, PBM, PGM, or PPM image |
| 10 |
|
| 11 |
.UN synopsis |
| 12 |
.SH SYNOPSIS |
| 13 |
|
| 14 |
\fBpamcut\fP |
| 15 |
|
| 16 |
[\fB-left \fP\fIcolnum\fP] |
| 17 |
|
| 18 |
[\fB-right \fP\fIcolnum\fP] |
| 19 |
|
| 20 |
[\fB-top \fP\fIrownum\fP] |
| 21 |
|
| 22 |
[\fB-bottom \fP\fIrownum\fP] |
| 23 |
|
| 24 |
[\fB-width \fP\fIcols\fP] |
| 25 |
|
| 26 |
[\fB-height \fP\fIrows\fP] |
| 27 |
|
| 28 |
[\fB-pad\fP] |
| 29 |
|
| 30 |
[\fB-cropleft \fP\fInumcols\fP] |
| 31 |
|
| 32 |
[\fB-cropright \fP\fInumcols\fP] |
| 33 |
|
| 34 |
[\fB-croptop \fP\fInumrows\fP] |
| 35 |
|
| 36 |
[\fB-cropbottom \fP\fInumrows\fP] |
| 37 |
|
| 38 |
[\fB-reportonly\fP] |
| 39 |
|
| 40 |
[\fB-verbose\fP] |
| 41 |
|
| 42 |
[\fIleft\fP \fItop\fP \fIwidth\fP \fIheight\fP] |
| 43 |
|
| 44 |
[\fIpnmfile\fP] |
| 45 |
.PP |
| 46 |
Minimum unique abbreviations of options are 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 |
\fBpamcut\fP reads a PAM, PBM, PGM, or PPM image as input and |
| 59 |
extracts the specified rectangle, and produces the same kind of image |
| 60 |
as output. |
| 61 |
.PP |
| 62 |
You can specify either the rectangle to cut out and keep or specify the |
| 63 |
edges to crop off and discard, or a combination. |
| 64 |
.PP |
| 65 |
To request edges be cropped off, use options \fB-cropleft\fP, |
| 66 |
\fB-cropright\fP, \fB-croptop\fP, and \fB-cropbottom\fP to indicate how many |
| 67 |
rows or columns to discard. |
| 68 |
.PP |
| 69 |
For example, \fB-cropleft=50 -cropright=200\fP means to discard the |
| 70 |
leftmost 50 and rightmost 200 columns. |
| 71 |
.PP |
| 72 |
To specify the rectangle to keep, use \fB-left\fP, \fB-right\fP, |
| 73 |
\fB-top\fP, \fB-bottom\fP, \fB-width\fP, \fB-height\fP, and \fB-pad\fP |
| 74 |
options. |
| 75 |
.PP |
| 76 |
For example, \fB-left=50 -right=200\fP means to keep the 151 columns |
| 77 |
between Columns 50 and 200 inclusive. |
| 78 |
.PP |
| 79 |
You can code any mixture of the options. What you don't specify defaults. |
| 80 |
Those defaults are in favor of minimal cutting and in favor of cutting the |
| 81 |
right and bottom edges off and (with \fB-pad\fP) minimal padding and padding |
| 82 |
on the right and bottom. It is an error to overspecify, i.e. to specify all |
| 83 |
three of \fB-left\fP, \fB-right\fP, and \fB-width\fP or \fB-top\fP, |
| 84 |
\fB-bottom\fP, and \fB-height\fP or \fBright\fP as well as |
| 85 |
\fB-cropright\fP. |
| 86 |
.PP |
| 87 |
There is an older way to specify the rectangle to keep: positional |
| 88 |
arguments. Arguments were the only way available before July 2000, but you |
| 89 |
should not use them in new applications. Options are easier to remember and |
| 90 |
read, more expressive, and allow you to use defaults. |
| 91 |
.PP |
| 92 |
If you use both options and arguments, the two specifications get mixed in |
| 93 |
an unspecified way. |
| 94 |
.PP |
| 95 |
To use arguments, specify all four of the \fIleft\fP, \fItop\fP, |
| 96 |
\fIwidth\fP, and \fIheight\fP arguments. \fIleft\fP and \fItop\fP have |
| 97 |
the same effect as specifying them as the argument of a \fB-left\fP or |
| 98 |
\fB-top\fP option, respectively. \fIwidth\fP and \fIheight\fP have the |
| 99 |
same effect as specifying them as the argument of a \fB-width\fP or |
| 100 |
\fB-height\fP option, respectively, where they are positive. Where they are |
| 101 |
not positive, they have the same effect as specifying one less than the value |
| 102 |
as the argument to a \fB-right\fP or \fB-bottom\fP option, respectively. |
| 103 |
(E.g. \fIwidth\fP = 0 makes the cut go all the way to the right edge). |
| 104 |
Before July 2000, negative numbers were not allowed for \fIwidth\fP and |
| 105 |
\fIheight\fP. |
| 106 |
.PP |
| 107 |
Input is from Standard Input if you don't specify the input file |
| 108 |
\fIpnmfile\fP. |
| 109 |
.PP |
| 110 |
Output is to Standard Output. |
| 111 |
.PP |
| 112 |
\fBpamcut\fP works on a multi-image stream. It cuts each image in the |
| 113 |
stream independently and produces a multi-image stream output. Before |
| 114 |
Netpbm 10.32 (March 2006), it ignored all but the first image in the stream. |
| 115 |
.PP |
| 116 |
If you are splitting a single image into multiple same-size images, |
| 117 |
\fBpamdice\fP is faster and easier than running \fBpamcut\fP |
| 118 |
multiple times. |
| 119 |
.PP |
| 120 |
\fBpamcomp\fP is also useful for cutting and padding an image to a |
| 121 |
certain size. You create a background image of the desired frame |
| 122 |
dimensions and overlay the subject image on it. |
| 123 |
|
| 124 |
.UN options |
| 125 |
.SH OPTIONS |
| 126 |
.PP |
| 127 |
In addition to the options common to all programs based on libnetpbm |
| 128 |
(most notably \fB-quiet\fP, see |
| 129 |
.UR index.html#commonoptions |
| 130 |
Common Options |
| 131 |
.UE |
| 132 |
\&), \fBpamcut\fP recognizes the following |
| 133 |
command line options: |
| 134 |
|
| 135 |
|
| 136 |
.TP |
| 137 |
\fB-left=\fP\fIcolnum\fP |
| 138 |
The column number of the leftmost column to be in the output. |
| 139 |
Columns left of this get cut out. If a nonnegative number, it refers |
| 140 |
to columns numbered from 0 at the left, increasing to the right. If |
| 141 |
negative, it refers to columns numbered -1 at the right, decreasing to |
| 142 |
the left. |
| 143 |
|
| 144 |
.TP |
| 145 |
\fB-right=\fP\fIcolnum\fP |
| 146 |
The column number of the rightmost column to be in the output, |
| 147 |
numbered the same as for \fB-left.\fP Columns to the right of this |
| 148 |
get cut out. |
| 149 |
|
| 150 |
.TP |
| 151 |
\fB-top=\fP\fIrownum\fP |
| 152 |
The row number of the topmost row to be in the output. Rows above |
| 153 |
this get cut out. If a nonnegative number it refers to rows numbered |
| 154 |
from 0 at the top, increasing downward. If negative, it refers to |
| 155 |
columns numbered -1 at the bottom, decreasing upward. |
| 156 |
|
| 157 |
.TP |
| 158 |
\fB-bottom=\fP\fIrownum\fP |
| 159 |
The row number of the bottom-most row to be in the output, |
| 160 |
numbered the same as for \fB-top\fP. Rows below this get cut out. |
| 161 |
|
| 162 |
.TP |
| 163 |
\fB-width=\fP\fIcols\fP |
| 164 |
The number of columns to be in the output. Must be positive. |
| 165 |
|
| 166 |
.TP |
| 167 |
\fB-height=\fP\fIrows\fP |
| 168 |
The number of rows to be in the output. Must be positive. |
| 169 |
|
| 170 |
.TP |
| 171 |
\fB-cropleft\fP |
| 172 |
.TP |
| 173 |
\fB-cropright\fP |
| 174 |
.TP |
| 175 |
\fB-croptop\fP |
| 176 |
.TP |
| 177 |
\fB-cropbottom\fP |
| 178 |
These options tell how many rows or columns to crop from the left, |
| 179 |
right, top, or bottom edges, respectively. |
| 180 |
.sp |
| 181 |
The value must not be negative. |
| 182 |
.sp |
| 183 |
These option were new in Netpbm 10.85 (December 2018). Before that, you |
| 184 |
can achieve the same thing with \fB-left\fP, \fBtop\fP, and negative values |
| 185 |
for \fB-right\fP and \fB-bottom\fP. Remember to subtract one in the latter |
| 186 |
case; e.g. the equivalent of \fB-cropright=1\fP is \fB-right=-2\fP. |
| 187 |
|
| 188 |
.TP |
| 189 |
\fB-pad\fP |
| 190 |
If the rectangle you specify is not entirely within the input |
| 191 |
image, \fBpamcut\fP fails unless you also specify \fB-pad\fP. In |
| 192 |
that case, it pads the output with black up to the edges you specify. |
| 193 |
You can use this option if you need to have an image of certain |
| 194 |
dimensions and have an image of arbitrary dimensions. |
| 195 |
.sp |
| 196 |
\fBpnmpad\fP also adds borders to an image, but you specify their |
| 197 |
width directly. |
| 198 |
.sp |
| 199 |
\fBpamcomp\fP does a more general form of this padding. Create a |
| 200 |
background image of the frame dimensions and overlay the subject image |
| 201 |
on it. You can use options to have the subject image in the center of |
| 202 |
the frame or against any edge and make the padding any color (the padding |
| 203 |
color is the color of the background image). |
| 204 |
|
| 205 |
.TP |
| 206 |
\fB-reportonly\fP |
| 207 |
This causes \fBpamcut\fP to write to Standard Output a description of the |
| 208 |
cutting it would have done instead of producing an output image. See |
| 209 |
|
| 210 |
.UR #reportonly |
| 211 |
below |
| 212 |
.UE |
| 213 |
\& for a description of this output and ways |
| 214 |
to use it. |
| 215 |
.sp |
| 216 |
That description is one line of text, containing 8 decimal numbers of |
| 217 |
pixels, separated by spaces: |
| 218 |
|
| 219 |
|
| 220 |
.IP \(bu |
| 221 |
column number of left cut |
| 222 |
.IP \(bu |
| 223 |
column number of right cut |
| 224 |
.IP \(bu |
| 225 |
row number of top cut |
| 226 |
.IP \(bu |
| 227 |
row number of bottom cut |
| 228 |
.IP \(bu |
| 229 |
width of input image |
| 230 |
.IP \(bu |
| 231 |
height of input image |
| 232 |
.IP \(bu |
| 233 |
width of output image |
| 234 |
.IP \(bu |
| 235 |
height of output image |
| 236 |
|
| 237 |
.sp |
| 238 |
The column number of the left cut is the column number in the input image |
| 239 |
of the leftmost column of the output image. for the right cut, it is for |
| 240 |
the rightmost column of the output. Top and bottom are analogous. |
| 241 |
.sp |
| 242 |
\fIThe column and row numbers can be negative\fP if you |
| 243 |
specified \fB-pad\fP and \fBpamcut\fP would have added padding. Likewise, |
| 244 |
they can be beyond the right and bottom edge of the input image. |
| 245 |
.sp |
| 246 |
Example: |
| 247 |
.nf |
| 248 |
|
| 249 |
10 109 -1 98 150 80 100 100 |
| 250 |
|
| 251 |
|
| 252 |
.fi |
| 253 |
.sp |
| 254 |
This option was new in Netpbm 11.06 (March 2024). |
| 255 |
|
| 256 |
.TP |
| 257 |
\fB-verbose\fP |
| 258 |
Print information about the processing to Standard Error. |
| 259 |
|
| 260 |
|
| 261 |
.UN seealso |
| 262 |
.SH SEE ALSO |
| 263 |
.BR "pnmcrop" (1)\c |
| 264 |
\&, |
| 265 |
.BR "pamdice" (1)\c |
| 266 |
\&, |
| 267 |
.BR "pamcomp" (1)\c |
| 268 |
\&, |
| 269 |
.BR "pnmpad" (1)\c |
| 270 |
\&, |
| 271 |
.BR "pamcat" (1)\c |
| 272 |
\&, |
| 273 |
.BR "pgmslice" (1)\c |
| 274 |
\&, |
| 275 |
.BR "pnm" (1)\c |
| 276 |
\& |
| 277 |
|
| 278 |
.UN history |
| 279 |
.SH HISTORY |
| 280 |
.PP |
| 281 |
\fBpamcut\fP was derived from \fBpnmcut\fP in Netpbm 9.20 (May 2001). |
| 282 |
It was the first Netpbm program adapted to the new PAM format and programming |
| 283 |
library. |
| 284 |
.PP |
| 285 |
The predecessor \fBpnmcut\fP was one of the oldest tools in the Netpbm |
| 286 |
package. |
| 287 |
|
| 288 |
|
| 289 |
.UN author |
| 290 |
.SH AUTHOR |
| 291 |
|
| 292 |
Copyright (C) 1989 by Jef Poskanzer. |
| 293 |
.SH DOCUMENT SOURCE |
| 294 |
This manual page was generated by the Netpbm tool 'makeman' from HTML |
| 295 |
source. The master documentation is at |
| 296 |
.IP |
| 297 |
.B http://netpbm.sourceforge.net/doc/pamcut.html |
| 298 |
.PP |