Debian Codegraph @

upstream/debian-unstable/man1/pamcat.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 "Pamcat User Manual" 1 "30 November 2022" "netpbm documentation"
7
8 .SH NAME
9
10 pamcat - concatenate Netpbm images
11
12 .UN synopsis
13 .SH SYNOPSIS
14
15 \fBpamcat\fP
16
17 {\fB-leftright\fP | \fB-lr\fP | \fB-topbottom\fP | \fB-tb\fP}
18
19 [\fB-white\fP|\fB-black\fP]
20
21 [\fB-jtop\fP|\fB-jbottom\fP|\fB-jcenter\fP]
22 [\fB-jleft\fP|\fB-jright\fP|\fB-jcenter\fP]
23
24 [\fInetpbmfile\fP ... | \fB-listfile=\fP{\fIfilename\fP|\fB-\fP}]
25 .PP
26 Minimum unique abbreviation of option is acceptable. You may use
27 double hyphens instead of single hyphen to denote options. You may
28 use white space in place of the equals sign to separate an option name
29 from its value.
30
31 .UN description
32 .SH DESCRIPTION
33 .PP
34 This program is part of
35 .BR "Netpbm" (1)\c
36 \&.
37 .PP
38 \fBpamcat\fP reads one or more Netpbm images as input, concatenates them
39 either left to right or top to bottom, and produces a single Netpbm image as
40 output.
41 .PP
42 Options \fB-leftright\fP and \fB-topbottom\fP determine the direction
43 of the concatenation.
44
45 .PP
46 The images do not have to be the same shape: You can concatenate images
47 of different widths top to bottom and of different heights left to right.
48 You can concatenate images of different depths (numbers of planes). You
49 can concatenate a PBM image with a PPM image. Et cetera.
50 .PP
51 The format of the output image is the highest of the formats of the
52 input images, in the order PBM, PGM, PPM, PAM.
53 .PP
54 For PAM output, if all of the input images have the same tuple type
55 (including implied tuple types of PNM images), that is the tuple type of the
56 output. If the inputs differ, but are all visual tuple types, the
57 output's tuple type is the most primitive that can represent all the
58 input. E.g. if inputs are GRAYSCALE and RGB, the output is RGB, and if the
59 inputs are GRAYSCALE_ALPHA and RGB, the output is RGB_ALPHA. If the inputs
60 differ and are not all visual, the output tuple type is a null string.
61 .PP
62 When the output is PAM, its depth is the maximum of the depths of the
63 inputs (including implied depths of PNM images), but at least enough to
64 represent the tuple type specified above. In the case of nonvisual PAM
65 output, input images are padded to this output depth with higher numbered
66 planes of all zeroes.
67 .PP
68 Where the input images are of different widths and you concatenate top
69 to bottom, \fBpamcat\fP generates output as wide as the widest of the
70 inputs and pads the narrower ones. The images can be justified either
71 left, right, or center within this padded field. Use options
72 \fB-jleft\fP, \fB-jright\fP, and \fB-jcenter\fP to control this.
73 .PP
74 Similarly, where the input images are of different heights and you
75 concatenate left to right, \fBpamcat\fP generates output as tall as the
76 tallest of the inputs and pads the shorter ones. The images can be
77 justified either top, bottom, or center within this padded field. Use
78 options
79 \fB-jtop\fP, \fB-jbottom\fP, and \fB-jcenter\fP to control this.
80 .PP
81 You can make the padding black or white or let \fBpamcat\fP determine a
82 likely background color, with possibly different colored padding for each
83 input image. Control this with the \fB-black\fP and \fB-white\fP options.
84 .PP
85 Where the output image contains transparency information (because at least
86 one of the input images does), the padding is opaque. (That is consistent
87 with the result for an output image without transparency information, because
88 such an image is defined to be opaque).
89
90 .PP
91 The arguments are names of input files. Any one of these, but not more
92 than one, may be "-" to indicate Standard Input. If you have no arguments
93 (and do not specify \fB-listfile\fP), that means a single input image from
94 Standard Input (and that is pointless - the output is the same as the input).
95 You can supply the file names in a file instead of as arguments with a
96 \fB-listfile\fP option.
97 .PP
98 Regardless of how you specify the input files, you may not concatenate
99 more files than your system's limit on the number of concurrently
100 open files by one process. 16 is a typical number for that.
101 .PP
102 To assemble a regular grid of images, you can use \fBpamundice\fP.
103 .PP
104 To do the reverse, you might use \fBpamdice\fP to split an image
105 up into smaller ones of equal size or \fBpamcut\fP to chop off part
106 of an image or extract part of an image.
107 .PP
108 \fBpnmtile\fP concatenates a single input image to itself repeatedly.
109
110
111 .UN options
112 .SH OPTIONS
113 .PP
114 In addition to the options common to all programs based on libnetpbm
115 (most notably \fB-quiet\fP, see
116 .UR index.html#commonoptions
117 Common Options
118 .UE
119 \&), \fBpamcat\fP recognizes the following
120 command line options:
121
122 .UN direction
123 .SS Direction
124
125
126 .TP
127 \fB-topbottom\fP, \fB-tb\fP
128 Combine images vertically, top to bottom.
129
130 .TP
131 \fB-leftright\fP, \fB-lr\fP
132 Combine images horizontally, left to right.
133 .sp
134 You must specify the direction by specifying one of the above. You cannot
135 specify both.
136
137
138
139 .UN justification
140 .SS Justification
141
142
143 .TP
144 \fB-jleft\fP
145
146 Left-justify images in a top-bottom concatenation.
147 .sp
148 You cannot specify this with \fB-jright\fP.
149 .sp
150 This option is invalid in a left-right concatenation.
151
152 .TP
153 \fB-jright\fP
154
155 Right-justify images in a top-bottom concatenation.
156 .sp
157 You cannot specify this with \fB-jleft\fP.
158 .sp
159 This option is invalid in a left-right concatenation.
160
161 .TP
162 \fB-jtop\fP
163
164 Top-justify images in a left-right concatenation.
165 .sp
166 You cannot specify this with \fB-jbottom\fP.
167 .sp
168 This option is invalid in a top-bottom concatenation.
169
170 .TP
171 \fB-jbottom\fP
172
173 Bottom-justify images in a left-right concatenation.
174 .sp
175 You cannot specify this with \fB-jtop\fP.
176 .sp
177 This option is invalid in a top-bottom concatenation.
178
179 .TP
180 \fB-jcenter\fP
181
182 Center images (valid for both left-right and top-bottom concatenations).
183 This is the default.
184
185
186 .PP
187 By default, \fBpamcat\fP centers the smaller images. Use
188 \fB-jleft\fP and \fB-jbottom\fP to override this.
189 \fB-topbottom -jleft\fP would stack the images on top of each other, flush
190 with the left edge. \fB-leftright -jbottom\fP would line up the images
191 left to right with their bottom edges aligned as if sitting on a table.
192
193
194 .UN paddingcolor
195 .SS Padding Color
196 These options specify what color to use to fill in the extra space when
197 doing the justification. If neither is specified, \fBpamcat\fP chooses
198 whichever color seems to be right for the images, and the color may be
199 different for each image.
200
201 .TP
202 \fB-white\fP
203 Make all padding white.
204 .sp
205 You may not specify this with \fB-black\fP
206 .TP
207 \fB-black\fP
208 Make all padding black.
209 .sp
210 You may not specify this with \fB-white\fP
211
212
213
214 .UN miscellaneousopt
215 .SS Miscellaneous
216
217
218 .TP
219 \fB-listfile=\fP{\fIfilename\fP|\fB-\fP}
220 This specifies the name of a file that contains the list of input files.
221 Option value \fB-\fP means the list comes from Standard Input.
222 .sp
223 The file contains one file name per newline-delimited line in whatever
224 code the system \fBfopen\fP service expects. You may omit the newline
225 on the last line. Empty lines are ignored. There is no mechanism for
226 including comments in the list (so if you want to have a commented list,
227 preprocess it to remove comments before supplying it to \fBpamcat\fP).
228 .sp
229 You may not specify file names as command line arguments together with
230 \fB-listfile\fP
231 .sp
232 You may not list more files than than your system's limit on the
233 number of concurrently open files by one process. 16 is a typical number
234 for that.
235 .sp
236 This option was new in Netpbm 11.01 (December 2022).
237
238
239
240 .UN seealso
241 .SH SEE ALSO
242 .BR "pamundice" (1)\c
243 \&,
244 .BR "pamdice" (1)\c
245 \&,
246 .BR "pnmtile" (1)\c
247 \&,
248 .BR "pamcut" (1)\c
249 \&,
250 .BR "pnm" (1)\c
251 \&,
252 .BR "pam" (1)\c
253 \&
254
255
256 .UN history
257 .SH HISTORY
258 .PP
259 \fBpamcat\fP was new in Netpbm 11.00 (September 2022); in earlier versions,
260 \fBpnmcat\fP does most of the same thing.
261 .PP
262 Primordial Netpbm/Pbmplus contained concatenation tools, but there were two
263 of them: \fBpbmcatlr\fP for left-right concatenation of PBM images
264 and \fBpbmcattb\fP for top-bottom concatenation. When the PGM and PPM
265 formats were added, these programs were combined and extended to handle all
266 three formats, as \fBpnmcat\fP. All of this work was done by Pbmplus
267 author Jef Poskanzer.
268 .PP
269 In Netpbm 10.44 (September 2008), Akira F Urushibata added special fast
270 processing for raw PBM images, exploiting bitstring processing CPU
271 facilities.
272 .PP
273 \fBpnmcat\fP was one of the most essential programs in Netpbm, but one
274 thing it could not concatenate was PAM images with transparency. So in
275 Netpbm 11.00 (September 2022), Bryan Henderson wrote \fBpamcat\fP to
276 replace it. It reused the raw PBM fast path code from \fBpnmcat\fP almost
277 verbatim.
278 .SH DOCUMENT SOURCE
279 This manual page was generated by the Netpbm tool 'makeman' from HTML
280 source. The master documentation is at
281 .IP
282 .B http://netpbm.sourceforge.net/doc/pamcat.html
283 .PP