AVINE Video System
TINE Property Interface of SGP
Any SGP component provides 5 TINE devices: 'Server', 'Source', 'ImageAdjustments', 'Output' and 'SSC'. In the
following, any property below these 5 devices is described in detail. Layer-type servers contain similar devices
'Server', 'Source'. Property layouy may be different, though. But in general the property layout for these
devices is comparable across SGP and Layer-type of component.
Table of Contents
- Property Interface of TINE-device named
Property Interface of TINE-device 'Server'
| TINE Property |
In/Out |
Data Types |
Description |
Special Error codes |
| AliveSince |
out |
1 NAME64 (any string)1 |
string showing last startup date and time of SGP |
|
| LastSwitchResult |
out |
300 TEXT (any string)1, also accepts INT32 |
human readable string showing result of last switching from current to new image source OR
general meaning of string encoded into an integer
| Integer Code |
String3 |
| 0 |
switching of input is currently ongoing |
| 1 |
switching of input successfully completed |
| -1 |
switching of input failed |
| -2 |
switching of input failed but server will keep running, because it's configured to do so |
|
|
| LastSwitchTime |
out |
1 NAME64 (any string)1 |
human readable string showing the timestamp when last switching attempt occured |
|
| Layers |
out |
n NAME64 |
returns array of strings showing names of all layers which can be connected to this SGP, needs syslist.xml file.
If the TINE client asks for less than N elements, as much elements as the client asks for are returned. |
526: error looking up Layers |
| Name |
out |
1 NAME64 (any string)1 |
returns name of SGP instance |
|
| ReloadCameraportsXML |
in/out |
in: 1 INT32, out: 1 INT32 (also possible: any string)1 |
if the correct magic number2 is passed as input, the cameraports.xml file is tried to be
reloaded. This avoids unnecessary step of stopping server if something was changed at cameraports.xml file.
Changes to cameraports.xml will be automatically put into effect. In case of non successful return, old
cameraports.xml that was already loaded to memory of SGP server will be continued to use.
| Integer Code |
String |
| 0 |
Reloading successfully finished. |
| 1 |
Error on loading cameraports.xml. See Logfile. |
| 2 |
Error on validation of cameraports.xml. See Logfile. |
| 515: error: wrong bad magic passed |
| Sources |
out |
n NAME64I or n NAME64 |
returns array of strings showing names of all image sources (Name and ID as NAME64I or
just Name as NAME64 data type) which can be connected to this SGP, needs syslist.xml file.
If the TINE client asks for less than N elements, as much elements as the client asks for are returned. |
526: error looking up image sources |
| SourcesType |
out |
NAME64 (any string)1 or INT32 |
returns which type the input source is
| Code |
String |
| 0 |
ImageSource |
| 1 |
InputSource |
For SGP-type of component, input source is always 0/'ImageSource'. For Layer-type of component,
input source is always 1/'InputSource'.
|
|
| Status |
out |
INT32 or any string1 |
returns code or string in which condition the server is currently
| Integer Code |
Recommended Colour for Code |
String |
| 0 |
Red |
Reinitialization failed. |
| 1 |
Green |
Everything is fine. |
| 2 |
Green/Yellow |
Some internal warning. |
| 3 |
Blue |
Currently no image source connected. |
| 4 |
Orange |
Camera temporarily disconnected. |
| 5 |
Yellow |
Many warnings happened |
|
|
| Type |
out |
1 NAME64 (any string)1 or INT32 |
returns code or string in which type of SGP this is
| Integer Code |
String |
| 1 |
PCVision (deprecated) |
| 2 |
ProsilicaGigE |
| 3 |
NI_IMAQ_PCI (deprecated) |
| 4 |
DirectShow |
| 5 |
AnimationPlayback |
| 6 |
JaiPulnixGigE |
| 7 |
LabVIEWToVSv3 (deprecated) |
| 8 |
pleora-ebus |
|
|
| Version |
out |
1 NAME64 (any string)1 |
string showing type, version no and build date of server binary, e.g. "SGP PCVision 0.9 beta (b230(Release) - Jun 24, 2011)" |
|
Footnotes:
|
1
|
possible are data types CF_TEXT, CF_NAME8, CF_NAME16, CF_NAME32, CF_NAME48, CF_NAME64,
longer text may be cutted automatically to fit datatype constraints |
|
2
|
the magic is INT32 1 |
|
3
|
the returned string does not exactly look like this |
Property Interface of TINE-device 'Source'
| TINE Property |
In/Out |
Data Types |
Description |
Special Error codes |
| AvailableSince |
out |
1 NAME64 (any string)1 |
returns a human readable string since when the current image source is already connected to this
server. e.g. 'available since 16.08.2011 11:56:50' |
|
| FrameRate |
out |
1 FLOAT or DOUBLE |
shows the current number of frames per second the server is detecting, average value based on
number of frames that were received from input device in the last 5 seconds |
|
| ID |
out |
1 INT32 |
shows the unique ID (0..99999999) of the current input device, e.g. 120 (ID=0 means no input device
is currently connected) |
|
| InputName |
out |
1 NAME64 (any string)1 |
returns 'Name' string of the current input device, e.g. "Low.Scr3" |
|
| Name |
out |
1 NAME64 (any string)1 |
returns the name of the current input device, e.g. "Low.Scr3" |
|
| Status |
out |
INT32 or any string1 |
returns code or string in which condition the input device currently is
| Integer Code |
Recommended Colour for Code |
String |
| 0 |
Red |
Reinitialization failed. |
| 1 |
Green |
Everything is fine. |
| 2 |
Yellow |
New frames are not coming in. |
| 3 |
Blue |
Currently no image source connected. |
| 4 |
Orange |
Camera temporarily disconnected. |
| 5 |
Green |
Source transmission paused.4 |
|
|
| Switch |
in/out |
in: 1 NAME64 (any string)1
out: INT32 |
switch to some new image source, its name is passed as input parameter, possible
source name may2 be seen at TINE-device 'Server', property 'Sources'.
In case return code is 513 (success), return value will be a transaction ID, which
can be passed later on to property 'SwitchResult' to obtain information about result
of the switching attempt.
|
513: OK. Name accepted. Switching will be tried. Server will be restarted for this.
525: Failed. Name was not accepted.
|
| SwitchIfNotAlready |
in/out |
in: 1 NAME64 (any string)1
out: INT32 |
works the same way as 'Switch' property, except if the image source name is currently already
active on this SGP, switching will not be performed at all.
|
0: OK. Image source/input device was already set. Switching was cancelled.
513: OK. Name accepted. Switching will be tried. Server will be restarted for this.
525: Failed. Name was not accepted.
|
| SwitchResult |
in/out |
in: INT32
out: 1 NAME64 (any string)1 or INT32 |
one has to pass a proper transaction id and then will get back
the return code or human readable string containing information
about success/failure of the switching attempt
| Integer Code |
String3 |
| 0 |
switching of input is currently ongoing |
| 1 |
switching of input successfully completed |
| -1 |
switching of input failed |
| -2 |
switching of input failed but server will keep running, because it's configured to do so |
|
515: bad magic passed on input |
Footnotes:
|
1
|
possible are data types CF_TEXT, CF_NAME8, CF_NAME16, CF_NAME32, CF_NAME48, CF_NAME64,
longer text may be cutted automatically to fit datatype constraints |
|
2
|
The possible image source (input device) names can only be read out if a syslist.xml
file is present. |
|
3
|
the returned string does not exactly look like this |
|
4
|
As of August 2014, constant delivery of video images from camera to SGP server can be
paused, in case no one is interested in the data (no client(consumer) is connected to SGP server and
SGP server internally does not need the data, too (e.g. for local history)). This functionality has been
implemented for resource economy, e.g. if raw camera images are transferred via a shared LAN backbone.
Please note that a minimal connection from camera to SGP server is being retained, e.g. get/set camera
slow control properties is still possible. |
Property Interface of TINE-device 'ImageAdjustments'
| TINE Property |
In/Out |
Data Types |
Description |
Special Error codes |
| Orientation |
in and/or out |
in: INT32 or any string1
out: INT32 or any string1 |
Gets or sets the orientation change of the currently connected image source. The set orientation change is
active and enabled as long as no switching is performed at SGP or the property is being rewritten with
some different value.
| Code | Input and Output string | Input String(s) also possible |
| 0 | 'No orientation change' | 'NORM', 'NoChange' |
| 1 | 'Rotation by 90 degrees clockwise' | 'ROT90CW', 'RotationBy90CW' |
| 2 | 'Rotation by 90 degrees clockwise' | 'ROT180CW', 'RotationBy180' |
| 3 | 'Rotation by 90 degrees counterclockwise' | 'ROT270CW', 'RotationBy90CCW' |
| 4 | 'Mirror along the horizontal axis' | 'MIRRORHORIZ', 'MirrorAlongHorizontalAxis' |
| 5 | 'Mirror along the vertical axis' | 'MIRRORVERT', 'MirrorAlongVerticalAxis' |
| 6 | 'Rotation by 90 degrees clockwise, then mirror along the horizontal axis' | 'ROT90CWMIRRHORIZ', 'RotationBy90CWThenMirrorAlongHorizontalAxis' |
| 7 | 'Rotation by 90 degrees clockwise, then mirror along the vertical axis' | 'ROT90CWMIRRVERT', 'RotationBy90CWThenMirrorAlongVerticalAxis' |
|
|
| ParametersChanged |
out |
1 INT32 |
shows the number of times parameters (orientation, scale) have been changed (NOTE: counter is reset to 0 each time an
image coming from a different image source is preprocessed) |
|
| Reset |
in |
in: 1 INT32 |
if correct magic number2 is passed, default orientation and scale factors from cameraports.xml
(if any) are reloaded. In addition, the counter (see 'ParametersChanged' property) is reset to zero. |
515: bad magic passed on input |
| ScalingFactors |
in and/or out |
in: 2 FLOAT or DOUBLE
out: 2 FLOAT or DOUBLE or 1 NAME64 (any string)1 |
one can read or alter the scaling factors (mm/pixel) for x and y which are attached to each
image, x is the first floating point number, y the second. Each number can have the
following values (two special meanings):
| Value |
Description |
| ~-1.0000 |
set the scale factor to 'not set' special value |
| 0.0000 |
do not touch the scale factor, leave it as it is |
| >0.0000 |
set scale factor to value in mm/pixel |
Note: Scaling factors are applied before orientation is changed. So if e.g. orientation is adjusted by rotating the video image at 90 degrees, width and height of video image are swapped. As a consequence, scale factors for x and y are swapped, too.
|
|
| SoftROI_Enabled |
out |
1 INT32 |
One can read whether software region of interest (roi) feature is enabled or disabled.
| Value |
Description |
| 0 |
false: the software roi feature is currently not enabled |
| 1 |
true: the software roi feature is currently enabled |
Notes:
- Please consult device 'SOFTWARE_ROI' for more properties related to
software region of interest.
- The software region of interest feature was implemented in January 2021 (2021-01).
|
|
| SourceNameScales |
in and out |
in: 1 NAME64 (any string)1
out: 1 NAME64 (any string)1 or INT32 |
A special string containing a partial name match of a input source
name and scale factors for unbinned mode of input source.
The string is evaluated inside the server and the scale factors
will (after successful evaluation) be changed. The set scale factors are
active and enabled as long as no switching is performed at SGP or the
property is being rewritten with some different values.
| Input String pattern |
Example |
Description |
| $partial_cameraport_name=$valuexy |
Low.Scr1=0.0083 |
If the currently connected image source name partially matches 'Low.Scr1',
x and y scale will be changed to 0.0083 each. |
| $partial_cameraport_name=$valuex:$valuey |
Low.Scr1=0.0083:0.0045 |
If the currently connected image source name partially matches 'Low.Scr1',
x scale will be changed to 0.0083 and y scale will be changed to 0.0045. |
| $partial_cameraport_name=:$valuey |
Low.Scr1=:0.0045 |
If the currently connected image source name partially matches 'Low.Scr1',
x scale will be set to undefined and y scale will be changed to 0.0045. |
| $partial_cameraport_name=$valuex: |
Low.Scr1=0.0083: |
If the currently connected image source name partially matches 'Low.Scr1',
x scale will be set to 0.0083 and y scale will be set to undefined. |
| $partial_cameraport_name= |
Low.Scr1= |
If the currently connected image source name partially matches 'Low.Scr1',
x and y scale will be set to undefined. |
| Return Code |
String |
| 0 |
Success: Updating of scale factors successfully finished. |
| 1 |
Failure: Image source name does not partially match. |
| 2 |
Failure: Translation of scale factors on SGP input failed. |
|
530:malformed input string could not be properly decoded |
Footnotes:
|
1
|
possible are data types CF_TEXT, CF_NAME8, CF_NAME16, CF_NAME32, CF_NAME48, CF_NAME64,
longer text may be cutted automatically to fit datatype constraints |
|
2
|
the magic is INT32 1 |
Property Interface of TINE-device 'Output'
| TINE Property |
In/Out |
Data Types |
Description |
Special Error codes |
| Frame |
out |
IMAGE |
will return the latest available video frame (bits and header), recommended to be used for single
requests as well as fallback solution (with long timeout e.g. 4000 ms) in case Frame.Sched does not work |
517: if not a single frame is available (yet), usually happens if server has not got one single frame from any input source since it was started |
| Frame.Sched |
out |
IMAGE |
will return the latest available video frame (bits and header), uses scheduled mode of TINE so that
frame is quickly transferred to client as soon as it's available, recommended to be used for clients that
need high update rate or low latency |
517: if not a single frame is available (yet), usually happens if server has not got one single
frame from any input source since it was started
516: frame was already sent out (a scheduled frame in principle cannot be asked a couple of
times per update cycle)
|
| Header |
out |
188 bytes |
debug-type property, will return the latest available video header contents
converted to array of 188 bytes |
517: if not a single header is available (yet), usually happens if server has not got one single
frame from any input source since it was started
|
| Header.Sched |
out |
188 bytes |
debug-type property, will return the latest available video header contents
converted to array of 188 bytes, uses scheduled mode of TINE so that
recent header update is transferred to client(s) with low latency |
517: if not a single frame is available (yet), usually happens if server has not got one single
frame from any input source since it was started
516: frame was already sent out (a scheduled frame in principle cannot be asked a couple of
times per update cycle)
|
Property Interface of TINE-device 'Monitoring'
The functionality of monitoring intensity increase of video image
was only a draft. It was never completed and put to production level.
It can not be used.
The TINE-device Monitoring groups properties related to monitoring
tasks of SGP component. As one feature, it was foreseen to monitor
intensity of subsequent video images while keeping a local history
of video images (backlog, short-term history). In case of sudden
intensity increase, local history was frozen and post mortem event
was triggered. Then, TINE post mortem archive server should download
frozen local history video images in order to permanently store a
video animation of the sudden intensity increase. This animation
was archived and provided for further analysis or inpection. The
goal was to record video images containing spark events.
| TINE Property |
In/Out |
Data Types |
Description |
Special Error codes |
| IntensityEnable |
in and out |
in: 1 INT32
out: 1 INT32 |
Returns whether intensity monitoring is enabled or not.
| Value |
Description |
| 0 |
false: intensity monitoring is currently not enabled |
| 1 |
true: intensitiy monitoring is currently enabled |
|
|
| IntensityLstVal |
out |
1 DOUBLE |
In case the intensitiy of the last video image was calculated,
it's value will be returned here. In case intensity value was
not calculated, -1.0 is returned.
|
|
| IntensityThresh |
in and out |
in: 1 DOUBLE
out: 1 DOUBLE or FLOAT
|
One can get and set the intensity threshold level. Allowed values to set are >1.0 to <10.0 .
A value of 1.1 means that the next image must be 10% more intense than the current image
to trigger intensity threshold action. A value
of 2.0 means that the next image is 100% more intense than the current image. A value of
9.99 means that the next image is almost 9 times more intense than the current image. The default
intensity threshold is set to 1.14 (next image is 14% more intense than current image).
|
|
Property Interface of TINE-device 'SOFTWARE_ROI'
The TINE-device SOFTWARE_ROI groups properties related to software region of interest.
In order to limit bandwidth on the network, a rectangular area (part of the whole
video image delivered from image source (i.e. camera hardware) can be defined.
This rectangular area is called roi. Only the defined roi is then transported further
to interested clients via shared memory or TINE properties Frame or Frame.Sched
(device Output).
It must be noted that the roi is applied after the orientation of image from hardware is adjusted (if
orientation adjustment is enabled). Orientation can be found in
device ImageAdjustments.
In principle, software roi is also part of image adjustments, but it's more intuitive to control if
all properties related to software roi are part of a device.
The software region of interest feature was implemented in Januar 2021.
| TINE Property |
In/Out |
Data Types |
Description |
Special Error codes |
| BOUNDING_RECT |
out |
1 ADDRESS (IIII) |
Returns four integers. The four integer values define the bounding rectangle of the roi (the roi can
not get outside these dimensions).
| Index |
Name |
Description |
| first integer |
minimum x |
the minimal starting colum in of the roi, in pixels |
| second integer |
minimum y |
the minimal starting row in of the roi, in pixels |
| third integer |
maximum x |
the maximum ending column of the roi, in pixels |
| fourth integer |
maximum y |
the maximum ending row of the roi, in pixels |
|
|
| HEIGHT_MIN_MAX |
out |
1 INTINT |
Returns two integers. The first integer defines the minimum height
of the roi (in pixels) which is currently possible. The second integer defines the
maximum height of the roi (in pixels) which is currently possible.
|
|
| IS_ENABLED |
out |
1 INT32 |
One can read whether software region of interest (roi) is enabled or disabled.
| Value |
Description |
| 0 |
false: the software roi feature is currently not enabled |
| 1 |
true: the software roi feature is currently enabled |
|
|
| SEND_AS_AOI_IMAGE |
in and out |
in: 1 INT32
out: 1 INT32
|
One can get or set whether the roi, if enabled, is send out as
aoi feature of image (preferred) or as plain image. Using
aoi feature, it is possible to transport full image dimensions
before roi was applied in addition, in order to keep a reference.
| Value |
Description |
| 1 (default) |
the software roi will be send out as aoi feature of image |
| 0 |
the software roi will be send out as plain image (not as aoi feature) |
|
|
| VALUE |
in and out |
in: 1 ADDRESS (IIII)
out: 1 ADDRESS (IIII)
|
| Index |
Name |
Description |
| first integer |
left (start x) |
the starting colum of the roi, in pixels |
| second integer |
top (start y) |
the minimal starting row in of the roi, in pixels |
| third integer |
width |
the width of the roi, in pixels |
| fourth integer |
height |
the height of the roi, in pixels |
One can set and get the roi. By successfully setting it, the roi is
automatically enabled. In order to reset the roi, one must send -1/-1/-1/-1 (reset code).
This reset code either fully disables the roi, if this is possible (full
image transport can be restricted to a certain roi width and height in
order to reduce bandwidth on the network), or resets the roi back to
it's maximum allowed width and height). The values to be set must be inside
of the bounding rectangle, which can be obtained via BOUNDING_RECT
property of this device.
| VALUE.left must be >= BOUNDING_RECT.minimum_x |
| VALUE.top must be >= BOUNDING_RECT.minimum_y |
| VALUE.width+VALUE.left must be <= BOUNDING_RECT.maximum_x |
| VALUE.height+VALUE.TOP must be <= BOUNDING_RECT.maximum_y |
In addition, the third integer (width) must
be also inside bounds given by property WIDTH_MIN_MAX. The fourth parameter (height) must
be also inside bounds given by property HEIGHT_MIN_MAX.
|
37: out_of_range (some value is out of range)
|
| VALUE_START |
out |
1 ADDRESS (IIII) |
| Index |
Name |
Description |
| first integer |
left (start x) |
the starting colum of the roi, in pixels |
| second integer |
top (start y) |
the minimal starting row in of the roi, in pixels |
| third integer |
width |
the width of the roi, in pixels |
| fourth integer |
height |
the height of the roi, in pixels |
Returns the value of the initial roi defined in
cameraports.xml file (applied directly after switching to the
current image source). By writing back the values obtained here
to property VALUE, one can reset changes to roi performed
by writing to property VALUE in the meantime.
|
|
| WIDTH_MIN_MAX |
out |
1 INTINT |
Returns two integers. The first integer defines the minimum width
of the roi (in pixels) which is currently possible. The second integer defines the
maximum width of the roi (in pixels) which is currently possible.
|
|
Property Interface of TINE-device 'SSC'
The TINE-device SSC (Simple Slow Control) is not always available. It exists if
the input device provides the possibility to read and/or set special parameters inside the image
source hardware (usually camera) via the same object/connection where the images (video frames) are
read out. Currently, SGP Type 'ProsilicaGigE' and 'JaiGigE' provide SSC functionality to provide a
front-end interface for USC (Universal Slow Control in order to control
camera properties like gain, shutter speed, etc.
| TINE Property |
In/Out |
Data Types |
Description |
Special Error codes |
| Name |
out |
1 NAME64 (any string)1 |
Returns the camera name of the image source. Provides the same functionality as TINE-device 'Source',
property 'Name'. |
|
| Read |
in and out |
in: n NAME64 (any string)1
out: n NAME64 (any string)1 |
One can read 1 to n hardware properties at the same time. The same number of names of hardware properties one
sends to the server as input parameter one can get back their values at output parameter. The server will
return the values returned by the underlying API for the hardware, only automatic type conversion to string
is performed. |
518: syntax error
519: one of the hardware parameter names could not be looked up at hardware API
520: no type conversion for value to string has been implemented yet
521: low-level error at hardware API
523: error getting value at hardware API
524: hardware device is not reachable
|
| Write |
in |
in: 1 NAME64 (any string)1
|
A wellformed string 'name=value' (e.g. 'ExposureValue=10') needs to be passed. Name will be looked up in hardware properties and if
found, it's type will be used to try an autoconvert of the passed value to the given type. If everything
went well so far, value is tried to be set at hardware property and on success, return code is 0. |
518: syntax error
519: one of the hardware parameter names could not be looked up at hardware API
520: no type conversion from string to value has been implemented yet
521: low-level error at hardware API
522: error setting value at hardware API
524: hardware device is not reachable
|
Footnotes:
|
1
|
possible are data types CF_TEXT, CF_NAME8, CF_NAME16, CF_NAME32, CF_NAME48, CF_NAME64,
longer text may be cutted automatically to fit datatype constraints |
|