Debian Codegraph @

upstream/debian-trixie/man1/pamundice.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 "Pamundice User Manual" 1 "08 February 2025" "netpbm documentation"
7
8 .SH NAME
9 pamundice - combine grid of images (tiles) into one
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 $ pamundice myimage_part_%2a -across=13 -hoverlap=9
20 \fP
21
22 .fi
23 .PP
24 See
25 .UR pamdice.html#example
26 pamdice
27 .UE
28 \& for more examples.
29
30 .UN synopsis
31 .SH SYNOPSIS
32
33 \fBpamundice\fP
34
35 {
36 [\fB-across=\fP\fIn\fP]
37
38 [\fB-down=\fP\fIn\fP]
39 ,
40 \fB-indexfile=pamfilename\fP
41 }
42
43
44 [\fB-hoverlap=\fP\fIpixels\fP]
45
46 [\fB-voverlap=\fP\fIpixels\fP]
47
48 [\fB-verbose\fP]
49
50 {\fIinput_filename_pattern\fP,
51 \fB-listfile=\fP\fItextfilename\fP}
52 .PP
53 You can use the minimum unique abbreviation of the options. You can use
54 two hyphens instead of one. You can separate an option name from its value
55 with white space instead of an equals sign.
56
57 .UN description
58 .SH DESCRIPTION
59 .PP
60 This program is part of
61 .BR "Netpbm" (1)\c
62 \&.
63 .PP
64 \fBpamundice\fP reads a bunch of Netpbm images as input and combines them
65 as a grid of tiles into a single output image of the same kind on Standard
66 Output.
67 .PP
68 You can optionally make the pieces overlap.
69 .PP
70 The images can either be in files whose names indicate where they go in the
71 output (e.g. 'myimage_part_03_04' could be the image for Row 3,
72 Column 4 - see the \fIinput_filename_pattern\fP argument) or listed in a
73 file, with a \fB-listfile\fP option.
74 .PP
75 The input images must all have the same format (PAM, PPM, etc.)
76 and maxval and for PAM must have the same depth and tuple type.
77 All the images in a rank (horizontal row of tiles) must have the
78 same height. All the images in a file (vertical column of tiles)
79 must have the same width. But it is not required that every rank
80 have the same height or every file have the same width.
81 .PP
82 \fBpamdice\fP is the inverse of \fBpamundice\fP. You can use
83 \fBpamundice\fP to reassemble an image sliced up by \fBpamdice\fP.
84 You can use \fBpamdice\fP to recreate the tiles of an image created
85 by \fBpamundice\fP, but to do this, the original ranks must all have
86 been the same height except for the bottom one and the original files
87 must all have been the same width except the right one.
88 .PP
89 One use for this is to process an image in pieces when the whole image is
90 too large to process. For example, you might have an image so large that an
91 image editor can't read it all into memory or processes it very slowly. You
92 can split it into smaller pieces with \fBpamdice\fP, edit one at a time, and
93 then reassemble them with \fBpamundice\fP.
94 .PP
95 Of course, you can also use \fBpamundice\fP to compose various kinds of
96 checkerboard images, for example, you could write a program to render a
97 chessboard by computing an image of each square, then using \fBpamundice\fP
98 to assemble them into a board.
99
100 .PP
101 An alternative to join images in a single direction (i.e. a single rank or
102 a single file) is \fBpamcat\fP. \fBpamcat\fP provides alternative ways to
103 identify the input images: you can supply them serially on Standard Input or
104 list them by name as command line arguments.
105 .PP
106 To join piecewise photographs, use \fBpnmstitch\fP instead of
107 \fBpamundice\fP, because it figures out where the pieces overlap, even if
108 they don't overlap exactly vertically or horizontally.
109 .PP
110 To create an image of the same tile repeated in a grid, that's
111 \fBpnmtile\fP.
112 .PP
113 \fBpnmindex\fP does a similar thing to \fBpamundice\fP: it combines a
114 bunch of small images in a grid into a big one. But its purpose is to produce
115 an index image of the input images. So it leaves space between them and has
116 labels for them, for example.
117
118
119 .UN arguments
120 .SH ARGUMENTS
121 .PP
122 Unless you use a \fB-listfile\fP option, there is one non-option
123 argument, and it is mandatory: \fIinput_filename_pattern\fP. This
124 tells \fBpamundice\fP what files contain the input tiles.
125 .PP
126 \fBpamundice\fP reads the input images from files which are named
127 with a pattern that indicates their positions in the combined image.
128 For example, \fBtile_00_05.ppm\fP could be the 6th tile over in the
129 1st rank, while \fBtile_04_01\fP is the 2nd tile over in the 5th rank.
130 .PP
131 (But see \fB-indexfile\fP, which can cause the tiles to be rearranged so
132 that the file whose name indicates it is the 6th tile over in the 1st rank
133 could actually be placed by \fBpamundice\fP in any arbitrary position in its
134 output).
135
136 .PP
137 You cannot supply any of the data on Standard Input, and the files
138 must be the kind that \fBpamundice\fP can close and reopen and read
139 the same image a second time (e.g. a regular file is fine; a named
140 pipe is probably not).
141 .PP
142 \fIinput_filename_pattern\fP is a printf-style pattern. (See the
143 standard C library \fBprintf\fP subroutine). For the example above,
144 it would be \fBtile_%2d_%2a.ppm\fP. The only possible conversion
145 specifiers are:
146
147
148
149 .TP
150 \fBd\fP
151 "down": The rank (row) number, starting with 0.
152
153 .TP
154 \fBa\fP
155 "across": The file (column) number, starting with 0.
156
157 .TP
158 \fB%\fP
159 The per cent character (%).
160
161
162 .PP
163 The number between the % and the conversion specifier is the
164 precision and is required. It says how many characters of the file
165 name are described by that conversion. The rank or file number is
166 filled with leading zeroes as necessary.
167 .PP
168 So the example \fBtile_%2d_%2a.ppm\fP means to get the name of
169 the file that contains the tile at Rank 0, File 5, you:
170
171
172
173 .IP \(bu
174 replace the "%2d" with the rank number, as a 2 digit
175 decimal number: "00"
176
177 .IP \(bu
178 Replace the "%2a" with the file number, as a 2 digit
179 decimal number: "05"
180
181 .PP
182 Note that this pattern describes file names that \fBpamdice\fP produces,
183 except that the precision may be more or less. (See the \fB-numberwidth\fP
184 option of \fBpamdice\fP).
185
186
187 .UN options
188 .SH OPTIONS
189 .PP
190 In addition to the options common to all programs based on libnetpbm
191 (most notably \fB-quiet\fP, see
192 .UR index.html#commonoptions
193 Common Options
194 .UE
195 \&), \fBpamundice\fP recognizes the following
196 command line options:
197
198
199 .TP
200 \fB-across=\fP\fIN\fP
201 This is the number of tiles across in the grid, i.e. the number of
202 tiles in each rank, or the number of files.
203 .sp
204 You cannot specify this together with \fB-indexfile\fP.
205 .sp
206 Default is 1.
207
208 .TP
209 \fB-down=\fP\fIN\fP
210 This is the number of tiles up and down in the grid, i.e. the
211 number of tiles in each file, or the number of ranks.
212 .sp
213 You cannot specify this together with \fB-indexfile\fP.
214 .sp
215 Default is 1.
216
217 .TP
218 \fB-hoverlap=\fP\fIpixels\fP
219 This is the amount in pixels to overlap the tiles horizontally.
220 \fBpamundice\fP clips this much off the right edge of every tile
221 before joining it to the adjacent image to the right. The tiles along
222 the right edge remain whole.
223 .sp
224 There must not be any input image narrower than this.
225 .sp
226 Note that this undoes the effect of the same \fB-hoverlap\fP
227 option of \fBpamdice\fP.
228 .sp
229 Default is zero -- no overlap.
230
231 .TP
232 \fB-voverlap=\fP\fIpixels\fP
233 This is analogous to \fB-hoverlap\fP, but \fBpamundice\fP
234 clips the bottom edge of each image before joining it to the one below.
235
236 .TP
237 \fB-listfile=\fP\fItextfilename\fP
238 This option names a file that contains the names of all the input files.
239 This is an alternative to specifying a file name pattern as an argument.
240 .sp
241 The named file contains file names, one per line. Each file contains the
242 image for one tile, in row-major order, top to bottom, left to right. So
243 the first file is the upper left tile, the second is the one to right of
244 that, etc. The number of lines in the file must be equal to the number of
245 tiles in the output, the product of the \fB-across\fP and \fB-down\fP
246 values.
247 .sp
248 The file names have no meaning to \fBpamundice\fP. You can list the same
249 file multiple times to have identical tiles in the output.
250 .sp
251 If you create the tile files with \fBpamdice\fP, you can use the
252 \fB-listfile\fP option of \fBpamdice\fP to produce a suitable list file
253 for reassembling the tiles into the same positions they had in the original
254 large image.
255 .sp
256 You cannot specify this together with \fB-indexfile\fP.
257 .sp
258 This option was new in Netpbm 10.90 (March 2020).
259
260 .TP
261 \fB-indexfile=\fP\fIpamfilename\fP
262 This option names a file that contains a PAM image that tells which
263 tile files to put where in the assembled output. See the
264 \fBpamfile\fP \fB-indexfile\fP option for details on its format.
265 .sp
266 A typical way to generate an index image to use with \fBpamundice\fP is to
267 use the \fB-indexfile\fP option of \fBpamdice\fP, and then possibly
268 manipulate the resulting index image with other Netpbm tools.
269 .sp
270 While the sample values in the index image are defined to be rank and file
271 positions in some original large image, and so are documented in those terms,
272 in practice, \fBpamundice\fP doesn't assign any meaning to the numbers
273 -- they are just substitutions for two variables in the input file name
274 pattern (given as a program argument).
275 .sp
276 The maxval of the index image is irrelevant, except that no sample in the
277 index image can be greater than it.
278 .sp
279 The depth of the index file must be at least two (rank and file), but the
280 program ignores any additional planes.
281 .sp
282 The program ignores the tuple type.
283 .sp
284 If you don't specify this option, the position of a tile in the ouput
285 is given directly by the rank and file portions of the tile file name, or if
286 you specify \fB-listfile\fP, by order in which the tile files are listed in
287 the list file.
288 .sp
289 You cannot specify this together with \fB-listfile\fP, \fB-down\fP, or
290 \fB-across\fP.
291 .sp
292 This option was new in Netpbm 11.10 (March 2025).
293
294 .TP
295 \fB-verbose\fP
296 This says to print information about the processing to Standard Error.
297
298
299
300
301 .UN usage
302 .SH Usage
303 .PP
304 Here is an example of using a list file:
305
306 .nf
307 \f(CW
308 Example usage of -listfile:
309
310 pamdice -width=100 -height=100 -outstem=img_part -listfile=listfile \e
311 img.ppm
312 pamundice -listfile=listfile -across=6 -down=4 > img_copy.ppm
313 \fP
314
315 .fi
316 .PP
317 Note that in the above example, you have to know somehow that you got
318 6 files and 4 ranks from \fBpamdice\fP and then specify the correct
319 \fB-across\fP and \fB-down\fP options on \fBpamundice\fP. A slight error
320 ruins the process. A better way is to use \fB-indexfile\fP:
321
322 .nf
323 \f(CW
324 pamdice -width=100 -height=100 -outstem=img_part \e
325 -numberwidth=3 -indexfile=index.pam img.pam
326 pamundice -indexfile=index.pam img_part_%3d_%3a.pam > img_copy.pam
327 \fP
328
329 .fi
330
331
332 .PP
333 Here is an example of flipping a large image. \fBpamflip\fP often
334 requires the entire image to be in real memory at once, which can be
335 impossible or impractical with a very large image. This method does it in
336 smaller pieces so as to require less memory:
337
338 .nf
339 \f(CW
340 Example of -indexfile with pamflip operation:
341
342 pamdice -width=2500 -height=2500 -outstem=tile \e
343 -numberwidth=3 -indexfile=index.pam hugeImage.ppm
344
345 # flip every tile
346 for tile in tile_???_???.ppm
347 do
348 pamflip -r180 $tile > ${tile%.ppm}.flipped.ppm
349 done
350
351 # flip indexfile - Simply apply the same flip operation
352 pamflip -r180 index.pam > index_flipped.pam
353
354 pamundice -indexfile=index_flipped.pam tile_%3d_%3a.flipped.ppm \e
355 > hugeImage_flipped.ppm
356 \fP
357
358 .fi
359
360
361
362 .UN history
363 .SH HISTORY
364 .PP
365 \fBpamundice\fP was new in Netpbm 10.39 (June 2007). Before that,
366 \fBpamcat\fP is the best substitute.
367
368
369 .UN seealso
370 .SH SEE ALSO
371 .BR "pamdice" (1)\c
372 \&,
373 .BR "pamcat" (1)\c
374 \&,
375 .BR "pnmindex" (1)\c
376 \&,
377 .BR "pnmtile" (1)\c
378 \&,
379 .BR "pnmtile" (1)\c
380 \&,
381 .BR "pnm" (1)\c
382 \&,
383 .BR "pam" (1)\c
384 \&
385 .SH DOCUMENT SOURCE
386 This manual page was generated by the Netpbm tool 'makeman' from HTML
387 source. The master documentation is at
388 .IP
389 .B http://netpbm.sourceforge.net/doc/pamundice.html
390 .PP