man > pamtojpeg2k(1)

Pamtojpeg2k User Manual(1)             General Commands Manual            Pamtojpeg2k User Manual(1)

NAME
       pamtojpeg2k - convert PAM/PNM image to a JPEG-2000 code stream


SYNOPSIS
       pamtojpeg2k  [-imgareatlx=column]  [-imgareatly=row]  [-tilegrdtlx=column]  [-tilegrdtly=row]
       [-tilewidth=columns]   [-tileheight=rows]   [-prcwidth=columns]   [-prcheight=rows]   [-cblk‐
       width=columns]     [-cblkheight=rows]     [-mode={integer|int|real}]     [-compression=ratio]
       [-size=bytes]  [-ilyrrates=[realnumber[,realnumber,  ...]]    [-numrlvls=number]   [-progres‐
       sion={lrcp|rlcp|rpcl|pcrl|cprl}] [-numgbits=number] [-nomct] [-sop] [-eph] [-lazy] [-termall]
       [-segsym] [-vcausal] [-pterm] [-resetprob] [-verbose] [-debuglevel=number] filename

       Minimum  unique  abbreviation of option is acceptable.  You may use double hyphens instead of
       single hyphen to denote options.  You may use white space in place of the equals sign to sep‐
       arate an option name from its value.



DESCRIPTION
       This program is part of Netpbm(1).

       pamtojpeg2k converts the named PBM, PGM, PPM, or PAM file, or Standard Input if  no  file  is
       named, to a JPEG-2000 code stream (JPC) file on Standard Output.

       The  JPEG-2000  specification  specifies  two separate formats: JP2 and JPEG-2000 code stream
       (JPC).  JP2 represents a visual image quite specifically, whereas JPC is a more or less arbi‐
       trary array of codes.  pamtojpeg2k can't produce a JP2, but the JPC  image  that  pamtojpeg2k
       produces  is very similar to a JP2 if the input is a PBM, PGM, or PPM image or equivalent PAM
       image.  One difference is that the RGB intensity values in a JP2 are SRGB values, while  pam‐
       tojpeg2k  produces ITU-R Recommendation BT.709 values.  Those are very similar, but not iden‐
       tical.  Another difference is that a JP2 can contain extra information about  an  image  that
       JPC cannot.

       When  the  input is a PAM image other than a PBM, PGM, or PPM equivalent, the JPC raster pro‐
       duced contains whatever the PAM raster does.  It can have any number of planes with any mean‐
       ings; the planes are in the same order in the JPC output as in the PAM input.

       A JPC image has a "precision," which is the number of bits used  for  each  code  (in  Netpbm
       lingo,  "sample").   Actually,  it  has a separate precision for each component.  pamtojpeg2k
       uses for the precision of every component the least number of bits  that  can  represent  the
       maxval  of  the input image.  A JPC image does not have an independent concept of maxval; the
       maxval of a JPC sample is the maximum value that the number of bits specified by  the  preci‐
       sion  can represent in pure binary code.  E.g. if the precision is 4, the maxval is 15.  pam‐
       tojpeg2k does of course scale the sample values from the input maxval to the  output  maxval.
       Example:  The  input  maxval is 99.  This means JPC precision is 7 bits and the JPC maxval is
       127.  A sample value of 33 in the input becomes a sample value of 43 in the output.

       pamtojpeg2k generates the JPC output with the ]8;;http://www.ece.uvic.ca/~mdadams/jasper/\Jasper JPEG-2000 library]8;;\ .   See  documentation
       of  the  library for details on what pamtojpeg2k produces.  Note that the Jasper library con‐
       tains facilities for reading PNM images, but pamtojpeg2k does not use  those.   It  uses  the
       Netpbm  library  instead.   Note that the makers of the Jasper library write it "JasPer," but
       Netpbm documentation follows standard American English typography rules,  which  don't  allow
       that kind of capitalization.

       Use jpeg2ktopam to convert in the other direction.

       The  program  jasper,  which is packaged with the Jasper JPEG-2000 library, also converts be‐
       tween JPEG-2000 and PNM formats.  Because it's packaged with the library, it may  exploit  it
       better,  especially  recently  added features.  However, since it does not use the Netpbm li‐
       brary to read and write the Netpbm formats, it doesn't do as good a job on that side.

       Another format with goals similar to those of JPEG-2000 but that allows for  faster  encoding
       and decoding, is JPEG-LS.  ]8;;http://charls.codeplex.com\CharLS]8;;\  is a package of software for using JPEG-LS.



OPTIONS
       In  addition  to  the options common to all programs based on libnetpbm (most notably -quiet,
       see ]8;;index.html#commonoptions\ Common Options]8;;\ ), pamtojpeg2k recognizes the following command line options:


   Jasper Library Options
       These options are identical in name and function to options that the Jasper library  JPC  en‐
       coder subroutine takes.  See ]8;;http://www.ece.uvic.ca/~mdadams/jasper/\Jasper documentation]8;;\  for details.



       -imgareatlx=column

       -imgareatly=row

       -tilegrdtlx=column

       -tilegrdtly=row

       -tilewidth=columns

       -tileheight=rows

       -prcwidth=columns

       -prcheight=rows

       -cblkwidth=columns

       -cblkheight=rows

       -mode={integer|int|real}

       -ilyrrates=[realnumber[,realnumber, ...]]

       -numrlvls=number

       -progression={lrcp|rlcp|rpcl|pcrl|cprl}

       -numgbits=number

       -nomct

       -sop

       -eph

       -lazy

       -termall

       -segsym

       -vcausal

       -pterm

       -resetprob


       -ilyrrates ('intermediate layer rates') lets you control
         the compression at each layer.  The compressed image is arranged in layers,
         so if you transmit it somewhere serially, enough information to make a low
         quality image arrives soon, then later more information arrives to improve
         the quality of the image, and so on until the entire image arrives.  The
         value of this option is a list of ascending fractions, such as
         '.1,.3,.5'.  Each fraction says the size of the layers up to and
         including that layer should add up to that fraction of the size of the input
         image.  If the size of the entire image is limited by -compression
         or -size, none of these numbers may exceed that limit.


   Other Options
       -compression=ratio
              ratio  is  a  floating point number that specifies the compression ratio.  pamtojpeg2k
              will adjust quality as necessary to ensure that you get this compression ratio.   E.g.
              4 means the output will be about one fourth the size in bytes of the input file.

              The  ratio concerns just the raster part of the image, with the denominator being what
              the raster would take if it were encoded the most naive way possible (e.g. 3 bytes per
              pixel in 8-bit-per-sample RGB).  It does, however, include metadata that  is  part  of
              the  compressed  raster.  Because of that, it may not be possible to give you your re‐
              quested compression ratio at any quality.  If it isn't, pamtojpeg2k fails with a  mes‐
              sage saying so.

              If  you  don't  specify this option, pamtojpeg2k gives you the best compression it can
              without losing any quality.  Because of the metadata issue described above,  this  may
              mean, for a small image, the image actually expands.

              This  option  controls  the 'rate' option of the Jasper library.  Note that though the
              Jasper library takes a compression factor, this option specifies a compression  ratio.
              The compression factor is the multiplicative inverse of (1 divided by) the compression
              ratio.

              You may not specify this with -size.

              Before  Netpbm 10.61 (December 2012), the default was a compression ratio of 1, and if
              pamtojpeg2k could not make the output that small, it just  made  it  as  small  as  it
              could,  with  zero  quality.  You know this is happening when you see the warning mes‐
              sage, "empty layer generated."


       -size=bytes
              This option specifies the maximum size in bytes you want the  output  image  to  have.
              This  size  is all-in, including headers and trailers and other metadata.  pamtojpeg2k
              will omit as much information as necessary to get under this limit.

              It is possible to specify a value impossibly small, for example a value  that  doesn't
              even  leave  room for the image header.  If you do this, the program fails with an ex‐
              planatory message.

              This option controls the 'rate' option of the Jasper library.

              You may not specify this with -compression.

              This option was new in Netpbm 11.1 (December 2022).



       -verbose
              This option causes pamtojpeg2k to issue informational messages  about  the  conversion
              process.


       -debuglevel=number
              This  option controls debug messages from the Jasper library.  pamtojpeg2k passes num‐
              ber as the debug level to the Jasper JPC encoder.




EXAMPLES
       This example compresses losslessly.

         pamtojpeg2k myimg.ppm >myimg.jpc


       jpeg2ktopam will recreate myimg.ppm exactly.

       This example compresses the file to one tenth its original size, throwing away information as
       necessary.

         pamtojpeg2k -compression=10 myimg.pgm >myimg.jpc




ABOUT JPEG-2000
       JPEG-2000 is a format that compresses a visual image (or a similar set of data) into a  mini‐
       mal  number  of bytes for storage or transmission.  In that, its goal is similar to JPEG.  It
       has two main differences from JPEG.

       One difference is that it does a much better job on most images of throwing  out  information
       in order to achieve a smaller output.  That means when you reconstruct the image from the re‐
       sulting  compressed  file, it looks a lot closer to the image you started with JPEG-2000 than
       with JPEG, for the same compressed file size.  Or, looked at another way, with JPEG-2000  you
       get a much smaller file than with JPEG for the same image quality.

       The  second  difference  is that with JPEG-2000, you decide how much compression you want and
       the compressor adjusts the quality to meet your requirement, whereas with  JPEG,  you  decide
       how  much quality you want and the compressor adjusts the size of the output to meet your re‐
       quirement.  I.e. with JPEG-2000, the quality of the result depends on the compressibility  of
       the input, but with JPEG, the size of the result depends on the compressibility of the input.

       With  JPEG-2000,  you  can  specify lossless compression, thus making it compete with GIF and
       PNG.  With standard JPEG, you always lose something.  (There are rumored to be variations  of
       JPEG around that are lossless, though).

       JPEG  is  much older than JPEG-2000 and far more popular.  JPEG is one of the half dozen most
       popular graphics formats and virtually all graphics facilities understand it.   JPEG-2000  is
       virtually unknown.

       There  is  no compatibility between JPEG and JPEG-2000.  Programs that read JPEG do not auto‐
       matically read JPEG-2000 and vice versa.



SEE ALSO
       jpeg2ktopam(1), pnmtojpeg(1), ppm(1), pgm(1), pbm(1), pam(1),


HISTORY
       pamtojpeg2k was added to Netpbm in Release 10.12 (November 2002).

DOCUMENT SOURCE
       This manual page was generated by the Netpbm tool 'makeman' from  HTML  source.   The  master
       documentation is at

              http://netpbm.sourceforge.net/doc/pamtojpeg2k.html

netpbm documentation                       1 November 2022                Pamtojpeg2k User Manual(1)