AVINE Video Client 3

Quick Reference

2023-06

Table of Contents

• Overview
• What's new
• Features
• Menu description
• Toolbar


• Zoom Panel
• Histogram Panel
• Side Panel
• False Color Table Panel
• Integrated TINE Server (Calculations) Panel
• Crosshair



• Keyboard shortcuts
• Special Mouse functions
• File formats
• Preferences


• Further References

Overview

The Video Client 3 is a fast versatile video display and analysis tool used to monitor, taking and analyzing data that is produced by image sources, such as video cameras. The Video Client was originally written for monitoring and measurements at Photo-Injector Test Facility Zeuthen (PITZ). But it is made in a generic way so that it is also useful for other use cases.

Brief list of possibilities:

• receive live video as well as take sequence of video images from live sources
• monitor what is going on (see electron beam, see laser beam, see dark current, see diagnostic devices in the beam pipe)
• online-analysis of the beam images (spot size, position, shape, ...)
• optimize the beam image quality before data is taken and stored permanently
• do manual data-taking
• do semi-automatic data-taking (control of laser shutter)
• correlate behaviour between spot-size, position and shape and "moving" experiment parameters (Online-DAQ)

Figure 1: Main Application Window

(click to enlarge)

What's new (2022-04)

• loading and saving to IMC2/BKC2 file format
• application is now 64-bit

Features of the program

• Spot position and size calculation using Fourier analysis
• Spot position and size calculation using Straightforward statistics (mean and RMS values)
• False color (PITZ False color, MATLAB JET-like, etc.) and grayscale mode
• Projections of the video signal (in X and Y)
• Printing of video image displayed, as well as the whole program window
• Live video-mode (polling)
• Acquiring sequence of images (grabbing)
• Saving and loading of raw images and backgrounds using application-specific (IMC2, IMC, IMM) and widely used format (Windows BMP)
• Background subtraction
• Acquiring backgrounds using grab single background, add to background, envelope background and average background
• Snapshot mode (video snapshot to BMP file)
• Automatic acquire of certain control system properties (parameters of the experiment) for simplified correlations (so-called Online DAQ)
• Automatic acquire of certain control system properties in order to save side-by-side (.txt file) to video frame(s)
• Scaled values (instead of pixel values obtain results directly in millimeters)
• Image preview on loading files
• Semi-automatic datataking of background and signal frames (called: GrabAndSave), interfacing of some shutter, e.g. Laser shutter
• X-Ray filtering
• Zoom Panel
• Histogram Panel
• False Color Table Layout Panel
• Selectable area of interest, either circular or rectangular (all calculations are only done there and not on the whole video frame)
• Integrated TINE server for live export of calculation results to e.g. Matlab (via xcomm MEX file)
• Crosshair (user-defined), to outline region in video which is of special interest, e.g. target position
• Free field on toolbar with the following implemented functions
• Sum of Pixels, in AOI (Sum of pixel values inside area of interest)
• Cooked Value under Cursor (pixel value under mouse cursor (cooked: background subtracted, normalized))
• Z mean, in AOI (Mean value of pixel values inside area of interest)
• Z rms, in AOI (RMS value of pixel values inside area of interest)
• XY Correlation Coefficient, in AOI (-1..1)
• XY Tilt, in AOI (Tilt factor of pixel shape, inside area of interest)
• XY Angle of Regression Line, in AOI [°]
• Number of saturated raw Pixels, in AOI (number of raw (before background subtraction, normalization etc.) pixels inside area of interest with maximum value)
• Number of distinct raw Pixel Values, in AOI

More technical:

• Works over Remote Desktop (Microsoft Remote Desktop Connection, VNC)
• Compatible with Multi-Monitor setups
• Video frame transfer from server to Video Client 3 can use multicasting (configurable)
• XML config file with speaking names
• Video System 3 video data interface (compatible with Video System 3 sources)

Menu description and quick reference of functions

Footnotes:

[1]	In addition, the area of interest (AOI) is automatically reset to the biggest one possible. For rectangular AOI, the AOI will span the whole image dimensions.
[2]	If using grayscale color mode, problems observing weak signals could appear. The gray scales are linear distributed across the bit-depth of the pixels of the image. Depending on the capabilities of the monitor, only a fraction of the possible gray scales are shown physically. Dark gray tends to vanish into black.
[3]	PITZ false color mode was designed for improved recognizablity of weak signals in comparison to grayscale. In addition, distinguishing between low, medium, high and saturated intensity is much easier with it. Black means no, blue means weak, green means medium, red means strong and white means saturated signal.
[4]	PITZ false color mode (MSB white) is identical to PITZ false color mode, except that by setting 'False Color MSB White' (few bits), configurable via Side Panel dialog, some most significant bits can be set to white color, while downscaling the blue, green and red parts of the color map to the remaining bits of the video image.
[5]	The colors are drawn like in MATLAB if JET color table is used. Slight finetuning has been performed so that the maximum (saturated) intensity of the displayed data is shown as white.
[6]	The colors are drawn like in MATLAB Plasma color map, refined for laser work by Christian Koschitzki (CK).
[7]	The colors are drawn like in Labview Gradient color map, refined for laser work by Christian Koschitzki (CK).
[8]	If there are multiple video frames in the buffer, first of all the value is calculated for each individual frame in the buffer. Then the individual values are averaged. What is shown in the field is the averaged value.
[9]	Please note that X-Ray filtering and background subtraction are performed before the value is calculated. So if these algorithms are in effect, they may alter this value! In contrast, normalization is performed after the value is calculated, so applying normalization does not influence this value.
[10]	Please note that X-Ray filtering, background subtraction and normalization are performed before the value is calculated. So if these algorithms are in effect, they may alter this value!
[11]	Please note that this value is only calculated if statistics mode is switched to straightforward or fourier.
[12]	Dedicated documentation on XY Correlation Factor, Tilt and Angle of Regression Line is available on the Video System website.
[13]	Any algorithm applied on a sequence of images is designed to perform best if there are no images lost in-between (so-called dropped frames) while recording the sequence. Due to shared resources like network bandwidth, drops may occur. The Video Client 3 will present a warning in this case. Also in rare cases it may happen that the image source is changed on server-side while the Video Client 3 records a sequence. Such events will be detected and an error message will be shown. As the recorded sequence is considered useless in this case, the sequence will be discarded.

Toolbar

Description of the Zoom Panel

The zoom panel shows a magnified or demagnified part of the video image that is displayed on the main application window. The zoom factor can be chosen from 1 to 1000% (10:1). Some predefined zoom steps are selectable in the combo box on the left of the tool bar (top row of the zoom panel). To the right of the combo box, one can see which zoom factor is currently set. Using the second feature (from left to right) on the tool bar, one is able to choose whether or when decorations (mouse cursor axis, spot size and centre) are drawn on top of the scaled pixels. One can choose between On (Always draw the decorations), Off (never draw decorations) and Mouse (draw decorations if mouse pointer is inside zoom panel's video area). The third feature on the tool bar, called 'Always follow Mouse on Main Video Area', changes the Zoom Panel into a magnifying glass. If the checkbox is checked (alternative: one can press SHIFT key while moving mouse on main application window's video area), the scaled video area follows the mouse cursor in the main application window's video area.

Description of the Histogram Panel

On the histogram panel's x-axis, each pixel intensity value which can be present in the image, is shown (from no intensity to maximum intensity). On the y-axis, the number of pixels that share the same pixel intensity value, are plotted. Note that only pixels inside the area of interest are taken into account for calculating the histogram. In case that only a certain portion of the histogram values are used throughout the image's pixel values, the x-axis may be displayed discontinued. In that case, the lowest and highest index shown is displayed in red color at the x-axis.
In case of significant under and overexposed images, one is able to cut (remove) the lowest and highest index value from the histogram display, as in such case the number of pixels with those index values can be much more than numbers of other pixels values. Removing them from display can improve visibility of other histogram indices.

Description of the Side Panel

Footnotes:
[1]	The data formats the Video Client 3 supports are: Gray8 (maximum 8 bits per pixel) and Gray16 (maximum 16 bits per pixel). In addition to the format, the effective bits per pixel currently set are shown. For example there exist Gray16 EBitPP=12 which means 16 physical bits per pixel, but the image source is only able to deliver 12 bits per pixel. The remaining 4 bits are not used and will not go into calculations. Only the effective bits are taken into account.
[2]	There are two types of Areas of Interest: Rectangular and Circular. The rectangular area of interest is defined by its bounding rectangle pixel positions left(l), top(t), right(r) and bottom(b). The circular area of interest is defined by its centre point (cx, cy) and its radius (r). There is always an area of interest set inside Video Client 3. The biggest rectangular area of interest spans the whole image dimensions. The biggest circular area of interest is a circle which is restricted to the image dimensions.
[3]	The setting is volatile. It will be lost if Video Client 3 is closed.
[4]	The current delimiter and decimal point for CSV files are tried to be obtained from Windows regional settings. Furthermore they can be specified in videoclnt3-config.xml. The config file takes precedence over what was obtained from Windows regional settings.

Description of the False Color Table Panel

In the False Color Table Panel, the currently selected false color table can be inspected. The false color table is displayed as a thick horizontal bar-like stream of colors from lowest color index (LS: Least Significant) to highest color index (MS: Most Significant) [1]. The thick horizontal bar consists of thinner vertical solid bars, one for each color index.

Using the toolbar, the layout of the false color table can be adjusted to ones needs. One is able to set an absolute thickness (width) of each unique color bar or fit the color table to the width of the panel. In addition one is able to add segmentation bars in between each color bar (thin vertical lines). The thin vertical color bar below the mouse cursor, while one is moving along the big horizontal color bar, is displayed in greater detail on the right hand side of the toolbar. The pixel index, the color itself and the RGB triplet (range of each component is from 0.0 to 1.0) are shown.

Note: If the width of the big horizontal color bar is smaller than the width of the window, the bar is scaled to fit the window width. If the width is bigger than the width of the window, the horizontal scroll bar is enabled.

Description of the Integrated Tine Server (Calculations) Panel

In the Integrated TINE Server (Calculations) panel, one is able to adjust the TINE port offset. On a single computer, each TINE server needs to have its unique port offset value. If multiple instances of Video Client 3 (with integrated TINE server enabled ) will be run on the same computer, each Video Client 3's integrated TINE server needs an unique port offset.

The TINE context name cannot be automatically adjusted in Video Client 3. It can however be adjusted in videoclnt3-config.xml configuration file. For details, please consult further references.

The TINE server name is automatically created based on the fixed string VIDCLN3_NR, the Port Offset value (incremented by one), the fixed string _at_, and the name of the computer (znnomos58 in this example as shown on the screenshot).

The FEC Name is automatically created based on the name of the computer (znnomos58 in this example), a dot, and the currently chosen port offset (zero in this example).

The button [Enable] is crosslinked to the button with the same name on the toolbar, and can be used to enable or disable the integrated TINE server.

Description of the Crosshair

(click to enlarge)

The crosshair is a user defined feature in order to outline a position in the video image, useful e.g. for showing a target position or for alignment. It can be enabled/disabled by a toggle-button on the toolbar (lower right), or via menu Application->Crosshair (user-defined). The crosshair is shown as yellow vertical / horizontal yellow lines with a gap where the lines cross each other (the outlined crosshair position). One must note that when crosshair mode is enabled, the calculations mode (i.e. the yellow cross outlining position and size of the beam spot on the image (if there is a beam spot) will be switched off. One needs to re-enable calculations mode by hand, for example by pressing F3 for straightforward (means and RMS values) calculations.

The crosshair position can be moved by pressing CTRL key and moving the mouse above the video area. Fine adjustment of position can be done via CTRL key and arrow keys. Note that, when not in crosshair mode, CTRL+arrow-keys will move the area of interest instead.

On the side panel, the current position of the crosshair, individual for X and Y, is shown. The values are in percentage, according to the coordinate system displayed at the right hand side of the toolbar. Zero is the center position of the image, -100% is right/bottom, +100% is left/top. A tooltip is shown if one moves the mouse in Side panel over the input boxes / values. In the input boxes, one is able to enter percentage values by hand (dot is decimal point). In addition, the middle gap, where x and y axis cross each other, can be switched on or off. The size of the middle gap can be adjusted, too.

Keyboard-shortcuts

Mouse functions

File Formats

In this section, the different file formats used by the application are briefly explained.

Preferences Dialog

For advanced users and experts, there is an xml configuration file where one can find many advanced adjustment possibilities.

Further References

AVINE Video System homepage:	https://avine.desy.de
Video Client 3 section on AVINE homepage:	https://tine.desy.de/VideoSystem/vsVideoClient3.shtml