Skip to content

Latest commit

 

History

History
341 lines (258 loc) · 13.3 KB

README.md

File metadata and controls

341 lines (258 loc) · 13.3 KB
Raw

Voxel Logo
Voxel

Overview

Voxel is a Python package that provides core components and functionality for controlling Light Sheet Microscopy systems. It is designed to simplify the process of developing software for novel microscope setups by focusing on modular composable components. Voxel is built on the following principles:

  1. Modular: Each component (device, writer, processor) implements a common interface and can be easily swapped out.
  2. Configurable: Microscope setups are defined in a human readable YAML configuration file, allowing for easy setup and modification.
  3. Extensible: New devices and components can be easily added by implementing the appropriate interface.
  4. Pythonic: Written in Python and designed to be easily understood and modified.

Voxel provides two key Classes: Instrument and Acquisition.

Instrument

The Instrument class focuses on the composition and structure of the microscope setup. At its core, an instrument is a collection of devices that implement the VoxelDevice interface. An instrument.yaml file defines the devices and their respective settings. Devices are defined by providing their python package, module, and class name as well as any initialization arguments and settings.

Checkout an example instrument configuration yaml and the Devices section for a list of supported devices and their respective drivers.

Acquisition

The Acquisition class focuses on the execution of an imaging experiment. It is responsible for coordinating the devices in the instrument to capture and process data. The Acquisition class is primarily set up as an abstract class that can be subclassed to implement specific acquisition protocols. It provides several methods that are useful in the implementation of an acquisition protocol. A run method is defined that should be overridden by the subclass in order to define a specific protocol for a given microscope design. For an example of an acquisition protocol, check out the ExaSpim Acquisiton Class

Utilities

Voxel also provides additional utilities useful for performing imaging experiments. This includes classes for writing data, performing online processing of imaging data, and concurrent transferring of data to external storage.

Checkout the Writers and File Transfers for a list of supported writers and file transfer methods and the Processes section for a list of supported processors.

Getting Started

Prerequisites

  • Python: >=3.10, <=3.11 (tested)
  • We using a virtual environment:
  • For control of some specific devices, you will need the appropriate SDK installed:

Installation

  1. Create a virtual environment and activate it: On Windows:

    conda create -n voxel
conda activate voxel

    or

    python -m venv voxel
.\voxel\Scripts\activate

  2. Clone the repository:

    git clone https://github.com/AllenNeuralDynamics/voxel.git && cd voxel

  3. To use the software, in the root directory, run:

    pip install -e .

  4. To develop the code, run:

    pip install -e .[dev]

  5. To install all dependencies including all optional device drivers, run:

    pip install -e .[all]

  6. To install specific device drivers that have SDK requirements, run:

    pip install -e .[imaris tiff]

Check out the list of supported devices for more information on device drivers.

Documentation

  • (coming soon)

Usage

1. Single device

Individual device can be instantiated by importing the appropriate driver class with the expected arguments. For example a camera object for a Vieworks VP-151MX can be invoked as:

from voxel.devices.camera.vieworks_egrabber import VieworksCamera

camera = VieworksCamera(id='123456')

Camera properties can then be queried and set by accessing attributes of the camera object:

camera.exposure_time ms = 10.0
camera.pixel_type = 'mono16'
camera.bit_packing_mode = 'lsb'
camera.binning = 1
camera.width_px = 14192
camera.height_px = 10640
camera.trigger = {'mode': 'on', 'source': 'line0', 'polarity': 'risingedge'}

The camera can then be operated with:

camera.prepare() # this function arms and creates the camera buffer
camera.start()
image = camera.grab_frame()
camera.stop()
camera.close()

2. Instrument YAML configuration

instrument:
    devices:
        vp-151mx camera:
        type: camera
        driver: voxel.devices.camera.simulated
        module: SimulatedCamera
        init:
            id: 123456
        settings:
            exposure_time_ms: 10.0
            pixel_type: mono16
            height_offest_px: 0
            height_px: 2048
            width_offset_px: 0
            width_px: 2048
            trigger:
            mode: off
            polarity: rising
            source: external
        488 nm laser:
        type: laser
        driver: voxel.devices.lasers.simulated
        module: SimulatedLaser
        init:
            id: COM1
        x axis stage:
        type: scanning_stage
        driver: voxel.devices.stage.simulated
        module: Stage
        init:
            hardware_axis: x
            instrument_axis: z
        settings:
            speed_mm_s: 1.0

An instrument can be invoked by loading the YAML file with and the loaded devices can be accessed with. The above example uses all simulated device classes.

from voxel.instruments.instrument import Instrument

instrument = Instrument(config_path='example.yaml')
instrument.cameras['vp-151mx camera']
instrument.lasers['488 nm laser']
instrument.scanning_stages['x axis stage']

3. Experimental workflows may then be scripted by using the full instrument object and the contained device objects as needed

  • (example coming soon)

Appendix

Devices

Currently supported device types and models are listed below.

DAQ

Manufacturer Model Class Module Tested
National Instruments PCIe-6738 NIDaq voxel.devices.daq.ni ✅
Simulated MockDAQ SimulatedDAQ voxel.devices.daq.simulated ✅

Cameras

Manufacturer Model Class Module Tested
Simulated MockCamera SimulatedCamera voxel.devices.camera.simulated ✅
Vieworks VP-151MX VieworksCamera voxel.devices.camera.vieworks ✅
Vieworks VNP-604MX VieworksCamera voxel.devices.camera.vieworks ✅
Hamamatsu ORCA-Flash4.0 V3 HamamatsuCamera voxel.devices.camera.hamamatsu ✅
Hamamatsu ORCA-Fusion BT HamamatsuCamera voxel.devices.camera.hamamatsu ✅
PCO ---- PCOCamera voxel.devices.camera.pco ❌

Lasers

Manufacturer Model Class Module Tested
Simulated MockLaser SimulatedLaser voxel.devices.laser.simulated ✅
Coherent OBISLX ObixLXLaser voxel.devices.laser.coherent ✅
Coherent OBISLS ObixLSLaser voxel.devices.laser.coherent ✅
Coherent GenesisMX GenesisMXVoxel coherent_lasers.genesis_mx.voxel_adapter ✅
Vortran Stradus StradusLaser voxel.devices.laser.vortran ❌
Oxxius LBX OxxiusLBXLaser voxel.devices.laser.oxxius ❌
Oxxius LCX OxxiusLCXLaser voxel.devices.laser.oxxius ❌
Cobolt Skyra CoboltLaser voxel.devices.laser.cobolt ❌

Stages

Manufacturer Model Class Module Tested
Simulated MockStage SimulatedStage voxel.devices.stage.simulated ✅
ASI Tiger ASIStage voxel.devices.stage.asi ✅

Rotation mounts

Manufacturer Model Class Module Tested
Simulated MockRM SimulatedRM voxel.devices.rotation_mount.simulated ✅
Thorlabs K10CR1 ThorlabsRM voxel.devices.rotation_mount.thorlabs ✅

AOTF

Manufacturer Model Class Module Tested
Simulated MockAOTF SimulatedAOTF voxel.devices.aotf.simulated ✅
AAOpto MPDSxx AAOptoAOTF voxel.devices.aotf.aaopto ❌

Filterwheel

Manufacturer Model Class Module Tested
Simulated MockFW SimulatedFW voxel.devices.filterwheel.simulated ✅
ASI FW-1000 ASIFilterWheel voxel.devices.filterwheel.asi ✅

Flip mount

Manufacturer Model Class Module Tested
Simulated MockFM SimulatedFM voxel.devices.flip_mount.simulated ✅
Thorlabs MFF101 ThorlabsFM voxel.devices.flip_mount.thorlabs ✅

Power meter

Manufacturer Model Class Module Tested
Simulated MockPM SimulatedPM voxel.devices.power_meter.simulated ✅
Thorlabs PM100D ThorlabsPM voxel.devices.power_meter.thorlabs ✅

Tunable lens

Manufacturer Model Class Module Tested
Simulated MockTL SimulatedTL voxel.devices.tunable_lens.simulated ✅
ASI TGTLC ASITunableLens voxel.devices.tunable_lens.asi ✅
Optotune ELE41, ICC4C OptotuneTL voxel.devices.tunable_lens.optotune ✅ , ✅

Writers

Writer File Format Class Module Tested
Imaris .ims ImarisWriter voxel.writers.imaris_writer ✅
TIFF .tiff TIFFWriter voxel.writers.tiff_writer ✅
BDV .h5/.xml BDVWriter voxel.writers.bdv_writer ✅
ACQUIRE .zarr V2/V3 ACQUIREWriter voxel.writers.acquire_writer ✅

File Transfers

Transfer Method Class Module Tested
Robocopy Robocopy voxel.file_transfer.robocopy ✅
Rsync Rsync voxel.file_transfer.rsync ✅

Processes

CPU processes:
    - Downsample 2D
    - Downsample 3D
    - Maximum projections (xy, xz, yz)
GPU processes:
    - Downsample 2D
    - Downsample 3D
    - Rank-ordered downsample 3D

Support and Contribution

If you encounter any problems or would like to contribute to the project, please submit an Issue on GitHub.

License

Voxel is licensed under the MIT License. For more details, see the LICENSE file.