Vicon Shogun supports a simple UDP protocol to broadcast when capture has started. Shogun can also receive these messages, which can be used to trigger a capture remotely.
The port for broadcast and trigger is configurable and defaults to 30.
Note that the packet contents are null terminated.
The XML file contains the following notifications:
The following example shows a Start notification. Note that the broadcast must fit into one UDP packet.
The indents in the following example are for clarity: the actual packet is not indented. White space between tokens is removed.
|The name of the trial, which is used as the filename for the capture files, for example
|Any notes provided
|Any description provided. Avoid very long description strings as the broadcast must fit into one UDP packet. If it does not, the broadcast is not sent.
|The target path for the capture files.
|The number of milliseconds that the broadcast is made before the capture starts. This delay enables clients to do any preparation required to respond.
|A number that individually identifies the packet. It is incremented for each packet generated. Use it to discard duplicate packets that are delivered by UDP. (This can happen if there are multiple paths between the broadcasting and listening machines.)
The following example shows a Stop notification. It is a notification that capturing has stopped.
Note that writing the file to disk may not be complete. Wait for the corresponding Complete notification before trying to open the file.
Possible values for the result are:
- SUCCESS - Everything was ok.
- FAIL - Everything was not ok. Perhaps the disk ran out of room, or the system was unplugged. You may get a truncated file.
- CANCEL - The user stopped the capture process. There will not be a Complete notification.
The following example shows a Complete notification. It indicates that the captured file is ready at the path specified. Note that:
- When capture is complete, buffers have yet to be flushed to disk.
- If the file is on a remote drive, it may be captured locally and then copied to the final location. This may take some time.
Timecode Start notification
The following example shows a Timecode Start notification. It is generated when the system is armed. Note that:
- Capture starts when the system receives the timecode specified.
- Additional notifications may be generated if the start timecode is updated after the system is armed.
TimeCode is represented as a sequence of integers delimited with spaces.
- Sub-Frame (Always zero)
- 0 - Even Field
- 1 - Odd Field
- 0 - PAL
- 1 - NTSC
- 2 - NTSC Drop
- 3 - Film at 24fps
- 4 - NTSC Film
- 5 - 30Hz exactly
- Sub-Frames Per Frame (the multiple of the timecode rate that the system is running at)
Timecode Stop notification
The following example shows a Timecode Stop notification. Note that additional notifications may be generated if the Timecode Stop is updated after the system is armed or possibly even capturing.
The values for
TimeCode are as listed in Timecode start notification.
Duration Stop notification
The packet is generated when the system is armed, or immediately prior to the capture being started.
Duration is the number of frames that will be captured.
The packet may contain extra information describing the frame rate:
PERIODis the number of clock ticks between each frame
TICKSis the number of ticks in each second
The frames per second of the system can be calculated as
TICKS/PERIOD. This representation of the frame rate avoids rounding errors for rates such as NTSC, which cannot be stored in a double without a loss of precision.
<Duration FRAMES="12867" PERIOD="653254" TICKS="135000000" />
The examples are provided in C++ and require the boost library for communications.
- CaptureBroadcastMonitor shows how to monitor for and decode the capture notifications described above.
- RemoteStartStop shows how to package and send the packets to trigger capture start and stop.