Skip to content

Home

Jump to bottom
Mattia D. edited this page Oct 2, 2024 · 16 revisions

BrightEyes-MCS

BrightEyes-MCS, a Microscope Control Software for image-scanning microscopy designed by the Molecular Microscopy and Spectroscopy group of the Italian Institute of Technology.

docs_video_brighteyes-mcs.webm

Click on the video

Development Notice

Important: This software is currently under active development and may contain bugs or incomplete features. Please use it with caution and report any issues you encounter to help us improve the application.

Main Features

  • Realtime preview
  • Support up 25 digital channels (SPAD array) + 2 "extra" channel
  • Support up 2 analog channels (PMT)
  • Pan & Zoom in realtime
  • Scan along each axis and XYZ multi-stack
    • (Supported up to 3 linear voltage-controlled actuator i.e. galvo mirror or piezo-stage)
  • Time lapse / Macro
  • Data saved in HDF5:
    • Multi-dimensional [repetition, z, y, x, t_bin, channel] array.
    • Metadata (current configurations, extra information, users comments etc etc).
    • The data can be analyzed a visualized directly with Napari (through Napari-ISM plugin) just by a few click
  • The pixel is subdivided in temporal bins:
    • Normal acquisition down-to:
      • 0.5 us for USB hardware
      • 0.25 us for Chassis Thunderbolt configuration
    • Histogram TCSPC, via Digital Frequency Domain techniques
      • 0.4 ns for bins
  • Integrated Jupyter Python Console for inspecting or acting on the running program
  • Plugins / Scripting in Python
    • Automatic grid analysis for calibration
  • Fluorescence correlation spectroscopy Preview
  • Integrated with BrightEyes-Time Tagging Module

Moreover, it can be integrated with the BrightEyes Time-Tagging Module. This module allow to perform single-photon time-tagging microscopy therefore fluorescence spectroscopy, fluorescence lifetime imaging microscopy (FLIM), and fluorescence lifetime correlation spectroscopy (FLFS) experiments.

image

Requirements

Software

  • Windows OS x64
  • Python 3.10
    • Or winget install -e --id Python.Python.3.10
  • Git
    • Or winget install -e --id Git.Git
  • FPGA drivers installed,
  • A C compiler installer, either
    • GCC MSYS2 (winget install -e --id MSYS2.MSYS2)
    • or Microsoft Visual Studio with C++ build tools.
  • Display resolution >= 1920×1080 (FullHD)

Hardware

BrightEyes-MCS supports only FPGA from NI. At the moment the bitfile are built for the following boards.

Type Board Extra req. Tested
1 NI FPGA PXIe-7856 (Single-board) NI Chassis + NI Thunderbolt Full supported, currently in use in our lab
2 NI FPGA USB-7856R (Single-board) - Full supported, currently in use in our lab
3 NI FPGA USB-7856R OEM (Single-board) - Should work but not fully tested
4 NI FPGA PXIe-7822 + NI FPGA PXIe-7856 (Dual-board) NI Chassis + NI Thunderbolt Full supported, currently in use in our lab
4 NI FPGA PXIe-7822 (Single-board) NI Chassis + NI Thunderbolt + External DAC required Full supported, currently in use in our lab
5 NI FPGA PCIe-7820R External DAC required Full supported, currently in use in our lab

Warning!! To avoid any damage of your equipment, please verify that the pinout described in I/O Table are compatible with your actual system.

Input & Output connections

The I/O table depeands by the firmware. The tables are available on the documentations of BrightEyes-MCSLL

Getting started

Installation

There are two possibility:

  • Download the Zip of the repository and extract it where you prefer
  • Or clone the repo:
    • git clone https://github.com/VicidominiLab/BrightEyes-MCS.git

Python 3.10 and the MSYS2 or Visual Studio C++ MUST BE installed before run the installer!

From the cmd.exe (NOT powershell!)

cd BrightEyes-MCS
install.bat

and following the instructions on the terminal. Once installed you will have the link with icon of BrightEyes-MCS and on your Desktop.

Example of usage

Minimal Configuration

Firmware selection.

image

The firmware must be chosen according to your hardware. Please check from BrightEyes-MCSLL documentation.

In the bottom-left panel select the tab "Adv." then the internal tab "Board configuration". Here you can select the "FPGA BitFile" and the "FPGA Addr.".

The FPGA address is defined by the NI Driver configuration. If you have only a single FPGA the default is "RIO0". You can check it by using using the NI tool named NI MAX.

In the case you need to use a second NI FPGA acting as DAC/ADC ("double-board" firmware) please select in "FPGA 2nd BitFile" and "FPGA 2nd Addr." board, respectivily the firmware and the address of the board which have the analog IN/OUT. In case you do not use a "double-board" firmware "FPGA 2nd BitFile" and "FPGA 2nd Addr." must be let empty.

Calibration

image

In the bottom-left panel select the tab "Adv." then the internal tab "Calibration". Here you can set the calibration factor (µm/V) for each axis of your microscope.

Voltage Ranges

image

In the bottom-left panel select the tab "Adv." then the internal tab "Limits". In the section "Set Voltage Ranges" you can set the voltage hardware limit of your positioning system.

In the section "Offset" you can set the voltage offset of the center of your positioning system. (Some piezo stages can have the center at +5V instead other ones have it a 0V.)

PLEASE TO AVOID HARDWARE DAMAGE PLEASE SET THESE PARAMETERS ACCORDING YOUR HARWARE

Destination Folder

image

In the bottom-left panel select the tab "File". Here you can set the destination folder.

It is suggested to let the filename set to "DEFAULT.h5": this create automatically a filename with date and time like "data-30-12-2023-16-22-45.h5".

Save the default configuration

image

REMIND TO SAVE YOUR DEFAULT CONFIGURATION

In the bottom-left panel select the tab "Adv." then the internal tab "Board configuration".

Then click to "Save .cfg file", you can use the default.cfg or another name, then click on make this configuration permanent.

Minimal usage instructions

Position

image

In the bottom-left panel select the tab "Position". Here you can set the parameter for the acquisiton like central position and range.

Acquisition

image

Preview

This button start an infinite loop: the number of repetition is ignored. The data are NOT saved.

During the preview is possible to pan and zoom by point-drag the mouse and use the mouse wheel on the preview image. Double-click on it will move the center of the image to the position selected. Ctrl+Double-click will add a marker.

Acquisition

This button start the acquisition and automatically stop it and the data saved.

List data saved

image

Graphical User Interface (GUI)

The GUI is designed around the preview image, and it is composed by three parts.

Screenshot of BrightEyes-MCS GUI\label{fig:fig4}

  • Left Panel:

    • Top:

      • Start/stop the preview or the real acquisition.
      • Choose between analogue and digital detectors and initiate either acquisition or preview mode. In acquisition, options include DFD mode for lifetime analysis and TTM activation (not part of this project).
      • Laser tab to turn on/off each lasers.
      • Advanced configuration includes bidirectional scanning (snake walk) and the cirucular motion (for circular FCS)

    • Temporal Settings: Configure time resolution, dwell time, and laser delays.

    • Spatial settings: Set pixel, line, frame, and repetition values for your imaging session.

    • Bottom:

      • Position: position and range, preset load/save, list of markers
      • File: destinatio folder, filename (DEFAULT.h5 force a actual time as filename) and textbox where is possible to set comments saved on the metadata
      • List File: list of the acquired data
      • Advanced:
        • Calibration settings
        • Board configurations
        • SPAD (for old SPAD prototype electronics configuration)
        • Default FOV
        • Limits (and offset) of positioner
        • External tools: set the string for integration with napari
        • Http Server: configuration of the REST API server
        • TTM: configuration for integration with TTM data receiver
        • FIFOs: settings of the FIFOs - for developer.

  • Central Area:

    • Preview Tab: Observe real-time image preview during acquisition. Pan and zoom functionalities are enabled. Double-click on a position centering the image on it. CTRL+Double-click add a marker.

    • FCS & Batch acq.: Allow the autocorrelation preview for FCS, set up batch (macro) acquisiton

    • Status: A debug function for reading the status of the registers

    • Cam: A preview for external camera

    • ScriptLauncher: A Python QTConsole in which all objects of the running software are exposed.

    • DFD Preview: A post-acquistion preview for FLIM

  • Right Panel:

    • Micro-Image Display: View a 5x5 micro-image with options for cumulative or end-of-frame updates. Pixel saturation indication are highlighted in blue.

    • Trace: Track photon flux trends for the selected channel or sum throughout the scanning process. Double-click on the trace reset it. And tab for its configuration.

    • Middle:

      • Statistics: Access imaging statistics for in-depth analysis.

      • Analog IN: Choose input options for analogue inputs.

      • Analog OUT: Define functionality for analogue outputs (scanning X, Y, Z, or constant voltage).

      • Menu & Debug: Explore test functionalities.

      • Plug-ins Management: Load and manage plugins seamlessly.

    • Panorama Image: Generate and update a panoramic image with the current preview image.

    • Image Script: Placeholder that can be used by the script.

The commands are intuitive, and the software highlights possible error of configuration such to minimize the user errors.

API

The documentation of the API is present in the Wiki.

Testing

The installation batch, after the compilation check if the Brighteyes libraries made in Cython are correctly installed using the script check_cython_lib.py.

The automated test can be run directly from the root folder of BrightEyes-MCS with the venv activated.

python .\test\check_cython_lib.py
python .\test\test_spadfcsmanager.py
python .\test\check_cython_lib.py
python .\test\test_mainwindow.py

As BrightEyes-MCS is controlling hardware, before connect your microscope system to it, it is strongly suggested to verify the output signal (expecially the analog output) with an oscilloscope. The steps to follow are the ones proposed in "Example of usage".

License

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. This is free software, and you are welcome to redistribute it under certain conditions; this software code is licensed under the GNU General Public License version 3 (GPLv3), with the exception of certain parts where a different license is specified. Please refer to the individual source files for details on specific licensing exceptions. See LICENSE.md file for details.

Firmware License

IMPORTANT The firmwares needed for running the NI FPGA are not included in the BrightEyes-MCS tree. It is present during the installation phase a graphical tool to download and extract them. In case of issues it is possible download directly from the repository of BrightEyes-MCSLL.

Community Guidelines

We welcome contributions to BrightEyes-MCS from the community. Below are the general guidelines for those who want to get involved:

  1. Contributing: If you want to contribute to the software, you can fork the repository, make your changes, and submit a pull request. We recommend getting in touch with the maintainers before starting work on major features to avoid duplicating efforts.
  2. Reporting Issues: You can report any bugs, issues, or feature requests by opening a new issue on the GitHub repository. Please ensure that you include as much detail as possible, including steps to reproduce the issue and your environment details (operating system, Python version, hardware setup).
  3. Seeking Support: For questions or technical assistance, you can start a discussion in the "Discussions" tab of the repository, or check the FAQ section in the project's documentation. For immediate support or collaborations, you can contact the developers through the contact information provided on the project website.

Contributing

Contributions are welcome in the form of code, documentation, testing, or suggestions. Here's how you can contribute:

  1. Fork the Repository: Create a personal copy of the BrightEyes-MCS repository by clicking on "Fork".
  2. Clone the Repository: Clone the forked repository to your local machine using git clone.
  3. Create a Branch: Create a new branch for your feature or bug fix.
  4. Make Changes: Implement your changes, ensuring that your code is well-documented and follows the project's coding guidelines.
  5. Test Your Changes: Ensure that all tests pass and add new ones if necessary.
  6. Submit a Pull Request: Once you're happy with your changes, submit a pull request to the main repository for review. Provide a clear description of the changes and reference any related issues.

For detailed instructions on how to set up your development environment, please refer to the Installation section.

Credits

Author: Mattia Donato

The authors are thanked for their valuable contributions. Below is a breakdown of the parts they have contributed to and the list of contributors.

  • BrightEyes-MCS-LowLevel: Marco Castello, Giorgio Tortarolo, Simonluca Piazza, Mattia Donato, Eli Slenders
  • MemorySharedNumpyArray: Sami Valtteri Koho
  • FCS Live Preview: Eli Slenders
  • Scripts examples (shift vectors, grid calibration, ffs analysis): Alessandro Zunino, Eli Slenders
  • Scientific QT Spinbox: Luca Bega

Scientific team: Molecular Microscopy and Spectroscopy, Istituto Italiano di Tecnologia:

  • Giuseppe Vicidomini (Principal Investigator)
  • Luca Bega
  • Andrea Bucci
  • Mattia Donato
  • Francesco Fersini
  • Giacomo Garre'
  • Marcus Held
  • Sanket Patil
  • Eleonora Perego
  • Marco Scotto
  • Eli Slenders
  • Sabrina Zappone
  • Alessandro Zunino

Reference

Clone this wiki locally