src/lib/openjpwl/README.txt

   1 ===============================================================================
   2         JPEG2000 Part 11 (ISO/IEC 15444-11 JPWL) Software
   3
   4
   5
   6                 Version 20061213
   7 ===============================================================================
   8
   9
  10
  11
  12
  13 1. Scope
  14 =============
  15
  16 This document describes the installation and use of the JPWL module in the framework of OpenJPEG library.
  17
  18 This implementation has been developed from OpenJPEG implementation of JPEG2000 standard, and for this reason it is written in C language.
  19
  20 If you find some bugs or if you have problems using the encoder/decoder, please send an e-mail to jpwl@diei.unipg.it
  21
  22
  23 2. Installing the code
  24 ==========================
  25
  26 The JPWL code is integrated with the standard OpenJPEG library and codecs: it is activated by setting the macro USE_JPWL to defined in the preprocessor configuration options of your preferred C compiler.
  27
  28 2.1. Compiling the source code in Windows
  29 -------------------------------------------
  30
  31 The "jpwl" directory is already populated with a couple of Visual C++ 6.0 workspaces
  32
  33  * JPWL_image_to_j2k.dsw - Creates the encoder with JPWL functionalities
  34  * JPWL_j2k_to_image.dsw - Creates the decoder with JPWL functionalities
  35
  36 2.2. Compiling the source code in Unix-like systems
  37 -----------------------------------------------------
  38
  39 Under linux, enter the jpwl directory and type "make clean" and "make".
  40
  41
  42 3. Running the JPWL software
  43 =========================
  44
  45 The options available at the command line are exactly the same of the base OpenJPEG codecs. In addition, there is a "-W" switch that activates JPWL functionalities.
  46
  47 3.1. JPWL Encoder
  48 -------------------
  49
  50 -W           : adoption of JPWL (Part 11) capabilities (-W params)
  51                The parameters can be written and repeated in any order:
  52                [h<tile><=type>,s<tile><=method>,a=<addr>,z=<size>,g=<range>,...
  53                 ...,p<tile:pack><=type>]
  54
  55                  h selects the header error protection (EPB): 'type' can be
  56                    [0=none 1,absent=predefined 16=CRC-16 32=CRC-32 37-128=RS]
  57                    if 'tile' is absent, it applies to main and tile headers
  58                    if 'tile' is present, it applies from that tile
  59                      onwards, up to the next h<tile> spec, or to the last tile
  60                      in the codestream (max. 16 specs)
  61
  62                  p selects the packet error protection (EEP/UEP with EPBs)
  63                   to be applied to raw data: 'type' can be
  64                    [0=none 1,absent=predefined 16=CRC-16 32=CRC-32 37-128=RS]
  65                    if 'tile:pack' is absent, it starts from tile 0, packet 0
  66                    if 'tile:pack' is present, it applies from that tile
  67                      and that packet onwards, up to the next packet spec
  68                      or to the last packet in the last tile in the codestream
  69                      (max. 16 specs)
  70
  71                  s enables sensitivity data insertion (ESD): 'method' can be
  72                    [-1=NO ESD 0=RELATIVE ERROR 1=MSE 2=MSE REDUCTION 3=PSNR
  73                     4=PSNR INCREMENT 5=MAXERR 6=TSE 7=RESERVED]
  74                    if 'tile' is absent, it applies to main header only
  75                    if 'tile' is present, it applies from that tile
  76                      onwards, up to the next s<tile> spec, or to the last tile
  77                      in the codestream (max. 16 specs)
  78
  79                  g determines the addressing mode: <range> can be
  80                    [0=PACKET 1=BYTE RANGE 2=PACKET RANGE]
  81
  82                  a determines the size of data addressing: <addr> can be
  83                    2/4 bytes (small/large codestreams). If not set, auto-mode
  84
  85                  z determines the size of sensitivity values: <size> can be
  86                    1/2 bytes, for the transformed pseudo-floating point value
  87
  88                  ex.:
  89  h,h0=64,h3=16,h5=32,p0=78,p0:24=56,p1,p3:0=0,p3:20=32,s=0,s0=6,s3=-1,a=0,g=1,z=1
  90                  means
  91                    predefined EPB in MH, rs(64,32) from TPH 0 to TPH 2,
  92                    CRC-16 in TPH 3 and TPH 4, CRC-32 in remaining TPHs,
  93                    UEP rs(78,32) for packets 0 to 23 of tile 0,
  94                    UEP rs(56,32) for packets 24 to the last of tile 0,
  95                    UEP rs default for packets of tile 1,
  96                    no UEP for packets 0 to 19 of tile 3,
  97                    UEP CRC-32 for packets 20 of tile 3 to last tile,
  98                    relative sensitivity ESD for MH,
  99                    TSE ESD from TPH 0 to TPH 2, byte range with automatic
 100                    size of addresses and 1 byte for each sensitivity value
 101
 102                  ex.:
 103                        h,s,p
 104                  means
 105                    default protection to headers (MH and TPHs) as well as
 106                    data packets, one ESD in MH
 107
 108                  N.B.: use the following recommendations when specifying
 109                        the JPWL parameters list
 110                    - when you use UEP, always pair the 'p' option with 'h'
 111
 112 3.2. JPWL Decoder
 113 -------------------
 114
 115   -W <options>
 116     Activates the JPWL correction capability, if the codestream complies.
 117     Options can be a comma separated list of <param=val> tokens:
 118     c, c=numcomps
 119        numcomps is the number of expected components in the codestream
 120        (search of first EPB rely upon this, default is 3)
 121
 122
 123 4. Known bugs and limitations
 124 ===============================
 125
 126 4.1. Bugs
 127 -----------
 128
 129 * It is not possible to save a JPWL encoded codestream using the wrapped file format (i.e. JP2): only raw file format (i.e. J2K) is working
 130
 131 4.2. Limitations
 132 ------------------
 133
 134 * When specifying an UEP protection, you need to activate even TPH protection for those tiles where there is a protection of the packets
 135 * RED insertion is not currently implemented at the decoder
 136 * JPWL at entropy coding level is not implemented