scant-pi

Imported from reprahkcin/scant-pi (AGENTS.md). Install upstream with npx skills add reprahkcin/scant-pi. Copyright stays with the author.

Agent Onboarding — scant-pi

This document provides the context an AI coding agent needs to continue development on scant-pi. Read this first, then the README.md for user-facing docs.

What This Project Is

scant-pi is a Raspberry Pi–based 3D specimen scanner control system. It is a clean-room rewrite inspired by scAnt, keeping only the scan logic and Pololu Tic stepper protocol. The PyQt5 GUI, FLIR camera code, and Windows-specific code from scAnt were discarded.

The system is split into two halves:

• Pi (capture): FastAPI web server controlling a Pi HQ Camera and 3 stepper motors. Saves RAW TIFF images to a USB drive.
• PC (processing): Offline CLI script that focus-stacks and masks the captured images.

Repository Layout & Module Roles

scant_core/ — Hardware & logic layer (no web dependencies)

scant_web/ — FastAPI web application

tools/

Root files

Key Design Decisions

1. subprocess.run() for ticcmd — Pololu's Python bindings don't support ARM64 well. The CLI works reliably. Each command is a separate process invocation with a 10-second timeout.

2. Thread-based scan loop — The scan runs in a threading.Thread(daemon=True). Pause uses threading.Event.wait(). Abort sets a flag checked between captures. This avoids asyncio complexity in the hardware layer.

3. Dual picamera2 configurations — Preview runs at 640×480 for low-bandwidth MJPEG streaming. capture_image() switches to the full-res still config, captures, then switches back. This is a picamera2 pattern (not a hack).

4. --system-site-packages venv — Required because picamera2 is installed via apt and is not on PyPI. The venv inherits system packages.

5. Config deep-merge — load_config() merges user YAML over DEFAULT_CONFIG. This means new keys added to defaults are automatically available without breaking existing configs.

6. No database — All state is in-memory (config dict, scanner state). The only persistence is the YAML config file and the scan manifest JSON.

7. Images saved as TIFF — Lossless, large (~35 MB each), suitable for scientific/archival use. OpenCV's imwrite with .tif extension.

Hardware Interface Details

Pololu Tic Steppers

• Each Tic controller has a unique serial number visible via ticcmd --list
• Commands: --energize, --exit-safe-start, --position <n>, --halt, --deenergize, --position (read), --status
• The -d <serial> flag addresses a specific controller
• Homing uses --home fwd or --home rev depending on limit switch wiring
• Position units are micro-steps (step_mode × full steps)
• Z axis homes first (safety — avoid crashing into specimen)

Pi HQ Camera (IMX477)

• Max resolution: 4056×3040 (12.3 MP)
• Interface: CSI ribbon cable (not USB)
• API: picamera2 (Python wrapper around libcamera)
• Key controls: ExposureTime (µs), AnalogueGain, ColourGains (tuple), AwbEnable, AeEnable
• Max exposure: ~670 seconds (useful for very dark macro setups)
• Lens: C/CS-mount (user-supplied)

State Management Pattern

The FastAPI app in scant_web/app.py uses module-level globals for shared state:

config: dict = {}
controller: ScannerController | None = None
camera: PiCameraHQ | None = None
scanner: Scanner | None = None

Route modules import these via a helper function (e.g., from scant_web.app import camera, config). The reload_config(new_config) function rebuilds controller, camera, and scanner from the new config.

This is intentionally simple. If the app grows to need multiple concurrent scans or users, this pattern should be replaced with a proper dependency injection or application context.

Known Limitations & TODO

These are areas that are known to be incomplete or need work:

• No authentication — The web UI has no login. Anyone on the network can control the scanner. Add auth if the Pi is on a shared network.
• No HTTPS — Runs HTTP only. Use a reverse proxy (nginx/caddy) if TLS is needed.
• No EXIF writing — The config has EXIF fields but capture_image() does not embed them in the TIFF. Needs piexif or similar.
• Single camera backend — Only PiCameraHQ is implemented. The BaseCamera ABC exists for adding USB webcam or other backends.
• No image thumbnails — The storage route lists images but doesn't serve thumbnails. Would improve the web UI.
• No config validation — load_config() merges but doesn't validate ranges/types. Bad values cause runtime errors.
• Scan resume — If the Pi loses power mid-scan, there's no way to resume. The manifest records what was captured, so a resume feature could skip already-captured positions.
• Processing script is basic — The masking assumes a light grey background. The focus threshold is a single global value. Both need tuning per specimen.
• Motor position calibration — Positions are in raw microsteps. There's no calibration to real-world units (degrees, mm).

Development Environment

On the Pi

cd /path/to/scant-pi
source venv/bin/activate        # or use system-site-packages venv
python run.py --log-level debug

On a Mac/PC (without hardware)

The camera and stepper modules will fail without real hardware. For UI and API development:

1. Create mock implementations of BaseCamera and ScannerController
2. Or run with --log-level debug and handle the connection errors in the UI

Testing

There are no automated tests yet. This is a good area for contribution. Key testable units:

• config.py — deep merge, load/save round-trip, default completeness
• scanner.py — scan loop with mock controller and camera
• storage.py — drive detection (can mock /media contents)
• API routes — FastAPI's TestClient

Coding Conventions

• Python 3.11+ (Pi OS Bookworm ships 3.11)
• No type annotations on existing code (don't add them retroactively)
• Logging via logging.getLogger(__name__) in every module
• Config keys use snake_case
• API paths use kebab-case for multi-word segments
• Hardware access is always in scant_core/, never in scant_web/
• Imports from scant_web.app inside functions (avoid circular imports)

Useful Commands

# Check camera
libcamera-hello --list-cameras

# List stepper controllers
ticcmd --list

# Query a specific stepper
ticcmd -d <serial> --status --full

# Watch systemd logs
journalctl -u scant-pi -f

# Restart service after code changes
sudo systemctl restart scant-pi

# Check USB drives
lsblk
udisksctl status

Origin & License

• MIT license with attribution to scAnt
• The scan loop logic, stepper protocol, and config structure are adapted from scAnt
• All GUI code, FLIR camera code, and Windows-specific code was discarded
• GitHub: https://github.com/reprahkcin/scant-pi