CADI.Server.LogicalTarget.JPEG2000.RateDistortion
Class CPIBasedDelivery

java.lang.Object
  CADI.Server.LogicalTarget.JPEG2000.RateDistortion.CPIBasedDelivery

public class CPIBasedDelivery
extends java.lang.Object

This class implements a Coding Passes Interleaving (CPI) -based rate-distortion method. The CPI method has been modified so that when a there is a reference to a coding pass, it means a real coding pass for a specific code-block and it is not a coding pass of the whole image.

Four CPI approaches have been developed:

PACKET PER PRECINCT

This approach delivery the requested window of interest using only one packet per precinct. Therefore, the served image only has one quality layer. See deliverOnePacketPerPrecinct() method.

PACKET PER BIT-PLANE

This approach delivery the requested window of interest building one packet per bit-plane. Therefore, the served served image has as quality layers as number of bit-planes. See deliverOnePacketPerBitPlane() method.

PACKET PER CODING PASS

This approach delivery the requested window of interest building one packet per coding pass. Therefore, the served served image has as quality layers as number of coding passes (3 * bit-planes + 1). See deliverOnePacketPerCodingPass() method.

SCALE

This approach delivery the requested window of interest following the the SCALE rate-distortion method, where the MRP and CP coding passes are joined in the same packet. Therefore, the served served image has ((K * 2) - 1) quality layers (where K = number of bit-planes). See #getResponseScale() method.

Usage example:
construct
runResponseParameters
getResponseViewWindow
getQuality
runResponseData
getJPIPMessageData
getEORReasonCode

Version:

2.0.0 2009/04/13

Author:

Group on Interactive Coding of Images (GICI)

Field Summary

private int[][][][][][][]	codingPassesToSendLengths Length of the coding passes which are included in the requested WOI.
private CODParameters	codParameters Definition in CODParameters
private int[][]	comps
private int	cpiType Indicates which type of CPI will be used to deliver images.
private int	EORReasonCode Definition in ServerLogicalTargetManager.EORReasonCode.
private int[]	fsiz Some internal attributes for passing values between diferents methods.
private HTTPResponseSender	httpResponseSender Definition in Worker.httpResponseSender
private JPCParameters	jpcParameters Definition in JP2LogicalTarget.jpcParameters
private JPIPMessageEncoder	jpipMessageEncoder Definition in JP2LogicalTargetManager.
private java.util.ArrayList<JPIPMessageHeader>	jpipMessageHeaders Definition in ServerLogicalTargetManager.jpipMessageHeaders.
private int	layers
private JP2LogicalTarget	logicalTarget Definition in ServerLogicalTargetManager.EORReasonCode.
private byte[]	mainHeader Contains the encoded main header.
private long	maximumResponseLength Definition in DataLimitField.len
private int	maxNumLayers Definition in CODParameters.numLayers
private int	MSBPlane Definition in JP2LogicalTarget.MSBPlane
private static int	PACKET_PER_BIT_PLANE This CPI tye delivery the image's window of interest by bit planes.
private static int	PACKET_PER_CODING_PASS This CPI type delivery the image's window of interest building a layer for each coding pass.
private static int	PACKET_PER_PRECINCT This CPI tye delivery the image's window of interest building only one packet, i.e., all coding passes of a precinct are grouped in one packet.
private int[][][]	precinctInLayer Indicates the layer in which one the precinct will be included.
private int	quality Definition in ServerLogicalTargetManager.quality.
private long	responseLength It is a temporal attribute to accumulate the response length which is sending to the client.
private ViewWindowField	responseViewWindow Definition in ServerLogicalTargetManager.responseViewWindow.
private int[]	roff
private int[]	rsiz
private static int	SCALE This CPI type delivery the image's window of interest following the SCALE method: l = L - 1 - ((c div 3) * 2)- ((c mod 3) div 2) where: L = (K * 2) - 1 K = number of bit-planes It can be uses when the request belongs to a session or with stateless request.
private JPCServerCache	serverCache This attribute contains the cache data for the client.
private SIZParameters	sizParameters Definition in SIZParameters

Constructor Summary

CPIBasedDelivery(JP2LogicalTarget logicalTarget, JPCServerCache serverCache, long maximumResponseLength)
Constructor.

Method Summary

private void	deliverOnePacketPerBitPlane() This method is used to deliver the requested window of interes using only one packet per bit-plane.
private void	deliverOnePacketPerCodingPass() This method is used to deliver the requested window of interes using only one packet per coding pass.
private void	deliverOnePacketPerPrecinct() This method is used to deliver the requested window of interes using only one packet per precinct.
private void	deliverScale() This method is used to delivery the requested window of interes using SCALE method.
private void	encodeMainHeader() Gets the main header as a byte array.
int	getEORReasonCode() Returns the EORReasonCode attribute.
java.util.ArrayList<JPIPMessageHeader>	getJPIPMessageHeaders() Returns the jpipMessageHeaders attribute.
private int	getLayer(int codingLevel)
byte[]	getMainHeader() Returns the main header.
private int	getMaxSubbandWeight() Deprecated.
private int	getNextCodingLevel(int codingLevel)
private byte[]	getPacketHeaderOnePacketPerBitPlane(PacketHeadersEncoder packetHeading, long inClassIdentifier, int z, int rLevel, int virtualBitPlane, int totalNumVirtualBitPlanes, int[][][][] codingPassesLengths) Builds a packet header using one packet per bit plane It is an auxiliary method used by #getResponseOnePacketPerBitPlane() method to build the packet headers.
private byte[]	getPacketHeaderOnePacketPerCodingPass(PacketHeadersEncoder packetHeadersEncoder, long inClassIdentifier, int z, int rLevel, int codingLevel, int[][][][] codingPassesLengths) Builds a packet header for a specific coding level.
private byte[]	getPacketHeaderScale(PacketHeadersEncoder packetHeading, long inClassIdentifier, int z, int rLevel, int totalNumVirtualCodingLevels, int virtualCodingLevel, int[][][][] codingPassesLengths) Builds a packet header for a specific coding level.
int	getQuality() Returns the quality attribute.
ViewWindowField	getResponseViewWindow() Returns the responseViewWindow attribute.
private int	getSubbandWeight(int z, int rLevel, int subband) Deprecated.
private boolean	isMRP(int codingLevel) Check whether a coding level is or not a MRP pass.
void	list(java.io.PrintStream out) Prints this CPI delivery out to the specified output stream.
private static void	printByteArray(byte[] buffer) Useful method for printing a byte array.
private void	printTypeOfCodingPass(int codingLevel) Useful to print which is the type of each coding level.
void	runResponseData(HTTPResponseSender httpResponseSender, JPIPMessageEncoder jpipMessageEncoder, java.util.ArrayList<JPIPMessageHeader> jpipMessageHeaders) Gets the data of the response window of interes.
void	runResponseParameters(ViewWindowField viewWindow)
void	setCPIType(int cpiType) Set the subtype of the CPI.
private void	setFirstLayerOnePacketPerBitPlane(PacketHeadersEncoder packetHeading, long inClassIdentifier, int z, int rLevel, int[][][][] codingPassesLengths) This method adjusts the first layer when requested window of interest is delivered using one packet per bit plane.
private void	setFirstLayerScale(PacketHeadersEncoder packetHeading, long inClassIdentifier, int z, int rLevel, int[][][][] codingPassesLengths) This method adjusts the first layer when requested window of interest is delivered using the SCALE method.
private boolean	skipPrecinctScale(long inClassIdentifier, int z, int rLevel, int totalNumVirtualCodingLevels, int virtualCodingLevel, int[][][][] codingPassesLengths) Check if a precinct has to be, or not, included in a fixed coding level.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

httpResponseSender

private HTTPResponseSender httpResponseSender

Definition in Worker.httpResponseSender

jpipMessageEncoder

private JPIPMessageEncoder jpipMessageEncoder

Definition in JP2LogicalTargetManager.

jpipMessageHeaders

private java.util.ArrayList<JPIPMessageHeader> jpipMessageHeaders

Definition in ServerLogicalTargetManager.jpipMessageHeaders.

mainHeader

private byte[] mainHeader

Contains the encoded main header.

responseViewWindow

private ViewWindowField responseViewWindow

Definition in ServerLogicalTargetManager.responseViewWindow.

quality

private int quality

Definition in ServerLogicalTargetManager.quality.

EORReasonCode

private int EORReasonCode

Definition in ServerLogicalTargetManager.EORReasonCode.

logicalTarget

private JP2LogicalTarget logicalTarget

Definition in ServerLogicalTargetManager.EORReasonCode.

serverCache

private JPCServerCache serverCache

This attribute contains the cache data for the client.

This reference is passed from the

maximumResponseLength

private long maximumResponseLength

Definition in DataLimitField.len

cpiType

private int cpiType

Indicates which type of CPI will be used to deliver images.

Allowed values:

1- Only one packet for each precinct is generated. Therefore, delivered image has only one quality layer.

2- Creates one packet per each bit plane. Therefore, delivered image has as quality layers as number of bit planes.

3- Creates one packet per each coding pass. Therefore, delivered image has as quality layers as number of coding passes.

4- Images are delivered following the SCALE method.

11- Is based on option 1 but precincts within each resolution level at the same coding pass are sorted.

12- Is based on option 2 but precincts within each resolution level at the same coding pass are sorted.

13- Is based on option 3 but precincts within each resolution level at the same coding pass are sorted.

14- Is based on option 4 but precincts within each resolution level at the same coding pass are sorted.

21- Is based on option 1 but all precincts at the same coding pass are sorted.

22- Is based on option 2 but all precincts at the same coding pass are sorted.

23- Is based on option 3 but all precincts at the same coding pass are sorted.

24- Is based on option 4 but all precincts at the same coding pass are sorted. Note: the sorting of precincts rearranges them in increasing length.

responseLength

private long responseLength

It is a temporal attribute to accumulate the response length which is sending to the client.

jpcParameters

private JPCParameters jpcParameters

Definition in JP2LogicalTarget.jpcParameters

sizParameters

private SIZParameters sizParameters

Definition in SIZParameters

codParameters

private CODParameters codParameters

Definition in CODParameters

MSBPlane

private int MSBPlane

Definition in JP2LogicalTarget.MSBPlane

maxNumLayers

private int maxNumLayers

Definition in CODParameters.numLayers

fsiz

private int[] fsiz

Some internal attributes for passing values between diferents methods. They contains the view window attributes, then for a full description see ViewWindowField

roff

private int[] roff

rsiz

private int[] rsiz

comps

private int[][] comps

layers

private int layers

codingPassesToSendLengths

private int[][][][][][][] codingPassesToSendLengths

Length of the coding passes which are included in the requested WOI.

It is used to pass information between the methods that calculate the WOI using the CPI rate-distortion approach. Indices means:
z: image component
resolutionLevel: 0 is the LL subband, and 1, 2, ... represents next starting with the little one
precinct: precinct in the resolution level
subband: 0 - HL, 1 - LH, 2 - HH (ifresolutionLevel == 0 --> 0 - LL)
yBlock: block row in the subband
xBlock: block column in the subband
codingPass: coding passes included in this layer
See precinctInLayer

precinctInLayer

private int[][][] precinctInLayer

Indicates the layer in which one the precinct will be included.

It is used to pass information between the methods that calculate the WOI using the CPI rate-distortion approach.

Indices means:
z: image component
resolutionLevel: 0 is the LL subband, and 1, 2, ... represents next starting with the little one
precinct: precinct in the resolution level
See codingPassesToSendLengths

PACKET_PER_PRECINCT

private static final int PACKET_PER_PRECINCT

This CPI tye delivery the image's window of interest building only one packet, i.e., all coding passes of a precinct are grouped in one packet.

It can be uses when the request belongs to a session or with stateless request.

See Also:

Constant Field Values

PACKET_PER_BIT_PLANE

private static final int PACKET_PER_BIT_PLANE

This CPI tye delivery the image's window of interest by bit planes.

Builds a packet for each bit-plane. So coding passes of different bit-planes are not grouped in the same packet.

It can be uses when the request belongs to a session or with stateless request.

See Also:

Constant Field Values

PACKET_PER_CODING_PASS

private static final int PACKET_PER_CODING_PASS

This CPI type delivery the image's window of interest building a layer for each coding pass.

It is the worst approach because a packet is built for each coding pass, even when two or more coding passes of the same precinct are sent.

It can be uses when the request belongs to a session or with stateless request.

See Also:

Constant Field Values

SCALE

private static final int SCALE

This CPI type delivery the image's window of interest following the SCALE method: l = L - 1 - ((c div 3) * 2)- ((c mod 3) div 2) where: L = (K * 2) - 1 K = number of bit-planes

It can be uses when the request belongs to a session or with stateless request.

See Also:

Constant Field Values

Constructor Detail

CPIBasedDelivery

public CPIBasedDelivery(JP2LogicalTarget logicalTarget,
                        JPCServerCache serverCache,
                        long maximumResponseLength)

Constructor.

Parameters:

logicalTarget - definition in logicalTarget

serverCache - definition in serverCache

maximumResponseLength - definition in maximumResponseLength

Method Detail

setCPIType

public void setCPIType(int cpiType)

Set the subtype of the CPI.

Parameters:

cpiType - definition in cpiType

runResponseParameters

public void runResponseParameters(ViewWindowField viewWindow)

Parameters:

viewWindow - the requested Window Of Interest

runResponseData

public void runResponseData(HTTPResponseSender httpResponseSender,
                            JPIPMessageEncoder jpipMessageEncoder,
                            java.util.ArrayList<JPIPMessageHeader> jpipMessageHeaders)
                     throws ErrorException,
                            java.io.IOException

Gets the data of the response window of interes. This data is calculate using the CPI algorithm.

Parameters:

httpResponseSender - definition in httpResponseSender

jpipMessageEncoder - definition in jpipMessageEncoder

jpipMessageHeaders - definition in jpipMessageHeaders

Throws:

ErrorException

java.io.IOException

getMainHeader

public byte[] getMainHeader()
                     throws ErrorException

Returns the main header.

Returns:

the mainHeader.

Throws:

ErrorException

getEORReasonCode

public int getEORReasonCode()

Returns the EORReasonCode attribute.

Returns:

the EORReasonCode attribute.

getResponseViewWindow

public ViewWindowField getResponseViewWindow()

Returns the responseViewWindow attribute.

Returns:

the responseViewWindow attribute.

getJPIPMessageHeaders

public java.util.ArrayList<JPIPMessageHeader> getJPIPMessageHeaders()

Returns the jpipMessageHeaders attribute.

Returns:

the jpipMessageHeaders attribute.

getQuality

public int getQuality()

Returns the quality attribute.

Returns:

the quality attribute.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

list

public void list(java.io.PrintStream out)

Prints this CPI delivery out to the specified output stream. This method is useful for debugging.

Parameters:

out - an output stream.

encodeMainHeader

private void encodeMainHeader()
                       throws ErrorException

Gets the main header as a byte array. This method can be called if the transcoding is done.

Throws:

ErrorException

getSubbandWeight

private int getSubbandWeight(int z,
                             int rLevel,
                             int subband)

Deprecated.

Returns the subband weight for a component, resolution level, and subband.

Parameters:

z - image component

rLevel - 0 is the LL subband, and 1, 2, ... represents next starting with the little one

subband - 0 - HL, 1 - LH, 2 - HH (if resolutionLevel == 0 --> 0 - LL)

Returns:

the subband weight for a component, resolution level, and subband.

getMaxSubbandWeight

private int getMaxSubbandWeight()

Deprecated.

Calculate which is the maximum subband weight for the whole image.

Returns:

the maximum subband weight.

See Also:

method.

deliverOnePacketPerPrecinct

private void deliverOnePacketPerPrecinct()
                                  throws ErrorException,
                                         java.io.IOException

This method is used to deliver the requested window of interes using only one packet per precinct. Therefore, the delivered image only has one quality layer.

The algorithm of this rate-distortion method is the most simple. But the coding performance achieved when the image is delivered with this algorithm is not the best one.

The coding performance is improved when delivered data are weigthed applying a weight to each subband of the tansformed image. Further information about suband weights, see the #getRateDistortionAdjustment(int, int, int) method.

Throws:

ErrorException

java.io.IOException

deliverOnePacketPerCodingPass

private void deliverOnePacketPerCodingPass()
                                    throws ErrorException,
                                           java.io.IOException

This method is used to deliver the requested window of interes using only one packet per coding pass. Therefore, the delivered image has as layers as coding levels (3 * most significant bit-plane + 1).

This rate-distortion method is useful to delivery the image when the request does not belong to a session, so the server does not have any information about the client's cache status. In this case, a fixed image structure is needed because, sometimes, the client includes in its request (stateless) information about the status of its cache.

The algorithm of this rate-distortion method is very simple. But the coding performance achieved when the image is delivered with this algorithm is not the best one.

Throws:

ErrorException

java.io.IOException

getPacketHeaderOnePacketPerCodingPass

private byte[] getPacketHeaderOnePacketPerCodingPass(PacketHeadersEncoder packetHeadersEncoder,
                                                     long inClassIdentifier,
                                                     int z,
                                                     int rLevel,
                                                     int codingLevel,
                                                     int[][][][] codingPassesLengths)
                                              throws ErrorException

Builds a packet header for a specific coding level.

It is an auxiliary method used by deliverOnePacketPerCodingPass() method to build the packet headers.

Parameters:

z - the image component

rLevel - the resolution level in the component

precinct - the precinct in the resolution level

codingLevel - the coding level

codingPassesLengths - a multiple array with the length of all coding passes that belong to the same precinct.

Returns:

the packet header.

Throws:

ErrorException - if the packet header cannot be built because an error has been found.

deliverOnePacketPerBitPlane

private void deliverOnePacketPerBitPlane()
                                  throws ErrorException,
                                         java.io.IOException

This method is used to deliver the requested window of interes using only one packet per bit-plane. Therefore, the delivered image has as layers as coding levels (most significant bit-plane + 1).

This rate-distortion method is useful to delivery the image when the request does not belong to a session, so the server does not have any information about the client's cache status. In this case, a fixed image structure is needed because, sometimes, the client includes in its request (stateless) information about the status of its cache.

The algorithm of this rate-distortion method is the very simple. But the coding performance achieved when the image is delivered with this algorithm is not the best one.

Throws:

ErrorException

java.io.IOException

setFirstLayerOnePacketPerBitPlane

private void setFirstLayerOnePacketPerBitPlane(PacketHeadersEncoder packetHeading,
                                               long inClassIdentifier,
                                               int z,
                                               int rLevel,
                                               int[][][][] codingPassesLengths)
                                        throws ErrorException

This method adjusts the first layer when requested window of interest is delivered using one packet per bit plane. The criterion followed to adjust the first layer is: the block(s) belonging to this precinct which has the maximum number of coding passes, its first layer is set to 0. And the

Parameters:

packetHeading -

inClassIdentifier -

z -

rLevel -

int[][][][] - codingPassesLengths

Throws:

ErrorException

getPacketHeaderOnePacketPerBitPlane

private byte[] getPacketHeaderOnePacketPerBitPlane(PacketHeadersEncoder packetHeading,
                                                   long inClassIdentifier,
                                                   int z,
                                                   int rLevel,
                                                   int virtualBitPlane,
                                                   int totalNumVirtualBitPlanes,
                                                   int[][][][] codingPassesLengths)
                                            throws ErrorException

Builds a packet header using one packet per bit plane

It is an auxiliary method used by #getResponseOnePacketPerBitPlane() method to build the packet headers.

Parameters:

packetHeading - the packet heading object used to build the header.

inClassIdentifier -

z - the image component.

rLevel - the resolution level in the component.

virtualBitPlane -

totalNumVirtualBitPlanes -

codingPasses - a multiple array with the length of all coding passes belonging to the precinct.

Returns:

the encoded packet header.

Throws:

ErrorException - if the packet header cannot be built because an error has been found.

deliverScale

private void deliverScale()
                   throws ErrorException,
                          java.io.IOException

This method is used to delivery the requested window of interes using SCALE method. Therefore, the coding passes of the delivered image are allocated in the layers following the SCALE method: l = L - 1 - ((c div 3) * 2) - ((c mod 3) div 2) where: L = (K * 2) - 1 K = number of bit-planes

This rate-distortion method is useful to delivery the image when the request does not belong to a session, so the server does not have any information about the client's cache status. In this case, a fixed image structure is needed because, sometimes, the client includes in its request (stateless) information about the status of its cache.

NOTE: Although the subband weight function is the number of coding passes to be upshifted, this value is mapped to bit planes (multipling by 3) in order to keep the coherence and allow the MRP and CP may be joined.

Throws:

ErrorException

java.io.IOException

getNextCodingLevel

private int getNextCodingLevel(int codingLevel)

Parameters:

codingLevel -

Returns:

getLayer

private int getLayer(int codingLevel)

Parameters:

codingLevel -

Returns:

isMRP

private boolean isMRP(int codingLevel)

Check whether a coding level is or not a MRP pass.

Parameters:

codingLevel -

Returns:

setFirstLayerScale

private void setFirstLayerScale(PacketHeadersEncoder packetHeading,
                                long inClassIdentifier,
                                int z,
                                int rLevel,
                                int[][][][] codingPassesLengths)
                         throws ErrorException

This method adjusts the first layer when requested window of interest is delivered using the SCALE method. The criterion followed to adjust the first layer is: the block(s) belonging to this precinct which has the maximum number of coding passes, its first layer is set to 0......

Parameters:

packetHeading -

inClassIdentifier -

z -

rLevel -

codingPassesLengths -

Throws:

ErrorException

getPacketHeaderScale

private byte[] getPacketHeaderScale(PacketHeadersEncoder packetHeading,
                                    long inClassIdentifier,
                                    int z,
                                    int rLevel,
                                    int totalNumVirtualCodingLevels,
                                    int virtualCodingLevel,
                                    int[][][][] codingPassesLengths)
                             throws ErrorException

Builds a packet header for a specific coding level.

It is an auxiliary method used by #getResponseOnePacketPerCodingPass() method to build the packet headers.

Parameters:

packetHeading - the packet heading object used to build the header.

z - the image component.

rLevel - the resolution level in the component.

precinct - the precinct in the resolution level

initialCodingPass - the first coding pass of the packet.

numOfCodingPasses - the number of coding passes of the packet.

codingPasses - a multiple array with the length of all coding passes belonging to the precinct.

Returns:

the encoded packet header.

Throws:

ErrorException - if the packet header cannot be built because an error has been found.

skipPrecinctScale

private boolean skipPrecinctScale(long inClassIdentifier,
                                  int z,
                                  int rLevel,
                                  int totalNumVirtualCodingLevels,
                                  int virtualCodingLevel,
                                  int[][][][] codingPassesLengths)

Check if a precinct has to be, or not, included in a fixed coding level.

This method is only used by the deliverScale() method.

Parameters:

inClassIdentifier -

z -

rLevel -

totalNumVirtualCodingLevels -

virtualCodingLevel -

codingPassesLengths -

Returns:

printTypeOfCodingPass

private void printTypeOfCodingPass(int codingLevel)

Useful to print which is the type of each coding level. Only for debugging purposes.

Parameters:

codingLevel -

printByteArray

private static void printByteArray(byte[] buffer)

Useful method for printing a byte array. Only for debugging purposes.

Parameters:

buffer - the byte array to be printed.