Home

XiLens /ksɪlɛns/

Welcome to the XiLens /ksɪlɛns/ wiki!

This wiki is dedicated specifically to documenting how the graphical user interface (GUI) of XiLens can be used. If you are looking for the general documentation of this application, you should look in our official documentation.

The entire GUI is populated with tool tips, whenever you are in doubt about what certain part of the GUI does, simply hover over it with the cursor, a message will appear indicating what that components does.

Landing view

When you first launch the application, you will be presented with the following application. The application is sorted into different tabs, where each tab contains grouped components that have been categorized depending on their intended use.

Menu bar

From the menu bar, you can access general information and tools of the application. The following components are included in the menu bar.

1. Help: From this menu, you can access a link to the documentation, information on how to cite the application and the "about" section that contains general information about the application that can be useful when debugging issues.

Main GUI tabs

The application is structured into the tabs displayed in the left side of the application. You can access each of these tabs by clicking on the vignettes displayed along the left borded of the application. At the moment, the following tabs are available.

The RECORD tab contains all the controls and viewers related to recording new images or videos, while the VIEWER tab contains controls designed to visualize already recorded data.

RECORD tab

This tab contains all components needed to start and stop video recordings, adjust data acquisition parameters like integration time, log messages to a file, or adjust the view of the images that are gathered from each camera.

Notice that in the middle of the GUI there is a handle that can be dragged left or right to hide the left control panel when desired.

Selecting a camera

Initially, many components are disabled because there no camera has been selected. You can select the camera you want to use by clicking the dropdown menu on the top left of the GUI.

Once the camera is selected and the connection to it has been established, the corresponding UI components will be enabled. If you connect a camera to your computer after the application has been started, it will not be displayed in the dropdown menu. To scan all cameras connected to the computer, you can press the reload button, this might take a couple of seconds to finish.

File saving paths

In order to save images or videos, you first have to define the folder where the data is to be stored, and the file name through the following dialog. The recorded files are stored with a pre-defined file extension, by default, files are stored with the .b2nd file extension. These fields cannot be modified while recordings are taking place.

Exposure time and skip frames

The speed at which images are recorded depends on several factors like exposure time, how many frames are skipped between consecutive saving operations, and the type of hard drive (SSD vs. HDD). The exposure time particularly regulates for how long and image is collected by the sensor before it is read from the sensor. Higher integration times lead to higher image intensity. This value can be specified through the GUI in milliseconds by controlling the value in the spin box.

In certain situations, you might want to keep the integration time relatively low (e.g. 40 ms), while at the same time not wanting to record data at video-rate, for example while recording over many hours where only one image per second is required. This can be achieved by specifying the number of skip frames. This value indicates the number of images that are ignored (not saved to file) in between consecutive saving to file operations. As a rule of thumb, the desired frame rate (indicated at the bottom of the GUI) can be estimated by:

$$fps \approx \frac{1000ms}{(skip \textunderscore frames + 1) \cdot integration \textunderscore time}.$$

Keep in mind that the rate at which images are displayed in the GUI is not altered by the skip frames. The rate at which images are displayed is approximately $fps \textunderscore {display} \approx 1000ms / integration \textunderscore time$.

Logging messages

Messages can be logged directly from the GUI. This can be very helpful to log any event that might be of interest during each recording. Each message is time-stamped and stored to the file called logFile.txt that is stored in the samve folder where the data is being recorded to. Messages can be recorded at any time to the file logFile.txt. The time stamps stored in the file logFile.txt are in the same format as the time_stamp stored in the image.schunk.vlmeta property of each .b2nd file.

Image viewer

Almost all image-related controls both for display and recording are arranged in the tool bar with different buttons. The images gathered from the camera are displayed in two main displays, the top one corresponds to the raw image, white the bottom one corresponds to either the true RGB image or merely a reconstruction depending on the camera type. Notice that between both displays there is a handle () that can be dragged up or down to hide each display if desired.

• Record video: This button controls the start and stop of a video recording sequence. To stop an undergoing video recording, simply press this button again. The video sequence is stored in the file path indicated in the main GUI dialog (left side of the GUI).
• Record snapshots: This button triggers the recording of a pre-defined number of images to a file. To control the name of the file to store snapshots and the number of snapshots, click on the bottom right arrow of the button. IF the name of the snapshot file is the same as the name of the file indicated in the main GUI, an error window is displayed. To prevent data corruption, snapshots are not allowed to be stored in the same file where videos are meant to be stored.
• Record white reference: Triggers the recording of a white reference. The camera should be adjusted to image a white target such as Spectralon. 100 images are recorded to a file called white in the folder indicated in the main GUI dialog. The progress bar in the status bar indicates the progress of this operation. If this button is pressed again, a new file is created with the same name suffixed with an integer value higher than the previous one encountered in the same folder.
• Record dark reference: Triggers the recording of a dark reference. The camera lens should be covered such that no light reaches the sensor. The behavior of this button is equivalent to the one of record white reference.
• RGB image bands: This button is only activated for spectral cameras, where an RGB image reconstruction is not trivial. By clicking on it, a dialog appears that controls the spectral image channels that are used to reconstruct an RGB representation of the image.
• Image brightness: This button controls the RGB image brightness. When clicking on it, a slider appears that controls the level of image intensity, the value displayed in the slider is arbitrary and might change in future releases.
• Band selector: This button is only activated for spectral cameras, where a single channel image channel is usually desired to be displayed. When clicking on it, a slider appears that controls the image channel to be displayed.
• Image normalization: This button controls whether to apply image histogram normalization or not.
• ![image](https://github.com/user-attachments/assets/9147a8eb-861c-47fa-b4a3-8d379fbde6e9 "Auto exposure) Auto exposure: This button controls whether the image exposure should be automatically controlled by the camera.
• Image saturation: This button controls the color and the min and max values used for determining which pixels are under-exposed and which are over-exposed. To control these parameters, simply click on the bottom right arrow of the button. Notice that both the min and max values should be of in int8 type because the colorization is only done in int8 images used for display. By default, images are recorded to file in int16 format, so you should make the appropriate conversion of the min & max values for the display. For example, if a camera records data in 10bits (max value of 1024), and you would like the over-exposure limit to be 1000 counts, you should set the max value to $max = 1000/10^2$.

The colorization of each pixel is done in a parallelized manner. However, it has a relatively high computational cost for some CPU architectures. If you notice that the application is slow on your computer, try to click in the center of this button to deactivate pixel saturation display.

VIEWER tab

This tab contains all the components needed to visualize either previously recorded files, or files that are currently being recorded.

To display a previously recorded file, or one that is currently being recorded, you should press the SELECT FILE button. A file dialog will be displayed from which you can select a file to display. Alternatively, you can write the path to a file in the line edit field and press the RETURN key in your keyboard. While you write the file path, the color of the line edit will change to indicate that the changes have not taken effect. The color will reset to it's default once you press RETURN. If the file path does not exist or cannot be read, the color of the line edit component will remain in the invalid state (usually a lila color). If the file is successfully opened, the slider is activated. You can drag the handle of this slider to scroll through the recorded images.

The file is only opened once at the beginning, which means that if changes to the file occur while you are viewing it, such changes are not reflected immediately. To load the changes to the file, for example if you are currently saving data to the same file, you can either press the reload button (button with reload arrow), or press click on the line edit component and then press RETURN. Once the file is reopened successfully, the slider will be updated to reflect the correct number of images in the file.

Status bar

The status bar is only used to display useful information regarding the camera status, image-related statistics, and recording progress.

• Progress bar: The progress bar is only activated when recording data that has a pre-defined number of images to record. For example recording a white & dark reference, or when recording a specific number of snapshots.
• Temperature: The camera temperature is queried from an independent thread at regular time intervals and displayed in the status bar in centigrade. This temperature is also stored in the metadata of each .b2nd file.
• Exposure indicators: The exposure indicators are estimates of the percentage of pixels in an image that are over-exposed (values above a certain value) or under-exposed (values below a certain value).
• Nr. images: The number of images displayed in the status bar indicates how many images have been stored in total during each recording session. A recording session is defined as from the moment the application is started until the application is closed.
• FPS: The frame rate displayed in the status bar corresponds to an estimate of the number of frames per second that are being stored to file. This is computed by measuring the time it takes to record a certain number of images to file. The text label next to the LCD display indicated an estimated frame rate calculated only based on the exposure time and the number of skipped frames. The LCD display is only updated while recording a video, since the computation is done live.
• Time: The time corresponds to the time that the current recording has taken. This display is reset when pressing the stop button.