Hardware/feature/photoneo

[Yasserelhaddar]

Add 3D scanner subsystem with Photoneo backend

Scope and Motivation

The hardware module supports 2D cameras, stereo cameras, PLCs, and sensors — but has no support for structured-light 3D scanners. Industrial inspection workflows require high-resolution 3D scanning (Photoneo PhoXi, MotionCam-3D) for dimensional measurement, surface defect detection, and bin picking.

This PR adds a complete 3D scanner subsystem following the same layered architecture as the existing subsystems: Backend → Core → Service → CLI.

Changes Included

Backend layer

• Scanner3DBackend — abstract async base class with multi-component capture, point cloud generation, configuration, and thread-affinity support
• PhotoneoBackend — production backend using Harvesters/GigE Vision with Matrix Vision mvGenTL Producer. Supports Range, Intensity, Confidence, Normals, and Color capture components, plus Coord3D point cloud generation
• MockPhotoneoBackend — full-fidelity mock for development and CI. Two simulated devices (PhoXi M and L) generating synthetic scan data without any hardware dependency

Core layer

• AsyncScanner3D / Scanner3D — async and sync high-level interfaces with factory method open("Photoneo:serial") for backend routing
• Data models: ScanResult, PointCloudData, CoordinateMap, ScannerConfiguration, ScannerCapabilities and configuration enums

Service layer

• REST API with 21 endpoints covering discovery, lifecycle, capture (scan + point cloud), configuration, and batch operations
• Connection manager for typed client access
• MCP tool integration

SDK setup (mindtrace-scanner-photoneo)

• Cross-platform installer for the Matrix Vision mvGenTL Producer v2.49.0
• Supports Linux, Windows, and macOS
• Handles post-install environment setup (GENICAM_GENTL64_PATH)
• Includes verify, discover, and uninstall commands

CLI

• mindtrace-hw scanner start/stop/status/logs for service lifecycle

Stereo refactor

• Extracted StereoCameraBackend base class from BaslerStereoAce to enable future stereo backends

Tests & docs

• Unit and integration tests covering backends, models, configuration, capture, and imports
• New scanners_3d/README.md with architecture, usage, configuration reference, and extension guide
• Updated hardware/README.md with scanner setup commands and backend info

How to Test

1. Install the OS-level SDK (Matrix Vision mvGenTL Producer — requires sudo):

mindtrace-scanner-photoneo install -v

2. Install Python dependencies:

uv sync --extra scanners-all

3. Verify everything is wired up:

mindtrace-scanner-photoneo verify -v

4. Discover scanners on the network (if hardware is available):

mindtrace-scanner-photoneo discover --all

5. Try a capture (works without hardware using the mock backend):

import asyncio
from mindtrace.hardware.scanners_3d import AsyncScanner3D

async def main():
    scanner = await AsyncScanner3D.open("MockPhotoneo")

    result = await scanner.capture(enable_range=True, enable_intensity=True)
    print(f"Range: {result.range_shape}, Intensity: {result.intensity_shape}")

    point_cloud = await scanner.capture_point_cloud()
    print(f"Points: {point_cloud.num_points}")

    await scanner.close()

asyncio.run(main())

Impact

• No breaking changes — entirely additive, no existing APIs modified
• New optional dependency group — scanners-all extra in pyproject.toml
• Stereo refactor — extracted base class; existing stereo functionality and tests unaffected
• New CLI entry point — mindtrace-scanner-photoneo registered in pyproject.toml
• Network — Photoneo scanners use GigE Vision, requiring host networking for discovery (same as Basler GigE cameras)