Debian Codegraph @

upstream/debian-trixie/man1/pamtojpeg2k.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 "Pamtojpeg2k User Manual" 1 "1 November 2022" "netpbm documentation"
7
8 .SH NAME
9 pamtojpeg2k - convert PAM/PNM image to a JPEG-2000 code stream
10
11 .UN synopsis
12 .SH SYNOPSIS
13
14 \fBpamtojpeg2k\fP
15 [\fB-imgareatlx=\fP\fIcolumn\fP]
16 [\fB-imgareatly=\fP\fIrow\fP]
17 [\fB-tilegrdtlx=\fP\fIcolumn\fP]
18 [\fB-tilegrdtly=\fP\fIrow\fP]
19 [\fB-tilewidth=\fP\fIcolumns\fP]
20 [\fB-tileheight=\fP\fIrows\fP]
21 [\fB-prcwidth=\fP\fIcolumns\fP]
22 [\fB-prcheight=\fP\fIrows\fP]
23 [\fB-cblkwidth=\fP\fIcolumns\fP]
24 [\fB-cblkheight=\fP\fIrows\fP]
25 [\fB-mode=\fP{\fBinteger\fP|\fBint\fP|\fBreal\fP}]
26 [\fB-compression=\fP\fIratio\fP]
27 [\fB-size=\fP\fIbytes\fP]
28 [\fB-ilyrrates=\fP[\fIrealnumber\fP[,\fIrealnumber\fP, ...]]
29 [\fB-numrlvls=\fP\fInumber\fP]
30 [\fB-progression=\fP{\fBlrcp\fP|\fBrlcp\fP|\fBrpcl\fP|\fBpcrl\fP|\fBcprl\fP}]
31 [\fB-numgbits=\fP\fInumber\fP]
32 [\fB-nomct\fP]
33 [\fB-sop\fP]
34 [\fB-eph\fP]
35 [\fB-lazy\fP]
36 [\fB-termall\fP]
37 [\fB-segsym\fP]
38 [\fB-vcausal\fP]
39 [\fB-pterm\fP]
40 [\fB-resetprob\fP]
41 [\fB-verbose\fP]
42 [\fB-debuglevel=\fP\fInumber\fP]
43 \fIfilename\fP
44 .PP
45 Minimum unique abbreviation of option is acceptable. You may use double
46 hyphens instead of single hyphen to denote options. You may use white
47 space in place of the equals sign to separate an option name from its value.
48
49
50 .UN description
51 .SH DESCRIPTION
52 .PP
53 This program is part of
54 .BR "Netpbm" (1)\c
55 \&.
56 .PP
57 \fBpamtojpeg2k\fP converts the named PBM, PGM, PPM, or PAM file,
58 or Standard Input if no file is named, to a JPEG-2000 code stream
59 (JPC) file on Standard Output.
60 .PP
61 The JPEG-2000 specification specifies two separate formats: JP2
62 and JPEG-2000 code stream (JPC). JP2 represents a visual image quite
63 specifically, whereas JPC is a more or less arbitrary array of codes.
64 \fBpamtojpeg2k\fP can't produce a JP2, but the JPC image that
65 \fBpamtojpeg2k\fP produces is very similar to a JP2 if the input is a
66 PBM, PGM, or PPM image or equivalent PAM image. One difference is
67 that the RGB intensity values in a JP2 are SRGB values, while
68 \fBpamtojpeg2k\fP produces ITU-R Recommendation BT.709 values. Those
69 are very similar, but not identical. Another difference is that a JP2
70 can contain extra information about an image that JPC cannot.
71 .PP
72 When the input is a PAM image other than a PBM, PGM, or PPM equivalent,
73 the JPC raster produced contains whatever the PAM raster does. It can have
74 any number of planes with any meanings; the planes are in the same order in
75 the JPC output as in the PAM input.
76 .PP
77 A JPC image has a "precision," which is the number of bits used for
78 each code (in Netpbm lingo, "sample"). Actually, it has a separate
79 precision for each component. \fBpamtojpeg2k\fP uses for the
80 precision of every component the least number of bits that can
81 represent the maxval of the input image. A JPC image does not have an
82 independent concept of maxval; the maxval of a JPC sample is the
83 maximum value that the number of bits specified by the precision can
84 represent in pure binary code. E.g. if the precision is 4, the maxval
85 is 15. \fBpamtojpeg2k\fP does of course scale the sample values from
86 the input maxval to the output maxval. Example: The input maxval is
87 99. This means JPC precision is 7 bits and the JPC maxval is 127. A
88 sample value of 33 in the input becomes a sample value of 43 in the
89 output.
90 .PP
91 \fBpamtojpeg2k\fP generates the JPC output with the
92 .UR http://www.ece.uvic.ca/~mdadams/jasper/
93 Jasper JPEG-2000 library
94 .UE
95 \&. See documentation of the library for details on what
96 \fBpamtojpeg2k\fP produces. Note that the Jasper library contains
97 facilities for reading PNM images, but \fBpamtojpeg2k\fP does not use
98 those. It uses the Netpbm library instead. Note that the makers of
99 the Jasper library write it "JasPer," but Netpbm documentation follows
100 standard American English typography rules, which don't allow that
101 kind of capitalization.
102 .PP
103 Use \fBjpeg2ktopam\fP to convert in the other direction.
104 .PP
105 The program \fBjasper\fP, which is packaged with the Jasper
106 JPEG-2000 library, also converts between JPEG-2000 and PNM formats.
107 Because it's packaged with the library, it may exploit it better,
108 especially recently added features. However, since it does not use the
109 Netpbm library to read and write the Netpbm formats, it doesn't do as
110 good a job on that side.
111 .PP
112 Another format with goals similar to those of JPEG-2000 but that allows for
113 faster encoding and decoding, is
114 .UR https://jpeg.org/jpegls
115 JPEG-LS
116 .UE
117 \&.
118 .UR http://github.com/team-charls/charls
119 CharLS
120 .UE
121 \& is a package of
122 software for using JPEG-LS.
123
124
125 .UN options
126 .SH OPTIONS
127 .PP
128 In addition to the options common to all programs based on libnetpbm
129 (most notably \fB-quiet\fP, see
130 .UR index.html#commonoptions
131 Common Options
132 .UE
133 \&), \fBpamtojpeg2k\fP recognizes the following
134 command line options:
135
136 .UN jasperopts
137 .SS Jasper Library Options
138 .PP
139 These options are identical in name and function to options that the
140 Jasper library JPC encoder subroutine takes. See
141 .UR http://www.ece.uvic.ca/~mdadams/jasper/
142 Jasper documentation
143 .UE
144 \&
145 for details.
146
147
148 .TP
149 \fB-imgareatlx=\fP\fIcolumn\fP
150 .TP
151 \fB-imgareatly=\fP\fIrow\fP
152 .TP
153 \fB-tilegrdtlx=\fP\fIcolumn\fP
154 .TP
155 \fB-tilegrdtly=\fP\fIrow\fP
156 .TP
157 \fB-tilewidth=\fP\fIcolumns\fP
158 .TP
159 \fB-tileheight=\fP\fIrows\fP
160 .TP
161 \fB-prcwidth=\fP\fIcolumns\fP
162 .TP
163 \fB-prcheight=\fP\fIrows\fP
164 .TP
165 \fB-cblkwidth=\fP\fIcolumns\fP
166 .TP
167 \fB-cblkheight=\fP\fIrows\fP
168 .TP
169 \fB-mode=\fP{\fBinteger\fP|\fBint\fP|\fBreal\fP}
170 .TP
171 \fB-ilyrrates=\fP[\fIrealnumber\fP[,\fIrealnumber\fP, ...]]
172 .TP
173 \fB-numrlvls=\fP\fInumber\fP
174 .TP
175 \fB-progression=\fP{\fBlrcp\fP|\fBrlcp\fP|\fBrpcl\fP|\fBpcrl\fP|\fBcprl\fP}
176 .TP
177 \fB-numgbits=\fP\fInumber\fP
178 .TP
179 \fB-nomct\fP
180 .TP
181 \fB-sop\fP
182 .TP
183 \fB-eph\fP
184 .TP
185 \fB-lazy\fP
186 .TP
187 \fB-termall\fP
188 .TP
189 \fB-segsym\fP
190 .TP
191 \fB-vcausal\fP
192 .TP
193 \fB-pterm\fP
194 .TP
195 \fB-resetprob\fP
196
197 .PP
198 \fB-ilyrrates\fP ('intermediate layer rates') lets you control
199 the compression at each layer. The compressed image is arranged in layers,
200 so if you transmit it somewhere serially, enough information to make a low
201 quality image arrives soon, then later more information arrives to improve
202 the quality of the image, and so on until the entire image arrives. The
203 value of this option is a list of ascending fractions, such as
204 '.1,.3,.5'. Each fraction says the size of the layers up to and
205 including that layer should add up to that fraction of the size of the input
206 image. If the size of the entire image is limited by \fB-compression\fP
207 or \fB-size\fP, none of these numbers may exceed that limit.
208
209 .UN otheropts
210 .SS Other Options
211
212
213
214 .TP
215 \fB-compression=\fP\fIratio\fP
216 \fIratio\fP is a floating point number that specifies the compression
217 ratio. \fBpamtojpeg2k\fP will adjust quality as necessary to ensure that
218 you get this compression ratio. E.g. 4 means the output will be about
219 one fourth the size in bytes of the input file.
220 .sp
221 The ratio concerns just the raster part of the image, with the denominator
222 being what the raster would take if it were encoded the most naive way
223 possible (e.g. 3 bytes per pixel in 8-bit-per-sample RGB). It does,
224 however, include metadata that is part of the compressed raster. Because
225 of that, it may not be possible to give you your requested compression ratio
226 at any quality. If it isn't, \fBpamtojpeg2k\fP fails with a message
227 saying so.
228 .sp
229 If you don't specify this option, \fBpamtojpeg2k\fP gives you the best
230 compression it can without losing any quality. Because of the metadata issue
231 described above, this may mean, for a small image, the image actually expands.
232 .sp
233 This option controls the 'rate' option of the Jasper library.
234 Note that though the Jasper library takes a compression factor, this option
235 specifies a compression ratio. The compression factor is the multiplicative
236 inverse of (1 divided by) the compression ratio.
237 .sp
238 You may not specify this with \fB-size\fP.
239 .sp
240 Before Netpbm 10.61 (December 2012), the default was a compression ratio
241 of 1, and if \fBpamtojpeg2k\fP could not make the output that small, it just
242 made it as small as it could, with zero quality. You know this is happening
243 when you see the warning message, "empty layer generated."
244
245 .TP
246 \fB-size=\fP\fIbytes\fP
247 This option specifies the maximum size in bytes you want the output image
248 to have. This size is all-in, including headers and trailers and other
249 metadata. \fBpamtojpeg2k\fP will omit as much information as necessary to
250 get under this limit.
251 .sp
252 It is possible to specify a value impossibly small, for example a value
253 that doesn't even leave room for the image header. If you do this, the
254 program fails with an explanatory message.
255 .sp
256 This option controls the 'rate' option of the Jasper library.
257 .sp
258 You may not specify this with \fB-compression\fP.
259 .sp
260 This option was new in Netpbm 11.1 (December 2022).
261
262
263 .TP
264 \fB-verbose\fP
265 This option causes \fBpamtojpeg2k\fP to issue informational messages about
266 the conversion process.
267
268 .TP
269 \fB-debuglevel\fP=\fInumber\fP
270 This option controls debug messages from the Jasper library.
271 \fBpamtojpeg2k\fP passes \fInumber\fP as the debug level to the Jasper
272 JPC encoder.
273
274
275
276 .UN examples
277 .SH EXAMPLES
278 .PP
279 This example compresses losslessly.
280
281 .nf
282 pamtojpeg2k myimg.ppm >myimg.jpc
283
284 .fi
285
286 \fBjpeg2ktopam\fP will recreate myimg.ppm exactly.
287 .PP
288 This example compresses the file to one tenth its original size, throwing
289 away information as necessary.
290
291 .nf
292 pamtojpeg2k -compression=10 myimg.pgm >myimg.jpc
293
294 .fi
295
296
297 .UN jpeg2000
298 .SH ABOUT JPEG-2000
299 .PP
300 JPEG-2000 is a format that compresses a visual image (or a similar set of
301 data) into a minimal number of bytes for storage or transmission. In that,
302 its goal is similar to JPEG. It has two main differences from JPEG.
303 .PP
304 One difference is that it does a much better job on most images of
305 throwing out information in order to achieve a smaller output. That
306 means when you reconstruct the image from the resulting compressed
307 file, it looks a lot closer to the image you started with
308 JPEG-2000 than with JPEG, for the same compressed file size. Or, looked
309 at another way, with JPEG-2000 you get a much smaller file than with
310 JPEG for the same image quality.
311 .PP
312 The second difference is that with JPEG-2000, you decide how much
313 compression you want and the compressor adjusts the quality to meet your
314 requirement, whereas with JPEG, you decide how much quality you want
315 and the compressor adjusts the size of the output to meet your requirement.
316 I.e. with JPEG-2000, the quality of the result depends on the compressibility
317 of the input, but with JPEG, the \fIsize\fP of the result depends on
318 the compressibility of the input.
319 .PP
320 With JPEG-2000, you can specify lossless compression, thus making it
321 compete with GIF and PNG. With standard JPEG, you always lose something.
322 (There are rumored to be variations of JPEG around that are lossless,
323 though).
324 .PP
325 JPEG is much older than JPEG-2000 and far more popular. JPEG is one of
326 the half dozen most popular graphics formats and virtually all graphics
327 facilities understand it. JPEG-2000 is virtually unknown.
328 .PP
329 There is no compatibility between JPEG and JPEG-2000. Programs that
330 read JPEG do not automatically read JPEG-2000 and vice versa.
331
332
333 .UN seealso
334 .SH SEE ALSO
335 .BR "jpeg2ktopam" (1)\c
336 \&,
337 .BR "pnmtojpeg" (1)\c
338 \&,
339 .BR "ppm" (1)\c
340 \&,
341 .BR "pgm" (1)\c
342 \&,
343 .BR "pbm" (1)\c
344 \&,
345 .BR "pam" (1)\c
346 \&,
347
348 .UN history
349 .SH HISTORY
350 .PP
351 \fBpamtojpeg2k\fP was added to Netpbm in Release 10.12 (November 2002).
352 .SH DOCUMENT SOURCE
353 This manual page was generated by the Netpbm tool 'makeman' from HTML
354 source. The master documentation is at
355 .IP
356 .B http://netpbm.sourceforge.net/doc/pamtojpeg2k.html
357 .PP