src/gdcmjpegls/README.DIST

   1 SPMG/JPEG-LS IMPLEMENTATION V.2.1
   2 =====================================
   3 These programs are Copyright (c) University of British Columbia. All rights reserved.
   4 They may be freely redistributed in their entirety provided that this copyright
   5 notice is not removed. THEY MAY NOT BE SOLD FOR PROFIT OR INCORPORATED IN
   6 COMMERCIAL PROGRAMS WITHOUT THE WRITTEN PERMISSION OF THE COPYRIGHT HOLDER.
   7 Each program is provided as is, without any express or implied warranty,
   8 without even the warranty of fitness for a particular purpose.
   9
  10 =========================================================
  11 THIS SOFTWARE IS BASED ON HP's implementation of jpeg-ls:
  12 =========================================================
  13
  14 LOCO-I/JPEG-LS IMPLEMENTATION V.0.90
  15 -------------------------------------------------------------------------------
  16 (c) COPYRIGHT HEWLETT-PACKARD COMPANY, 1995-1997.
  17      HEWLETT-PACKARD COMPANY ("HP") DOES NOT WARRANT THE ACCURACY OR
  18 COMPLETENESS OF THE INFORMATION GIVEN HERE.  ANY USE MADE OF, OR
  19 RELIANCE ON, SUCH INFORMATION IS ENTIRELY AT USER'S OWN RISK.
  20      BY DOWNLOADING THE LOCO-I/JPEG-LS COMPRESSORS/DECOMPRESSORS
  21 ("THE SOFTWARE") YOU AGREE TO BE BOUND BY THE TERMS AND CONDITIONS
  22 OF THIS LICENSING AGREEMENT.
  23      YOU MAY DOWNLOAD AND USE THE SOFTWARE FOR NON-COMMERCIAL PURPOSES
  24 FREE OF CHARGE OR FURTHER OBLIGATION.  YOU MAY NOT, DIRECTLY OR
  25 INDIRECTLY, DISTRIBUTE THE SOFTWARE FOR A FEE, INCORPORATE THIS
  26 SOFTWARE INTO ANY PRODUCT OFFERED FOR SALE, OR USE THE SOFTWARE
  27 TO PROVIDE A SERVICE FOR WHICH A FEE IS CHARGED.
  28      YOU MAY MAKE COPIES OF THE SOFTWARE AND DISTRIBUTE SUCH COPIES TO
  29 OTHER PERSONS PROVIDED THAT SUCH COPIES ARE ACCOMPANIED BY
  30 HEWLETT-PACKARD'S COPYRIGHT NOTICE AND THIS AGREEMENT AND THAT
  31 SUCH OTHER PERSONS AGREE TO BE BOUND BY THE TERMS OF THIS AGREEMENT.
  32      THE SOFTWARE IS NOT OF PRODUCT QUALITY AND MAY HAVE ERRORS OR DEFECTS.
  33 THE JPEG-LS STANDARD IS STILL UNDER DEVELOPMENT. THE SOFTWARE IS NOT A
  34 FINAL OR FULL IMPLEMENTATION OF THE STANDARD.  HP GIVES NO EXPRESS OR
  35 IMPLIED WARRANTY OF ANY KIND AND ANY IMPLIED WARRANTIES OF
  36 MERCHANTABILITY AND FITNESS FOR PURPOSE ARE DISCLAIMED.
  37      HP SHALL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL,
  38 OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE.
  39 -------------------------------------------------------------------------------
  40
  41
  42 This software package contains an implementation of JPEG-LS, the
  43 emerging lossless/near-lossless compression standard for continuous-tone
  44 images being developed by ISO/IEC JTC1/SC29/WG1 (draft document FCD14495
  45 as of November 1997). The names of the executables in the software package
  46 derive from the acronym LOCO, as the core of the new standard is
  47 based on the LOCO-I algorithm (LOw COmplexity LOssless
  48 COmpression for Images) developed at Hewlett-Packard Laboratories
  49 (reference: M. Weinberger, G. Seroussi, G. Sapiro, "LOCO-I: A Low
  50 Complexity, Context-Based, Lossless Image Compression Algorithm,"
  51 Proc. IEEE Data Compression Conference, Snowbird, Utah, March-April 1996).
  52
  53 The term "near-lossless compression" refers to a lossy algorithm
  54 for which each decompressed image sample differs from the corresponding
  55 original image sample by not more than a pre-specified value, the (usually
  56 small) "loss."  Lossless compression corresponds to loss=0.
  57 Even though the term "continuous-tone image" refers in principle to any
  58 image whose components have more than one bit per sample, palletized images
  59 may require a reordering of the color palette for best compression results
  60 using LOCO-I on the array of color indices. This functionality is not
  61 implemented in the present software, although it is supported by the new
  62 standard, and is easy enough to implement with the tools given. Notice,
  63 however, that LOCO-I and JPEG-LS were not designed, and might not give
  64 optimal performance, for images that have been palletized through dithering.
  65
  66 At various points in the README file, we refer to the FCD14495 draft
  67 standard. An electronic version of the draft is available from the official
  68 JPEG Web site at <http://www.disc.org.uk/public/jpegnew.htm> (a very nice
  69 site worth browsing in any case).
  70
  71
  72 THIS PACKAGE CONTAINS:
  73 ----------------------
  74
  75         README.DIST - this file
  76         Encoder - contains the encoder's source code.
  77         Decoder - contains the dncoder's source code.
  78         JLSEncoder.exe - the executable of a Win95/NT based
  79                          GUI implementation of the jpeg-ls codec
  80         (The images lena8b.jls and lena24b.jls are provided so that
  81           you can immediately "play" with the executable.)
  82
  83         Two table files which they can be used to test the mapping
  84         tables:
  85         "table_r" is for 8bpp PGM's which will reverse the colour.
  86         "table24_no_red" is also for 8bpp PGM's and converts it to
  87          a RGB PPM file but has all its red values 0.
  88
  89
  90 IMAGE FORMATS:
  91 --------------
  92
  93         Encoder input (uncompressed) or decoder output (decompressed)
  94         images are in either PGM (grayscale) or PPM (3-color) format.
  95         These input/output formats are NOT part of the JPEG-LS standard,
  96         and they were selected for the sake of simplicity in this
  97         implementation.
  98
  99         The PGM and PPM formats have an ASCII header consisting of 3 lines
 100         of the following form:
 101
 102             * PGM (single component):
 103
 104                 P5
 105                 cols rows
 106                 maxval
 107
 108             * PPM (3 components)
 109
 110                 P6
 111                 cols rows
 112                 maxval
 113
 114         P5 and P6 appear verbatim in the header. The parameters "cols,"
 115         "rows," and "maxval" are decimal numbers in ASCII representation.
 116         For PGM, the header is followed by cols*rows samples in binary format,
 117         where cols and rows are the number of columns and rows, respectively.
 118         For this implementation, each sample occupies one 8-bit byte if
 119         maxval < 256, or two bytes if 256 <= maxval < 65536. In the case of
 120         16-bit samples, BIG ENDIAN convention is used (most significant byte
 121         first).
 122
 123         For PPM, the header is followed by cols*rows TRIPLETS of symbols in
 124         binary format. Each symbol in a triplet represents a color plane
 125         value (viewers usually interpret PPM triplets as RGB).
 126
 127         A multi-component image can be specified to the encoder either as
 128         a list of PGM files (each representing a color plane), or as a single
 129         PPM-type file.
 130
 131 MULTIPLE-COMPONENT IMAGES:
 132 --------------------------
 133
 134         Three modes of operation are supported for multi-component images
 135         (images of the type RGB, CMYK, YUV, etc). This is a subset of the
 136         more general scan-based structure supported by JPEG-LS, and is
 137         briefly described next:
 138
 139            * Plane-by-plane (PbP) compression. The image components are
 140              compressed one after the other, in a completely independent
 141              manner (in JPEG terminology, there is one component per scan).
 142              In this mode, the input to the encoder is one PGM file per
 143              component (i.e., no PPM input is allowed). The same applies to
 144              the output of the decoder.
 145
 146            * Line-interleaved (LI) compression. One row per image component
 147              is processed at a time, in an interleaved manner (in JPEG
 148              terminology, all the components are encoded in the same
 149              scan).  Both multiple PGM file and single file PPM input
 150              (output) are supported by the encoder (decoder). LI mode is
 151              the default mode of this implementation.
 152
 153            * Sample-interleaved (SI) compression. One sample per image
 154              component is processed at a time, in an interleaved manner
 155              (again, all the components are encoded in the same scan).
 156              In this mode, the input to the encoder (output from the
 157              decoder) is always a single PPM file.
 158
 159         Remarks:
 160
 161         a) Sub-sampled components can be specified to the encoder in
 162            PbP and LI modes (e.g., a YUV representation with the U and
 163            V components having a fraction of the number of columns of
 164            the Y component). For sub-sampled images, the input to the
 165            encoder must be given as a sequence of PGM files. JPEG-LS
 166            does not support sub-sampling in SI mode.
 167
 168         b) Regardless of the input format, the output of the encoder (input
 169            to the decoder), is always a single JPEG-LS compressed bit-stream,
 170            consisting of marker segments and compressed image data segments.
 171
 172         c) The SI mode is recommended only for computer generated compound
 173            documents. On other image types, this mode is likely to be slower,
 174            and compress worse, than the other modes.
 175
 176         d) For single-component images, the three modes are equivalent.
 177            By default, the JPEG-LS header will indicate LI mode in this case.
 178
 179
 180 COMMAND LINES:
 181 --------------
 182
 183         encoder:
 184         --------------------------
 185
 186         locoe [flags] infile1 [infile2,infile3,...] [-ooutfile]
 187
 188         FILES:
 189         infile1    : Input file -- must be in PGM or PPM format. If there
 190                      are additional input files, then infile1 must be in
 191                      PGM format.
 192         infile2,...: Additional input files for PbP or LI modes. Must be
 193                      in PGM format.
 194         outfile    : Output file in JPEG-LS format. Default = locoe.jls.
 195
 196         FLAGS, PARAMETERS:
 197         (*** NOTE: no spaces allowed between a flag and its argument ***)
 198
 199         -i<infile> : Alternate input specification, use -i- for stdin.
 200         -o<outfile>: Output specification, use -o- for stdout
 201                      (default=locoe.jls).
 202         -c<num>    : Mode for multi-component images (program default=1):
 203                      0:plane-by-plane
 204                      1:line-interleaved
 205                      2:sample-interleaved.
 206         -n<error> or
 207         -e<error>  : Max allowed loss per symbol (default = 0, lossless).
 208
 209         -h         : Print help.
 210
 211         OTHER FLAGS AND PARAMETERS:
 212         The following optional flags allow for overriding of JPEG-LS
 213         default parameters. Please refer to JPEG-LS specification (FCD14495)
 214         for details.  *** Use only if you know what you are doing! ***
 215
 216         -r<num>    : reset frequency
 217         -Ta<num>,
 218         -Tb<num>,
 219         -Tc<num>   : context modeling thresholds
 220         -m<table>  : Use mapping table where <table> is a file in the
 221                      format:
 222                      1st byte of <table> is the Table ID, 2nd byte
 223                      of <table> is the Width of each table entry (in bytes),
 224                      3rd - 6th byte of <table> is the Max Table Index Value
 225                      specified as an integer (4 bytes), 7th byte and on
 226                      are the table entries.
 227         -t<num>    : Use Restart Markers where <num> is the restart interval
 228                      (ie. number of MCU's between restart markers).
 229
 230
 231         decoder:
 232         --------------------------
 233
 234         locod [flags] [infile] [outfile1 [outfile2,outfile3,...]]
 235
 236         FILES:
 237         infile   : Input file in JPEG-LS format. Default = locoe.jls.
 238         outfile[1,2,...] : Output files. If a single PPM file is generated
 239                    for a multi-component image (in LI or SI modes), the
 240                    default name is locod.out. In all other cases, the
 241                    default names for the of PGM output files are
 242                    locod1.out, locod2.out, locod3.out, ...
 243
 244         FLAGS, PARAMETERS:
 245         -i<infile> : Alternate input specification, use -i- for stdin.
 246         -o<outfile>: Alternate output specification, use -o- for stdout.
 247         -P         : Generate single PPM output file for SI or LI modes. This
 248                      is the default for SI mode. The default for LI mode (and
 249                      only option for PbP mode) is a sequence of PGM files.
 250
 251
 252 EXAMPLES:
 253 ---------
 254
 255         For the examples, assume:
 256         * red.pgm, green.pgm, and blue.pgm are 3 PGM components of a color
 257           image, of the same size.
 258         * color.ppm is the color PPM image corresponding to red.pgm,
 259           green.pgm, blue.pgm
 260         * hotely.pgm, hotelu.pgm, hotelv.pgm are 3 components of a color
 261           image sub-sampled in the horizontal direction 2:1:1
 262
 263
 264         a) locoe red.pgm green.pgm blue.pgm
 265
 266            Compresses the three components using the program default color
 267            mode (LI, c=1). Compressed bit-stream is locoe.jls
 268
 269            locod
 270
 271            Decompresses locoe.jls into 3 PGM files:
 272            locod1.out, locod2.out, locod3.out
 273
 274            locod locoe.jls a.pgm b.pgm c.pgm
 275
 276            Decompresses locoe.jls into 3 PGM files: a.pgm, b.pgm, c.pgm
 277
 278            locod -P
 279
 280            Decompresses locoe.jls into one PPM file: locod.out
 281
 282
 283         b) locoe color.ppm
 284
 285            Same as (a), using single input
 286
 287
 288         c) locoe -c0 red.pgm green.pgm blue.pgm
 289
 290            Compresses the three components in PbP mode. Compressed
 291            bit-stream is locoe.jls
 292
 293            locod
 294
 295            Decompresses locoe.jls into 3 PGM files: locod1.out, locod2.out,
 296            locod3.out.
 297
 298            locod -P
 299
 300            Since c=0, this command will produce an error.
 301
 302         d) locoe -c2 color.ppm
 303
 304            Compresses color.ppm in SI mode. Only one (PPM) input file
 305            can be specified in this mode. Compressed bit stream is locoe.jls.
 306
 307            locod
 308
 309            Decompresses locoe.jls into locod.out, a PPM file.
 310            Note that -P needs not be specified in this case.
 311
 312         g) locoe -Ta5 -Tb9 red.pgm
 313
 314            Compresses red.pgm with context thresholds Ta=5, Tb=9,
 315            and Tc=DEFAULT
 316
 317         h) locoe -r128 green.pgm
 318
 319            Compresses green.pgm with RESET=128.
 320
 321
 322 OTHER CAVEATS, LIMITATIONS, ANNOYANCES, BUGS (?)
 323 =================================================
 324
 325         * Annoyance: no spaces are allowed between flags and their arguments.
 326           This will be fixed in a future version.
 327         * Other bugs, annoyances: guaranteed to exist. Please tell us
 328           if you find significant ones. We will be thankful. However, we
 329           cannot guarantee that we will maintain the code or that we will
 330           satisfy requests for added functionality, recompilation,
 331           executables for other operating systems, etc.
 332
 333 Feedback to the SPMG/JPEGLS at UBC:
 334 www.spmg.ece.ubc.ca, or
 335
 336 LOCO-I/JPEG-LS team at HP Labs:
 337 http://www.hpl.hp.com/loco