Robot obstacle detector (YOLO26n, 6 classes)

An obstacle detector for the robot's camera, with the model, the code and every Python package needed. It runs offline on a Windows or a Linux machine, on the CPU or on an NVIDIA GPU (built for the RTX 3060).

class id	class	trained from
0	table	table
1	tv or pc monitor	TV + PC monitor
2	box	box + foam resin bundle
3	beverage	bottle (glass, resin) + can
4	trunk	trunk
5	chair	chair

Files

file	size	for	contents
`obstacle_detector_windows.zip`	2.4 GB	Windows x64	detector + model; CPU wheels (Python 3.10–3.14); pre-installed GPU packages for Python 3.10
`obstacle_detector_linux.zip`	2.6 GB	Linux x86_64 / aarch64	the same for Linux (CPU wheels also for aarch64)
`cuda_env_py310_windows.zip`	3.3 GB	Windows x64	offline wheels for a Python 3.10 CUDA environment: PyTorch 2.10 + ultralytics, ONNX Runtime GPU
`cuda_env_py310_linux.zip`	4.6 GB	Linux x86_64	the same for Linux

To run the detector: you only need obstacle_detector_<os>.zip.
To train or use the .pt model with Ultralytics on the GPU: also take cuda_env_py310_<os>.zip. It also gives a GPU environment for the detector, as an alternative to the pre-installed packages.

Each zip holds a README with the details.

Download with the browser (Files tab), or:

huggingface-cli download beketov027/obstacle_detector obstacle_detector_linux.zip --local-dir .
wget https://huggingface.co/beketov027/obstacle_detector/resolve/main/obstacle_detector_linux.zip

What each machine needs

	CPU	NVIDIA GPU (RTX 3060)
Python	3.10 – 3.14, 64-bit	3.10, 64-bit
driver	–	NVIDIA ≥ 528 (Windows) / ≥ 525 (Linux); 570+ recommended for the CUDA environment
CUDA toolkit, cuDNN	–	not needed (they come as Python packages)
internet	not needed	not needed

Windows machine

Unzip to a short path, such as C:\obstacle_detector or C:\cuda_env_py310. Windows limits paths to 260 characters, and some packages have files about 140 characters deep. The scripts check this.

Detector on the GPU (Python 3.10): no install

cd C:\obstacle_detector
run_gpu_windows.bat --source samples --save out          # finds "py -3.10"; or: set PYTHON=C:\Python310\python.exe
run_gpu_windows.bat --source 0 --save out                # camera 0

It uses the packages pre-installed in gpu\lib_windows_py310 (onnxruntime-gpu 1.23.2, CUDA 12.8, cuDNN 9.10). If CUDA cannot be used, it prints a warning and runs on the CPU.

Detector on the CPU

cd C:\obstacle_detector
python obstacle_detector.py --source samples --save out  # Python 3.10: no install (uses gpu\ packages on the CPU)
install_windows.bat                                       # any Python 3.10 - 3.14: one offline install into .venv
run_windows.bat --source samples --save out

CUDA environment (PyTorch + ultralytics + ONNX Runtime GPU)

cd C:\cuda_env_py310
install_windows.bat              # .venv with everything, then verify_cuda.py -> "ALL OK: the GPU works"
install_windows.bat torch        # PyTorch + ultralytics only
.venv\Scripts\python -c "from ultralytics import YOLO; print(YOLO('models/obstacle_yolo26n_6cls.pt').predict('models/sample.jpg', device=0)[0].boxes)"

On Windows, ONNX Runtime GPU uses PyTorch's CUDA DLLs, so it is installed together with PyTorch.

Linux machine

unzip obstacle_detector_linux.zip      # the .sh scripts stay executable
unzip cuda_env_py310_linux.zip

Detector on the GPU (Python 3.10): no install

cd obstacle_detector
./run_gpu_linux.sh --source samples --save out           # finds python3.10; or PYTHON=/path/to/python3.10 ./run_gpu_linux.sh ...
./run_gpu_linux.sh --source 0 --save out                 # camera 0

It uses gpu/lib_linux_py310. No LD_LIBRARY_PATH or CUDA toolkit is needed.

Detector on the CPU

cd obstacle_detector
python3.10 obstacle_detector.py --source samples --save out   # Python 3.10: no install
./install_linux.sh                                            # any Python 3.10 - 3.14 (x86_64 or aarch64): one offline install
./run_linux.sh --source samples --save out

CUDA environment (PyTorch + ultralytics + ONNX Runtime GPU)

cd cuda_env_py310
./install_linux.sh               # .venv with everything, then verify_cuda.py -> "ALL OK: the GPU works"
./install_linux.sh torch         # PyTorch + ultralytics only
./install_linux.sh onnxruntime   # ONNX Runtime GPU only
source .venv/bin/activate

On Linux both stacks share the same nvidia-* CUDA wheels.

Using the detector

These options work for every script. run_* scripts pass their arguments to obstacle_detector.py.

--source samples | video.mp4 | 0          image, folder, video file or camera index
--save out | --json out/dets.jsonl        annotated output / detections as JSON lines
--profile recall                          recall-first thresholds (default: balanced)
--conf 0.5 | --class-conf "chair=0.3"     one threshold for all classes / per-class overrides
--eval-labels labels/                     precision / recall / F1 against YOLO labels
--benchmark 50                            latency
--device cuda                             NVIDIA GPU (the run_gpu_* scripts add it)

From Python:

import cv2
from obstacle_detector import ObstacleDetector   # for the GPU: OBSTACLE_DEVICE=cuda before this import
det = ObstacleDetector()                         # or ObstacleDetector(device="cuda"); det.warmup(1280, 720)
for d in det.detect(cv2.imread("frame.jpg")):    # BGR image, e.g. a camera frame
    print(d["name"], d["conf"], d["box"])        # box = [x1, y1, x2, y2] in pixels

Accuracy, thresholds and speed

Accuracy. Measured on 497 generated validation images (2,345 objects, IoU 0.5), with per-class confidence thresholds stored in config.json:

profile	table	tv/monitor	box	beverage	trunk	chair	precision / recall / F1
balanced (default, best F1)	0.34	0.50	0.46	0.54	0.51	0.41	0.917 / 0.823 / 0.868
recall (best F2)	0.20	0.50	0.21	0.23	0.51	0.18	0.856 / 0.845 / 0.850

The thresholds come from generated images. Re-tune them on real robot-camera frames with tune_thresholds.py --images ... --labels ... --write.

Speed. Measured on a 1376×768 frame, including pre- and postprocessing:

machine	ms per frame
3-vCPU Windows server (CPU)	34
Linux CPU, 8 threads	34
RTX 3090 (GPU)	5.7

The RTX 3060 is the same architecture with fewer cores; expect roughly 7–10 ms per frame.

Model

Architecture: YOLO26n (Ultralytics 8.4.183), input 640, trained 100 epochs from COCO-pretrained yolo26n.pt.
Data: about 4,000 Gemini-generated obstacle-course images, with labels from SAM3 that were then reviewed by hand (beketov027/obstacle_label).
Files: in each obstacle_detector zip, models/obstacle_yolo26n_6cls.onnx is used for inference and models/obstacle_yolo26n_6cls.pt is the PyTorch weights.

Tested

	result
Linux x86_64 + RTX 3090 (compute capability 8.6, like the RTX 3060)	GPU detector from the unpacked zip with a bare Python 3.10; CUDA environment `install_linux.sh all` + `verify_cuda.py` ALL OK
Linux x86_64 CPU	install with Python 3.11 / 3.12, full validation
Windows x64 without a GPU and without the VC++ Redistributable	CPU install with Python 3.10 / 3.12, Python 3.10 without install; GPU packages load and fall back to the CPU

Not tested here:

a GPU on Windows;
the Linux aarch64 wheels;
Python 3.13 / 3.14.

Licences

Model: the model and code use Ultralytics YOLO (AGPL-3.0).
Bundled third-party packages: each keeps its own licence. This includes NVIDIA CUDA / cuDNN wheels, PyTorch, ONNX Runtime, OpenCV, numpy, and the Microsoft Visual C++ runtime DLLs in the Windows detector package.

Downloads last month: -; Downloads are not tracked for this model. How to track