libvisiontransfer  4.1.5
Classes | Public Types | Public Member Functions | List of all members
ImageProtocol Class Reference

A lightweight protocol for transferring image pairs. More...

#include <visiontransfer/imageprotocol.h>

Classes

class  Pimpl
 

Public Types

enum  ProtocolType { PROTOCOL_TCP, PROTOCOL_UDP }
 Supported network protocols. More...
 

Public Member Functions

 ImageProtocol (ProtocolType protType)
 Creates a new instance for decoding / encoding network messages for the given network protocol. More...
 
void setTransferImagePair (const ImagePair &imagePair)
 Sets a new image that will be transfer. More...
 
void setRawTransferData (const ImagePair &metaData, unsigned char *rawData, int firstTileWidth=0, int secondTileWidth=0, int validBytes=0x7FFFFFFF)
 Sets the already pre-formatted image data for the next transfer. More...
 
void setRawValidBytes (int validBytes)
 Updates the number of valid bytes in a partial raw transfer. More...
 
const unsigned char * getTransferMessage (int &length)
 Gets the next network message for the current transfer. More...
 
bool transferComplete ()
 Returns true if the current transfer has been completed. More...
 
void resetTransfer ()
 Aborts the transmission of the current transfer and performs a reset of the internal state. More...
 
bool getReceivedImagePair (ImagePair &imagePair)
 Returns a received image when complete. More...
 
bool getPartiallyReceivedImagePair (ImagePair &imagePair, int &validRows, bool &complete)
 Returns a partially received image. More...
 
bool imagesReceived () const
 Returns true if the images of the current transfer have been received. More...
 
unsigned char * getNextReceiveBuffer (int &maxLength)
 Returns the buffer for receiving the next network message. More...
 
bool processReceivedMessage (int length)
 Handles a received network message. More...
 
void resetReception ()
 Aborts the reception of the current image transfer and resets the internal state. More...
 

Detailed Description

A lightweight protocol for transferring image pairs.

Two images are transferred together as a pair. These are usually the left and right image of a stereo camera, or the left image and a disparity map.

The images are monochrome and can have a bit depth of 8 or 12 bits. For simplicity, the 12-bits are inflated to 16-bit by introducing additional padding. Both images must always have the same image size.

When receiving, the class takes in an image pair and chops it down to several network messages. When sending, the class takes a set of messages and assembles them into an image pair. We have to differentiate between TCP and UDP in both cases.

Definition at line 36 of file imageprotocol.h.

Member Enumeration Documentation

Supported network protocols.

Enumerator
PROTOCOL_TCP 

The connection oriented TCP transport protocol.

PROTOCOL_UDP 

The connection-less UDP transport protocol.

Definition at line 39 of file imageprotocol.h.

Constructor & Destructor Documentation

ImageProtocol::ImageProtocol ( ProtocolType  protType)

Creates a new instance for decoding / encoding network messages for the given network protocol.

Parameters
protTypeThe target network protocol.

Definition at line 165 of file imageprotocol.cpp.

Member Function Documentation

unsigned char * ImageProtocol::getNextReceiveBuffer ( int &  maxLength)

Returns the buffer for receiving the next network message.

Parameters
maxLengthMaximum allowed length for the next network message
Returns
Pointer to the buffer memory.

Definition at line 212 of file imageprotocol.cpp.

bool ImageProtocol::getPartiallyReceivedImagePair ( ImagePair imagePair,
int &  validRows,
bool &  complete 
)

Returns a partially received image.

Parameters
imagePairWill be set to the partially received image pair.
validRowsThe number of valid image rows in the partially received image pair.
completeTrue if the image pair has been fully received.
Returns
Returns true if a full or partial image have been received. Otherwise false.

If a partial image has been received, the meta data returned in imagePair will be complete. The pixel data contained in imagePair, however, will only be valid for the first validRows rows.

After obtaining a complete image pair, reception is reset and subsequent calls to getPartiallyReceivedImagePair() or imagesReceived() will return false.

Please note that the received image data is only valid until processing the first network message of the next image transfer.

Definition at line 203 of file imageprotocol.cpp.

bool ImageProtocol::getReceivedImagePair ( ImagePair imagePair)

Returns a received image when complete.

Parameters
imagePairWill be set to the received image pair.
Returns
Returns true if a new image pair has been received. Otherwise false.

After obtaining a received image pair, reception is reset and subsequent calls to getReceivedImagePair() or imagesReceived() will return false.

Please note that the received image data is only valid until processing the first network message of the next image transfer.

Definition at line 199 of file imageprotocol.cpp.

const unsigned char * ImageProtocol::getTransferMessage ( int &  length)

Gets the next network message for the current transfer.

Parameters
lengthThe length of the network message.
Returns
Pointer to the network message data.

If the transfer has already been completed, a null pointer is returned.

Definition at line 187 of file imageprotocol.cpp.

bool ImageProtocol::imagesReceived ( ) const

Returns true if the images of the current transfer have been received.

Definition at line 208 of file imageprotocol.cpp.

bool ImageProtocol::processReceivedMessage ( int  length)

Handles a received network message.

Parameters
lengthLength of the received network message.
Returns
False if the message could not be parsed. otherwise true.

This method has to be called for every network message that has been received. The message data must be located in the most recent buffer that has been obtained with getNextReceiveBuffer().

After calling this method, please check if a new image has been received by calling getReceivedImagePair() or getPartiallyReceivedImagePair().

Definition at line 216 of file imageprotocol.cpp.

void ImageProtocol::resetReception ( )

Aborts the reception of the current image transfer and resets the internal state.

Definition at line 220 of file imageprotocol.cpp.

void ImageProtocol::resetTransfer ( )

Aborts the transmission of the current transfer and performs a reset of the internal state.

Definition at line 195 of file imageprotocol.cpp.

void ImageProtocol::setRawTransferData ( const ImagePair metaData,
unsigned char *  rawData,
int  firstTileWidth = 0,
int  secondTileWidth = 0,
int  validBytes = 0x7FFFFFFF 
)

Sets the already pre-formatted image data for the next transfer.

Parameters
metaDataImagePair object containing all the meta data but no pixel data.
rawDataPre-formatted data for this transfer.
firstTileWidthIf not 0, specifies the width of the first tile in a tiled transfer.
secondTileWidthIf not 0, specifies the width of the second tile in a tiled transfer.
validBytesThe number of bytes that are valid in rawData.

This method is a more efficient alternative to setTransferImage(). In this case the image data already has to be pre-formatted in the format of the image protocol, which means row-wise interleaving both images. For 12-bit images, the lower 4 bits have to be interleaved separately. This avoids transferring the unused 4 padding bits.

The pixel data contained in metaData is ignored, while all other data is transmitted. The actual pixel data must be encoded in rawData.

Parts of rawData will be overwritten. There must be at least 2 additional allocated bytes after the pixel data in rawData.

If validBytes is set to a value smaller than the total transfer size, only a partial transfer is performed. Subsequent calls to setRawValidBytes() are then necessary.

Definition at line 178 of file imageprotocol.cpp.

void ImageProtocol::setRawValidBytes ( int  validBytes)

Updates the number of valid bytes in a partial raw transfer.

Parameters
validBytesThe number of already valid bytes in the previously set raw data pointer.

This method has to be called whenever new data is available in a raw transfer.

See also
setRawTransferData()

Definition at line 183 of file imageprotocol.cpp.

void ImageProtocol::setTransferImagePair ( const ImagePair imagePair)

Sets a new image that will be transfer.

Parameters
imagePairThe image pair that shall be transmitted.

After setting the transfer image, subsequent calls to getTransferMessage() can be made for obtaining the encoded network messages.

Definition at line 174 of file imageprotocol.cpp.

bool ImageProtocol::transferComplete ( )

Returns true if the current transfer has been completed.

Definition at line 191 of file imageprotocol.cpp.


The documentation for this class was generated from the following files:
Nerian Vision Technologies