Back to Home Road Asset
Guides

Loading Models

How to add custom detection models to RoadAsset

Overview

RoadAsset supports custom YOLO detection models in ONNX and TensorFlow.js formats. Models are stored in Cloudflare R2 and delivered via CDN for fast, cached downloads. Once registered, models are cached locally in the browser using IndexedDB.

User Upload Admin Upload

User Model Upload

New

Upload your own models directly from the browser with our easy-to-use wizard. No command-line tools or admin access required.

Upload a Model

Personal

Only you can see and use the model. Perfect for testing and personal projects.

Organization

Share with your team. All organization members can use the model.

Public

Share with everyone. Requires admin approval before becoming visible.

Upload Wizard Steps

1 Select Files → 2 Model Details → 3 Visibility → 4 Upload

System Models (Admin)

For administrators adding system-wide models via R2

1

Prepare Your Model

Export your trained YOLO model in one of the supported formats:

ONNX Format

Recommended
  • Single file: best.onnx
  • Faster inference with ONNX Runtime
  • WebGPU acceleration supported

TensorFlow.js Format

  • Multiple files: model.json + shards
  • Native TensorFlow.js support
  • Good fallback compatibility
Important: Models must be YOLO-compatible with NMS (Non-Maximum Suppression) built-in. The output format should be [batch, num_detections, 6] where each detection is [x, y, width, height, confidence, class_id].
2

Create Folder Structure

Organize your model files in a folder structure before uploading to R2:

# For ONNX models:
your-model-name/
├── best.onnx
└── metadata.yaml # optional
# For TensorFlow.js models:
your-model-name/
├── model.json
├── group1-shard1of2.bin
├── group1-shard2of2.bin
└── metadata.yaml # optional

metadata.yaml (Optional)

Include a metadata file to auto-populate model details during registration:

label: "Road Asset Detection v2"
description: "Trained on Malaysian highways"
version: "2.0.0"
author: "Your Name"
license: "MIT"
modelType: detect  # detect | segment | classify
classLabels:
  0: "signboard"
  1: "guardrail"
  2: "kilometer_marker"
  3: "bridge"
stride: 32
imgsz: [640, 640]
3

Upload to R2 Bucket

Upload your model folder to the roadasset-models R2 bucket under the system/ prefix:

Option A: Wrangler CLI

# Upload entire folder
wrangler r2 object put roadasset-models/system/your-model-name/ \
--file ./your-model-name/ --recursive
# Or upload individual files
wrangler r2 object put roadasset-models/system/your-model-name/best.onnx \
--file ./your-model-name/best.onnx

Option B: Cloudflare Dashboard

  1. Go to Cloudflare Dashboard → R2 → roadasset-models
  2. Navigate to the system/ folder (create if needed)
  3. Create a new folder with your model name
  4. Upload all model files into the folder
Verification: After uploading, your model should be accessible at: https://roadasset-models.analitik.my/system/your-model-name/best.onnx
4

Register Model

Recommended: Use the Model Upload Wizard which handles both upload and registration automatically.

If you've manually uploaded files to R2 (Steps 1-3), register the model via the Models section:

  1. Go to Models (/models)
  2. Click "Upload Model" and select your files
  3. The wizard will detect the model format and validate files
  4. Edit the model details (label, description, class labels)
  5. Choose visibility (Personal, Organization, or Public)
  6. Complete the upload to register your model

What Gets Auto-Detected:

  • Model format (ONNX or TFJS)
  • File size in bytes
  • R2 key and CDN URL
  • Metadata from metadata.yaml (if present)

Browser Caching

When users select a model for detection, it's automatically downloaded and cached locally in their browser using IndexedDB. This enables:

  • Instant model loading on subsequent visits
  • Offline detection capability (once cached)
  • Reduced bandwidth usage

Cache Management

Users can manage their local cache in Detection Settings → Model Cache:

View Cache Status

See used space, cached models, and last used times

Clear Cache

Remove all cached models or individual models

Cache Limits by Plan:

  • Free: 200 MB
  • Basic: 500 MB
  • Pro: 1 GB
  • Team: 2 GB

When the cache limit is reached, least recently used models are automatically evicted.

Troubleshooting

Model not appearing in Scan R2

  • Ensure files are under system/ prefix
  • Check that the folder contains either best.onnx or model.json
  • Verify the R2 bucket binding is configured in wrangler.toml

Model fails to load in browser

  • Check browser console for CORS errors
  • Verify CDN URL is accessible (try in new tab)
  • For TFJS models, ensure all shard files are uploaded
  • Clear browser cache and try again

Detection not working correctly

  • Verify model output format matches expected YOLO format
  • Check that class labels are correctly mapped (0-indexed)
  • Ensure input size matches model's expected imgsz
  • Try with confidence threshold of 0.25 initially

Related

My Models
Manage your uploaded models
Upload Model
Add a new custom model
Model Formats
ONNX vs TensorFlow.js comparison
Detection Settings
Configure thresholds and performance
enmsid