AVINE Video System

Application Programming Interfaces

Matlab external functions
C/C++ API

Matlab external functions

The following Matlab functions are currently available:

Function name	Short description	Calling conventions
avine_load_video_images_from_file()	load Video System 2 image files (.imc2, .bkc2, .imc, .bkc, .imm, .bkg) into Matlab as cell of matrices	calling-avine_load_video_images_from_file.txt
avine_tine_read_images()	acquire fresh image(s) from video server into Matlab as cell of matrices	calling-avine_tine_read_images.txt
avine_save_video_images_to_file()	save Matlab cell of matrices (e.g. produced via avine_load_video_images_from_file() or avine_tine_read_images() to Video System 2 image file (.imc2, .bkc2, .imc, .bkc, .imm, .bkg)	calling-avine_save_video_images_to_file.txt

Environment Variables

Name	AVINE_MATLAB_NO_MEXLOCK
available since	v0.9.4 Jan 25, 2017
Description	By default, as of v0.9.4 (Jan 25, 2017), avine_tine_read_images() Matlab EXternal function (MEX file) is locked into memory. This is done to reduce amount of Matlab hangs and crashes, especially on Linux. Crashes are related to the use of clear commands in Matlab (e.g. 'clear all', 'clear mex'), which unload the mex file beneath the surface. Although improvements have been implemented at shared library level (TINE, video system library), crashes have still been observed under rare exotic non-reproducable scenarios. If locking the mex file in memory is not wanted, it can be disabled by setting the environment variable AVINE_MATLAB_NO_MEXLOCK to TRUE (case insensitive). Setting of environment variable must be done prior to first call to avine_tine_read_images()! Once the mex function is locked into Matlab, it's not possible to unlock it!
Example	AVINE_MATLAB_NO_MEXLOCK=TRUE

Download Packages

Precompiled binaries for Matlab R2016b and newer are available for Linux (.mexa64, RHEL/SL7), ~~Win32 (.mexw32, Visual Studio 6)~~ and Win64 (.mexw64, Visual Studio 2015). However it is planned for the near future to migrate to some newer Matlab release, possibly R2021b, and Visual Studio 2019. In order to use the precompiled binaries, appropriate TINE (Release 5, >= 5.2.6) shared library (libtinemt.so, libtbufsrv.so, tbufsrv64.dll, tine64.dll) as well as Video System 3 (AVINE) shared library (libvideosystem3.so or videosystem3-x64.dll, >= 1.0.0) is required. In order to easily get going, appropriate shared libraries are part of the package. However users are asked to look for a centrally managed release of TINE and/or AVINE libraries at their facility.

The package contains prebuilt libraries, library dependencies of TINE and C/C++ api for Video System 3 (AVINE), calling conventions as well as changelogs for each MATLAB-function:

Package	Release date
avine-matlab-binaries.zip	Oct 2023

History (Previous Versions)

Version Date Remarks

1.0.0 July 2023

introduced .imc2/.bkc2 support
UTC time instead of local time
avine_load_video_images_from_file() / avine_save_video_images_to_file(): added support for color images (imc2/bkc2)
avine_save_video_images_to_file(): fixed crash-type of bug when trying to save single image of Matlab uint16 data type (not passed as cell of matrices, but directly putting array to second parameter)

0.9.6 Apr 9, 2020 Linux tine library filenames were wrong in v0.9.6 (Dec 17, 2019), fixed (libtinemt.so -> libtinemt.so.5, libtbufsrv.so -> libtbufsrv.so.5)

0.9.6 Dec 17, 2019

avine_tine_read_images(): v0.9.5: typo corrected, minor cosmetic improvement in source
avine_save_video_images_to_file(): v0.9.6: fixed two crash-type bugs on arguments
avine_load_video_images_from_file(): v0.9.4: fixed compiler error on Scientific Linux 7
updated videosystem library (0.99.13 -> 0.99.15): stability and robustness improved, upgraded to TINE release 5 and Visual Studio 2015

0.9.4 Jan 25, 2017

avine_tine_read_images(): by default, mex file will be locked in memory (mexLock()), because it has been observed that Matlab's clear command can lead to crashes if library is unloaded
avine_tine_read_images(): added AVINE_MATLAB_NO_MEXLOCK environment variable
avine_tine_read_images(): some verbose and debug output improved
avine_save_video_images_to_file(): unchanged (kept at v0.9.3)
avine_load_video_images_from_file(): unchanged (kept at v0.9.3)
updated videosystem library (0.99.7 -> 0.99.13): stability and robustness improved, streamlined asychronous listener

0.9.3 Jan 19, 2016

new function: avine_save_video_images_to_file()
on Windows 64-bit, Visual Studio Runtime DLLs (e.g. msvcr100.dll, msvcp100.dll) are no longer necessary
avine_tine_read_images(): if only one frame is asked for, TINE asynchronous listener is used (performance gain, reduced wasting of system resources if called in a loop)
avine_load_video_images_from_file(): a parameter has not been cleaned up properly
few minor fixes and improvements
updated videosystem library (0.99.5 -> 0.99.7)

0.9.2 Aug 19, 2014 - updated videosystem library (0.99.4 -> 0.99.5)

0.9.2 Feb 7, 2014

updated videosystem library (0.99.2 -> 0.99.4), a data type was not properly initialized which sometimes lead to that one client was able to get video data while some other client(s), receiving video from the same source in parallel, could not get the video data
added tine buffered server shared library (libtbufsrv.so, tbufsrv.dll, tbufsrv64.dll) as video system library >= 0.99.4 requires it

0.9.2 Sept 6, 2013 - avine_load_video_images_from_file still 0.9.1 (no changes required)
- updated videosystem libraries (0.99.2)
- changed avine_tine_read_images to 0.9.2
- fixed avine_tine_read_images->vsGrabFramesEx2->callback reentrance
- fixed avine_tine_read_images->vsGrabFramesEx2->discard multiple frames with same framenumber
- fixed avine_tine_read_images: bug in third parameter (sequenceIndicator): was parsed incorrectly

0.9.2 Sept 2, 2013 - avine_load_video_images_from_file still 0.9.1 (no changes required)
- updated videosystem libraries (0.99.1)
- changed avine_tine_read_images to 0.9.2
- fixed avine_tine_read_images->vsGrabFramesEx2->callback reentrance
- fixed avine_tine_read_images->vsGrabFramesEx2->discard multiple frames with same framenumber
- fixed avine_tine_read_images: bug in third parameter (sequenceIndicator): was parsed incorrectly

0.9.1 May 27, 2013 - updated videosystem libraries (0.99.0)
- changed avine_tine_read_images default Tine transport mode EVENT -> TIMER
- added Tine timestamp, user stamp and system stamp
- added version number, build timestamp
- improved verbose output (added timestamp, mex function name)

Apr 24, 2013 - updated videosystem libraries

Mar 22, 2013 - new videosystem libraries

Feb 12, 2013 - changed naming

Jan 11, 2013 - initial public release

C/C++ interface/API for software developers

General Remarks
Download Packages
History (Previous Versions)
Getting Started with the Package
Using the Library with your own Application
Environment Variables
Logging
API Documentation
Special Information for PITZ
Building videosystem3.dll/.so

General Remarks

The C interface/API (compatible with C++) for software developers is being designed in a platform-independent manner. The library contains plain C interface. It can be accessed from C and C++. Currently, the following platforms are provided and tested:

~~Win32 (32-bit Windows, Visual C++ 6, focused on Windows XP)~~¹
~~Win64 (64-bit Windows, Visual Studio 2010 C++, focused on Windows 7)~~²
Win64 (64-bit Windows, Visual Studio 2015 C++, focused on Windows 10 (Win7 ok))³
Win64 (64-bit Windows, Visual Studio 2019 C++, focused on Windows 10/11)
Linux (64 bit, using gcc compiler, focused on Scientific Linux 7 (SL7) and Ubuntu-debian)

Platforms are foreseen to be supported long-term. Support for other platforms / software frameworks (like ROOT) may be possible (experience exists) and is will be considered on reasonable user request.

Footnote:

¹ As of January 2016, Windows 32-bit library has been deprecated and is not foreseen to be continued to be updated.

² As of December 2019, Windows 64-bit Visual Studio 2010 library has been deprecated and is not foreseen to be continued to be updated.

³ As of 2023, platform Windows 64-bit Visual Studio 2015 is considered to be superseded by Windows 64-bit Visual Studio 2019.

Download Packages

Packages containing prebuilt libraries, required include files and an example project (using the library and its includes) are available:

Platform Package Version Release date

Linux (SL7: amd64_rhel70) clnAPI-Linux-so-example-gcc.zip 1.0.0 July 2023

Linux (SL6: amd64_rhel60) DEPRECATED clnAPI-Linux-so-example-gcc--Jan25_2017.zip 0.99.13 Jan 25, 2017

Windows (x64) MSVS 2019 clnAPI-Win-x64-dll-example-MSVS2019.zip 1.0.0 July 26, 2023

Windows (x64) MSVS 2015 DEPRECATED clnAPI-Win-x64-dll-example-MSVS2015--Dec12_2019.zip 0.99.15 Dec 12, 2019

~~Windows (x64) MSVS10 DEPRECATED~~ ~~clnAPI-Win-x64-dll-example-MSVS2010.zip~~ ~~0.99.13~~ ~~Jan 25, 2017~~

~~Windows (x86) MSVC6 DEPRECATED~~ ~~clnAPI-Win-x86-dll-example-MSVC6.zip~~ ~~0.99.5~~ ~~Aug 19, 2014~~

History (Previous Versions)

Version Date Remarks

1.0.0 July 5, 2023

added .imc2/.bkc2 file format
upgraded build to Visual Studio 2019
added functions load_file__return_code_to_string(), vsCheckFileFormat(), vsBunchToVIDINFHDREx2, vsCheckImageValidity, vsLoadImagesFromFileEx(), vsLoadImagesFromFile(), vsSaveImagesToFileEx(), vsSaveImagesToFile()
improved stability and robustness
some minor and cosmetic bugs fixed

0.99.15 Dec 12, 2019

upgraded from TINE Release 4 to TINE Release 5
upgraded build to Visual Studio 2015
improved stability and robustness

0.99.13 Jan 25, 2017

improved stability and robustness
pipe can be created by environment variable AVINE_CLIENTLIB_TINE_PIPE, to inspect TINE client kernel while working
vsEstimateMaxFrameSizeBytes() refactored: now uses asynchronous listener (less overhead if called many times, e.g. beneath the surface of vsGrabFrame() (if this is called many times))

0.99.8 Sept 2, 2016

libvideosystem3.so (Linux) uses libtinemt.so instead of libtine.so
instead of manual TINE C-API SystemCycle() function calls in-between, TINE's SystemStartCycleTimer() is used before first call of TINE function in library (to initialize TINE kernel and provide data communication flow)
at unload of library, TINE C-API function SystemKillCycleTimer() is used (proper clean up)
vsGetFrameFromDIMAGE: fixed incorrect width returned as height of video image at aOutFrameHeightInPixels

0.99.7 Jan 12, 2016

new functions:

DIMAGE *vsInitializeImageEx( int aiFrameBufferSizeBytes );
int vsEstimateMaxFrameSizeBytes( const char *asTineAddress, const char *asTinePropertyName );
int vsCreateBunchStructure( VSBUNCHOFIMAGES *aImages, unsigned int aiNumFrames, unsigned int aiFrameBufferSizeBytes );

vsLibraryInfoEx: added TINE version and build number to string returned
Windows 64-bit DLL (videosystem3-x64.dll) does no longer depend on Microsoft Visual Studio runtime DLLs (e.g. no msvcr100.dll, msvcp100.dll required)

0.99.6 Dec 23, 2014 - special version for REGAE
- improved reliability if unexpected TINE return codes appear (e.g. sudden '45' while a transfer is running smooth)

0.99.5 Aug 19, 2014 - NO functional changes
- limit platform.h declarations to avoid naming collisions
- changed position of include files (separate folder)
- Linux library now only exports wanted symbols (via libvideosystem3.map linker definition file)

0.99.4 Jan 28, 2014

fixes TINE contract coercion failure seen recently at PITZ with Fastscan and Video Client in parallel
library will log its version number and build string to logfile (when logfile is created)
added vsGrabFrame() - single frame receive, optimized for calling in a loop, uses TINE asynchronous listener underneath
added support/helper functions for vsGrabFrame(): vsInitializeImage() and vsFreeImage()
new library requirements (tbufsrv, libtinemt.so):

due to support of TINE asynchronous listener, TINE tbufsrv library (tbufsrv.dll (Win32), tbufsrv64.dll (Win64), libtbufsrv.so(Linux)) is required from now on, in addition to TINE library (tine32.dll, tine64.dll, libtine.so)
libtbufsrv.so itself needs libtinemt.so

0.99.3 Dec 2, 2013 - fixes some occurence (sometimes, non-deterministic) on closing the TINE link at vsGrabFrames(Ex,Ex2), which could lead to memory corruption and crashes, seen on Linux

0.99.2 Sept 6, 2013 - added environment variables AVINE_CLIENTLIB_LOGGING_PATH, AVINE_CLIENTLIB_LOGLEVEL
- log file path defaults (TEMP environment variable on Windows, /tmp on Linux)
- log file name pattern including date, hostname, process-id, username
- process-id, process name will be put to logfile

0.99.1 Sept 2, 2013 - increased output to log file in case of errors
- vsGrabFrames(Ex, Ex2): tine callback called by these function is now robust against reentrant calls
- vsGrabFrames(Ex, Ex2): if a video frame (by frame number) is received more than once, only the first one will be used, all others will be discarded
- vsGrabFramesEx, Ex2: added more error codes (apiOutError: -8 and -9)

0.99.0 May 27, 2013 - added new logging mode: log to file (#3)
- changed default logging mode from 'off' to 'log to file' (avine-sharedlib.log)
- added vsGrabFramesEx2() (added possibility to obtain DTYPE values for each frame for user, system and tine timestamp)
- added to vsGrabFrames(Ex, Ex2): set 4 MB Tine socket receive buffers
- added vsTineCodeToString()
- revised and cleaned up exampleMain.cpp
- changed version numbering scheme from a.b to a.b.c (major.minor.subminor-revision)

- added environment variable AVINE_CLIENTLIB_VIDEO_TRANSFER_TINE_ACCESS_RATE_MILLISECONDS_FORCE
(e.g. AVINE_CLIENTLIB_VIDEO_TRANSFER_TINE_ACCESS_RATE_MILLISECONDS_FORCE=500)
- added environment variable AVINE_CLIENTLIB_VIDEO_TRANSFER_TINE_ACCESS_MODE_FORCE
(e.g. AVINE_CLIENTLIB_VIDEO_TRANSFER_TINE_ACCESS_MODE_FORCE=TIMER|CONNECT)
(possible, |ed together: EVENT, TIMER, STREAM, MCAST, NETWORK, CONNECT, SYNCNOTIFY)

0.98 Apr 24, 2013 - changed transfer startup (adjust to server's tine data size) at vsGrabFrames(Ex) in order to improve compatibility
- added more logging (of TINE error codes during transfer at vsGrabFrames(Ex))
- vsGrabFramesEx: apiOutTineError will not be filled just in certain scenarios (0.97), but always

0.97 Mar 22, 2013 - added vsGrabFramesEx
- added vsBunchToVIDINFHDREx
- added save_imm_fileEx, save_imc_fileEx, save_bkc_fileEx - added more logging (e.g. at vsIsSequence() ) - logging is switched off by default, use vsSetVerbose() to enable logging

0.96 Mar 12, 2013 - first package release for Win x64
- added INT32 load_bmp_file( const char *filename, struct VIDINFHDR *vinf, int bEightBitDirect );
- added internal routines for 'avine...' Matlab external functions

0.95 Jan 11, 2013 - fix at v2videofileload.cpp::load_imc_bkc_file()
- fixed time_t on win64
- introduced vsGetVerbose(), vsSetVerbose()
- reworked debug printfs

0.93 Nov 29, 2012 - minor adjustment in include file videosystem3.h (added #define TINE_DECORATED_CONSTANTS)

0.93 Nov 27, 2012 - Scientific Linux 6 (amd64_rhel60) tested
- vsGetAllImageSourceNames() added

0.92 Sept 28, 2012 - added experimental Labview support

0.91 Sept 19, 2012 - initial public release

Getting Started with the Package

For inexperienced users it is recommended to compile, link, execute and study the provided example inside the package before integration into own projects are started.

After unzipping the downloaded package, depending on the downloaded package, one may need to get some external reference: TINE library and include files for the chosen platform. For newer packages these files are provided as a starting point. Please consult readme.txt included in each package for information whether these files are provided or where to get them.

For Linux, a makefile for the example is provided. For Windows platform, project files for Microsoft Visual Studio 2019 (Win-x64) are provided.

Before building the example, one may need to edit exampleMain.cpp. Inside the function videoImagesExample(), the address of the video server used for getting images from, is hardcoded to some Zeuthen PITZ Video System 3 server name. It may need to be modified according to your current local availability.

When the example binary is executed, the following execution flow is going to happen:
In the first part, the so-called videoImagesExample(), 10 fresh video images in-a-row are requested at some Zeuthen PITZ Video System 3 server (the address for this is hardcoded in exampleMain.cpp and may need modification according to current availability). If successful, it is being checked whether the images-in-a-row are a sequence and if successful, whether these images are even a strict sequence. If successful, it is tried to decompress the images (jpeg -> raw, images which are already raw will be left untouched). Afterwards, images are converted to old-style header format (videokernel library of VSv2) and VSv2 function is used to save the sequence to an imc file.
In the second part, the so-called syslistExample(), PITZsyslist.xml file is loaded. If successful, the TINE Context, as it is encoded in the XML file, will be printed to stdout. Then all servers names of servers which are delivering raw video, as encoded in the XML file, are printed. After that, all image source names are printed. As last step, all images source names and their corresponding ID numbers are printed out.

Using the Library with your own Application

Facts that need to be remembered without regard to platform are:

the directory containing TINE includes (*.h as well as proper TINE project.def for the platform) need to be added to the includes-search-path of your project
a system.h needs to exist in your project (containing proper platform define for platform.h) [1]
the directory containing library includes (in package the directory is /lib/include) needs to be added to the includes-search-path of your project
only 'videosystem3.h' needs to be included (#include "videosystem3.h") into your project

Inside of videosystem3.h, the following includes are placed:

  #include "system.h"                 // part of your project (see example), needed by platform.h
  #include <videosystem3/platform.h>  // platform-wrapper
  #include <videosystem3/v3clientlib-tineincludewrapper.h>
  
  #include <videosystem3/v2core.h>
  #include <videosystem3/v2algorithms.h>
  #include <videosystem3/v2videofileload.h>
  #include <videosystem3/v3clientapi.h>

Facts that need to be remembered for Linux are:

TINE libraries (~~libtine.so~~¹, libtbufsrv.so, libtinemt.so) needs to be in search-path (LD_LIBRARY_PATH)
Video System 3 library (libvideosystem3.so) needs to be in search-path (LD_LIBRARY_PATH)
Footnote:

¹ Since libvideosystem3.so v0.99.8 (Sept 2, 2016), libtine.so is not referenced any more. It has been superseded by libtinemt.so.

Facts that need to be remembered for Windows x86 (x64) are:

tine64.dll, tbufsrv64.dll must be in dll-search-path (PATH environment variable)
videosystem3-x64.dll must be in dll-search-path (PATH environment variable)

Environment Variables

Name AVINE_CLIENTLIB_LOGGING_PATH

available since v0.99.2 Sept 6, 2013

Description One can change the path where the client library puts its logfile.
Note: The user is able to change the logfile path and filename by API (vsSetVerboseEx()). User changes will not be superseded by the environment variable.

Examples Linux: AVINE_CLIENTLIB_LOGGING_PATH=/afs/ifh.de/group/pitz/doocs/log/
Windows: AVINE_CLIENTLIB_LOGGING_PATH=\\win.desy.de\home\sweisse\tmp
Windows: AVINE_CLIENTLIB_LOGGING_PATH=c:\tine\log\

Name AVINE_CLIENTLIB_LOGLEVEL

available since v0.99.2 Sept 6, 2013

Description One is able to set a certain logging level (more or less messages).
Possible values are 1 (default) and 2 (more details). In case of 2 parameters of certain function calls (e.g. vsGrabFramesEx) are also put to log file.

Example AVINE_CLIENTLIB_LOGLEVEL=2

Name AVINE_CLIENTLIB_TINE_PIPE

available since v0.99.13 Jan 25, 2017

Description In order to inspect TINE client kernel beneath video system library while working, one can set the environment variable AVINE_CLIENTLIB_TINE_PIPE to some custom string value. The recommendation is to use between 6 and 30 Ascii characters. Note: Tine is not initialized prior to first call of a function which requires TINE kernel to be running: vsGrabFrame(), vsGrabFrames(), vsGrabFramesEx(), vsGrabFramesEx2() and vsEstimateMaxFrameSizeBytes().

Example AVINE_CLIENTLIB_TINE_PIPE=TiClnDbgPipe

Name AVINE_CLIENTLIB_VIDEO_TRANSFER_TINE_ACCESS_MODE_FORCE

available since v0.99.0 May 27, 2013

Description One can supersede the vsGrabFrames(Ex,Ex2) parameter aTineMode by this environment variable.
Possible values are EVENT, TIMER, STREAM, MCAST, NETWORK, CONNECT, SYNCNOTIFY. Certain values can be ORed together via special character '|'. This environment variable comes handy e.g. if multicast access is introduced later on. Client code does not need to be changed.

Example AVINE_CLIENTLIB_VIDEO_TRANSFER_TINE_ACCESS_MODE_FORCE=TIMER|CONNECT
This changes any passed aTineMode to TIMER|CONNECT.

Name AVINE_CLIENTLIB_VIDEO_TRANSFER_TINE_ACCESS_RATE_MILLISECONDS_FORCE

available since v0.99.0 May 27, 2013

Description One can supersede vsGrabFrames(Ex,Ex2) parameter aTineTimeoutMilliseconds by this environment variable.

Example AVINE_CLIENTLIB_VIDEO_TRANSFER_TINE_ACCESS_RATE_MILLISECONDS_FORCE=4000
This changes any passed aTineTimeoutMilliseconds to 4000 ms.

Logging

As of v0.99.2 (Sept 6, 2013), logging has been extended:

Filename The name of the log file has been changed. It now follows a defined pattern:
avine-sharedlib--$year-$month-$day--p-$process_id--u-$username--h-$hostname.log
e.g. avine-sharedlib--2013-Sep-09--p-16435--u-sweisse--h-ZNOREADE20.log

Path By default, a well-known temporary directory for the operating system will be used to put the log file to.
On Linux, /tmp is used. On Windows, environment variable TEMP is used.

If AVINE_CLIENTLIB_LOGGING_PATH is set, the path given there will be used to put the log file to.

In case the log path is not writable, stderr is used to output log messages.

Versions earlier than v0.99.2 by default logged to avine-sharedlib.log file, created in the current working directory.

API Documentation

New Functionality

In order to avoid redundancies and documentation work, the detailed function reference is not put into html. Explanation of structures and definitions used is placed in single header file v3clientapi.h. Please consult v3clientapi.h. In addition, function reference is also put there, in front of each function declaration. In the following just bare function prototypes and structure declaration are shown.

typedef struct
{
	DIMAGE *imageArray; // DIMAGE declared in TINE, see tinetype.h
	UINT32 numFrames;   // number of frames in sequence, zero in case of no frame
} VSBUNCHOFIMAGES;

since v1.0.0 (July 2023)

INT32 vsLoadImagesFromFile
(
    const char *asFilePath,
    VSBUNCHOFIMAGES *apImages
);

INT32 vsLoadImagesFromFileEx
(
    const char *asFilePath, 
    VSBUNCHOFIMAGES *apImages, 
    int *apiInInterrupt,
    double *apdOutPercentageFinished,
    char *asErrorStringReturnBuffer,
    unsigned int aiErrorReturnBufferSizeBytes
);

INT32 vsSaveImagesToFile
(
    VSBUNCHOFIMAGES *apImages, 
    const char *asFilePath
);

INT32 vsSaveImagesToFileEx
(
    VSBUNCHOFIMAGES *apImages, 
    const char *asFilePath, 
    char *asErrorStringReturnBuffer, 
    unsigned int anErrorReturnBufferSizeBytes,
    int *apiInInterrupt,
    double *apdOutPercentageFinished
);

INT32 vsCheckFileFormat
(
    const char *asFilePath,
    char *asOutErrorReturnString,
    size_t aiErrorReturnStringLengthBytes
);


INT32 load_bmp_file
( 
    const char *filename,
    struct VIDINFHDR *vinf,
    int bEightBitDirect
);

INT32 save_bkc_fileEx
(
    const char *outfilename,
    const struct VIDINFHDR *vinf,
    int *apiInInterrupt,
    double *apdOutPercentageFinished
);

INT32 save_imc_fileEx
(
   const char *outfilename,
   const struct VIDINFHDR *vinf,
   int *apiInInterrupt,
   double *apdOutPercentageFinished
);

INT32 save_imm_fileEx
(
    const char *outfilename,
    const struct VIDINFHDR *vinf,
    int *apiInInterrupt,
    double *apdOutPercentageFinished
);

int vsBunchToVIDINFHDR
( 
    const VSBUNCHOFIMAGES * const aImages, 
    struct VIDINFHDR *aV
);

int vsBunchToVIDINFHDREx
( 
    VSBUNCHOFIMAGES *aImages,
    struct VIDINFHDR *aV,
    int aiLowMemoryConsumption,
    int *apiOutImagesBunchUntouched
);

int vsCreateBunchStructure
( 
    VSBUNCHOFIMAGES *aImages,
    unsigned int aiNumFrames,
    unsigned int aiFrameBufferSizeBytes
); 

int vsDecompressImage
(
    DIMAGE *aOut, 
    const DIMAGE * const aIn
);

int vsDecompressSequence
(
    VSBUNCHOFIMAGES *aImages,
    int aReleaseMemory
);

int vsEstimateMaxFrameSizeBytes
( 
    const char *asTineAddress,
    const char *asTinePropertyName
); 

int vsFreeBunch
(
    VSBUNCHOFIMAGES *aImages
);

int vsFreeImage
( 
    DIMAGE *apImage 
);

int vsGetAllRawVideoServerNames
( 
    const char *aSyslistFilenamePath, 
    NAME64 *aOutTineContext, 
    NAME64 *aOutTineServerNames, 
    unsigned int *aInOutNumServerNames
);

int vsGetAllImageSourceNames
(
    const char *aSyslistFilenamePath,
    NAME64 *aOutCameraNames,
    NAME64I *aOutCameraNameIDs,
    unsigned int *aInOutNumCameras
);

//getFrameFromDIMAGE before lib# 0.99.1
int vsGetFrameFromDIMAGE
( 
    void *aInOutFrame, 
    int *aInOutFrameSizeInBytes,
    const void *aInDIMAGEBuffer, 
    int *aOutFrameWidthInPixels, 
    int *aOutFrameHeightInPixels,
    int *aOutRawDataFormat,
    int *aOutBytesPerPixel,
    int *aOutEffectiveBitsPerPixel,
    void *aOutDIMAGE
);

int vsGetVerbose();

int vsGetVerboseEx
( 
    int *apiOutVerboseLevel, 
    char *apsOutLogFileNamePathBuffer, 
    int *apiInOutLogFileNamePathBufferSizeBytes
);


int vsGrabFrame
( 
    DIMAGE *apInOutImage, 
    DTYPE *apDOut,
    const char *asTineAddress,
    const char *asTinePropertyName,
    int aiTineTimeoutMilliseconds,
    int aiTineMode,
    int *apiOutTineError 
);

int vsGrabFrames
(
    VSBUNCHOFIMAGES *aImages, 
    const char *aTineAddress, 
    const char *aTinePropertyName, 
    unsigned int aNumFrames, 
    int aTineTimeoutMilliseconds, 
    int aTineMode
);

int vsGrabFramesEx
(
    VSBUNCHOFIMAGES *aImages, 
    const char *aTineAddress, 
    const char *aTinePropertyName, 
    unsigned int aNumFrames, 
    int aTineTimeoutMilliseconds, 
    int aTineMode,
    int *apiOutError,
    int *apiOutTineError,
    int *apiInInterrupt,
    double *apdOutPercentageFinished
);

int vsGrabFramesEx2
(
    VSBUNCHOFIMAGES *aImages, 
    DTYPE *aImagesDOut,
    const char *aTineAddress, 
    const char *aTinePropertyName, 
    unsigned int aNumFrames, 
    int aTineTimeoutMilliseconds, 
    int aTineMode,
    int *apiOutError,
    int *apiOutTineError,
    int *apiInInterrupt,
    double *apdOutPercentageFinished
);

int vsInitializeBunchStructure
( 
    VSBUNCHOFIMAGES *aImages
);

DIMAGE *vsInitializeImage();

DIMAGE *vsInitializeImageEx
( 
    int aiFrameBufferSizeBytes
); 

int vsIsCompleteSequence
(
    const VSBUNCHOFIMAGES * const aImages
);

int vsIsSequence
( 
    const VSBUNCHOFIMAGES * const aImages 
);

char * vsLibraryInfo
(
    unsigned int *aVersionMajor, 
    unsigned int *aVersionMinor, 
    char *aBuildInfoString, 
    unsigned int *aBuildInfoStringBufferLengthBytes
);


char * vsLibraryInfoEx
(
    unsigned int *aVersionMajor, 
    unsigned int *aVersionMinor, 
    unsigned int *aVersionSubMinor, 
    char *aBuildInfoString, 
    unsigned int *aBuildInfoStringBufferLengthBytes
);

int vsSetVerbose
( 
    int aVerboseLevel 
);

int vsSetVerboseEx
(
   int aVerboseLevel,
   const char *aFilePath
);

INT32 vsTineCodeToString
( 
    int aCC, 
    char *aOutStringBuffer, 
    size_t *aInOutStringBufferLength
);

Functionality taken over from Video System 2 videokernel library

In the following, the structures, definitions and functions which have been taken over from videokernel library of VideoSystem 2 are mentioned. For in-depth documentation please consult backed up documentation, available at Video System Website (VSv2 section).

#define FCN_NONE         0
#define FCN_AVERAGE      1
#define FCN_ENVELOPE     2 
#define FCN_SIGNIFICANCE 3

// type of file, also used as type information for data stored in a VIDINFHDR
#define TYPE_NONE_EMPTY    -1
#define TYPE_CHOOSE         0
#define TYPE_IMM            1
#define TYPE_IMC            2 
#define TYPE_BKG            3
#define TYPE_BKC            4
#define TYPE_SIGNIFICANCE   5

struct VIDINFHDR
{
	UINT32	width;
	UINT32	height;
	UINT32	bpp;
	UINT32  bpp_effective;
	
	DOUBLE	scale;
	
	INT32	numframes;
	
	INT32	type; // TYPE_

	VOID  **framebits;
	DOUBLE *framescales;
};

void initialize_vidinfhdr( struct VIDINFHDR *vinf );
void free_vidinfhdr( struct VIDINFHDR *vinf );

INT32 calculate_significance_map( const struct VIDINFHDR *signal_and_background, 
                                  const struct VIDINFHDR *background, 
                                  struct VIDINFHDR *out, 
                                  DOUBLE sigma);
                                  
INT32 convert_format( struct VIDINFHDR *vinf, 
                      UINT32 newtype, 
                      UINT32 downscale_function);

INT32 xrayfilter( struct VIDINFHDR *vinout);

INT32 normalizeframes_rect( struct VIDINFHDR *vinout, 
                            UINT32 x1, 
                            UINT32 y1, 
                            UINT32 x2, 
                            UINT32 y2 );

INT32 normalizeframes( struct VIDINFHDR *vinout);

// arbitrary, non-standard bkg file with multiple images

INT32 load_bkg_file_arb( const char *filename, struct VIDINFHDR *vinf ); 

INT32 load_imc_bkc_file( const char *filename, 
                         struct VIDINFHDR *vinf, 
                         INT32 type);

INT32 load_imm_file( const char *filename, struct VIDINFHDR *vinf );
INT32 load_bkg_file( const char *filename, struct VIDINFHDR *vinf );
INT32 load_imc_file( const char *filename, struct VIDINFHDR *vinf );
INT32 load_bkc_file( const char *filename, struct VIDINFHDR *vinf );

INT32 load_file( INT32 type, 
                 const char *filename, 
                 struct VIDINFHDR *vinf );

INT32 save_bmp_files( const char *base_filename, 
                      const struct VIDINFHDR *vinf, 
                      int fcol, 
                      int lzeroes);
               
INT32 save_imm_file( const char *outfilename, const struct VIDINFHDR *vinf );
INT32 save_bkg_file( const char *outfilename, const struct VIDINFHDR *vinf );
INT32 save_bkc_file( const char *outfilename, const struct VIDINFHDR *vinf );
INT32 save_imc_file( const char *outfilename, const struct VIDINFHDR *vinf );

INT32 save_file( INT32 type, 
                 const char *filename, 
                 const struct VIDINFHDR *vinf );

Special Information for PITZ

The Linux library (libvideosystem3.so) has been made available on PITZ library path ( /doocs/lib ( /afs/ifh.de/group/pitz/doocs/lib )). The library is provided for amd64_rhel70 platform. The include files for Linux are provided at /doocs/lib/include/videosystem3/ for amd64_rhel70 platform.

In order to perform browsing of e.g. available servers and cameras, the so-called syslist.xml file is one possibility to use. Inside this file, all video servers, all image sources (cameras) and their possible relations are encoded. In general, a syslist.xml file is optional in Video System 3. But for PITZ, this file is part of the setup, centrally distributed and maintained. You are welcome to use PITZsyslist.xml according to your needs. In clnAPI, C functions (e.g. vsGetAllRawVideoServerNames(), vsGetAllImageSourceNames()) are provided to easily get all available video servers as well as image sources (cameras).

The centrally managed and updated file (there may be outdated local copies of it around) is located at: \\win.desy.de\group\zn\4groups\zn_pitz\controls\VideoSystem\PITZ-VSv3\settings\PITZsyslist.xml .

For accessing the file easily via e.g. Linux, a copy of the file can be found on AFS at: /afs/ifh.de/group/pitz/public/video/config/PITZsyslist.xml . This file is also centrally managed and updated.

Building videosystem3.dll/.so

In general, the library should not be built by users. If no build is available for the requested platform yet, it is recommended to ask the current maintainer of the library (Stefan Weisse) to provide one. In case it is necessary and no expert (like current maintainer or initial author of the library) is available, you are encouraged to build the library yourself. Please don't forget to give feedback to the current maintainer of clnAPI (Stefan Weisse) in this case. Your build can enlarge the list of prebuilt libraries!

The source code is located inside a git repository at https://gitlab.zeuthen.desy.de/ers/avine and below. In case you are unable to access the repository, please contact us.

Footnotes:

[1] The platform dependency wrapping consist of:

system.h - a file which defines which platform is used
platform.h - header file which based on the platform define at system.h includes appropriate system header files as well as declares appropriate functions and defines macros
platform.cpp - implementation of functions declared at platform.h
The files platform.h and platform.cpp are located at VSv3 general source (git). The file system.h needs to be created and present in each project.

Note: For external use of platform.h, e.g. if videosystem3 client API is included, only minimal declarations are performed to avoid naming collisions. See defines DEFINE_VIDEOSYSTEM3_H_INTERNAL and VIDEOSYSTEM3_PLATFORM_H_EXTERNAL at the top of videosystem3.h .

Last modified: Sept 2023