libvisiontransfer
4.1.2
|
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... | |
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.
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.
ImageProtocol::ImageProtocol | ( | ProtocolType | protType | ) |
Creates a new instance for decoding / encoding network messages for the given network protocol.
protType | The target network protocol. |
Definition at line 165 of file imageprotocol.cpp.
unsigned char * ImageProtocol::getNextReceiveBuffer | ( | int & | maxLength | ) |
Returns the buffer for receiving the next network message.
maxLength | Maximum allowed length for the next network message |
Definition at line 212 of file imageprotocol.cpp.
bool ImageProtocol::getPartiallyReceivedImagePair | ( | ImagePair & | imagePair, |
int & | validRows, | ||
bool & | complete | ||
) |
Returns a partially received image.
imagePair | Will be set to the partially received image pair. |
validRows | The number of valid image rows in the partially received image pair. |
complete | True if the image pair has been fully received. |
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.
imagePair | Will be set to the received image pair. |
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.
length | The length of the network message. |
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.
length | Length of the received network message. |
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.
metaData | ImagePair object containing all the meta data but no pixel data. |
rawData | Pre-formatted data for this transfer. |
firstTileWidth | If not 0, specifies the width of the first tile in a tiled transfer. |
secondTileWidth | If not 0, specifies the width of the second tile in a tiled transfer. |
validBytes | The 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.
validBytes | The 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.
Definition at line 183 of file imageprotocol.cpp.
void ImageProtocol::setTransferImagePair | ( | const ImagePair & | imagePair | ) |
Sets a new image that will be transfer.
imagePair | The 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.