| 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 |