docs: rewrite README, sync notices, and ignore local AI docs

This commit is contained in:
2026-11-19 22:55:37 -05:00
parent 9359779afa
commit f39a548ba3
5 changed files with 70 additions and 87 deletions

2
.gitignore vendored
View File

@@ -1,4 +1,6 @@
.superpowers/
chat-summaries/
docs/superpowers/
app/build/
app/build-arm64/
packaging/dist/

147
README.md
View File

@@ -1,121 +1,100 @@
> [!IMPORTANT]
> This project was developed with AI coding assistance and has not yet undergone a full hardware soak test on physical CM0 hardware. It is provided under the Apache 2.0 license and may require adjustment for other environments.
> This project was developed entirely with AI coding assistance (Google Neon) and has not undergone rigorous review. It is provided as-is and may require adjustments for other environments.
# `czcamera` — CardputerZero Camera App
# `czcamera`
A dedicated `320×170` camera, video, timelapse, and gallery application built for the **M5Stack CardputerZero** (Raspberry Pi CM0, ARM64 Debian Bookworm, non-touch `/dev/fb0`, 46-key `cp0-keys`, 8MP Sony IMX219 CSI-2 sensor, ES8389 MEMS microphone & speaker), styled with `shadcn/ui` Zinc Dark and Light themes.
`czcamera` is a camera application for the M5Stack CardputerZero that replaces the stock Camera app. It adds true cropped zoom, a separate focus loupe, nine live photo filters, video recording with microphone audio, foreground timelapse capture, and an on-device gallery with video playback.
Includes a desktop **SDL2 simulator** (`--sim`) with a procedural test scene (`--mock-cam`) and headless PPM snapshot runner (`--render-test`) for macOS and Linux development.
## What it adds over the stock camera
---
| Feature | Stock Camera | `czcamera` |
|---|---|---|
| Photos | Unfiltered stills only | `8MP` / `2MP` stills, EV (`-2.0` to `+2.0`), `3s`/`10s` self-timer, grid overlay |
| Zoom and framing | Preview magnification only (saved photos stay uncropped) | Cropped zoom (`1.0x` to `4.0x`) in Photo, Video, and Timelapse, plus a `2x` viewfinder-only Loupe (`Z`) |
| Filters | None | 9 live-previewed filters baked into JPEGs (`None`, `B&W`, `Hi-Con`, `Sepia`, `Cool`, `Vivid`, `Invert`, `Retro`, `GameBoy`) |
| Video | None | `480p`, `720p`, or `1080p` `.mp4` at 30fps with mic audio (`M` mute toggle, muted fallback), live viewfinder, and live zoom/loupe |
| Timelapse | None | Custom intervals (`1-3600s`), `1-30` FPS, manual/shot/duration stop limits, raw JPEG folder or compiled `.mp4`, auto-dim with safe wake, crash recovery |
| Gallery and playback | Basic still viewing | Full-screen browser for photos, timelapse folders, and on-device `.mp4` playback with speaker audio, `-5s`/`+5s` seek, and `[Y/N]` delete confirmation |
| Interface and storage | Fixed layout and defaults | Dark/Light themes, left/right control rail swap, camera orientation options, configurable output directory (`~/Pictures/czcamera` default), and hidden staging files for external sync tools |
## Key Features
## Features and usage
- **Option A Split Layout (`320×170`):** Live `226×170` viewfinder alongside a focusable `94×170` control rail (`1P · 2V · 3T`), with live **`[W]`** rail-side toggle (`right` default or `left`) and **`[T]`** Zinc Dark / Light theme toggle.
- **Photo Mode + 9 Filters:** True ISP `ScalerCrop` zoom (`1x`–`4x` via `5`/`7`), independent `2x` viewfinder-only **Loupe** (`Z`), EV (`-2.0` to `+2.0`), `8MP` / `2MP` presets (`R`), `Off`/`3s`/`10s` self-timer (`C`), `[G]` rule-of-thirds grid, and 9 shared RGB24/`libjpeg` filters (`None` zero-re-encode passthrough, `B&W`, `Hi-Con`, `Sepia`, `Cool`, `Vivid`, `Invert`, `Retro`, and Bayer-dithered `GameBoy` DMG).
- **Hardware H.264 Video Mode:** `720p30` (default), `1080p30`, and `480p30` `.mp4` recording with ES8389 MEMS mic ON by default (`[M]` idle mute toggle, graceful muted fallback on `audio_unavailable`), live 16:9 letterboxed viewfinder, and live digital zoom (`5`/`7`) and `2x` Loupe (`Z`) during capture.
- **Foreground Timelapse Mode:** `2MP` default (`1080p` / `8MP` presets), customizable interval, any FPS `1..30`, and stop presets (`C` / `P`), live zoom (`5`/`7`) & `2x` Loupe (`Z`), output to `TL_<timestamp>/` JPEGs or compiled `TL_<timestamp>.mp4` (`h264_v4l2m2m` at memory-safe `1024×768` / `1280×720` with low-RAM `libx264` fallback), sysfs backlight auto-dim + **dimmed safe-wake** (any keypress only wakes the display), and startup recovery for orphaned `.tl_work_*` sessions.
- **Full-Screen Gallery & Video Playback (`[8]`):** Pauses the camera backend while open, supports `TL_*` session drill-down, plays `.mp4` videos (with or without audio tracks) via `ffmpeg`/`aplay` (or SDL2 audio on desktop) with `-5s`/`+5s` seek, and enforces `[Y/N]` delete confirmation.
- **Settings & Directory Tree Picker (`[S]`):** Output folder browser (plus `[T]` manual path entry), `Camera Orient` (`auto`, `0°`, `180°`, `H-Flip`, `V-Flip` via ISP `Transform`), rail side, theme, grid, and auto-dim timeout.
- **Sync-Safe & Hardware-Decoupled:** Writes exclusively to `.`-prefixed staging paths until finalized via `fsync` + atomic `rename()` (with a `100 MB` free-space guard), keeping zero runtime/packaging dependencies on external sync tools or direct `libcamera.so` linkage.
The interface splits the screen between a live viewfinder and a control rail with tabs for Photo (`1`), Video (`2`), and Timelapse (`3`). Navigate rail cards and menus with the arrow keys or `h`/`j`/`k`/`l`, swap the rail between the left and right edges with `W`, switch between Dark and Light themes with `T`, and toggle the rule-of-thirds grid with `G`.
---
### Photo (`1`)
## Architecture Overview
Photo mode saves `8MP` (default) or `2MP` (`R`) JPEGs with EV adjustment (`-2.0` to `+2.0`), an `Off`/`3s`/`10s` self-timer (`C`), `1.0x` to `4.0x` cropped zoom (`5`/`7`), and a `2x` viewfinder-only Loupe (`Z`) to check focus without cropping the final image. Pressing `F` cycles all nine filters on the live preview; `None` saves the sensor JPEG directly without re-encoding.
| Component | Path | Target / Role | Purpose |
|---|---|---|---|
| **C++17 UI & Core** | [`app/`](app/) | CardputerZero (`/dev/fb0` + `cp0-keys`) & macOS (`--sim`) | `czcamera` binary & `czcamera_core` library (`ShadcnCanvas`, `UiController`, filters/JPEG, timelapse engine, gallery model, `VideoPlayer`, and 5 CTest suites). |
| **Python Camera Worker** | [`cam-helper/`](cam-helper/) | CardputerZero (`czcamera-cam`) & `--mock-driver` | Dual-stream (`main` + `lores`) `python3-picamera2` worker driven by newline JSON v1 + 16-byte `CZFR` binary frame pipe. |
| **ARM64 Packaging** | [`packaging/`](packaging/) | ARM64 Docker (`bookworm-slim`) / Debian | Builds `czcamera_1.0.0_m5stack1_arm64.deb` installing `czcamera`, `czcamera-cam`, `czcamera_cam`, and the `APPLaunch` entry/icon. |
### Video (`2`)
---
In Video (`2`), pressing `Enter`, `Space`, or `6` records `720p30` (default), `1080p30`, or `480p30` `.mp4` clips (`R` cycles resolution while idle). The microphone is on by default (`M` toggles mute while idle), and if audio capture is unavailable the app falls back to recording a silent `.mp4`. Zoom (`5`/`7`) and Loupe (`Z`) stay active during recording, which stops automatically if free space drops below `100 MB`.
## Quick Start
### Timelapse (`3`)
### 1. Build & Install on CardputerZero (Docker on macOS/Linux → CM0)
Timelapse shoots `2MP` (default), `1080p`, or `8MP` (`R`) sequences using preset or custom intervals (`1-3600s` via `C` or `P`), `1-30` playback FPS, and manual, shot-count, or duration stop limits. Sessions save as a `TL_<timestamp>/` JPEG folder or compile into `TL_<timestamp>.mp4`. During a run, the screen dims automatically, any keypress wakes the display first without cancelling capture, and unfinished sessions trigger a recovery prompt on the next launch.
Ensure Docker Desktop is running with `linux/arm64` support, then build `packaging/dist/czcamera_1.0.0_m5stack1_arm64.deb`:
### Gallery (`8`) and settings (`S`)
Press `8` to pause the camera and open the full-screen gallery, sorted newest first. From there you can open `TL_*` folders, play `.mp4` files with speaker audio, seek `-5s` or `+5s`, and delete items after a `[Y/N]` confirmation. Settings (`S`) covers the output directory (folder tree picker or manual path entry via `T`), rail side, theme, grid overlay, timelapse auto-dim timeout, and camera orientation (`auto`, `0`, `180`, `hflip`, `vflip`).
## Installation
Build the ARM64 `.deb` package on macOS or Linux with Docker (`linux/arm64` enabled), or pass `--local` to build directly on the CardputerZero:
```bash
./packaging/build-deb.sh
scp packaging/dist/czcamera_1.0.0_m5stack1_arm64.deb pi@<cardputerzero-host>:/tmp/
```
Install on the CardputerZero:
Install the package on the device:
```bash
sudo dpkg -i /tmp/czcamera_1.0.0_m5stack1_arm64.deb
sudo apt-get install -f
```
Launch **czcamera** from the `APPLaunch` app grid or run `/usr/bin/czcamera` directly.
Launch `czcamera` from `APPLaunch` or run `/usr/bin/czcamera`. Remove it with `sudo apt-get remove czcamera`.
### 2. Run the Desktop Simulator (macOS / Linux)
For the desktop SDL2 simulator, native device builds, and unit tests, see [Building, installation, and desktop simulator](docs/building-and-installation.md).
```bash
cmake -S app -B app/build -DCZ_BUILD_APP=ON -DCZ_BUILD_TESTS=ON
cmake --build app/build
./app/build/czcamera --sim --scale 3
```
## Keyboard shortcuts
Run the unit test suites anytime:
```bash
ctest --test-dir app/build --output-on-failure
PYTHONPATH=cam-helper python3 -W error -m unittest discover -s cam-helper/tests -v
python3 -m unittest discover -s packaging/tests -v
```
---
## Core Keyboard Shortcuts (`320×170`)
| Key | Where | Action |
| Key | Context | Action |
|---|---|---|
| `1`, `2`, `3` | Main View | Switch between **Photo**, **Video**, and **Timelapse** |
| `Enter`, `Space`, `6` | Main View | Trigger shutter / Start-Stop recording / Open Timelapse stop prompt |
| `Up`/`Down` or `k`/`j` | Rail / Lists / Modals | Move selection cursor |
| `Left`/`Right` or `h`/`l` | Rail / Settings | Cycle selected card value |
| `5` / `7` | Photo / Video / Timelapse | Step ISP digital crop zoom (`1.0x`–`4.0x`, live during Video & Timelapse) |
| `Z` | Photo / Video / Timelapse | Toggle `2x` viewfinder-only Loupe (works idle or recording/capturing) |
| `F` | Photo | Cycle 9 photo filters (`None` .. `GameBoy`) |
| `R` | Photo / Video / TL (or Offline) | Cycle resolution preset (or recover camera when `Offline`) |
| `C` | Photo / Timelapse | Cycle self-timer (`Off`/`3s`/`10s`) in Photo; open Custom TL modal in Timelapse |
| `M` | Video (idle) / Gallery video | Toggle ES8389 mic audio / Toggle playback mute |
| `G` | Main View | Toggle rule-of-thirds viewfinder grid |
| `W` | Main View | Swap control rail side (`right` ↔ `left`) |
| `T` | Main View / Gallery / DirPicker | Toggle Zinc Dark / Light theme (or type path inside DirPicker) |
| `8` | Main View | Pause camera and open full-screen **Gallery** |
| `S` | Main View | Open **Settings** modal |
| `Esc` / `Q` | Dimmed Timelapse / Modals / Main | Wake dimmed screen safely (first key), cancel/close modal, or exit to `APPLaunch` |
| `1`, `2`, `3` | Main view / Gallery | Switch to Photo, Video, or Timelapse |
| `Enter`, `Space`, `6` | Main view | Take photo, start/stop video, or start timelapse / open stop prompt |
| `Up`/`Down` or `k`/`j` | Rail / Lists / Modals | Move cursor up or down |
| `Left`/`Right` or `h`/`l` | Rail / Settings / Video playback | Cycle selected setting, or seek `-5s`/`+5s` during video playback |
| `5` / `7` | Photo / Video / Timelapse | Step cropped digital zoom (`1.0x` to `4.0x`, works during video and timelapse) |
| `Z` | Photo / Video / Timelapse | Toggle `2x` viewfinder-only Loupe (idle or active capture) |
| `F` | Photo | Cycle 9 photo filters (`None` through `GameBoy`) |
| `R` | Main view / Offline | Cycle resolution preset, or retry camera startup when `Offline` |
| `C` (or `P` in TL) | Photo / Timelapse | Cycle self-timer (`Off`/`3s`/`10s`) in Photo; open custom setup in Timelapse |
| `M` | Video (idle) / Gallery video | Toggle microphone recording / Toggle playback mute |
| `G` | Main view | Toggle rule-of-thirds grid |
| `W` | Main view | Flip control rail between right and left |
| `T` | Main view / Gallery / DirPicker | Toggle Dark / Light theme (or enter path manually in DirPicker) |
| `8` | Main view | Pause camera and open Gallery |
| `S` | Main view | Open Settings |
| `D` / `Delete` | Gallery | Prompt `[Y/N]` to delete selected item |
| `Esc` / `Q` | Dimmed TL / Modals / Main | Wake dimmed screen safely (first press), close/cancel modal, or exit |
---
## Troubleshooting
| Symptom | Check or fix |
|---|---|
| `Camera Offline [R]` on launch | Press `R` to retry startup. If it stays offline, check `grep imx219 /boot/firmware/config.txt` and `rpicam-hello --list-cameras`. |
| Video records without audio (`audio_unavailable`) | When audio capture fails, `czcamera` records a silent `.mp4` instead of dropping the clip. Check ALSA inputs with `arecord -l` and `alsamixer`. |
| Upside-down or mirrored preview | Open Settings (`S`) and cycle `Camera Orient` (`auto`, `0`, `180`, `hflip`, `vflip`). |
| Recovery prompt appears on startup | An earlier timelapse ended before finishing. Press `C` to compile frames to `.mp4`, `K` to keep the raw JPEGs, `D` to discard them, or `Esc` to defer. |
| Capture refuses to start or stops early | `czcamera` checks for at least `100 MB` free on the target mount before starting and during video or timelapse runs. |
## Documentation
- **[Building & Installation Guide](docs/building-and-installation.md)** — Host & device dependencies, `.deb` packaging (`./packaging/build-deb.sh` modes), `APPLaunch` integration, font bundling, SDL2 simulator builds, and C++/Python/packaging tests.
- **[Usage, Controls & Configuration Guide](docs/usage-and-controls.md)** — Capture modes, all 9 photo filters, Timelapse auto-dim safe-wake & recovery, Gallery playback, complete keymap, `config.json` (18 fields), CLI flags, sync-safe staging rules, and troubleshooting.
- **[Architecture & Camera Protocol Reference](docs/architecture-and-protocol.md)** — `cz::ICameraBackend` decoupling boundary, JSON v1 + 16-byte `CZFR` binary frame pipe spec, dual `main`+`lores` camera pipeline, VideoCore IV limits, `320×170` Zinc tokens, and directory map.
- **[Design Specification](docs/superpowers/specs/2026-11-19-czcamera-design.md)** — Original hardware/UI design specification.
- **[Implementation Plan](docs/superpowers/plans/2026-11-19-czcamera.md)** — 7-task TDD architecture and verification plan.
---
## Repository Layout
```text
.
├── app/ # C++17 320x170 UI, filters, timelapse/gallery/playback & 5 CTest suites
├── cam-helper/ # Python 3 czcamera-cam helper (picamera2 + mock driver) & tests
├── packaging/ # ARM64 Docker/.deb builder, APPLaunch desktop/icon & packaging tests
├── docs/ # User/developer guides, design specification & implementation plan
├── chat-summaries/ # Technical implementation summaries
└── LICENSE.md # Apache License 2.0
```
---
- [Usage, controls, and configuration](docs/usage-and-controls.md): Mode behavior, all nine filters, `config.json` fields, CLI flags, and sync-safe file naming.
- [Building, installation, and desktop simulator](docs/building-and-installation.md): Dependencies, `.deb` packaging options, SDL2 simulator, headless PPM snapshots, and test suites.
- [Architecture and camera protocol](docs/architecture-and-protocol.md): Backend interface, camera helper JSON and binary frame protocol, UI color tokens, and directory map.
## License
Licensed under the **Apache License, Version 2.0**. See [LICENSE.md](LICENSE.md) for the full license text.
Licensed under the Apache License, Version 2.0. See [LICENSE.md](LICENSE.md) for the full text.

View File

@@ -1,5 +1,5 @@
> [!IMPORTANT]
> This project was developed with AI coding assistance and has not yet undergone a full hardware soak test on physical CM0 hardware. It is provided under the Apache 2.0 license and may require adjustment for other environments.
> This project was developed entirely with AI coding assistance (Google Neon) and has not undergone rigorous review. It is provided as-is and may require adjustments for other environments.
# Architecture & Camera Protocol Reference
@@ -126,3 +126,5 @@ Exact palette tokens defined in [`app/src/theme.cpp`](../app/src/theme.cpp):
- **`app/tests/`**: `test_config_and_storage.cpp`, `test_filters_and_jpeg.cpp`, `test_backend_protocol.cpp`, `test_timelapse_and_gallery.cpp`, `test_ui_controller.cpp`
- **`cam-helper/`**: `bin/czcamera-cam`, `czcamera_cam/{__init__,protocol,picam2_worker}.py`, `tests/test_{protocol,picam2_worker}.py`
- **`packaging/`**: `Dockerfile.arm64`, `build-deb.sh`, `czcamera.desktop`, `czcamera.png`, `debian/{control,postinst,prerm}`, `tests/test_packaging.py`
- **`docs/`**: User/developer guides (`building-and-installation.md`, `usage-and-controls.md`, `architecture-and-protocol.md`)
- **`LICENSE.md`**: Apache License, Version 2.0

View File

@@ -1,5 +1,5 @@
> [!IMPORTANT]
> This project was developed with AI coding assistance and has not yet undergone a full hardware soak test on physical CM0 hardware. It is provided under the Apache 2.0 license and may require adjustment for other environments.
> This project was developed entirely with AI coding assistance (Google Neon) and has not undergone rigorous review. It is provided as-is and may require adjustments for other environments.
# Building & Installation Guide

View File

@@ -1,5 +1,5 @@
> [!IMPORTANT]
> This project was developed with AI coding assistance and has not yet undergone a full hardware soak test on physical CM0 hardware. It is provided under the Apache 2.0 license and may require adjustment for other environments.
> This project was developed entirely with AI coding assistance (Google Neon) and has not undergone rigorous review. It is provided as-is and may require adjustments for other environments.
# Usage, Controls & Configuration Guide