| 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> ("intermediate layer rates") 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 |
".1,.3,.5". 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 "rate" 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'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 "rate" 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 >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 >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> |