docs: release v2.4.0 - FOV mode selection feature

Add comprehensive documentation for Field of View (FOV) mode selection feature:
- Choose between 'scale' (constant FOV) and 'crop' (digital zoom) modes
- New endpoints: GET/POST /v1/camera/fov_mode
- Enhanced resolution endpoint with optional fov_mode parameter

Updated files:
- camera_service/api.py: Updated version to 2.4.0
- tests/test_api_integration.py: Updated expected version
- CHANGELOG.md: Added v2.4.0 release notes with FOV mode details
- README.md: Added FOV mode section and updated version references
- docs/api-reference.md: Added FOV mode endpoints documentation

FOV Modes:
- scale (default): Full sensor readout + ISP downscaling = constant FOV
- crop: Sensor crop for target resolution = digital zoom effect

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: gmathy2104

CHANGELOG.md

@@ -5,6 +5,50 @@ 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.4.0] - 2025-11-22
+
+### Added
+
+#### Field of View (FOV) Mode Selection
+- **NEW FEATURE**: Choose between two FOV modes for different use cases
+  - **"scale" mode** (default): Constant field of view at all resolutions
+    - Reads full sensor area (4608x2592 for IMX708)
+    - Hardware ISP downscales to target resolution
+    - Better image quality (downsampling vs cropping)
+    - Ideal for monitoring, surveillance, and consistent framing
+  - **"crop" mode**: Digital zoom effect with sensor crop
+    - Reads only required sensor area for target resolution
+    - FOV reduces at lower resolutions (telephoto effect)
+    - Lower processing load, faster sensor readout
+    - Useful for zoom/telephoto applications
+
+#### New API Endpoints
+- `GET /v1/camera/fov_mode` - Query current FOV mode
+  - Returns: `{"mode": "scale", "description": "..."}`
+- `POST /v1/camera/fov_mode` - Change FOV mode
+  - Request: `{"mode": "scale"}` or `{"mode": "crop"}`
+  - Takes effect on next resolution/framerate change
+
+#### Enhanced Resolution Endpoint
+- Added optional `fov_mode` parameter to `POST /v1/camera/resolution`
+  - Can change FOV mode and resolution in single request
+  - Example: `{"width": 1280, "height": 720, "fov_mode": "crop"}`
+
+#### Enhanced Status Response
+- Added `fov_mode` field to `GET /v1/camera/status`
+  - Shows current FOV mode ("scale" or "crop")
+
+### Changed
+- Default FOV mode is now "scale" for constant field of view across all resolutions
+- All resolution/framerate changes now maintain configurable FOV behavior
+- Camera configuration uses conditional sensor parameters based on FOV mode
+
+### Technical Details
+- New `CameraController` methods: `set_fov_mode()`, `get_fov_mode()`, `_get_sensor_config()`
+- FOV mode persists across camera reconfigurations
+- Thread-safe implementation with existing RLock protection
+- Zero breaking changes - fully backwards compatible
+
 ## [2.3.1] - 2025-11-22
 
 ### Fixed

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.3.1** - Critical race condition fix + Dynamic framerate control with intelligent clamping!
+**Version 2.4.0** - FOV mode selection (scale/crop) + Dynamic framerate control!
 
-[![Version](https://img.shields.io/badge/version-2.3.1-blue.svg)](https://github.com/gmathy2104/pi-camera-service/releases)
+[![Version](https://img.shields.io/badge/version-2.4.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.3**: Dynamic framerate control with intelligent clamping! Request any framerate and the API automatically applies the maximum for your resolution. Enhanced capabilities endpoint with complete framerate limits table.
+> 🆕 **New in v2.4**: **FOV mode selection** - Choose between constant field of view (scale) or digital zoom effect (crop) for all resolutions. Perfect control for surveillance or telephoto applications!
+>
+> ℹ️ **v2.3 features**: Dynamic framerate control with intelligent clamping. Fixed critical race condition in concurrent camera reconfiguration.
 >
 > ℹ️ **v2.2 features**: Camera capabilities discovery endpoint to query supported resolutions, exposure/gain limits, and available features.
 >
@@ -381,7 +383,7 @@ sudo journalctl -u pi-camera-service -f
   "status": "healthy",
   "camera_configured": true,
   "streaming_active": true,
-  "version": "2.3.1"
+  "version": "2.4.0"
 }
 ```
 
@@ -467,6 +469,53 @@ Discover camera hardware capabilities and supported features.
 }
 ```
 
+### Field of View (FOV) Mode (New in v2.4)
+
+Choose between constant field of view or digital zoom effect across all resolutions.
+
+**GET** `/v1/camera/fov_mode`
+
+Query current FOV mode.
+
+```json
+{
+  "mode": "scale",
+  "description": "Full sensor readout with downscaling → Constant field of view"
+}
+```
+
+**POST** `/v1/camera/fov_mode`
+
+Change FOV mode.
+
+```json
+{"mode": "scale"}  // or "crop"
+```
+
+**Modes:**
+- **`scale`** (default): Constant field of view at all resolutions
+  - Reads full sensor area (4608x2592 for IMX708)
+  - Hardware ISP downscales to target resolution
+  - Better image quality from downsampling
+  - Perfect for surveillance, monitoring, consistent framing
+
+- **`crop`**: Digital zoom effect (sensor crop)
+  - Reads only required sensor area for target resolution
+  - FOV reduces at lower resolutions (telephoto effect)
+  - Lower processing load, faster readout
+  - Useful for zoom/telephoto applications
+
+**Example - Set FOV mode with resolution:**
+```json
+POST /v1/camera/resolution
+{
+  "width": 1280,
+  "height": 720,
+  "fov_mode": "crop",  // Optional: change mode simultaneously
+  "restart_streaming": true
+}
+```
+
 ### Exposure Control
 
 **POST** `/v1/camera/auto_exposure`

camera_service/api.py

@@ -168,7 +168,7 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
 app = FastAPI(
     title="Pi Camera Service",
     description="API for controlling Raspberry Pi camera and streaming to MediaMTX via RTSP",
-    version="2.3.1",
+    version="2.4.0",
     lifespan=lifespan,
 )
 
@@ -491,7 +491,7 @@ def health_check() -> HealthResponse:
         status="healthy" if camera_controller is not None else "initializing",
         camera_configured=camera_controller._configured if camera_controller else False,
         streaming_active=streaming_manager.is_streaming() if streaming_manager else False,
-        version="2.3.1",
+        version="2.4.0",
     )
 
 

docs/api-reference.md

@@ -2,13 +2,17 @@
 
 This document provides a complete reference for the Pi Camera Service HTTP API, including all available features, endpoints, and connection instructions.
 
+> **Note**: This document primarily covers v1.0 API endpoints. For comprehensive documentation of v2.0+ features (autofocus, snapshot, HDR, exposure value, noise reduction, capabilities, framerate control, FOV mode, etc.), see the main [README.md](../README.md).
+>
+> **New in v2.4**: Field of View (FOV) mode selection - documented below.
+
 ## Overview
 
 The Pi Camera Service is a REST API that controls a Raspberry Pi camera and streams H.264 video to MediaMTX via RTSP. It provides real-time control over camera settings including exposure, gain, white balance, and streaming.
 
 **Base URL:** `http://<RASPBERRY_PI_IP>:8000`
 
-**API Version:** v1.0
+**API Version:** v2.4.0 (this document covers v1.0 core features + v2.4 FOV mode)
 
 **Protocol:** HTTP/REST
 
@@ -371,6 +375,144 @@ curl -X POST http://<PI_IP>:8000/v1/camera/awb \
 
 ---
 
+#### POST /v1/camera/fov_mode (v2.4)
+
+Set the Field of View (FOV) mode to control sensor readout behavior across different resolutions.
+
+**Authentication:** Required (if configured)
+
+**Request Body:**
+```json
+{
+  "mode": "scale"
+}
+```
+
+**Request Fields:**
+- `mode` (string, required): FOV mode - either `"scale"` or `"crop"`
+
+**Response:**
+```json
+{
+  "status": "ok",
+  "mode": "scale",
+  "description": "Full sensor readout with downscaling → Constant field of view"
+}
+```
+
+**FOV Modes:**
+
+- **`scale`** (default): Constant field of view at all resolutions
+  - Reads full sensor area (4608x2592 for IMX708)
+  - Hardware ISP downscales to target resolution
+  - Better image quality from downsampling vs cropping
+  - Perfect for surveillance, monitoring, consistent framing
+  - Use when you want the same field of view regardless of resolution
+
+- **`crop`**: Digital zoom effect (sensor crop)
+  - Reads only required sensor area for target resolution
+  - FOV reduces at lower resolutions (telephoto effect)
+  - Lower processing load, faster sensor readout
+  - Useful for zoom/telephoto applications
+  - Use when you want a "zoomed in" view at lower resolutions
+
+**Example - Set to scale mode:**
+```bash
+curl -X POST http://<PI_IP>:8000/v1/camera/fov_mode \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: your-key" \
+  -d '{"mode": "scale"}'
+```
+
+**Example - Set to crop mode:**
+```bash
+curl -X POST http://<PI_IP>:8000/v1/camera/fov_mode \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: your-key" \
+  -d '{"mode": "crop"}'
+```
+
+**Python Example:**
+```python
+import requests
+
+# Set to scale mode for constant FOV
+response = requests.post(
+    "http://<PI_IP>:8000/v1/camera/fov_mode",
+    headers={"X-API-Key": "your-key"},
+    json={"mode": "scale"}
+)
+print(response.json())
+
+# Set to crop mode for digital zoom effect
+response = requests.post(
+    "http://<PI_IP>:8000/v1/camera/fov_mode",
+    headers={"X-API-Key": "your-key"},
+    json={"mode": "crop"}
+)
+print(response.json())
+```
+
+**Combined with Resolution Change:**
+
+You can also set FOV mode when changing resolution:
+
+```bash
+curl -X POST http://<PI_IP>:8000/v1/camera/resolution \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: your-key" \
+  -d '{
+    "width": 1280,
+    "height": 720,
+    "fov_mode": "crop",
+    "restart_streaming": true
+  }'
+```
+
+**When to Use:**
+- Use `scale` for surveillance cameras where consistent framing is essential
+- Use `crop` when you want different zoom levels at different resolutions
+- Change to `crop` before lowering resolution if you want a telephoto effect
+- Change to `scale` if lower resolutions appear too zoomed in
+
+**Note:** Changes take effect on the next camera reconfiguration (resolution/framerate change).
+
+---
+
+#### GET /v1/camera/fov_mode (v2.4)
+
+Query the current FOV mode.
+
+**Authentication:** Required (if configured)
+
+**Response:**
+```json
+{
+  "mode": "scale",
+  "description": "Full sensor readout with downscaling → Constant field of view"
+}
+```
+
+**Example:**
+```bash
+curl -H "X-API-Key: your-key" http://<PI_IP>:8000/v1/camera/fov_mode
+```
+
+**Python Example:**
+```python
+import requests
+
+response = requests.get(
+    "http://<PI_IP>:8000/v1/camera/fov_mode",
+    headers={"X-API-Key": "your-key"}
+)
+mode_info = response.json()
+print(f"Current FOV mode: {mode_info['mode']}")
+print(f"Description: {mode_info['description']}")
+```
+
+---
+
 ### Streaming Control Endpoints
 
 #### POST /v1/streaming/start

tests/test_api_integration.py

@@ -62,7 +62,7 @@ def test_health_endpoint(self) -> None:
         assert data["status"] == "healthy"
         assert "camera_configured" in data
         assert "streaming_active" in data
-        assert data["version"] == "2.3.1"
+        assert data["version"] == "2.4.0"
 
         print("✓ Health endpoint working")