CV / MobileNet

MobileNetV2

reComputer RK3588

MobileNetV2 image classification accelerated by RKNN on reComputer RK3576 and RK3588.

55 downloads

Precision

RKNN

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

Platform

Size

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/renderD128:/dev/dri/renderD128 \
  -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
  ghcr.io/seeed-projects/recomputer-rk-cv/rk3588-mobilenet:latest \
  python3 web_classification.py --model_path model/rk3588_mobilenet_v2.rknn --camera_id -1

REST API

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

Curl

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

Python

import requests

resp = requests.post(
    "http://localhost:8080/v1/chat/completions",
    json={"model": "mobilenet-v2-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 page is adapted from the MobileNetV2 READMEs in reComputer-RK-CV. The service runs ImageNet classification with RKNN-Toolkit-Lite2 and provides a Web preview, MJPEG stream, health check, and REST API.

Model Information

Property	Value
Task	Image classification
Input	`224 x 224` image
Output	Configurable Top-K ImageNet labels and confidence scores
RK3576 model	`model/rk3576_mobilenet_v2.rknn`
RK3588 model	`model/rk3588_mobilenet_v2.rknn`
Labels	`model/synset.txt`

Step A: Pull Images

bash

sudo docker pull ghcr.io/seeed-projects/recomputer-rk-cv/rk3588-mobilenet:latest
sudo docker pull ghcr.io/seeed-projects/recomputer-rk-cv/rk3576-mobilenet: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/renderD128:/dev/dri/renderD128 \
  -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
  ghcr.io/seeed-projects/recomputer-rk-cv/rk3576-mobilenet:latest \
  python3 web_classification.py \
  --model_path model/rk3576_mobilenet_v2.rknn --camera_id -1

For RK3588:

bash

sudo docker run --rm --privileged --net=host \
  -e PYTHONUNBUFFERED=1 -e RKNN_LOG_LEVEL=0 \
  --device /dev/dri/renderD128:/dev/dri/renderD128 \
  -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
  ghcr.io/seeed-projects/recomputer-rk-cv/rk3588-mobilenet:latest \
  python3 web_classification.py \
  --model_path model/rk3588_mobilenet_v2.rknn --camera_id -1

Open http://<BOARD_IP>:8000 for the Web page or http://<BOARD_IP>:8000/docs for OpenAPI. Replace --camera_id -1 with a mapped camera ID, or use --video_path video/test.mp4 for the bundled video.

🔌 API Documentation

1. Model Inference Interface (Predict)

Endpoint: POST /api/models/mobilenet/predict

Request Parameters (Multipart/Form-Data):

file: Optional image file to classify.
video: Optional MP4 file; it cannot be supplied together with file.
timestamp: Optional non-negative video timestamp in seconds; defaults to the first frame.
conf: Optional request-level confidence threshold from 0.0 to 1.0.
topk: Optional number of results from 1 to 20; defaults to 5.
With neither file nor video, the current camera or local-video frame is used when available.

Usage Examples:

bash

curl -X POST "http://<BOARD_IP>:8000/api/models/mobilenet/predict" \
  -F "file=@bell.jpg" -F "topk=5" -F "conf=0.01"

To classify a frame at 5.5 seconds in an MP4:

bash

curl -X POST "http://<BOARD_IP>:8000/api/models/mobilenet/predict" \
  -F "video=@test.mp4" -F "timestamp=5.5" -F "topk=3"

Response Format (JSON):

json

{
  "success": true,
  "model": "mobilenet",
  "source": "uploaded image",
  "predictions": [
    {"class": "n02123045 tabby, tabby cat", "confidence": 0.91}
  ],
  "image": {"width": 640, "height": 480}
}

2. System Configuration Interface (Config)

GET /api/config returns the global conf_thresh. Update it with POST /api/config and JSON such as {"conf_thresh":0.1}. A request-level conf value overrides the global threshold for that request.

Endpoint	Purpose
`GET /api/health`	Platform, model path, and readiness.
`GET /api/video_feed`	Annotated MJPEG preview.
`POST /api/video/upload`	Upload JPG, JPEG, PNG, BMP, or MP4.
`POST /api/video/analyze`	Start asynchronous analysis by uploaded `filename`.
`GET /api/video/status`	Progress and error state.
`GET /api/video/list`	Uploaded and generated files.
`GET /api/video/download/{filename}`	Download a generated result.

3. Command Line Arguments

The application accepts an uploaded image, an uploaded MP4 frame selected by timestamp, a looping local video, or a camera frame. A local video takes precedence over the camera.

Argument	Default	Description
`--model_path`	Required	RKNN model selected for the target SoC.
`--camera_id`	`1`	Camera index; use `-1` for upload-only mode.
`--video_path`	None	Local MP4 path. Overrides `--camera_id`.
`--host`	`0.0.0.0`	FastAPI listen address.
`--port`	`8000`	Service port.

For a USB camera, map the matching device node, for example --device /dev/video0:/dev/video0, and pass --camera_id 0.

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)

Model Replacement

The preprocessing keeps the BGR channel order required by this model, applies softmax, and filters the Top-K results. A replacement model must preserve the input layout, channel order, normalization, and output format. Update synset.txt when changing the class set. Runtime uploads and outputs are stored under workspace/; set RK_CV_WORKSPACE to use a different directory.

Build Local Images

Run from the upstream repository root:

bash

docker build -f docker/rk3576/mobilenet.dockerfile \
  -t rk3576-mobilenet:local src/rk3576_mobilenet

docker build -f docker/rk3588/mobilenet.dockerfile \
  -t rk3588-mobilenet:local src/rk3588_mobilenet

Inputs and Outputs

Input: image, video frame, or camera frame. Output: Top-K ImageNet labels and confidence scores.