Synchronization output GPO configuration files
- Gisela Roberts
- Ben Stanley
A General Purpose Output (GPO) configuration file specifies the characteristics of a synchronization signal to be output from the Sync Outputs sockets on the rear panel of the Vicon Lock unit.
In your Vicon application software, you specify the GPO configuration file that you want to use:
- Supplied GPO file
The GPO files supplied with your Vicon application software specify the relationship of the frame rate of a connected device with that of Vicon optical cameras. For details, see Supplied synchronization configuration (GPO) files.
- Custom GPO file
You can write a GPO file to specify the type of signal to have the Vicon Lock unit produce when a specified Vicon system event occurs. For details, see Custom synchronization (GPO) files.
Your connected device can then perform the action it is defined to do on receipt of that type of signal (for details, see the documentation supplied with your device)
For details on specifying a GPO file, see your Vicon software documentation.
Supplied synchronization configuration (GPO) files
Some synchronization configuration files may be supplied with your Vicon application software. For example, the GPO files supplied with Vicon Nexus are used to synchronize the frame rates of connected reference video cameras to the frame rate used by the Vicon system as shown in the following tables. For details on the installation location of these files, see your Vicon Nexus documentation.
Duration signals
| Synchronization configuration file | Description |
|---|---|
| Duration.gpo | On a StartCapture event, the synchronization output latches high for the duration of the capture. On a StopCapture event, the output latches low. Further details: StartEvent section and StopEvent section. This GPO file is used to synchronize supported third-party devices connected to your Vicon system. |
| SyncDuration.gpo | On an MXDVStart event the synchronization output latches high until an MXDVStop event is received. Further details: StartEvent section and StopEvent section. This GPO file is for use with ZeroWire Digital devices. |
Repeating signals
| Synchronization configuration file | Description |
|---|---|
| DV_Double.gpo | On an MXDVStart event produces two high and two low pulses for each Vicon frame. The pulse period is one-half of a Vicon frame, and the pulse width is one-quarter of a Vicon frame. Further details: StartEvent section and PulsePeriod section. This GPO file is used to align reference video cameras with Vicon optical cameras at twice the Vicon system frame rate. |
| DV_Half.gpo | On an MXDVStart event sends a high pulse followed by a low pulse on every other Vicon frame. The pulse period is two Vicon frames, and the pulse width is one Vicon frame. Further details: StartEvent section and PulsePeriod section. This GPO file is used to align reference video cameras with Vicon optical cameras at half the Vicon system frame rate. |
| DV_Normal.gpo | On an MXDVStart event sends a high pulse followed by a low pulse within every Vicon frame. The pulse period is one Vicon frame, and the pulse width is one-half of a Vicon frame. Further details: StartEvent section and PulsePeriod section. This GPO file is used to synchronize reference video cameras to the Vicon system at the same frequency as the Vicon optical cameras. |
| DV_Quarter.gpo | On an MXDVStart event sends a high pulse followed by a low pulse on every fourth Vicon optical camera system frame. The pulse period is four Vicon frames, and the pulse width is two Vicon frames. Further details: StartEvent section and PulsePeriod section. This GPO file is used to align reference video cameras with Vicon optical cameras at one-quarter of the Vicon system frame rate. |
Custom synchronization (GPO) files
You can write your own GPO file to specify the type of synchronization signal to be output from the Sync Output sockets for a specified Vicon system event.
The following sections illustrate the two types of synchronization signals that can be output and show how you can specify each in a GPO file:
- Custom GPO file for a fixed duration synchronization signal
- Custom GPO file for a repeating synchronization signal
The examples use wave form diagrams to illustrate the signal characteristics and provide cross-references to the relevant GPO file syntax sections.
Custom GPO file for a fixed duration synchronization signal
The following diagram illustrates the characteristics of a fixed duration synchronization signal and a custom GPO file that would generate this signal.
Note that timing offsets are taken from the frame boundaries (indicated by green (4) and red (7) lines) and are measured in 27MHz increments (ticks).
where:
| 1 | are lines of code required to maintain full XML conformity for starting and ending a program. Further details: XML header and AllPrograms section. |
| 2 | are lines of code required to maintain full XML conformity. Note that Vicon software uses the GPO filename rather this program name. In this example, the Program Name is Example_1. Further details: Program Name section. |
| 3 | specifies the type of synchronization signal the GPO is to produce. In this example, it is a signal with a defined start and stop rather than a repeating signal. Further details: Type section. |
| 4 | is the system event that has been defined to start the GPO program.In this example, it sets the signal to be active referenced to the start of capture. Further details: StartEvent section. |
| 5 | is the amount of time to wait after the start event has occurred before sending the signal to its specified polarity. In this example, it sets the delay of signal activation to two frames after the start of capture. Further details: StartOffset section. |
| 6 | is the direction the synchronization signal moves when started. In this example, it sets the signal to start low, go high on activation, and then reset low on completion. Further details: Polarity section. |
| 7 | is the event that has been defined to end the GPO program. In this example, it sets the signal to stop being active referenced to the end of capture. Further details: StopEvent section. |
| 8 | is the stop offset to be applied in the GPO file. In this example, it resets the signal 2 milliseconds (2000 microseconds) after the end of capture. Further details: StopOffset section. |
| 9 | are the length and frequency of the signal to be produced. In this example, they are set to 0 (zero) as they are not required for duration signals. Further details: PulseWidth section and PulsePeriod section. |
Custom GPO file for a repeating synchronization signal
The following diagram illustrates a custom GPO file that sends a repetitive signal from the time the system becomes synchronized after boot up. The signal is not locked to the video frame rate but to time and is, therefore, described as asynchronous. For examples of synchronous signals refer to the supplied GPO files (DV_*.gpo). Further details: Supplied synchronization configuration (GPO) files.
The repeating synchronization signal GPO file described here will be active until the system reboots or is resynchronized. After resynchronization, the GPO will restart in the same way it does after system boot.
Note that timing offsets are taken from the frame boundaries (indicated by green (4) and red (7) lines) and are measured in 27MHz increments (ticks).
where:
| 1 | are lines of code required to maintain full XML conformity for starting and ending a program. Further details: XML header and AllPrograms section. |
| 2 | are lines of code required to maintain full XML conformity. Note that Vicon software uses the GPO filename rather this program name. In this example, the Program Name is Repeat 750mS. Further details: Program Name section. |
| 3 | specifies the type of synchronization signal the GPO is to produce. In this example, it is a repeating signal that will be active as long as the system is running and is not booting up, resynchronizing, or shutting down, rather than a duration signal. Further details: Type section. |
| 4 | is the system event based on which you want to start the GPO program. In this example, the signal is set to start as soon as the system has finished synchronizing after it has booted up. Further details: StartEvent section. |
| 5 | is the amount of time to wait after the start event has occurred before sending the signal to its specified polarity. In this example, it sets the delay of signal activation to 50 milliseconds (50000 microseconds) after the start event. Further details: StartOffset section. |
| 6 | is the direction the synchronization signal moves when started. In this example, it sets it to start low and go high when active. Further details: Polarity section. |
| 7 | is the event that has been defined to end the GPO program. In this example, it's set to the system suspending dataflow pending either a resynchronization being performed or a software shutdown. Further details: StopEvent section. |
| 8 | is the stop offset to be applied in the GPO file. In this example, it sets the stop offset to zero. Further details: StopOffset section. |
| 9 | is the width of the active part of the signal. In this example, it sets it to 0.25 seconds (250000 microseconds). Further details: PulseWidth section. |
| 10 | is the period between two pulse signals. In this example, it sets the cycle period of the signal to 0.75 seconds (750000 microseconds). The ratio of 0.75 to 0.25 means that the rectangular waveform produced has a 3:1 (33 1/3%) mark-space ratio. Also, by defining the cycle period in seconds instead of frames, the signal is asynchronous with respect to system frequency. Further details: PulsePeriod section. |
Synchronization configuration (GPO) file format
General Purpose Output (GPO) configuration files are written in eXtensible Markup Language (XML) file format. These XML files are used to store structured information and to enclose or encapsulate information so that it can be passed between different computing systems. As in any XML file, GPO file sections are delimited with start and end section tags, and subsections are nested beneath main sections to reflect their hierarchical relationship, for example:
<XML header> <SectionStart> <SubsectionStart ATTRIBUTE="value"> <Keyword>Value</Keyword> <Keyword ATTRIBUTE="value"/> </SubsectionEnd> </SectionEnd>
The GPO file can be viewed in most Web browsers or standard text editors like any other XML file. You may find it helpful to view the examples in Custom synchronization (GPO) files or one of the sample GPO files provided with your Vicon application software while you read this description of the general format and content of a GPO file. You are assumed to have a basic understanding of the use and presentation of XML files.
Synchronization configuration (GPO) file structure
The full structure of a GPO file is outlined below:
<?xml version="1.0" standalone="yes"?> <AllPrograms> <Program Name="gpo_name"> <Type>signal_type</Type> <Polarity>signal_direction</Polarity> <StartEvent>gpo_start</StartEvent> <StopEvent>gpo_stop</StopEvent> <StartOffset Frames="" MicroSeconds=""/> <StopOffset Frames="" MicroSeconds=""/> <PulseWidth Frames="" MicroSeconds=""/> <PulsePeriod Frames="" MicroSeconds="" Ticks=""/> </Program> </AllPrograms>
XML header
The header <?xml version="1.0" standalone="yes"?> is essential for the file to be recognized as XML format by Vicon applications and other XML file viewing packages. You must include this section at the top of your GPO file.
AllPrograms section
The program start and end section tags <AllPrograms> and </AllPrograms> delimit the details of the synchronization signal to be sent. Include the start section straight after the XML header and the end section at the end of your GPO file.
Each option in a given section within the <AllPrograms> section consists of a keyword and a single value or one or more ATTRIBUTE="value" pairs, which are written in the following ways in an XML file:
<Keyword>value</Keyword>
<Keyword ATTRIBUTE="value"/>
The Keyword identifies the element with which the Vicon application is concerned, the ATTRIBUTE is a characteristic of the specified keyword, and the value is the data that the Vicon application is to use. For most options, you must specify the value required for your specific implementation of the GPO file. To help you understand how to construct these definitions in your GPO file, when giving the syntax for a section, the following information includes the Keyword and any ATTRIBUTE words, and describes the type of data you must supply for the value.
Program Name section
The syntax for the Program Name section is:
<Program Name="gpo_name">
where:
gpo_name
|
is the name for your GPO program. Tip: The base of the GPO file name is used as the program display name in your Vicon application software. Therefore, Vicon recommends that you use the file name base as the GPO program name.
For example, the sample GPO program Duration.gpo, has the display name Duration in the Vicon application software. |
Type section
The syntax for the Type section is:
<Type>signal_type</Type>
where:
signal_type
|
specifies the type of synchronization signal the ViconLock unit is to produce, one of: | |
|
|
Duration
|
A single signal that lasts from a given start event until a given stop event. |
|
|
Repeating
|
A repetitive pulse signal that begins on a given start event and ends on a given stop event. |
|
|
Start
|
A type of duration signal that occurs on a given start event; no signal occurs on a given stop event. |
|
|
StartStop
|
A type of duration signal that occurs on a given start event and then again on a given stop event. |
|
|
Stop
|
A type of duration signal that occurs on a given stop event; no signal occurs on a start event. |
Polarity section
The syntax for the Polarity section is:
<Polarity>signal_direction</Polarity>
where:
signal_direction
|
specifies the direction the synchronization signal is to start and then move when the GPO file is activated: | |
|
|
High
|
Starts low (0V) and moves high (5V). For a duration signal type, the signal latches high until the start event occurs, whereupon the signal starts with a positive-going edge. When the stop event occurs, the signal is latched low. Further details: StartEvent section and StopEvent section. For a repeating signal type, the signal starts its repetitive cycle in this direction. |
|
|
Low
|
Starts high (5V) and moves low (0V). For a duration signal type, the signal latches low until the start event occurs, when the signal starts with a negative-going edge. When the stop event occurs, the signal is latched low. Further details: StartEvent section and StopEvent section. For a repeating signal type, the signal starts its repetitive cycle in this direction. |
StartEvent section
The syntax for the StartEvent section is:
<StartEvent>gpo_start</StartEvent>
where:
gpo_start
|
specifies the Vicon system event that activates the GPO file: | |
|
|
StartCapture
|
The Start Capture event. |
|
|
MXDVStart
|
The Start System event. |
|
|
Further details: System events and synchronization output signals.
Important: The StartCapture event type does not synchronize reference video cameras or the ZeroWire EMG system. Use the MXDVStart event to synchronize such external devices. |
|
StopEvent section
The syntax for this StopEvent section is:
<StopEvent>gpo_stop</StopEvent>
where:
gpo_stop
|
specifies the Vicon system event that stops the GPO file: | |
|
|
StopCapture
|
The Stop Capture event. |
|
|
MXDVStop
|
The Stop System event |
|
|
Further details: System events and synchronization output signals. | |
StartOffset section
The syntax for the StartOffset section is:
<StartOffset Frames="" MicroSeconds=""/>
where:
StartOffset
|
specifies how long to wait after the start event (StartEvent section) has occurred before sending the signal to its desired polarity: | |
|
|
Frames
|
A specified number of frames. |
|
|
MicroSeconds
|
A specified number of microseconds |
|
|
Important: If you specify both Frames and MicroSeconds, the two values are added together to determine the offset.
The maximum time-based offset you can define is 65 milliseconds (16 bits times microseconds). Frame-based offsets are unlimited. |
|
StopOffset section
The syntax for the StopOffset section is:
<StopOffset Frames="" MicroSeconds=""/>
where:
StopOffset
|
specifies how long to wait after the stop event (StopEvent section) has occurred before sending the signal to its desired polarity: | |
|
|
Frames
|
A specified number of frames |
|
|
MicroSeconds
|
A specified number of microseconds. |
|
|
Important: If you specify both Frames and MicroSeconds, the two values are added together to determine the offset. The maximum time-based offset you can define is 65 milliseconds (16 bits times microseconds). Frame-based offsets are unlimited. |
|
PulseWidth section
The syntax for the PulseWidth section is:
<PulseWidth Frames="" MicroSeconds=""/>
where:
PulseWidth
|
specifies the fixed duration of the pulse for a repeating synchronization signal as either one or the sum of both the following: | |
|
|
Frames
|
The number of frames the pulse signal is to last. |
|
|
MicroSeconds
|
The number of microseconds the pulse signal is to last. |
|
|
Important: If you specify both Frames and MicroSeconds, the two values are added together to determine the pulse width; however, you are recommended to use either Frames and MicroSeconds rather than adding these values. We recommend that you avoid specifying values greater than 65 ms. When you specify values up to 65 ms, the value determines the pulse width to an accuracy of 1 ms. If you specify a value greater than 65, the GPO ceases to be controlled from the hardware and and is instead controlled by the software, which acts on a frame-by-frame basis only. The automatically generated values that determine the GPO rising and falling edges are always multiples of the frame period and remain aligned with the frame boundaries.The offset continues to be handled as before, but in whole frames only. For example, if you specified an offset of 55000 us and the frame rate was 50 fps, the offset used would be two frame periods: one frame period is 20 ms, so 55 ms is 2.75 frame periods, and the number is always rounded down. |
|
Note
If you define a repeating GPO signal to have a pulse period of 1 and a pulse width of 0.5 seconds, and set the system frame rate to 240 fps, the signal from the sync output of a Lock Lab is actually 1.0042 Hz, rather than 1 Hz.
To correct this, in the referenced GPO, set the frame period to be 241.
PulsePeriod section
The syntax for the PulsePeriod section is:
<PulsePeriod Frames="" MicroSeconds="" Ticks=""/>
where:
PulsePeriod
|
specifies the total period of the pulse for a repeating synchronization signal, that is, the time from one rising edge to the next rising edge, as either one or the sum of two or more of the following values converted to 27Mhz: | |
|
|
Frames
|
The number of frames after which the pulse is to be repeated. |
|
|
MicroSeconds
|
The number of microseconds after which the pulse is to be repeated. |
|
|
Ticks
|
The number of 27Mhz clock ticks of the timing reference after which the pulse is to be repeated. |
|
|
Important: If you specify Frames, MicroSeconds, and Ticks, all values are added together to determine the offset; however, you are recommended to add either MicroSeconds or Ticks to frames rather than adding all three values. We recommend that you avoid specifying values greater than 65 ms. When you specify values up to 65 ms, the value determines the pulse period to an accuracy of 1 ms. If you specify a value greater than 65, the GPO ceases to be controlled from the hardware and and is instead controlled by the software, which acts on a frame-by-frame basis only. The automatically generated values that determine the GPO rising and falling edges are always multiples of the frame period and remain aligned with the frame boundaries.The offset continues to be handled as before, but in whole frames only. For example, if you specified an offset of 55000 us and the frame rate was 50 fps, the offset used would be two frame periods: one frame period is 20 ms, so 55 ms is 2.75 frame periods, and the number is always rounded down. |
|
Note
If you define a repeating GPO signal to have a pulse period of 1 and a pulse width of 0.5 seconds, and set the system frame rate to 240 fps, the signal from the sync output of a Lock Lab is actually 1.0042 Hz, rather than 1 Hz.
To correct this, in the referenced GPO, set the frame period to be 241.
