RTV

pybarst.rtv

RTV Channel

The Barst RTV interface. An RTV channel is a interface to a RTV camera sampling device such as the RTV-24. See RTVChannel for details.

Driver requirements

In order to create RTV channels, the RTV WDM drivers must be installed. In particular, the server dynamically loads the AngeloRTV.dll dll from the system path. The server automatically loads the 64 or 32-bit version, depending on whether the server is 32 or 64-bit.

If driver errors arise, either, the driver is not installed, an older version of the driver is installed, or the incorrect 64/32-bit version is installed.

Typical usage

For the RTV channel, typically, the client creates a RTVChannel and then calls RTVChannel.open_channel() on it to create the channel on the server. Once created, no other client can connect to this channel because RTV channels do not support connections to multiple clients.

After creation, the client must call RTVChannel.set_state() to activate the channel. Once activated, the server immediately starts sending data back to the client, and the client should start calling RTVChannel.read() to get the data.

When a client wants to stop getting data, it can call RTVChannel.set_state() to just deactivate the channel, or close_channel_server() to delete the channel from the server altogether. close_channel_client() is not supported, and if it is called, close_channel_server() will have to be called before RTVChannel.open_channel() can be called again.

class pybarst.rtv.RTVChannel(int chan, BarstServer server, video_fmt='full_NTSC', frame_fmt='rgb24', unsigned char brightness=128, unsigned char hue=0, unsigned char u_saturation=127, unsigned char v_saturation=90, unsigned char luma_contrast=124, unsigned char luma_filt=0, int lossless=True, **kwargs)

Bases: pybarst.core.server.BarstChannel

An RTV interface channel.

A RTV channel controls a single RTV port which samples from a single camera.

Parameters:

chan: int

The channel number of the port. The RTV ports are assigned different channel numbers by the RTV driver. By using the proper channel number you can select which RTV channel to sample from.

server: BarstServer

An instance of a server through which this channel is opened.

video_fmt: str

The size of the videos captured. See video_fmt. Defaults to ‘full_NTSC’.

frame_fmt: str

The format of the images captured. See frame_fmt. Defaults to ‘rgb24’.

brightness: unsigned char

The brightness of the images captured. See brightness. Defaults to to 128.

hue: unsigned char

The hue of the captured images. See hue. Defaults to 0.

u_saturation: unsigned char

The chroma (U) of the images captured. See u_saturation. Defaults to 127.

v_saturation: unsigned char

The chroma (V) of the images captured. See v_saturation. Defaults to 90.

luma_contrast: unsigned char

The luma of the images captured. See luma_contrast. Defaults to 124.

luma_filt: unsigned char

Whether the luma notch filter is enabled (black and white, True) or disabled (color, False). See luma_filt. Defaults to 0.

lossless: int

Whether all frames should be sent to the client or if frames should only be sent when no other frames are waiting to be sent. See lossless. Defaults to True.

For example:

>>> # create a channel controlling port 0, returning rgb24 images of size 640x480.
>>> rtv = RTVChannel(chan=0, server=server, video_fmt='full_NTSC', frame_fmt='rgb24', lossless=False)
>>> rtv.open_channel()
>>> print rtv
<pybarst.rtv._rtv.RTVChannel object at 0x05676718>
>>> # print the image and buffer size information
>>> print rtv.width, rtv.height, rtv.bpp, rtv.buffer_size, rtv.width * rtv.height * rtv.bpp
640 480 3 921600 921600
>>> rtv.set_state(True)
>>> # now read the first image
>>> t, data = rtv.read()
>>> # the size of the data should be the same as rtv.buffer_size
>>> print t, len(data)
0.0544582486987 921600

Note

For the RTV channel, the python client currently does not support reading from a channel that is already open on the server. I.e. each channel can only have its state set and read from by a single client at once. An already open error will be raised when trying to open an already existing RTV channel using open_channel().

bpp

bpp: ‘unsigned char’

The average bytes per pixel for the images returned by the server. This is automatically set and is read only.

brightness

brightness: ‘unsigned char’

The brightness of the acquired images.

buffer_size

buffer_size: ‘DWORD’

The size of the buffer, in bytes, required to hold a single image given the current settings. This is automatically set by the server and is read only.

frame_fmt

frame_fmt: object

Selects the image format in which the frames are returned by the driver. Can be one of rgb16 (rgb565le in ffmpeg), gray (gray in ffmpeg), rgb15 (rgb555le in ffmpeg), rgb24 (rgb24 in ffmpeg), rgb32 (rgba in ffmpeg), rgb8, raw8x, or yuy24:2:2. rgb8, raw8x, and yuy24:2:2 are not tested.

height

height: ‘int’

The height of the images returned by the server. This is automatically set and is read only.

hue

hue: ‘unsigned char’

The hue of the acquired images.

lossless

lossless: ‘int’

If this is true, then every frame acquired by the server will be sent to the client. This ensures that no frame is missed. However, if the client doesn’t read them quickly enough, a lot of RAM will be used up quickly due to the space required to hold them in RAM while it’s waiting to be sent to the client.

If it’s false, a frame will only be sent if no other frame is waiting to be sent. So when we queue a frame, as long as the client has not read this frame, no other frame will be queued for sending.

luma_contrast

luma_contrast: ‘unsigned char’

The luma of the acquired images.

luma_filt

luma_filt: ‘unsigned char’

Whether the luma notch filter is enabled (black and white, True) or disabled (color, False).

open_channel(self)

Opens a new channel on the server and connects the client to it. If the channel already exists, a error will be raised.

See open_channel() for more details.

Warning

Since you cannot open an existing channel, once the channel is created to reconnect to the channel you’ll first have to delete it. I.e. if you call close_channel_client() which disconnect the client but leaves the channel on the server, then you won’t be able to call open_channel() again without raising an error. Instead you’ll first have to call close_channel_server() to delete the channel from the server.

read(self)

Reads an images sampled from the camera connected to port controlled by this RTV Channel. Once activated, there server continuously sends back images to the client, which is read with this method.

This method will wait until the server sends data or an error message is raised, thereby tying up this thread. To cancel a read, from another thread you must call close_channel_server(), or just close the the server, which will cause this method to return with an error. A better method to cancel a read is set_state() with flush set to True, and state False. However, that method may raise an exception if the state is not already active.

After set_state() is called to activate the channel, the server will continuously read from the device and send the results back to the client. If lossless is False, the server will only send the most recent image if no image is waiting to be sent.

However, if lossless is True, then the server will continuously send back images to the server, no matter how many are still waiting to be sent. This means that if the client doesn’t call read() frequently enough data will accumulate in the pipe. Also, the data returned might have been acquired before read() was called.

Before this method can be called, open_channel() must be called and the device must be set to active with set_state(). read() will raise an exception if it’s called when inactive.

To stop the server from reading and sending data back to the client, set set_state() to inactive for this channel.

Returns:2-tuple of (time, data). time is the time that the data was read in channel time, clock(). data is a python bytearray containing the raw image data as determined by the video_fmt and frame_fmt settings.

For example, with lossless False:

>>> # do a read
>>> t, data = rtv.read()
>>> print t, len(data)
0.0704396276054 921600
>>> # now stop reading for two seconds
>>> time.sleep(2)
>>> # resume reading. The first few frames will be old data.
>>> print rtv.read()[0]
0.103799921367
>>> print rtv.read()[0]
0.170531751867
>>> print rtv.read()[0]
2.53962433471

Note

When reading with lossless False, if waiting between between reads, the first 1 or 2 images read when resuming reading might be older images from when the reading initially stopped.

Warning

When lossless is True, if the client doesn’t read the images and max_server_size is set (i.e. not -1), then after the size has been exceeded, the server will go into an error state.

set_state(self, int state, flush=False)

See set_state() for details.

Note

When the state is set to active, the RTV server will immediately start sending images back to the client, even before the first call to read(). So a user should start calling read() as soon as this method is called.

u_saturation

u_saturation: ‘unsigned char’

The chroma (U) of the acquired images.

v_saturation

v_saturation: ‘unsigned char’

The chroma (V) of the acquired images.

video_fmt

video_fmt: object

The video format that the RTV driver should use to capture the video. This parameter determines the size of the video being captured. In all cases the frame rate is approximately 30, provided the system has enough resources to process them.

Possible values are: full_NTSC for 640x480, full_PAL for 768x576, CIF_NTSC for 320x240, CIF_PAL for 384x288, QCIF_NTSC for 160x120, and QCIF_PAL for 192x144.

width

width: ‘int’

The width of the images returned by the server. This is automatically set and is read only.