CV / PPSeg

PP-LiteSeg

reComputer RK3588

PP-LiteSeg Cityscapes semantic segmentation accelerated by RKNN.

57 downloads

Precision

RKNN

Choose the device you're using, the set up guide and documentation will update accordingly.

Platform

Inference Engine

Getting Started

Armbian 26.8.7 Gnome or newer with OTA overlayroot: Configure Docker storage before running containers to avoid overlay mount errors.

Deploy

sudo docker run --rm --privileged --net=host \
  -e PYTHONUNBUFFERED=1 -e RKNN_LOG_LEVEL=0 \
  --device /dev/dri/renderD129:/dev/dri/renderD129 \
  -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
  ghcr.io/seeed-projects/recomputer-rk-cv/rk3588-ppseg:latest \
  python web_service.py --platform rk3588 --model_dir /app/model --camera_id -1 --host 0.0.0.0 --port 8000

REST API

Use the REST API to run inference. Copy the commands below.

Curl

curl http://localhost:8080/v1/chat/completions -d '{
  "model": "pp-liteseg-rknn",
  "messages": [{"role": "user", "content": "Hello"}]
}'

Python

import requests

resp = requests.post(
    "http://localhost:8080/v1/chat/completions",
    json={"model": "pp-liteseg-rknn", "messages": [{"role": "user", "content": "Hello"}]},
)
print(resp.json())

Model Details

Armbian 26.8.7 Gnome or newer with OTA overlayroot: Configure Docker storage before running containers to avoid overlay mount errors.

Quick Start

1. Install Docker

Run the following commands on the development board to install Docker:

bash

# Download installation script
curl -fsSL https://get.docker.com -o get-docker.sh
# Install using Aliyun mirror source
sudo sh get-docker.sh --mirror Aliyun
# Start Docker and enable auto-start on boot
sudo systemctl enable docker
sudo systemctl start docker

2. Run the Project (One command, dual-mode preview)

This service packages the PP-LiteSeg Cityscapes example from reComputer-RK-CV with RKNN inference, Web preview, REST APIs, and asynchronous MP4 processing.

Model Information

Property	Value
Model	`model/ppseg.rknn`
Input	`512 x 512` RGB
Output	19-class Cityscapes segmentation mask
Warm-up image	`model/test.png`

Step A: Pull Images

bash

sudo docker pull ghcr.io/seeed-projects/recomputer-rk-cv/rk3588-ppseg:latest
sudo docker pull ghcr.io/seeed-projects/recomputer-rk-cv/rk3576-ppseg:latest

Step B: Run with One Click

For RK3576:

bash

sudo docker run --rm --privileged --net=host \
  -e PYTHONUNBUFFERED=1 -e RKNN_LOG_LEVEL=0 \
  --device /dev/dri/renderD129:/dev/dri/renderD129 \
  -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
  ghcr.io/seeed-projects/recomputer-rk-cv/rk3576-ppseg:latest \
  python web_service.py --platform rk3576 --model_dir /app/model \
  --camera_id -1 --host 0.0.0.0 --port 8000

For RK3588:

bash

sudo docker run --rm --privileged --net=host \
  -e PYTHONUNBUFFERED=1 -e RKNN_LOG_LEVEL=0 \
  --device /dev/dri/renderD129:/dev/dri/renderD129 \
  -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
  ghcr.io/seeed-projects/recomputer-rk-cv/rk3588-ppseg:latest \
  python web_service.py --platform rk3588 --model_dir /app/model \
  --camera_id -1 --host 0.0.0.0 --port 8000

Open http://<BOARD_IP>:8000 or /docs. Use --camera_id N with a mapped /dev/videoN node for a camera. Use --video video/test.mp4 for the bundled video; --video and --video_path are aliases and override the camera.

🔌 API Documentation

1. Segmentation Interface (Predict)

Endpoint: POST /api/models/ppseg/predict

Request Parameters (Multipart/Form-Data):

file: Image file to segment. The service resizes it to 512 x 512 before inference.

Usage Examples:

bash

curl -X POST "http://<BOARD_IP>:8000/api/models/ppseg/predict" \
  -F "file=@test.png"

The response contains inference time, source dimensions, and per-class pixel counts. The latest mask overlay is served by GET /api/video_feed.

Endpoint	Purpose
`GET /api/health`	Platform, model names, and readiness.
`GET /api/video_feed`	Latest color-mask overlay as MJPEG.
`POST /api/video/upload`	Upload one MP4 in field `file`.
`POST /api/video/analyze`	Analyze an uploaded `filename`.
`GET /api/video/status`	Background progress and errors.
`GET /api/video/list`	Uploaded and generated videos.
`GET /api/video/download/{filename}`	Download a result.

2. System Configuration Interface (Config)

The generic threshold and topk configuration fields are retained for service compatibility but do not change the fixed argmax segmentation. A replacement model must retain the expected 19-class output or update the palette and post-processing code.

The runtime resizes input to 512 x 512, converts BGR to RGB, accepts NCHW or NHWC 19-class output, restores the mask with nearest-neighbor interpolation, and overlays the Cityscapes palette. Conversion sources are under rknn_model_zoo/examples/ppseg in the upstream project.

3. Command Line Arguments

Argument	Default	Description
`--platform`	Required	`rk3576` or `rk3588`.
`--model_dir`	`model`	Directory containing `ppseg.rknn` and `test.png`.
`--camera_id`	`-1`	Camera index; `-1` disables capture.
`--video`, `--video_path`	None	Looping local video; overrides the camera.
`--host` / `--port`	`0.0.0.0` / `8000`	FastAPI listen address and port.

PYTHONUNBUFFERED=1 flushes logs immediately. RKNN_LOG_LEVEL=0 suppresses known harmless static-model initialization messages; remove it while debugging RKNN startup.

Real-time Video Stream Interface (Video Feed)

Get the latest annotated MJPEG stream for browser preview:

Endpoint: GET /api/video_feed
Example Usage: <img src="http://<BOARD_IP>:8000/api/video_feed">

🛠️ Developer Guide (Production Recommendations)

Build Local Images

bash

docker build -f docker/rk3576/ppseg.dockerfile \
  -t rk3576-ppseg:local src/rk3576_ppseg

docker build -f docker/rk3588/ppseg.dockerfile \
  -t rk3588-ppseg:local src/rk3588_ppseg

Inputs and Outputs

Input: image, video frame, or camera frame. Output: Cityscapes mask, class pixel counts, and overlay.