|
libvisiontransfer
10.8.0
|
A lightweight protocol for transferring image sets.
Two images are transferred together as a set. These are usually the left and right image of a stereo camera, or the left image and a disparity map.
The images are 8- or 12-bit monochrome, or 8-bit RGB color. For simplicity, 12-bit images are inflated to 16-bit by introducing additional padding bits. Both images must always have the same image size.
When receiving, the class takes in an image set and chops it down to several network messages. When sending, the class takes a set of messages and assembles them into an image set. We have to differentiate between TCP and UDP in both cases.
Definition at line 52 of file imageprotocol.h.
#include <visiontransfer/imageprotocol.h>
Classes | |
| class | Pimpl |
Public Types | |
| enum | ProtocolType { PROTOCOL_TCP, PROTOCOL_UDP } |
| Supported network protocols. More... | |
Public Member Functions | |
| ImageProtocol (bool server, ProtocolType protType, int maxUdpPacketSize=1472) | |
| Creates a new instance for decoding / encoding network messages for the given network protocol. More... | |
| void | setTransferImageSet (const ImageSet &imageSet) |
| Sets a new image that will be transfer. More... | |
| void | setRawTransferData (const ImageSet &metaData, const std::vector< unsigned char * > &imageData, int firstTileWidth=0, int middleTilesWidth=0, int lastTileWidth=0) |
| Sets the already pre-formatted image data for the next transfer. More... | |
| void | setRawValidBytes (const std::vector< 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 | getReceivedImageSet (ImageSet &imageSet) |
| Returns a received image when complete. More... | |
| bool | getPartiallyReceivedImageSet (ImageSet &imageSet, 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... | |
| void | processReceivedMessage (int length) |
| Handles a received network message. More... | |
| int | getNumDroppedFrames () const |
| Returns the number of frames that have been dropped since connecting to the current remote host. More... | |
| void | resetReception () |
| Aborts the reception of the current image transfer and resets the internal state. More... | |
| bool | newClientConnected () |
| Returns true if the last message has established a new connection from a client. More... | |
| bool | isConnected () const |
| Returns true if a remote connection is established. More... | |
| const unsigned char * | getNextControlMessage (int &length) |
| If a control message is pending to be transmitted then the message data will be returned by this method. More... | |
| bool | supportsExtendedConnectionStateProtocol () const |
| Returns true if the server-client handshake indicated that UDP disconnection messages are supported. More... | |
Supported network protocols.
| Enumerator | |
|---|---|
| PROTOCOL_TCP | The connection oriented TCP transport protocol. |
| PROTOCOL_UDP | The connection-less UDP transport protocol. |
Definition at line 67 of file imageprotocol.h.
| visiontransfer::ImageProtocol::ImageProtocol | ( | bool | server, |
| ProtocolType | protType, | ||
| int | maxUdpPacketSize = 1472 |
||
| ) |
Creates a new instance for decoding / encoding network messages for the given network protocol.
| server | If set to true, this object will be a communication server. |
| maxUdpPacketSize | Maximum allowed size of a UDP packet when sending data. |
Definition at line 197 of file imageprotocol.cpp.
| const unsigned char * visiontransfer::ImageProtocol::getNextControlMessage | ( | int & | length | ) |
If a control message is pending to be transmitted then the message data will be returned by this method.
| length | Will be set to the length of the message |
Control messages are only needed when using the UDP network protocol.
Definition at line 264 of file imageprotocol.cpp.
| unsigned char * visiontransfer::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 244 of file imageprotocol.cpp.
| int visiontransfer::ImageProtocol::getNumDroppedFrames | ( | ) | const |
Returns the number of frames that have been dropped since connecting to the current remote host.
Dropped frames are caused by dropped packets due to a poor network connection
Definition at line 252 of file imageprotocol.cpp.
| bool visiontransfer::ImageProtocol::getPartiallyReceivedImageSet | ( | ImageSet & | imageSet, |
| int & | validRows, | ||
| bool & | complete | ||
| ) |
Returns a partially received image.
| imageSet | Will be set to the partially received image set. |
| validRows | The number of valid image rows in the partially received image set. |
| complete | True if the image set has been fully received. |
If a partial image has been received, the meta data returned in imageSet will be complete. The pixel data contained in imageSet, however, will only be valid for the first validRows rows.
After obtaining a complete image set, reception is reset and subsequent calls to getPartiallyReceivedImageSet() 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 235 of file imageprotocol.cpp.
| bool visiontransfer::ImageProtocol::getReceivedImageSet | ( | ImageSet & | imageSet | ) |
Returns a received image when complete.
| imageSet | Will be set to the received image set. |
After obtaining a received image set, reception is reset and subsequent calls to getReceivedImageSet() 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 231 of file imageprotocol.cpp.
| const unsigned char * visiontransfer::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 219 of file imageprotocol.cpp.
| bool visiontransfer::ImageProtocol::imagesReceived | ( | ) | const |
Returns true if the images of the current transfer have been received.
Definition at line 240 of file imageprotocol.cpp.
| bool visiontransfer::ImageProtocol::isConnected | ( | ) | const |
Returns true if a remote connection is established.
Definition at line 260 of file imageprotocol.cpp.
| bool visiontransfer::ImageProtocol::newClientConnected | ( | ) |
Returns true if the last message has established a new connection from a client.
Definition at line 268 of file imageprotocol.cpp.
| void visiontransfer::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 getReceivedImageSet() or getPartiallyReceivedImageSet().
In order to handle connection timeouts this method should be called frequently. If no new data is available, a length of 0 can be passed.
Definition at line 248 of file imageprotocol.cpp.
| void visiontransfer::ImageProtocol::resetReception | ( | ) |
Aborts the reception of the current image transfer and resets the internal state.
Definition at line 256 of file imageprotocol.cpp.
| void visiontransfer::ImageProtocol::resetTransfer | ( | ) |
Aborts the transmission of the current transfer and performs a reset of the internal state.
Definition at line 227 of file imageprotocol.cpp.
| void visiontransfer::ImageProtocol::setRawTransferData | ( | const ImageSet & | metaData, |
| const std::vector< unsigned char * > & | imageData, | ||
| int | firstTileWidth = 0, |
||
| int | middleTilesWidth = 0, |
||
| int | lastTileWidth = 0 |
||
| ) |
Sets the already pre-formatted image data for the next transfer.
| metaData | ImageSet 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. |
| middleTilesWidth | If not 0, specifies the width of the tiles between the first and the last tile in a tiled transfer. |
| lastTileWidth | If not 0, specifies the width of the last 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 pixel data must be packed in LSB order.
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 4 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 210 of file imageprotocol.cpp.
| void visiontransfer::ImageProtocol::setRawValidBytes | ( | const std::vector< 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 215 of file imageprotocol.cpp.
| void visiontransfer::ImageProtocol::setTransferImageSet | ( | const ImageSet & | imageSet | ) |
Sets a new image that will be transfer.
| imageSet | The image set 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 206 of file imageprotocol.cpp.
| bool visiontransfer::ImageProtocol::supportsExtendedConnectionStateProtocol | ( | ) | const |
Returns true if the server-client handshake indicated that UDP disconnection messages are supported.
Definition at line 272 of file imageprotocol.cpp.
| bool visiontransfer::ImageProtocol::transferComplete | ( | ) |
Returns true if the current transfer has been completed.
Definition at line 223 of file imageprotocol.cpp.