GSL - Get Sequence Library- Overview and Release Notes -
second revision from October 2006 created by Stefan Weisse Note! A lot of the documentation might not be up to date. Also X-ray filtering is not yet included. It will be changed in the near future. Table of Contents
OverviewThe Get Sequence Library (GSL) was designed for users of the PITZ Video System in order to be able to acquire live image sequence of any camera. It uses the VideoFileLoad library (VFL) version 2 in order to use its defined structures (VIDINFHDR), buffer management and ability to load and save any Video Client 2 file format (except BMP). The library was written in such a way that it is instantaneously possible to use it on Linux32, Linux64, Win32 and ROOT (32 and 64 bit) platforms. It may work on any other Little-Endian based platform with little adjustments. To not be confused by the terminology, one should know that the term library in this document means a set of source code and header files to be used on many platforms. One may create by hand a shared library (.so) for Scientific Linux 3 (SL3) or a shared library (.dll) for Windows operating system using Visual C++ v6. These steps are not provided. The examples for Linux and Windows show how to integrate the five main source files (platform.c, getframes.c, getframes.h, decompression.c, platform.h) and required files from VFLv2 into example projects. For ROOT v4/v5 a makefile in order to create a shared library for loading into ROOT C interpreter (CINT) is provided as example. The library is expected to compile and link without errors on Linux, ROOT (v4, v5) and Windows. It was tested with Visual C++ V6 SP6, GCC on Scientific Linux 3 (SL3) and using ROOT v4.02.00 under Linux (SL3). The flawless execution on a 64-bit platform was tested under Linux. Note: The library is only compatible with platforms that use Little-Endian byte ordering, like Intel X86 processors. Sourcecode has to be changed in certain positions if the library is going to be used on Solaris (e.g. using SPARC CPUs with Big-Endian byte ordering). Directory Contents
Linux (gcc on SL3)
Using the supplied makefile standalone.mak (make -f standalone.mak) one should be able to compile the example code
without errors or warnings on SL3. The result will be an executable file getsequence which should be working. Root v4/v5 on Linux
Using the supplied makefile rootlib.mak (make -f rootlib.mak) one should be able to compile the example root library
without errors or warnings on SL3. It is a good idea to clean the current directory first (make -f rootlib.mak clean).
It might be possible that the makefile needs to be adjusted (see commented-out ROOTSYS line) if the ROOTSYS variable is missing
in the environment or points to a wrong installation. The second makefile (rootlib_d.mak) creates a library with debug info.
This code was tested and proved to be working on ROOT_64 under 64-bit Linux. The result of making will be a root shared
library file getframes.sl which can be loaded into Root interpreter and tested by using the following sequence: $> root root [0] gSystem->Load("getframes.sl"); root [1] .X rootexample.CXX Note: The example code inside rootexample.CXX is shown for reference and may not work (just because the test server to acquire frames from is not running by accident). Windows (MS Visual C++ v6)
After starting MS Visual C++ v6, one should load in the workspace file. All pathes should be
relative so directly compiling and linking without any warning or error should be no problem.
The library and the provided example code was written to compile and link without a single error
even at highest warning level !
If this does not work, one may check the include pathes as well as the output pathes for
correctness. It is also a good advise to check the supplied files for read-only attribute and
clear it in case it is set.
The result will be an executable file getsequence.exe which should be working. API reference
Variable type mappings typedef int INT32; typedef unsigned int UINT32; typedef double DOUBLE; typedef char CHAR; typedef void VOID; typedef unsigned char UCHAR;In order to meet certain platform independent criterias, C variable data types are mapped to unique names inside the programming interface. Type reference #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 5These types are used to set and define the file types. TYPE_NONE_EMPTY is used to declare a VIDINFHDR to be empty. #define FCN_NONE 0 #define FCN_AVERAGE 1 #define FCN_ENVELOPE 2 #define FCN_SIGNIFICANCE 3These types are used to pass appropriate a downscale function when converting a multiple image buffer to BKG file format. Structure reference struct VIDINFHDR { UINT32 width; UINT32 height; UINT32 bpp; DOUBLE scale; INT32 numframes; INT32 type; // TYPE_ VOID **framebits; DOUBLE *framescales; }; The structure VIDINFHDR is used in memory to describe and define a set of single images that were loaded from a file or are about to be saved. The parameters are explained in detail:
In principle an image set is defined that all images have the same width, height, bpp, bpp_effective and scale values. The value scale is used as an easy way to access the scale value. The framescales values are only used for the sake of completeness and all of them should contain the same value as scale !
A one-dimensional array is the physical representation of the two-dimensional image data.
The data is organized inside the array in the following scheme: Function reference INT32 grabframes( const CHAR *servername, const UINT16 net_port, UINT32 num_frames, struct VIDINFHDR *vinf); In order to acquire frames from any GrabServer2 program running, one should use this function. It is blocking and returns if either one of the error conditions is met or all frames have been acquired successfully. The parameters are:
The return values and their meanings are:
Remarks: Any error after a successful connection attempt alters the vinf structure. INT32 convert_format( struct VIDINFHDR *vinf, UINT32 newtype, UINT32 downscale_function); This function is used to conveniently convert between different formats inside a VIDINFHDR. Most conversions are lossless, however, conversion of a VIDINFHDR with multiple images to FILE_BKG will be lossy because a downscale function is required and will be used. The parameters are:
Remarks: INT32 calculate_significance_map( const struct VIDINFHDR *sig_and_back, const struct VIDINFHDR *back, struct VIDINFHDR *out, double sigma); This function can be used to calculate a so-called significance map of two sets of matching frames (signal and background images). In case of no error, the resulting VIDINFHDR out will contain a single image with the same physical bpp as sig_and_back and back. A value of 0 means that the signal value at that position should be masked out (not significant). A value of 1 means that the signal value at that position should not be masked out (significant data). Using sigma (default value is 1.0) one is able to increase the significance of RMS of noise. Sigma is used as a factor to RMS. The bigger sigma gets, the more the rms of noise will increase and thus, more parts of the signal might be filtered out. The parameters are:
Remarks: |
Last modified: August 23, 2006 |