StdEntropyCoder (SCIFIO Javadocs 0-SNAPSHOT API)

java.lang.Object
- io.scif.jj2000.j2k.image.ImgDataAdapter
- - io.scif.jj2000.j2k.entropy.encoder.EntropyCoder
  - - io.scif.jj2000.j2k.entropy.encoder.StdEntropyCoder

All Implemented Interfaces:

CodedCBlkDataSrcEnc, StdEntropyCoderOptions, ImgData, ForwWTDataProps
```
public class StdEntropyCoder
extends EntropyCoder
implements StdEntropyCoderOptions
```
This class implements the JPEG 2000 entropy coder, which codes stripes in code-blocks. This entropy coding engine can function in a single-threaded mode where one code-block is encoded at a time, or in a multi-threaded mode where multiple code-blocks are entropy coded in parallel. The interface presented by this class is the same in both modes.
The number of threads used by this entropy coder is specified by the "io.scif.jj2000.j2k.entropy.encoder.StdEntropyCoder.nthreads" Java system property. If set to "0" the single threaded implementation is used. If set to 'n' ('n' larger than 0) then 'n' extra threads are started by this class which are used to encode the code-blocks in parallel (i.e. ideally 'n' code-blocks will be encoded in parallel at a time). On multiprocessor machines under a "native threads" Java Virtual Machine implementation each one of these threads can run on a separate processor speeding up the encoding time. By default the single-threaded implementation is used. The multi-threaded implementation currently assumes that the vast majority of consecutive calls to 'getNextCodeBlock()' will be done on the same component. If this is not the case, the speed-up that can be expected on multiprocessor machines might be significantly decreased.
The code-blocks are rectangular, with dimensions which must be powers of 2. Each dimension has to be no smaller than 4 and no larger than 256. The product of the two dimensions (i.e. area of the code-block) may not exceed 4096.
Context 0 of the MQ-coder is used as the uniform one (uniform, non-adaptive probability distribution). Context 1 is used for RLC coding. Contexts 2-10 are used for zero-coding (ZC), contexts 11-15 are used for sign-coding (SC) and contexts 16-18 are used for magnitude-refinement (MR).
This implementation buffers the symbols and calls the MQ coder only once per stripe and per coding pass, to reduce the method call overhead.
This implementation also provides some timing features. They can be enabled by setting the 'DO_TIMING' constant of this class to true and recompiling. The timing uses the 'System.currentTimeMillis()' Java API call, which returns wall clock time, not the actual CPU time used. The timing results will be printed on the message output. Since the times reported are wall clock times and not CPU usage times they can not be added to find the total used time (i.e. some time might be counted in several places). When timing is disabled ('DO_TIMING' is false) there is no penalty if the compiler performs some basic optimizations. Even if not the penalty should be negligeable.
The source module must implement the CBlkQuantDataSrcEnc interface and code-block's data is received in a CBlkWTData instance. This modules sends code-block's information in a CBlkRateDistStats instance.

See Also:

CBlkQuantDataSrcEnc, CBlkWTData, CBlkRateDistStats

Field Summary

Fields
Modifier and Type	Field and Description
`StringSpec`	`bms` By-pass mode specifications
`StringSpec`	`css` Causal stripes specifications
`static String`	`DEF_THREADS_NUM` The default value for the property in THREADS_PROP_NAME: 0
`StringSpec`	`lcs` The length calculation specifications
`StringSpec`	`mqrs` MQ reset specifications
`StringSpec`	`rts` Regular termination specifications
`StringSpec`	`sss` Error resilience segment symbol use specifications
`static int`	`THREADS_PRIORITY_INC` The increase in priority for the compressor threads, currently 3.
`static String`	`THREADS_PROP_NAME` The Java system property name for the number of threads to use: io.scif.jj2000.j2k.entropy.encoder.StdEntropyCoder.nthreads
`StringSpec`	`tts` The termination type specifications

Fields inherited from class io.scif.jj2000.j2k.entropy.encoder.EntropyCoder
OPT_PREFIX, src

Fields inherited from class io.scif.jj2000.j2k.image.ImgDataAdapter
imgdatasrc, tIdx

Fields inherited from interface io.scif.jj2000.j2k.entropy.StdEntropyCoderOptions
FIRST_BYPASS_PASS_IDX, MAX_CB_AREA, MAX_CB_DIM, MIN_CB_DIM, NUM_EMPTY_PASSES_IN_MS_BP, NUM_NON_BYPASS_MS_BP, NUM_PASSES, OPT_BYPASS, OPT_PRED_TERM, OPT_RESET_MQ, OPT_SEG_SYMBOLS, OPT_TERM_PASS, OPT_VERT_STR_CAUSAL, STRIPE_HEIGHT

Constructor Summary

Constructors
Constructor and Description
`StdEntropyCoder(CBlkQuantDataSrcEnc src, CBlkSizeSpec cblks, PrecinctSizeSpec pss, StringSpec bms, StringSpec mqrs, StringSpec rts, StringSpec css, StringSpec sss, StringSpec lcs, StringSpec tts)` Instantiates a new entropy coder engine, with the specified source of data, nominal block width and height.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`finalize()` Prints the timing information, if collected, and calls 'finalize' on the super class.
`int`	`getCBlkHeight(int t, int c)` Returns the code-block height for the specified tile and component.
`int`	`getCBlkWidth(int t, int c)` Returns the code-block width for the specified tile and component.
`CBlkRateDistStats`	`getNextCodeBlock(int c, CBlkRateDistStats ccb)` Returns the next coded code-block in the current tile for the specified component, as a copy (see below).
`int`	`getPPX(int t, int c, int rl)` Returns the precinct partition width for the specified component, tile and resolution level.
`int`	`getPPY(int t, int c, int rl)` Returns the precinct partition height for the specified component, tile and resolution level.
`void`	`initTileComp(int nt, int nc)` Load options, length calculation type and termination type for each tile-component.
`void`	`nextTile()` Advances to the next tile, in standard scan-line order (by rows then columns).
`boolean`	`precinctPartitionUsed(int c, int t)` Returns true if precinct partition is used for the specified component and tile, returns false otherwise.
`void`	`setTile(int x, int y)` Changes the current tile, given the new indexes.

Methods inherited from class io.scif.jj2000.j2k.entropy.encoder.EntropyCoder
createInstance, getAnSubbandTree, getCbULX, getCbULY, getParameterInfo, isReversible

Methods inherited from class io.scif.jj2000.j2k.image.ImgDataAdapter
getCompImgHeight, getCompImgWidth, getCompSubsX, getCompSubsY, getCompULX, getCompULY, getImgHeight, getImgULX, getImgULY, getImgWidth, getNomRangeBits, getNomTileHeight, getNomTileWidth, getNumComps, getNumTiles, getNumTiles, getTile, getTileCompHeight, getTileCompWidth, getTileHeight, getTileIdx, getTilePartULX, getTilePartULY, getTileWidth

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface io.scif.jj2000.j2k.image.ImgData
getCompImgHeight, getCompImgWidth, getCompSubsX, getCompSubsY, getCompULX, getCompULY, getImgHeight, getImgULX, getImgULY, getImgWidth, getNomRangeBits, getNomTileHeight, getNomTileWidth, getNumComps, getNumTiles, getNumTiles, getTile, getTileCompHeight, getTileCompWidth, getTileHeight, getTileIdx, getTilePartULX, getTilePartULY, getTileWidth

- Field Detail
  - THREADS_PROP_NAME
```
public static final String THREADS_PROP_NAME
```
    The Java system property name for the number of threads to use: io.scif.jj2000.j2k.entropy.encoder.StdEntropyCoder.nthreads
    
    See Also:
    
    Constant Field Values
  - DEF_THREADS_NUM
```
public static final String DEF_THREADS_NUM
```
    The default value for the property in THREADS_PROP_NAME: 0
    
    See Also:
    
    Constant Field Values
  - THREADS_PRIORITY_INC
```
public static final int THREADS_PRIORITY_INC
```
    The increase in priority for the compressor threads, currently 3. The compressor threads will have a priority of THREADS_PRIORITY_INC more than the priority of the thread calling this class constructor. Used only in the multi-threaded implementation.
    
    See Also:
    
    Constant Field Values
  - bms
```
public StringSpec bms
```
    By-pass mode specifications
  - mqrs
```
public StringSpec mqrs
```
    MQ reset specifications
  - rts
```
public StringSpec rts
```
    Regular termination specifications
  - css
```
public StringSpec css
```
    Causal stripes specifications
  - sss
```
public StringSpec sss
```
    Error resilience segment symbol use specifications
  - lcs
```
public StringSpec lcs
```
    The length calculation specifications
  - tts
```
public StringSpec tts
```
    The termination type specifications
- Constructor Detail
  - StdEntropyCoder
```
public StdEntropyCoder(CBlkQuantDataSrcEnc src,
                       CBlkSizeSpec cblks,
                       PrecinctSizeSpec pss,
                       StringSpec bms,
                       StringSpec mqrs,
                       StringSpec rts,
                       StringSpec css,
                       StringSpec sss,
                       StringSpec lcs,
                       StringSpec tts)
```
    Instantiates a new entropy coder engine, with the specified source of data, nominal block width and height.
    If the 'OPT_PRED_TERM' option is given then the MQ termination must be 'TERM_PRED_ER' or an exception is thrown.
    
    Parameters:
    
    src - The source of data
    
    cbks - Code-block size specifications
    
    pss - Precinct partition specifications
    
    bms - By-pass mode specifications
    
    mqrs - MQ-reset specifications
    
    rts - Regular termination specifications
    
    css - Causal stripes specifications
    
    sss - Error resolution segment symbol use specifications
    
    lcs - Length computation specifications
    
    tts - Termination type specifications
    
    See Also:
    
    MQCoder
- Method Detail
  - finalize
```
public void finalize()
              throws Throwable
```
    Prints the timing information, if collected, and calls 'finalize' on the super class.
    
    Overrides:
    
    finalize in class Object
    
    Throws:
    
    Throwable
  - getCBlkWidth
```
public int getCBlkWidth(int t,
                        int c)
```
    Returns the code-block width for the specified tile and component.
    
    Specified by:
    
    getCBlkWidth in class EntropyCoder
    
    Parameters:
    
    t - The tile index
    
    c - the component index
    
    Returns:
    
    The code-block width for the specified tile and component
  - getCBlkHeight
```
public int getCBlkHeight(int t,
                         int c)
```
    Returns the code-block height for the specified tile and component.
    
    Specified by:
    
    getCBlkHeight in class EntropyCoder
    
    Parameters:
    
    t - The tile index
    
    c - The component index
    
    Returns:
    
    The code-block height for the specified tile and component.
  - getNextCodeBlock
```
public CBlkRateDistStats getNextCodeBlock(int c,
                                          CBlkRateDistStats ccb)
```
    Returns the next coded code-block in the current tile for the specified component, as a copy (see below). The order in which code-blocks are returned is not specified. However each code-block is returned only once and all code-blocks will be returned if the method is called 'N' times, where 'N' is the number of code-blocks in the tile. After all the code-blocks have been returned for the current tile calls to this method will return 'null'.
    When changing the current tile (through 'setTile()' or 'nextTile()') this method will always return the first code-block, as if this method was never called before for the new current tile.
    The data returned by this method is always a copy of the internal data of this object, if any, and it can be modified "in place" without any problems after being returned.
    
    Specified by:
    
    getNextCodeBlock in interface CodedCBlkDataSrcEnc
    
    Parameters:
    
    c - The component for which to return the next code-block.
    
    ccb - If non-null this object might be used in returning the coded code-block in this or any subsequent call to this method. If null a new one is created and returned. If the 'data' array of 'cbb' is not null it may be reused to return the compressed data.
    
    Returns:
    
    The next coded code-block in the current tile for component 'n', or null if all code-blocks for the current tile have been returned.
    
    See Also:
    
    CBlkRateDistStats
  - setTile
```
public void setTile(int x,
                    int y)
```
    Changes the current tile, given the new indexes. An IllegalArgumentException is thrown if the indexes do not correspond to a valid tile.
    This default implementation just changes the tile in the source.
    
    Specified by:
    
    setTile in interface ImgData
    
    Overrides:
    
    setTile in class ImgDataAdapter
    
    Parameters:
    
    x - The horizontal index of the tile.
    
    y - The vertical index of the new tile.
  - nextTile
```
public void nextTile()
```
    Advances to the next tile, in standard scan-line order (by rows then columns). An NoNextElementException is thrown if the current tile is the last one (i.e. there is no next tile).
    This default implementation just advances to the next tile in the source.
    
    Specified by:
    
    nextTile in interface ImgData
    
    Overrides:
    
    nextTile in class ImgDataAdapter
  - initTileComp
```
public void initTileComp(int nt,
                         int nc)
```
    Load options, length calculation type and termination type for each tile-component.
    
    Parameters:
    
    nt - The number of tiles
    
    nc - The number of components
  - getPPX
```
public int getPPX(int t,
                  int c,
                  int rl)
```
    Returns the precinct partition width for the specified component, tile and resolution level.
    
    Specified by:
    
    getPPX in interface CodedCBlkDataSrcEnc
    
    Parameters:
    
    t - the tile index
    
    c - the component
    
    rl - the resolution level
    
    Returns:
    
    The precinct partition width for the specified component, tile and resolution level
  - getPPY
```
public int getPPY(int t,
                  int c,
                  int rl)
```
    Returns the precinct partition height for the specified component, tile and resolution level.
    
    Specified by:
    
    getPPY in interface CodedCBlkDataSrcEnc
    
    Parameters:
    
    t - the tile index
    
    c - the component
    
    rl - the resolution level
    
    Returns:
    
    The precinct partition height for the specified component, tile and resolution level
  - precinctPartitionUsed
```
public boolean precinctPartitionUsed(int c,
                                     int t)
```
    Returns true if precinct partition is used for the specified component and tile, returns false otherwise.
    
    Specified by:
    
    precinctPartitionUsed in interface CodedCBlkDataSrcEnc
    
    Parameters:
    
    c - The component
    
    t - The tile
    
    Returns:
    
    True if precinct partition is used for the specified component and tile, returns false otherwise.

Class StdEntropyCoder

Field Summary

Fields inherited from class io.scif.jj2000.j2k.entropy.encoder.EntropyCoder

Fields inherited from class io.scif.jj2000.j2k.image.ImgDataAdapter

Fields inherited from interface io.scif.jj2000.j2k.entropy.StdEntropyCoderOptions

Constructor Summary

Method Summary

Methods inherited from class io.scif.jj2000.j2k.entropy.encoder.EntropyCoder

Methods inherited from class io.scif.jj2000.j2k.image.ImgDataAdapter

Methods inherited from class java.lang.Object

Methods inherited from interface io.scif.jj2000.j2k.image.ImgData

Field Detail

THREADS_PROP_NAME

DEF_THREADS_NUM

THREADS_PRIORITY_INC

bms

mqrs

rts

css

sss

lcs

tts

Constructor Detail

StdEntropyCoder

Method Detail

finalize

getCBlkWidth

getCBlkHeight

getNextCodeBlock

setTile

nextTile

initTileComp

getPPX

getPPY

precinctPartitionUsed