Debian Codegraph @

upstream/debian-unstable/man1/pamdice.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 "Pamdice User Manual" 1 "27 May 2025" "netpbm documentation"
7
8 .SH NAME
9 pamdice - slice a Netpbm image into many horizontally and/or vertically
10
11 .UN example
12 .SH EXAMPLE
13 .PP
14 In these examples, \fBmyimage.ppm\fP is an image that is 10,000 pixels wide
15 and 8,000 pixels high.
16
17 .nf
18 \f(CW
19 $ pamdice myimage.ppm -width=1000 -height=1000 -outstem=myimage_part
20 $ pamundice myimage_part_%1d_%1a.ppm -across=10 -down=8 >myimage.ppm
21
22 $ pamdice myimage.ppm -height=1000 -voverlap=90 -outstem=myimage_part
23
24 $ pamdice myimage.ppm -width=1000 -height=1000 -outstem=myimage_part \e
25 -listfile=tiles.txt
26 $ pamundice -across=10 -down=8 -listfile=tiles.txt >myimage.ppm
27
28 $ pamdice myimage.ppm -width=1000 -height=1000 -outstem=myimage_part \e
29 -indexfile=tiles.pam
30 $ pamundice myimage_part_%1d_%1a.ppm -indexfile=tiles.pam >myimage.ppm
31 \fP
32
33 .fi
34
35
36 .UN synopsis
37 .SH SYNOPSIS
38
39 \fBpamdice\fP
40
41 \fB-outstem=\fP\fIfilenamestem\fP
42
43 [\fB-outsuffix=\fP\fIfilenamesuffix\fP]
44
45 [\fB-width=\fP\fIwidth\fP]
46
47 [\fB-height=\fP\fIheight\fP]
48
49 [\fB-hoverlap=\fP\fIhoverlap\fP]
50
51 [\fB-voverlap=\fP\fIvoverlap\fP]
52
53 [\fB-numberwidth=\fP\fIN\fP]
54
55 [\fB-listfile=\fP\fItextfilename\fP]
56
57 [\fB-indexfile=\fP\fIpamfilename\fP
58
59 [\fB-dry-run\fP]
60
61 [\fB-verbose\fP]
62
63 [\fIfilename\fP]
64 .PP
65 You can use the minimum unique abbreviation of the options. You can use
66 two hyphens instead of one. You can separate an option name from its value
67 with white space instead of an equals sign.
68
69 .UN description
70 .SH DESCRIPTION
71 .PP
72 This program is part of
73 .BR "Netpbm" (1)\c
74 \&.
75 .PP
76 \fBpamdice\fP reads a PAM, PBM, PGM, or PPM image as input and
77 splits it horizontally and/or vertically into equal size pieces and
78 writes them into separate files as the same kind of image. You can
79 optionally make the pieces overlap.
80 .PP
81 See the \fB-outstem\fP option for information on naming of the output
82 files.
83 .PP
84 The \fB-width\fP and \fB-height\fP options determine the size of the
85 output pieces.
86 .PP
87 \fBpamundice\fP can rejoin the images. For finer control, you can
88 also use \fBpamcat\fP.
89 .PP
90 One use for this is to make pieces that take less computer resources
91 than the whole image to process. For example, you might have an image
92 so large that an image editor can't read it all into memory or processes
93 it very slowly. With \fBpamdice\fP, you can split it into smaller pieces,
94 edit one at a time, and then reassemble them.
95 .PP
96 Another use for this is to print a large image in small printer-sized
97 pieces that you can glue together. \fBppmglobe\fP does a similar thing;
98 it lets you glue the pieces together into a sphere.
99 .PP
100 If you want to cut pieces from an image individually, not in a regular
101 grid, use \fBpamcut\fP.
102
103
104 .UN options
105 .SH OPTIONS
106 .PP
107 In addition to the options common to all programs based on libnetpbm
108 (most notably \fB-quiet\fP, see
109 .UR index.html#commonoptions
110 Common Options
111 .UE
112 \&), \fBpamdice\fP recognizes the following
113 command line options:
114
115
116 .TP
117 \fB-outstem=\fP\fIfilenamestem\fP
118 This option determines the names of the output files. Each output
119 file is named
120 \fIfilenamestem\fP\fB_\fP\fIy\fP\fB_\fP\fIx\fP\fB.\fP\fItype\fP,
121 where \fIfilenamestem\fP is the value of the \fB-outstem\fP option,
122 \fIx\fP and \fIy\fP are the horizontal and vertical locations,
123 respectively, in the input image of the output image, zero being the
124 leftmost and top, and \fItype\fP is \fB.pbm\fP, \fB.pgm\fP,
125 \fB.ppm\fP, or \fB.pam\fP, depending on the type of image.
126 .sp
127 \fIx\fP and \fIy\fP are filled with leading zeroes so are the same width
128 in every file. Use \fB-numberwidth\fP to specify that width; otherwise, it
129 defaults to the minimum width that works for all the files. For example, if
130 you have 25 slices across and no \fB-numberwidth\fP, \fIx\fP is 2 digits for
131 all the output files. The leftmost slice is numbered '00'; the next
132 one is '01', etc. With \fB-numberwidth=3\fP, \fIx\fP is
133 \&'000', '001', etc.
134 .sp
135 You can override the file type suffix with an \fB-outsuffix\fP option.
136
137 .TP
138 \fB-outsuffix=\fP\fIfilenamesuffix\fP
139 This specifies the suffix for the output file names. \fBpamdice\fP does
140 not add a period.
141 .sp
142 Example: \f(CW-outsuffix=.pnm\fP
143 .sp
144 The default is an appropriate suffix for the image type,
145 e.g. '.ppm'.
146 .sp
147 This option was new in Netpbm 11.11 (June 2025).
148
149 .TP
150 \fB-numberwidth=\fP\fIN\fP
151 This option determines the width of the numbers in the output file
152 names. See the \fB-outstem\fP option for details.
153 .sp
154 It is not valid to specify a width less than is necessary to represent all
155 the slices.
156 .sp
157 This option was new in Netpbm 11.10 (March 2025).
158
159 .TP
160 \fB-width=\fP\fIwidth\fP
161 This gives the width in pixels of the output images. The rightmost
162 pieces are smaller than this if the input image is not a multiple of
163 \fIwidth\fP pixels wide.
164 .sp
165 If you don't specify this, the default is the entire width of the
166 image; i.e. \fBpamdice\fP does not split vertically.
167
168 .TP
169 \fB-height=\fP\fIheight\fP
170 This gives the height in pixels of the output images. The bottom
171 pieces are smaller than this if the input image is not a multiple of
172 \fIheight\fP pixels high.
173 .sp
174 If you don't specify this, the default is the entire height of the
175 image; i.e. \fBpamdice\fP does not split horizontally.
176
177
178
179 .TP
180 \fB-hoverlap=\fP\fIhoverlap\fP
181 This gives the horizontal overlap in pixels between output images. Each
182 image in a row will overlap the previous one by \fIhoverlap\fP pixels. By
183 default, there is no overlap.
184 .sp
185 This option was new in Netpbm 10.23 (July 2004).
186
187 .TP
188 \fB-voverlap=\fP\fIvoverlap\fP
189 This gives the vertical overlap in pixels between output images. Each row
190 of images will overlap the previous row by \fIvoverlap\fP pixels. By
191 default, there is no overlap.
192 .sp
193 This option was new in Netpbm 10.23 (July 2004).
194
195
196 .TP
197 \fB-listfile=\fP\fItextfilename\fP
198 This causes the program to generate a file listing the names of all the
199 tile files it creates. It is in row-major order. For example,
200
201 \f(CW
202 $ pamdice -width=100 -height=100 -outstem=myimage_part -listfile=mylist.txt \e
203 -numberwidth=3 myimage.ppm
204 \fP
205
206 on a 200x200 image generates the file \fBmylist.txt\fP containing this:
207
208 .nf
209 \f(CW
210 myimage_part_000_000.ppm
211 myimage_part_000_001.ppm
212 myimage_part_001_000.ppm
213 myimage_part_001_001.ppm
214 \fP
215
216 .fi
217 .sp
218 You can use this list file with \fBpamundice -listfile\fP in lieu of an
219 input file name pattern argument, which may save you the trouble of
220 coordinating the patterns used in your invocations of \fBpamdice\fP and
221 \fBpamundice\fP.
222 .sp
223 This option was new in Netpbm 11.10 (March 2025).
224
225 .TP
226 \fB-indexfile=\fP\fIpamfilename\fP
227 This causes the program to generate a file containing a PAM image that
228 contains rank and file numbers for the tiles. It is simply an image whose
229 width and height are the number of horizontal and vertical slices,
230 respectively, in which each tuple is just the row and column number of that
231 tuple. For example, if \fBpamdice\fP produces 3 slices across and 2 down,
232 the image looks like this:
233
234 .nf
235 (0,0) (0,1) (0,2)
236 (1,0) (1,1) (1,2)
237
238 .fi
239 .sp
240 The depth of the image is 2, the tuple type is 'grid_coord' (a
241 tuple type invented for use with \fBpamdice\fP and \fBpamundice\fP), and the
242 maxval is 255 unless the height or width is greater than 256, in which case it
243 is 65535.
244 .sp
245 This image can be useful as input to \fBpamundice\fP, particularly after
246 doing transformations on it. The prime example of such usage is in flipping a
247 large image. You can dice the image with \fBpamdice\fP, then flip each of
248 the tiles produced (with \fBpamflip\fP), then flip the index image (again
249 with \fBpamflip\fP), then use \fBpamundice\fP with the flipped tiles and
250 the flipped index image to generate a flipped version of the original large
251 image.
252 .sp
253 This option was new in Netpbm 11.10 (March 2025).
254
255 .TP
256 \fB-dry-run\fP
257 This makes \fBpamdice\fP skip creating the output tile images. It still
258 creates the list file (with \fB-listfile\fP) and the index file (with
259 \fB-indexfile\fP) and checks for most errors.
260 .sp
261 This option was new in Netpbm 11.10 (March 2025).
262
263 .TP
264 \fB-verbose\fP
265 Print information about the processing to Standard Error.
266
267
268
269 .UN history
270 .SH HISTORY
271 .PP
272 \fBpamdice\fP was new in Netpbm 9.25 (March 2002).
273 .PP
274 Before Netpbm 10.29 (August 2005), there was a limit of 100 slices in each
275 direction, and the output file names always used two digits for the slice
276 number.
277
278 .UN seealso
279 .SH SEE ALSO
280 .BR "pamundice" (1)\c
281 \&,
282 .BR "pamcut" (1)\c
283 \&,
284 .BR "pamcat" (1)\c
285 \&,
286 .BR "pgmslice" (1)\c
287 \&,
288 .BR "ppmglobe" (1)\c
289 \&
290 .BR "pamflip" (1)\c
291 \&
292 .BR "pnm" (1)\c
293 \&
294 .BR "pam" (1)\c
295 \&
296 .SH DOCUMENT SOURCE
297 This manual page was generated by the Netpbm tool 'makeman' from HTML
298 source. The master documentation is at
299 .IP
300 .B http://netpbm.sourceforge.net/doc/pamdice.html
301 .PP