Detailed Description

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...

Member Enumeration Documentation

◆ ProtocolType

enum visiontransfer::ImageProtocol::ProtocolType

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.

Constructor & Destructor Documentation

◆ ImageProtocol()

visiontransfer::ImageProtocol::ImageProtocol	(	bool	server,
		ProtocolType	protType,
		int	maxUdpPacketSize = `1472`
	)

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

Parameters

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 195 of file imageprotocol.cpp.

Member Function Documentation

◆ getNextControlMessage()

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.

Parameters

length Will be set to the length of the message

Returns: Pointer to the message data or NULL if no message is pending

Control messages are only needed when using the UDP network protocol.

Definition at line 262 of file imageprotocol.cpp.

◆ getNextReceiveBuffer()

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

Returns the buffer for receiving the next network message.

Parameters

maxLength Maximum allowed length for the next network message

Returns: Pointer to the buffer memory.

Definition at line 242 of file imageprotocol.cpp.

◆ getNumDroppedFrames()

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 250 of file imageprotocol.cpp.

◆ getPartiallyReceivedImageSet()

bool visiontransfer::ImageProtocol::getPartiallyReceivedImageSet	(	ImageSet &	imageSet,
		int &	validRows,
		bool &	complete
	)

Returns a partially received image.

Parameters

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.

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 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 233 of file imageprotocol.cpp.

◆ getReceivedImageSet()

bool visiontransfer::ImageProtocol::getReceivedImageSet ( ImageSet & imageSet )

Returns a received image when complete.

Parameters

imageSet Will be set to the received image set.

Returns: Returns true if a new image set has been received. Otherwise false.

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 229 of file imageprotocol.cpp.

◆ getTransferMessage()

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

Gets the next network message for the current transfer.

Parameters

length The 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 217 of file imageprotocol.cpp.

◆ imagesReceived()

bool visiontransfer::ImageProtocol::imagesReceived ( ) const

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

Definition at line 238 of file imageprotocol.cpp.

◆ isConnected()

bool visiontransfer::ImageProtocol::isConnected ( ) const

Returns true if a remote connection is established.

Definition at line 258 of file imageprotocol.cpp.

◆ newClientConnected()

bool visiontransfer::ImageProtocol::newClientConnected ( )

Returns true if the last message has established a new connection from a client.

Definition at line 266 of file imageprotocol.cpp.

◆ processReceivedMessage()

void visiontransfer::ImageProtocol::processReceivedMessage ( int length )

Handles a received network message.

Parameters

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 246 of file imageprotocol.cpp.

◆ resetReception()

void visiontransfer::ImageProtocol::resetReception ( )

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

Definition at line 254 of file imageprotocol.cpp.

◆ resetTransfer()

void visiontransfer::ImageProtocol::resetTransfer ( )

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

Definition at line 225 of file imageprotocol.cpp.

◆ setRawTransferData()

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.

Parameters

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 208 of file imageprotocol.cpp.

◆ setRawValidBytes()

void visiontransfer::ImageProtocol::setRawValidBytes ( const std::vector< int > & validBytes )

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

Parameters

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.

See also: setRawTransferData()

Definition at line 213 of file imageprotocol.cpp.

◆ setTransferImageSet()

void visiontransfer::ImageProtocol::setTransferImageSet ( const ImageSet & imageSet )

Sets a new image that will be transfer.

Parameters

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 204 of file imageprotocol.cpp.

◆ transferComplete()

bool visiontransfer::ImageProtocol::transferComplete ( )

Returns true if the current transfer has been completed.

Definition at line 221 of file imageprotocol.cpp.

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

visiontransfer/imageprotocol.h
visiontransfer/imageprotocol.cpp

Detailed Description

Classes

Public Types

Public Member Functions

Member Enumeration Documentation

◆ ProtocolType

Constructor & Destructor Documentation

◆ ImageProtocol()

Member Function Documentation

◆ getNextControlMessage()

◆ getNextReceiveBuffer()

◆ getNumDroppedFrames()

◆ getPartiallyReceivedImageSet()

◆ getReceivedImageSet()

◆ getTransferMessage()

◆ imagesReceived()

◆ isConnected()

◆ newClientConnected()

◆ processReceivedMessage()

◆ resetReception()

◆ resetTransfer()

◆ setRawTransferData()

◆ setRawValidBytes()

◆ setTransferImageSet()

◆ transferComplete()