README

   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 'openjpeg3d' directory:
  23
  24  * libopenjpeg3d - 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  * LICENSE - Copyright statement of the JP3D VM software
  29
  30 2.1. Compilation
  31 -----------------
  32
  33 see INSTALL file for compilation and installation instructions
  34
  35 3. Running the JP3D VM
  36 ====================================================
  37
  38 3.1. JP3D ENCODER
  39 ====================================================
  40
  41 Required arguments
  42 ------------------------
  43
  44  * Input file(s): -i Involume [*.bin, *.pgx]
  45
  46 Specifies the volume to compress. Accepted formats are *.BIN (raw binary data) or *.PGX files.
  47 Both formats need some particular settings:
  48
  49   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:
  50            -m Involumeinfo.IMG
  51      This file shall have the following structure, with the appropiate value in each case (bit per voxel, color map, dimensions in X,Y,Z):
  52         o Bpp   %d
  53         o Color Map     %d
  54         o Dimensions    %d %d %d
  55
  56   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).
  57
  58  * Output file: -o Outfile [*.jp3d, *j2k]
  59
  60 Specifies the name of the file where the codestream will be saved.
  61 Part 1 compliant codestream will be created when an outfile has .j2k format.
  62
  63 Options
  64 --------
  65
  66     * Rate values : -r 20,10,5
  67       This option offers the possibility to define the compression rate to apply.
  68       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.
  69       NOTE : The order used to define the different levels of compression is important and must be from left to right in descending order.
  70
  71     * Quality values : -q 30,35,40
  72       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.
  73       NOTE : The order used to define the different psnr-values is important and must be from left to right in ascending order.
  74
  75
  76     * Number of resolutions : -n 3,3,2
  77       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.
  78       DEFAULT VALUE : 3,3,1
  79
  80
  81     * Switch modes : -M 3
  82       This option offers the possibility to use a mode switch during the encoding process:
  83           o BYPASS(LAZY)        [1]
  84           o RESET               [2]
  85           o RESTART(TERMALL)    [4]
  86           o VSC                 [8]
  87           o ERTERM(SEGTERM)     [16]
  88           o SEGMARK(SEGSYM)     [32]
  89           o 3D_CONTEXT          [64]
  90       For several mode switch just sum corresponding values: i.e. -M 38  => RESTART(4) + RESET(2) + SEGMARK(32)
  91       DEFAULT VALUE: 0
  92
  93
  94     * Progression order : -p LRCP
  95       This option offers the possibility to specify the progression order. Possible progression orders are : LRCP, RLCP, RPCL, PCRL and CPRL.
  96       DEFAULT VALUE: LRCP.
  97
  98
  99     * Code-block size : -b 32,32,32
 100       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.
 101       DEFAULT VALUE: 64,64,64
 102
 103
 104     * Precinct size : -c [128,128,128],[128,128,128],...
 105       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.
 106       NOTE : specified values must be power of 2.
 107       DEFAULT VALUE: 2^15 x 2^15 x 2^15
 108
 109
 110     * Tile size : -t 512,512,512
 111       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.
 112       DEFAULT VALUE: Volume dimensions (one tile)
 113
 114
 115     * Subsampling factor : -s 2,2,2
 116       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 !
 117       DEFAULT VALUE: 1,1,1
 118
 119
 120     * SOP marker before each packet : -SOP
 121       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.
 122
 123
 124     * EPH marker after each packet header : -EPH
 125       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.
 126
 127
 128     * Offset of the volume origin : -d 150,300,10
 129       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.
 130       NOTE : the offset of the volume can not be higher than the tile dimension if the tile option is used.
 131       DEFAULT VALUE: 0,0,0
 132
 133
 134     * Offset of the tile origin : -T 100,75,5
 135       This option offers the possibility to move the anchor point of the volume in X, Y and/or Z axis.
 136       NOTE : the tile anchor point can not be on the volume area.
 137       DEFAULT VALUE: 0,0,0
 138
 139
 140     * Display the help menu : -help
 141       This option displays on screen the content of this page
 142
 143 Additional options
 144 ----------------------------------
 145
 146     * Encoding information file: -x index_name.idx
 147       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:
 148           o Volume size:
 149                 + VolW   + VolH   + VolD
 150           o Progression Order:
 151                 + Prog
 152           o Tile size:
 153                 + TileW   + TileH   + TileD
 154           o Number of components:
 155                 + NumComp
 156           o Number of layers:
 157                 + NumLayer
 158           o Number of decompositions (=(number of resolutions - 1)):
 159                 + NumDWTx   + NumDWTy   + NumDWTz
 160           o Precinct size:
 161                 + [Precinct_width(NumDWT),Precinct_height(NumDWT),Precinct_depth(NumDWT)]
 162                 + [Precinct_width(NumDWT-1),Precinct_height(NumDWT-1),Precinct_depth(NumDWT-1)]
 163                 + ...
 164                 + [Precinct_width(0),Precinct_height(0),Precinct_depth(0)]
 165           o Main Header end position:
 166                 + MH_EndPos
 167           o Codestream size:
 168                 + CSSize
 169           o Tile 0 information:
 170                 + TileNum (0)
 171                 + StartPos
 172                 + TileHeader_EndPos
 173                 + EndPos
 174                 + TotalDisto (this is the sum of the distortion reductions brought by each packet belonging to this tile)
 175                 + NumPix (this is the number of pixels in the tile)
 176                 + MaxMSE (=TotalDisto/NumPix)
 177           o Tile1 information:
 178                 + TileNum (1)
 179                 + ...
 180           o ...
 181           o Tile N information:
 182                 + TileNum (N)
 183                 + ...
 184           o Packet 0 from Tile 0 information:
 185                 + PackNum (0)
 186                 + TileNum (0)
 187                 + LayerNum
 188                 + ResNum
 189                 + CompNum
 190                 + PrecNum
 191                 + StartPos
 192                 + EndPos
 193                 + Disto (distortion reduction brought by this packet)
 194           o Packet 1 from Tile 0 information:
 195                 + PackNum (1)
 196                 + ...
 197           o ...
 198           o Packet M from Tile 0 information
 199           o Packet 0 from Tile 1 information
 200           o ...
 201           o Packet M from Tile N information
 202           o Maximum distortion reduction on the whole volume:
 203                 + MaxDisto
 204           o Total distortion on the whole volume (sum of the distortion reductions from all packets in the volume):
 205                 + TotalDisto
 206
 207 3.2. JP3D DECODER
 208 ====================================================
 209
 210 Required arguments
 211 ------------------------
 212
 213     * Infile : -i compressed file
 214       Currently accepts JP3D and J2K-files. The file type is identified based on its suffix (*.jp3d, *.j2k).
 215
 216
 217     * Outfile(s) : -o decompressed file(s)
 218       Currently accepts BIN-files and PGX-files. Binary data is written to the file (not ascii).
 219       If a BIN-file is defined, decoder will create automatically the volume characteristic file appending a .IMG extension to the provided output filename.
 220       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.
 221       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.
 222
 223
 224 Options available
 225 ------------------------
 226
 227     * Reduce factor : -r 1,1,0
 228       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.
 229       NOTE : The reduce factor is limited by the smallest total number of decomposition levels among tiles.
 230
 231
 232     * Layer number : -l 2
 233       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.
 234
 235
 236     * Performance comparisons : -O original-file
 237       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.
 238       NOTE: Only valid when -r option is 0,0,0 (both original and decompressed volumes have same resolutions)
 239       NOTE: If original file is .BIN file, the volume characteristics file shall be defined with the -m option.
 240             (i.e. -O original-BIN-file -m original-IMG-file)
 241
 242
 243     * Byte order (Big-endian / Little-endian) : -BE
 244       This option offers the possibility to save the decompressed volume with a predefined byte order.
 245       DEFAULT VALUE: Little-endian
 246
 247
 248     * Display the help menu : -help
 249       This option displays on screen the content of this page
 250
 251