chore: 集成今晚相机与解算改进 / integrate nightly camera and solving improvements

.github/workflows/release.yml

@@ -5,6 +5,9 @@ on:
     tags:
       - 'v*'
 
+permissions:
+  contents: write
+
 jobs:
   release:
     runs-on: ubuntu-latest
@@ -23,7 +26,7 @@ jobs:
       run: poetry build
 
     - name: 创建 GitHub Release
-      uses: softprops/action-gh-release@v1
+      uses: softprops/action-gh-release@v2
       with:
         files: dist/*
         generate_release_notes: true
@@ -35,4 +38,3 @@ jobs:
     #   run: poetry publish
     #   env:
     #     POETRY_PYPI_TOKEN_PYPI: ${{ secrets.PYPI_TOKEN }}
-

CONTRIBUTING.md

@@ -132,7 +132,7 @@
 
 流程：`feature/*` / `fix/*` → PR → `staging` → 测试通过后 PR → `main`。
 
-**禁止直接向 `main` 或 `staging` 提交或推送**（本地 pre-commit 会拦截；remote 需配置 GitHub Rulesets 或 Branch protection，见 [.github/scripts/apply-branch-protection.sh](../.github/scripts/apply-branch-protection.sh)）。
+**禁止直接向 `main` 或 `staging` 提交或推送**（本地 pre-commit 会拦截；remote 需配置 GitHub Rulesets 或 Branch protection，见 [.github/scripts/apply-branch-protection.sh](.github/scripts/apply-branch-protection.sh)）。
 
 **已废弃**：不再使用 `develop`、`dev`、`dev-latest` 集成分支。
 

CONTRIBUTING_EN.md

@@ -87,7 +87,7 @@ Thank you for your interest in OGScope. We welcome contributions of all kinds.
 
 Flow: `feature/*` / `fix/*` → PR → `staging` → validated PR → `main`.
 
-**Do not commit or push directly to `main` or `staging`.** Local pre-commit blocks this; configure GitHub Rulesets or branch protection via [.github/scripts/apply-branch-protection.sh](../.github/scripts/apply-branch-protection.sh).
+**Do not commit or push directly to `main` or `staging`.** Local pre-commit blocks this; configure GitHub Rulesets or branch protection via [.github/scripts/apply-branch-protection.sh](.github/scripts/apply-branch-protection.sh).
 
 **Deprecated**: `develop`, `dev`, and `dev-latest` integration branches.
 

README.md

@@ -24,7 +24,8 @@
 ### Phase 2 - 完整功能
 
 - ⏳ SPI 屏幕显示
-- ⏳ 自动板块求解
+- ✅ Tetra3 自动板块求解
+- ✅ 实时解算与调试控制台
 - ⏳ 移动 App 控制
 - ⏳ 校准数据管理
 
@@ -77,7 +78,7 @@ python -m ogscope.main
 
 ### Web 界面访问
 
-启动后访问: [http://raspberrypi.local:8000](http://raspberrypi.local:8000) 或 http://:8000
+启动后访问：[http://raspberrypi.local:8000](http://raspberrypi.local:8000) 或 `http://<设备IP>:8000`
 
 ## 文档
 
@@ -141,4 +142,4 @@ OGScope/
 
 ## 贡献
 
-欢迎提交 Issue 和 Pull Request！详见 [贡献指南](CONTRIBUTING.md)
+欢迎提交 Issue 和 Pull Request！详见 [贡献指南](CONTRIBUTING.md)

README_EN.md

@@ -22,7 +22,8 @@ English | [中文](README.md)
 
 ### Phase 2 - Complete Features
 - ⏳ SPI screen display
-- ⏳ Automatic plate solving
+- ✅ Tetra3 automatic plate solving
+- ✅ Realtime solve and debug console
 - ⏳ Mobile app control
 - ⏳ Calibration data management
 
@@ -43,13 +44,13 @@ English | [中文](README.md)
 - **Processor**: Raspberry Pi Zero 2W (ARM Cortex-A53)
 - **Camera**: IMX327 sensor (1920x1080)
 - **Display**: 2.4" SPI LCD (240x320)
-- **Software**: Python 3.9 + FastAPI
+- **Software**: Python 3.10+ + FastAPI
 
 ## Quick Start
 
 ### Requirements
 
-- Python 3.9+
+- Python 3.10+
 - Poetry 1.2+
 - Raspberry Pi Zero 2W (Raspberry Pi OS)
 
@@ -139,4 +140,3 @@ See [LICENSE](LICENSE) file for details.
 ## Contributing
 
 Issues and Pull Requests are welcome! See [Contributing Guide](CONTRIBUTING.md) for details.
-

deploy/ogscope.env.example

@@ -41,7 +41,10 @@ OGSCOPE_RELOAD=false
 # OGSCOPE_CAMERA_EXPOSURE=10000
 # OGSCOPE_CAMERA_GAIN=1.0
 # OGSCOPE_CAMERA_AE_POLAR_PRESET=true
-# OGSCOPE_CAMERA_AE_EXPOSURE_VALUE=0.35
+# OGSCOPE_CAMERA_AE_EXPOSURE_VALUE=1.0
+# OGSCOPE_CAMERA_AE_AGGRESSIVE_ENABLED=true
+# OGSCOPE_CAMERA_AUTO_EXPOSURE_MAX_US=1000000
+# OGSCOPE_CAMERA_TUNING_FILE=/path/to/imx327-override.json
 # OGSCOPE_CAMERA_FLIP_HORIZONTAL=false
 # OGSCOPE_CAMERA_FLIP_VERTICAL=false
 
@@ -54,6 +57,7 @@ OGSCOPE_RELOAD=false
 # OGSCOPE_KEEP_RAW_CACHE=false
 # OGSCOPE_STREAM_MAX_MJPEG_CLIENTS=4
 # OGSCOPE_STREAM_MJPEG_FRAME_FETCH_TIMEOUT_MS=20000
+# OGSCOPE_STREAM_MJPEG_CLIENT_STALL_TIMEOUT_MS=30000
 
 # --- SPI 屏幕 / SPI display ---
 # OGSCOPE_DISPLAY_ENABLED=false

docs/DEBUG_CONSOLE.md

@@ -13,14 +13,21 @@ OGScope 调试控制台是一个专为开发者设计的相机调试工具，提
 - 支持启动/停止预览
 - 实时状态显示：采集帧率、预览帧率、曝光、消费者数量、编码器与内存压力
 
+### ✨ 星点焦点校准
+- 一键进入焦点校准，自动持续测量多颗可用星点的 HFD 与 FWHM
+- 用“继续、接近最佳、向错误方向”等直观提示引导用户缓慢旋转镜头
+- 记录本次调焦的最佳 HFD 与变化趋势；数值越低通常越锐利
+- 可直接点击预览中的星点锁定目标，也可恢复自动多星统计
+- 自动排除饱和、信噪比不足或形状异常的星点，避免误导
+
 ### 📸 拍摄控制
 - **单张拍摄**: 拍摄高质量照片并自动保存
 - **视频录制**: 手动控制录制时长，支持MP4格式
 - **文件命名**: 自动生成时间戳文件名
 - **参数记录**: 每次拍摄自动生成参数记录文件
 
 ### ⚙️ 参数设置
-- **曝光时间**: 1ms - 100ms (微秒级调节)
+- **曝光时间**: 0.1ms–1s（微秒级调节，与自动曝光上限一致）
 - **模拟增益**: 1x - 16x (0.1x步进)
 - **数字增益**: 1x - 4x (0.1x步进)
 - **白平衡**: `auto` / `manual` / `night`，手动模式可设置红/蓝增益
@@ -83,23 +90,29 @@ python -m ogscope.web.app
    - 拖动滑块调整曝光和增益
    - 点击 "应用设置" 使参数生效
 
-3. **拍摄照片**
+3. **校准焦点（可选）**
+   - 点击预览区的“开始焦点校准”
+   - 工具会锁定当前实测曝光/增益并临时关闭降噪，完成或离开时恢复原设置
+   - 缓慢旋转镜头，观察 HFD 数值与趋势提示
+   - 让 HFD 尽可能接近本次最佳值；小星点未被自动选中时，直接点击画面中的星点强制局部测量
+
+4. **拍摄照片**
    - 切换到 "拍摄控制" 标签页
    - 点击 "拍摄照片" 按钮
    - 照片自动保存到 `~/dev_captures/` 目录
 
-4. **录制视频**
+5. **录制视频**
    - 点击 "开始录制" 按钮
    - 录制过程中显示计时器
    - 点击 "停止录制" 结束录制
 
-5. **管理预设**
+6. **管理预设**
    - 切换到 "预设管理" 标签页
    - 输入预设名称和描述
    - 点击 "保存预设" 保存当前设置
    - 点击预设卡片上的 "应用" 快速切换
 
-6. **查看文件**
+7. **查看文件**
    - 切换到 "文件管理" 标签页
    - 查看所有拍摄文件
    - 点击 "下载" 下载文件到本地
@@ -151,6 +164,7 @@ python -m ogscope.web.app
 - `POST /api/dev/debug/camera/start` - 启动相机
 - `POST /api/dev/debug/camera/stop` - 停止相机
 - `GET /api/dev/debug/camera/preview` - 获取预览图像
+- `GET /api/dev/debug/camera/focus/metrics` - 获取当前帧的星点焦点指标
 
 ### 拍摄功能
 - `POST /api/dev/debug/camera/capture` - 拍摄照片
@@ -224,7 +238,8 @@ python scripts/test_debug_console.py --test deps
 | `camera_white_balance_mode` | `auto` | `auto` / `manual` / `night` |
 | `camera_white_balance_gain_r` / `camera_white_balance_gain_b` | `1.0` | 手动白平衡红/蓝增益 |
 | `camera_night_mode` | `false` | 启动时应用夜间白平衡标记 |
-| `camera_auto_exposure_max_us` | `2000000` | 自动曝光最长帧周期，暗场允许降低帧率 |
+| `camera_tuning_file` | 空 | 可选 Picamera2 tuning 覆盖路径；默认加载产品内置 IMX327 tuning |
+| `camera_auto_exposure_max_us` | `1000000` | 自动曝光最长帧周期，暗场允许降至约 1 fps |
 | `camera_ae_flicker_mode` | `off` | `off` / `50hz` / `60hz` |
 | `camera_noise_reduction_mode` | `fast` | `off` / `fast` / `high_quality` |
 | `camera_lores_enabled` | `true` | 启用低分辨率辅助流统计 |

docs/DEBUG_CONSOLE_EN.md

@@ -13,14 +13,21 @@ The OGScope debug console is a developer-focused camera tool: live preview, capt
 - Start/stop preview
 - Live status: capture FPS, preview FPS, exposure, consumers, encoder, and memory pressure
 
+### Star focus calibration
+- Start a guided focusing session and continuously measure multi-star HFD and FWHM.
+- Follow plain-language guidance such as keep turning, near best, or wrong direction.
+- Track the best HFD and recent trend for the current session; lower is normally sharper.
+- Click a star in the preview to lock it, or return to automatic multi-star aggregation.
+- Saturated, low-SNR, and badly shaped candidates are excluded to avoid misleading scores.
+
 ### Capture
 - **Still capture**: high-quality photos with auto-save
 - **Video recording**: manual duration, MP4
 - **Filenames**: timestamp-based names
 - **Sidecar metadata**: `.txt` parameter file per capture
 
 ### Parameters
-- **Exposure**: 1ms–100ms (fine steps)
+- **Exposure**: 0.1ms–1s (fine steps, aligned with the auto-exposure ceiling)
 - **Analog gain**: 1x–16x (0.1x steps)
 - **Digital gain**: 1x–4x (0.1x steps)
 - **White balance**: `auto` / `manual` / `night`; manual mode exposes red/blue gains
@@ -68,10 +75,11 @@ Browser: `http://localhost:8000/debug`
 
 1. **Start preview** — click Start, wait for init, view stream.
 2. **Tune parameters** — Parameters tab, adjust sliders, Apply.
-3. **Capture still** — Capture tab, Capture photo; files under `~/dev_captures/`.
-4. **Record video** — Start recording, stop when done.
-5. **Presets** — Presets tab: name, description, Save; Apply from cards.
-6. **Files** — Files tab: list, download, details.
+3. **Calibrate focus (optional)** — start focus calibration, rotate the lens slowly, and minimize HFD. Click a preview star when you want to lock the target.
+4. **Capture still** — Capture tab, Capture photo; files under `~/dev_captures/`.
+5. **Record video** — Start recording, stop when done.
+6. **Presets** — Presets tab: name, description, Save; Apply from cards.
+7. **Files** — Files tab: list, download, details.
 
 ### Keyboard shortcuts
 
@@ -115,6 +123,7 @@ Browser: `http://localhost:8000/debug`
 - `POST /api/dev/debug/camera/start`
 - `POST /api/dev/debug/camera/stop`
 - `GET /api/dev/debug/camera/preview`
+- `GET /api/dev/debug/camera/focus/metrics`
 
 ### Capture
 - `POST /api/dev/debug/camera/capture`
@@ -179,7 +188,8 @@ These settings enter runtime through environment variables or config files. Name
 | `camera_white_balance_mode` | `auto` | `auto` / `manual` / `night` |
 | `camera_white_balance_gain_r` / `camera_white_balance_gain_b` | `1.0` | Manual white-balance red/blue gains |
 | `camera_night_mode` | `false` | Apply night white-balance flag at startup |
-| `camera_auto_exposure_max_us` | `2000000` | Longest AE frame duration for dark fields |
+| `camera_tuning_file` | empty | Optional Picamera2 tuning override path; the bundled IMX327 tuning is used by default |
+| `camera_auto_exposure_max_us` | `1000000` | Longest AE frame duration; dark scenes may fall to about 1 fps |
 | `camera_ae_flicker_mode` | `off` | `off` / `50hz` / `60hz` |
 | `camera_noise_reduction_mode` | `fast` | `off` / `fast` / `high_quality` |
 | `camera_lores_enabled` | `true` | Enable the low-resolution helper stream |