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]
       [-cblkwidth=columns]  [-cblkheight=rows]  [-mode={integer|int|real}]  [-compression=ratio]
       [-size=bytes]     [-ilyrrates=[realnumber[,realnumber,      ...]]       [-numrlvls=number]
       [-progression={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 separate 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
       arbitrary 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  pamtojpeg2k  produces  ITU-R Recommendation BT.709 values.  Those are very
       similar, but  not  identical.   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
       produced contains whatever the PAM raster does.  It can have any number of planes with any
       meanings; 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
       precision can represent in pure binary code.  E.g. if the precision is 4,  the  maxval  is
       15.   pamtojpeg2k  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   Jasper    JPEG-2000    library
       ⟨http://www.ece.uvic.ca/~mdadams/jasper/⟩  .  See documentation of the library for details
       on what pamtojpeg2k produces.  Note  that  the  Jasper  library  contains  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
       between 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
       library 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  ⟨jpeg.org/jpegls⟩  .   CharLS  ⟨http://github.com/team-
       charls/charls⟩  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
        Common Options ⟨index.html#commonoptions⟩ ), 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
       encoder        subroutine         takes.          See         Jasper         documentation
       ⟨http://www.ece.uvic.ca/~mdadams/jasper/⟩  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 requested compression ratio at any  quality.   If  it  isn't,  pamtojpeg2k
              fails with a message 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
              message, "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 explanatory 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
              number 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
       minimal  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 resulting 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
       requirement.    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
       automatically 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