From 9a07102390c0dd5be8788919eec2115c3cdd6801 Mon Sep 17 00:00:00 2001 From: Benedict Diederich Date: Fri, 14 Feb 2025 16:38:15 +0100 Subject: [PATCH 1/4] Update ImSwitchClient.md --- docs/04_ImSwitch/ImSwitchClient.md | 144 +++++++++++++++++++++-------- 1 file changed, 103 insertions(+), 41 deletions(-) diff --git a/docs/04_ImSwitch/ImSwitchClient.md b/docs/04_ImSwitch/ImSwitchClient.md index 0ec751928..a8dd6bb0d 100644 --- a/docs/04_ImSwitch/ImSwitchClient.md +++ b/docs/04_ImSwitch/ImSwitchClient.md @@ -1,75 +1,137 @@ # ImSwitchClient Documentation -`ImSwitchClient` is a Python package designed to connect to the ImSwitch REST API, enabling remote control of ImSwitchUC2 functionalities directly from Jupyter Notebooks. This client facilitates easy integration with the ImSwitch ecosystem, offering programmable access to various features like laser control, stage manipulation, and image acquisition. - -[![PyPI Version](https://img.shields.io/pypi/v/imswitchclient.svg)](https://pypi.python.org/pypi/imswitchclient) +## Introduction +`ImSwitchClient` is a Python wrapper designed for interacting with the ImSwitch REST API, enabling remote control over ImSwitch functionalities, such as stage positioning, laser control, and image acquisition. This client simplifies API interactions and allows seamless integration into Python scripts and Jupyter Notebooks. - +[![PyPI Version](https://img.shields.io/pypi/v/imswitchclient.svg)](https://pypi.python.org/pypi/imswitchclient) ## Features -- **Remote Control**: Interact with ImSwitchUC2 from Jupyter Notebooks via fastapi endpoints. -- **Comprehensive Documentation**: Access detailed documentation and explore API endpoints at [https://imswitchclient.readthedocs.io](https://imswitchclient.readthedocs.io). -- **API Exploration**: Utilize FastAPI's interface at http://localhost:8000/docs for an interactive API experience. -- **Broad Functionality**: Current implementations include laser control, stage manipulation, and image acquisition, with the possibility for future expansion based on user requests. -- **Global API Testing**: Test the client using the globally hosted API at [https://youseetoo.github.io/imswitch/api.html](https://youseetoo.github.io/imswitch/api.html). -- **Open Source**: Inspired by the OpenFlexure Client, `ImSwitchClient` is freely available for modification and distribution under the MIT license. -- **Implemented functions** (so far, please file an issue for feature requests): - - Laser - - Stage - - Image Acquisition -- You can test the client with the globally hosted api here: https://youseetoo.github.io/imswitch/api.html -- It is inspired by the OpenFlexure Client: https://gitlab.com/openflexure/openflexure-microscope-pyclient/-/blob/master/openflexure_microscope_client/microscope_client.py -- The source files can be found here: https://github.com/openUC2/imswitchclient/ +- **Remote Control**: Interface with ImSwitch through REST API endpoints. +- **Comprehensive API Access**: Easily control positioners, lasers, detectors, and imaging settings. +- **Interactive API Exploration**: Utilize the FastAPI Swagger UI at `http://localhost:8000/docs`. +- **Modular Design**: Includes managers for lasers, positioners, image acquisition, and more. +- **Open Source**: Inspired by OpenFlexure Client, freely available under the MIT license. ## Installation -To install `ImSwitchClient`, use the following pip command: +You can install `ImSwitchClient` via pip: ```bash pip install imswitchclient ``` -## Quick Start Example +## Getting Started -This example demonstrates basic usage of `ImSwitchClient` for moving a positioner and acquiring an image. +### Initializing the Client ```python import imswitchclient.ImSwitchClient as imc + +# Initialize the client +client = imc.ImSwitchClient(host="0.0.0.0", isHttps=True, port=8001) +``` + +### Example: Moving a Stage and Acquiring an Image + +```python import numpy as np import matplotlib.pyplot as plt import time -# Initialize the client -client = imc.ImSwitchClient() - -# Retrieve the first positioner's name and current position +# Retrieve positioner names positioner_names = client.positionersManager.getAllDeviceNames() positioner_name = positioner_names[0] -currentPositions = client.positionersManager.getPositionerPositions()[positioner_name] -initialPosition = (currentPositions["X"], currentPositions["Y"]) - -# Define and move to a new position -newPosition = (initialPosition[0] + 10, initialPosition[1] + 10) -client.positionersManager.movePositioner(positioner_name, "X", newPosition[0], is_absolute=True, is_blocking=True) -client.positionersManager.movePositioner(positioner_name, "Y", newPosition[1], is_absolute=True, is_blocking=True) - -# Acquire and display an image -time.sleep(0.5) # Allow time for the move -lastFrame = client.recordingManager.snapNumpyToFastAPI() -plt.imshow(lastFrame) + +# Get current position +current_positions = client.positionersManager.getPositionerPositions()[positioner_name] +initial_position = (current_positions["X"], current_positions["Y"]) + +# Turn on illumination +laser_name = client.lasersManager.getLaserNames()[0] +client.lasersManager.setLaserActive(laser_name, True) +client.lasersManager.setLaserValue(laser_name, 512) + +# Move the stage and capture an image +def capture_image_at_position(x, y): + client.positionersManager.movePositioner(positioner_name, "X", x, is_absolute=True, is_blocking=True) + client.positionersManager.movePositioner(positioner_name, "Y", y, is_absolute=True, is_blocking=True) + last_frame = client.recordingManager.snapNumpyToFastAPI() + plt.imshow(last_frame) + plt.show() + +# Example scanning +for ix in range(5): + for iy in range(5): + new_x = initial_position[0] + ix * 50 + new_y = initial_position[1] + iy * 50 + capture_image_at_position(new_x, new_y) + +# Return stage to initial position +client.positionersManager.movePositioner(positioner_name, "X", initial_position[0], is_absolute=True, is_blocking=True) +client.positionersManager.movePositioner(positioner_name, "Y", initial_position[1], is_absolute=True, is_blocking=True) +``` + +### Laser Control Example + +```python +laser_name = client.lasersManager.getLaserNames()[0] +client.lasersManager.setLaserActive(laser_name, True) +client.lasersManager.setLaserValue(laser_name, 800) + +# Verify laser status +print(client.lasersManager.getLaserNames()) +client.lasersManager.setLaserActive(laser_name, False) +``` + +### Recording an Image + +```python +# Take a snapshot +image = client.recordingManager.snapNumpyToFastAPI() +plt.imshow(image) plt.show() +``` -# Return the positioner to its initial position -client.positionersManager.movePositioner(positioner_name, "X", initialPosition[0], is_absolute=True, is_blocking=True) -client.positionersManager.movePositioner(positioner_name, "Y", initialPosition[1], is_absolute=True, is_blocking=True) +### Setting Live View + +```python +client.viewManager.setLiveViewActive(True) +client.viewManager.setLiveViewCrosshairVisible(True) +client.viewManager.setLiveViewGridVisible(False) ``` +## API Overview + +The ImSwitch API provides access to various components: + +### Positioners Manager +- `getAllDeviceNames()` - Get all available positioners. +- `getPositionerPositions()` - Get current position. +- `movePositioner(name, axis, value, is_absolute, is_blocking)` - Move the stage. +- `homeAxis(name, axis, is_blocking)` - Home the positioner. + +### Lasers Manager +- `getLaserNames()` - Get available lasers. +- `setLaserActive(name, status)` - Turn laser on/off. +- `setLaserValue(name, value)` - Set laser intensity. + +### Recording Manager +- `snapNumpyToFastAPI()` - Capture an image. +- `startRecording()` - Begin recording. +- `stopRecording()` - Stop recording. + +### View Manager +- `setLiveViewActive(status)` - Enable live view. +- `setLiveViewCrosshairVisible(status)` - Show/hide crosshair. +- `setLiveViewGridVisible(status)` - Show/hide grid. + ## Contributing -Contributions to `ImSwitchClient` are welcome! Please refer to the project's GitHub repository for contribution guidelines: [https://github.com/openUC2/imswitchclient/](https://github.com/openUC2/imswitchclient/). +Contributions are welcome! Visit the GitHub repository for details: [https://github.com/openUC2/imswitchclient](https://github.com/openUC2/imswitchclient) ## License -`ImSwitchClient` is licensed under the MIT License. For more details, see the LICENSE file in the project repository. +This project is licensed under the MIT License. + From d8ab45bd6083b85d5e799aa9c3fd25d04e250ee2 Mon Sep 17 00:00:00 2001 From: beniroquai Date: Fri, 14 Feb 2025 16:41:06 +0100 Subject: [PATCH 2/4] Update 01_Fluoresence_smart_microscope.md --- .../01_Fluoresence_smart_microscope.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/01_Toolboxes/06_DiscoveryFluorescence/01_Fluoresence_smart_microscope.md b/docs/01_Toolboxes/06_DiscoveryFluorescence/01_Fluoresence_smart_microscope.md index 1672b1e63..9c7d07d98 100644 --- a/docs/01_Toolboxes/06_DiscoveryFluorescence/01_Fluoresence_smart_microscope.md +++ b/docs/01_Toolboxes/06_DiscoveryFluorescence/01_Fluoresence_smart_microscope.md @@ -301,8 +301,8 @@ This will initiate the Bluetooth scan on the ESP32, which will detect and pair w 1. Download Raspberry PI Imager 2. Flash Raspberry Pi OS 64Bit Bookworm Lite on an SD card with appropriate size (e.g. 64GB ) -> add the necessary settings (i.e. SSH, wifi password, uc2/youseetoo password/login ) )> Flash -3. Boot Raspberry Pi and wait until it's full there; ~5 minutes => It should be connected to you r wifi; you're computer should be in the same network -4. You should be able to log into that using ssh +3. Boot Raspberry Pi and wait until it's full there; ~5 minutes => It should be connected to you r wifi; you're computer should be in the same network, you can check it's ip by using tools like Fing (Android app) which scans the ips in your network or Angry ip scanner which is for MAC OsX which will do the same on mac +4. You should be able to log into that using ssh => `ssh uc2@IP-ADDRESS` 5. Install imswitch; Go to https://github.com/openUC2/ImSwitchDockerInstall?tab=readme-ov-file#imswitch--docker-on-raspi and then follow the procedures: ```bash cd ~/Downloads @@ -321,6 +321,12 @@ This will: 6. Go to your browser and enter the `https://IP-OF-YOUR-RASPI:8001/imswitch/index.html` 7. Have a look for additional information here: https://openuc2.github.io/docs/ImSwitch/ImSwitchOnRaspi/ + +## altternaive : + +Flash the pre-built image from this link using this software + + ### Video Tutorial For a visual guide on how to set up ImSwitch and control the UC2 system, watch the following video: From c124b9b23b8669af878af526126100a97d63e93c Mon Sep 17 00:00:00 2001 From: beniroquai Date: Fri, 14 Feb 2025 16:43:23 +0100 Subject: [PATCH 3/4] Update 01_Fluoresence_smart_microscope.md --- .../06_DiscoveryFluorescence/01_Fluoresence_smart_microscope.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/01_Toolboxes/06_DiscoveryFluorescence/01_Fluoresence_smart_microscope.md b/docs/01_Toolboxes/06_DiscoveryFluorescence/01_Fluoresence_smart_microscope.md index 7682dbb9a..12e4ce3bf 100644 --- a/docs/01_Toolboxes/06_DiscoveryFluorescence/01_Fluoresence_smart_microscope.md +++ b/docs/01_Toolboxes/06_DiscoveryFluorescence/01_Fluoresence_smart_microscope.md @@ -26,7 +26,7 @@ In this workshop, we will guide you through assembling a LED-powered fluorescenc ### Diagram -![](./IMAGES/diagramm_no_filter.png) +![](./IMAGES/diagramm.png) --- ### Theory of Operation From 71c0398dd737fa5c1183ae087bf67ad92c0a9f37 Mon Sep 17 00:00:00 2001 From: beniroquai Date: Fri, 14 Feb 2025 18:52:32 +0100 Subject: [PATCH 4/4] Update 01_Fluoresence_smart_microscope.md --- .../01_Fluoresence_smart_microscope.md | 115 +++++++++--------- 1 file changed, 58 insertions(+), 57 deletions(-) diff --git a/docs/01_Toolboxes/06_DiscoveryFluorescence/01_Fluoresence_smart_microscope.md b/docs/01_Toolboxes/06_DiscoveryFluorescence/01_Fluoresence_smart_microscope.md index 12e4ce3bf..7e5381980 100644 --- a/docs/01_Toolboxes/06_DiscoveryFluorescence/01_Fluoresence_smart_microscope.md +++ b/docs/01_Toolboxes/06_DiscoveryFluorescence/01_Fluoresence_smart_microscope.md @@ -1,12 +1,12 @@ id: LED_Fluoresence_microscope title: openUC2 LED Fluoresence microscope ---- + # Workshop Manual: Building a Smart LED-Powered Fluorescence Microscope In this workshop, we will guide you through assembling a LED-powered fluorescence microscope, allowing you to explore fascinating experiments with microscopic details. ---- + ### Materials Needed @@ -22,12 +22,12 @@ In this workshop, we will guide you through assembling a LED-powered fluorescenc 10. Camera with tube lens 11. UC2 Electronics box, Infinity Box, and Corebox (cubes, puzzle pieces, and holders) ---- + ### Diagram ![](./IMAGES/diagramm.png) ---- + ### Theory of Operation @@ -36,7 +36,7 @@ First, an electron is excited from the ground state to the higher-energy state ![](./IMAGES/fluoresence_microscope.png) ---- + ### Theoretical Background: Fluorescence @@ -47,7 +47,7 @@ First, an electron is excited from the ground state to the higher-energy state ![](./IMAGES/fluoreszenzshema.png) ---- + ## Tutorial: LED-Powered Fluorescence Microscope @@ -66,7 +66,7 @@ If the Z-stage isn't already set up, insert the 8 grub screws on the long sides Now, your bright-field microscope is ready! ---- + #### 1.2: Assembling the Fluorescence Microscope But of course if you got this box you want more, so now let#s start buidling the fluorescene Microscope @@ -80,38 +80,38 @@ But of course if you got this box you want more, so now let#s start buidling the After completing these steps, you're done with the assembly, nice job! ---- + # Step 2: Turn Your Microscope Into a Smart One - aka the Electronics ### 2.1: Plug in the Electronics as Shown Below -
- ⚠️ Caution! -

If you need to change any of the cables or their position, always unplug the 12V power cable before doing so. Otherwise, the electronic components might get damaged!

-
+:::caution +**⚠️ Caution!** +If you need to change any of the cables or their position, always unplug the 12V power cable before doing so. Otherwise, the electronic components might get damaged! +::: - connect the LED-Array panel by plugging in the micro-USB and connect it to your PC. -- Connect the Z-stage to the ``Z-Motor`` on the main board. Ensure there's a motor driver. -- Connect the blue LED to the LED driver (red plate) at ``out1``: - - The cable at ``-`` goes to ``-`` - - The cable at ``+`` goes to ``+`` +- Connect the Z-stage to the `Z-Motor` on the main board. Ensure there's a motor driver. +- Connect the blue LED to the LED driver (red plate) at `out1`: + - The cable at `-` goes to `-` + - The cable at `+` goes to `+` - Connect the LED driver to the main board: - - The cable at ``in 1`` goes to ``PM2 - PMW2`` - - The cable at ``V In -`` goes to ``12V - GND`` - - The cable at ``V IN +`` goes to ``12V - 12V`` + - The cable at `in 1` goes to `PM2 - PMW2` + - The cable at `V In -` goes to `12V - GND` + - The cable at `V IN +` goes to `12V - 12V` - Plug in the micro-USB and connect to your PC. - Plug in the 12V power cable. ---- + ### 2.2: Flashing the ESP32 Firmware -1. Before proceeding, ensure your ESP32 board has the latest firmware. You can download and flash the firmware via the official [openUC2 website](https://youseetoo.github.io/), selecting your version (**row 2, column 1**), then click on the ``connect`` button. +1. Before proceeding, ensure your ESP32 board has the latest firmware. You can download and flash the firmware via the official [openUC2 website](https://youseetoo.github.io/), selecting your version (**row 2, column 1**), then click on the `connect` button. - ![](./IMAGES/Electronics_Box_5.png) +![](./IMAGES/Electronics_Box_5.png) - The source code can be found [here](https://github.com/youseetoo/uc2-esp32). +The source code can be found [here](https://github.com/youseetoo/uc2-esp32). 2. Connect the ESP32 to your computer using the micro-USB cable. @@ -129,7 +129,7 @@ After completing these steps, you're done with the assembly, nice job! 5. 💡 **flash your LED-Array**. Repeat the same steps, but this time for the LED-Array ![](./IMAGES/LED_install.png) ---- + ### 2.3: Connecting to the Web Interface @@ -144,16 +144,17 @@ After completing these steps, you're done with the assembly, nice job! ```json {"task":"/motor_act", "motor": { "steppers": [ { "stepperid": 3, "position": -1000, "speed": 1000, "isabs": 0, "isaccel": 0} ] } } ``` - ![](./IMAGES/Electronics_Box_1.png) + +![](./IMAGES/Electronics_Box_1.png) This command will move the Z-axis motor by -1000 steps (1 full rotation) at a speed of 1000 steps per second. Each step corresponds to a movement of 300nm when using microstepping. You’ll observe the motor rotating, adjusting the focus. -> **Note:** Ensure that the command string has no line breaks. +**Note:** Ensure that the command string has no line breaks. 4. 💡**Connect your LED-Array as well**. Duplicate the current tab and connect the LED-Array again via the button. Choose the correct COM Port. Now you can test all components through these two tabs. ---- + ### 2.4: Testing in the Web Interface @@ -162,7 +163,7 @@ Now you can test all components through these two tabs. - `Motor Z(+)` and `Motor Z(-)` control the Z-stage. - `LED (on)` and `LED (off)` control the LED-Array panel (💡you must change tabs to control it). ---- + ### 2.5: Pairing the PS4 Controller 🎮 @@ -183,18 +184,18 @@ The UC2-ESP firmware supports various input devices, including the PS4 controlle - **Move the Z-stage**: Use the **left analog stick** to move the stage up and down (adjust focus). - **Control the LEDs**: Use the **controller buttons** to turn the LED array on/off and cycle through different illumination patterns. - --- + ### 2.6: Setup and Use the Camera Software 1. Connect the camera to your PC. 2. For the installation process, follow these instructions: [Install MVS App for Camera Utilization](https://openuc2.github.io/docs/Toolboxes/DiscoveryInterferometer/SoftwareTutorial/#install-mvs-app-for-camera-utilization). ---- -# Congratulations! You Have Completed All the Setup Steps! Now Let's Use the Microscope ---- +**Congratulations! You Have Completed All the Setup Steps! Now Let's Use the Microscope** + + ## Experiment 1: Bright Field Illumination @@ -207,21 +208,21 @@ The UC2-ESP firmware supports various input devices, including the PS4 controlle ![](./IMAGES/cameraaufnahme_hellfeld.png) ---- + ## Experiment 2: Fluorescence Microscopy 1. To turn your microscope into a fluorescence microscope, turn the LED-Array off and the blue LED on. 2. The probe should still be in the probe insert, and the camera should still be on. -3. At this point, you're likely seeing a black screen. This is because the fluorescence (the photons emitted by the probe) is much weaker than the bright LED-Array. To adjust, open the feature tree, go to ``Acquisition Control``, and increase the ``exposure time`` to 300000ms. You should now see the fluorescence image. -Optional you can go to ``Analog Control``, and increase the ``Gain``. +3. At this point, you're likely seeing a black screen. This is because the fluorescence (the photons emitted by the probe) is much weaker than the bright LED-Array. To adjust, open the feature tree, go to `Acquisition Control`, and increase the `exposure time` to 300000ms. You should now see the fluorescence image. +Optional you can go to `Analog Control`, and increase the `Gain`. ![](./IMAGES/cameraaufnahme_fluoreszenz.png) --------- +-- Benedicts stuff --------- +-- @@ -242,25 +243,25 @@ Benedicts stuff A more detailed explantion can be found here: https://openuc2.discourse.group/t/imswitch-installation-on-mac-and-windows/37 1. **Set up your Python environment** (using Conda or Mamba): - ```bash + ``bash mamba create -n imswitchhackathon python=3.9 -y mamba activate imswitchhackathon - ``` + `` 2. **Install ImSwitch**: - ```bash + ``bash pip install https://github.com/openUC2/ImSwitch/archive/refs/heads/master.zip # this installs the lastest master # do the same if you want to update the system # alternative: git clone https://github.com/openUC2/ImSwitch/ cd ImSwitch pip install -e . - ``` + `` 3. **Optional**: Install the required dependencies for QT and Napari: - ```bash + ``bash pip install pyqtgraph qdarkstyle - ``` + `` This setup will allow you to run ImSwitch with full functionality, including graphical user interface (GUI) support for Napari. @@ -269,12 +270,12 @@ Benedicts stuff For a simpler, platform-agnostic solution, you can run ImSwitch using Docker: 1. **Pull the Docker container**: - ```bash + ``bash sudo docker pull ghcr.io/openuc2/imswitch-noqt-x64:latest - ``` + `` 2. **Run the Docker container**: - ```bash + ``bash sudo docker run -it --rm -p 8001:8001 -p 2222:22 \ -e HEADLESS=1 \ -e HTTP_PORT=8001 \ @@ -282,13 +283,13 @@ Benedicts stuff -e CONFIG_PATH=/config \ -v ~/Downloads:/config \ --privileged ghcr.io/openuc2/imswitch-noqt-x64:latest - ``` + `` Once you have ImSwitch installed and running, you can access the web interface at `localhost:8001` to control the system. For detailed instructions on Docker installation, visit the [ImSwitch Docker Guide](https://openuc2.github.io/docs/ImSwitch/ImSwitchDocker/). - --- + ### Step 2: Using the ImSwitch Config File @@ -355,18 +356,18 @@ Benedicts stuff "frameCropy": 400 } } - ``` + `` This file configures the ESP32 stage, LED control, and the camera for widefield imaging. Ensure the `host_` and `serialport` match your system setup. - --- + ### Step 3: Running the Microscope with ImSwitch 1. **Launch ImSwitch**: - ```bash + ``bash python -m imswitch - ``` + `` 2. **Select the Configuration**: Upon launch, choose **"Virtual Microscope"** or load your custom configuration file, such as `uc2_hik_histo.json`. @@ -387,7 +388,7 @@ Benedicts stuff ![](./IMAGES/RaspiOS_2.png) -3. Boot Raspberry Pi and wait until it's full there; ~5 minutes => It should be connected to you r wifi; you're computer should be in the same network (startet das booten, wenn man auf ``weiter`` klickt? siehe bild) +3. Boot Raspberry Pi and wait until it's full there; ~5 minutes => It should be connected to you r wifi; you're computer should be in the same network (startet das booten, wenn man auf `weiter` klickt? siehe bild) 4. You should be able to log into that using ssh => (Windows + R => CMD ) = > Terminal opens and then type `ssh uc2@IP-OF-YOURRASPI` ![](./IMAGES/ssh_uc2_IP_of_your_Raspi.png) @@ -398,7 +399,7 @@ Benedicts stuff in the last line copypaste the following code: (not completly correct.. do you have to type ~ $ before as shown in picture?) -```bash +``bash mkdir Downloads mkdir Desktop sudo apt-get install git -y @@ -407,7 +408,7 @@ git clone https://github.com/openUC2/ImSwitchDockerInstall cd ImSwitchDockerInstall chmod +x install_all.sh ./install_all.sh -``` +`` This will: - install docker - install all necessary camera drivers @@ -425,9 +426,9 @@ This will: ## launch imswitch if you have installed it alredy execute the following -``` +`` bash ~/Desktop/launch_docker_container.sh -``` +`` (hier auch unbedingt screenshot machen!)