mirror of
https://github.com/cottongin/cardputerzero-camera.git
synced 2026-11-20 14:24:48 -06:00
docs: add README, guides, and Apache 2.0 license
This commit is contained in:
128
docs/architecture-and-protocol.md
Normal file
128
docs/architecture-and-protocol.md
Normal file
@@ -0,0 +1,128 @@
|
||||
> [!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.
|
||||
|
||||
# Architecture & Camera Protocol Reference
|
||||
|
||||
`czcamera` separates user-space UI, image processing, media assembly, and storage management in C++17 from Raspberry Pi hardware capture in Python 3 (`python3-picamera2`) through an explicit backend abstraction (`cz::ICameraBackend`).
|
||||
|
||||
---
|
||||
|
||||
## 1. System Topology & Decoupling Boundary
|
||||
|
||||
```text
|
||||
+-------------------------------------------------------------------+
|
||||
| C++17 /usr/bin/czcamera |
|
||||
| - AppView (320x170 ShadcnCanvas: FreeType2 + 5x7 fallback) |
|
||||
| - UiController, TimelapseEngine, GalleryStore, VideoPlayer |
|
||||
| - Filters RGB24 + libjpeg still pipeline, BacklightController |
|
||||
| - Linux (/dev/fb0 + cp0-keys evdev) OR Desktop SDL2 (--sim) |
|
||||
| | |
|
||||
| cz::ICameraBackend |
|
||||
| +---------------+---------------+ |
|
||||
| | | |
|
||||
| SubprocessCameraBackend SimCameraBackend |
|
||||
| (device / --mock-driver) (--sim / --mock-cam / tests) |
|
||||
+--------------|----------------------------------------------------+
|
||||
| stdin/stdout JSON v1 + dedicated CZFR fd pipe
|
||||
v
|
||||
+-------------------------------------------------------------------+
|
||||
| Python 3 /usr/bin/czcamera-cam (czcamera_cam) |
|
||||
| - JsonProtocolServer + FramePipeWriter (latest-slot drop-oldest) |
|
||||
| - Picam2Worker (main + lores YUV420 dual streams, H264Encoder) |
|
||||
| - MockCameraDriver (--mock-driver deterministic test driver) |
|
||||
+-------------------------------------------------------------------+
|
||||
| python3-picamera2 / libcamera IPA (rpi/vc4)
|
||||
v
|
||||
Sony IMX219 (3280x2464) + ES8389 MEMS Mic (ALSA default)
|
||||
```
|
||||
|
||||
### Replacing `picamera2` with Native `libcamera` Later
|
||||
`czcamera` C++ sources have **zero** `#include <libcamera/...>` or CMake linkage to `libcamera.so`. To swap `python3-picamera2` for a native C++ `libcamera` backend (or `rpicam-apps`), implement [`app/src/camera_backend.hpp`](../app/src/camera_backend.hpp) (`cz::ICameraBackend`) and return it from `create_camera_backend()` in [`app/src/sim_backend.cpp`](../app/src/sim_backend.cpp) without touching `UiController`, `AppView`, filters, timelapse, or gallery code.
|
||||
|
||||
---
|
||||
|
||||
## 2. Camera Helper Wire Protocol v1
|
||||
|
||||
`SubprocessCameraBackend` launches `/usr/bin/czcamera-cam --frame-fd <N>` (overridable via `CZCAMERA_CAM_BIN`, passing `--mock-driver` in protocol tests) with an inherited read/write pipe (`frame_fd`).
|
||||
|
||||
### Control Channel (`stdin` / `stdout` Newline-Delimited JSON)
|
||||
|
||||
Requests from C++ → Python carry `"id"` (uint64) and `"cmd"`:
|
||||
|
||||
| Command | Payload Fields | Reply Extra Fields (`{"id", "ok": true, ...}`) |
|
||||
|---|---|---|
|
||||
| `configure` | `mode` (`"photo"`/`"video"`/`"timelapse"`), `main_w`, `main_h`, `preview_w` (`226`), `preview_h` (`170`), `fps`, `zoom`, `ev`, `transform` (`"auto"`/`"0"`/`"180"`/`"hflip"`/`"vflip"`) | `mode`, `main_w`, `main_h`, `preview_w`, `preview_h` (`226x128` for 16:9 modes), `transform`, `is_16_9` |
|
||||
| `set_controls` | Optional `zoom` (`1.0..4.0`), `ev` (`-2.0..+2.0`) | `zoom`, `ev` |
|
||||
| `capture_still` | `tmp_path`, `width`, `height` | `bytes` (temporarily stops video / switches to still format if needed and restores stream config) |
|
||||
| `start_video` | `tmp_path`, `width`, `height`, `fps`, `bitrate`, `audio` (`bool`) | `audio_recorded` (`bool`) |
|
||||
| `stop_video` | — | `duration_sec`, `bytes`, `audio_recorded` |
|
||||
| `pause` | — | Stops recording if active, closes camera & releases IMX219 lock |
|
||||
| `resume` | — | Re-opens camera and restores last `configure` spec |
|
||||
| `shutdown` | — | Tears down writer & camera cleanly and exits `0` |
|
||||
|
||||
Asynchronous Events from Python → C++ (no `"id"`):
|
||||
- `{"event": "ready", "protocol": 1, "backend": "picamera2"|"mock", "sensor": "...", "has_audio": true|false}`
|
||||
- `{"event": "warn", "code": "...", "message": "..."}` (for example `"audio_unavailable"`, `"invalid_json"`, `"control_error"`)
|
||||
- `{"event": "error", "code": "...", "message": "..."}`
|
||||
|
||||
### Binary Preview Frame Channel (`--frame-fd <N>`, 16-Byte `CZFR` Header)
|
||||
|
||||
Every preview frame packet starts with a fixed **16-byte little-endian** header (`struct.Struct("<4sHHBBHI")`) followed immediately by `payload_len` bytes:
|
||||
|
||||
| Offset | Size | C Type | Field | Description |
|
||||
|---|---|---|---|---|
|
||||
| `0` | `4` | `char[4]` | `magic` | `"CZFR"` (`0x43 0x5A 0x46 0x52`) |
|
||||
| `4` | `2` | `uint16_t` | `width` | Negotiated preview frame width (e.g., `226`) |
|
||||
| `6` | `2` | `uint16_t` | `height` | Preview frame height (`170` for 4:3, `128` for 16:9) |
|
||||
| `8` | `1` | `uint8_t` | `pixfmt` | `1` = `YUV420`, `2` = `RGB24` |
|
||||
| `9` | `1` | `uint8_t` | `flags` | Bit `0` (`0x01`): `FLAG_ASPECT_16_9` |
|
||||
| `10` | `2` | `uint16_t` | `reserved` | Always `0` |
|
||||
| `12` | `4` | `uint32_t` | `payload_len` | `width * height * 3 / 2` (`YUV420`) or `width * height * 3` (`RGB24`) |
|
||||
|
||||
**Backpressure Contract (Review Focus #1):**
|
||||
- `FramePipeWriter` uses a single-slot bounded queue (`_pending`). When the UI consumer slows down, `push_frame()` drops any unconsumed queued packet and replaces it with the newest frame, keeping camera/H.264 encoder threads non-blocking.
|
||||
- `Picam2Worker._extract_lores_yuv420()` inspects the negotiated `lores` `stride` (handling 64-byte DMA padding such as `256` for `226px`) and strips row padding before packing tight `YUV420` payloads.
|
||||
|
||||
---
|
||||
|
||||
## 3. Target Hardware Constraints & Media Pipelines
|
||||
|
||||
- **Sony IMX219 Sensor Modes:** `640×480` (4:3, crop `(1000,752)/1280×960`), `1640×1232` (4:3 full-FOV 2×2 binned), `1920×1080` (16:9 crop), `3280×2464` (4:3 8MP full sensor).
|
||||
- **Video Output (`FfmpegOutput`):** `_FfmpegOutputTarget` overrides `.split()` cleanly around `picamera2.outputs.FfmpegOutput`'s whitespace `.split()` so staging paths containing spaces or special characters (and ending in `.mp4.part`, with `-f mp4 -movflags +faststart`) remain exact `argv` tokens.
|
||||
- **Timelapse Compilation:** [`TimelapseEngine`](../app/src/timelapse_engine.hpp) invokes `ffmpeg` with `-vf scale=1440:1080:flags=lanczos` for `8MP` sessions to stay under VideoCore IV's `2048px` H.264 limit, tries `h264_v4l2m2m` (`6M`, `yuv420p`), and retries automatically with `libx264 -preset veryfast -crf 22 -pix_fmt yuv420p` on failure.
|
||||
- **Gallery Playback:** [`VideoPlayer`](../app/src/video_player.hpp) probes duration & audio presence via `ffprobe`, spawns `ffmpeg` raw `rgb24` frames timed cleanly to PTS, and drives audio through ALSA `aplay` on Linux or `set_pcm_sink` (SDL2 audio queue) on desktop—allowing silent `.mp4` files (compiled timelapses or muted clips) to play smoothly without audio failure.
|
||||
|
||||
---
|
||||
|
||||
## 4. `320×170` UI Renderer & Zinc Color Tokens
|
||||
|
||||
[`AppView`](../app/src/app_ui.hpp) renders into an offscreen `320×170` ARGB8888 canvas with SDF antialiased rounded primitives and FreeType2 + `5×7` bitmap fallback, then blits via [`fb_blit.hpp`](../app/src/fb_blit.hpp) (`RGB565` / `RGB24` / `XRGB8888`) or SDL2 texture.
|
||||
|
||||
Exact palette tokens defined in [`app/src/theme.cpp`](../app/src/theme.cpp):
|
||||
|
||||
| Token | Zinc Dark (`ThemeMode::Dark`) | Zinc Light (`ThemeMode::Light`) |
|
||||
|---|---|---|
|
||||
| `background` / `card` | `#09090b` / `#09090b` | `#fafafa` / `#ffffff` |
|
||||
| `muted` | `#18181b` | `#f4f4f5` |
|
||||
| `border` | `#27272a` | `#e4e4e7` |
|
||||
| `ring` | `#d4d4d8` | `#71717a` |
|
||||
| `foreground` / `muted_foreground` | `#fafafa` / `#a1a1aa` | `#09090b` / `#71717a` |
|
||||
| `active_tab` / `active_tab_foreground` | `#27272a` / `#fafafa` | `#ffffff` / `#09090b` |
|
||||
| `status_online` / `status_online_bg` | `#4ade80` / `#11261a` | `#16a34a` / `#dcfce7` |
|
||||
| `status_sleeping` / `status_sleeping_bg` | `#fbbf24` / `#271d0b` | `#d97706` / `#fef3c7` |
|
||||
| `status_error` / `status_error_bg` | `#f87171` / `#2b1214` | `#dc2626` / `#fee2e2` |
|
||||
| `viewfinder_surround` | `#050507` | `#050507` |
|
||||
|
||||
---
|
||||
|
||||
## 5. Source Directory Map
|
||||
|
||||
- **`app/src/`**:
|
||||
- `theme.{hpp,cpp}`, `fb_blit.hpp`, `config.{hpp,cpp}`, `storage.{hpp,cpp}`
|
||||
- `filters.{hpp,cpp}`, `jpeg_pipeline.{hpp,cpp}`
|
||||
- `camera_backend.hpp`, `subprocess_backend.{hpp,cpp}`, `sim_backend.{hpp,cpp}`
|
||||
- `backlight.{hpp,cpp}`, `timelapse_engine.{hpp,cpp}`, `gallery_model.{hpp,cpp}`, `video_player.{hpp,cpp}`
|
||||
- `ui_controller.{hpp,cpp}`, `app_ui.{hpp,cpp}`, `evdev_repeat_guard.hpp`, `main.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`
|
||||
188
docs/building-and-installation.md
Normal file
188
docs/building-and-installation.md
Normal file
@@ -0,0 +1,188 @@
|
||||
> [!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.
|
||||
|
||||
# Building & Installation Guide
|
||||
|
||||
This guide covers building the CardputerZero ARM64 `.deb` package, installing on device with `APPLaunch` integration, building the macOS/Linux SDL2 desktop simulator, and running all verification suites.
|
||||
|
||||
---
|
||||
|
||||
## 1. Prerequisites
|
||||
|
||||
### CardputerZero Device (Runtime)
|
||||
- Raspberry Pi CM0 (ARM64 Debian Bookworm, `dtoverlay=imx219` enabled in `/boot/firmware/config.txt`)
|
||||
- Sony IMX219 camera module verified with `rpicam-hello --list-cameras`
|
||||
- `APPLaunch` application launcher and `/dev/fb0` + `cp0-keys` `evdev` input device
|
||||
- Runtime `.deb` dependencies (declared in [`packaging/debian/control`](../packaging/debian/control)):
|
||||
- `python3 (>= 3.9)`
|
||||
- `python3-picamera2`
|
||||
- `ffmpeg`
|
||||
- `alsa-utils` (`aplay`)
|
||||
- `libjpeg62-turbo | libjpeg8`
|
||||
- `libfreetype6`
|
||||
- `libc6`, `libstdc++6`
|
||||
|
||||
> Note: `czcamera` intentionally has **no** dependency on `cp0-sync` and **no** direct C++ linkage to `libcamera0*` or `libcamera.so`.
|
||||
|
||||
### Docker Cross-Build Host (macOS / Linux)
|
||||
- Docker Desktop (or Docker Engine with `linux/arm64` emulation / `buildx`)
|
||||
|
||||
### Desktop Simulator Build (macOS / Linux)
|
||||
- CMake `>= 3.16` and a C++17 compiler (`clang++` or `g++`)
|
||||
- `pkg-config`
|
||||
- `libjpeg` (`libjpeg-turbo` via Homebrew `jpeg-turbo`/`libjpeg` or Debian `libjpeg62-turbo-dev`)
|
||||
- `SDL2` (`sdl2` via Homebrew or `libsdl2-dev`)
|
||||
- **Optional:** `FreeType2` (`freetype` / `libfreetype-dev`) for crisp antialiased UI fonts (falls back automatically to the built-in `5×7` bitmap renderer if absent)
|
||||
- **Optional:** `ffmpeg` & `ffprobe` on `PATH` for desktop Timelapse MP4 compilation and Gallery `.mp4` playback tests
|
||||
- Python `>= 3.9` for running helper/packaging test suites
|
||||
|
||||
---
|
||||
|
||||
## 2. Building the ARM64 Debian Package (`.deb`)
|
||||
|
||||
Use [`packaging/build-deb.sh`](../packaging/build-deb.sh) in one of four supported modes:
|
||||
|
||||
```bash
|
||||
./packaging/build-deb.sh --help
|
||||
```
|
||||
|
||||
### Option A: Docker `linux/arm64` Build (Recommended on macOS / x86_64)
|
||||
|
||||
Builds a clean `debian:bookworm-slim` (`linux/arm64`) container via [`packaging/Dockerfile.arm64`](../packaging/Dockerfile.arm64), compiles `czcamera` with `-DCZ_BUILD_APP=ON -DCZ_TARGET_DEVICE=ON -DCZ_BUILD_TESTS=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS_RELEASE="-O2"`, executes ARM64 `ctest` and `cam-helper/tests`, and outputs `packaging/dist/czcamera_1.0.0_m5stack1_arm64.deb`:
|
||||
|
||||
```bash
|
||||
./packaging/build-deb.sh
|
||||
```
|
||||
|
||||
> Why `-O2` without global `-DNDEBUG`: the ARM64 verification step runs the C++ `ctest` binaries (`app/tests/*.cpp`) built in the same tree, and those tests use `<cassert>` `assert()`.
|
||||
|
||||
### Option B: Native Build on CardputerZero / ARM64 Linux
|
||||
|
||||
On an ARM64 Debian host with build dependencies installed (`build-essential cmake pkg-config libjpeg62-turbo-dev libfreetype-dev dpkg-dev`):
|
||||
|
||||
```bash
|
||||
./packaging/build-deb.sh --local
|
||||
```
|
||||
|
||||
### Option C: Stage Directory or Supply Prebuilt Binary
|
||||
|
||||
Stage the package tree without running `dpkg-deb` or Docker (useful for inspection or custom packaging):
|
||||
|
||||
```bash
|
||||
./packaging/build-deb.sh --stage-only /tmp/czcamera-stage --bin /path/to/czcamera
|
||||
```
|
||||
|
||||
Flags supported by `build-deb.sh`:
|
||||
|
||||
| Flag | Description |
|
||||
|---|---|
|
||||
| `--local` | Build `app/build-arm64` natively on Linux ARM64 and package `.deb` |
|
||||
| `--stage-only <dir>` | Stage package files into `<dir>` with target permissions and exit |
|
||||
| `--bin <path>` / `--ui-bin <path>` | Supply a prebuilt `czcamera` binary (`--ui-bin` is an alias for `--bin`) |
|
||||
| `--out-dir <dir>` | Output directory for `.deb` (default: `packaging/dist/`) |
|
||||
| `-h`, `--help` | Show usage help |
|
||||
|
||||
### Optional TrueType Font Bundling
|
||||
|
||||
If TTF/OTF font files exist under `app/assets/fonts/` or `packaging/fonts/` before running `build-deb.sh`, they are staged into `/usr/share/czcamera/fonts/` (`0644`). At runtime, `cz::AppView` checks `/usr/share/czcamera/fonts/` first, then common system font directories, and falls back to the built-in `5×7` bitmap font cleanly if none are installed.
|
||||
|
||||
---
|
||||
|
||||
## 3. Installing & Uninstalling on CardputerZero
|
||||
|
||||
Copy the generated package to the device and install via `dpkg` + `apt-get`:
|
||||
|
||||
```bash
|
||||
scp packaging/dist/czcamera_1.0.0_m5stack1_arm64.deb pi@<cardputerzero-host>:/tmp/
|
||||
ssh pi@<cardputerzero-host> 'sudo dpkg -i /tmp/czcamera_1.0.0_m5stack1_arm64.deb && sudo apt-get install -f'
|
||||
```
|
||||
|
||||
### Installed Layout
|
||||
|
||||
| Destination Path | Mode | Role |
|
||||
|---|---|---|
|
||||
| `/usr/bin/czcamera` | `0755` | C++17 `320×170` `fbdev` + `evdev` camera application binary |
|
||||
| `/usr/bin/czcamera-cam` | `0755` | Python 3 camera worker launcher (`python3-picamera2`) |
|
||||
| `/usr/lib/czcamera/czcamera_cam/*.py` | `0644` | Protocol, `FramePipeWriter`, `Picam2Worker`, and mock driver modules |
|
||||
| `/usr/share/APPLaunch/applications/czcamera.desktop` | `0644` | `APPLaunch` launcher entry (`Name=czcamera`, `Exec=/usr/bin/czcamera`) |
|
||||
| `/usr/share/APPLaunch/share/images/czcamera.png` | `0644` | `80×80` Zinc dark camera launcher icon |
|
||||
| `/usr/share/czcamera/fonts/*.ttf` *(optional)* | `0644` | Optional bundled UI fonts |
|
||||
|
||||
### Sanity Checks on Device
|
||||
|
||||
Verify shared libraries (`libjpeg.so.62` / `libfreetype.so.6` present, zero `libcamera.so` linkage) and camera visibility:
|
||||
|
||||
```bash
|
||||
ldd /usr/bin/czcamera
|
||||
rpicam-hello --list-cameras
|
||||
```
|
||||
|
||||
Launch **czcamera** from the `APPLaunch` grid, or test from TTY/SSH:
|
||||
|
||||
```bash
|
||||
/usr/bin/czcamera
|
||||
```
|
||||
|
||||
### Uninstalling
|
||||
|
||||
```bash
|
||||
sudo apt-get remove czcamera
|
||||
```
|
||||
|
||||
[`packaging/debian/prerm`](../packaging/debian/prerm) automatically cleans Python `__pycache__` bytecode under `/usr/lib/czcamera` on package removal or deconfiguration.
|
||||
|
||||
---
|
||||
|
||||
## 4. Building & Running the Desktop SDL2 Simulator
|
||||
|
||||
Configure and build on macOS or Linux desktop:
|
||||
|
||||
```bash
|
||||
cmake -S app -B app/build -DCZ_BUILD_APP=ON -DCZ_BUILD_TESTS=ON
|
||||
cmake --build app/build
|
||||
```
|
||||
|
||||
Run the interactive `320×170` SDL2 simulator (defaults to `SimCameraBackend` when `--sim` or `--mock-cam` is given):
|
||||
|
||||
```bash
|
||||
./app/build/czcamera --sim --scale 3
|
||||
```
|
||||
|
||||
Render headless `P6 320×170` PPM snapshots (`163215` bytes each) for CI or visual inspection:
|
||||
|
||||
```bash
|
||||
./app/build/czcamera --render-test /tmp/cz_photo.ppm --theme dark --mode photo --rail right
|
||||
./app/build/czcamera --render-test /tmp/cz_light_left.ppm --theme light --mode photo --rail left
|
||||
./app/build/czcamera --render-test /tmp/cz_video.ppm --theme dark --mode video
|
||||
./app/build/czcamera --render-test /tmp/cz_timelapse.ppm --theme dark --mode timelapse
|
||||
./app/build/czcamera --render-test /tmp/cz_gallery.ppm --theme dark --mode gallery
|
||||
./app/build/czcamera --render-test /tmp/cz_settings.ppm --theme dark --mode settings
|
||||
```
|
||||
|
||||
### CMake Build Options
|
||||
|
||||
| Option | Default | Effect |
|
||||
|---|---|---|
|
||||
| `CZ_BUILD_APP` | `OFF` | Build the `czcamera` executable in addition to `czcamera_core` |
|
||||
| `CZ_TARGET_DEVICE` | `OFF` | Build Linux `/dev/fb0` + `cp0-keys` `evdev` backend instead of SDL2 (Linux only) |
|
||||
| `CZ_BUILD_TESTS` | `ON` | Build the 5 `ctest` suites |
|
||||
| `CZ_ENABLE_LVGL` | `OFF` | Link optional `lvgl::lvgl` (`CP0_HAS_LVGL=1`) if available |
|
||||
|
||||
---
|
||||
|
||||
## 5. Running Test Suites
|
||||
|
||||
Run all three suites cleanly from the repository root:
|
||||
|
||||
```bash
|
||||
# C++ unit & integration tests (5 suites)
|
||||
ctest --test-dir app/build --output-on-failure -V
|
||||
|
||||
# Python camera helper & mock-driver IPC tests (18 tests, warnings-as-errors)
|
||||
PYTHONPATH=cam-helper python3 -W error -m unittest discover -s cam-helper/tests -v
|
||||
|
||||
# Packaging metadata, icon, maintainer script & staging tests (4 tests)
|
||||
python3 -m unittest discover -s packaging/tests -v
|
||||
```
|
||||
|
||||
*(Note: `test_backend_protocol` also spawns `cam-helper/bin/czcamera-cam --mock-driver` end-to-end across pipes to validate C++ ↔ Python JSON v1 + `CZFR` binary framing.)*
|
||||
154
docs/usage-and-controls.md
Normal file
154
docs/usage-and-controls.md
Normal file
@@ -0,0 +1,154 @@
|
||||
> [!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.
|
||||
|
||||
# Usage, Controls & Configuration Guide
|
||||
|
||||
`czcamera` is operated entirely with the 46-key CardputerZero keyboard (`cp0-keys`) or an attached keyboard in the SDL2 desktop simulator.
|
||||
|
||||
---
|
||||
|
||||
## 1. Screen Layout (Option A Split View)
|
||||
|
||||
The `320×170` canvas splits into two regions whose horizontal side swaps dynamically with **`W`** (or via Settings → `Control Rail`):
|
||||
|
||||
- **Viewfinder (`226×170`):** `16:9` modes (`720p`, `1080p` Video, `1080p` Timelapse) letterbox cleanly into `226×127` centered on a `#050507` surround; `4:3` modes (`8MP`, `2MP`, `480p`) fill `226×170`. Minimal corner badges show active filter, crop zoom / `2x` Loupe state, timer countdown, `● REC MM:SS`, or Timelapse shot counter/next-shot countdown.
|
||||
- **Control Rail (`94×170`):** Displays `1P · 2V · 3T` mode tabs at the top, 4 setting cards tailored to the active mode, and a compact 2-line `<kbd>` keybind hint footer.
|
||||
|
||||
---
|
||||
|
||||
## 2. Capture Modes
|
||||
|
||||
### Photo Mode (`1`)
|
||||
- **Resolutions (`R` or card 0):** `8MP` (`3280×2464` JPEG) default, `2MP` (`1640×1232` JPEG).
|
||||
- **Digital Crop Zoom vs. Viewfinder Loupe:**
|
||||
- **`5` / `7`**: Steps ISP `ScalerCrop` (`1.0x`, `1.5x`, `2.0x`, `3.0x`, `4.0x`). Both the live preview and captured JPEG are cropped cleanly to that region.
|
||||
- **`L`** (or `l` on Photo idle view): Toggles a **`2x` Viewfinder-Only Loupe** for checking framing/focus without cropping the saved full-resolution photo.
|
||||
- **Exposure Value (card 1, `Left`/`Right`):** `-2.0` to `+2.0` in `0.5` EV steps.
|
||||
- **Photo Filters (`F` or card 2):** Cycles all 9 filters live on the preview and applies them on JPEG save (`None` writes the sensor JPEG directly with zero re-encode):
|
||||
`None` (`none`), `B&W` (`bw`), `Hi-Con` (`hicon`), `Sepia` (`sepia`), `Cool` (`cool`), `Vivid` (`vivid`), `Invert` (`invert`), `Retro` (`retro`), `GameBoy` (`gameboy`, scaled integer blocks with 4-shade Bayer DMG palette).
|
||||
- **Self-Timer (`C` or card 3):** Cycles `Off` (`0s`), `3s`, `10s`. Press `Esc` during countdown to cancel without quitting.
|
||||
- **Shutter (`Enter`, `Space`, `6`):** Stages to `.IMG_<ts>.jpg.tmp`, applies filter if active, `fsync`s, and commits atomically to `IMG_<ts>.jpg` (adding `_01`, `_02`, ... on same-second collisions).
|
||||
|
||||
### Video Mode (`2`)
|
||||
- **Resolutions (`R` or card 0, while idle):** `720p` (`1280×720` @ 30fps, default), `1080p` (`1920×1080` @ 30fps), `480p` (`640×480` @ 30fps).
|
||||
- **Audio (`M` or card 1, while idle):** ES8389 MEMS microphone ON by default (`audio=true`). If ALSA capture is unavailable or busy at recording start, `czcamera-cam` emits `audio_unavailable`, shows a warning toast, and falls back to muted `.mp4` recording instead of aborting.
|
||||
- **Live Zoom (`5` / `7` or card 2):** Active both before and during recording (`1.0x`–`4.0x`).
|
||||
- **Storage Indicator (card 3):** Displays read-only `FREE` space remaining on the target mount (`100 MB` minimum enforced every 2 seconds while recording; auto-stops safely if space drops below `100 MB`).
|
||||
- **Recording Lock:** While `● REC` is active, mode switches (`1`/`2`/`3`), `[8]` Gallery, `[S]` Settings, `[W]` rail flip, `[T]` theme toggle, `[M]`/`[R]`, and `Q` are locked out. Press `Enter`, `Space`, `6`, or `Esc` to stop recording cleanly.
|
||||
|
||||
### Timelapse Mode (`3`)
|
||||
- **Defaults & Presets:**
|
||||
- **Resolution (`R` or card 2):** `2MP` (`1640×1232` default for tighter intervals), `1080p` (`1920×1080`), `8MP` (`3280×2464`).
|
||||
- **Interval (card 0):** Cycles `2s`, `5s` (default), `10s`, `30s`, `60s`, `300s` (or any custom `1..3600s` via `[C]` / `[P]`).
|
||||
- **Output Mode (card 1):** `video` (`TL_<ts>.mp4`, default) or `photos` (`TL_<ts>/frame_0001.jpg`...).
|
||||
- **Stop Condition (card 3):** `Manual` (default), `60 shots`, `120 shots`, `300 shots`, `15 min`, `30 min`, `60 min` (or custom via `[C]` / `[P]`).
|
||||
- **Custom Input Modal (`C` or `P` while idle):** Adjusts exact Interval (`1..3600s`), FPS (`15`, `24`, `30`), Stop Mode (`manual` / `shots` / `duration`), and Stop Value (`1..9999` shots or `1..1440` min) with numeric digits or `Left`/`Right`. `Enter` saves and closes; `Esc` discards.
|
||||
- **MP4 Compilation & VideoCore IV Compliance:**
|
||||
- Frames stage inside `.tl_work_<ts>/` with a `manifest.json` heartbeat.
|
||||
- On stop/completion in `video` mode, `ffmpeg` prefers hardware `h264_v4l2m2m` (`6M`, `yuv420p`) and automatically falls back to `libx264 -preset veryfast -crf 22 -pix_fmt yuv420p` if hardware encoding fails.
|
||||
- Because Raspberry Pi VideoCore IV's hardware H.264 encoder caps dimensions at `2048px`, **`8MP` (`3280×2464`) frames automatically scale to `1440×1080` (`lanczos`)** during MP4 compile (while individual `Photos`-mode frames remain full `8MP`).
|
||||
- Press `Esc` during `TimelapseCompiling` to cancel compilation cleanly and preserve the raw frames in a non-hidden `TL_<ts>/` folder.
|
||||
- **Auto-Dim & Safe Wake:**
|
||||
- When capturing, the screen dims after `timelapse_dim_sec` idle seconds (`15s` default; configurable `15s`/`30s`/`60s`/`Off` in Settings) via `/sys/class/backlight/*/brightness` (or a software black frame fallback on desktop/headless).
|
||||
- **Safe-Wake Rule:** Pressing **any** key while dimmed (including `Enter`, `6`, `Esc`, `Q`) **only wakes the display** and resets the idle timer — and on Linux `evdev`, held auto-repeats (`ev.value == 2`) for that wake key are suppressed until key release (`ev.value == 0`). Press `Esc`, `Enter`, `6`, or `Q` while **awake** to open `TimelapseStopConfirm` (`[Y]` stop & finish/compile, `[N]`/`[Esc]` keep capturing).
|
||||
- **Crash Recovery on Launch:** On startup, `czcamera` scans `output_dir` for incomplete `.tl_work_*` directories containing valid JPEGs and prompts `TimelapseRecovery`: `[C]` Compile to MP4, `[K]` Keep Photos, `[D]` Discard, or `[Esc]` Defer.
|
||||
|
||||
---
|
||||
|
||||
## 3. Gallery & Media Playback (`8`)
|
||||
|
||||
Pressing `8` pauses the camera backend (`pause` IPC, releasing the sensor) and opens the full-screen `320×170` Gallery showing items from `output_dir` (newest first, ignoring all `.`-prefixed hidden files/directories):
|
||||
|
||||
| Key | Gallery Context | Action |
|
||||
|---|---|---|
|
||||
| `Up`/`Down`/`Left`/`Right` or `k`/`j`/`h`/`l` | Photo / Video (stopped) / TL Folder | Navigate items |
|
||||
| `Space` / `Enter` | `TL_*` Timelapse Folder | Drill into folder (`Backspace` or `Esc` returns to root) |
|
||||
| `Space` / `Enter` | Video (`.mp4`) | Play / Pause |
|
||||
| `Left` / `Right` or `h` / `l` | Video (playing) | Seek `-5s` / `+5s` |
|
||||
| `M` | Video selected | Toggle playback mute (works cleanly even on silent `.mp4` files with no audio stream) |
|
||||
| `D` / `Delete` | Any item | Open `[Y]` Confirm / `[N]`/`Esc` Cancel delete prompt |
|
||||
| `T` | Gallery | Toggle Zinc Dark / Light theme |
|
||||
| `1`, `2`, `3` | Gallery | Close Gallery, resume camera, and jump directly to mode |
|
||||
| `Esc` / `Q` | Gallery root | Close Gallery and resume camera live preview |
|
||||
|
||||
---
|
||||
|
||||
## 4. Settings Modal & Directory Tree Picker (`S`)
|
||||
|
||||
| Row | Setting | Values / Action |
|
||||
|---|---|---|
|
||||
| 0 | `Output Dir` | Opens `DirPicker` (`Enter` drill down, `Backspace` parent, `Space` select highlighted dir, `.` select current dir, `/` root, `~` home, `[T]` manual `TextInput` with printable ASCII + spaces, `Esc` back) |
|
||||
| 1 | `Control Rail` | `right` (default) / `left` |
|
||||
| 2 | `Theme` | `dark` (Zinc Dark) / `light` (Zinc Light) |
|
||||
| 3 | `Grid Overlay` | `on` (`true`) / `off` (`false`) |
|
||||
| 4 | `Timelapse Dim` | `15s` / `30s` / `60s` / `Off` (`0`) |
|
||||
| 5 | `Camera Orient` | `auto` / `0` / `180` / `hflip` / `vflip` (live backend `reconfigure`) |
|
||||
|
||||
---
|
||||
|
||||
## 5. Configuration Reference (`config.json`)
|
||||
|
||||
Persisted atomically to `~/.config/czcamera/config.json` (override path with `CZCAMERA_CONFIG`). Malformed or missing configs fall back safely to defaults; out-of-range fields are sanitized on load.
|
||||
|
||||
| Field | Default | Valid Values / Range |
|
||||
|---|---|---|
|
||||
| `output_dir` | `"~/Pictures/czcamera"` | Target media folder (`~/` expanded via `$HOME`) |
|
||||
| `theme` | `"dark"` | `"dark"`, `"light"` |
|
||||
| `rail_side` | `"right"` | `"right"`, `"left"` |
|
||||
| `photo_resolution` | `"8mp"` | `"8mp"` (`3280×2464`), `"2mp"` (`1640×1232`) |
|
||||
| `photo_filter` | `"none"` | `"none"`, `"bw"`, `"hicon"`, `"sepia"`, `"cool"`, `"vivid"`, `"invert"`, `"retro"`, `"gameboy"` |
|
||||
| `photo_timer_sec` | `0` | `0`, `3`, `10` |
|
||||
| `grid_enabled` | `true` | `true`, `false` |
|
||||
| `video_resolution` | `"720p"` | `"480p"`, `"720p"`, `"1080p"` |
|
||||
| `video_audio` | `true` | `true`, `false` |
|
||||
| `timelapse_resolution` | `"2mp"` | `"2mp"`, `"1080p"`, `"8mp"` |
|
||||
| `timelapse_interval_sec` | `5` | `1..3600` (seconds) |
|
||||
| `timelapse_output_mode` | `"video"` | `"video"`, `"photos"` |
|
||||
| `timelapse_fps` | `24` | `15`, `24`, `30` |
|
||||
| `timelapse_stop_mode` | `"manual"` | `"manual"`, `"shots"`, `"duration"` |
|
||||
| `timelapse_stop_value` | `0` | `>= 0` (shot count or seconds when `"duration"`) |
|
||||
| `timelapse_dim_sec` | `15` | `0..3600` (`0` = never auto-dim) |
|
||||
| `ev` | `0.0` | `-2.0..2.0` |
|
||||
| `camera_transform` | `"auto"` | `"auto"`, `"0"`, `"180"`, `"hflip"`, `"vflip"` |
|
||||
|
||||
---
|
||||
|
||||
## 6. CLI Options & Environment Variables
|
||||
|
||||
```text
|
||||
czcamera [options]
|
||||
--sim Run desktop 320x170 SDL2 simulator (uses mock camera)
|
||||
--scale <1..4> Integer SDL2 window scale factor (default: 2)
|
||||
--mock-cam Force procedural SimCameraBackend (desktop or device)
|
||||
--output-dir <path> Override media output directory for this session (non-destructive to config.json)
|
||||
--render-test <path.ppm> Render 320x170 P6 PPM snapshot headlessly and exit
|
||||
--theme <dark|light> Initial theme override
|
||||
--mode <photo|video|timelapse|gallery|settings>
|
||||
Initial mode or modal
|
||||
--rail <right|left> Control rail side override
|
||||
--help Print usage help
|
||||
```
|
||||
|
||||
Environment variables:
|
||||
- `CZCAMERA_CONFIG`: Override path to `config.json`.
|
||||
- `CZCAMERA_CAM_BIN`: Override path to `czcamera-cam` executable (default `/usr/bin/czcamera-cam`, with `./cam-helper/bin/czcamera-cam` development fallback).
|
||||
|
||||
---
|
||||
|
||||
## 7. Sync-Safe Storage & Disk Floor
|
||||
|
||||
- All in-progress files inside `output_dir` use leading dots so filesystem watchers/sync tools ignore partial writes:
|
||||
- Photos: `.IMG_<ts>.jpg.tmp` → atomic `rename()` → `IMG_<ts>.jpg`
|
||||
- Videos: `.VID_<ts>.mp4.part` → atomic `rename()` → `VID_<ts>.mp4`
|
||||
- Timelapses: `.tl_work_<ts>/frame_0001.jpg` + `manifest.json`, `.TL_<ts>.mp4.part` → `TL_<ts>.mp4` or `TL_<ts>/`
|
||||
- Minimum free storage floor: **`100 MB` (`104857600` bytes)** checked via `statvfs()` before any capture, every 2s during Video recording, and before each Timelapse shot.
|
||||
|
||||
---
|
||||
|
||||
## 8. Troubleshooting
|
||||
|
||||
- **"Camera Offline [R]" shown on device:**
|
||||
1. Check `grep imx219 /boot/firmware/config.txt` (`dtoverlay=imx219`) and `rpicam-hello --list-cameras`.
|
||||
2. Verify `/usr/bin/czcamera-cam --mock-driver --frame-fd 3` manually, or press `R` inside `czcamera` to respawn the backend.
|
||||
- **Video records muted (`audio_unavailable` toast):** Check ALSA capture device visibility (`arecord -l` and `alsamixer`); `czcamera` automatically records muted video rather than dropping the shot.
|
||||
- **Upside-down or mirrored preview on custom lens mount:** Open **Settings (`S`) → `Camera Orient`** and cycle `auto`, `0`, `180`, `hflip`, or `vflip`.
|
||||
Reference in New Issue
Block a user