Skip to content

Commit 75b0ce0

Browse files
Taoxuan-168Taoxuan-168
committed
* app_camera supports capture raw picture, add README_EN.md for projects
1 parent db6b178 commit 75b0ce0

File tree

33 files changed

+1387
-44
lines changed

33 files changed

+1387
-44
lines changed

‎components/vision/port/maixcam2/maix_camera_maixcam2.cpp‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -701,7 +701,7 @@ namespace maix::camera
701701
err::check_raise(err::ERR_BUFF_EMPTY, "read camera failed");
702702
}
703703

704-
auto img = new image::Image(frame->w, frame->h, image::FMT_RGGB10, (uint8_t *)frame->data, frame->len, false);
704+
auto img = new image::Image(frame->w, frame->h, image::FMT_RGGB10, (uint8_t *)frame->data, frame->len, true);
705705
delete frame;
706706
return img;
707707
}

‎projects/README.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
# MaixCam & MaixCam2 Auto Build & Pack Script
2+
A bash script to **automatically compile MaixCDK projects for MaixCam and MaixCam2 platforms**, package the compiled binaries into a portable ZIP file, and generate a self-executing `main.py` for one-click deployment on both devices.
3+
4+
## Features
5+
- **Two Compilation Modes**: Batch compile all valid projects in a directory, or compile a single project independently.
6+
- **Platform Selection**: Choose to build for MaixCam only, MaixCam2 only, or both platforms (default).
7+
- **Project Exclusion**: Configure an exclusion list to skip specific projects during batch compilation.
8+
- **Cross-Platform Support**: Compiles binaries for both MaixCam and MaixCam2 in one run.
9+
- **Smart Packaging**:
10+
- Separates platform-specific binaries into dedicated folders (`maixcam/`, `maixcam2/`).
11+
- Copies shared resources (assets, app.yaml, README) to the root of the package.
12+
- Generates an auto-executing `main.py` that **auto-detects the device model** (when building both) and runs the corresponding binary.
13+
- **Auto-Clean**: Clears compilation caches after each build to avoid version conflicts.
14+
- **Error Handling**: Stops execution on critical errors (batch mode skips failed projects and continues).
15+
- **Colorful Logs**: Clear visual feedback with colored info/warn/error messages for easy debugging.
16+
- **Timestamped ZIP**: Generates uniquely named ZIP packages with timestamps to avoid overwriting.
17+
18+
## Prerequisites
19+
1. **MaixCDK Installed**: The script relies on the `maixcdk` command-line tool for compilation and cleaning.
20+
Install MaixCDK following the official guide: [MaixCDK Documentation](https://wiki.sipeed.com/maixcdk)
21+
2. **Bash Environment**: Works on Linux/macOS (native bash) or Windows (WSL2, Git Bash, or MSYS2).
22+
3. **Basic Dependencies**: Ensure `zip`, `find`, `sed` are installed (pre-installed on most Linux/macOS systems).
23+
4. **Valid MaixCDK Projects**: Projects must contain either `app.yaml` (MaixCDK app) or `CMakeLists.txt` (CMake-based project) to be recognized.
24+
25+
## Quick Start
26+
### 1. Get the Script
27+
Save the script as `build_and_pack.sh` and grant execution permission:
28+
```bash
29+
chmod +x build_and_pack.sh
30+
```
31+
32+
### 2. Configure Exclusion List (Optional)
33+
Edit the script to exclude specific projects from batch compilation:
34+
```bash
35+
# Open the script and modify line 14-15
36+
EXCLUDE_PROJECTS=("project1" "project2" "project3")
37+
```
38+
Leave the array empty `EXCLUDE_PROJECTS=()` to compile all projects.
39+
40+
### 3. Show Help Information
41+
```bash
42+
./build_and_pack.sh -h
43+
# or
44+
./build_and_pack.sh --help
45+
```
46+
47+
## Usage
48+
### Mode 1: Batch Compile (Default)
49+
Compile **all valid MaixCDK projects** in a target directory (skips non-project folders and a `build/` subdirectory if present).
50+
The compiled ZIP packages are output to a `build/` folder in the target directory.
51+
52+
#### Syntax
53+
```bash
54+
./build_and_pack.sh [PROJECTS_DIRECTORY] [--platform maixcam|maixcam2|both]
55+
```
56+
- `[PROJECTS_DIRECTORY]`: Optional, path to the folder containing all MaixCDK projects (defaults to the **current working directory** if not specified).
57+
- `--platform` or `-p`: Optional, specify target platform(s) to build (defaults to `both`).
58+
59+
#### Examples
60+
```bash
61+
# Batch compile all projects in the current directory (both platforms)
62+
./build_and_pack.sh
63+
64+
# Batch compile only for MaixCam
65+
./build_and_pack.sh --platform maixcam
66+
67+
# Batch compile only for MaixCam2
68+
./build_and_pack.sh --platform maixcam2
69+
70+
# Batch compile all projects in a specified directory for both platforms
71+
./build_and_pack.sh /root/MaixCDK/projects --platform both
72+
```
73+
74+
### Mode 2: Single Project Compile
75+
Compile a **single MaixCDK project** (outputs the ZIP package directly to the project directory by default).
76+
77+
#### Syntax
78+
```bash
79+
./build_and_pack.sh --single [PROJECT_PATH] [--platform maixcam|maixcam2|both]
80+
# or short version
81+
./build_and_pack.sh -s [PROJECT_PATH] [-p maixcam|maixcam2|both]
82+
```
83+
- `[PROJECT_PATH]`: Optional, path to the single MaixCDK project (defaults to the **current working directory** if not specified).
84+
- `--platform` or `-p`: Optional, specify target platform(s) to build (defaults to `both`).
85+
86+
#### Examples
87+
```bash
88+
# Compile the project in the current directory (both platforms)
89+
./build_and_pack.sh --single
90+
91+
# Compile only for MaixCam
92+
./build_and_pack.sh --single --platform maixcam
93+
94+
# Compile a specified single project only for MaixCam2
95+
./build_and_pack.sh --single /root/MaixCDK/projects/app_camera --platform maixcam2
96+
```
97+
98+
## Output File Structure
99+
### Compiled ZIP Package Content
100+
The generated ZIP file (e.g., `app_camera_release_20260129_153000.zip`) structure depends on the platform selection:
101+
102+
**When building both platforms (`--platform both` or default):**
103+
```
104+
app_camera_release_20260129_153000/
105+
├── main.py # Auto-execution script (auto-detects device & runs binary)
106+
├── app.yaml # Project configuration (shared)
107+
├── assets/ # Resource files (images/fonts, shared)
108+
├── README.md # Project documentation (shared)
109+
├── README_EN.md # English documentation (shared, if exists)
110+
├── maixcam/ # MaixCam-specific files
111+
│ ├── [binary] # Compiled binary for MaixCam
112+
│ └── dl_lib/ # Deep learning libraries (if exists)
113+
└── maixcam2/ # MaixCam2-specific files
114+
├── [binary] # Compiled binary for MaixCam2
115+
└── dl_lib/ # Deep learning libraries (if exists)
116+
```
117+
118+
**When building single platform (`--platform maixcam` or `--platform maixcam2`):**
119+
```
120+
app_camera_release_20260129_153000/
121+
├── main.py # Direct execution script (runs platform-specific binary)
122+
├── app.yaml # Project configuration
123+
├── assets/ # Resource files (images/fonts)
124+
├── README.md # Project documentation
125+
├── README_EN.md # English documentation (if exists)
126+
└── maixcam/ # Only the selected platform folder
127+
├── [binary] # Compiled binary
128+
└── dl_lib/ # Deep learning libraries (if exists)
129+
```
130+
131+
### Key Output Files
132+
- **ZIP Package**: Named as `<PROJECT_NAME>_release_<TIMESTAMP>.zip` (timestamp format: `YYYYMMDD_HHMMSS`).
133+
- Batch mode: Stored in `[PROJECTS_DIRECTORY]/build/`.
134+
- Single mode: Stored in the project root directory by default.
135+
- **`main.py`**: The core execution script—**no manual modification needed** (auto-replaces the binary name during compilation).
136+
137+
## How to Deploy on MaixCam/MaixCam2
138+
1. Copy the generated ZIP file to the root directory of the MaixCam/MaixCam2 device (via SSH/SCP or SD card).
139+
2. Unzip the package on the device:
140+
```bash
141+
unzip <PROJECT_NAME>_release_<TIMESTAMP>.zip -d <PROJECT_FOLDER>
142+
```
143+
3. Enter the project folder and run the script:
144+
```bash
145+
cd <PROJECT_FOLDER>
146+
python main.py
147+
```
148+
The script will **automatically detect the device model** (MaixCam/MaixCam2), grant execute permission to the binary, and run it.
149+
150+
## Script Workflow
151+
### For Single Project Compilation
152+
1. Clean up previous build outputs (if any).
153+
2. Based on `--platform` parameter:
154+
- `both` (default): Compile for **MaixCam** first, then **MaixCam2**
155+
- `maixcam`: Compile only for **MaixCam**
156+
- `maixcam2`: Compile only for **MaixCam2**
157+
3. Copy shared resources (assets, app.yaml, README) to the output directory.
158+
4. Generate platform-appropriate `main.py`:
159+
- For `both`: Auto-detects device and runs corresponding binary
160+
- For single platform: Directly runs the platform-specific binary
161+
5. Package all files into a timestamped ZIP and clean up temporary build files.
162+
163+
### For Batch Compilation
164+
1. Create a `build/` directory for output ZIP packages.
165+
2. Traverse all subdirectories in the target folder, skip non-project folders, the `build/` directory, and projects in the exclusion list.
166+
3. Compile each valid project with the **single project workflow** using the specified platform, outputting ZIPs to the `build/` directory.
167+
4. Skip failed projects and continue compiling the rest.
168+
5. Print a summary (total/succeeded/failed projects) and list failed projects (if any).

‎projects/app_camera/README.md‎

Lines changed: 64 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,69 @@
1+
## 1. 简介
2+
本应用是基于Maix系列硬件（MaixCam/Pro/MaixCam2）开发的相机控制程序，集成了拍照、录像、参数调节等核心功能，适配不同分辨率的摄像头传感器，支持音视频同步录制、参数自定义配置等特性，可满足日常拍摄、延时摄影等多样化的使用需求。
13

2-
# Create lv_i8n file
4+
## 2. 主要功能
5+
| 功能分类 | 具体能力 |
6+
|----------|----------|
7+
| 基础拍摄 | 支持一键拍照，可设置拍照延时（单位：秒）；支持照片自动按日期分类存储，生成缩略图便于预览 |
8+
| 视频录制 | 支持H.264格式视频录制，音视频同步；可自定义视频码率，适配不同分辨率的码率自动推荐 |
9+
| 参数调节 | 快门：支持自动/手动模式，手动模式可自定义快门值<br>ISO：支持自动/手动模式，范围100~800<br>曝光补偿（EV）：支持自动/手动调节<br>白平衡（WB）：支持自动/手动调节<br>分辨率：支持3840×2160、2560×1440、1920×1080等多档位切换 |
10+
| 辅助功能 | 补光灯控制：支持开启/关闭硬件补光灯<br>延时摄影：可设置延时秒数，开启后自动按间隔录制视频（关闭音频）<br>对焦：支持手动对焦区域设置<br>时间戳：支持在画面中显示当前时间<br>RAW格式：支持开启/关闭RAW格式照片保存 |
311

4-
```shell
5-
# install npm
6-
sudo apt install npm
12+
## 3. 使用说明
13+
### 3.1 基础操作
14+
#### 3.1.1 拍照
15+
1. 进入应用后，默认进入预览界面；
16+
2. 可先设置拍照延时（可选，0秒为立即拍摄）；
17+
3. 点击拍照按钮，若设置了延时，界面会显示延时动画，延时结束后自动完成拍照；
18+
4. 照片会自动保存至「图片存储目录/当前日期/序号.jpg」路径，同时生成缩略图供预览。
719

8-
# intall lv_i18n
9-
sudo npm i lv_i18n -g
20+
#### 3.1.2 视频录制
21+
1. 点击录制开始按钮，应用自动准备录制环境并开始录制，界面显示录制时长；
22+
2. 录制过程中可查看实时录制时间，支持根据分辨率自动适配推荐码率，也可手动修改码率（非录制状态下）；
23+
3. 点击停止按钮，录制结束，视频自动保存至「视频存储目录/当前日期/序号.mp4」路径。
1024

11-
# create en-GB.yml, and edit it
12-
mkdir i18n
13-
touch i18n/en-GB.yml
25+
### 3.2 参数配置
26+
#### 3.2.1 分辨率切换
27+
1. 在参数设置界面选择分辨率档位，确认后应用会自动重启相机并加载新分辨率；
28+
2. 分辨率档位受硬件传感器限制，超出传感器最大尺寸的档位会被禁用。
1429

15-
# create lv_i18n file
16-
lv_i18n compile -t i18n/en-GB.yml -o i18n
17-
```
30+
#### 3.2.2 快门/ISO调节
31+
- 自动模式：勾选「自动」选项，相机会根据环境自动调节快门/ISO；
32+
- 手动模式：取消「自动」勾选，输入目标快门值（单位：秒）/ISO值，确认后立即生效。
33+
34+
#### 3.2.3 辅助功能开关
35+
- 补光灯：点击补光灯按钮，切换开启/关闭状态；
36+
- 时间戳：点击时间戳按钮，开启后画面左下角显示当前日期时间；
37+
- 延时摄影：设置延时秒数（0为关闭，>0为固定间隔，<0为自动模式），开启后录制视频时自动关闭音频；
38+
- RAW格式：点击RAW按钮，开启后拍照会同时保存RAW格式文件（后缀.raw）。
39+
40+
### 3.3 预览与查看
41+
1. 拍照完成后，界面会自动显示刚拍摄的照片缩略图和预览图；
42+
2. 点击「查看照片」按钮，可浏览已拍摄的照片。
43+
44+
## 4. 注意事项
45+
1. 分辨率切换：切换分辨率时，应用会重启相机模块，期间预览会短暂中断，属于正常现象；
46+
2. 码率修改：仅在非录制状态下可修改码率，录制过程中修改码率会提示「视频忙」且不生效；
47+
3. 延时摄影：开启延时摄影后，音频会自动关闭，关闭延时摄影后需手动重新开启音频；
48+
4. RAW格式：开启RAW格式后，照片保存体积会增大，且需要专用软件解析；
49+
5. 补光灯：补光灯的硬件引脚默认配置为GPIOB3，可通过设备配置文件修改引脚映射；
50+
6. 存储路径：照片/视频默认按日期分目录存储，需确保存储设备有足够空间，否则会保存失败；
51+
7. 音视频同步：录制视频时，若出现音频卡顿，可检查音频采样率配置（默认48000Hz）。
52+
53+
## 5. 更多介绍
54+
### 5.1 硬件适配
55+
- 支持MaixCam、MaixCam2两款硬件平台，MaixCam2支持更高码率（最高100Mbps）和AI-ISP功能；
56+
- 补光灯引脚可通过设备配置文件中的「cam_light_io」参数自定义，默认B3引脚；
57+
- 摄像头传感器最大分辨率决定可选分辨率档位，适配前需确认硬件传感器规格。
58+
59+
### 5.2 存储说明
60+
- 照片默认存储路径：应用指定的图片目录（可通过系统接口修改）；
61+
- 视频默认存储路径：应用指定的视频目录（可通过系统接口修改）；
62+
- 所有文件保存后会执行「sync」操作，确保数据写入存储设备，避免断电丢失。
63+
64+
### 5.3 性能说明
65+
- 预览帧率默认30fps，分辨率越高，预览/录制的系统资源占用越大；
66+
- 延时摄影模式下，视频帧率仍为30fps，仅按设置的间隔推送帧数据，适合长时间低帧率录制场景。
67+
68+
### 5.4 源码
69+
- [源码](https://github.com/sipeed/MaixCDK/tree/main/projects/app_camera)

‎projects/app_camera/README_EN.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
## 1. Introduction
2+
This application is a camera control program developed based on Maix series hardware (MaixCam/Pro/MaixCam2). It integrates core functions such as photo capture, video recording, and parameter adjustment. It is compatible with camera sensors of different resolutions and supports features like audio-video synchronization and custom parameter configuration, meeting diverse usage requirements such as daily shooting and time-lapse photography.
3+
4+
## 2. Main Features
5+
6+
| Feature Category | Capabilities |
7+
|------------------|--------------|
8+
| **Basic Shooting** | Supports one-click photo capture with configurable delay (in seconds). Photos are automatically categorized by date and thumbnails are generated for easy preview. |
9+
| **Video Recording** | Supports H.264 format video recording with audio-video synchronization. Video bitrate can be customized, and recommended bitrates are automatically adapted based on resolution. |
10+
| **Parameter Adjustment** | **Shutter:** Auto/manual mode with customizable shutter speed.<br>**ISO:** Auto/manual mode (range: 100~800).<br>**Exposure Compensation (EV):** Auto/manual adjustment.<br>**White Balance (WB):** Auto/manual adjustment.<br>**Resolution:** Switch between multiple presets (e.g., 3840×2160, 2560×1440, 1920×1080). |
11+
| **Auxiliary Functions** | **Fill Light:** Hardware fill light on/off control.<br>**Time-lapse:** Configurable interval; audio is automatically disabled when enabled.<br>**Focus:** Manual focus area setting.<br>**Timestamp:** Display current time on the screen.<br>**RAW Format:** Option to save photos in RAW format. |
12+
13+
## 3. User Guide
14+
15+
### 3.1 Basic Operations
16+
17+
#### 3.1.1 Taking Photos
18+
1. Upon entering the app, the preview screen is displayed by default.
19+
2. (Optional) Set a capture delay (0 seconds for immediate capture).
20+
3. Click the capture button. If a delay is set, a countdown animation will appear. The photo is taken automatically after the countdown.
21+
4. Photos are automatically saved to `[Image Storage Directory]/[Current Date]/[Index].jpg`, and a thumbnail is generated for preview.
22+
23+
#### 3.1.2 Video Recording
24+
1. Click the Record Start button. The app prepares the environment and starts recording; the recording duration is displayed on screen.
25+
2. During recording, the elapsed time is shown. The bitrate is auto-adapted but can be manually modified (only when not recording).
26+
3. Click the Stop button to end recording. The video is saved to `[Video Storage Directory]/[Current Date]/[Index].mp4`.
27+
28+
### 3.2 Parameter Configuration
29+
30+
#### 3.2.1 Resolution Switching
31+
1. Select a resolution preset in the settings menu.
32+
2. The app will automatically restart the camera module to apply the new resolution.
33+
3. Note: Options are limited by the hardware sensor; presets exceeding the sensor's maximum capability are disabled.
34+
35+
#### 3.2.2 Shutter/ISO Adjustment
36+
* **Auto Mode:** Check the "Auto" option. The camera adjusts Shutter/ISO based on the environment.
37+
* **Manual Mode:** Uncheck "Auto" and input the target Shutter speed (seconds) or ISO value. Changes take effect immediately.
38+
39+
#### 3.2.3 Auxiliary Function Switches
40+
* **Fill Light:** Toggle the button to turn the hardware light on or off.
41+
* **Timestamp:** Toggle the button to display the current date and time in the bottom-left corner.
42+
* **Time-lapse:** Set the interval in seconds (0 to disable, >0 for fixed interval). Audio is automatically disabled in this mode.
43+
* **RAW Format:** Toggle the button to save an additional RAW format file (`.raw` suffix) when capturing photos.
44+
45+
### 3.3 Preview and Playback
46+
1. After capturing a photo, the thumbnail and a larger preview are displayed automatically.
47+
2. Click the "View Photos" button to browse the photo gallery.
48+
49+
## 4. Notes
50+
51+
1. **Resolution Switching:** Switching resolution restarts the camera module, causing a brief interruption in the preview. This is normal behavior.
52+
2. **Bitrate Modification:** Bitrate can only be modified when not recording. Attempting to change it during recording will show a "Video Busy" warning and will not take effect.
53+
3. **Time-lapse Photography:** Audio is automatically disabled in time-lapse mode. You need to manually re-enable it if you switch back to normal recording.
54+
4. **RAW Format:** Enabling RAW format increases file size significantly, and dedicated software is required for viewing/processing.
55+
5. **Fill Light:** The default hardware pin for the light is GPIOB3. This can be modified via the device configuration file (`cam_light_io`).
56+
6. **Storage Path:** Files are stored in date-based directories by default. Ensure sufficient storage space is available to prevent save failures.
57+
7. **AV Sync:** If audio stutters during recording, check the audio sample rate configuration (default is 48000Hz).
58+
59+
## 5. More Information
60+
61+
### 5.1 Hardware Compatibility
62+
* Supports **MaixCam** and **MaixCam2** platforms.
63+
* **MaixCam2** supports higher bitrates (up to 100Mbps) and features AI-ISP.
64+
* The fill light pin is configurable via the `cam_light_io` parameter in the device config file (default: B3).
65+
* The available resolution options are determined by the camera sensor's maximum resolution.
66+
67+
### 5.2 Storage Details
68+
* **Default Photo Path:** Defined by the system interface (usually under the app's picture directory).
69+
* **Default Video Path:** Defined by the system interface (usually under the app's video directory).
70+
* A `sync` operation is performed after saving to ensure data is written to the storage device, preventing data loss in case of sudden power loss.
71+
72+
### 5.3 Performance
73+
* The default preview frame rate is 30fps. Higher resolutions consume more system resources.
74+
* In time-lapse mode, the output video remains at 30fps, but frames are pushed at the set interval. This is suitable for long-duration, low-frame-rate recording.
75+
76+
### 5.4 Source Code
77+
* [Source Code](https://github.com/sipeed/MaixCDK/tree/main/projects/app_camera)

‎projects/app_camera/app.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,4 +10,5 @@ files:
1010
app.yaml: app.yaml
1111
assets: assets
1212
README.md: README.md
13+
README_EN.md: README_EN.md
1314

0 commit comments

Comments
 (0)