The following documentation describes the lowest level interface to the Virtual Video Tool, and can be used to create client applications on most platforms and programming languages. Before reading the following documentation, users should review the architecture of the Virtual Video Tool described here. The Camera and PTZ Servers are both based on the Windows Sockets 2 API, and can communicate with any compatible socket library. The following table gives the default port numbers on which users can connect to the servers.

Each connection to the PTZ Server can create a new virtual PTZ controller or connect to an existing controller, and similarly each connection to the Camera Server can create and configure a new virtual camera or stream video from an existing camera. Static cameras do not require a connection to the PTZ Server. Each virtual camera is identified by a unique camID, set by the client using the Set Camera ID command; each virtual PTZ controller is identified by a unique ptzID, set using the Set PTZ ID command. A camera can be directed to follow motion commands from a particular virtual PTZ controller by specifying the corresponding ptzID in a Set Camera Type command (and also setting the PTZ control flag field to a non-zero value). This framework allows for static cameras, multiple independent PTZ cameras, and special configurations such as a stereo PTZ cameras in which multiple cameras share the same PTZ controller.

To connect to either server, clients should create a connection-oriented TCP socket and connect to the appropriate port listed above. The following C code snippet shows how to connect to the camera server on localhost (to connecting over a network, replace 127.0.0.1 with the address of the PC running the mod):

SOCKET sock;
sockaddr_in local;
sock = socket(AF_INET, SOCK_STREAM, 0);
local.sin_family=AF_INET;
local.sin_addr.s_addr = inet_addr("127.0.0.1");
local.sin_port=htons(3166);
connect(sock,(sockaddr*)&local,sizeof(local));

The protocol for sending server commands is identical for both servers, and described in the following notes:

• Each command consists of a single command packet.
• For every command packet, the server sends a single response packet.
• The command and response packets have identical structure: a single command byte, followed by zero or more data bytes, as illustrated below. For a given instruction, the command byte is identical in both the command and response packets but the number of data bytes usually differ.

For example, to set the camera intrinsic parameters to 320x240 pixels, 15 frames/sec and 45 degree FOV (see the Set Intrinsic Parameters command below), a client would send the following byte packet to the camera server (recalling that PCs are little-endian):

{0x05, 0x40, 0x01, 0, 0, 0xf0, 0, 0, 0, 0x0f, 0, 0, 0, 0x2d, 0, 0, 0}

The server would then respond with the following single byte packet:

{0x05}

A typical client application would implement the following sequence of commands:

• Establish a socket connection to the Camera Server and PTZ Server (if active control is required) as outlined above.
• Create a new camera at by sending a Set Camera ID command to the Camera Server and specifying a unique non-zero identifier in the camera ID field. Note that this step is not necessary if you just intend to use one camera, ie. the default camera.
• Retrieve the default camera settings by sending the Get Camera Type, Get Intrinsic Parameters and Get Extrinsic Parameters commands to the Camera Server.
• Make appropriate changes to the default parameters, and send the new parameters to the Camera Server using Set Camera Type, Set Intrinsic Parameters and Set Extrinsic Parameters.
• If active control is required, the Set Camera Type command should set the PTZ control flag to a non-zero value and set PTZ controller ID to the ptzID of an existing controller (eg. the default controller, ptzID = 0).
• In the main processing loop, retrieve the latest rendered frame by sending the Get Latest Frame command to the Camera Server. Active PTZ control commands can be sent to the PTZ server using the Set PTZ Status command.
• Before closing the client application, close the network sockets to disconnect from the servers.

Below is an index of available server commands. The following sections describe the commands in detail, including the command byte, data bytes sent in the command packet and data bytes received in the response.

Camera Server Commands:

• Get Camera ID
• Set Camera ID
• Get Camera Type
• Set Camera Type
• Get Intrinsic Parameters
• Set Intrinsic Parameters
• Get Extrinsic Parameters
• Set Extrinsic Parameters
• Get Latest Frame

PTZ Server Commands:

• Get PTZ ID
• Set PTZ ID
• Get PTZ Status
• Set PTZ Status
• Get Auto Scan
• Set Auto Scan