Debian Codegraph @

userguide/pamtojpeg2k.html

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