feat: add wide-angle camera detection and intelligent sensor mode selection (v2.7.0)

gmathy2104 · claude · gmathy2104 · commit 223abc94cc5d · 2025-11-23T00:55:37.000+01:00
This release adds automatic detection of wide-angle cameras (Camera Module 3 Wide) and intelligent sensor mode selection to preserve the full 120° field of view. ### Core Features **Wide-Angle Camera Detection** - Auto-detect Camera Module 3 Wide (120° FOV) via model name (imx708_wide_noir) - Distinguish wide cameras (120° FOV) from standard cameras (66° FOV) - Graceful fallback to standard camera if detection fails **Intelligent Sensor Mode Selection** - Wide cameras: Always use full sensor (Mode 0/1) to preserve 120° FOV - Mode 2 crops the sensor and would lose the wide-angle advantage - 720p-1080p: Use Mode 1 (2304x1296 @ 56fps) - Full sensor with binning - 4K: Use Mode 0 (4608x2592 @ 14fps) - Full sensor, no binning - Standard cameras: Can use Mode 2 (cropped) for higher framerates - Optimized for framerate vs resolution tradeoffs **Critical Fix** - Wide-angle cameras no longer lose field of view at lower resolutions - Previously: Mode 2 (1536x864 cropped) was used for 720p → Lost wide FOV - Now: Mode 1 (2304x1296 full sensor) preserves full 120° FOV at 720p/1080p ### API Changes **Enhanced GET /v1/camera/status** - Added is_wide_camera: Boolean flag for camera type - Added sensor_mode_width: Sensor mode width being used - Added sensor_mode_height: Sensor mode height being used **Enhanced GET /v1/camera/capabilities** - Added is_wide_camera: Camera type detection result - Added field_of_view_degrees: FOV in degrees (120° or 66°) - Added sensor_modes: Complete IMX708 sensor mode specifications - Added recommended_resolutions: Resolution presets optimized for camera type - Wide cameras: Prioritize full FOV preservation - Standard cameras: Prioritize framerate optimization ### Technical Details **camera_service/camera_controller.py** - New method: _detect_wide_camera() -> bool - New method: _get_recommended_resolutions() -> list - Updated: _get_optimal_sensor_mode() - Camera type-aware selection - New instance variable: self._is_wide_camera **camera_service/api.py** - Updated CameraStatusResponse model with v2.7 fields - Updated CameraCapabilitiesResponse model with v2.7 fields - Field mappings in get_camera_status endpoint - Field mappings in get_camera_capabilities endpoint **Documentation** - Updated CHANGELOG.md with comprehensive v2.7.0 release notes - Updated README.md with wide-angle camera features section - Updated API endpoint examples with v2.7 fields - Added client integration examples for dynamic preset generation ### Breaking Changes None - Fully backwards compatible with v2.6.x ### Tested On - Raspberry Pi 5 with Camera Module 3 Wide NoIR (imx708_wide_noir) - Verified 720p uses Mode 1 (2304x1296) preserving 120° FOV - Verified API returns is_wide_camera=true and sensor mode info 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,107 @@ All notable changes to Pi Camera Service will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.7.0] - 2025-11-23
+
+### Added
+
+#### Wide-Angle Camera Detection and Intelligent Sensor Mode Selection
+- **NEW FEATURE**: Automatic wide-angle camera detection (Camera Module 3 Wide - 120° FOV)
+  - **Problem Solved**: Wide-angle cameras were using cropped sensor modes (Mode 2), losing the wide 120° field of view advantage
+  - **Solution**: Auto-detect wide vs standard cameras and intelligently select sensor mode to preserve FOV
+  - **Impact**: Wide cameras now preserve full 120° FOV at all resolutions up to 1080p
+
+#### Camera Type-Aware Sensor Mode Selection
+The system now adapts sensor mode selection based on camera type:
+
+**For Wide-Angle Cameras (120° FOV)**:
+- **Always use full sensor** (Mode 0 or Mode 1) to preserve wide field of view
+- Mode 2 (cropped) would lose the wide-angle advantage
+- Recommended resolutions:
+  - 720p-1080p: Mode 1 (2304x1296 @ 56fps) - Full sensor with binning
+  - 4K: Mode 0 (4608x2592 @ 14fps) - Full sensor, no binning
+  - All preserve full 120° FOV
+
+**For Standard Cameras (66° FOV)**:
+- Can use Mode 2 (cropped) for higher framerates at lower resolutions
+- Mode 2 acceptable since cropping doesn't lose wide-angle advantage
+- Optimized for framerate vs resolution tradeoffs
+
+#### New API Fields - Camera Type Information
+
+**Enhanced `GET /v1/camera/status` Response**:
+- `is_wide_camera`: Boolean flag indicating wide-angle camera (120° FOV)
+- `sensor_mode_width`: Sensor mode width being used (e.g., 2304 for Mode 1)
+- `sensor_mode_height`: Sensor mode height being used (e.g., 1296 for Mode 1)
+
+**Enhanced `GET /v1/camera/capabilities` Response**:
+- `is_wide_camera`: Camera type detection result
+- `field_of_view_degrees`: Field of view in degrees (120° for wide, 66° for standard)
+- `sensor_modes`: Complete specifications for all 3 IMX708 sensor modes
+  - Mode 0: 4608x2592 @ 14.35fps (full sensor, no binning)
+  - Mode 1: 2304x1296 @ 56.03fps (full sensor with 2x2 binning)
+  - Mode 2: 1536x864 @ 120.13fps (cropped sensor with 2x2 binning)
+- `recommended_resolutions`: Array of recommended resolutions for this camera type
+  - Includes resolution, label, max FPS, sensor mode, and FOV preservation info
+  - Different recommendations for wide vs standard cameras
+
+#### Wide-Angle Camera Detection Logic
+- Detects Camera Module 3 Wide via model name: `imx708_wide_noir`, `imx708_wide`
+- Logs camera type at startup for visibility
+- Graceful fallback to standard camera if detection fails
+
+### Changed
+- Updated `CameraController._get_optimal_sensor_mode()` to consider camera type
+- Wide cameras now default to Mode 1 for all resolutions ≤ 1080p (preserves 120° FOV)
+- Standard cameras continue to use Mode 2 for ≤ 720p (optimizes framerate)
+- Enhanced logging to show FOV preservation rationale in sensor mode selection
+
+### Fixed
+- **CRITICAL FIX**: Wide-angle cameras no longer lose field of view at lower resolutions
+  - Root cause: Mode 2 crops the sensor, eliminating the wide-angle advantage
+  - Impact: Users with Camera Module 3 Wide now get full 120° FOV at 720p and 1080p
+  - Verified: `sensor_mode_width/height` shows 2304x1296 (Mode 1) instead of 1536x864 (Mode 2)
+
+### Technical Details
+- New method: `CameraController._detect_wide_camera() -> bool`
+- New method: `CameraController._get_recommended_resolutions() -> list`
+- Updated method: `_get_optimal_sensor_mode()` now accepts camera type parameter
+- New instance variable: `self._is_wide_camera`
+- API models updated: `CameraStatusResponse`, `CameraCapabilitiesResponse`
+- Zero breaking changes - fully backwards compatible
+
+### Use Cases
+- **Surveillance with wide FOV**: Preserve 120° coverage at all resolutions
+- **Dynamic preset selection**: Client can query recommended resolutions for camera type
+- **Intelligent client UIs**: Display appropriate resolution options based on camera capabilities
+- **FOV-aware applications**: Adjust counting lines, detection zones based on actual FOV
+
+### Client Integration Example
+
+```javascript
+// Query camera capabilities
+const capabilities = await fetch('/v1/camera/capabilities').then(r => r.json());
+
+if (capabilities.is_wide_camera) {
+  console.log(`Wide-angle camera detected: ${capabilities.field_of_view_degrees}° FOV`);
+
+  // Use recommended resolutions that preserve full FOV
+  const presets = capabilities.recommended_resolutions.map(res => ({
+    label: res.label,
+    width: res.width,
+    height: res.height,
+    maxFps: res.max_fps,
+    fov: res.fov
+  }));
+}
+```
+
+### Upgrade Notes
+- Existing deployments with Camera Module 3 Wide will automatically benefit from FOV preservation
+- No configuration changes required - detection is automatic
+- Check `/v1/camera/capabilities` to verify camera type detection
+- Recommended to update client UIs to use `recommended_resolutions` endpoint for dynamic presets
+
 ## [2.6.1] - 2025-11-22
 
 ### Added
diff --git a/README.md b/README.md
@@ -2,15 +2,17 @@
 
 Production-ready **FastAPI** microservice for controlling Raspberry Pi Camera (libcamera/Picamera2) with **H.264 streaming** to **MediaMTX** via RTSP.
 
-**Version 2.6.1** - Intelligent bitrate auto-selection prevents encoding errors!
+**Version 2.7.0** - Wide-angle camera support preserves 120° field of view!
 
-[![Version](https://img.shields.io/badge/version-2.6.1-blue.svg)](https://github.com/gmathy2104/pi-camera-service/releases)
+[![Version](https://img.shields.io/badge/version-2.7.0-blue.svg)](https://github.com/gmathy2104/pi-camera-service/releases)
 [![Python](https://img.shields.io/badge/python-3.9+-green.svg)](https://www.python.org/)
 [![FastAPI](https://img.shields.io/badge/FastAPI-0.121+-teal.svg)](https://fastapi.tiangolo.com/)
 [![License](https://img.shields.io/badge/license-MIT-orange.svg)](LICENSE)
 [![Tests](https://github.com/gmathy2104/pi-camera-service/workflows/Tests/badge.svg)](https://github.com/gmathy2104/pi-camera-service/actions)
 
-> 🔥 **New in v2.6.1**: **Intelligent Bitrate Auto-Selection** - Automatic bitrate calculation prevents corrupted macroblock errors. Bitrate now adapts to resolution×framerate (12 Mbps @ 720p/60fps, 25 Mbps @ 1080p/60fps). Visible in status endpoint!
+> 🔥 **New in v2.7.0**: **Wide-Angle Camera Detection** - Automatic detection of Camera Module 3 Wide (120° FOV). Intelligent sensor mode selection preserves full wide-angle field of view at all resolutions. New API fields expose camera type, sensor modes, and recommended resolutions!
+>
+> 🔥 **v2.6.1**: **Intelligent Bitrate Auto-Selection** - Automatic bitrate calculation prevents corrupted macroblock errors. Bitrate now adapts to resolution×framerate (12 Mbps @ 720p/60fps, 25 Mbps @ 1080p/60fps). Visible in status endpoint!
 >
 > ⚡ **v2.6 features**: **Intelligent Sensor Mode Auto-Selection** - Camera Module 3 (IMX708) automatically selects optimal native sensor mode. 720p achieves 60fps (was 14fps) - 4.2x faster!
 >
@@ -216,6 +218,43 @@ This service runs **on the Raspberry Pi**, controls the camera (e.g., Raspberry
   - `max_framerate_for_current_resolution`: Maximum fps for active resolution
   - `framerate_limits_by_resolution`: Complete table of max fps for each resolution
 
+### Advanced Features (v2.7) 🆕
+
+#### 📐 Wide-Angle Camera Detection & FOV Preservation
+- **Automatic camera type detection**: Detects Camera Module 3 Wide (120° FOV) vs standard cameras (66° FOV)
+  - Detection via camera model name (e.g., `imx708_wide_noir`)
+  - Graceful fallback to standard camera if detection fails
+- **Intelligent sensor mode selection**: Preserves wide-angle field of view
+  - **Wide cameras**: Always use full sensor (Mode 0 or Mode 1) to maintain 120° FOV
+  - **Standard cameras**: Can use cropped modes (Mode 2) for higher framerates
+  - **Critical fix**: Wide cameras no longer lose FOV at lower resolutions
+- **New API fields in `GET /v1/camera/status`**:
+  - `is_wide_camera`: Boolean flag for camera type (true = 120° FOV)
+  - `sensor_mode_width`: Current sensor mode width being used
+  - `sensor_mode_height`: Current sensor mode height being used
+- **New API fields in `GET /v1/camera/capabilities`**:
+  - `is_wide_camera`: Camera type detection result
+  - `field_of_view_degrees`: Field of view (120° or 66°)
+  - `sensor_modes`: Complete IMX708 sensor mode specifications
+  - `recommended_resolutions`: Resolution presets optimized for camera type
+    - Wide cameras: Prioritize full FOV preservation
+    - Standard cameras: Prioritize framerate optimization
+- **Perfect for**: Surveillance with wide coverage, dynamic client UIs, FOV-aware applications
+
+**Example - Query camera type and get recommendations**:
+```javascript
+const capabilities = await fetch('/v1/camera/capabilities').then(r => r.json());
+
+if (capabilities.is_wide_camera) {
+  console.log(`Wide-angle camera: ${capabilities.field_of_view_degrees}° FOV`);
+
+  // Use recommended resolutions that preserve full 120° FOV
+  capabilities.recommended_resolutions.forEach(res => {
+    console.log(`${res.label}: ${res.width}x${res.height} @ ${res.max_fps}fps (${res.fov})`);
+  });
+}
+```
+
 ### Advanced Features (v2.5) 🆕
 
 #### 🖥️ System Monitoring & Health Metrics
@@ -472,7 +511,7 @@ sudo journalctl -u pi-camera-service -f
 }
 ```
 
-### Camera Status (Enhanced in v2.0)
+### Camera Status (Enhanced in v2.0, v2.2, v2.7)
 
 **GET** `/v1/camera/status`
 ```json
@@ -504,11 +543,16 @@ sudo journalctl -u pi-camera-service -f
       "min": 100,
       "max": 1000000
     }
-  }
+  },
+
+  // New v2.7 fields (wide-angle camera support)
+  "is_wide_camera": true,
+  "sensor_mode_width": 2304,
+  "sensor_mode_height": 1296
 }
 ```
 
-### Camera Capabilities (New in v2.2, Enhanced in v2.3)
+### Camera Capabilities (New in v2.2, Enhanced in v2.3, v2.7)
 
 **GET** `/v1/camera/capabilities`
 
@@ -550,6 +594,21 @@ Discover camera hardware capabilities and supported features.
     {"width": 1920, "height": 1080, "label": "1080p", "max_fps": 50.0},
     {"width": 1280, "height": 720, "label": "720p", "max_fps": 120.0},
     {"width": 640, "height": 480, "label": "VGA", "max_fps": 120.0}
+  ],
+
+  // New v2.7 fields (wide-angle camera support)
+  "is_wide_camera": true,
+  "field_of_view_degrees": 120,
+  "sensor_modes": {
+    "mode_0": {"width": 4608, "height": 2592, "max_fps": 14.35, "description": "Full sensor, no binning"},
+    "mode_1": {"width": 2304, "height": 1296, "max_fps": 56.03, "description": "Full sensor with 2x2 binning"},
+    "mode_2": {"width": 1536, "height": 864, "max_fps": 120.13, "description": "Cropped sensor with 2x2 binning"}
+  },
+  "recommended_resolutions": [
+    {"width": 2304, "height": 1296, "label": "Native Mode 1", "max_fps": 56, "sensor_mode": "mode_1", "fov": "Full 120°"},
+    {"width": 1920, "height": 1080, "label": "1080p (Full FOV)", "max_fps": 56, "sensor_mode": "mode_1", "fov": "Full 120°"},
+    {"width": 1280, "height": 720, "label": "720p (Full FOV)", "max_fps": 56, "sensor_mode": "mode_1", "fov": "Full 120°"},
+    {"width": 4608, "height": 2592, "label": "4K (Full sensor)", "max_fps": 14, "sensor_mode": "mode_0", "fov": "Full 120°"}
   ]
 }
 ```
diff --git a/camera_service/api.py b/camera_service/api.py
@@ -257,6 +257,11 @@ class CameraStatusResponse(BaseModel):
     bitrate_bps: int | None = Field(None, description="Current bitrate in bits per second")
     bitrate_mbps: float | None = Field(None, description="Current bitrate in megabits per second")
 
+    # Camera type and sensor mode (v2.7.0)
+    is_wide_camera: bool | None = Field(None, description="True if wide-angle camera (120° FOV)")
+    sensor_mode_width: int | None = Field(None, description="Sensor mode width being used")
+    sensor_mode_height: int | None = Field(None, description="Sensor mode height being used")
+
     # Current limits (v2.2)
     current_limits: dict | None = Field(None, description="Currently applied exposure/frame duration limits")
 
@@ -278,6 +283,11 @@ class CameraCapabilitiesResponse(BaseModel):
     current_framerate: float = Field(..., description="Current configured framerate")
     framerate_limits_by_resolution: list[dict] = Field(..., description="Maximum framerate for each resolution")
     max_framerate_for_current_resolution: float = Field(..., description="Maximum framerate for current resolution")
+    # Wide-angle camera info (v2.7.0)
+    is_wide_camera: bool | None = Field(None, description="True if wide-angle camera (120° FOV)")
+    field_of_view_degrees: int | None = Field(None, description="Field of view in degrees (120° or 66°)")
+    sensor_modes: dict | None = Field(None, description="Available sensor modes with specifications")
+    recommended_resolutions: list[dict] | None = Field(None, description="Recommended resolutions for this camera type")
 
 
 class AutoExposureResponse(StatusResponse):
@@ -588,6 +598,11 @@ def get_camera_status(
             bitrate_bps=status_data.get("bitrate_bps"),
             bitrate_mbps=status_data.get("bitrate_mbps"),
 
+            # Camera type and sensor mode (v2.7.0)
+            is_wide_camera=status_data.get("is_wide_camera"),
+            sensor_mode_width=status_data.get("sensor_mode_width"),
+            sensor_mode_height=status_data.get("sensor_mode_height"),
+
             # Current limits (v2.2)
             current_limits=status_data.get("current_limits"),
         )
diff --git a/camera_service/camera_controller.py b/camera_service/camera_controller.py
