CV / DeepLab v3

DeepLabV3 RKNN

DeepLabV3 semantic segmentation accelerated by RKNN on reComputer RK3576 and RK3588.

8 downloads

Precision

RKNN

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

Platform

Inference Engine

Getting Started

Deploy

sudo docker run --rm --privileged -p 8000:8000 \
  -v /dev/dri/renderD129:/dev/dri/renderD129 \
  -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
  ghcr.io/seeed-projects/recomputer-rk-cv/rk3576-deeplabv3:latest \
  python3 web_service.py --platform rk3576 --model_path /app/model/deeplabv3.rknn \
  --sample_path /app/model/test.jpg --overlay_alpha 0.5 --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": "deeplab-v3-rknn",
  "messages": [{"role": "user", "content": "Hello"}]
}'

Python

import requests

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

Model Details

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 page documents the DeepLabV3 semantic-segmentation service in reComputer-RK-CV. It supports still images, cameras, looping local video, uploaded MP4 analysis, and an MJPEG overlay preview.

Model Information

Property	Value
Model	`/app/model/deeplabv3.rknn`
Input	`513 x 513` RGB
Output	21-class PASCAL VOC logits
Rendering	Argmax mask with configurable color-overlay opacity

The service validates both NCHW and NHWC output layouts and restores the mask to the source resolution.

Step A: Pull Images

bash

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

Step B: Run with One Click

For RK3576:

bash

sudo docker run --rm --privileged -p 8000:8000 \
  -v /dev/dri/renderD129:/dev/dri/renderD129 \
  -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
  ghcr.io/seeed-projects/recomputer-rk-cv/rk3576-deeplabv3:latest \
  python3 web_service.py --platform rk3576 \
  --model_path /app/model/deeplabv3.rknn \
  --sample_path /app/model/test.jpg --overlay_alpha 0.5 \
  --camera_id -1 --host 0.0.0.0 --port 8000

For RK3588:

bash

sudo docker run --rm --privileged -p 8000:8000 \
  -v /dev/dri/renderD129:/dev/dri/renderD129 \
  -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
  ghcr.io/seeed-projects/recomputer-rk-cv/rk3588-deeplabv3:latest \
  python3 web_service.py --platform rk3588 \
  --model_path /app/model/deeplabv3.rknn \
  --sample_path /app/model/test.jpg --overlay_alpha 0.5 \
  --camera_id -1 --host 0.0.0.0 --port 8000

Open http://<BOARD_IP>:8000 or /docs. For a USB camera, map its /dev/videoN node and set --camera_id N. For a mounted local video, use --video /data/input.mp4; local video takes precedence over the camera.

🔌 API Documentation

1. Segmentation Interface (Predict)

Endpoint: POST /api/models/deeplabv3/predict

Request Parameters (Multipart/Form-Data):

file: Image file to segment.
overlay_alpha: Optional mask opacity from 0.0 to 1.0; defaults to the current service configuration.

Usage Examples:

bash

curl -X POST "http://<BOARD_IP>:8000/api/models/deeplabv3/predict" \
  -F "file=@test.jpg" -F "overlay_alpha=0.65"

The response reports image size, inference time, opacity, and all PASCAL VOC classes present with their pixel counts. The latest rendered overlay is available from GET /api/video_feed.

Response Format (JSON):

json

{
  "success": true,
  "model": "deeplabv3",
  "inference_time": 0.052,
  "result": {
    "classes": [{"id": 15, "class": "person", "pixels": 18234}],
    "width": 1280,
    "height": 720,
    "overlay_alpha": 0.65
  }
}

2. System Configuration Interface (Config)

GET/POST /api/config manages the global overlay opacity. Health, MP4 upload, analysis status, list, and download endpoints are also provided. Models with a different class count require corresponding label and output-processing code changes.

3. Command Line Arguments

Argument	Default	Description
`--platform`	Required	`rk3576` or `rk3588`.
`--model_path`	`model/deeplabv3.rknn`	DeepLabV3 RKNN file.
`--sample_path`	`model/test.jpg`	Warm-up and initial-preview image.
`--overlay_alpha`	`0.5`	Initial mask opacity from 0 to 1.
`--camera_id`	`-1`	Camera `N`, or `-1` for uploads only.
`--video`, `--video_path`	None	Looping local video; overrides the camera.
`--host` / `--port`	`0.0.0.0` / `8000`	Service address and container port.

When using -p, change only the host side if port 8000 is occupied. The container service must remain on port 8000 for its health check.

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)

Processing Details

Input is resized to 513 x 513 and converted from BGR to RGB. The runtime accepts NCHW or NHWC logits, verifies that the output has 21 channels, restores the logits to the source resolution, applies argmax, and overlays the PASCAL VOC color map. POST /api/video/analyze accepts an uploaded filename; status and result files are exposed through the /api/video/* endpoints.

Build Local Images

bash

docker build -f docker/rk3576/deeplabv3.dockerfile \
  -t rk3576-deeplabv3:local src/rk3576_deeplabv3

docker build -f docker/rk3588/deeplabv3.dockerfile \
  -t rk3588-deeplabv3:local src/rk3588_deeplabv3

Inputs and Outputs

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