¶
Style Camera
Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.
This project is an AI style camera sample built on the Quectel Pi M2 smart mainboard.
The system captures live video through a USB camera and runs artistic style-transfer models and a human pose model on the on-board NPU, providing 11 real-time effects — 7 artistic styles (Hayao, oil painting, candy, glass mosaic, sketch, ukiyo-e and ink painting) plus 4 fun stickers (dog, pig, rabbit and clown head) positioned by human body keypoints. It demonstrates the end-to-end pipeline of “video capture → real-time NPU stylization → one-press photo saving”. The GUI previews the stylized picture in real time; press the space bar to save a stylized photo, and open the photo folder directly from the thumbnail.
It is recommended to insert an application photo here (UI running view + effect comparison) as the cover.
Developer Resources¶
Accessory List¶
Note: tips — The accessory list is for reference only; actual requirements may vary with the development environment.
[电子表格]
Accessory Photos¶
It is recommended to insert a photo of the accessories here.
Quick Start¶
Preparation¶
The Quectel Pi M2 smart mainboard ships with the Debian 13 image by default, so there is no need to flash the image again — simply follow the steps below. The NPU runtime library, the Python 3.12 environment and all dependencies are installed automatically by the one-click deployment script bundled in the repository.
Hardware Connection¶
Complete all of the following hardware connections:
Camera: plug the USB camera into the USB-A port of the mainboard. Use v4l2-ctl –list-devices to check the device index (on the reference unit, PC Camera = /dev/video73); if it differs from the configuration, override it with the –camera N option.
Display (optional): connect an HDMI monitor to view the GUI locally; without a monitor, run in headless mode.
Network: connect an Ethernet cable for SSH login and code cloning.
Power: connect the Type-C power adapter and power on.
Note: tips — This project does not require audio peripherals such as a microphone or speaker. After connection, verify that the camera is present with v4l2-ctl –list-devices, or run –test-camera to measure the actual capture frame rate.
Project Implementation¶
Get the Code¶
Open a terminal on the mainboard and clone the project code with git.
sudo apt update
sudo apt install -y git
git clone https://github.com/Quectel-Pi/demo_style_camera.git
cd demo_style_camera
After the command completes, enter the demo_style_camera directory, which contains all source code of this project.
Environment Setup¶
Run the one-click deployment script bundled in the repository to automatically install a standalone Python 3.12 environment, inference dependencies and the RKNN runtime library:
sudo bash deploy/board_setup.sh
The script supports both online and offline modes: in online mode, Python 3.12 and pip dependencies are installed via uv; in offline mode, the wheels and offline Python packages shipped with the bundle are used. It also installs the NPU runtime librknnrt.so into the system directory.
Note: tips — All on-board dependencies are installed into the standalone /opt/py312 environment created by the deployment script. Do not run this project with the system python3 (it raises ModuleNotFoundError). run.sh locates the environment automatically — always launch the program through run.sh.
Self-Test¶
Before the first run, it is recommended to run the built-in self-checks in order to confirm that the hardware and software links work properly:
/opt/py312/bin/python3.12 selftest.py # Offline self-test: model loading / effect pipeline, no camera needed
sudo ./run.sh --test-camera # Camera test: measures the actual capture frame rate for 5 seconds
sudo ./run.sh --list-styles # Lists all currently available effects
sudo ./run.sh --test-style any.jpg # Runs all effects on any static image and saves the results
Run the Program¶
sudo ./run.sh
run.sh automatically locates the deployment directory and the Python environment, sets up the desktop display permissions and starts the program. If the program starts properly, a “Style Camera” window pops up, with the live effect preview on the left and the effect selection panel on the right.
For scenarios without a monitor, run in headless mode:
sudo ./run.sh --no-ui
UI and Features¶
After the program starts normally, the preview defaults to the raw picture (about 25 fps); click an effect button on the right to switch effects in real time, and press the space bar to take a photo.
[电子表格]
Shortcuts: in the GUI, press the space bar to take a photo; in the OpenCV fallback window, the space bar takes a photo, s cycles through effects, and q quits.
Effects Overview¶
All effects run on the NPU (the corresponding mode is hidden automatically when its model file is missing):
[电子表格]
Photo Storage¶
After pressing the space bar, photos are saved automatically to the photos/ directory:
style_YYYYMMDD_HHMMSS.jpg: the stylized picture (JPEG quality 95);
orig_time.jpg: the original picture at the original resolution (enabled when save.save_original: true in config.yaml).
Captures are completed through a dedicated photo-writing thread plus a queue, without blocking the preview.
How It Works¶
System data flow: 720p@30fps MJPG capture → stylization thread (art style modes: the image is scaled to the model input size and sent to the NPU for inference, and the result is pasted back onto the original frame; sticker modes: YOLOv8-Pose detects facial keypoints and the sticker PNG is scaled and aligned to the keypoint positions) → UI thread renders the preview / the capture thread enqueues the photo.
The three threads (capture and stylization, photo writing, UI) are decoupled from each other: the preview always stays smooth and photo taking never stutters. All style-transfer models take a unified 192×192 input (oil painting 224, Hayao 160); the normalization parameters are baked into the RKNN models, so the board can feed RGB images directly.
Model files are located in the models/ directory (7 style-transfer models + 1 pose model, all in RK3576 NPU fp16 format); to convert or replace a style model by yourself, refer to the conversion scripts under the tools/ directory.
Application Demo¶
It is recommended to insert an application demo video here (live effect switching + space bar photo capture).
Frequently Asked Questions and Solutions¶
Program cannot find the camera¶
Symptom:
Camera open failed
Solutions:
Confirm the camera device index with v4l2-ctl –list-devices;
Change camera.index in config.yaml, or specify it at runtime with the –camera N option (73 on the reference unit of this project).
GUI fails to start¶
Symptom: after running in a desktop environment no window pops up, and the program falls back to command-line mode.
Solutions:
Start with sudo ./run.sh; the script already handles the display permissions under the Wayland desktop (DISPLAY / XAUTHORITY / QT_QPA_PLATFORM);
If the log says the Qt xcb plugin failed to load, install the missing system library: sudo apt install -y libxcb-cursor0 (the deployment script has a built-in automatic fallback installation);
For scenarios without a monitor, use sudo ./run.sh –no-ui directly.
NPU inference error or model loading failure¶
Symptom:
RKNN run error / librknnrt version mismatch
Solutions:
Make sure librknnrt.so matches the on-board rknn-toolkit-lite2 version (re-running the deployment script aligns them automatically);
Make sure the model files are .rknn files compiled for the RK3576 target platform (bundled in the models/ directory of the project);
For debugging on a PC, run python3 main.py –config config_onnx_debug.yaml –test-style any.jpg to verify the pipeline with CPU inference.
Technical Support and Contribution¶
If you encounter any problems during use, feel free to submit a technical request on the Quectel official forum; our technical support team will answer you promptly.
Project open-source address: https://github.com/Quectel-Pi/demo_style_camera
Issues and Pull Requests for code improvements are welcome!