intensity-tracing-py

Intensity Tracing v1.3

Logo


Table of Contents
  1. Introduction
  2. GUI Usage
  3. Long Time Acquisitions and Ring Buffers
  4. Console Usage
  5. Exported Data Visualization
  6. License
  7. Contact

Introduction

Welcome to FLIM LABS Intensity Tracing v1.3 usage guide. In this documentation section, you will find all the necessary information for the proper use of the application’s graphical user interface (GUI). For a general introduction to the aims and technical requirements of the project, read the Intensity Tracing Homepage. You can also follow the Console mode and Data export dedicated guides links.

(back to top)

GUI Usage

GUI

The GUI mode provides advanced functionality for configuring analysis parameters and displaying live-streamed photon data. It allows simultaneous acquisition from up to 8 channels, offering real-time data visualization in the form of plots:

Here a table summary of the configurable parameters:

  data-type config default explanation
enabled_channels number[] set a list of enabled acquisition data channels (up to 8). e.g. [0,1,2,3,4,5,6,7] [] the list of enabled channels for photons data acquisition
selected_conn_channel string set the selected connection type for acquisition (USB or SMA) “USB” If USB is selected, USB firmware is automatically used. If SMA is selected, SMA firmware is automatically used.
bin_width_micros number Set the numerical value in microseconds. Range: 1-1000000µs 1000 (µs) the time duration to wait for photons count accumulation.
selected_update_rate string Set the chart update frequency (LOW or HIGH) “LOW” If selected_update_rate is configured as LOW, draw_frequency is set to 40Hz. When set to HIGH, it is configured to 10Hz.
free_running_acquisition_time boolean Set the acquisition time mode (True or False) True If set to True, the acquisition_time_millis is indeterminate. If set to False, the acquisition_time_millis param is needed (acquisition duration)
time_span number Time interval, in seconds, for the visible data range on the duration x-axis. Range: 1-300s 5 For instance, if time_span is set to 5s, the x-axis will scroll to continuously display the latest 5 seconds of real-time data on the chart
acquisition_time_millis number/None Set the data acquisition duration. Range: 1-1800s None The acquisition duration is indeterminate (None) if free_running_acquisition_time is set to True.
output_frequency_ms number Set the frequency, in milliseconds (time interval between successive acquired data points in the exported .bin data file).   If selected_update_rate is configured as LOW, output_frequency_ms is set to 100ms. When set to HIGH, it is configured to 25ms.
write_data boolean Set export data option to True/False False if set to True, the acquired raw data will be exported locally to the computer
show_cps boolean Set show cps option to True/False False if set to True, user can visualize cps value (average photon count per second) on charts for each active channel


Max Points and Draw Frequency

From Intensity Tracing v.1.2, there’s a change in the calculation of max points and draw frequency on charts to prevent overload and overcrowding while maintaining real-time acquisition.

draw_frequency takes fixed values based solely on the selected_update_rate:

Similarly, the max_points value is recalibrated to ensure clarity and speed in chart rendering. It no longer depends on bin_width_micros but solely on selected_update_rate and time_span:

This recalibration on the data visualization side doesn’t affect the acquisition of all points during data reading and export in .bin format, thanks to the combination of bin_width_micros and output_frequency_ms values.


Save Parameters Configuration

GUI

Users can locally save their parameter configuration by clicking the SAVE CONFIGURATION button in the top-right corner of the GUI. The saved parameters include:

The configuration file is stored as a JSON file at C:\Users\YOUR_USER\.flim-labs\config\intensity_tracing_config.json. On application restart, the saved configuration is automatically loaded if the file is found; otherwise, a default configuration is applied.

Here an example of the saved json structure:

{
  "selected_update_rate": "HIGH",
  "selected_conn_channel": "USB",
  "selected_firmware": "intensity_tracing_usb.flim",
  "bin_width_micros": 1000,
  "time_span": 5,
  "acquisition_time_millis": 10000000,
  "draw_frequency": 40,
  "free_running_acquisition_time": false,
  "write_data": true,
  "show_cps": true,
  "enabled_channels": [1, 2, 3]
}

(back to top)

Long Time Acquisitions and Ring Buffers

The software employs ring buffers to ensure seamless long-time acquisition of photon counts. A ring buffer, also known as a circular buffer, is utilized for efficient handling of cyclic data streams.

A ring buffer is a data structure implemented as a circular array, allowing continuous and cyclic storage of data. It is particularly useful when dealing with repetitive data streams without the need to fill or empty the entire buffer at once. This characteristic makes it well-suited for scenarios requiring constant data access and management.

It’s important to note that, due to the continuous nature of long-time acquisition, the system may consume a significant amount of RAM. In practice, for extended acquisition sessions, we estimate a potential consumption of up to 4 gigabytes of RAM. Users should be mindful of their system’s memory capabilities to ensure smooth operation during extended experiments.

(back to top)

Console Usage

For a detailed guide about console mode usage follow this link:

(back to top)

Exported Data Visualization

The application GUI allows the user to export the analysis data in binary file format. For a detailed guide about data export and binary file structure see:

(back to top)

License

Distributed under the MIT License.

(back to top)

Contact

FLIM LABS: info@flimlabs.com

Project Link: FLIM LABS - Intensity Tracing

(back to top)

This site is open source. Improve this page.