src/gdcmjpegls/README

   1 COMPILATION INSTRUCTIONS:
   2 1. Unpack archive.
   3 2. Run
   4
   5         make clean "name",
   6    where "name" is
   7         loco  -- for encoder/decoder
   8
   9 This program supports:
  10 "8 bit"  images with 8 bits per color component or less.
  11 "16 bit" images with between 9 and 16 bits per color component.
  12          component.
  13
  14 3. Executable for compressor is "locoe," decompressor is "locod".
  15
  16 USAGE:
  17          General remarks for multiple-component images:
  18
  19          a) Encoder input (uncompressed) or decoder output (decompressed)
  20             images are in either PGM (grayscale) or PPM (3-color) format.
  21             This is of course NOT part of the JPEG-LS standard, and these
  22             input/output formats were selected for this implementation only.
  23
  24             These formats have an ASCII header consisting of 3 lines of the
  25             following form
  26
  27             * PGM (single component):
  28
  29                 P5
  30                 cols rows
  31                 maxval
  32
  33             * PPM (3 components)
  34
  35                 P6
  36                 cols rows
  37                 maxval
  38
  39
  40           For PGM, the header is followed by cols*rows samples in binary
  41           format, where cols and rows are the number of columns and rows,
  42           respectively.  A test image "cmpnd2g.pgm" is included in the
  43           archive. Samples have 8 bits if maxval < 256, or 16 bits if
  44           256 <= maxval < 65536.
  45
  46           For PPM, the header is followed by cols*rows TRIPLETS of symbols in
  47           binary format. Each symbol in a triplet represents a color plane
  48           value (viewers usually interpret PPM triplets as RGB).
  49
  50           For more than 3 components, the PPM output file
  51           format is extended to arbitrary m-tuples,
  52           where m is the number of components.
  53           The first row of the header is Px, where x = 10+m
  54           (e.g. P15 for a 5-component image). P5 (m=1), P6 (m=3),
  55           and P7 (m=4) are used, in addition to P11, P13, and P14,
  56           respectively.
  57
  58           A multi-component image can be specified to the encoder either
  59           as a list of PGM files (each representing a color plane), or
  60           a single PPM-type file.
  61
  62          b) Three modes of operation are supported for multi-component
  63             images (images of the type RGB, CMYK, YUV, etc).
  64             We briefly describe them now, for details see the
  65             JPEG-LS Working Draft document.
  66
  67            * Plane-interleaved. The image components are
  68              compressed one after the other, in a completely
  69              independent form. Only multiple input
  70              (one PGM file per plane) in the encoder, and multiple
  71              output (one PGM file per plane) in the decoder are supported
  72              in this mode. This mode also works when m=1.
  73
  74            * Line-interleaved. One row per image component is processed
  75              at a time, in an interleaved form.
  76              Common context statistics for all the components
  77              are used in this mode, and is plane independent otherwise.
  78              Both multiple PGM and single PPM input
  79              (output) are supported in the encoder (decoder).
  80              Line-interleaved mode is the default mode of the encoder.
  81              This mode also works when m=1.
  82
  83            * Sample-interleaved mode. One sample per image component is
  84              processed at a time, using common statistics. Only single PPM
  85              input and single PPM output are supported in this mode.
  86
  87          c) Which of the three multi-components modes runs faster depends
  88             on the specific system (UNIX or PC).
  89             For the line interleaved mode, the processing time relation
  90             between the single and the multiple files input/output depends
  91             on the system as well.
  92
  93          d) Sub-sampled components can be specified to the encoder (e.g.,
  94             a YUV representation with the U and V components having a fraction
  95             of the number of columns of the Y component).
  96             For sub-sampled files, the input to the encoder must be
  97             given as a series of PGM files in non-increasing order of size.
  98             Sample-interleaved mode is not supported for images with
  99             sub-sampled components.
 100
 101          e) The output of the encoder, and input to the decoder, is
 102             always a unique JPEG-LS compressed file, independently of the
 103             number of image components. All the image components share the
 104             same header in JPEG-LS.
 105
 106
 107     COMMAND LINES:
 108
 109         encoder:
 110
 111           locoe [flags] infile1 [infile2,infile3,...] [-ooutfile]
 112
 113           DEFAULTS:
 114           infile1     : must be in PGM or PPM format
 115           infile2,... : additional input files for Plane Interleaved
 116                         or Line Interleaved modes. Must be in PGM (P5) format
 117           outfile     : default is locoe.out
 118
 119           FLAGS, PARAMETERS:
 120           -i<infile>  : alternate input-specification, use -i- for stdin
 121           -o<outfile> : output specification, use -o- for stdout
 122           -c          : mode for multi-component images:
 123                         0: plane interleaved
 124                         1: line interleaved (Default)
 125                         2: sample interleaved
 126           -n<error> or
 127           -e<error>  : Max allowed loss per symbol (default = 0, lossless).
 128           -h          : print help
 129
 130         Remarks:
 131                 The following optional flags allow specification of
 132                 parameters in the algorithm. These parameters,
 133                 if not default, are included in the JPEG-LS
 134                 header, and are part of the standard. Please
 135                 refer to Working Document for details.
 136
 137                 -r         : RESET (if not compiled with FIXRESET, see below)
 138                 -S<a,b,c>  : Context modeling thresholds
 139                 -m<table>  : Use mapping table where <table> is a file in the
 140                              format:
 141                              1st byte of <table> is the Table ID, 2nd byte
 142                              of <table> is the Width of each table entry (in bytes),
 143                              3rd - 6th byte of <table> is the Max Table Index Value
 144                              specified as an integer (4 bytes), 7th byte and on
 145                              are the table entries.
 146                 -t<num>    : Use Restart Markers where <num> is the restart interval
 147                              (ie. number of MCU's between restart markers).\n");
 148
 149                 *** Use only if you know what you are doing!
 150
 151          decoder:
 152
 153           locod [flags] [infile] [outfile1 [outfile2, ...]]
 154
 155           DEFAULTS:
 156           infile   = locoe.out
 157           outfile1 = locod.out for single output file
 158           outfile[1,2,...] = locod[1,2,...].out for multiple output files in
 159                              Plane or Line Interleaved mode
 160           FLAGS, PARAMETERS:
 161           outfile2, ... : multiple output specification for plane- or
 162                           line-interleaved mode
 163           -i<infile>    : alternate input specification, use -i- for stdin
 164           -o<outfile>   : alternate output specification, use -o- for stdout
 165           -P            : generate single (.ppm) output file for
 166                           sample/line-int. mode. Mandatory for sample-int. mode.
 167
 168 EXAMPLES:
 169
 170    For the examples, assume:
 171    * red.pgm, green.pgm, and blue.pgm are 3 color components of
 172      a color image, of the same size.
 173    * color.ppm is the color image corresponding to red.pgm, green.pgm, blue.pgm
 174    * hotely.pgm, hotelu.pgm, hotelv.pgm are 3 components of a color image
 175      sub-sampled in the horizontal direction 2:1:1
 176
 177
 178    a) locoe red.pgm green.pgm blue.pgm
 179
 180       Compresses the three files using the default color mode (line int., c=1)
 181       Compressed file is in locoe.out
 182
 183       locod
 184
 185       Decompresses locoe.out into 3 pgm files:
 186       locod1.out, locod2.out, locod3.out
 187
 188       locod locoe.out a.pgm b.pgm c.pgm
 189
 190       Decompresses locoe.out into 3 pgm files: a.pgm, b.pgm, c.pgm
 191
 192       locod -P
 193
 194       Decompresses locoe.out into one ppm file: locod.out
 195
 196
 197
 198    b) locoe color.ppm
 199
 200       Same as (a), using single input
 201
 202    c) locoe -c0 red.pgm green.pgm blue.pgm
 203
 204       Compresses the three files using the plane interleaved color mode
 205
 206       locod
 207
 208       Decompresses locoe.out into 3 pgm files: locod1.out, locod2.out,
 209       locod3.out In this case, since c=0, the command locod -P will give
 210       an error.
 211
 212    d) locoe -c2 color.ppm
 213
 214       Compresses color.ppm with sample int. mode. Note that only one (ppm) input
 215       file must be given in this mode.
 216       Output is in locoe.out
 217
 218       locod -P
 219
 220       Decompresses locoe.out into locod.out. Note that -P must be given, since
 221       for sample int. mode, only single output file is supported.
 222
 223    g) locoe -Sa5 -Sb9 red.pgm
 224
 225       Compress red.pgm with Sa=5, Sb=9, and Sc=DEFAULT
 226
 227    h) locoe -r128 green.pgm
 228
 229       Compresses green.pgm with RESET=128.
 230
 231
 232 OTHER CAVEATS, LIMITATIONS, ANNOYANCES, BUGS (?)
 233 =================================================
 234 * The makefiles included in this version are very simple and could lead to
 235   a slower executable files than HP executables.
 236 * Annoyance: no spaces are allowed between flags and their arguments. This
 237   will be fixed in a future version.
 238 * Other bugs, annoyances: you tell us.
 239
 240 ------------------------------------------------------------------------------
 241
 242 Feedback to
 243 -----------
 244 The SPMG lab at the University of British Columbia:
 245 ismaeil R. Ismaeil ismail@ee.ubc.ca
 246 Dr. Faouzi Kossentini faouzi@ece.ubc.ca, or