jj2000.j2k.codestream.writer

Class TagTreeEncoder

java.lang.Object

jj2000.j2k.codestream.writer.TagTreeEncoder

public class TagTreeEncoder
extends Object

This class implements the tag tree encoder. A tag tree codes a 2D matrix of integer elements in an efficient way. The encoding procedure 'encode()' codes information about a value of the matrix, given a threshold. The procedure encodes the sufficient information to identify whether or not the value is greater than or equal to the threshold.

The tag tree saves encoded information to a BitOutputBuffer.

A particular and useful property of tag trees is that it is possible to change a value of the matrix, provided both new and old values of the element are both greater than or equal to the largest threshold which has yet been supplied to the coding procedure 'encode()'. This property can be exploited through the 'setValue()' method.

This class allows saving the state of the tree at any point and restoring it at a later time, by calling save() and restore().

A tag tree can also be reused, or restarted, if one of the reset() methods is called.

The TagTreeDecoder class implements the tag tree decoder.

Tag trees that have one dimension, or both, as 0 are allowed for convenience. Of course no values can be set or coded in such cases.

See Also:

BitOutputBuffer, TagTreeDecoder

Field Summary

Fields

Modifier and Type	Field and Description
protected int	h The vertical dimensions of the base level
protected int	lvls The number of levels in the tag tree
protected boolean	saved The saved state.
protected int[][]	treeS The tag tree state.
protected int[][]	treeSbak The saved tag tree state.
protected int[][]	treeV The tag tree values.
protected int[][]	treeVbak The saved tag tree values.
protected int	w The horizontal dimension of the base level

Constructor Summary

Constructors

Constructor and Description
TagTreeEncoder(int h, int w) Creates a tag tree encoder with 'w' elements along the horizontal dimension and 'h' elements along the vertical direction.
TagTreeEncoder(int h, int w, int[] val) Creates a tag tree encoder with 'w' elements along the horizontal dimension and 'h' elements along the vertical direction.

Method Summary

Methods

Modifier and Type	Method and Description
void	encode(int m, int n, int t, BitOutputBuffer out) Encodes information for the specified element of the tree, given the threshold and sends it to the 'out' stream.
int	getHeight() Returns the number of leafs along the vertical direction.
int	getWidth() Returns the number of leafs along the horizontal direction.
private void	init(int w, int h) Initializes the variables of this class, given the dimensions at the base level (leaf level).
private void	recalcTreeV() Recalculates the values of the elements in the tag tree, in levels 1 and up, based on the values of the leafs (level 0).
void	reset() Resets the tree values and state.
void	reset(int[] val) Resets the tree values and state.
void	restore() Restores the saved values and state of the tree.
void	save() Saves the current values and state of the tree.
void	setValue(int m, int n, int v) Changes the value of a leaf in the tag tree.
void	setValues(int[] val) Sets the values of the leafs to the new set of values and updates the tag tree accordingly.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

w

protected int w

The horizontal dimension of the base level

h

protected int h

The vertical dimensions of the base level

lvls

protected int lvls

The number of levels in the tag tree

treeV

protected int[][] treeV

The tag tree values. The first index is the level, starting at level 0 (leafs). The second index is the element within the level, in lexicographical order.

treeS

protected int[][] treeS

The tag tree state. The first index is the level, starting at level 0 (leafs). The second index is the element within the level, in lexicographical order.

treeVbak

protected int[][] treeVbak

The saved tag tree values. The first index is the level, starting at level 0 (leafs). The second index is the element within the level, in lexicographical order.

treeSbak

protected int[][] treeSbak

The saved tag tree state. The first index is the level, starting at level 0 (leafs). The second index is the element within the level, in lexicographical order.

saved

protected boolean saved

The saved state. If true the values and states of the tree have been saved since the creation or last reset.

Constructor Detail

TagTreeEncoder

public TagTreeEncoder(int h,
              int w)

Creates a tag tree encoder with 'w' elements along the horizontal dimension and 'h' elements along the vertical direction. The total number of elements is thus 'vdim' x 'hdim'.

The values of all elements are initialized to Integer.MAX_VALUE.

Parameters:

h - The number of elements along the horizontal direction.

w - The number of elements along the vertical direction.

TagTreeEncoder

public TagTreeEncoder(int h,
              int w,
              int[] val)

Creates a tag tree encoder with 'w' elements along the horizontal dimension and 'h' elements along the vertical direction. The total number of elements is thus 'vdim' x 'hdim'. The values of the leafs in the tag tree are initialized to the values of the 'val' array.

The values in the 'val' array are supposed to appear in lexicographical order, starting at index 0.

Parameters:

h - The number of elements along the horizontal direction.

w - The number of elements along the vertical direction.

val - The values with which initialize the leafs of the tag tree.

Method Detail

getWidth

public final int getWidth()

Returns the number of leafs along the horizontal direction.

Returns:

The number of leafs along the horizontal direction.

getHeight

public final int getHeight()

Returns the number of leafs along the vertical direction.

Returns:

The number of leafs along the vertical direction.

init

private void init(int w,
        int h)

Initializes the variables of this class, given the dimensions at the base level (leaf level). All the state ('treeS' array) and values ('treeV' array) are intialized to 0. This method is called by the constructors.

Parameters:

w - The number of elements along the vertical direction.

h - The number of elements along the horizontal direction.

recalcTreeV

private void recalcTreeV()

Recalculates the values of the elements in the tag tree, in levels 1 and up, based on the values of the leafs (level 0).

setValue

public void setValue(int m,
            int n,
            int v)

Changes the value of a leaf in the tag tree. The new and old values of the element must be not smaller than the largest threshold which has yet been supplied to 'encode()'.

Parameters:

m - The vertical index of the element.

n - The horizontal index of the element.

v - The new value of the element.

setValues

public void setValues(int[] val)

Sets the values of the leafs to the new set of values and updates the tag tree accordingly. No leaf can change its value if either the new or old value is smaller than largest threshold which has yet been supplied to 'encode()'. However such a leaf can keep its old value (i.e. new and old value must be identical.

This method is more efficient than the setValue() method if a large proportion of the leafs change their value. Note that for leafs which don't have their value defined yet the value should be Integer.MAX_VALUE (which is the default initialization value).

Parameters:

val - The new values for the leafs, in lexicographical order.

See Also:

setValue(int, int, int)

encode

public void encode(int m,
          int n,
          int t,
          BitOutputBuffer out)

Encodes information for the specified element of the tree, given the threshold and sends it to the 'out' stream. The information that is coded is whether or not the value of the element is greater than or equal to the value of the threshold.

Parameters:

m - The vertical index of the element.

n - The horizontal index of the element.

t - The threshold to use for encoding. It must be non-negative.

out - The stream where to write the coded information.

save

public void save()

Saves the current values and state of the tree. Calling restore() restores the tag tree the saved state.

See Also:

restore()

restore

public void restore()

Restores the saved values and state of the tree. An IllegalArgumentException is thrown if the tree values and state have not been saved yet.

See Also:

save()

reset

public void reset()

Resets the tree values and state. All the values are set to Integer.MAX_VALUE and the states to 0.

reset

public void reset(int[] val)

Resets the tree values and state. The values are set to the values in 'val'. The states are all set to 0.

Parameters:

val - The new values for the leafs, in lexicographical order.