Debian Codegraph @

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