Debian Codegraph @

upstream/debian-unstable/man1/pamcut.1

raw
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