GSL - Get Sequence Library

- Overview and Release Notes -

first revision from August 2006

second revision from October 2006
(added proper effective bits per pixel handling and calculation of significance map)

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.
Also ROOT-code is not capable to use significance map calculation up to now!
-- sw, oct 10, 2006


Table of Contents


 

Overview

The 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

DirectoryContents
docDocumentation
includeinclude (header) files for any platform
srcsourcecode for all worlds
unixUnix example code, makefile
rootROOT example code
winWindows example code, MS Visual C++ 6 project and workspace
 

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.
The example code inside main.c is shown for reference and may not work (just because the test server to acquire frames from is not running by accident). The second makefile (standalone_d.mak) creates an executable with debugging information. This code was tested and proved to be working on 64-bit Linux.

 

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   5 
These 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   3 
These 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:

Structure memberExplanation
UINT32 widthdefines the width in pixels of the contained image(s)
UINT32 heightdefines the height in pixels of the contained image(s)
UINT32 bppdefines the physical bits per pixel for each pixel (8, 16 or 32)
UINT32 bpp_effectivedefines the effective bits per pixel for each pixel (8, 12, 14, 16, ...)
DOUBLE scaledefines the scale value of all image(s)
INT32 numframesdefines the number of frames (images) inside the file (1..n)
INT32 typedefines the type of the file that has been loaded in (or TYPE_NONE_EMPTY) if the structure is empty
VOID **framebitsnumframes pointers to one dimensional arrays[width*height*bpp/8] that contain the frame bits (data)
DOUBLE **framescalesnumframes pointers to a DOUBLE value containing the scale value of the frame in question

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:
Imagine a image rectangle on screen. The image is stored in the array from top to bottom, line by line from left to right, pixel by pixel.


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:
servername[in]hostname of grab server
port[in]port of grab server
num_frames[in]number of frames to grab as sequence
vinf[out]empty VIDINFHDR where the acquired frames will be returned

The return values and their meanings are:
  • general return parameters
    • 0 all fine, all frames have been acquired
    • -1 unable to create socket
    • -2 unable to get hostname / malformed ip address
    • -23 vinf structure was not passed empty, please clean up the structure first
  • errors that might be emitted by connect() call
    • -3 EADDRNOTAVAIL
    • -4 EAFNOSUPPORT
    • -5 EALREADY
    • -6 EBADF
    • -7 ECONNREFUSED
    • -8 EINPROGRESS
    • -9 EINTR
    • -10 EISCONN
    • -11 ENETUNREACH
    • -12 ENOTSOCK
    • -13 EPROTOTYPE
    • -14 ETIMEDOUT
    • -15 EADDRINUSE
    • -16 ECONNRESET
    • -17 EHOSTUNREACH
    • -18 EINVAL
    • -19 ENAMETOOLONG
    • -20 ENETDOWN
    • -21 unknown error at connect statement
  • Errors that may happen after a successful connection attempt
    • -22 unable to switch to nonblocking mode
    • -24 could not receive video header stream
    • -25 could not receive frame data: timeout
    • -26 could not receive frame data: other errors
    • -27 unable to allocate memory location needed for storing frames
    • -28 frames are not in a sequence
    • -29 camera port change has happened during frame receive
    • -30 could not allocate memory for compressed frame bits
    • -31 could not translate vidhdr_stream into VIDHDR

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:
vinf[in/out]VIDINFHDR containing multiple images [in]
VIDINFHDR containing the resulting buffer(s) [out]
newtype[in]new type inside VIDINFHDR (one of FILE_IMM, FILE_IMC, FILE_BKG, FILE_BKC)
downscale_function[in]if the resulting format will be FILE_BKG, a downscale function must be passed in order to recalculate the contents. either FCN_AVERAGE or FCN_ENVELOPE might be passed. In any other case one must pass the FCN_NONE statement.
The return values and their meanings are:
  • 0 okay, everything fine
  • -1 inappropriate 'type' inside vinf structre
  • -2 inappropriate 'type' parameter passed
  • -3 downscale function selected which does not fit to passed structure and resulting type
  • -4 convert to bkg, downscale function was NOT specified
  • -5 unsupported bits per pixel settings inside vinf (using downscaling)
  • -6 memory allocation error (out of memory, using downscale to bkg)

Remarks:
In any error case the vinf is not touched and the old data remains inside (without corruption) !
FCN_AVERAGE: averaging each frame pixel over the number of frames (average noise rules)
FCN_ENVELOPE: the maximum value of each pixel for all frames is obtained and stored as bitmap (max noise rules)


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:
sig_and_back[in]VIDINFHDR containing multiple images containing signal and background
back[in]VIDINFHDR containing multiple images containing just background
out[out]VIDINFHDR that will contain the significance map after the function was successfully called
sigma[in]arbitrary factor for significance of rms of noise, default=1.0, if bigger then rms noise significance is increased
The return values and their meanings are:
  • 0 okay, everything fine
  • -1 VIDINFHDR out was not passed uninitialized
  • -2 sig_and_back must at least contain 2 frames
  • -3 back must at least contain 2 frames
  • -4 sig_and_back, back must contain the same number of images!
  • -5 bitdepth, effective bitdepth, width or heigt of back and sig_and_back were not set to equal values (important)
  • -6 memory allocation error, no data was changed (in out)
  • -7 data error (unsupported bpp (physical value) for algorithm)

Remarks:
In any error case the vinfs are not touched and the old data remains inside (applies for any passed variable) !
The out vidinf structure must be passed uninitialized, otherwise you will get an error. Best is to use initialize_vidinfhdr before passing it to this function.


Last modified: August 23, 2006