jp3d/README.txt

   1 ===============================================================================
   2         JPEG2000 Part 10 (ISO/IEC 15444-10 JP3D) Verification Model
   3
   4                                 Version 1.1
   5 ===============================================================================
   6
   7
   8 1. Scope
   9 ================
  10
  11 This document describes the installation and the use of the JP3D VM decoder and encoder under several operating systems (Linux, Unix, Windows, ...). Version 1.1 contains a complete JPEG 2000 Part 10 encoder, as well as a decoder.
  12 The supported functionalities are compliant with the JPEG2000 part 10 algorithm as described in the WD 6.0.
  13 The provided encoder and the decoder are compatible also with the International standard IS 15444-1 (core coding system).
  14 This implementation has been developped from OpenJPEG implementation of JPEG2000 standard, and for this reason it is written in C language.
  15
  16 If you find some bugs or if you have problems using the encoder/decoder, please send an e-mail to jp3d@lpi.tel.uva.es
  17
  18 2. Installing the code
  19 ======================================================
  20
  21 - After decompressing the zip file provided, you should find
  22 at least the following files in the created 'jp3d_vm' directory:
  23
  24  * libjp3dvm - This directory contains all library related code
  25  * codec - This directory contains all codec related code
  26  * tcltk - This directory contains the API scripts
  27  * README - The file you are reading
  28  * LICENCE - Copyright statement of the JP3D VM software
  29
  30 2.1. Compiling the source code in Windows
  31 -------------------------------------------
  32
  33 This version has been compiled with Visual Studio 2003 using
  34 the projects included in the distribution:
  35
  36  * LibJp3dVM.vcproj - Creates the library with all the JP3D functionalities
  37  * jp3d_vm_enc.vcproj - Test encoder
  38  * jp3d_vm_dec.vcproj - Test decoder
  39
  40 2.2. Compiling the source code in Unix-like systems
  41 -------------------------------------------
  42
  43 Library compilation
  44 ------------------------
  45 This version of the library has been tested under the following OS:
  46 - Fedora Core
  47
  48 The installation process is as simple as this :
  49 1) Enter the 'jp3d_vm' directory
  50 2) Build the distribution :
  51 make
  52 make install
  53 3) Clean all files produced during the build process
  54 make clean
  55
  56 Codec compilation
  57 ------------------------
  58 Once you've built the library, you should compile the JP3D codec.
  59
  60 1) Go to the 'codec' directory
  61 2) Build the encoder and decoder programs:
  62
  63 gcc convert.c volume_to_jp3d.c -o jp3d_vm_enc -I ../libjp3dvm/ -lm -ljp3dvm
  64 gcc convert.c jp3d_to_volume.c -o jp3d_vm_dec -I ../libjp3dvm/ -lm -ljp3dvm
  65
  66 Note: You should add '-L ../libjp3dvm/' to those lines if you
  67 did not use the 'install' target (and the 'clean' target neither...).
  68
  69 3. Running the JP3D VM
  70 ====================================================
  71
  72 3.1. JP3D ENCODER
  73 ====================================================
  74
  75 Required arguments
  76 ------------------------
  77
  78  * Input file(s): -i Involume [*.bin, *.pgx]
  79
  80 Specifies the volume to compress. Accepted formats are *.BIN (raw binary data) or *.PGX files.
  81 Both formats need some particular settings:
  82
  83   a) BIN format. As it has no header, volume characteristics will be obtained from a .IMG file. Its location will be specified through the following argument:
  84            -m Involumeinfo.IMG
  85      This file shall have the following structure, with the appropiate value in each case (bit per voxel, color map, dimensions in X,Y,Z):
  86         o Bpp   %d
  87         o Color Map     %d
  88         o Dimensions    %d %d %d
  89
  90   b) PGX format. Program will consider it as a volume slice. In order to denote a volume through a sequence of slices, you can define the input filename with the common pattern of the set of PGX files followed by a dash (as a wildcard character for the sequence numbers).
  91
  92  * Output file: -o Outfile [*.jp3d, *j2k]
  93
  94 Specifies the name of the file where the codestream will be saved.
  95 Part 1 compliant codestream will be created when an outfile has .j2k format.
  96
  97 Options
  98 --------
  99
 100     * Rate values : -r 20,10,5
 101       This option offers the possibility to define the compression rate to apply.
 102       Each value is a factor of compression (i.e. 20 : 1) and will generate a different quality layer. A lossless compression will be signified by the value 1.
 103       NOTE : The order used to define the different levels of compression is important and must be from left to right in descending order.
 104
 105     * Quality values : -q 30,35,40
 106       This option offers the possibility to define the quality level to achieve. Each value is a psnr, to be given in dB, and represents a quality layer.
 107       NOTE : The order used to define the different psnr-values is important and must be from left to right in ascending order.
 108
 109
 110     * Number of resolutions : -n 3,3,2
 111       This option offers the possibility to define the number of resolution levels computed for each dimension of the volume through the discret wavelet transform (DWT). Resolution in axial dimension can have a different value than in horizontal and vertical cases, but must be lower.
 112       DEFAULT VALUE : 3,3,1
 113
 114
 115     * Switch modes : -M 3
 116       This option offers the possibility to use a mode switch during the encoding process:
 117           o BYPASS(LAZY)        [1]
 118           o RESET               [2]
 119           o RESTART(TERMALL)    [4]
 120           o VSC                 [8]
 121           o ERTERM(SEGTERM)     [16]
 122           o SEGMARK(SEGSYM)     [32]
 123           o 3D_CONTEXT          [64]
 124       For several mode switch just sum corresponding values: i.e. -M 38  => RESTART(4) + RESET(2) + SEGMARK(32)
 125       DEFAULT VALUE: 0
 126
 127
 128     * Progression order : -p LRCP
 129       This option offers the possibility to specify the progression order. Possible progression orders are : LRCP, RLCP, RPCL, PCRL and CPRL.
 130       DEFAULT VALUE: LRCP.
 131
 132
 133     * Code-block size : -b 32,32,32
 134       This option offers the possibility to define the size of the code-block. The dimension must respect the constraint defined in the JPEG-2000 standard. The maximum value autorized is 64x64x64.
 135       DEFAULT VALUE: 64,64,64
 136
 137
 138     * Precinct size : -c [128,128,128],[128,128,128],...
 139       This option offers the possibility to define the size of the precincts at each resolution. Multiple records may be supplied, in which case the first record refers to the highest resolution level and subsequent records to lower resolution levels. The last specified record is right-shifted for each remaining lower resolution levels.
 140       NOTE : specified values must be power of 2.
 141       DEFAULT VALUE: 2^15 x 2^15 x 2^15
 142
 143
 144     * Tile size : -t 512,512,512
 145       This option offers the possibility to divide the volume in several tiles. The three values define the width, the heigth and the depth of the tile respectivily.
 146       DEFAULT VALUE: Volume dimensions (one tile)
 147
 148
 149     * Subsampling factor : -s 2,2,2
 150       This option offers the possibility to apply a subsampling factor for X, Y and Z axis. Value higher than 2 can be a source of error !
 151       DEFAULT VALUE: 1,1,1
 152
 153
 154     * SOP marker before each packet : -SOP
 155       This option offers the possibility to add a specific marker before each packet. It is the marker SOP (Start of packet). If the option is not used no SOP marker will be added.
 156
 157
 158     * EPH marker after each packet header : -EPH
 159       This option offers the possibility to add a specific marker at the head of each packet header. It is the marker EPH (End of packet Header). If the option is not used no EPH marker will be added.
 160
 161
 162     * Offset of the volume origin : -d 150,300,10
 163       This option offers the possibility to move the origine of the volume in X, Y and/or Z axis. The division in tile could be modified as the anchor point for tiling will be different than the volume origin.
 164       NOTE : the offset of the volume can not be higher than the tile dimension if the tile option is used.
 165       DEFAULT VALUE: 0,0,0
 166
 167
 168     * Offset of the tile origin : -T 100,75,5
 169       This option offers the possibility to move the anchor point of the volume in X, Y and/or Z axis.
 170       NOTE : the tile anchor point can not be on the volume area.
 171       DEFAULT VALUE: 0,0,0
 172
 173
 174     * Display the help menu : -help
 175       This option displays on screen the content of this page
 176
 177 Additional options
 178 ----------------------------------
 179
 180     * Encoding information file: -x index_name.idx
 181       This option offers the possibility to create a text file with some structured information generated through the encoding. The name of the file must be specified, with .idx extension. The information structure is the following:
 182           o Volume size:
 183                 + VolW   + VolH   + VolD
 184           o Progression Order:
 185                 + Prog
 186           o Tile size:
 187                 + TileW   + TileH   + TileD
 188           o Number of components:
 189                 + NumComp
 190           o Number of layers:
 191                 + NumLayer
 192           o Number of decompositions (=(number of resolutions - 1)):
 193                 + NumDWTx   + NumDWTy   + NumDWTz
 194           o Precinct size:
 195                 + [Precinct_width(NumDWT),Precinct_height(NumDWT),Precinct_depth(NumDWT)]
 196                 + [Precinct_width(NumDWT-1),Precinct_height(NumDWT-1),Precinct_depth(NumDWT-1)]
 197                 + ...
 198                 + [Precinct_width(0),Precinct_height(0),Precinct_depth(0)]
 199           o Main Header end position:
 200                 + MH_EndPos
 201           o Codestream size:
 202                 + CSSize
 203           o Tile 0 information:
 204                 + TileNum (0)
 205                 + StartPos
 206                 + TileHeader_EndPos
 207                 + EndPos
 208                 + TotalDisto (this is the sum of the distortion reductions brought by each packet belonging to this tile)
 209                 + NumPix (this is the number of pixels in the tile)
 210                 + MaxMSE (=TotalDisto/NumPix)
 211           o Tile1 information:
 212                 + TileNum (1)
 213                 + ...
 214           o ...
 215           o Tile N information:
 216                 + TileNum (N)
 217                 + ...
 218           o Packet 0 from Tile 0 information:
 219                 + PackNum (0)
 220                 + TileNum (0)
 221                 + LayerNum
 222                 + ResNum
 223                 + CompNum
 224                 + PrecNum
 225                 + StartPos
 226                 + EndPos
 227                 + Disto (distortion reduction brought by this packet)
 228           o Packet 1 from Tile 0 information:
 229                 + PackNum (1)
 230                 + ...
 231           o ...
 232           o Packet M from Tile 0 information
 233           o Packet 0 from Tile 1 information
 234           o ...
 235           o Packet M from Tile N information
 236           o Maximum distortion reduction on the whole volume:
 237                 + MaxDisto
 238           o Total distortion on the whole volume (sum of the distortion reductions from all packets in the volume):
 239                 + TotalDisto
 240
 241 3.2. JP3D DECODER
 242 ====================================================
 243
 244 Required arguments
 245 ------------------------
 246
 247     * Infile : -i compressed file
 248       Currently accepts JP3D and J2K-files. The file type is identified based on its suffix (*.jp3d, *.j2k).
 249
 250
 251     * Outfile(s) : -o decompressed file(s)
 252       Currently accepts BIN-files and PGX-files. Binary data is written to the file (not ascii).
 253       If a BIN-file is defined, decoder will create automatically the volume characteristic file appending a .IMG extension to the provided output filename.
 254       If a PGX-file is defined, decoder will understand this as a file pattern, appending corresponding indice from 0 to the number of decoded slices.
 255       NOTE : There will be as many output files as there are components: an indice starting from 0 will then be appended to the output filename, just before the extension.
 256
 257
 258 Options available
 259 ------------------------
 260
 261     * Reduce factor : -r 1,1,0
 262       Set the number of highest resolution levels to be discarded in each dimension. The decoded volume size is effectively divided by 2 to the power of the number of discarded levels.
 263       NOTE : The reduce factor is limited by the smallest total number of decomposition levels among tiles.
 264
 265
 266     * Layer number : -l 2
 267       Set the maximum number of quality layers to decode. If there are less quality layers than the specified number, all the quality layers are decoded.
 268
 269
 270     * Performance comparisons : -O original-file
 271       This option offers the possibility to compute some quality results for the decompressed volume, like the PSNR value achieved or the global SSIM value. Needs the original file in order to compare with the new one.
 272       NOTE: Only valid when -r option is 0,0,0 (both original and decompressed volumes have same resolutions)
 273       NOTE: If original file is .BIN file, the volume characteristics file shall be defined with the -m option.
 274             (i.e. -O original-BIN-file -m original-IMG-file)
 275
 276
 277     * Byte order (Big-endian / Little-endian) : -BE
 278       This option offers the possibility to save the decompressed volume with a predefined byte order.
 279       DEFAULT VALUE: Little-endian
 280
 281
 282     * Display the help menu : -help
 283       This option displays on screen the content of this page
 284
 285