jj2000.j2k.codestream.writer
Class PktEncoder

java.lang.Object
  |
  +--jj2000.j2k.codestream.writer.PktEncoder

public class PktEncoder
extends java.lang.Object

This class builds packets and keeps the state information of packet interdependencies. It also supports saving the state and reverting (restoring) to the last saved state, with the save() and restore() methods.

Each time the encodePacket() method is called a new packet is encoded, the packet header is returned by the method, and the packet body can be obtained with the getLastBodyBuf() and getLastBodyLen() methods.


Field Summary
private  int[][][][][] bak_lblock
          The saved base number of bits for sending code-block length information.
private  int[][][][][] bak_prevtIdxs
          The saved last encoded truncation point for each code-block.
private  CBlkCoordInfo[][][][][] cbArrayI
          Array containing the coordinates, width, height, indexes, ...
(package private)  EncoderSpecs encSpec
          The encoder specs
private  Coord[][][] incArray
          Array containing the increment step 1st dim : tile index 2nd dim : component index 3rd dim : resolution level
private  Coord[][] incArrayMax
          Array containing the maximum increment step 1st dim : tile index 2nd dim : component index
private  CodedCBlkDataSrcEnc infoSrc
          The source object
private static int INIT_LBLOCK
          The initial value for the lblock
private  byte[] lbbuf
          The body buffer of the last encoded packet
private  int lblen
          The body length of the last encoded packet
private  int[][][][][] lblock
          The base number of bits for sending code-block length information (referred as Lblock in the JPEG 2000 standard).
private  Coord[][][] maxNumPrec
          Maximum number of precincts in each resolution level : 1st dim: tile index. 2nd dim: component index. 3nd dim: resolution level index.
(package private)  int[][] mrl
          The maximum number of resolution level for each component and each tile
static char OPT_PREFIX
          The prefix for packet encoding options: 'P'
private  boolean packetWritable
          Whether or not the current packet is writable
private static java.lang.String[][] pinfo
          The list of parameters that is accepted for packet encoding.
private  PrecCoordInfo[][][][][] precArrayI
          Array containing the coordinates, width, height, indexes, ...
private  int[][][][][] prevtIdxs
          The last encoded truncation point for each code-block.
private  boolean roiInPkt
          Whether or not there is ROI information in the last encoded Packet
private  int roiLen
          Length to read in current packet body to get all the ROI information
private  boolean saved
          The saved state
private  SubbandAn[][] savedSbTree
          Backup of the subband tree for each tile and component as they are used quite often.
private  Coord[][][][] sot_eotArray
          Array used to store the start/end of tile horizontal and vertical coordinates at each resolution level 1st dim : tile index 2nd dim : component index 3rd dim : resolution level 4th dim : 0, start of tile, 1, end of tile
private  Coord[][][] sot_eotArrayMax
          Array used to store the start/end of tile horizontal and vertical coordinates at the highest resolution level using the smallest increments 1st dim : tile index 2nd dim : component index 3rd dim : 0, start of tile, 1, end of tile
private  int[][][][] subRange
          Keeps the first and the last subband index in the associated resolution level for each tile and each component
private  TagTreeEncoder[][][][][] ttIncl
          The tag tree for inclusion information.
private  TagTreeEncoder[][][][][] ttMaxBP
          The tag tree for the maximum significant bit-plane.
 
Constructor Summary
PktEncoder(CodedCBlkDataSrcEnc infoSrc, EncoderSpecs encSpec, Coord[][][] maxNumPrec, ParameterList pl)
          Creates a new packet header encoder, using the information from the 'infoSrc' object.
 
Method Summary
private  void buildCblkPrec(int t, int c, int resLvl)
          Builds the lists containing the ulx, uly, width, height and indexes of the code-blocks and of the precincts for each tile, component, resolution level and subband.
private  void buildIncArrays(int c, int t)
          Creates the arrays incArray and incArrayMax.
private  void buildSotEotArrays(int c, int t)
          Creates the arrays sot_eotArray and sot_eotArrayMax.
 BitOutputBuffer encodePacket(int ly, int c, int r, int t, CBlkRateDistStats[][] cbs, int[][] tIndx, BitOutputBuffer hbuf, byte[] bbuf, int pIdx)
          Encodes a packet and returns the buffer containing the encoded packet header.
private  int[][] findSubInResLvl(int c, int t)
          Finds the number of subbands in each resolution level according to the decomposition tree for the specified tile and component.
 java.util.Vector getCBlkInPrec(int t, int c, int r, int sbIdx, int precIdx, java.util.Vector cblks)
          Returns the code-blocks contained in the precinct which index is precIdx for the tile 't', the component 'c', the resolution level 'r' and the subband index 'sbIdx'.
 Coord getIncArray(int t, int c, int r)
          Returns the 'incArray' for the specified component, tile and resolution level.
 Coord getIncArrayMax(int t, int c)
          Returns the 'incArrayMax' for the specified component and tile.
 byte[] getLastBodyBuf()
          Returns the buffer of the body of the last encoded packet.
 int getLastBodyLen()
          Returns the length of the body of the last encoded packet, in bytes.
 int[][] getMRL()
          Returns the maximum resolution level for all tile-components.
static java.lang.String[][] getParameterInfo()
          Returns the parameters that are used in this class and implementing classes.
 int getROILen()
          Gives the length to read in current packet body to get all ROI information
 Coord[] getSotEotArray(int t, int c, int r)
          Returns the 'sot_eotArray' for the specified component, tile and resolution level.
 Coord[] getSotEotArrayMax(int t, int c)
          Returns the 'sot_eotArrayMax' for the specified component and tile.
 boolean isPacketWritable()
          Returns true if the current packet is writable i.e.
 boolean isROIinPkt()
          Tells if there was ROI information in the last written packet
 void reset()
          Resets the state of the object to the initial state, as if the object was just created.
 void restore()
          Restores the last saved state of this object.
 void save()
          Saves the current state of this object.
 
Methods inherited from class java.lang.Object
, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait
 

Field Detail

OPT_PREFIX

public static final char OPT_PREFIX
The prefix for packet encoding options: 'P'

pinfo

private static final java.lang.String[][] pinfo
The list of parameters that is accepted for packet encoding.

INIT_LBLOCK

private static final int INIT_LBLOCK
The initial value for the lblock

infoSrc

private CodedCBlkDataSrcEnc infoSrc
The source object

encSpec

EncoderSpecs encSpec
The encoder specs

ttIncl

private TagTreeEncoder[][][][][] ttIncl
The tag tree for inclusion information. The indexes are outlined below. Note that the layer indexes start at 1, therefore, the layer index minus 1 is used. The subband indices are used as they are defined in the Subband class. The tile indices start at 0 and follow a lexicographical order.

ttMaxBP

private TagTreeEncoder[][][][][] ttMaxBP
The tag tree for the maximum significant bit-plane. The indexes are outlined below. Note that the layer indexes start at 1, therefore, the layer index minus 1 is used. The subband indices are used as they are defined in the Subband class. The tile indices start at 0 and follow a lexicographical order.

lblock

private int[][][][][] lblock
The base number of bits for sending code-block length information (referred as Lblock in the JPEG 2000 standard). The indexes are outlined below. Note that the layer indexes start at 1, therefore, the layer index minus 1 is used. The subband indices are used as they are defined in the Subband class. The tile indices start at 0 and follow a lexicographical order.

prevtIdxs

private int[][][][][] prevtIdxs
The last encoded truncation point for each code-block. A negative value means that no information has been included for the block, yet. The indexes are outlined below. The subband indices are used as they are defined in the Subband class. The tile indices start at 0 and follow a lexicographical order. The code-block indices follow a lexicographical order within the subband tile.

What is actually stored is the index of the element in CBlkRateDistStats.truncIdxs that gives the real truncation point.


bak_lblock

private int[][][][][] bak_lblock
The saved base number of bits for sending code-block length information. It is used for restoring previous saved state by restore(). The indexes are outlined below. Note that the layer indexes start at 1, therefore, the layer index minus 1 is used. The subband indices are used as they are defined in the Subband class. The tile indices start at 0 and follow a lexicographical order.

bak_prevtIdxs

private int[][][][][] bak_prevtIdxs
The saved last encoded truncation point for each code-block. It is used for restoring previous saved state by restore(). A negative value means that no information has been included for the block, yet. The indexes are outlined below. The subband indices are used as they are defined in the Subband class. The tile indices start at 0 and follow a lexicographical order. The code-block indices follow a lexicographical order within the subband tile.

lbbuf

private byte[] lbbuf
The body buffer of the last encoded packet

lblen

private int lblen
The body length of the last encoded packet

saved

private boolean saved
The saved state

roiInPkt

private boolean roiInPkt
Whether or not there is ROI information in the last encoded Packet

roiLen

private int roiLen
Length to read in current packet body to get all the ROI information

precArrayI

private PrecCoordInfo[][][][][] precArrayI
Array containing the coordinates, width, height, indexes, ... of the precincts

cbArrayI

private CBlkCoordInfo[][][][][] cbArrayI
Array containing the coordinates, width, height, indexes, ... of the code-blocks

maxNumPrec

private Coord[][][] maxNumPrec
Maximum number of precincts in each resolution level :

incArray

private Coord[][][] incArray
Array containing the increment step

incArrayMax

private Coord[][] incArrayMax
Array containing the maximum increment step

sot_eotArray

private Coord[][][][] sot_eotArray
Array used to store the start/end of tile horizontal and vertical coordinates at each resolution level

sot_eotArrayMax

private Coord[][][] sot_eotArrayMax
Array used to store the start/end of tile horizontal and vertical coordinates at the highest resolution level using the smallest increments

mrl

int[][] mrl
The maximum number of resolution level for each component and each tile

subRange

private int[][][][] subRange
Keeps the first and the last subband index in the associated resolution level for each tile and each component

packetWritable

private boolean packetWritable
Whether or not the current packet is writable

savedSbTree

private SubbandAn[][] savedSbTree
Backup of the subband tree for each tile and component as they are used quite often.
Constructor Detail

PktEncoder

public PktEncoder(CodedCBlkDataSrcEnc infoSrc,
                  EncoderSpecs encSpec,
                  Coord[][][] maxNumPrec,
                  ParameterList pl)
Creates a new packet header encoder, using the information from the 'infoSrc' object. The information used is the number of components, number of tiles, subband decomposition, etc.

Note that this constructor visits all the tiles in the 'infoSrc' object. The 'infoSrc' object is left at the original tile (i.e. the current tile before calling this constructor), but any side effects of visiting the tiles is not reverted.

Parameters:
infoSrc - The source of information to construct the object.
encSpec - The parameters for the encoding
maxNumPrec - Maximum number of precinct in each tile, component and resolution level.
pl - ParameterList instance that holds command line options
Method Detail

encodePacket

public BitOutputBuffer encodePacket(int ly,
                                    int c,
                                    int r,
                                    int t,
                                    CBlkRateDistStats[][] cbs,
                                    int[][] tIndx,
                                    BitOutputBuffer hbuf,
                                    byte[] bbuf,
                                    int pIdx)
Encodes a packet and returns the buffer containing the encoded packet header. The code-blocks appear in a 3D array of CBlkRateDistStats, 'cbs'. The first index is the tile index in lexicographical order, the second index is the subband index (as defined in the Subband class), and the third index is the code-block index (whithin the subband tile) in lexicographical order as well. The indexes of the new truncation points for each code-block are specified by the 3D array of int 'tIndx'. The indices of this array are the same as for cbs. The truncation point indices in 'tIndx' are the indices of the elements of the 'truncIdxs' array, of the CBlkRateDistStats class, that give the real truncation points. If a truncation point index is negative it means that the code-block has not been included in any layer yet. If the truncation point is less than or equal to the highest truncation point used in previous layers then the code-block is not included in the packet. Otherwise, if larger, the code-block is included in the packet. The body of the packet can be obtained with the getLastBodyBuf() and getLastBodyLen() methods.

Layers must be coded in increasing order, in consecutive manner, for each tile, component and resolution level (e.g., layer 1, then layer 2, etc.). For different tile, component and/or resolution level no particular order must be followed.

Parameters:
ly - The layer index (starts at 1).
c - The component index.
r - The resolution level
t - Index of the current tile
cbs - The 3D array of coded code-blocks.
tIndx - The truncation point indices for each code-block.
hbuf - The header buffer. If null a new BitOutputBuffer is created and returned. This buffer is reset before anything is written to it.
bbuf - The body buffer. If null a new one is created. If not large enough a new one is created.
pIdx - The precinct index
Returns:
The buffer containing the packet header.

getLastBodyBuf

public byte[] getLastBodyBuf()
Returns the buffer of the body of the last encoded packet. The length of the body can be retrieved with the getLastBodyLen() method. The length of the array returned by this method may be larger than the actual body length.
Returns:
The buffer of body of the last encoded packet.
Throws:
java.lang.IllegalArgumentException - If no packet has been coded since last reset(), last restore(), or object creation.
See Also:
getLastBodyLen()

getLastBodyLen

public int getLastBodyLen()
Returns the length of the body of the last encoded packet, in bytes. The body itself can be retrieved with the getLastBodyBuf() method.
Returns:
The length of the body of last encoded packet, in bytes.
See Also:
getLastBodyBuf()

save

public void save()
Saves the current state of this object. The last saved state can be restored with the restore() method.
See Also:
restore()

restore

public void restore()
Restores the last saved state of this object. An IllegalArgumentException is thrown if no state has been saved.
See Also:
save()

reset

public void reset()
Resets the state of the object to the initial state, as if the object was just created.

buildIncArrays

private void buildIncArrays(int c,
                            int t)
Creates the arrays incArray and incArrayMax. The first array (incArray) contains the increment step used for each component, each tile and each resolution level. The second one (incArrayMax) contains the smallest increment. This is used when looking for precinct inclusion.
Parameters:
t - the tile index
c - the component index

buildSotEotArrays

private void buildSotEotArrays(int c,
                               int t)
Creates the arrays sot_eotArray and sot_eotArrayMax. The first array (sot_eotArray) contains the start/end of tile coordinates at each resolution level and the second array (sot_eotArrayMax) contains the start/end of tile coordinates for the highest resolution level using the smallest increment step
Parameters:
t - the tile index
c - the component index

buildCblkPrec

private void buildCblkPrec(int t,
                           int c,
                           int resLvl)
Builds the lists containing the ulx, uly, width, height and indexes of the code-blocks and of the precincts for each tile, component, resolution level and subband. First, we compute the projected anchor point for the code-block partition. Then, the array containing the code-blocks coordinates is built. Finally, the array containing the precincts coordinates is built.
Parameters:
t - the tile index
c - the component index
ppx - the precinct partition width
ppy - the precinct partition height
resLvl - The resolution level

getCBlkInPrec

public java.util.Vector getCBlkInPrec(int t,
                                      int c,
                                      int r,
                                      int sbIdx,
                                      int precIdx,
                                      java.util.Vector cblks)
Returns the code-blocks contained in the precinct which index is precIdx for the tile 't', the component 'c', the resolution level 'r' and the subband index 'sbIdx'. The result is returned in a Coord object which is allocated if it is null. The returned object is a Vector object whose first element is a Coord object containing the number of code-blocks in each direction and then, cblks contains all the code-blocks indexes.
Parameters:
t - the tile index
c - the component index
r - the resolution level
sbIdx - the subband index
precIdx - the precinct index
cblks - the Vector object in which to return the code-blocks indexes
Returns:
the code-blocks contained in the precinct as the first Coord object stored in the Vector and then the code-blocks indexes

findSubInResLvl

private int[][] findSubInResLvl(int c,
                                int t)
Finds the number of subbands in each resolution level according to the decomposition tree for the specified tile and component. Since JPEG 2000 part I only supports dyadic decomposition, there is one subbands in resolution level 0 and 3 in each other (numbered from 1 to 3).
Parameters:
c - The component
t - the tile
Returns:
Minimun and maximum subband identifier for each resolution level (First index= resolution level, second index = 0(minimum) or 1(maximum))

getSotEotArray

public Coord[] getSotEotArray(int t,
                              int c,
                              int r)
Returns the 'sot_eotArray' for the specified component, tile and resolution level. This method is used by the rate allocator.
Parameters:
c - The component
t - The tile
r - The resolution level

getSotEotArrayMax

public Coord[] getSotEotArrayMax(int t,
                                 int c)
Returns the 'sot_eotArrayMax' for the specified component and tile. This method is used by the rate allocator.
Parameters:
c - The component
t - The tile

getIncArray

public Coord getIncArray(int t,
                         int c,
                         int r)
Returns the 'incArray' for the specified component, tile and resolution level. This method is used by the rate allocator.
Parameters:
c - The component
t - The tile
r - The resolution level

getIncArrayMax

public Coord getIncArrayMax(int t,
                            int c)
Returns the 'incArrayMax' for the specified component and tile. This method is used by the rate allocator.
Parameters:
c - The component
t - The tile

getMRL

public int[][] getMRL()
Returns the maximum resolution level for all tile-components. This method is used by the rate allocator.

isPacketWritable

public boolean isPacketWritable()
Returns true if the current packet is writable i.e. should be written. Returns false otherwise.

isROIinPkt

public boolean isROIinPkt()
Tells if there was ROI information in the last written packet

getROILen

public int getROILen()
Gives the length to read in current packet body to get all ROI information

getParameterInfo

public static java.lang.String[][] getParameterInfo()
Returns the parameters that are used in this class and implementing classes. It returns a 2D String array. Each of the 1D arrays is for a different option, and they have 3 elements. The first element is the option name, the second one is the synopsis, the third one is a long description of what the parameter is and the fourth is its default value. The synopsis or description may be 'null', in which case it is assumed that there is no synopsis or description of the option, respectively. Null may be returned if no options are supported.
Returns:
the options name, their synopsis and their explanation, or null if no options are supported.