Docs — RoboCam 3.1

Installation

Requires Python 3.10+. Raspberry Pi OS Bookworm is recommended, but any Linux system works.

1. Clone

git clone https://github.com/E-Lab-SFSU/RoboCam3.1.git
cd RoboCam3.1

2. Setup

bash setup.sh

Creates .venv (with --system-site-packages on a detected Raspberry Pi), installs requirements.txt, and — on a Pi — additionally installs lgpio, RPi.GPIO, and picamera2. Finishes by downloading and patching the Player One SDK (safe to skip if you don't have that camera). Windows: run setup.bat instead.

3. Launch

bash start_robocam.sh

start_robocam.bat on Windows.

The six tabs

Reference for each tab individually. All tabs except Experiment are disabled while an experiment is running.

1 — Setup

Scan and pick a camera (Player One, Picamera2, or OpenCV); configure the printer backend (Marlin serial or Klipper HTTP); configure the laser/GPIO output; watch live connection and homing status.

2 — Motion Profiles

Read, tune, and save feed-rate (M203), acceleration (M201), and jerk (M205) on Marlin, with slow/medium/fast presets. Klipper has no gcode equivalent, so the tab shows "not supported" for that backend. Untested on real Marlin hardware so far.

3 — Calibration

Jog to the four physical corners of the well plate and click Set for each — the well map auto-generates once all four are set. Choose grid dimensions and scan pattern (Raster or Snake), then save the calibration as JSON. Quick Capture grabs a still or short raw burst directly from this tab.

4 — Experiment

Pick a calibration and capture mode (Image or Raw Burst, with optional laser stimulus split into Pre/ON/Post phases), select wells on the grid, and run. Auto-process can hand the finished output straight to the Processing tab.

5 — Manual Control

Direct hardware control outside of an experiment: homing, stepper disable, jog pad, go-to by coordinate, manual laser toggle, and a raw G-code sender.

6 — Processing

Batch-converts one or more experiment folders' .npy bursts into PNG image sequences and/or video (MP4 + VFR MKV), with per-well and overall progress.

Headless CLI

Test hardware or script workflows without launching the GUI:

source .venv/bin/activate

python -m robocam status
python -m robocam motion pos
python -m robocam motion home
python -m robocam motion move --x 50 --y 50
python -m robocam motion gcode G28
python -m robocam camera info
python -m robocam camera capture --output frame.jpg
python -m robocam config show
python -m robocam config set paths.output_dir /mnt/ssd/outputs

# Simulation mode (no hardware required)
python -m robocam --simulate status

Post-processing

Run after an experiment (or use the Processing tab) to produce per-frame images and video from the raw .npy burst:

# All wells in an experiment directory
python scripts/reconstruct_vfr.py outputs/20260625_133324_my_experiment/

# Images only
python scripts/reconstruct_vfr.py outputs/exp/ --no-video

# Video only
python scripts/reconstruct_vfr.py outputs/exp/ --no-images

# Lossless video
python scripts/reconstruct_vfr.py outputs/exp/ --codec ffv1

Testing

Hardware-free unit tests (pytest): calibration bilinear interpolation, config persistence, and CLI argument parsing.

pip install -e ".[dev]"
pytest

See TESTING.md for the manual hardware checklist used on a live Raspberry Pi session.

Getting started