From 78883a404422607bebc476976a48267909c169ff Mon Sep 17 00:00:00 2001 From: rathaumons Date: Thu, 2 May 2024 14:19:48 +0200 Subject: [PATCH] Initialize v8.1.48 - Hello world! --- .github/workflows/publish.yaml | 67 + .github/workflows/test_build.yaml | 49 + .gitignore | 164 ++ LICENSE | 661 ++++++ MANIFEST.in | 10 + README.md | 38 + create_whl.cmd | 14 + examples/README.md | 36 + examples/YOLOv8-CPP-Inference/CMakeLists.txt | 28 + examples/YOLOv8-CPP-Inference/README.md | 50 + examples/YOLOv8-CPP-Inference/inference.cpp | 185 ++ examples/YOLOv8-CPP-Inference/inference.h | 52 + examples/YOLOv8-CPP-Inference/main.cpp | 70 + .../CMakeLists.txt | 47 + .../YOLOv8-LibTorch-CPP-Inference/README.md | 35 + .../YOLOv8-LibTorch-CPP-Inference/main.cc | 259 +++ .../YOLOv8-ONNXRuntime-CPP/CMakeLists.txt | 96 + examples/YOLOv8-ONNXRuntime-CPP/README.md | 107 + examples/YOLOv8-ONNXRuntime-CPP/inference.cpp | 375 +++ examples/YOLOv8-ONNXRuntime-CPP/inference.h | 94 + examples/YOLOv8-ONNXRuntime-CPP/main.cpp | 193 ++ examples/YOLOv8-ONNXRuntime-Rust/Cargo.toml | 21 + examples/YOLOv8-ONNXRuntime-Rust/README.md | 221 ++ examples/YOLOv8-ONNXRuntime-Rust/src/cli.rs | 87 + examples/YOLOv8-ONNXRuntime-Rust/src/lib.rs | 119 + examples/YOLOv8-ONNXRuntime-Rust/src/main.rs | 28 + examples/YOLOv8-ONNXRuntime-Rust/src/model.rs | 642 ++++++ .../src/ort_backend.rs | 534 +++++ .../src/yolo_result.rs | 235 ++ examples/YOLOv8-ONNXRuntime/README.md | 43 + examples/YOLOv8-ONNXRuntime/main.py | 231 ++ examples/YOLOv8-OpenCV-ONNX-Python/README.md | 19 + examples/YOLOv8-OpenCV-ONNX-Python/main.py | 130 ++ .../README.md | 65 + .../YOLOv8-OpenCV-int8-tflite-Python/main.py | 299 +++ examples/YOLOv8-Region-Counter/readme.md | 123 + .../yolov8_region_counter.py | 251 ++ .../YOLOv8-SAHI-Inference-Video/readme.md | 69 + .../yolov8_sahi.py | 111 + .../README.md | 63 + .../main.py | 342 +++ examples/heatmaps.ipynb | 145 ++ examples/hub.ipynb | 106 + examples/object_counting.ipynb | 147 ++ examples/object_tracking.ipynb | 203 ++ examples/tutorial.ipynb | 649 ++++++ requirements.txt | 29 + setup.cfg | 70 + setup.py | 98 + tests/conftest.py | 71 + tests/test_cli.py | 138 ++ tests/test_engine.py | 133 ++ tests/test_python.py | 664 ++++++ ultralytics/__init__.py | 27 + ultralytics/assets/bus.jpg | Bin 0 -> 137419 bytes ultralytics/assets/zidane.jpg | Bin 0 -> 50427 bytes ultralytics/cfg/__init__.py | 601 +++++ ultralytics/cfg/datasets/Argoverse.yaml | 74 + ultralytics/cfg/datasets/DOTAv1.5.yaml | 36 + ultralytics/cfg/datasets/DOTAv1.yaml | 35 + ultralytics/cfg/datasets/GlobalWheat2020.yaml | 53 + ultralytics/cfg/datasets/ImageNet.yaml | 2024 +++++++++++++++++ ultralytics/cfg/datasets/Objects365.yaml | 442 ++++ ultralytics/cfg/datasets/SKU-110K.yaml | 57 + ultralytics/cfg/datasets/VOC.yaml | 99 + ultralytics/cfg/datasets/VisDrone.yaml | 72 + .../cfg/datasets/african-wildlife.yaml | 24 + ultralytics/cfg/datasets/brain-tumor.yaml | 22 + ultralytics/cfg/datasets/carparts-seg.yaml | 43 + ultralytics/cfg/datasets/coco-pose.yaml | 38 + ultralytics/cfg/datasets/coco.yaml | 114 + ultralytics/cfg/datasets/coco128-seg.yaml | 100 + ultralytics/cfg/datasets/coco128.yaml | 100 + ultralytics/cfg/datasets/coco8-pose.yaml | 25 + ultralytics/cfg/datasets/coco8-seg.yaml | 100 + ultralytics/cfg/datasets/coco8.yaml | 100 + ultralytics/cfg/datasets/crack-seg.yaml | 21 + ultralytics/cfg/datasets/dota8.yaml | 34 + ultralytics/cfg/datasets/lvis.yaml | 1239 ++++++++++ ultralytics/cfg/datasets/open-images-v7.yaml | 660 ++++++ ultralytics/cfg/datasets/package-seg.yaml | 21 + ultralytics/cfg/datasets/tiger-pose.yaml | 24 + ultralytics/cfg/datasets/xView.yaml | 152 ++ ultralytics/cfg/default.yaml | 126 + ultralytics/cfg/models/README.md | 40 + ultralytics/cfg/models/rt-detr/rtdetr-l.yaml | 50 + .../cfg/models/rt-detr/rtdetr-resnet101.yaml | 42 + .../cfg/models/rt-detr/rtdetr-resnet50.yaml | 42 + ultralytics/cfg/models/rt-detr/rtdetr-x.yaml | 54 + ultralytics/cfg/models/v3/yolov3-spp.yaml | 46 + ultralytics/cfg/models/v3/yolov3-tiny.yaml | 37 + ultralytics/cfg/models/v3/yolov3.yaml | 46 + ultralytics/cfg/models/v5/yolov5-p6.yaml | 59 + ultralytics/cfg/models/v5/yolov5.yaml | 48 + ultralytics/cfg/models/v6/yolov6.yaml | 53 + .../cfg/models/v8/yolov8-cls-resnet101.yaml | 25 + .../cfg/models/v8/yolov8-cls-resnet50.yaml | 25 + ultralytics/cfg/models/v8/yolov8-cls.yaml | 29 + .../cfg/models/v8/yolov8-ghost-p2.yaml | 54 + .../cfg/models/v8/yolov8-ghost-p6.yaml | 56 + ultralytics/cfg/models/v8/yolov8-ghost.yaml | 47 + ultralytics/cfg/models/v8/yolov8-obb.yaml | 46 + ultralytics/cfg/models/v8/yolov8-p2.yaml | 54 + ultralytics/cfg/models/v8/yolov8-p6.yaml | 56 + ultralytics/cfg/models/v8/yolov8-pose-p6.yaml | 57 + ultralytics/cfg/models/v8/yolov8-pose.yaml | 47 + ultralytics/cfg/models/v8/yolov8-rtdetr.yaml | 46 + ultralytics/cfg/models/v8/yolov8-seg-p6.yaml | 56 + ultralytics/cfg/models/v8/yolov8-seg.yaml | 46 + ultralytics/cfg/models/v8/yolov8-world.yaml | 48 + ultralytics/cfg/models/v8/yolov8-worldv2.yaml | 46 + ultralytics/cfg/models/v8/yolov8.yaml | 46 + ultralytics/cfg/models/v9/yolov9c-seg.yaml | 38 + ultralytics/cfg/models/v9/yolov9c.yaml | 38 + ultralytics/cfg/models/v9/yolov9e-seg.yaml | 61 + ultralytics/cfg/models/v9/yolov9e.yaml | 61 + ultralytics/cfg/trackers/botsort.yaml | 18 + ultralytics/cfg/trackers/bytetrack.yaml | 11 + ultralytics/data/__init__.py | 26 + ultralytics/data/annotator.py | 50 + ultralytics/data/augment.py | 1384 +++++++++++ ultralytics/data/base.py | 310 +++ ultralytics/data/build.py | 209 ++ ultralytics/data/converter.py | 561 +++++ ultralytics/data/dataset.py | 506 +++++ ultralytics/data/explorer/__init__.py | 5 + ultralytics/data/explorer/explorer.py | 472 ++++ ultralytics/data/explorer/gui/__init__.py | 1 + ultralytics/data/explorer/gui/dash.py | 268 +++ ultralytics/data/explorer/utils.py | 167 ++ ultralytics/data/loaders.py | 558 +++++ ultralytics/data/scripts/download_weights.sh | 18 + ultralytics/data/scripts/get_coco.sh | 60 + ultralytics/data/scripts/get_coco128.sh | 17 + ultralytics/data/scripts/get_imagenet.sh | 51 + ultralytics/data/split_dota.py | 288 +++ ultralytics/data/utils.py | 676 ++++++ ultralytics/engine/__init__.py | 1 + ultralytics/engine/exporter.py | 1148 ++++++++++ ultralytics/engine/model.py | 845 +++++++ ultralytics/engine/predictor.py | 397 ++++ ultralytics/engine/results.py | 743 ++++++ ultralytics/engine/trainer.py | 761 +++++++ ultralytics/engine/tuner.py | 242 ++ ultralytics/engine/validator.py | 338 +++ ultralytics/hub/__init__.py | 128 ++ ultralytics/hub/auth.py | 136 ++ ultralytics/hub/session.py | 372 +++ ultralytics/hub/utils.py | 247 ++ ultralytics/models/__init__.py | 7 + ultralytics/models/fastsam/__init__.py | 8 + ultralytics/models/fastsam/model.py | 34 + ultralytics/models/fastsam/predict.py | 86 + ultralytics/models/fastsam/prompt.py | 359 +++ ultralytics/models/fastsam/utils.py | 67 + ultralytics/models/fastsam/val.py | 40 + ultralytics/models/nas/__init__.py | 7 + ultralytics/models/nas/model.py | 84 + ultralytics/models/nas/predict.py | 60 + ultralytics/models/nas/val.py | 50 + ultralytics/models/rtdetr/__init__.py | 7 + ultralytics/models/rtdetr/model.py | 54 + ultralytics/models/rtdetr/predict.py | 86 + ultralytics/models/rtdetr/train.py | 102 + ultralytics/models/rtdetr/val.py | 135 ++ ultralytics/models/sam/__init__.py | 6 + ultralytics/models/sam/amg.py | 187 ++ ultralytics/models/sam/build.py | 161 ++ ultralytics/models/sam/model.py | 115 + ultralytics/models/sam/modules/__init__.py | 1 + ultralytics/models/sam/modules/decoders.py | 190 ++ ultralytics/models/sam/modules/encoders.py | 603 +++++ ultralytics/models/sam/modules/sam.py | 65 + .../models/sam/modules/tiny_encoder.py | 742 ++++++ ultralytics/models/sam/modules/transformer.py | 274 +++ ultralytics/models/sam/predict.py | 478 ++++ ultralytics/models/utils/__init__.py | 1 + ultralytics/models/utils/loss.py | 346 +++ ultralytics/models/utils/ops.py | 263 +++ ultralytics/models/yolo/__init__.py | 7 + ultralytics/models/yolo/classify/__init__.py | 7 + ultralytics/models/yolo/classify/predict.py | 61 + ultralytics/models/yolo/classify/train.py | 159 ++ ultralytics/models/yolo/classify/val.py | 113 + ultralytics/models/yolo/detect/__init__.py | 7 + ultralytics/models/yolo/detect/predict.py | 43 + ultralytics/models/yolo/detect/train.py | 143 ++ ultralytics/models/yolo/detect/val.py | 318 +++ ultralytics/models/yolo/model.py | 107 + ultralytics/models/yolo/obb/__init__.py | 7 + ultralytics/models/yolo/obb/predict.py | 53 + ultralytics/models/yolo/obb/train.py | 42 + ultralytics/models/yolo/obb/val.py | 185 ++ ultralytics/models/yolo/pose/__init__.py | 7 + ultralytics/models/yolo/pose/predict.py | 58 + ultralytics/models/yolo/pose/train.py | 79 + ultralytics/models/yolo/pose/val.py | 248 ++ ultralytics/models/yolo/segment/__init__.py | 7 + ultralytics/models/yolo/segment/predict.py | 57 + ultralytics/models/yolo/segment/train.py | 62 + ultralytics/models/yolo/segment/val.py | 277 +++ ultralytics/models/yolo/world/__init__.py | 5 + ultralytics/models/yolo/world/train.py | 92 + ultralytics/models/yolo/world/train_world.py | 108 + ultralytics/nn/__init__.py | 29 + ultralytics/nn/autobackend.py | 653 ++++++ ultralytics/nn/modules/__init__.py | 138 ++ ultralytics/nn/modules/block.py | 686 ++++++ ultralytics/nn/modules/conv.py | 333 +++ ultralytics/nn/modules/head.py | 492 ++++ ultralytics/nn/modules/transformer.py | 426 ++++ ultralytics/nn/modules/utils.py | 85 + ultralytics/nn/tasks.py | 1055 +++++++++ ultralytics/solutions/__init__.py | 1 + ultralytics/solutions/ai_gym.py | 150 ++ ultralytics/solutions/distance_calculation.py | 181 ++ ultralytics/solutions/heatmap.py | 306 +++ ultralytics/solutions/object_counter.py | 283 +++ ultralytics/solutions/queue_management.py | 187 ++ ultralytics/solutions/speed_estimation.py | 198 ++ ultralytics/trackers/README.md | 321 +++ ultralytics/trackers/__init__.py | 7 + ultralytics/trackers/basetrack.py | 105 + ultralytics/trackers/bot_sort.py | 200 ++ ultralytics/trackers/byte_tracker.py | 444 ++++ ultralytics/trackers/track.py | 90 + ultralytics/trackers/utils/__init__.py | 1 + ultralytics/trackers/utils/gmc.py | 363 +++ ultralytics/trackers/utils/kalman_filter.py | 360 +++ ultralytics/trackers/utils/matching.py | 138 ++ ultralytics/utils/__init__.py | 1095 +++++++++ ultralytics/utils/autobatch.py | 88 + ultralytics/utils/benchmarks.py | 401 ++++ ultralytics/utils/callbacks/__init__.py | 5 + ultralytics/utils/callbacks/base.py | 218 ++ ultralytics/utils/callbacks/clearml.py | 153 ++ ultralytics/utils/callbacks/comet.py | 375 +++ ultralytics/utils/callbacks/dvc.py | 145 ++ ultralytics/utils/callbacks/hub.py | 105 + ultralytics/utils/callbacks/mlflow.py | 133 ++ ultralytics/utils/callbacks/neptune.py | 112 + ultralytics/utils/callbacks/raytune.py | 29 + ultralytics/utils/callbacks/tensorboard.py | 107 + ultralytics/utils/callbacks/wb.py | 163 ++ ultralytics/utils/checks.py | 736 ++++++ ultralytics/utils/dist.py | 71 + ultralytics/utils/downloads.py | 500 ++++ ultralytics/utils/errors.py | 22 + ultralytics/utils/files.py | 188 ++ ultralytics/utils/instance.py | 407 ++++ ultralytics/utils/loss.py | 716 ++++++ ultralytics/utils/metrics.py | 1289 +++++++++++ ultralytics/utils/ops.py | 849 +++++++ ultralytics/utils/patches.py | 88 + ultralytics/utils/plotting.py | 1120 +++++++++ ultralytics/utils/tal.py | 344 +++ ultralytics/utils/torch_utils.py | 631 +++++ ultralytics/utils/triton.py | 92 + ultralytics/utils/tuner.py | 148 ++ 259 files changed, 52124 insertions(+) create mode 100644 .github/workflows/publish.yaml create mode 100644 .github/workflows/test_build.yaml create mode 100644 .gitignore create mode 100644 LICENSE create mode 100644 MANIFEST.in create mode 100644 README.md create mode 100644 create_whl.cmd create mode 100644 examples/README.md create mode 100644 examples/YOLOv8-CPP-Inference/CMakeLists.txt create mode 100644 examples/YOLOv8-CPP-Inference/README.md create mode 100644 examples/YOLOv8-CPP-Inference/inference.cpp create mode 100644 examples/YOLOv8-CPP-Inference/inference.h create mode 100644 examples/YOLOv8-CPP-Inference/main.cpp create mode 100644 examples/YOLOv8-LibTorch-CPP-Inference/CMakeLists.txt create mode 100644 examples/YOLOv8-LibTorch-CPP-Inference/README.md create mode 100644 examples/YOLOv8-LibTorch-CPP-Inference/main.cc create mode 100644 examples/YOLOv8-ONNXRuntime-CPP/CMakeLists.txt create mode 100644 examples/YOLOv8-ONNXRuntime-CPP/README.md create mode 100644 examples/YOLOv8-ONNXRuntime-CPP/inference.cpp create mode 100644 examples/YOLOv8-ONNXRuntime-CPP/inference.h create mode 100644 examples/YOLOv8-ONNXRuntime-CPP/main.cpp create mode 100644 examples/YOLOv8-ONNXRuntime-Rust/Cargo.toml create mode 100644 examples/YOLOv8-ONNXRuntime-Rust/README.md create mode 100644 examples/YOLOv8-ONNXRuntime-Rust/src/cli.rs create mode 100644 examples/YOLOv8-ONNXRuntime-Rust/src/lib.rs create mode 100644 examples/YOLOv8-ONNXRuntime-Rust/src/main.rs create mode 100644 examples/YOLOv8-ONNXRuntime-Rust/src/model.rs create mode 100644 examples/YOLOv8-ONNXRuntime-Rust/src/ort_backend.rs create mode 100644 examples/YOLOv8-ONNXRuntime-Rust/src/yolo_result.rs create mode 100644 examples/YOLOv8-ONNXRuntime/README.md create mode 100644 examples/YOLOv8-ONNXRuntime/main.py create mode 100644 examples/YOLOv8-OpenCV-ONNX-Python/README.md create mode 100644 examples/YOLOv8-OpenCV-ONNX-Python/main.py create mode 100644 examples/YOLOv8-OpenCV-int8-tflite-Python/README.md create mode 100644 examples/YOLOv8-OpenCV-int8-tflite-Python/main.py create mode 100644 examples/YOLOv8-Region-Counter/readme.md create mode 100644 examples/YOLOv8-Region-Counter/yolov8_region_counter.py create mode 100644 examples/YOLOv8-SAHI-Inference-Video/readme.md create mode 100644 examples/YOLOv8-SAHI-Inference-Video/yolov8_sahi.py create mode 100644 examples/YOLOv8-Segmentation-ONNXRuntime-Python/README.md create mode 100644 examples/YOLOv8-Segmentation-ONNXRuntime-Python/main.py create mode 100644 examples/heatmaps.ipynb create mode 100644 examples/hub.ipynb create mode 100644 examples/object_counting.ipynb create mode 100644 examples/object_tracking.ipynb create mode 100644 examples/tutorial.ipynb create mode 100644 requirements.txt create mode 100644 setup.cfg create mode 100644 setup.py create mode 100644 tests/conftest.py create mode 100644 tests/test_cli.py create mode 100644 tests/test_engine.py create mode 100644 tests/test_python.py create mode 100644 ultralytics/__init__.py create mode 100644 ultralytics/assets/bus.jpg create mode 100644 ultralytics/assets/zidane.jpg create mode 100644 ultralytics/cfg/__init__.py create mode 100644 ultralytics/cfg/datasets/Argoverse.yaml create mode 100644 ultralytics/cfg/datasets/DOTAv1.5.yaml create mode 100644 ultralytics/cfg/datasets/DOTAv1.yaml create mode 100644 ultralytics/cfg/datasets/GlobalWheat2020.yaml create mode 100644 ultralytics/cfg/datasets/ImageNet.yaml create mode 100644 ultralytics/cfg/datasets/Objects365.yaml create mode 100644 ultralytics/cfg/datasets/SKU-110K.yaml create mode 100644 ultralytics/cfg/datasets/VOC.yaml create mode 100644 ultralytics/cfg/datasets/VisDrone.yaml create mode 100644 ultralytics/cfg/datasets/african-wildlife.yaml create mode 100644 ultralytics/cfg/datasets/brain-tumor.yaml create mode 100644 ultralytics/cfg/datasets/carparts-seg.yaml create mode 100644 ultralytics/cfg/datasets/coco-pose.yaml create mode 100644 ultralytics/cfg/datasets/coco.yaml create mode 100644 ultralytics/cfg/datasets/coco128-seg.yaml create mode 100644 ultralytics/cfg/datasets/coco128.yaml create mode 100644 ultralytics/cfg/datasets/coco8-pose.yaml create mode 100644 ultralytics/cfg/datasets/coco8-seg.yaml create mode 100644 ultralytics/cfg/datasets/coco8.yaml create mode 100644 ultralytics/cfg/datasets/crack-seg.yaml create mode 100644 ultralytics/cfg/datasets/dota8.yaml create mode 100644 ultralytics/cfg/datasets/lvis.yaml create mode 100644 ultralytics/cfg/datasets/open-images-v7.yaml create mode 100644 ultralytics/cfg/datasets/package-seg.yaml create mode 100644 ultralytics/cfg/datasets/tiger-pose.yaml create mode 100644 ultralytics/cfg/datasets/xView.yaml create mode 100644 ultralytics/cfg/default.yaml create mode 100644 ultralytics/cfg/models/README.md create mode 100644 ultralytics/cfg/models/rt-detr/rtdetr-l.yaml create mode 100644 ultralytics/cfg/models/rt-detr/rtdetr-resnet101.yaml create mode 100644 ultralytics/cfg/models/rt-detr/rtdetr-resnet50.yaml create mode 100644 ultralytics/cfg/models/rt-detr/rtdetr-x.yaml create mode 100644 ultralytics/cfg/models/v3/yolov3-spp.yaml create mode 100644 ultralytics/cfg/models/v3/yolov3-tiny.yaml create mode 100644 ultralytics/cfg/models/v3/yolov3.yaml create mode 100644 ultralytics/cfg/models/v5/yolov5-p6.yaml create mode 100644 ultralytics/cfg/models/v5/yolov5.yaml create mode 100644 ultralytics/cfg/models/v6/yolov6.yaml create mode 100644 ultralytics/cfg/models/v8/yolov8-cls-resnet101.yaml create mode 100644 ultralytics/cfg/models/v8/yolov8-cls-resnet50.yaml create mode 100644 ultralytics/cfg/models/v8/yolov8-cls.yaml create mode 100644 ultralytics/cfg/models/v8/yolov8-ghost-p2.yaml create mode 100644 ultralytics/cfg/models/v8/yolov8-ghost-p6.yaml create mode 100644 ultralytics/cfg/models/v8/yolov8-ghost.yaml create mode 100644 ultralytics/cfg/models/v8/yolov8-obb.yaml create mode 100644 ultralytics/cfg/models/v8/yolov8-p2.yaml create mode 100644 ultralytics/cfg/models/v8/yolov8-p6.yaml create mode 100644 ultralytics/cfg/models/v8/yolov8-pose-p6.yaml create mode 100644 ultralytics/cfg/models/v8/yolov8-pose.yaml create mode 100644 ultralytics/cfg/models/v8/yolov8-rtdetr.yaml create mode 100644 ultralytics/cfg/models/v8/yolov8-seg-p6.yaml create mode 100644 ultralytics/cfg/models/v8/yolov8-seg.yaml create mode 100644 ultralytics/cfg/models/v8/yolov8-world.yaml create mode 100644 ultralytics/cfg/models/v8/yolov8-worldv2.yaml create mode 100644 ultralytics/cfg/models/v8/yolov8.yaml create mode 100644 ultralytics/cfg/models/v9/yolov9c-seg.yaml create mode 100644 ultralytics/cfg/models/v9/yolov9c.yaml create mode 100644 ultralytics/cfg/models/v9/yolov9e-seg.yaml create mode 100644 ultralytics/cfg/models/v9/yolov9e.yaml create mode 100644 ultralytics/cfg/trackers/botsort.yaml create mode 100644 ultralytics/cfg/trackers/bytetrack.yaml create mode 100644 ultralytics/data/__init__.py create mode 100644 ultralytics/data/annotator.py create mode 100644 ultralytics/data/augment.py create mode 100644 ultralytics/data/base.py create mode 100644 ultralytics/data/build.py create mode 100644 ultralytics/data/converter.py create mode 100644 ultralytics/data/dataset.py create mode 100644 ultralytics/data/explorer/__init__.py create mode 100644 ultralytics/data/explorer/explorer.py create mode 100644 ultralytics/data/explorer/gui/__init__.py create mode 100644 ultralytics/data/explorer/gui/dash.py create mode 100644 ultralytics/data/explorer/utils.py create mode 100644 ultralytics/data/loaders.py create mode 100644 ultralytics/data/scripts/download_weights.sh create mode 100644 ultralytics/data/scripts/get_coco.sh create mode 100644 ultralytics/data/scripts/get_coco128.sh create mode 100644 ultralytics/data/scripts/get_imagenet.sh create mode 100644 ultralytics/data/split_dota.py create mode 100644 ultralytics/data/utils.py create mode 100644 ultralytics/engine/__init__.py create mode 100644 ultralytics/engine/exporter.py create mode 100644 ultralytics/engine/model.py create mode 100644 ultralytics/engine/predictor.py create mode 100644 ultralytics/engine/results.py create mode 100644 ultralytics/engine/trainer.py create mode 100644 ultralytics/engine/tuner.py create mode 100644 ultralytics/engine/validator.py create mode 100644 ultralytics/hub/__init__.py create mode 100644 ultralytics/hub/auth.py create mode 100644 ultralytics/hub/session.py create mode 100644 ultralytics/hub/utils.py create mode 100644 ultralytics/models/__init__.py create mode 100644 ultralytics/models/fastsam/__init__.py create mode 100644 ultralytics/models/fastsam/model.py create mode 100644 ultralytics/models/fastsam/predict.py create mode 100644 ultralytics/models/fastsam/prompt.py create mode 100644 ultralytics/models/fastsam/utils.py create mode 100644 ultralytics/models/fastsam/val.py create mode 100644 ultralytics/models/nas/__init__.py create mode 100644 ultralytics/models/nas/model.py create mode 100644 ultralytics/models/nas/predict.py create mode 100644 ultralytics/models/nas/val.py create mode 100644 ultralytics/models/rtdetr/__init__.py create mode 100644 ultralytics/models/rtdetr/model.py create mode 100644 ultralytics/models/rtdetr/predict.py create mode 100644 ultralytics/models/rtdetr/train.py create mode 100644 ultralytics/models/rtdetr/val.py create mode 100644 ultralytics/models/sam/__init__.py create mode 100644 ultralytics/models/sam/amg.py create mode 100644 ultralytics/models/sam/build.py create mode 100644 ultralytics/models/sam/model.py create mode 100644 ultralytics/models/sam/modules/__init__.py create mode 100644 ultralytics/models/sam/modules/decoders.py create mode 100644 ultralytics/models/sam/modules/encoders.py create mode 100644 ultralytics/models/sam/modules/sam.py create mode 100644 ultralytics/models/sam/modules/tiny_encoder.py create mode 100644 ultralytics/models/sam/modules/transformer.py create mode 100644 ultralytics/models/sam/predict.py create mode 100644 ultralytics/models/utils/__init__.py create mode 100644 ultralytics/models/utils/loss.py create mode 100644 ultralytics/models/utils/ops.py create mode 100644 ultralytics/models/yolo/__init__.py create mode 100644 ultralytics/models/yolo/classify/__init__.py create mode 100644 ultralytics/models/yolo/classify/predict.py create mode 100644 ultralytics/models/yolo/classify/train.py create mode 100644 ultralytics/models/yolo/classify/val.py create mode 100644 ultralytics/models/yolo/detect/__init__.py create mode 100644 ultralytics/models/yolo/detect/predict.py create mode 100644 ultralytics/models/yolo/detect/train.py create mode 100644 ultralytics/models/yolo/detect/val.py create mode 100644 ultralytics/models/yolo/model.py create mode 100644 ultralytics/models/yolo/obb/__init__.py create mode 100644 ultralytics/models/yolo/obb/predict.py create mode 100644 ultralytics/models/yolo/obb/train.py create mode 100644 ultralytics/models/yolo/obb/val.py create mode 100644 ultralytics/models/yolo/pose/__init__.py create mode 100644 ultralytics/models/yolo/pose/predict.py create mode 100644 ultralytics/models/yolo/pose/train.py create mode 100644 ultralytics/models/yolo/pose/val.py create mode 100644 ultralytics/models/yolo/segment/__init__.py create mode 100644 ultralytics/models/yolo/segment/predict.py create mode 100644 ultralytics/models/yolo/segment/train.py create mode 100644 ultralytics/models/yolo/segment/val.py create mode 100644 ultralytics/models/yolo/world/__init__.py create mode 100644 ultralytics/models/yolo/world/train.py create mode 100644 ultralytics/models/yolo/world/train_world.py create mode 100644 ultralytics/nn/__init__.py create mode 100644 ultralytics/nn/autobackend.py create mode 100644 ultralytics/nn/modules/__init__.py create mode 100644 ultralytics/nn/modules/block.py create mode 100644 ultralytics/nn/modules/conv.py create mode 100644 ultralytics/nn/modules/head.py create mode 100644 ultralytics/nn/modules/transformer.py create mode 100644 ultralytics/nn/modules/utils.py create mode 100644 ultralytics/nn/tasks.py create mode 100644 ultralytics/solutions/__init__.py create mode 100644 ultralytics/solutions/ai_gym.py create mode 100644 ultralytics/solutions/distance_calculation.py create mode 100644 ultralytics/solutions/heatmap.py create mode 100644 ultralytics/solutions/object_counter.py create mode 100644 ultralytics/solutions/queue_management.py create mode 100644 ultralytics/solutions/speed_estimation.py create mode 100644 ultralytics/trackers/README.md create mode 100644 ultralytics/trackers/__init__.py create mode 100644 ultralytics/trackers/basetrack.py create mode 100644 ultralytics/trackers/bot_sort.py create mode 100644 ultralytics/trackers/byte_tracker.py create mode 100644 ultralytics/trackers/track.py create mode 100644 ultralytics/trackers/utils/__init__.py create mode 100644 ultralytics/trackers/utils/gmc.py create mode 100644 ultralytics/trackers/utils/kalman_filter.py create mode 100644 ultralytics/trackers/utils/matching.py create mode 100644 ultralytics/utils/__init__.py create mode 100644 ultralytics/utils/autobatch.py create mode 100644 ultralytics/utils/benchmarks.py create mode 100644 ultralytics/utils/callbacks/__init__.py create mode 100644 ultralytics/utils/callbacks/base.py create mode 100644 ultralytics/utils/callbacks/clearml.py create mode 100644 ultralytics/utils/callbacks/comet.py create mode 100644 ultralytics/utils/callbacks/dvc.py create mode 100644 ultralytics/utils/callbacks/hub.py create mode 100644 ultralytics/utils/callbacks/mlflow.py create mode 100644 ultralytics/utils/callbacks/neptune.py create mode 100644 ultralytics/utils/callbacks/raytune.py create mode 100644 ultralytics/utils/callbacks/tensorboard.py create mode 100644 ultralytics/utils/callbacks/wb.py create mode 100644 ultralytics/utils/checks.py create mode 100644 ultralytics/utils/dist.py create mode 100644 ultralytics/utils/downloads.py create mode 100644 ultralytics/utils/errors.py create mode 100644 ultralytics/utils/files.py create mode 100644 ultralytics/utils/instance.py create mode 100644 ultralytics/utils/loss.py create mode 100644 ultralytics/utils/metrics.py create mode 100644 ultralytics/utils/ops.py create mode 100644 ultralytics/utils/patches.py create mode 100644 ultralytics/utils/plotting.py create mode 100644 ultralytics/utils/tal.py create mode 100644 ultralytics/utils/torch_utils.py create mode 100644 ultralytics/utils/triton.py create mode 100644 ultralytics/utils/tuner.py diff --git a/.github/workflows/publish.yaml b/.github/workflows/publish.yaml new file mode 100644 index 0000000..517e954 --- /dev/null +++ b/.github/workflows/publish.yaml @@ -0,0 +1,67 @@ +name: Publish on PyPI + +on: + push: + tags: + - "v*" + +jobs: + + build_wheel: + name: Build wheel + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-python@v4 + with: + python-version: '3.11' + - name: Install requirements + run: | + python -m pip install --upgrade pip + pip install "setuptools>=67.2.0" + pip install -r requirements.txt + pip install wheel build PyYAML + - name: Build .whl + run: | + python -m build --wheel --skip-dependency-check + - name: Archive wheels + uses: actions/upload-artifact@v3 + with: + path: dist/*.whl + + build_source: + name: Build source + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-python@v4 + with: + python-version: '3.11' + - name: Install requirements + run: | + python -m pip install --upgrade pip + pip install "setuptools>=67.2.0" + pip install wheel build PyYAML + - name: Build .tar.gz + run: | + python -m build --sdist --skip-dependency-check + - name: Archive wheels + uses: actions/upload-artifact@v3 + with: + path: dist/*.tar.gz + + publish_pypi: + name: Publish 📦 on PyPI + needs: [build_wheel, build_source] + runs-on: ubuntu-latest + environment: pypi + permissions: + id-token: write + steps: + - name: Collect and extract artifact + uses: actions/download-artifact@v3 + with: + name: artifact + path: dist + - name: Publish + uses: pypa/gh-action-pypi-publish@release/v1 diff --git a/.github/workflows/test_build.yaml b/.github/workflows/test_build.yaml new file mode 100644 index 0000000..d160cfc --- /dev/null +++ b/.github/workflows/test_build.yaml @@ -0,0 +1,49 @@ +name: Test Build + +on: [workflow_dispatch] + +jobs: + + build_wheel: + name: Build wheel + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-python@v4 + with: + python-version: '3.11' + - name: Install requirements + run: | + python -m pip install --upgrade pip + pip install "setuptools>=67.2.0" + pip install -r requirements.txt + pip install wheel build + - name: Build .whl + run: | + python -m build --wheel --skip-dependency-check + - name: Archive + uses: actions/upload-artifact@v3 + with: + path: dist/*.whl + + build_source: + name: Build source + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-python@v4 + with: + python-version: '3.11' + - name: Install requirements + run: | + python -m pip install --upgrade pip + pip install "setuptools>=67.2.0" + pip install -r requirements.txt + pip install wheel build + - name: Build .tar.gz + run: | + python -m build --sdist --skip-dependency-check + - name: Archive + uses: actions/upload-artifact@v3 + with: + path: dist/*.tar.gz diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..5b9d176 --- /dev/null +++ b/.gitignore @@ -0,0 +1,164 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +pip-wheel-metadata/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# Profiling +*.pclprof + +# pyenv +.python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +.idea +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# VSCode project settings +.vscode/ + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site +mkdocs_github_authors.yaml + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# datasets and projects +# datasets/ +runs/ +wandb/ +.DS_Store + +# Neural Network weights ----------------------------------------------------------------------------------------------- +weights/ +*.weights +*.pt +*.pb +*.onnx +*.engine +*.mlmodel +*.mlpackage +*.torchscript +*.tflite +*.h5 +*_saved_model/ +*_web_model/ +*_openvino_model/ +*_paddle_model/ +pnnx* + +# Autogenerated files for tests +# /ultralytics/assets/ diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..be3f7b2 --- /dev/null +++ b/LICENSE @@ -0,0 +1,661 @@ + GNU AFFERO GENERAL PUBLIC LICENSE + Version 3, 19 November 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The GNU Affero General Public License is a free, copyleft license for +software and other kinds of works, specifically designed to ensure +cooperation with the community in the case of network server software. + + The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +our General Public Licenses are intended to guarantee your freedom to +share and change all versions of a program--to make sure it remains free +software for all its users. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + + Developers that use our General Public Licenses protect your rights +with two steps: (1) assert copyright on the software, and (2) offer +you this License which gives you legal permission to copy, distribute +and/or modify the software. + + A secondary benefit of defending all users' freedom is that +improvements made in alternate versions of the program, if they +receive widespread use, become available for other developers to +incorporate. Many developers of free software are heartened and +encouraged by the resulting cooperation. However, in the case of +software used on network servers, this result may fail to come about. +The GNU General Public License permits making a modified version and +letting the public access it on a server without ever releasing its +source code to the public. + + The GNU Affero General Public License is designed specifically to +ensure that, in such cases, the modified source code becomes available +to the community. It requires the operator of a network server to +provide the source code of the modified version running there to the +users of that server. Therefore, public use of a modified version, on +a publicly accessible server, gives the public access to the source +code of the modified version. + + An older license, called the Affero General Public License and +published by Affero, was designed to accomplish similar goals. This is +a different license, not a version of the Affero GPL, but Affero has +released a new version of the Affero GPL which permits relicensing under +this license. + + The precise terms and conditions for copying, distribution and +modification follow. + + TERMS AND CONDITIONS + + 0. Definitions. + + "This License" refers to version 3 of the GNU Affero General Public License. + + "Copyright" also means copyright-like laws that apply to other kinds of +works, such as semiconductor masks. + + "The Program" refers to any copyrightable work licensed under this +License. Each licensee is addressed as "you". "Licensees" and +"recipients" may be individuals or organizations. + + To "modify" a work means to copy from or adapt all or part of the work +in a fashion requiring copyright permission, other than the making of an +exact copy. The resulting work is called a "modified version" of the +earlier work or a work "based on" the earlier work. + + A "covered work" means either the unmodified Program or a work based +on the Program. + + To "propagate" a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification), making available to the +public, and in some countries other activities as well. + + To "convey" a work means any kind of propagation that enables other +parties to make or receive copies. Mere interaction with a user through +a computer network, with no transfer of a copy, is not conveying. + + An interactive user interface displays "Appropriate Legal Notices" +to the extent that it includes a convenient and prominently visible +feature that (1) displays an appropriate copyright notice, and (2) +tells the user that there is no warranty for the work (except to the +extent that warranties are provided), that licensees may convey the +work under this License, and how to view a copy of this License. If +the interface presents a list of user commands or options, such as a +menu, a prominent item in the list meets this criterion. + + 1. Source Code. + + The "source code" for a work means the preferred form of the work +for making modifications to it. "Object code" means any non-source +form of a work. + + A "Standard Interface" means an interface that either is an official +standard defined by a recognized standards body, or, in the case of +interfaces specified for a particular programming language, one that +is widely used among developers working in that language. + + The "System Libraries" of an executable work include anything, other +than the work as a whole, that (a) is included in the normal form of +packaging a Major Component, but which is not part of that Major +Component, and (b) serves only to enable use of the work with that +Major Component, or to implement a Standard Interface for which an +implementation is available to the public in source code form. A +"Major Component", in this context, means a major essential component +(kernel, window system, and so on) of the specific operating system +(if any) on which the executable work runs, or a compiler used to +produce the work, or an object code interpreter used to run it. + + The "Corresponding Source" for a work in object code form means all +the source code needed to generate, install, and (for an executable +work) run the object code and to modify the work, including scripts to +control those activities. However, it does not include the work's +System Libraries, or general-purpose tools or generally available free +programs which are used unmodified in performing those activities but +which are not part of the work. For example, Corresponding Source +includes interface definition files associated with source files for +the work, and the source code for shared libraries and dynamically +linked subprograms that the work is specifically designed to require, +such as by intimate data communication or control flow between those +subprograms and other parts of the work. + + The Corresponding Source need not include anything that users +can regenerate automatically from other parts of the Corresponding +Source. + + The Corresponding Source for a work in source code form is that +same work. + + 2. Basic Permissions. + + All rights granted under this License are granted for the term of +copyright on the Program, and are irrevocable provided the stated +conditions are met. This License explicitly affirms your unlimited +permission to run the unmodified Program. The output from running a +covered work is covered by this License only if the output, given its +content, constitutes a covered work. This License acknowledges your +rights of fair use or other equivalent, as provided by copyright law. + + You may make, run and propagate covered works that you do not +convey, without conditions so long as your license otherwise remains +in force. You may convey covered works to others for the sole purpose +of having them make modifications exclusively for you, or provide you +with facilities for running those works, provided that you comply with +the terms of this License in conveying all material for which you do +not control copyright. Those thus making or running the covered works +for you must do so exclusively on your behalf, under your direction +and control, on terms that prohibit them from making any copies of +your copyrighted material outside their relationship with you. + + Conveying under any other circumstances is permitted solely under +the conditions stated below. Sublicensing is not allowed; section 10 +makes it unnecessary. + + 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + + No covered work shall be deemed part of an effective technological +measure under any applicable law fulfilling obligations under article +11 of the WIPO copyright treaty adopted on 20 December 1996, or +similar laws prohibiting or restricting circumvention of such +measures. + + When you convey a covered work, you waive any legal power to forbid +circumvention of technological measures to the extent such circumvention +is effected by exercising rights under this License with respect to +the covered work, and you disclaim any intention to limit operation or +modification of the work as a means of enforcing, against the work's +users, your or third parties' legal rights to forbid circumvention of +technological measures. + + 4. Conveying Verbatim Copies. + + You may convey verbatim copies of the Program's source code as you +receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice; +keep intact all notices stating that this License and any +non-permissive terms added in accord with section 7 apply to the code; +keep intact all notices of the absence of any warranty; and give all +recipients a copy of this License along with the Program. + + You may charge any price or no price for each copy that you convey, +and you may offer support or warranty protection for a fee. + + 5. Conveying Modified Source Versions. + + You may convey a work based on the Program, or the modifications to +produce it from the Program, in the form of source code under the +terms of section 4, provided that you also meet all of these conditions: + + a) The work must carry prominent notices stating that you modified + it, and giving a relevant date. + + b) The work must carry prominent notices stating that it is + released under this License and any conditions added under section + 7. This requirement modifies the requirement in section 4 to + "keep intact all notices". + + c) You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable section 7 + additional terms, to the whole of the work, and all its parts, + regardless of how they are packaged. This License gives no + permission to license the work in any other way, but it does not + invalidate such permission if you have separately received it. + + d) If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has interactive + interfaces that do not display Appropriate Legal Notices, your + work need not make them do so. + + A compilation of a covered work with other separate and independent +works, which are not by their nature extensions of the covered work, +and which are not combined with it such as to form a larger program, +in or on a volume of a storage or distribution medium, is called an +"aggregate" if the compilation and its resulting copyright are not +used to limit the access or legal rights of the compilation's users +beyond what the individual works permit. Inclusion of a covered work +in an aggregate does not cause this License to apply to the other +parts of the aggregate. + + 6. Conveying Non-Source Forms. + + You may convey a covered work in object code form under the terms +of sections 4 and 5, provided that you also convey the +machine-readable Corresponding Source under the terms of this License, +in one of these ways: + + a) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + + b) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for as + long as you offer spare parts or customer support for that product + model, to give anyone who possesses the object code either (1) a + copy of the Corresponding Source for all the software in the + product that is covered by this License, on a durable physical + medium customarily used for software interchange, for a price no + more than your reasonable cost of physically performing this + conveying of source, or (2) access to copy the + Corresponding Source from a network server at no charge. + + c) Convey individual copies of the object code with a copy of the + written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, and + only if you received the object code with such an offer, in accord + with subsection 6b. + + d) Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access to the + Corresponding Source in the same way through the same place at no + further charge. You need not require recipients to copy the + Corresponding Source along with the object code. If the place to + copy the object code is a network server, the Corresponding Source + may be on a different server (operated by you or a third party) + that supports equivalent copying facilities, provided you maintain + clear directions next to the object code saying where to find the + Corresponding Source. Regardless of what server hosts the + Corresponding Source, you remain obligated to ensure that it is + available for as long as needed to satisfy these requirements. + + e) Convey the object code using peer-to-peer transmission, provided + you inform other peers where the object code and Corresponding + Source of the work are being offered to the general public at no + charge under subsection 6d. + + A separable portion of the object code, whose source code is excluded +from the Corresponding Source as a System Library, need not be +included in conveying the object code work. + + A "User Product" is either (1) a "consumer product", which means any +tangible personal property which is normally used for personal, family, +or household purposes, or (2) anything designed or sold for incorporation +into a dwelling. In determining whether a product is a consumer product, +doubtful cases shall be resolved in favor of coverage. For a particular +product received by a particular user, "normally used" refers to a +typical or common use of that class of product, regardless of the status +of the particular user or of the way in which the particular user +actually uses, or expects or is expected to use, the product. A product +is a consumer product regardless of whether the product has substantial +commercial, industrial or non-consumer uses, unless such uses represent +the only significant mode of use of the product. + + "Installation Information" for a User Product means any methods, +procedures, authorization keys, or other information required to install +and execute modified versions of a covered work in that User Product from +a modified version of its Corresponding Source. The information must +suffice to ensure that the continued functioning of the modified object +code is in no case prevented or interfered with solely because +modification has been made. + + If you convey an object code work under this section in, or with, or +specifically for use in, a User Product, and the conveying occurs as +part of a transaction in which the right of possession and use of the +User Product is transferred to the recipient in perpetuity or for a +fixed term (regardless of how the transaction is characterized), the +Corresponding Source conveyed under this section must be accompanied +by the Installation Information. But this requirement does not apply +if neither you nor any third party retains the ability to install +modified object code on the User Product (for example, the work has +been installed in ROM). + + The requirement to provide Installation Information does not include a +requirement to continue to provide support service, warranty, or updates +for a work that has been modified or installed by the recipient, or for +the User Product in which it has been modified or installed. Access to a +network may be denied when the modification itself materially and +adversely affects the operation of the network or violates the rules and +protocols for communication across the network. + + Corresponding Source conveyed, and Installation Information provided, +in accord with this section must be in a format that is publicly +documented (and with an implementation available to the public in +source code form), and must require no special password or key for +unpacking, reading or copying. + + 7. Additional Terms. + + "Additional permissions" are terms that supplement the terms of this +License by making exceptions from one or more of its conditions. +Additional permissions that are applicable to the entire Program shall +be treated as though they were included in this License, to the extent +that they are valid under applicable law. If additional permissions +apply only to part of the Program, that part may be used separately +under those permissions, but the entire Program remains governed by +this License without regard to the additional permissions. + + When you convey a copy of a covered work, you may at your option +remove any additional permissions from that copy, or from any part of +it. (Additional permissions may be written to require their own +removal in certain cases when you modify the work.) You may place +additional permissions on material, added by you to a covered work, +for which you have or can give appropriate copyright permission. + + Notwithstanding any other provision of this License, for material you +add to a covered work, you may (if authorized by the copyright holders of +that material) supplement the terms of this License with terms: + + a) Disclaiming warranty or limiting liability differently from the + terms of sections 15 and 16 of this License; or + + b) Requiring preservation of specified reasonable legal notices or + author attributions in that material or in the Appropriate Legal + Notices displayed by works containing it; or + + c) Prohibiting misrepresentation of the origin of that material, or + requiring that modified versions of such material be marked in + reasonable ways as different from the original version; or + + d) Limiting the use for publicity purposes of names of licensors or + authors of the material; or + + e) Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + + f) Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified versions of + it) with contractual assumptions of liability to the recipient, for + any liability that these contractual assumptions directly impose on + those licensors and authors. + + All other non-permissive additional terms are considered "further +restrictions" within the meaning of section 10. If the Program as you +received it, or any part of it, contains a notice stating that it is +governed by this License along with a term that is a further +restriction, you may remove that term. If a license document contains +a further restriction but permits relicensing or conveying under this +License, you may add to a covered work material governed by the terms +of that license document, provided that the further restriction does +not survive such relicensing or conveying. + + If you add terms to a covered work in accord with this section, you +must place, in the relevant source files, a statement of the +additional terms that apply to those files, or a notice indicating +where to find the applicable terms. + + Additional terms, permissive or non-permissive, may be stated in the +form of a separately written license, or stated as exceptions; +the above requirements apply either way. + + 8. Termination. + + You may not propagate or modify a covered work except as expressly +provided under this License. Any attempt otherwise to propagate or +modify it is void, and will automatically terminate your rights under +this License (including any patent licenses granted under the third +paragraph of section 11). + + However, if you cease all violation of this License, then your +license from a particular copyright holder is reinstated (a) +provisionally, unless and until the copyright holder explicitly and +finally terminates your license, and (b) permanently, if the copyright +holder fails to notify you of the violation by some reasonable means +prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + + Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, you do not qualify to receive new licenses for the same +material under section 10. + + 9. Acceptance Not Required for Having Copies. + + You are not required to accept this License in order to receive or +run a copy of the Program. Ancillary propagation of a covered work +occurring solely as a consequence of using peer-to-peer transmission +to receive a copy likewise does not require acceptance. However, +nothing other than this License grants you permission to propagate or +modify any covered work. These actions infringe copyright if you do +not accept this License. Therefore, by modifying or propagating a +covered work, you indicate your acceptance of this License to do so. + + 10. Automatic Licensing of Downstream Recipients. + + Each time you convey a covered work, the recipient automatically +receives a license from the original licensors, to run, modify and +propagate that work, subject to this License. You are not responsible +for enforcing compliance by third parties with this License. + + An "entity transaction" is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an +organization, or merging organizations. If propagation of a covered +work results from an entity transaction, each party to that +transaction who receives a copy of the work also receives whatever +licenses to the work the party's predecessor in interest had or could +give under the previous paragraph, plus a right to possession of the +Corresponding Source of the work from the predecessor in interest, if +the predecessor has it or can get it with reasonable efforts. + + You may not impose any further restrictions on the exercise of the +rights granted or affirmed under this License. For example, you may +not impose a license fee, royalty, or other charge for exercise of +rights granted under this License, and you may not initiate litigation +(including a cross-claim or counterclaim in a lawsuit) alleging that +any patent claim is infringed by making, using, selling, offering for +sale, or importing the Program or any portion of it. + + 11. Patents. + + A "contributor" is a copyright holder who authorizes use under this +License of the Program or a work on which the Program is based. The +work thus licensed is called the contributor's "contributor version". + + A contributor's "essential patent claims" are all patent claims +owned or controlled by the contributor, whether already acquired or +hereafter acquired, that would be infringed by some manner, permitted +by this License, of making, using, or selling its contributor version, +but do not include claims that would be infringed only as a +consequence of further modification of the contributor version. For +purposes of this definition, "control" includes the right to grant +patent sublicenses in a manner consistent with the requirements of +this License. + + Each contributor grants you a non-exclusive, worldwide, royalty-free +patent license under the contributor's essential patent claims, to +make, use, sell, offer for sale, import and otherwise run, modify and +propagate the contents of its contributor version. + + In the following three paragraphs, a "patent license" is any express +agreement or commitment, however denominated, not to enforce a patent +(such as an express permission to practice a patent or covenant not to +sue for patent infringement). To "grant" such a patent license to a +party means to make such an agreement or commitment not to enforce a +patent against the party. + + If you convey a covered work, knowingly relying on a patent license, +and the Corresponding Source of the work is not available for anyone +to copy, free of charge and under the terms of this License, through a +publicly available network server or other readily accessible means, +then you must either (1) cause the Corresponding Source to be so +available, or (2) arrange to deprive yourself of the benefit of the +patent license for this particular work, or (3) arrange, in a manner +consistent with the requirements of this License, to extend the patent +license to downstream recipients. "Knowingly relying" means you have +actual knowledge that, but for the patent license, your conveying the +covered work in a country, or your recipient's use of the covered work +in a country, would infringe one or more identifiable patents in that +country that you have reason to believe are valid. + + If, pursuant to or in connection with a single transaction or +arrangement, you convey, or propagate by procuring conveyance of, a +covered work, and grant a patent license to some of the parties +receiving the covered work authorizing them to use, propagate, modify +or convey a specific copy of the covered work, then the patent license +you grant is automatically extended to all recipients of the covered +work and works based on it. + + A patent license is "discriminatory" if it does not include within +the scope of its coverage, prohibits the exercise of, or is +conditioned on the non-exercise of one or more of the rights that are +specifically granted under this License. You may not convey a covered +work if you are a party to an arrangement with a third party that is +in the business of distributing software, under which you make payment +to the third party based on the extent of your activity of conveying +the work, and under which the third party grants, to any of the +parties who would receive the covered work from you, a discriminatory +patent license (a) in connection with copies of the covered work +conveyed by you (or copies made from those copies), or (b) primarily +for and in connection with specific products or compilations that +contain the covered work, unless you entered into that arrangement, +or that patent license was granted, prior to 28 March 2007. + + Nothing in this License shall be construed as excluding or limiting +any implied license or other defenses to infringement that may +otherwise be available to you under applicable patent law. + + 12. No Surrender of Others' Freedom. + + If conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot convey a +covered work so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you may +not convey it at all. For example, if you agree to terms that obligate you +to collect a royalty for further conveying from those to whom you convey +the Program, the only way you could satisfy both those terms and this +License would be to refrain entirely from conveying the Program. + + 13. Remote Network Interaction; Use with the GNU General Public License. + + Notwithstanding any other provision of this License, if you modify the +Program, your modified version must prominently offer all users +interacting with it remotely through a computer network (if your version +supports such interaction) an opportunity to receive the Corresponding +Source of your version by providing access to the Corresponding Source +from a network server at no charge, through some standard or customary +means of facilitating copying of software. This Corresponding Source +shall include the Corresponding Source for any work covered by version 3 +of the GNU General Public License that is incorporated pursuant to the +following paragraph. + + Notwithstanding any other provision of this License, you have +permission to link or combine any covered work with a work licensed +under version 3 of the GNU General Public License into a single +combined work, and to convey the resulting work. The terms of this +License will continue to apply to the part which is the covered work, +but the work with which it is combined will remain governed by version +3 of the GNU General Public License. + + 14. Revised Versions of this License. + + The Free Software Foundation may publish revised and/or new versions of +the GNU Affero General Public License from time to time. Such new versions +will be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + + Each version is given a distinguishing version number. If the +Program specifies that a certain numbered version of the GNU Affero General +Public License "or any later version" applies to it, you have the +option of following the terms and conditions either of that numbered +version or of any later version published by the Free Software +Foundation. If the Program does not specify a version number of the +GNU Affero General Public License, you may choose any version ever published +by the Free Software Foundation. + + If the Program specifies that a proxy can decide which future +versions of the GNU Affero General Public License can be used, that proxy's +public statement of acceptance of a version permanently authorizes you +to choose that version for the Program. + + Later license versions may give you additional or different +permissions. However, no additional obligations are imposed on any +author or copyright holder as a result of your choosing to follow a +later version. + + 15. Disclaimer of Warranty. + + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY +APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT +HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY +OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, +THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM +IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF +ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. Limitation of Liability. + + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS +THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY +GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE +USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF +DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD +PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), +EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF +SUCH DAMAGES. + + 17. Interpretation of Sections 15 and 16. + + If the disclaimer of warranty and limitation of liability provided +above cannot be given local legal effect according to their terms, +reviewing courts shall apply local law that most closely approximates +an absolute waiver of all civil liability in connection with the +Program, unless a warranty or assumption of liability accompanies a +copy of the Program in return for a fee. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +state the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU Affero General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License + along with this program. If not, see . + +Also add information on how to contact you by electronic and paper mail. + + If your software can interact with users remotely through a computer +network, you should also make sure that it provides a way for users to +get its source. For example, if your program is a web application, its +interface could display a "Source" link that leads users to an archive +of the code. There are many ways you could offer source, and different +solutions will be better for different programs; see section 13 for the +specific requirements. + + You should also get your employer (if you work as a programmer) or school, +if any, to sign a "copyright disclaimer" for the program, if necessary. +For more information on this, and how to apply and follow the GNU AGPL, see +. diff --git a/MANIFEST.in b/MANIFEST.in new file mode 100644 index 0000000..a70ad0d --- /dev/null +++ b/MANIFEST.in @@ -0,0 +1,10 @@ +include *.md +include requirements.txt +include LICENSE +include setup.py +include ultralytics/assets/bus.jpg +include ultralytics/assets/zidane.jpg +include tests/*.py +recursive-include ultralytics *.yaml +recursive-include ultralytics/cfg/datasets *.yaml +recursive-exclude __pycache__ * diff --git a/README.md b/README.md new file mode 100644 index 0000000..a387dfc --- /dev/null +++ b/README.md @@ -0,0 +1,38 @@ +[![Test Build](https://github.com/rathaumons/ultralytics-for-vsensebox/actions/workflows/test_build.yaml/badge.svg)](https://github.com/rathaumons/ultralytics-for-vsensebox/actions/workflows/test_build.yaml) [![PyPI](https://github.com/rathaumons/ultralytics-for-vsensebox/actions/workflows/publish.yaml/badge.svg)](https://github.com/rathaumons/ultralytics-for-vsensebox/actions/workflows/publish.yaml) + +# Customized Ultralytics for VSenseBox + +* Updated: **May 2, 2024** +* Synced with: v8.1.48 -> [[c54b013]](https://github.com/ultralytics/ultralytics/commit/c54b013188870dafdd5ce0d78b3f5f3fdee655fd) +* All credit and info -> [[Original Ultralytics repo]](https://github.com/ultralytics/ultralytics) +* Customized for [`VSenseBox`](https://github.com/rathaumons/vsensebox): + - Enable OpenCV multithreading + - Remove restrictions on customized OpenCV + - Disable dependency auto-install + - Disable auto update + +## Installation + +* Install from [PyPI](https://pypi.org/project/vsensebox-ultralytics/): + ``` + pip install vsensebox-ultralytics + ``` +* Or install from GitHub directly: + ``` + pip install git+https://github.com/rathaumons/ultralytics-for-vsensebox.git + ``` +* Or build from source: + +
Click here to expand! + + ``` + git clone https://github.com/rathaumons/ultralytics-for-vsensebox.git + cd ultralytics-for-vsensebox + python -m pip install --upgrade pip + python -m pip install -U pip setuptools + pip install wheel build + python -m build --wheel --skip-dependency-check --no-isolatio + cd dist + ``` + +
diff --git a/create_whl.cmd b/create_whl.cmd new file mode 100644 index 0000000..3a25f79 --- /dev/null +++ b/create_whl.cmd @@ -0,0 +1,14 @@ +:: VSenseBox - Python toolbox for visual sensing +:: GNU General Public License v3 or later (GPLv3+) +:: Copyright (C) 2024 UMONS-Numediart + + +@echo off +setlocal +cd /d %~dp0 +set "PYTHONWARNINGS=ignore" +python -m pip install --upgrade pip +python -m pip install -U pip setuptools +pip install wheel build +python -m build --wheel --skip-dependency-check --no-isolation +pause diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..42c3bd5 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,36 @@ +## Ultralytics YOLOv8 Example Applications + +This repository features a collection of real-world applications and walkthroughs, provided as either Python files or notebooks. Explore the examples below to see how YOLOv8 can be integrated into various applications. + +### Ultralytics YOLO Example Applications + +| Title | Format | Contributor | +| ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------- | +| [YOLO ONNX Detection Inference with C++](./YOLOv8-CPP-Inference) | C++/ONNX | [Justas Bartnykas](https://github.com/JustasBart) | +| [YOLO OpenCV ONNX Detection Python](./YOLOv8-OpenCV-ONNX-Python) | OpenCV/Python/ONNX | [Farid Inawan](https://github.com/frdteknikelektro) | +| [YOLOv8 .NET ONNX ImageSharp](https://github.com/dme-compunet/YOLOv8) | C#/ONNX/ImageSharp | [Compunet](https://github.com/dme-compunet) | +| [YOLO .Net ONNX Detection C#](https://www.nuget.org/packages/Yolov8.Net) | C# .Net | [Samuel Stainback](https://github.com/sstainba) | +| [YOLOv8 on NVIDIA Jetson(TensorRT and DeepStream)](https://wiki.seeedstudio.com/YOLOv8-DeepStream-TRT-Jetson/) | Python | [Lakshantha](https://github.com/lakshanthad) | +| [YOLOv8 ONNXRuntime Python](./YOLOv8-ONNXRuntime) | Python/ONNXRuntime | [Semih Demirel](https://github.com/semihhdemirel) | +| [YOLOv8 ONNXRuntime CPP](./YOLOv8-ONNXRuntime-CPP) | C++/ONNXRuntime | [DennisJcy](https://github.com/DennisJcy), [Onuralp Sezer](https://github.com/onuralpszr) | +| [RTDETR ONNXRuntime C#](https://github.com/Kayzwer/yolo-cs/blob/master/RTDETR.cs) | C#/ONNX | [Kayzwer](https://github.com/Kayzwer) | +| [YOLOv8 SAHI Video Inference](https://github.com/RizwanMunawar/ultralytics/blob/main/examples/YOLOv8-SAHI-Inference-Video/yolov8_sahi.py) | Python | [Muhammad Rizwan Munawar](https://github.com/RizwanMunawar) | +| [YOLOv8 Region Counter](https://github.com/RizwanMunawar/ultralytics/blob/main/examples/YOLOv8-Region-Counter/yolov8_region_counter.py) | Python | [Muhammad Rizwan Munawar](https://github.com/RizwanMunawar) | +| [YOLOv8 Segmentation ONNXRuntime Python](./YOLOv8-Segmentation-ONNXRuntime-Python) | Python/ONNXRuntime | [jamjamjon](https://github.com/jamjamjon) | +| [YOLOv8 LibTorch CPP](./YOLOv8-LibTorch-CPP-Inference) | C++/LibTorch | [Myyura](https://github.com/Myyura) | +| [YOLOv8 OpenCV INT8 TFLite Python](./YOLOv8-OpenCV-int8-tflite-Python) | Python | [Wamiq Raza](https://github.com/wamiqraza) | + +### How to Contribute + +We greatly appreciate contributions from the community, including examples, applications, and guides. If you'd like to contribute, please follow these guidelines: + +1. Create a pull request (PR) with the title prefix `[Example]`, adding your new example folder to the `examples/` directory within the repository. +2. Make sure your project adheres to the following standards: + - Makes use of the `ultralytics` package. + - Includes a `README.md` with clear instructions for setting up and running the example. + - Refrains from adding large files or dependencies unless they are absolutely necessary for the example. + - Contributors should be willing to provide support for their examples and address related issues. + +For more detailed information and guidance on contributing, please visit our [contribution documentation](https://docs.ultralytics.com/help/contributing). + +If you encounter any questions or concerns regarding these guidelines, feel free to open a PR or an issue in the repository, and we will assist you in the contribution process. diff --git a/examples/YOLOv8-CPP-Inference/CMakeLists.txt b/examples/YOLOv8-CPP-Inference/CMakeLists.txt new file mode 100644 index 0000000..bc2f33f --- /dev/null +++ b/examples/YOLOv8-CPP-Inference/CMakeLists.txt @@ -0,0 +1,28 @@ +cmake_minimum_required(VERSION 3.5) + +project(Yolov8CPPInference VERSION 0.1) + +set(CMAKE_INCLUDE_CURRENT_DIR ON) + +# CUDA +set(CUDA_TOOLKIT_ROOT_DIR "/usr/local/cuda") +find_package(CUDA 11 REQUIRED) + +set(CMAKE_CUDA_STANDARD 11) +set(CMAKE_CUDA_STANDARD_REQUIRED ON) +# !CUDA + +# OpenCV +find_package(OpenCV REQUIRED) +include_directories(${OpenCV_INCLUDE_DIRS}) +# !OpenCV + +set(PROJECT_SOURCES + main.cpp + + inference.h + inference.cpp +) + +add_executable(Yolov8CPPInference ${PROJECT_SOURCES}) +target_link_libraries(Yolov8CPPInference ${OpenCV_LIBS}) diff --git a/examples/YOLOv8-CPP-Inference/README.md b/examples/YOLOv8-CPP-Inference/README.md new file mode 100644 index 0000000..601c1d0 --- /dev/null +++ b/examples/YOLOv8-CPP-Inference/README.md @@ -0,0 +1,50 @@ +# YOLOv8/YOLOv5 Inference C++ + +This example demonstrates how to perform inference using YOLOv8 and YOLOv5 models in C++ with OpenCV's DNN API. + +## Usage + +```bash +git clone ultralytics +cd ultralytics +pip install . +cd examples/YOLOv8-CPP-Inference + +# Add a **yolov8\_.onnx** and/or **yolov5\_.onnx** model(s) to the ultralytics folder. +# Edit the **main.cpp** to change the **projectBasePath** to match your user. + +# Note that by default the CMake file will try and import the CUDA library to be used with the OpenCVs dnn (cuDNN) GPU Inference. +# If your OpenCV build does not use CUDA/cuDNN you can remove that import call and run the example on CPU. + +mkdir build +cd build +cmake .. +make +./Yolov8CPPInference +``` + +## Exporting YOLOv8 and YOLOv5 Models + +To export YOLOv8 models: + +```commandline +yolo export model=yolov8s.pt imgsz=480,640 format=onnx opset=12 +``` + +To export YOLOv5 models: + +```commandline +python3 export.py --weights yolov5s.pt --img 480 640 --include onnx --opset 12 +``` + +yolov8s.onnx: + +![image](https://user-images.githubusercontent.com/40023722/217356132-a4cecf2e-2729-4acb-b80a-6559022d7707.png) + +yolov5s.onnx: + +![image](https://user-images.githubusercontent.com/40023722/217357005-07464492-d1da-42e3-98a7-fc753f87d5e6.png) + +This repository utilizes OpenCV's DNN API to run ONNX exported models of YOLOv5 and YOLOv8. In theory, it should work for YOLOv6 and YOLOv7 as well, but they have not been tested. Note that the example networks are exported with rectangular (640x480) resolutions, but any exported resolution will work. You may want to use the letterbox approach for square images, depending on your use case. + +The **main** branch version uses Qt as a GUI wrapper. The primary focus here is the **Inference** class file, which demonstrates how to transpose YOLOv8 models to work as YOLOv5 models. diff --git a/examples/YOLOv8-CPP-Inference/inference.cpp b/examples/YOLOv8-CPP-Inference/inference.cpp new file mode 100644 index 0000000..12c2607 --- /dev/null +++ b/examples/YOLOv8-CPP-Inference/inference.cpp @@ -0,0 +1,185 @@ +#include "inference.h" + +Inference::Inference(const std::string &onnxModelPath, const cv::Size &modelInputShape, const std::string &classesTxtFile, const bool &runWithCuda) +{ + modelPath = onnxModelPath; + modelShape = modelInputShape; + classesPath = classesTxtFile; + cudaEnabled = runWithCuda; + + loadOnnxNetwork(); + // loadClassesFromFile(); The classes are hard-coded for this example +} + +std::vector Inference::runInference(const cv::Mat &input) +{ + cv::Mat modelInput = input; + if (letterBoxForSquare && modelShape.width == modelShape.height) + modelInput = formatToSquare(modelInput); + + cv::Mat blob; + cv::dnn::blobFromImage(modelInput, blob, 1.0/255.0, modelShape, cv::Scalar(), true, false); + net.setInput(blob); + + std::vector outputs; + net.forward(outputs, net.getUnconnectedOutLayersNames()); + + int rows = outputs[0].size[1]; + int dimensions = outputs[0].size[2]; + + bool yolov8 = false; + // yolov5 has an output of shape (batchSize, 25200, 85) (Num classes + box[x,y,w,h] + confidence[c]) + // yolov8 has an output of shape (batchSize, 84, 8400) (Num classes + box[x,y,w,h]) + if (dimensions > rows) // Check if the shape[2] is more than shape[1] (yolov8) + { + yolov8 = true; + rows = outputs[0].size[2]; + dimensions = outputs[0].size[1]; + + outputs[0] = outputs[0].reshape(1, dimensions); + cv::transpose(outputs[0], outputs[0]); + } + float *data = (float *)outputs[0].data; + + float x_factor = modelInput.cols / modelShape.width; + float y_factor = modelInput.rows / modelShape.height; + + std::vector class_ids; + std::vector confidences; + std::vector boxes; + + for (int i = 0; i < rows; ++i) + { + if (yolov8) + { + float *classes_scores = data+4; + + cv::Mat scores(1, classes.size(), CV_32FC1, classes_scores); + cv::Point class_id; + double maxClassScore; + + minMaxLoc(scores, 0, &maxClassScore, 0, &class_id); + + if (maxClassScore > modelScoreThreshold) + { + confidences.push_back(maxClassScore); + class_ids.push_back(class_id.x); + + float x = data[0]; + float y = data[1]; + float w = data[2]; + float h = data[3]; + + int left = int((x - 0.5 * w) * x_factor); + int top = int((y - 0.5 * h) * y_factor); + + int width = int(w * x_factor); + int height = int(h * y_factor); + + boxes.push_back(cv::Rect(left, top, width, height)); + } + } + else // yolov5 + { + float confidence = data[4]; + + if (confidence >= modelConfidenceThreshold) + { + float *classes_scores = data+5; + + cv::Mat scores(1, classes.size(), CV_32FC1, classes_scores); + cv::Point class_id; + double max_class_score; + + minMaxLoc(scores, 0, &max_class_score, 0, &class_id); + + if (max_class_score > modelScoreThreshold) + { + confidences.push_back(confidence); + class_ids.push_back(class_id.x); + + float x = data[0]; + float y = data[1]; + float w = data[2]; + float h = data[3]; + + int left = int((x - 0.5 * w) * x_factor); + int top = int((y - 0.5 * h) * y_factor); + + int width = int(w * x_factor); + int height = int(h * y_factor); + + boxes.push_back(cv::Rect(left, top, width, height)); + } + } + } + + data += dimensions; + } + + std::vector nms_result; + cv::dnn::NMSBoxes(boxes, confidences, modelScoreThreshold, modelNMSThreshold, nms_result); + + std::vector detections{}; + for (unsigned long i = 0; i < nms_result.size(); ++i) + { + int idx = nms_result[i]; + + Detection result; + result.class_id = class_ids[idx]; + result.confidence = confidences[idx]; + + std::random_device rd; + std::mt19937 gen(rd()); + std::uniform_int_distribution dis(100, 255); + result.color = cv::Scalar(dis(gen), + dis(gen), + dis(gen)); + + result.className = classes[result.class_id]; + result.box = boxes[idx]; + + detections.push_back(result); + } + + return detections; +} + +void Inference::loadClassesFromFile() +{ + std::ifstream inputFile(classesPath); + if (inputFile.is_open()) + { + std::string classLine; + while (std::getline(inputFile, classLine)) + classes.push_back(classLine); + inputFile.close(); + } +} + +void Inference::loadOnnxNetwork() +{ + net = cv::dnn::readNetFromONNX(modelPath); + if (cudaEnabled) + { + std::cout << "\nRunning on CUDA" << std::endl; + net.setPreferableBackend(cv::dnn::DNN_BACKEND_CUDA); + net.setPreferableTarget(cv::dnn::DNN_TARGET_CUDA); + } + else + { + std::cout << "\nRunning on CPU" << std::endl; + net.setPreferableBackend(cv::dnn::DNN_BACKEND_OPENCV); + net.setPreferableTarget(cv::dnn::DNN_TARGET_CPU); + } +} + +cv::Mat Inference::formatToSquare(const cv::Mat &source) +{ + int col = source.cols; + int row = source.rows; + int _max = MAX(col, row); + cv::Mat result = cv::Mat::zeros(_max, _max, CV_8UC3); + source.copyTo(result(cv::Rect(0, 0, col, row))); + return result; +} diff --git a/examples/YOLOv8-CPP-Inference/inference.h b/examples/YOLOv8-CPP-Inference/inference.h new file mode 100644 index 0000000..dc6149f --- /dev/null +++ b/examples/YOLOv8-CPP-Inference/inference.h @@ -0,0 +1,52 @@ +#ifndef INFERENCE_H +#define INFERENCE_H + +// Cpp native +#include +#include +#include +#include + +// OpenCV / DNN / Inference +#include +#include +#include + +struct Detection +{ + int class_id{0}; + std::string className{}; + float confidence{0.0}; + cv::Scalar color{}; + cv::Rect box{}; +}; + +class Inference +{ +public: + Inference(const std::string &onnxModelPath, const cv::Size &modelInputShape = {640, 640}, const std::string &classesTxtFile = "", const bool &runWithCuda = true); + std::vector runInference(const cv::Mat &input); + +private: + void loadClassesFromFile(); + void loadOnnxNetwork(); + cv::Mat formatToSquare(const cv::Mat &source); + + std::string modelPath{}; + std::string classesPath{}; + bool cudaEnabled{}; + + std::vector classes{"person", "bicycle", "car", "motorcycle", "airplane", "bus", "train", "truck", "boat", "traffic light", "fire hydrant", "stop sign", "parking meter", "bench", "bird", "cat", "dog", "horse", "sheep", "cow", "elephant", "bear", "zebra", "giraffe", "backpack", "umbrella", "handbag", "tie", "suitcase", "frisbee", "skis", "snowboard", "sports ball", "kite", "baseball bat", "baseball glove", "skateboard", "surfboard", "tennis racket", "bottle", "wine glass", "cup", "fork", "knife", "spoon", "bowl", "banana", "apple", "sandwich", "orange", "broccoli", "carrot", "hot dog", "pizza", "donut", "cake", "chair", "couch", "potted plant", "bed", "dining table", "toilet", "tv", "laptop", "mouse", "remote", "keyboard", "cell phone", "microwave", "oven", "toaster", "sink", "refrigerator", "book", "clock", "vase", "scissors", "teddy bear", "hair drier", "toothbrush"}; + + cv::Size2f modelShape{}; + + float modelConfidenceThreshold {0.25}; + float modelScoreThreshold {0.45}; + float modelNMSThreshold {0.50}; + + bool letterBoxForSquare = true; + + cv::dnn::Net net; +}; + +#endif // INFERENCE_H diff --git a/examples/YOLOv8-CPP-Inference/main.cpp b/examples/YOLOv8-CPP-Inference/main.cpp new file mode 100644 index 0000000..6d1ba98 --- /dev/null +++ b/examples/YOLOv8-CPP-Inference/main.cpp @@ -0,0 +1,70 @@ +#include +#include +#include + +#include + +#include "inference.h" + +using namespace std; +using namespace cv; + +int main(int argc, char **argv) +{ + std::string projectBasePath = "/home/user/ultralytics"; // Set your ultralytics base path + + bool runOnGPU = true; + + // + // Pass in either: + // + // "yolov8s.onnx" or "yolov5s.onnx" + // + // To run Inference with yolov8/yolov5 (ONNX) + // + + // Note that in this example the classes are hard-coded and 'classes.txt' is a place holder. + Inference inf(projectBasePath + "/yolov8s.onnx", cv::Size(640, 480), "classes.txt", runOnGPU); + + std::vector imageNames; + imageNames.push_back(projectBasePath + "/ultralytics/assets/bus.jpg"); + imageNames.push_back(projectBasePath + "/ultralytics/assets/zidane.jpg"); + + for (int i = 0; i < imageNames.size(); ++i) + { + cv::Mat frame = cv::imread(imageNames[i]); + + // Inference starts here... + std::vector output = inf.runInference(frame); + + int detections = output.size(); + std::cout << "Number of detections:" << detections << std::endl; + + for (int i = 0; i < detections; ++i) + { + Detection detection = output[i]; + + cv::Rect box = detection.box; + cv::Scalar color = detection.color; + + // Detection box + cv::rectangle(frame, box, color, 2); + + // Detection box text + std::string classString = detection.className + ' ' + std::to_string(detection.confidence).substr(0, 4); + cv::Size textSize = cv::getTextSize(classString, cv::FONT_HERSHEY_DUPLEX, 1, 2, 0); + cv::Rect textBox(box.x, box.y - 40, textSize.width + 10, textSize.height + 20); + + cv::rectangle(frame, textBox, color, cv::FILLED); + cv::putText(frame, classString, cv::Point(box.x + 5, box.y - 10), cv::FONT_HERSHEY_DUPLEX, 1, cv::Scalar(0, 0, 0), 2, 0); + } + // Inference ends here... + + // This is only for preview purposes + float scale = 0.8; + cv::resize(frame, frame, cv::Size(frame.cols*scale, frame.rows*scale)); + cv::imshow("Inference", frame); + + cv::waitKey(-1); + } +} diff --git a/examples/YOLOv8-LibTorch-CPP-Inference/CMakeLists.txt b/examples/YOLOv8-LibTorch-CPP-Inference/CMakeLists.txt new file mode 100644 index 0000000..2cbd796 --- /dev/null +++ b/examples/YOLOv8-LibTorch-CPP-Inference/CMakeLists.txt @@ -0,0 +1,47 @@ +cmake_minimum_required(VERSION 3.18 FATAL_ERROR) + +project(yolov8_libtorch_example) + +set(CMAKE_CXX_STANDARD 17) +set(CMAKE_CXX_STANDARD_REQUIRED ON) +set(CMAKE_CXX_EXTENSIONS OFF) + + +# -------------- OpenCV -------------- +set(OpenCV_DIR "/path/to/opencv/lib/cmake/opencv4") +find_package(OpenCV REQUIRED) + +message(STATUS "OpenCV library status:") +message(STATUS " config: ${OpenCV_DIR}") +message(STATUS " version: ${OpenCV_VERSION}") +message(STATUS " libraries: ${OpenCV_LIBS}") +message(STATUS " include path: ${OpenCV_INCLUDE_DIRS}") + +include_directories(${OpenCV_INCLUDE_DIRS}) + +# -------------- libtorch -------------- +list(APPEND CMAKE_PREFIX_PATH "/path/to/libtorch") +set(Torch_DIR "/path/to/libtorch/share/cmake/Torch") + +find_package(Torch REQUIRED) +set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${TORCH_CXX_FLAGS}") +message("${TORCH_LIBRARIES}") +message("${TORCH_INCLUDE_DIRS}") + +# The following code block is suggested to be used on Windows. +# According to https://github.com/pytorch/pytorch/issues/25457, +# the DLLs need to be copied to avoid memory errors. +# if (MSVC) +# file(GLOB TORCH_DLLS "${TORCH_INSTALL_PREFIX}/lib/*.dll") +# add_custom_command(TARGET yolov8_libtorch_example +# POST_BUILD +# COMMAND ${CMAKE_COMMAND} -E copy_if_different +# ${TORCH_DLLS} +# $) +# endif (MSVC) + +include_directories(${TORCH_INCLUDE_DIRS}) + +add_executable(yolov8_libtorch_inference "${CMAKE_CURRENT_SOURCE_DIR}/main.cc") +target_link_libraries(yolov8_libtorch_inference ${TORCH_LIBRARIES} ${OpenCV_LIBS}) +set_property(TARGET yolov8_libtorch_inference PROPERTY CXX_STANDARD 17) diff --git a/examples/YOLOv8-LibTorch-CPP-Inference/README.md b/examples/YOLOv8-LibTorch-CPP-Inference/README.md new file mode 100644 index 0000000..930c3cd --- /dev/null +++ b/examples/YOLOv8-LibTorch-CPP-Inference/README.md @@ -0,0 +1,35 @@ +# YOLOv8 LibTorch Inference C++ + +This example demonstrates how to perform inference using YOLOv8 models in C++ with LibTorch API. + +## Dependencies + +| Dependency | Version | +| ------------ | -------- | +| OpenCV | >=4.0.0 | +| C++ Standard | >=17 | +| Cmake | >=3.18 | +| Libtorch | >=1.12.1 | + +## Usage + +```bash +git clone ultralytics +cd ultralytics +pip install . +cd examples/YOLOv8-LibTorch-CPP-Inference + +mkdir build +cd build +cmake .. +make +./yolov8_libtorch_inference +``` + +## Exporting YOLOv8 + +To export YOLOv8 models: + +```commandline +yolo export model=yolov8s.pt imgsz=640 format=torchscript +``` diff --git a/examples/YOLOv8-LibTorch-CPP-Inference/main.cc b/examples/YOLOv8-LibTorch-CPP-Inference/main.cc new file mode 100644 index 0000000..b68b7f7 --- /dev/null +++ b/examples/YOLOv8-LibTorch-CPP-Inference/main.cc @@ -0,0 +1,259 @@ +#include + +#include +#include +#include +#include +#include + +using torch::indexing::Slice; +using torch::indexing::None; + + +float generate_scale(cv::Mat& image, const std::vector& target_size) { + int origin_w = image.cols; + int origin_h = image.rows; + + int target_h = target_size[0]; + int target_w = target_size[1]; + + float ratio_h = static_cast(target_h) / static_cast(origin_h); + float ratio_w = static_cast(target_w) / static_cast(origin_w); + float resize_scale = std::min(ratio_h, ratio_w); + return resize_scale; +} + + +float letterbox(cv::Mat &input_image, cv::Mat &output_image, const std::vector &target_size) { + if (input_image.cols == target_size[1] && input_image.rows == target_size[0]) { + if (input_image.data == output_image.data) { + return 1.; + } else { + output_image = input_image.clone(); + return 1.; + } + } + + float resize_scale = generate_scale(input_image, target_size); + int new_shape_w = std::round(input_image.cols * resize_scale); + int new_shape_h = std::round(input_image.rows * resize_scale); + float padw = (target_size[1] - new_shape_w) / 2.; + float padh = (target_size[0] - new_shape_h) / 2.; + + int top = std::round(padh - 0.1); + int bottom = std::round(padh + 0.1); + int left = std::round(padw - 0.1); + int right = std::round(padw + 0.1); + + cv::resize(input_image, output_image, + cv::Size(new_shape_w, new_shape_h), + 0, 0, cv::INTER_AREA); + + cv::copyMakeBorder(output_image, output_image, top, bottom, left, right, + cv::BORDER_CONSTANT, cv::Scalar(114.)); + return resize_scale; +} + + +torch::Tensor xyxy2xywh(const torch::Tensor& x) { + auto y = torch::empty_like(x); + y.index_put_({"...", 0}, (x.index({"...", 0}) + x.index({"...", 2})).div(2)); + y.index_put_({"...", 1}, (x.index({"...", 1}) + x.index({"...", 3})).div(2)); + y.index_put_({"...", 2}, x.index({"...", 2}) - x.index({"...", 0})); + y.index_put_({"...", 3}, x.index({"...", 3}) - x.index({"...", 1})); + return y; +} + + +torch::Tensor xywh2xyxy(const torch::Tensor& x) { + auto y = torch::empty_like(x); + auto dw = x.index({"...", 2}).div(2); + auto dh = x.index({"...", 3}).div(2); + y.index_put_({"...", 0}, x.index({"...", 0}) - dw); + y.index_put_({"...", 1}, x.index({"...", 1}) - dh); + y.index_put_({"...", 2}, x.index({"...", 0}) + dw); + y.index_put_({"...", 3}, x.index({"...", 1}) + dh); + return y; +} + + +// Reference: https://github.com/pytorch/vision/blob/main/torchvision/csrc/ops/cpu/nms_kernel.cpp +torch::Tensor nms(const torch::Tensor& bboxes, const torch::Tensor& scores, float iou_threshold) { + if (bboxes.numel() == 0) + return torch::empty({0}, bboxes.options().dtype(torch::kLong)); + + auto x1_t = bboxes.select(1, 0).contiguous(); + auto y1_t = bboxes.select(1, 1).contiguous(); + auto x2_t = bboxes.select(1, 2).contiguous(); + auto y2_t = bboxes.select(1, 3).contiguous(); + + torch::Tensor areas_t = (x2_t - x1_t) * (y2_t - y1_t); + + auto order_t = std::get<1>( + scores.sort(/*stable=*/true, /*dim=*/0, /* descending=*/true)); + + auto ndets = bboxes.size(0); + torch::Tensor suppressed_t = torch::zeros({ndets}, bboxes.options().dtype(torch::kByte)); + torch::Tensor keep_t = torch::zeros({ndets}, bboxes.options().dtype(torch::kLong)); + + auto suppressed = suppressed_t.data_ptr(); + auto keep = keep_t.data_ptr(); + auto order = order_t.data_ptr(); + auto x1 = x1_t.data_ptr(); + auto y1 = y1_t.data_ptr(); + auto x2 = x2_t.data_ptr(); + auto y2 = y2_t.data_ptr(); + auto areas = areas_t.data_ptr(); + + int64_t num_to_keep = 0; + + for (int64_t _i = 0; _i < ndets; _i++) { + auto i = order[_i]; + if (suppressed[i] == 1) + continue; + keep[num_to_keep++] = i; + auto ix1 = x1[i]; + auto iy1 = y1[i]; + auto ix2 = x2[i]; + auto iy2 = y2[i]; + auto iarea = areas[i]; + + for (int64_t _j = _i + 1; _j < ndets; _j++) { + auto j = order[_j]; + if (suppressed[j] == 1) + continue; + auto xx1 = std::max(ix1, x1[j]); + auto yy1 = std::max(iy1, y1[j]); + auto xx2 = std::min(ix2, x2[j]); + auto yy2 = std::min(iy2, y2[j]); + + auto w = std::max(static_cast(0), xx2 - xx1); + auto h = std::max(static_cast(0), yy2 - yy1); + auto inter = w * h; + auto ovr = inter / (iarea + areas[j] - inter); + if (ovr > iou_threshold) + suppressed[j] = 1; + } + } + return keep_t.narrow(0, 0, num_to_keep); +} + + +torch::Tensor non_max_suppression(torch::Tensor& prediction, float conf_thres = 0.25, float iou_thres = 0.45, int max_det = 300) { + auto bs = prediction.size(0); + auto nc = prediction.size(1) - 4; + auto nm = prediction.size(1) - nc - 4; + auto mi = 4 + nc; + auto xc = prediction.index({Slice(), Slice(4, mi)}).amax(1) > conf_thres; + + prediction = prediction.transpose(-1, -2); + prediction.index_put_({"...", Slice({None, 4})}, xywh2xyxy(prediction.index({"...", Slice(None, 4)}))); + + std::vector output; + for (int i = 0; i < bs; i++) { + output.push_back(torch::zeros({0, 6 + nm}, prediction.device())); + } + + for (int xi = 0; xi < prediction.size(0); xi++) { + auto x = prediction[xi]; + x = x.index({xc[xi]}); + auto x_split = x.split({4, nc, nm}, 1); + auto box = x_split[0], cls = x_split[1], mask = x_split[2]; + auto [conf, j] = cls.max(1, true); + x = torch::cat({box, conf, j.toType(torch::kFloat), mask}, 1); + x = x.index({conf.view(-1) > conf_thres}); + int n = x.size(0); + if (!n) { continue; } + + // NMS + auto c = x.index({Slice(), Slice{5, 6}}) * 7680; + auto boxes = x.index({Slice(), Slice(None, 4)}) + c; + auto scores = x.index({Slice(), 4}); + auto i = nms(boxes, scores, iou_thres); + i = i.index({Slice(None, max_det)}); + output[xi] = x.index({i}); + } + + return torch::stack(output); +} + + +torch::Tensor clip_boxes(torch::Tensor& boxes, const std::vector& shape) { + boxes.index_put_({"...", 0}, boxes.index({"...", 0}).clamp(0, shape[1])); + boxes.index_put_({"...", 1}, boxes.index({"...", 1}).clamp(0, shape[0])); + boxes.index_put_({"...", 2}, boxes.index({"...", 2}).clamp(0, shape[1])); + boxes.index_put_({"...", 3}, boxes.index({"...", 3}).clamp(0, shape[0])); + return boxes; +} + + +torch::Tensor scale_boxes(const std::vector& img1_shape, torch::Tensor& boxes, const std::vector& img0_shape) { + auto gain = (std::min)((float)img1_shape[0] / img0_shape[0], (float)img1_shape[1] / img0_shape[1]); + auto pad0 = std::round((float)(img1_shape[1] - img0_shape[1] * gain) / 2. - 0.1); + auto pad1 = std::round((float)(img1_shape[0] - img0_shape[0] * gain) / 2. - 0.1); + + boxes.index_put_({"...", 0}, boxes.index({"...", 0}) - pad0); + boxes.index_put_({"...", 2}, boxes.index({"...", 2}) - pad0); + boxes.index_put_({"...", 1}, boxes.index({"...", 1}) - pad1); + boxes.index_put_({"...", 3}, boxes.index({"...", 3}) - pad1); + boxes.index_put_({"...", Slice(None, 4)}, boxes.index({"...", Slice(None, 4)}).div(gain)); + return boxes; +} + + +int main() { + // Device + torch::Device device(torch::cuda::is_available() ? torch::kCUDA :torch::kCPU); + + // Note that in this example the classes are hard-coded + std::vector classes {"person", "bicycle", "car", "motorcycle", "airplane", "bus", "train", "truck", "boat", "traffic light", "fire hydrant", + "stop sign", "parking meter", "bench", "bird", "cat", "dog", "horse", "sheep", "cow", "elephant", "bear", "zebra", + "giraffe", "backpack", "umbrella", "handbag", "tie", "suitcase", "frisbee", "skis", "snowboard", "sports ball", "kite", + "baseball bat", "baseball glove", "skateboard", "surfboard", "tennis racket", "bottle", "wine glass", "cup", "fork", "knife", + "spoon", "bowl", "banana", "apple", "sandwich", "orange", "broccoli", "carrot", "hot dog", "pizza", "donut", "cake", "chair", + "couch", "potted plant", "bed", "dining table", "toilet", "tv", "laptop", "mouse", "remote", "keyboard", "cell phone", + "microwave", "oven", "toaster", "sink", "refrigerator", "book", "clock", "vase", "scissors", "teddy bear", "hair drier", "toothbrush"}; + + try { + // Load the model (e.g. yolov8s.torchscript) + std::string model_path = "/path/to/yolov8s.torchscript"; + torch::jit::script::Module yolo_model; + yolo_model = torch::jit::load(model_path); + yolo_model.eval(); + yolo_model.to(device, torch::kFloat32); + + // Load image and preprocess + cv::Mat image = cv::imread("/path/to/bus.jpg"); + cv::Mat input_image; + letterbox(image, input_image, {640, 640}); + + torch::Tensor image_tensor = torch::from_blob(input_image.data, {input_image.rows, input_image.cols, 3}, torch::kByte).to(device); + image_tensor = image_tensor.toType(torch::kFloat32).div(255); + image_tensor = image_tensor.permute({2, 0, 1}); + image_tensor = image_tensor.unsqueeze(0); + std::vector inputs {image_tensor}; + + // Inference + torch::Tensor output = yolo_model.forward(inputs).toTensor().cpu(); + + // NMS + auto keep = non_max_suppression(output)[0]; + auto boxes = keep.index({Slice(), Slice(None, 4)}); + keep.index_put_({Slice(), Slice(None, 4)}, scale_boxes({input_image.rows, input_image.cols}, boxes, {image.rows, image.cols})); + + // Show the results + for (int i = 0; i < keep.size(0); i++) { + int x1 = keep[i][0].item().toFloat(); + int y1 = keep[i][1].item().toFloat(); + int x2 = keep[i][2].item().toFloat(); + int y2 = keep[i][3].item().toFloat(); + float conf = keep[i][4].item().toFloat(); + int cls = keep[i][5].item().toInt(); + std::cout << "Rect: [" << x1 << "," << y1 << "," << x2 << "," << y2 << "] Conf: " << conf << " Class: " << classes[cls] << std::endl; + } + } catch (const c10::Error& e) { + std::cout << e.msg() << std::endl; + } + + return 0; +} diff --git a/examples/YOLOv8-ONNXRuntime-CPP/CMakeLists.txt b/examples/YOLOv8-ONNXRuntime-CPP/CMakeLists.txt new file mode 100644 index 0000000..86232cc --- /dev/null +++ b/examples/YOLOv8-ONNXRuntime-CPP/CMakeLists.txt @@ -0,0 +1,96 @@ +cmake_minimum_required(VERSION 3.5) + +set(PROJECT_NAME Yolov8OnnxRuntimeCPPInference) +project(${PROJECT_NAME} VERSION 0.0.1 LANGUAGES CXX) + + +# -------------- Support C++17 for using filesystem ------------------# +set(CMAKE_CXX_STANDARD 17) +set(CMAKE_CXX_STANDARD_REQUIRED ON) +set(CMAKE_CXX_EXTENSIONS ON) +set(CMAKE_INCLUDE_CURRENT_DIR ON) + + +# -------------- OpenCV ------------------# +find_package(OpenCV REQUIRED) +include_directories(${OpenCV_INCLUDE_DIRS}) + + +# -------------- Compile CUDA for FP16 inference if needed ------------------# +option(USE_CUDA "Enable CUDA support" ON) +if (NOT APPLE AND USE_CUDA) + find_package(CUDA REQUIRED) + include_directories(${CUDA_INCLUDE_DIRS}) + add_definitions(-DUSE_CUDA) +else () + set(USE_CUDA OFF) +endif () + +# -------------- ONNXRUNTIME ------------------# + +# Set ONNXRUNTIME_VERSION +set(ONNXRUNTIME_VERSION 1.15.1) + +if (WIN32) + if (USE_CUDA) + set(ONNXRUNTIME_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/onnxruntime-win-x64-gpu-${ONNXRUNTIME_VERSION}") + else () + set(ONNXRUNTIME_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/onnxruntime-win-x64-${ONNXRUNTIME_VERSION}") + endif () +elseif (LINUX) + if (USE_CUDA) + set(ONNXRUNTIME_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/onnxruntime-linux-x64-gpu-${ONNXRUNTIME_VERSION}") + else () + set(ONNXRUNTIME_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/onnxruntime-linux-x64-${ONNXRUNTIME_VERSION}") + endif () +elseif (APPLE) + set(ONNXRUNTIME_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/onnxruntime-osx-arm64-${ONNXRUNTIME_VERSION}") + # Apple X64 binary + # set(ONNXRUNTIME_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/onnxruntime-osx-x64-${ONNXRUNTIME_VERSION}") + # Apple Universal binary + # set(ONNXRUNTIME_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/onnxruntime-osx-universal2-${ONNXRUNTIME_VERSION}") +endif () + +include_directories(${PROJECT_NAME} ${ONNXRUNTIME_ROOT}/include) + +set(PROJECT_SOURCES + main.cpp + inference.h + inference.cpp +) + +add_executable(${PROJECT_NAME} ${PROJECT_SOURCES}) + +if (WIN32) + target_link_libraries(${PROJECT_NAME} ${OpenCV_LIBS} ${ONNXRUNTIME_ROOT}/lib/onnxruntime.lib) + if (USE_CUDA) + target_link_libraries(${PROJECT_NAME} ${CUDA_LIBRARIES}) + endif () +elseif (LINUX) + target_link_libraries(${PROJECT_NAME} ${OpenCV_LIBS} ${ONNXRUNTIME_ROOT}/lib/libonnxruntime.so) + if (USE_CUDA) + target_link_libraries(${PROJECT_NAME} ${CUDA_LIBRARIES}) + endif () +elseif (APPLE) + target_link_libraries(${PROJECT_NAME} ${OpenCV_LIBS} ${ONNXRUNTIME_ROOT}/lib/libonnxruntime.dylib) +endif () + +# For windows system, copy onnxruntime.dll to the same folder of the executable file +if (WIN32) + add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD + COMMAND ${CMAKE_COMMAND} -E copy_if_different + "${ONNXRUNTIME_ROOT}/lib/onnxruntime.dll" + $) +endif () + +# Download https://raw.githubusercontent.com/ultralytics/ultralytics/main/ultralytics/cfg/datasets/coco.yaml +# and put it in the same folder of the executable file +configure_file(coco.yaml ${CMAKE_CURRENT_BINARY_DIR}/coco.yaml COPYONLY) + +# Copy yolov8n.onnx file to the same folder of the executable file +configure_file(yolov8n.onnx ${CMAKE_CURRENT_BINARY_DIR}/yolov8n.onnx COPYONLY) + +# Create folder name images in the same folder of the executable file +add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD + COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_CURRENT_BINARY_DIR}/images +) diff --git a/examples/YOLOv8-ONNXRuntime-CPP/README.md b/examples/YOLOv8-ONNXRuntime-CPP/README.md new file mode 100644 index 0000000..1cb6eb3 --- /dev/null +++ b/examples/YOLOv8-ONNXRuntime-CPP/README.md @@ -0,0 +1,107 @@ +# YOLOv8 OnnxRuntime C++ + +C++ Onnx-runtime + +This example demonstrates how to perform inference using YOLOv8 in C++ with ONNX Runtime and OpenCV's API. + +## Benefits ✨ + +- Friendly for deployment in the industrial sector. +- Faster than OpenCV's DNN inference on both CPU and GPU. +- Supports FP32 and FP16 CUDA acceleration. + +## Note ☕ + +1. Benefit for Ultralytics' latest release, a `Transpose` op is added to the YOLOv8 model, while make v8 and v5 has the same output shape. Therefore, you can run inference with YOLOv5/v7/v8 via this project. + +## Exporting YOLOv8 Models 📦 + +To export YOLOv8 models, use the following Python script: + +```python +from ultralytics import YOLO + +# Load a YOLOv8 model +model = YOLO("yolov8n.pt") + +# Export the model +model.export(format="onnx", opset=12, simplify=True, dynamic=False, imgsz=640) +``` + +Alternatively, you can use the following command for exporting the model in the terminal + +```bash +yolo export model=yolov8n.pt opset=12 simplify=True dynamic=False format=onnx imgsz=640,640 +``` + +## Exporting YOLOv8 FP16 Models 📦 + +```python +import onnx +from onnxconverter_common import float16 + +model = onnx.load(R'YOUR_ONNX_PATH') +model_fp16 = float16.convert_float_to_float16(model) +onnx.save(model_fp16, R'YOUR_FP16_ONNX_PATH') +``` + +## Download COCO.yaml file 📂 + +In order to run example, you also need to download coco.yaml. You can download the file manually from [here](https://raw.githubusercontent.com/ultralytics/ultralytics/main/ultralytics/cfg/datasets/coco.yaml) + +## Dependencies ⚙️ + +| Dependency | Version | +| -------------------------------- | -------------- | +| Onnxruntime(linux,windows,macos) | >=1.14.1 | +| OpenCV | >=4.0.0 | +| C++ Standard | >=17 | +| Cmake | >=3.5 | +| Cuda (Optional) | >=11.4 \<12.0 | +| cuDNN (Cuda required) | =8 | + +Note: The dependency on C++17 is due to the usage of the C++17 filesystem feature. + +Note (2): Due to ONNX Runtime, we need to use CUDA 11 and cuDNN 8. Keep in mind that this requirement might change in the future. + +## Build 🛠️ + +1. Clone the repository to your local machine. + +2. Navigate to the root directory of the repository. + +3. Create a build directory and navigate to it: + + ```console + mkdir build && cd build + ``` + +4. Run CMake to generate the build files: + + ```console + cmake .. + ``` + +5. Build the project: + + ```console + make + ``` + +6. The built executable should now be located in the `build` directory. + +## Usage 🚀 + +```c++ +//change your param as you like +//Pay attention to your device and the onnx model type(fp32 or fp16) +DL_INIT_PARAM params; +params.rectConfidenceThreshold = 0.1; +params.iouThreshold = 0.5; +params.modelPath = "yolov8n.onnx"; +params.imgSize = { 640, 640 }; +params.cudaEnable = true; +params.modelType = YOLO_DETECT_V8; +yoloDetector->CreateSession(params); +Detector(yoloDetector); +``` diff --git a/examples/YOLOv8-ONNXRuntime-CPP/inference.cpp b/examples/YOLOv8-ONNXRuntime-CPP/inference.cpp new file mode 100644 index 0000000..88aeae3 --- /dev/null +++ b/examples/YOLOv8-ONNXRuntime-CPP/inference.cpp @@ -0,0 +1,375 @@ +#include "inference.h" +#include + +#define benchmark +#define min(a,b) (((a) < (b)) ? (a) : (b)) +YOLO_V8::YOLO_V8() { + +} + + +YOLO_V8::~YOLO_V8() { + delete session; +} + +#ifdef USE_CUDA +namespace Ort +{ + template<> + struct TypeToTensorType { static constexpr ONNXTensorElementDataType type = ONNX_TENSOR_ELEMENT_DATA_TYPE_FLOAT16; }; +} +#endif + + +template +char* BlobFromImage(cv::Mat& iImg, T& iBlob) { + int channels = iImg.channels(); + int imgHeight = iImg.rows; + int imgWidth = iImg.cols; + + for (int c = 0; c < channels; c++) + { + for (int h = 0; h < imgHeight; h++) + { + for (int w = 0; w < imgWidth; w++) + { + iBlob[c * imgWidth * imgHeight + h * imgWidth + w] = typename std::remove_pointer::type( + (iImg.at(h, w)[c]) / 255.0f); + } + } + } + return RET_OK; +} + + +char* YOLO_V8::PreProcess(cv::Mat& iImg, std::vector iImgSize, cv::Mat& oImg) +{ + if (iImg.channels() == 3) + { + oImg = iImg.clone(); + cv::cvtColor(oImg, oImg, cv::COLOR_BGR2RGB); + } + else + { + cv::cvtColor(iImg, oImg, cv::COLOR_GRAY2RGB); + } + + switch (modelType) + { + case YOLO_DETECT_V8: + case YOLO_POSE: + case YOLO_DETECT_V8_HALF: + case YOLO_POSE_V8_HALF://LetterBox + { + if (iImg.cols >= iImg.rows) + { + resizeScales = iImg.cols / (float)iImgSize.at(0); + cv::resize(oImg, oImg, cv::Size(iImgSize.at(0), int(iImg.rows / resizeScales))); + } + else + { + resizeScales = iImg.rows / (float)iImgSize.at(0); + cv::resize(oImg, oImg, cv::Size(int(iImg.cols / resizeScales), iImgSize.at(1))); + } + cv::Mat tempImg = cv::Mat::zeros(iImgSize.at(0), iImgSize.at(1), CV_8UC3); + oImg.copyTo(tempImg(cv::Rect(0, 0, oImg.cols, oImg.rows))); + oImg = tempImg; + break; + } + case YOLO_CLS://CenterCrop + { + int h = iImg.rows; + int w = iImg.cols; + int m = min(h, w); + int top = (h - m) / 2; + int left = (w - m) / 2; + cv::resize(oImg(cv::Rect(left, top, m, m)), oImg, cv::Size(iImgSize.at(0), iImgSize.at(1))); + break; + } + } + return RET_OK; +} + + +char* YOLO_V8::CreateSession(DL_INIT_PARAM& iParams) { + char* Ret = RET_OK; + std::regex pattern("[\u4e00-\u9fa5]"); + bool result = std::regex_search(iParams.modelPath, pattern); + if (result) + { + Ret = "[YOLO_V8]:Your model path is error.Change your model path without chinese characters."; + std::cout << Ret << std::endl; + return Ret; + } + try + { + rectConfidenceThreshold = iParams.rectConfidenceThreshold; + iouThreshold = iParams.iouThreshold; + imgSize = iParams.imgSize; + modelType = iParams.modelType; + env = Ort::Env(ORT_LOGGING_LEVEL_WARNING, "Yolo"); + Ort::SessionOptions sessionOption; + if (iParams.cudaEnable) + { + cudaEnable = iParams.cudaEnable; + OrtCUDAProviderOptions cudaOption; + cudaOption.device_id = 0; + sessionOption.AppendExecutionProvider_CUDA(cudaOption); + } + sessionOption.SetGraphOptimizationLevel(GraphOptimizationLevel::ORT_ENABLE_ALL); + sessionOption.SetIntraOpNumThreads(iParams.intraOpNumThreads); + sessionOption.SetLogSeverityLevel(iParams.logSeverityLevel); + +#ifdef _WIN32 + int ModelPathSize = MultiByteToWideChar(CP_UTF8, 0, iParams.modelPath.c_str(), static_cast(iParams.modelPath.length()), nullptr, 0); + wchar_t* wide_cstr = new wchar_t[ModelPathSize + 1]; + MultiByteToWideChar(CP_UTF8, 0, iParams.modelPath.c_str(), static_cast(iParams.modelPath.length()), wide_cstr, ModelPathSize); + wide_cstr[ModelPathSize] = L'\0'; + const wchar_t* modelPath = wide_cstr; +#else + const char* modelPath = iParams.modelPath.c_str(); +#endif // _WIN32 + + session = new Ort::Session(env, modelPath, sessionOption); + Ort::AllocatorWithDefaultOptions allocator; + size_t inputNodesNum = session->GetInputCount(); + for (size_t i = 0; i < inputNodesNum; i++) + { + Ort::AllocatedStringPtr input_node_name = session->GetInputNameAllocated(i, allocator); + char* temp_buf = new char[50]; + strcpy(temp_buf, input_node_name.get()); + inputNodeNames.push_back(temp_buf); + } + size_t OutputNodesNum = session->GetOutputCount(); + for (size_t i = 0; i < OutputNodesNum; i++) + { + Ort::AllocatedStringPtr output_node_name = session->GetOutputNameAllocated(i, allocator); + char* temp_buf = new char[10]; + strcpy(temp_buf, output_node_name.get()); + outputNodeNames.push_back(temp_buf); + } + options = Ort::RunOptions{ nullptr }; + WarmUpSession(); + return RET_OK; + } + catch (const std::exception& e) + { + const char* str1 = "[YOLO_V8]:"; + const char* str2 = e.what(); + std::string result = std::string(str1) + std::string(str2); + char* merged = new char[result.length() + 1]; + std::strcpy(merged, result.c_str()); + std::cout << merged << std::endl; + delete[] merged; + return "[YOLO_V8]:Create session failed."; + } + +} + + +char* YOLO_V8::RunSession(cv::Mat& iImg, std::vector& oResult) { +#ifdef benchmark + clock_t starttime_1 = clock(); +#endif // benchmark + + char* Ret = RET_OK; + cv::Mat processedImg; + PreProcess(iImg, imgSize, processedImg); + if (modelType < 4) + { + float* blob = new float[processedImg.total() * 3]; + BlobFromImage(processedImg, blob); + std::vector inputNodeDims = { 1, 3, imgSize.at(0), imgSize.at(1) }; + TensorProcess(starttime_1, iImg, blob, inputNodeDims, oResult); + } + else + { +#ifdef USE_CUDA + half* blob = new half[processedImg.total() * 3]; + BlobFromImage(processedImg, blob); + std::vector inputNodeDims = { 1,3,imgSize.at(0),imgSize.at(1) }; + TensorProcess(starttime_1, iImg, blob, inputNodeDims, oResult); +#endif + } + + return Ret; +} + + +template +char* YOLO_V8::TensorProcess(clock_t& starttime_1, cv::Mat& iImg, N& blob, std::vector& inputNodeDims, + std::vector& oResult) { + Ort::Value inputTensor = Ort::Value::CreateTensor::type>( + Ort::MemoryInfo::CreateCpu(OrtDeviceAllocator, OrtMemTypeCPU), blob, 3 * imgSize.at(0) * imgSize.at(1), + inputNodeDims.data(), inputNodeDims.size()); +#ifdef benchmark + clock_t starttime_2 = clock(); +#endif // benchmark + auto outputTensor = session->Run(options, inputNodeNames.data(), &inputTensor, 1, outputNodeNames.data(), + outputNodeNames.size()); +#ifdef benchmark + clock_t starttime_3 = clock(); +#endif // benchmark + + Ort::TypeInfo typeInfo = outputTensor.front().GetTypeInfo(); + auto tensor_info = typeInfo.GetTensorTypeAndShapeInfo(); + std::vector outputNodeDims = tensor_info.GetShape(); + auto output = outputTensor.front().GetTensorMutableData::type>(); + delete[] blob; + switch (modelType) + { + case YOLO_DETECT_V8: + case YOLO_DETECT_V8_HALF: + { + int strideNum = outputNodeDims[1];//8400 + int signalResultNum = outputNodeDims[2];//84 + std::vector class_ids; + std::vector confidences; + std::vector boxes; + cv::Mat rawData; + if (modelType == YOLO_DETECT_V8) + { + // FP32 + rawData = cv::Mat(strideNum, signalResultNum, CV_32F, output); + } + else + { + // FP16 + rawData = cv::Mat(strideNum, signalResultNum, CV_16F, output); + rawData.convertTo(rawData, CV_32F); + } + //Note: + //ultralytics add transpose operator to the output of yolov8 model.which make yolov8/v5/v7 has same shape + //https://github.com/ultralytics/assets/releases/download/v8.1.0/yolov8n.pt + //rowData = rowData.t(); + + float* data = (float*)rawData.data; + + for (int i = 0; i < strideNum; ++i) + { + float* classesScores = data + 4; + cv::Mat scores(1, this->classes.size(), CV_32FC1, classesScores); + cv::Point class_id; + double maxClassScore; + cv::minMaxLoc(scores, 0, &maxClassScore, 0, &class_id); + if (maxClassScore > rectConfidenceThreshold) + { + confidences.push_back(maxClassScore); + class_ids.push_back(class_id.x); + float x = data[0]; + float y = data[1]; + float w = data[2]; + float h = data[3]; + + int left = int((x - 0.5 * w) * resizeScales); + int top = int((y - 0.5 * h) * resizeScales); + + int width = int(w * resizeScales); + int height = int(h * resizeScales); + + boxes.push_back(cv::Rect(left, top, width, height)); + } + data += signalResultNum; + } + std::vector nmsResult; + cv::dnn::NMSBoxes(boxes, confidences, rectConfidenceThreshold, iouThreshold, nmsResult); + for (int i = 0; i < nmsResult.size(); ++i) + { + int idx = nmsResult[i]; + DL_RESULT result; + result.classId = class_ids[idx]; + result.confidence = confidences[idx]; + result.box = boxes[idx]; + oResult.push_back(result); + } + +#ifdef benchmark + clock_t starttime_4 = clock(); + double pre_process_time = (double)(starttime_2 - starttime_1) / CLOCKS_PER_SEC * 1000; + double process_time = (double)(starttime_3 - starttime_2) / CLOCKS_PER_SEC * 1000; + double post_process_time = (double)(starttime_4 - starttime_3) / CLOCKS_PER_SEC * 1000; + if (cudaEnable) + { + std::cout << "[YOLO_V8(CUDA)]: " << pre_process_time << "ms pre-process, " << process_time << "ms inference, " << post_process_time << "ms post-process." << std::endl; + } + else + { + std::cout << "[YOLO_V8(CPU)]: " << pre_process_time << "ms pre-process, " << process_time << "ms inference, " << post_process_time << "ms post-process." << std::endl; + } +#endif // benchmark + + break; + } + case YOLO_CLS: + case YOLO_CLS_HALF: + { + cv::Mat rawData; + if (modelType == YOLO_CLS) { + // FP32 + rawData = cv::Mat(1, this->classes.size(), CV_32F, output); + } else { + // FP16 + rawData = cv::Mat(1, this->classes.size(), CV_16F, output); + rawData.convertTo(rawData, CV_32F); + } + float *data = (float *) rawData.data; + + DL_RESULT result; + for (int i = 0; i < this->classes.size(); i++) + { + result.classId = i; + result.confidence = data[i]; + oResult.push_back(result); + } + break; + } + default: + std::cout << "[YOLO_V8]: " << "Not support model type." << std::endl; + } + return RET_OK; + +} + + +char* YOLO_V8::WarmUpSession() { + clock_t starttime_1 = clock(); + cv::Mat iImg = cv::Mat(cv::Size(imgSize.at(0), imgSize.at(1)), CV_8UC3); + cv::Mat processedImg; + PreProcess(iImg, imgSize, processedImg); + if (modelType < 4) + { + float* blob = new float[iImg.total() * 3]; + BlobFromImage(processedImg, blob); + std::vector YOLO_input_node_dims = { 1, 3, imgSize.at(0), imgSize.at(1) }; + Ort::Value input_tensor = Ort::Value::CreateTensor( + Ort::MemoryInfo::CreateCpu(OrtDeviceAllocator, OrtMemTypeCPU), blob, 3 * imgSize.at(0) * imgSize.at(1), + YOLO_input_node_dims.data(), YOLO_input_node_dims.size()); + auto output_tensors = session->Run(options, inputNodeNames.data(), &input_tensor, 1, outputNodeNames.data(), + outputNodeNames.size()); + delete[] blob; + clock_t starttime_4 = clock(); + double post_process_time = (double)(starttime_4 - starttime_1) / CLOCKS_PER_SEC * 1000; + if (cudaEnable) + { + std::cout << "[YOLO_V8(CUDA)]: " << "Cuda warm-up cost " << post_process_time << " ms. " << std::endl; + } + } + else + { +#ifdef USE_CUDA + half* blob = new half[iImg.total() * 3]; + BlobFromImage(processedImg, blob); + std::vector YOLO_input_node_dims = { 1,3,imgSize.at(0),imgSize.at(1) }; + Ort::Value input_tensor = Ort::Value::CreateTensor(Ort::MemoryInfo::CreateCpu(OrtDeviceAllocator, OrtMemTypeCPU), blob, 3 * imgSize.at(0) * imgSize.at(1), YOLO_input_node_dims.data(), YOLO_input_node_dims.size()); + auto output_tensors = session->Run(options, inputNodeNames.data(), &input_tensor, 1, outputNodeNames.data(), outputNodeNames.size()); + delete[] blob; + clock_t starttime_4 = clock(); + double post_process_time = (double)(starttime_4 - starttime_1) / CLOCKS_PER_SEC * 1000; + if (cudaEnable) + { + std::cout << "[YOLO_V8(CUDA)]: " << "Cuda warm-up cost " << post_process_time << " ms. " << std::endl; + } +#endif + } + return RET_OK; +} diff --git a/examples/YOLOv8-ONNXRuntime-CPP/inference.h b/examples/YOLOv8-ONNXRuntime-CPP/inference.h new file mode 100644 index 0000000..3a9d029 --- /dev/null +++ b/examples/YOLOv8-ONNXRuntime-CPP/inference.h @@ -0,0 +1,94 @@ +#pragma once + +#define RET_OK nullptr + +#ifdef _WIN32 +#include +#include +#include +#endif + +#include +#include +#include +#include +#include "onnxruntime_cxx_api.h" + +#ifdef USE_CUDA +#include +#endif + + +enum MODEL_TYPE +{ + //FLOAT32 MODEL + YOLO_DETECT_V8 = 1, + YOLO_POSE = 2, + YOLO_CLS = 3, + + //FLOAT16 MODEL + YOLO_DETECT_V8_HALF = 4, + YOLO_POSE_V8_HALF = 5, + YOLO_CLS_HALF = 6 +}; + + +typedef struct _DL_INIT_PARAM +{ + std::string modelPath; + MODEL_TYPE modelType = YOLO_DETECT_V8; + std::vector imgSize = { 640, 640 }; + float rectConfidenceThreshold = 0.6; + float iouThreshold = 0.5; + int keyPointsNum = 2;//Note:kpt number for pose + bool cudaEnable = false; + int logSeverityLevel = 3; + int intraOpNumThreads = 1; +} DL_INIT_PARAM; + + +typedef struct _DL_RESULT +{ + int classId; + float confidence; + cv::Rect box; + std::vector keyPoints; +} DL_RESULT; + + +class YOLO_V8 +{ +public: + YOLO_V8(); + + ~YOLO_V8(); + +public: + char* CreateSession(DL_INIT_PARAM& iParams); + + char* RunSession(cv::Mat& iImg, std::vector& oResult); + + char* WarmUpSession(); + + template + char* TensorProcess(clock_t& starttime_1, cv::Mat& iImg, N& blob, std::vector& inputNodeDims, + std::vector& oResult); + + char* PreProcess(cv::Mat& iImg, std::vector iImgSize, cv::Mat& oImg); + + std::vector classes{}; + +private: + Ort::Env env; + Ort::Session* session; + bool cudaEnable; + Ort::RunOptions options; + std::vector inputNodeNames; + std::vector outputNodeNames; + + MODEL_TYPE modelType; + std::vector imgSize; + float rectConfidenceThreshold; + float iouThreshold; + float resizeScales;//letterbox scale +}; diff --git a/examples/YOLOv8-ONNXRuntime-CPP/main.cpp b/examples/YOLOv8-ONNXRuntime-CPP/main.cpp new file mode 100644 index 0000000..6e4ef1d --- /dev/null +++ b/examples/YOLOv8-ONNXRuntime-CPP/main.cpp @@ -0,0 +1,193 @@ +#include +#include +#include "inference.h" +#include +#include +#include + +void Detector(YOLO_V8*& p) { + std::filesystem::path current_path = std::filesystem::current_path(); + std::filesystem::path imgs_path = current_path / "images"; + for (auto& i : std::filesystem::directory_iterator(imgs_path)) + { + if (i.path().extension() == ".jpg" || i.path().extension() == ".png" || i.path().extension() == ".jpeg") + { + std::string img_path = i.path().string(); + cv::Mat img = cv::imread(img_path); + std::vector res; + p->RunSession(img, res); + + for (auto& re : res) + { + cv::RNG rng(cv::getTickCount()); + cv::Scalar color(rng.uniform(0, 256), rng.uniform(0, 256), rng.uniform(0, 256)); + + cv::rectangle(img, re.box, color, 3); + + float confidence = floor(100 * re.confidence) / 100; + std::cout << std::fixed << std::setprecision(2); + std::string label = p->classes[re.classId] + " " + + std::to_string(confidence).substr(0, std::to_string(confidence).size() - 4); + + cv::rectangle( + img, + cv::Point(re.box.x, re.box.y - 25), + cv::Point(re.box.x + label.length() * 15, re.box.y), + color, + cv::FILLED + ); + + cv::putText( + img, + label, + cv::Point(re.box.x, re.box.y - 5), + cv::FONT_HERSHEY_SIMPLEX, + 0.75, + cv::Scalar(0, 0, 0), + 2 + ); + + + } + std::cout << "Press any key to exit" << std::endl; + cv::imshow("Result of Detection", img); + cv::waitKey(0); + cv::destroyAllWindows(); + } + } +} + + +void Classifier(YOLO_V8*& p) +{ + std::filesystem::path current_path = std::filesystem::current_path(); + std::filesystem::path imgs_path = current_path;// / "images" + std::random_device rd; + std::mt19937 gen(rd()); + std::uniform_int_distribution dis(0, 255); + for (auto& i : std::filesystem::directory_iterator(imgs_path)) + { + if (i.path().extension() == ".jpg" || i.path().extension() == ".png") + { + std::string img_path = i.path().string(); + //std::cout << img_path << std::endl; + cv::Mat img = cv::imread(img_path); + std::vector res; + char* ret = p->RunSession(img, res); + + float positionY = 50; + for (int i = 0; i < res.size(); i++) + { + int r = dis(gen); + int g = dis(gen); + int b = dis(gen); + cv::putText(img, std::to_string(i) + ":", cv::Point(10, positionY), cv::FONT_HERSHEY_SIMPLEX, 1, cv::Scalar(b, g, r), 2); + cv::putText(img, std::to_string(res.at(i).confidence), cv::Point(70, positionY), cv::FONT_HERSHEY_SIMPLEX, 1, cv::Scalar(b, g, r), 2); + positionY += 50; + } + + cv::imshow("TEST_CLS", img); + cv::waitKey(0); + cv::destroyAllWindows(); + //cv::imwrite("E:\\output\\" + std::to_string(k) + ".png", img); + } + + } +} + + + +int ReadCocoYaml(YOLO_V8*& p) { + // Open the YAML file + std::ifstream file("coco.yaml"); + if (!file.is_open()) + { + std::cerr << "Failed to open file" << std::endl; + return 1; + } + + // Read the file line by line + std::string line; + std::vector lines; + while (std::getline(file, line)) + { + lines.push_back(line); + } + + // Find the start and end of the names section + std::size_t start = 0; + std::size_t end = 0; + for (std::size_t i = 0; i < lines.size(); i++) + { + if (lines[i].find("names:") != std::string::npos) + { + start = i + 1; + } + else if (start > 0 && lines[i].find(':') == std::string::npos) + { + end = i; + break; + } + } + + // Extract the names + std::vector names; + for (std::size_t i = start; i < end; i++) + { + std::stringstream ss(lines[i]); + std::string name; + std::getline(ss, name, ':'); // Extract the number before the delimiter + std::getline(ss, name); // Extract the string after the delimiter + names.push_back(name); + } + + p->classes = names; + return 0; +} + + +void DetectTest() +{ + YOLO_V8* yoloDetector = new YOLO_V8; + ReadCocoYaml(yoloDetector); + DL_INIT_PARAM params; + params.rectConfidenceThreshold = 0.1; + params.iouThreshold = 0.5; + params.modelPath = "yolov8n.onnx"; + params.imgSize = { 640, 640 }; +#ifdef USE_CUDA + params.cudaEnable = true; + + // GPU FP32 inference + params.modelType = YOLO_DETECT_V8; + // GPU FP16 inference + //Note: change fp16 onnx model + //params.modelType = YOLO_DETECT_V8_HALF; + +#else + // CPU inference + params.modelType = YOLO_DETECT_V8; + params.cudaEnable = false; + +#endif + yoloDetector->CreateSession(params); + Detector(yoloDetector); +} + + +void ClsTest() +{ + YOLO_V8* yoloDetector = new YOLO_V8; + std::string model_path = "cls.onnx"; + ReadCocoYaml(yoloDetector); + DL_INIT_PARAM params{ model_path, YOLO_CLS, {224, 224} }; + yoloDetector->CreateSession(params); + Classifier(yoloDetector); +} + + +int main() +{ + //DetectTest(); + ClsTest(); +} diff --git a/examples/YOLOv8-ONNXRuntime-Rust/Cargo.toml b/examples/YOLOv8-ONNXRuntime-Rust/Cargo.toml new file mode 100644 index 0000000..101f72e --- /dev/null +++ b/examples/YOLOv8-ONNXRuntime-Rust/Cargo.toml @@ -0,0 +1,21 @@ +[package] +name = "yolov8-rs" +version = "0.1.0" +edition = "2021" + +# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html + +[dependencies] +clap = { version = "4.2.4", features = ["derive"] } +image = { version = "0.24.7", default-features = false, features = ["jpeg", "png", "webp-encoder"] } +imageproc = { version = "0.23.0", default-features = false } +ndarray = { version = "0.15.6" } +ort = {version = "1.16.3", default-features = false, features = ["load-dynamic", "copy-dylibs", "half"]} +rusttype = { version = "0.9", default-features = false } +anyhow = { version = "1.0.75"} +regex = { version = "1.5.4" } +rand = { version ="0.8.5" } +chrono = { version = "0.4.30" } +half = { version = "2.3.1" } +dirs = { version = "5.0.1" } +ureq = { version = "2.9.1" } diff --git a/examples/YOLOv8-ONNXRuntime-Rust/README.md b/examples/YOLOv8-ONNXRuntime-Rust/README.md new file mode 100644 index 0000000..8961d9c --- /dev/null +++ b/examples/YOLOv8-ONNXRuntime-Rust/README.md @@ -0,0 +1,221 @@ +# YOLOv8-ONNXRuntime-Rust for All the Key YOLO Tasks + +This repository provides a Rust demo for performing YOLOv8 tasks like `Classification`, `Segmentation`, `Detection` and `Pose Detection` using ONNXRuntime. + +## Features + +- Support `Classification`, `Segmentation`, `Detection`, `Pose(Keypoints)-Detection` tasks. +- Support `FP16` & `FP32` ONNX models. +- Support `CPU`, `CUDA` and `TensorRT` execution provider to accelerate computation. +- Support dynamic input shapes(`batch`, `width`, `height`). + +## Installation + +### 1. Install Rust + +Please follow the Rust official installation. (https://www.rust-lang.org/tools/install) + +### 2. Install ONNXRuntime + +This repository use `ort` crate, which is ONNXRuntime wrapper for Rust. (https://docs.rs/ort/latest/ort/) + +You can follow the instruction with `ort` doc or simply do this: + +- step1: Download ONNXRuntime(https://github.com/microsoft/onnxruntime/releases) +- setp2: Set environment variable `PATH` for linking. + +On ubuntu, You can do like this: + +``` +vim ~/.bashrc + +# Add the path of ONNXRUntime lib +export LD_LIBRARY_PATH=/home/qweasd/Documents/onnxruntime-linux-x64-gpu-1.16.3/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}} + +source ~/.bashrc +``` + +### 3. \[Optional\] Install CUDA & CuDNN & TensorRT + +- CUDA execution provider requires CUDA v11.6+. +- TensorRT execution provider requires CUDA v11.4+ and TensorRT v8.4+. + +## Get Started + +### 1. Export the YOLOv8 ONNX Models + +```bash +pip install -U ultralytics + +# export onnx model with dynamic shapes +yolo export model=yolov8m.pt format=onnx simplify dynamic +yolo export model=yolov8m-cls.pt format=onnx simplify dynamic +yolo export model=yolov8m-pose.pt format=onnx simplify dynamic +yolo export model=yolov8m-seg.pt format=onnx simplify dynamic + + +# export onnx model with constant shapes +yolo export model=yolov8m.pt format=onnx simplify +yolo export model=yolov8m-cls.pt format=onnx simplify +yolo export model=yolov8m-pose.pt format=onnx simplify +yolo export model=yolov8m-seg.pt format=onnx simplify +``` + +### 2. Run Inference + +It will perform inference with the ONNX model on the source image. + +``` +cargo run --release -- --model --source +``` + +Set `--cuda` to use CUDA execution provider to speed up inference. + +``` +cargo run --release -- --cuda --model --source +``` + +Set `--trt` to use TensorRT execution provider, and you can set `--fp16` at the same time to use TensorRT FP16 engine. + +``` +cargo run --release -- --trt --fp16 --model --source +``` + +Set `--device_id` to select which device to run. When you have only one GPU, and you set `device_id` to 1 will not cause program panic, the `ort` would automatically fall back to `CPU` EP. + +``` +cargo run --release -- --cuda --device_id 0 --model --source +``` + +Set `--batch` to do multi-batch-size inference. + +If you're using `--trt`, you can also set `--batch-min` and `--batch-max` to explicitly specify min/max/opt batch for dynamic batch input.(https://onnxruntime.ai/docs/execution-providers/TensorRT-ExecutionProvider.html#explicit-shape-range-for-dynamic-shape-input).(Note that the ONNX model should exported with dynamic shapes) + +``` +cargo run --release -- --cuda --batch 2 --model --source +``` + +Set `--height` and `--width` to do dynamic image size inference. (Note that the ONNX model should exported with dynamic shapes) + +``` +cargo run --release -- --cuda --width 480 --height 640 --model --source +``` + +Set `--profile` to check time consumed in each stage.(Note that the model usually needs to take 1~3 times dry run to warmup. Make sure to run enough times to evaluate the result.) + +``` +cargo run --release -- --trt --fp16 --profile --model --source +``` + +Results: (yolov8m.onnx, batch=1, 3 times, trt, fp16, RTX 3060Ti) + +``` +==> 0 +[Model Preprocess]: 12.75788ms +[ORT H2D]: 237.118µs +[ORT Inference]: 507.895469ms +[ORT D2H]: 191.655µs +[Model Inference]: 508.34589ms +[Model Postprocess]: 1.061122ms +==> 1 +[Model Preprocess]: 13.658655ms +[ORT H2D]: 209.975µs +[ORT Inference]: 5.12372ms +[ORT D2H]: 182.389µs +[Model Inference]: 5.530022ms +[Model Postprocess]: 1.04851ms +==> 2 +[Model Preprocess]: 12.475332ms +[ORT H2D]: 246.127µs +[ORT Inference]: 5.048432ms +[ORT D2H]: 187.117µs +[Model Inference]: 5.493119ms +[Model Postprocess]: 1.040906ms +``` + +And also: + +`--conf`: confidence threshold \[default: 0.3\] + +`--iou`: iou threshold in NMS \[default: 0.45\] + +`--kconf`: confidence threshold of keypoint \[default: 0.55\] + +`--plot`: plot inference result with random RGB color and save + +you can check out all CLI arguments by: + +``` +git clone https://github.com/ultralytics/ultralytics +cd ultralytics/examples/YOLOv8-ONNXRuntime-Rust +cargo run --release -- --help +``` + +## Examples + +### Classification + +Running dynamic shape ONNX model on `CPU` with image size `--height 224 --width 224`. Saving plotted image in `runs` directory. + +``` +cargo run --release -- --model ../assets/weights/yolov8m-cls-dyn.onnx --source ../assets/images/dog.jpg --height 224 --width 224 --plot --profile +``` + +You will see result like: + +``` +Summary: +> Task: Classify (Ultralytics 8.0.217) +> EP: Cpu +> Dtype: Float32 +> Batch: 1 (Dynamic), Height: 224 (Dynamic), Width: 224 (Dynamic) +> nc: 1000 nk: 0, nm: 0, conf: 0.3, kconf: 0.55, iou: 0.45 + +[Model Preprocess]: 16.363477ms +[ORT H2D]: 50.722µs +[ORT Inference]: 16.295808ms +[ORT D2H]: 8.37µs +[Model Inference]: 16.367046ms +[Model Postprocess]: 3.527µs +[ + YOLOResult { + Probs(top5): Some([(208, 0.6950566), (209, 0.13823675), (178, 0.04849795), (215, 0.019029364), (212, 0.016506357)]), + Bboxes: None, + Keypoints: None, + Masks: None, + }, +] + +``` + +![2023-11-25-22-02-02-156623351](https://github.com/jamjamjon/ultralytics/assets/51357717/ef75c2ae-c5ab-44cc-9d9e-e60b51e39662) + +### Object Detection + +Using `CUDA` EP and dynamic image size `--height 640 --width 480` + +``` +cargo run --release -- --cuda --model ../assets/weights/yolov8m-dynamic.onnx --source ../assets/images/bus.jpg --plot --height 640 --width 480 +``` + +![det](https://github.com/jamjamjon/ultralytics/assets/51357717/5d89a19d-0c96-4a59-875c-defab6887a2c) + +### Pose Detection + +using `TensorRT` EP + +``` +cargo run --release -- --trt --model ../assets/weights/yolov8m-pose.onnx --source ../assets/images/bus.jpg --plot +``` + +![2023-11-25-22-31-45-127054025](https://github.com/jamjamjon/ultralytics/assets/51357717/157b5ba7-bfcf-47cf-bee7-68b62e0de1c4) + +### Instance Segmentation + +using `TensorRT` EP and FP16 model `--fp16` + +``` +cargo run --release -- --trt --fp16 --model ../assets/weights/yolov8m-seg.onnx --source ../assets/images/0172.jpg --plot +``` + +![seg](https://github.com/jamjamjon/ultralytics/assets/51357717/cf046f4f-9533-478a-adc7-4de22443a641) diff --git a/examples/YOLOv8-ONNXRuntime-Rust/src/cli.rs b/examples/YOLOv8-ONNXRuntime-Rust/src/cli.rs new file mode 100644 index 0000000..2ba0dd4 --- /dev/null +++ b/examples/YOLOv8-ONNXRuntime-Rust/src/cli.rs @@ -0,0 +1,87 @@ +use clap::Parser; + +use crate::YOLOTask; + +#[derive(Parser, Clone)] +#[command(author, version, about, long_about = None)] +pub struct Args { + /// ONNX model path + #[arg(long, required = true)] + pub model: String, + + /// input path + #[arg(long, required = true)] + pub source: String, + + /// device id + #[arg(long, default_value_t = 0)] + pub device_id: u32, + + /// using TensorRT EP + #[arg(long)] + pub trt: bool, + + /// using CUDA EP + #[arg(long)] + pub cuda: bool, + + /// input batch size + #[arg(long, default_value_t = 1)] + pub batch: u32, + + /// trt input min_batch size + #[arg(long, default_value_t = 1)] + pub batch_min: u32, + + /// trt input max_batch size + #[arg(long, default_value_t = 32)] + pub batch_max: u32, + + /// using TensorRT --fp16 + #[arg(long)] + pub fp16: bool, + + /// specify YOLO task + #[arg(long, value_enum)] + pub task: Option, + + /// num_classes + #[arg(long)] + pub nc: Option, + + /// num_keypoints + #[arg(long)] + pub nk: Option, + + /// num_masks + #[arg(long)] + pub nm: Option, + + /// input image width + #[arg(long)] + pub width: Option, + + /// input image height + #[arg(long)] + pub height: Option, + + /// confidence threshold + #[arg(long, required = false, default_value_t = 0.3)] + pub conf: f32, + + /// iou threshold in NMS + #[arg(long, required = false, default_value_t = 0.45)] + pub iou: f32, + + /// confidence threshold of keypoint + #[arg(long, required = false, default_value_t = 0.55)] + pub kconf: f32, + + /// plot inference result and save + #[arg(long)] + pub plot: bool, + + /// check time consumed in each stage + #[arg(long)] + pub profile: bool, +} diff --git a/examples/YOLOv8-ONNXRuntime-Rust/src/lib.rs b/examples/YOLOv8-ONNXRuntime-Rust/src/lib.rs new file mode 100644 index 0000000..1af7f7c --- /dev/null +++ b/examples/YOLOv8-ONNXRuntime-Rust/src/lib.rs @@ -0,0 +1,119 @@ +#![allow(clippy::type_complexity)] + +use std::io::{Read, Write}; + +pub mod cli; +pub mod model; +pub mod ort_backend; +pub mod yolo_result; +pub use crate::cli::Args; +pub use crate::model::YOLOv8; +pub use crate::ort_backend::{Batch, OrtBackend, OrtConfig, OrtEP, YOLOTask}; +pub use crate::yolo_result::{Bbox, Embedding, Point2, YOLOResult}; + +pub fn non_max_suppression( + xs: &mut Vec<(Bbox, Option>, Option>)>, + iou_threshold: f32, +) { + xs.sort_by(|b1, b2| b2.0.confidence().partial_cmp(&b1.0.confidence()).unwrap()); + + let mut current_index = 0; + for index in 0..xs.len() { + let mut drop = false; + for prev_index in 0..current_index { + let iou = xs[prev_index].0.iou(&xs[index].0); + if iou > iou_threshold { + drop = true; + break; + } + } + if !drop { + xs.swap(current_index, index); + current_index += 1; + } + } + xs.truncate(current_index); +} + +pub fn gen_time_string(delimiter: &str) -> String { + let offset = chrono::FixedOffset::east_opt(8 * 60 * 60).unwrap(); // Beijing + let t_now = chrono::Utc::now().with_timezone(&offset); + let fmt = format!( + "%Y{}%m{}%d{}%H{}%M{}%S{}%f", + delimiter, delimiter, delimiter, delimiter, delimiter, delimiter + ); + t_now.format(&fmt).to_string() +} + +pub const SKELETON: [(usize, usize); 16] = [ + (0, 1), + (0, 2), + (1, 3), + (2, 4), + (5, 6), + (5, 11), + (6, 12), + (11, 12), + (5, 7), + (6, 8), + (7, 9), + (8, 10), + (11, 13), + (12, 14), + (13, 15), + (14, 16), +]; + +pub fn check_font(font: &str) -> rusttype::Font<'static> { + // check then load font + + // ultralytics font path + let font_path_config = match dirs::config_dir() { + Some(mut d) => { + d.push("Ultralytics"); + d.push(font); + d + } + None => panic!("Unsupported operating system. Now support Linux, MacOS, Windows."), + }; + + // current font path + let font_path_current = std::path::PathBuf::from(font); + + // check font + let font_path = if font_path_config.exists() { + font_path_config + } else if font_path_current.exists() { + font_path_current + } else { + println!("Downloading font..."); + let source_url = "https://ultralytics.com/assets/Arial.ttf"; + let resp = ureq::get(source_url) + .timeout(std::time::Duration::from_secs(500)) + .call() + .unwrap_or_else(|err| panic!("> Failed to download font: {source_url}: {err:?}")); + + // read to buffer + let mut buffer = vec![]; + let total_size = resp + .header("Content-Length") + .and_then(|s| s.parse::().ok()) + .unwrap(); + let _reader = resp + .into_reader() + .take(total_size) + .read_to_end(&mut buffer) + .unwrap(); + + // save + let _path = std::fs::File::create(font).unwrap(); + let mut writer = std::io::BufWriter::new(_path); + writer.write_all(&buffer).unwrap(); + println!("Font saved at: {:?}", font_path_current.display()); + font_path_current + }; + + // load font + let buffer = std::fs::read(font_path).unwrap(); + rusttype::Font::try_from_vec(buffer).unwrap() +} diff --git a/examples/YOLOv8-ONNXRuntime-Rust/src/main.rs b/examples/YOLOv8-ONNXRuntime-Rust/src/main.rs new file mode 100644 index 0000000..8dd1567 --- /dev/null +++ b/examples/YOLOv8-ONNXRuntime-Rust/src/main.rs @@ -0,0 +1,28 @@ +use clap::Parser; + +use yolov8_rs::{Args, YOLOv8}; + +fn main() -> Result<(), Box> { + let args = Args::parse(); + + // 1. load image + let x = image::io::Reader::open(&args.source)? + .with_guessed_format()? + .decode()?; + + // 2. model support dynamic batch inference, so input should be a Vec + let xs = vec![x]; + + // You can test `--batch 2` with this + // let xs = vec![x.clone(), x]; + + // 3. build yolov8 model + let mut model = YOLOv8::new(args)?; + model.summary(); // model info + + // 4. run + let ys = model.run(&xs)?; + println!("{:?}", ys); + + Ok(()) +} diff --git a/examples/YOLOv8-ONNXRuntime-Rust/src/model.rs b/examples/YOLOv8-ONNXRuntime-Rust/src/model.rs new file mode 100644 index 0000000..1c0e5e4 --- /dev/null +++ b/examples/YOLOv8-ONNXRuntime-Rust/src/model.rs @@ -0,0 +1,642 @@ +#![allow(clippy::type_complexity)] + +use anyhow::Result; +use image::{DynamicImage, GenericImageView, ImageBuffer}; +use ndarray::{s, Array, Axis, IxDyn}; +use rand::{thread_rng, Rng}; +use std::path::PathBuf; + +use crate::{ + check_font, gen_time_string, non_max_suppression, Args, Batch, Bbox, Embedding, OrtBackend, + OrtConfig, OrtEP, Point2, YOLOResult, YOLOTask, SKELETON, +}; + +pub struct YOLOv8 { + // YOLOv8 model for all yolo-tasks + engine: OrtBackend, + nc: u32, + nk: u32, + nm: u32, + height: u32, + width: u32, + batch: u32, + task: YOLOTask, + conf: f32, + kconf: f32, + iou: f32, + names: Vec, + color_palette: Vec<(u8, u8, u8)>, + profile: bool, + plot: bool, +} + +impl YOLOv8 { + pub fn new(config: Args) -> Result { + // execution provider + let ep = if config.trt { + OrtEP::Trt(config.device_id) + } else if config.cuda { + OrtEP::Cuda(config.device_id) + } else { + OrtEP::Cpu + }; + + // batch + let batch = Batch { + opt: config.batch, + min: config.batch_min, + max: config.batch_max, + }; + + // build ort engine + let ort_args = OrtConfig { + ep, + batch, + f: config.model, + task: config.task, + trt_fp16: config.fp16, + image_size: (config.height, config.width), + }; + let engine = OrtBackend::build(ort_args)?; + + // get batch, height, width, tasks, nc, nk, nm + let (batch, height, width, task) = ( + engine.batch(), + engine.height(), + engine.width(), + engine.task(), + ); + let nc = engine.nc().or(config.nc).unwrap_or_else(|| { + panic!("Failed to get num_classes, make it explicit with `--nc`"); + }); + let (nk, nm) = match task { + YOLOTask::Pose => { + let nk = engine.nk().or(config.nk).unwrap_or_else(|| { + panic!("Failed to get num_keypoints, make it explicit with `--nk`"); + }); + (nk, 0) + } + YOLOTask::Segment => { + let nm = engine.nm().or(config.nm).unwrap_or_else(|| { + panic!("Failed to get num_masks, make it explicit with `--nm`"); + }); + (0, nm) + } + _ => (0, 0), + }; + + // class names + let names = engine.names().unwrap_or(vec!["Unknown".to_string()]); + + // color palette + let mut rng = thread_rng(); + let color_palette: Vec<_> = names + .iter() + .map(|_| { + ( + rng.gen_range(0..=255), + rng.gen_range(0..=255), + rng.gen_range(0..=255), + ) + }) + .collect(); + + Ok(Self { + engine, + names, + conf: config.conf, + kconf: config.kconf, + iou: config.iou, + color_palette, + profile: config.profile, + plot: config.plot, + nc, + nk, + nm, + height, + width, + batch, + task, + }) + } + + pub fn scale_wh(&self, w0: f32, h0: f32, w1: f32, h1: f32) -> (f32, f32, f32) { + let r = (w1 / w0).min(h1 / h0); + (r, (w0 * r).round(), (h0 * r).round()) + } + + pub fn preprocess(&mut self, xs: &Vec) -> Result> { + let mut ys = + Array::ones((xs.len(), 3, self.height() as usize, self.width() as usize)).into_dyn(); + ys.fill(144.0 / 255.0); + for (idx, x) in xs.iter().enumerate() { + let img = match self.task() { + YOLOTask::Classify => x.resize_exact( + self.width(), + self.height(), + image::imageops::FilterType::Triangle, + ), + _ => { + let (w0, h0) = x.dimensions(); + let w0 = w0 as f32; + let h0 = h0 as f32; + let (_, w_new, h_new) = + self.scale_wh(w0, h0, self.width() as f32, self.height() as f32); // f32 round + x.resize_exact( + w_new as u32, + h_new as u32, + if let YOLOTask::Segment = self.task() { + image::imageops::FilterType::CatmullRom + } else { + image::imageops::FilterType::Triangle + }, + ) + } + }; + + for (x, y, rgb) in img.pixels() { + let x = x as usize; + let y = y as usize; + let [r, g, b, _] = rgb.0; + ys[[idx, 0, y, x]] = (r as f32) / 255.0; + ys[[idx, 1, y, x]] = (g as f32) / 255.0; + ys[[idx, 2, y, x]] = (b as f32) / 255.0; + } + } + + Ok(ys) + } + + pub fn run(&mut self, xs: &Vec) -> Result> { + // pre-process + let t_pre = std::time::Instant::now(); + let xs_ = self.preprocess(xs)?; + if self.profile { + println!("[Model Preprocess]: {:?}", t_pre.elapsed()); + } + + // run + let t_run = std::time::Instant::now(); + let ys = self.engine.run(xs_, self.profile)?; + if self.profile { + println!("[Model Inference]: {:?}", t_run.elapsed()); + } + + // post-process + let t_post = std::time::Instant::now(); + let ys = self.postprocess(ys, xs)?; + if self.profile { + println!("[Model Postprocess]: {:?}", t_post.elapsed()); + } + + // plot and save + if self.plot { + self.plot_and_save(&ys, xs, Some(&SKELETON)); + } + Ok(ys) + } + + pub fn postprocess( + &self, + xs: Vec>, + xs0: &[DynamicImage], + ) -> Result> { + if let YOLOTask::Classify = self.task() { + let mut ys = Vec::new(); + let preds = &xs[0]; + for batch in preds.axis_iter(Axis(0)) { + ys.push(YOLOResult::new( + Some(Embedding::new(batch.into_owned())), + None, + None, + None, + )); + } + Ok(ys) + } else { + const CXYWH_OFFSET: usize = 4; // cxcywh + const KPT_STEP: usize = 3; // xyconf + let preds = &xs[0]; + let protos = { + if xs.len() > 1 { + Some(&xs[1]) + } else { + None + } + }; + let mut ys = Vec::new(); + for (idx, anchor) in preds.axis_iter(Axis(0)).enumerate() { + // [bs, 4 + nc + nm, anchors] + // input image + let width_original = xs0[idx].width() as f32; + let height_original = xs0[idx].height() as f32; + let ratio = (self.width() as f32 / width_original) + .min(self.height() as f32 / height_original); + + // save each result + let mut data: Vec<(Bbox, Option>, Option>)> = Vec::new(); + for pred in anchor.axis_iter(Axis(1)) { + // split preds for different tasks + let bbox = pred.slice(s![0..CXYWH_OFFSET]); + let clss = pred.slice(s![CXYWH_OFFSET..CXYWH_OFFSET + self.nc() as usize]); + let kpts = { + if let YOLOTask::Pose = self.task() { + Some(pred.slice(s![pred.len() - KPT_STEP * self.nk() as usize..])) + } else { + None + } + }; + let coefs = { + if let YOLOTask::Segment = self.task() { + Some(pred.slice(s![pred.len() - self.nm() as usize..]).to_vec()) + } else { + None + } + }; + + // confidence and id + let (id, &confidence) = clss + .into_iter() + .enumerate() + .reduce(|max, x| if x.1 > max.1 { x } else { max }) + .unwrap(); // definitely will not panic! + + // confidence filter + if confidence < self.conf { + continue; + } + + // bbox re-scale + let cx = bbox[0] / ratio; + let cy = bbox[1] / ratio; + let w = bbox[2] / ratio; + let h = bbox[3] / ratio; + let x = cx - w / 2.; + let y = cy - h / 2.; + let y_bbox = Bbox::new( + x.max(0.0f32).min(width_original), + y.max(0.0f32).min(height_original), + w, + h, + id, + confidence, + ); + + // kpts + let y_kpts = { + if let Some(kpts) = kpts { + let mut kpts_ = Vec::new(); + // rescale + for i in 0..self.nk() as usize { + let kx = kpts[KPT_STEP * i] / ratio; + let ky = kpts[KPT_STEP * i + 1] / ratio; + let kconf = kpts[KPT_STEP * i + 2]; + if kconf < self.kconf { + kpts_.push(Point2::default()); + } else { + kpts_.push(Point2::new_with_conf( + kx.max(0.0f32).min(width_original), + ky.max(0.0f32).min(height_original), + kconf, + )); + } + } + Some(kpts_) + } else { + None + } + }; + + // data merged + data.push((y_bbox, y_kpts, coefs)); + } + + // nms + non_max_suppression(&mut data, self.iou); + + // decode + let mut y_bboxes: Vec = Vec::new(); + let mut y_kpts: Vec> = Vec::new(); + let mut y_masks: Vec> = Vec::new(); + for elem in data.into_iter() { + if let Some(kpts) = elem.1 { + y_kpts.push(kpts) + } + + // decode masks + if let Some(coefs) = elem.2 { + let proto = protos.unwrap().slice(s![idx, .., .., ..]); + let (nm, nh, nw) = proto.dim(); + + // coefs * proto -> mask + let coefs = Array::from_shape_vec((1, nm), coefs)?; // (n, nm) + let proto = proto.to_owned().into_shape((nm, nh * nw))?; // (nm, nh*nw) + let mask = coefs.dot(&proto).into_shape((nh, nw, 1))?; // (nh, nw, n) + + // build image from ndarray + let mask_im: ImageBuffer, Vec> = + match ImageBuffer::from_raw(nw as u32, nh as u32, mask.into_raw_vec()) { + Some(image) => image, + None => panic!("can not create image from ndarray"), + }; + let mut mask_im = image::DynamicImage::from(mask_im); // -> dyn + + // rescale masks + let (_, w_mask, h_mask) = + self.scale_wh(width_original, height_original, nw as f32, nh as f32); + let mask_cropped = mask_im.crop(0, 0, w_mask as u32, h_mask as u32); + let mask_original = mask_cropped.resize_exact( + // resize_to_fill + width_original as u32, + height_original as u32, + match self.task() { + YOLOTask::Segment => image::imageops::FilterType::CatmullRom, + _ => image::imageops::FilterType::Triangle, + }, + ); + + // crop-mask with bbox + let mut mask_original_cropped = mask_original.into_luma8(); + for y in 0..height_original as usize { + for x in 0..width_original as usize { + if x < elem.0.xmin() as usize + || x > elem.0.xmax() as usize + || y < elem.0.ymin() as usize + || y > elem.0.ymax() as usize + { + mask_original_cropped.put_pixel( + x as u32, + y as u32, + image::Luma([0u8]), + ); + } + } + } + y_masks.push(mask_original_cropped.into_raw()); + } + y_bboxes.push(elem.0); + } + + // save each result + let y = YOLOResult { + probs: None, + bboxes: if !y_bboxes.is_empty() { + Some(y_bboxes) + } else { + None + }, + keypoints: if !y_kpts.is_empty() { + Some(y_kpts) + } else { + None + }, + masks: if !y_masks.is_empty() { + Some(y_masks) + } else { + None + }, + }; + ys.push(y); + } + + Ok(ys) + } + } + + pub fn plot_and_save( + &self, + ys: &[YOLOResult], + xs0: &[DynamicImage], + skeletons: Option<&[(usize, usize)]>, + ) { + // check font then load + let font = check_font("Arial.ttf"); + for (_idb, (img0, y)) in xs0.iter().zip(ys.iter()).enumerate() { + let mut img = img0.to_rgb8(); + + // draw for classifier + if let Some(probs) = y.probs() { + for (i, k) in probs.topk(5).iter().enumerate() { + let legend = format!("{} {:.2}%", self.names[k.0], k.1); + let scale = 32; + let legend_size = img.width().max(img.height()) / scale; + let x = img.width() / 20; + let y = img.height() / 20 + i as u32 * legend_size; + imageproc::drawing::draw_text_mut( + &mut img, + image::Rgb([0, 255, 0]), + x as i32, + y as i32, + rusttype::Scale::uniform(legend_size as f32 - 1.), + &font, + &legend, + ); + } + } + + // draw bboxes & keypoints + if let Some(bboxes) = y.bboxes() { + for (_idx, bbox) in bboxes.iter().enumerate() { + // rect + imageproc::drawing::draw_hollow_rect_mut( + &mut img, + imageproc::rect::Rect::at(bbox.xmin() as i32, bbox.ymin() as i32) + .of_size(bbox.width() as u32, bbox.height() as u32), + image::Rgb(self.color_palette[bbox.id()].into()), + ); + + // text + let legend = format!("{} {:.2}%", self.names[bbox.id()], bbox.confidence()); + let scale = 40; + let legend_size = img.width().max(img.height()) / scale; + imageproc::drawing::draw_text_mut( + &mut img, + image::Rgb(self.color_palette[bbox.id()].into()), + bbox.xmin() as i32, + (bbox.ymin() - legend_size as f32) as i32, + rusttype::Scale::uniform(legend_size as f32 - 1.), + &font, + &legend, + ); + } + } + + // draw kpts + if let Some(keypoints) = y.keypoints() { + for kpts in keypoints.iter() { + for kpt in kpts.iter() { + // filter + if kpt.confidence() < self.kconf { + continue; + } + + // draw point + imageproc::drawing::draw_filled_circle_mut( + &mut img, + (kpt.x() as i32, kpt.y() as i32), + 2, + image::Rgb([0, 255, 0]), + ); + } + + // draw skeleton if has + if let Some(skeletons) = skeletons { + for &(idx1, idx2) in skeletons.iter() { + let kpt1 = &kpts[idx1]; + let kpt2 = &kpts[idx2]; + if kpt1.confidence() < self.kconf || kpt2.confidence() < self.kconf { + continue; + } + imageproc::drawing::draw_line_segment_mut( + &mut img, + (kpt1.x(), kpt1.y()), + (kpt2.x(), kpt2.y()), + image::Rgb([233, 14, 57]), + ); + } + } + } + } + + // draw mask + if let Some(masks) = y.masks() { + for (mask, _bbox) in masks.iter().zip(y.bboxes().unwrap().iter()) { + let mask_nd: ImageBuffer, Vec> = + match ImageBuffer::from_vec(img.width(), img.height(), mask.to_vec()) { + Some(image) => image, + None => panic!("can not crate image from ndarray"), + }; + + for _x in 0..img.width() { + for _y in 0..img.height() { + let mask_p = imageproc::drawing::Canvas::get_pixel(&mask_nd, _x, _y); + if mask_p.0[0] > 0 { + let mut img_p = imageproc::drawing::Canvas::get_pixel(&img, _x, _y); + // img_p.0[2] = self.color_palette[bbox.id()].2 / 2; + // img_p.0[1] = self.color_palette[bbox.id()].1 / 2; + // img_p.0[0] = self.color_palette[bbox.id()].0 / 2; + img_p.0[2] /= 2; + img_p.0[1] = 255 - (255 - img_p.0[2]) / 2; + img_p.0[0] /= 2; + imageproc::drawing::Canvas::draw_pixel(&mut img, _x, _y, img_p) + } + } + } + } + } + + // mkdir and save + let mut runs = PathBuf::from("runs"); + if !runs.exists() { + std::fs::create_dir_all(&runs).unwrap(); + } + runs.push(gen_time_string("-")); + let saveout = format!("{}.jpg", runs.to_str().unwrap()); + let _ = img.save(saveout); + } + } + + pub fn summary(&self) { + println!( + "\nSummary:\n\ + > Task: {:?}{}\n\ + > EP: {:?} {}\n\ + > Dtype: {:?}\n\ + > Batch: {} ({}), Height: {} ({}), Width: {} ({})\n\ + > nc: {} nk: {}, nm: {}, conf: {}, kconf: {}, iou: {}\n\ + ", + self.task(), + match self.engine.author().zip(self.engine.version()) { + Some((author, ver)) => format!(" ({} {})", author, ver), + None => String::from(""), + }, + self.engine.ep(), + if let OrtEP::Cpu = self.engine.ep() { + "" + } else { + "(May still fall back to CPU)" + }, + self.engine.dtype(), + self.batch(), + if self.engine.is_batch_dynamic() { + "Dynamic" + } else { + "Const" + }, + self.height(), + if self.engine.is_height_dynamic() { + "Dynamic" + } else { + "Const" + }, + self.width(), + if self.engine.is_width_dynamic() { + "Dynamic" + } else { + "Const" + }, + self.nc(), + self.nk(), + self.nm(), + self.conf, + self.kconf, + self.iou, + ); + } + + pub fn engine(&self) -> &OrtBackend { + &self.engine + } + + pub fn conf(&self) -> f32 { + self.conf + } + + pub fn set_conf(&mut self, val: f32) { + self.conf = val; + } + + pub fn conf_mut(&mut self) -> &mut f32 { + &mut self.conf + } + + pub fn kconf(&self) -> f32 { + self.kconf + } + + pub fn iou(&self) -> f32 { + self.iou + } + + pub fn task(&self) -> &YOLOTask { + &self.task + } + + pub fn batch(&self) -> u32 { + self.batch + } + + pub fn width(&self) -> u32 { + self.width + } + + pub fn height(&self) -> u32 { + self.height + } + + pub fn nc(&self) -> u32 { + self.nc + } + + pub fn nk(&self) -> u32 { + self.nk + } + + pub fn nm(&self) -> u32 { + self.nm + } + + pub fn names(&self) -> &Vec { + &self.names + } +} diff --git a/examples/YOLOv8-ONNXRuntime-Rust/src/ort_backend.rs b/examples/YOLOv8-ONNXRuntime-Rust/src/ort_backend.rs new file mode 100644 index 0000000..5be93bd --- /dev/null +++ b/examples/YOLOv8-ONNXRuntime-Rust/src/ort_backend.rs @@ -0,0 +1,534 @@ +use anyhow::Result; +use clap::ValueEnum; +use half::f16; +use ndarray::{Array, CowArray, IxDyn}; +use ort::execution_providers::{CUDAExecutionProviderOptions, TensorRTExecutionProviderOptions}; +use ort::tensor::TensorElementDataType; +use ort::{Environment, ExecutionProvider, Session, SessionBuilder, Value}; +use regex::Regex; + +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, ValueEnum)] +pub enum YOLOTask { + // YOLO tasks + Classify, + Detect, + Pose, + Segment, +} + +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] +pub enum OrtEP { + // ONNXRuntime execution provider + Cpu, + Cuda(u32), + Trt(u32), +} + +#[derive(Debug)] +pub struct Batch { + pub opt: u32, + pub min: u32, + pub max: u32, +} + +impl Default for Batch { + fn default() -> Self { + Self { + opt: 1, + min: 1, + max: 1, + } + } +} + +#[derive(Debug, Default)] +pub struct OrtInputs { + // ONNX model inputs attrs + pub shapes: Vec>, + pub dtypes: Vec, + pub names: Vec, + pub sizes: Vec>, +} + +impl OrtInputs { + pub fn new(session: &Session) -> Self { + let mut shapes = Vec::new(); + let mut dtypes = Vec::new(); + let mut names = Vec::new(); + for i in session.inputs.iter() { + let shape: Vec = i + .dimensions() + .map(|x| if let Some(x) = x { x as i32 } else { -1i32 }) + .collect(); + shapes.push(shape); + dtypes.push(i.input_type); + names.push(i.name.clone()); + } + Self { + shapes, + dtypes, + names, + ..Default::default() + } + } +} + +#[derive(Debug)] +pub struct OrtConfig { + // ORT config + pub f: String, + pub task: Option, + pub ep: OrtEP, + pub trt_fp16: bool, + pub batch: Batch, + pub image_size: (Option, Option), +} + +#[derive(Debug)] +pub struct OrtBackend { + // ORT engine + session: Session, + task: YOLOTask, + ep: OrtEP, + batch: Batch, + inputs: OrtInputs, +} + +impl OrtBackend { + pub fn build(args: OrtConfig) -> Result { + // build env & session + let env = Environment::builder() + .with_name("YOLOv8") + .with_log_level(ort::LoggingLevel::Verbose) + .build()? + .into_arc(); + let session = SessionBuilder::new(&env)?.with_model_from_file(&args.f)?; + + // get inputs + let mut inputs = OrtInputs::new(&session); + + // batch size + let mut batch = args.batch; + let batch = if inputs.shapes[0][0] == -1 { + batch + } else { + assert_eq!( + inputs.shapes[0][0] as u32, batch.opt, + "Expected batch size: {}, got {}. Try using `--batch {}`.", + inputs.shapes[0][0] as u32, batch.opt, inputs.shapes[0][0] as u32 + ); + batch.opt = inputs.shapes[0][0] as u32; + batch + }; + + // input size: height and width + let height = if inputs.shapes[0][2] == -1 { + match args.image_size.0 { + Some(height) => height, + None => panic!("Failed to get model height. Make it explicit with `--height`"), + } + } else { + inputs.shapes[0][2] as u32 + }; + let width = if inputs.shapes[0][3] == -1 { + match args.image_size.1 { + Some(width) => width, + None => panic!("Failed to get model width. Make it explicit with `--width`"), + } + } else { + inputs.shapes[0][3] as u32 + }; + inputs.sizes.push(vec![height, width]); + + // build provider + let (ep, provider) = match args.ep { + OrtEP::Cuda(device_id) => Self::set_ep_cuda(device_id), + OrtEP::Trt(device_id) => Self::set_ep_trt(device_id, args.trt_fp16, &batch, &inputs), + _ => (OrtEP::Cpu, ExecutionProvider::CPU(Default::default())), + }; + + // build session again with the new provider + let session = SessionBuilder::new(&env)? + // .with_optimization_level(ort::GraphOptimizationLevel::Level3)? + .with_execution_providers([provider])? + .with_model_from_file(args.f)?; + + // task: using given one or guessing + let task = match args.task { + Some(task) => task, + None => match session.metadata() { + Err(_) => panic!("No metadata found. Try making it explicit by `--task`"), + Ok(metadata) => match metadata.custom("task") { + Err(_) => panic!("Can not get custom value. Try making it explicit by `--task`"), + Ok(value) => match value { + None => panic!("No correspoing value of `task` found in metadata. Make it explicit by `--task`"), + Some(task) => match task.as_str() { + "classify" => YOLOTask::Classify, + "detect" => YOLOTask::Detect, + "pose" => YOLOTask::Pose, + "segment" => YOLOTask::Segment, + x => todo!("{:?} is not supported for now!", x), + }, + }, + }, + }, + }; + + Ok(Self { + session, + task, + ep, + batch, + inputs, + }) + } + + pub fn fetch_inputs_from_session( + session: &Session, + ) -> (Vec>, Vec, Vec) { + // get inputs attrs from ONNX model + let mut shapes = Vec::new(); + let mut dtypes = Vec::new(); + let mut names = Vec::new(); + for i in session.inputs.iter() { + let shape: Vec = i + .dimensions() + .map(|x| if let Some(x) = x { x as i32 } else { -1i32 }) + .collect(); + shapes.push(shape); + dtypes.push(i.input_type); + names.push(i.name.clone()); + } + (shapes, dtypes, names) + } + + pub fn set_ep_cuda(device_id: u32) -> (OrtEP, ExecutionProvider) { + // set CUDA + if ExecutionProvider::CUDA(Default::default()).is_available() { + ( + OrtEP::Cuda(device_id), + ExecutionProvider::CUDA(CUDAExecutionProviderOptions { + device_id, + ..Default::default() + }), + ) + } else { + println!("> CUDA is not available! Using CPU."); + (OrtEP::Cpu, ExecutionProvider::CPU(Default::default())) + } + } + + pub fn set_ep_trt( + device_id: u32, + fp16: bool, + batch: &Batch, + inputs: &OrtInputs, + ) -> (OrtEP, ExecutionProvider) { + // set TensorRT + if ExecutionProvider::TensorRT(Default::default()).is_available() { + let (height, width) = (inputs.sizes[0][0], inputs.sizes[0][1]); + + // dtype match checking + if inputs.dtypes[0] == TensorElementDataType::Float16 && !fp16 { + panic!( + "Dtype mismatch! Expected: Float32, got: {:?}. You should use `--fp16`", + inputs.dtypes[0] + ); + } + + // dynamic shape: input_tensor_1:dim_1xdim_2x...,input_tensor_2:dim_3xdim_4x...,... + let mut opt_string = String::new(); + let mut min_string = String::new(); + let mut max_string = String::new(); + for name in inputs.names.iter() { + let s_opt = format!("{}:{}x3x{}x{},", name, batch.opt, height, width); + let s_min = format!("{}:{}x3x{}x{},", name, batch.min, height, width); + let s_max = format!("{}:{}x3x{}x{},", name, batch.max, height, width); + opt_string.push_str(s_opt.as_str()); + min_string.push_str(s_min.as_str()); + max_string.push_str(s_max.as_str()); + } + let _ = opt_string.pop(); + let _ = min_string.pop(); + let _ = max_string.pop(); + ( + OrtEP::Trt(device_id), + ExecutionProvider::TensorRT(TensorRTExecutionProviderOptions { + device_id, + fp16_enable: fp16, + timing_cache_enable: true, + profile_min_shapes: min_string, + profile_max_shapes: max_string, + profile_opt_shapes: opt_string, + ..Default::default() + }), + ) + } else { + println!("> TensorRT is not available! Try using CUDA..."); + Self::set_ep_cuda(device_id) + } + } + + pub fn fetch_from_metadata(&self, key: &str) -> Option { + // fetch value from onnx model file by key + match self.session.metadata() { + Err(_) => None, + Ok(metadata) => match metadata.custom(key) { + Err(_) => None, + Ok(value) => value, + }, + } + } + + pub fn run(&self, xs: Array, profile: bool) -> Result>> { + // ORT inference + match self.dtype() { + TensorElementDataType::Float16 => self.run_fp16(xs, profile), + TensorElementDataType::Float32 => self.run_fp32(xs, profile), + _ => todo!(), + } + } + + pub fn run_fp16(&self, xs: Array, profile: bool) -> Result>> { + // f32->f16 + let t = std::time::Instant::now(); + let xs = xs.mapv(f16::from_f32); + if profile { + println!("[ORT f32->f16]: {:?}", t.elapsed()); + } + + // h2d + let t = std::time::Instant::now(); + let xs = CowArray::from(xs); + let xs = vec![Value::from_array(self.session.allocator(), &xs)?]; + if profile { + println!("[ORT H2D]: {:?}", t.elapsed()); + } + + // run + let t = std::time::Instant::now(); + let ys = self.session.run(xs)?; + if profile { + println!("[ORT Inference]: {:?}", t.elapsed()); + } + + // d2h + Ok(ys + .iter() + .map(|x| { + // d2h + let t = std::time::Instant::now(); + let x = x.try_extract::<_>().unwrap().view().clone().into_owned(); + if profile { + println!("[ORT D2H]: {:?}", t.elapsed()); + } + + // f16->f32 + let t_ = std::time::Instant::now(); + let x = x.mapv(f16::to_f32); + if profile { + println!("[ORT f16->f32]: {:?}", t_.elapsed()); + } + x + }) + .collect::>>()) + } + + pub fn run_fp32(&self, xs: Array, profile: bool) -> Result>> { + // h2d + let t = std::time::Instant::now(); + let xs = CowArray::from(xs); + let xs = vec![Value::from_array(self.session.allocator(), &xs)?]; + if profile { + println!("[ORT H2D]: {:?}", t.elapsed()); + } + + // run + let t = std::time::Instant::now(); + let ys = self.session.run(xs)?; + if profile { + println!("[ORT Inference]: {:?}", t.elapsed()); + } + + // d2h + Ok(ys + .iter() + .map(|x| { + let t = std::time::Instant::now(); + let x = x.try_extract::<_>().unwrap().view().clone().into_owned(); + if profile { + println!("[ORT D2H]: {:?}", t.elapsed()); + } + x + }) + .collect::>>()) + } + + pub fn output_shapes(&self) -> Vec> { + let mut shapes = Vec::new(); + for o in &self.session.outputs { + let shape: Vec<_> = o + .dimensions() + .map(|x| if let Some(x) = x { x as i32 } else { -1i32 }) + .collect(); + shapes.push(shape); + } + shapes + } + + pub fn output_dtypes(&self) -> Vec { + let mut dtypes = Vec::new(); + self.session + .outputs + .iter() + .for_each(|x| dtypes.push(x.output_type)); + dtypes + } + + pub fn input_shapes(&self) -> &Vec> { + &self.inputs.shapes + } + + pub fn input_names(&self) -> &Vec { + &self.inputs.names + } + + pub fn input_dtypes(&self) -> &Vec { + &self.inputs.dtypes + } + + pub fn dtype(&self) -> TensorElementDataType { + self.input_dtypes()[0] + } + + pub fn height(&self) -> u32 { + self.inputs.sizes[0][0] + } + + pub fn width(&self) -> u32 { + self.inputs.sizes[0][1] + } + + pub fn is_height_dynamic(&self) -> bool { + self.input_shapes()[0][2] == -1 + } + + pub fn is_width_dynamic(&self) -> bool { + self.input_shapes()[0][3] == -1 + } + + pub fn batch(&self) -> u32 { + self.batch.opt + } + + pub fn is_batch_dynamic(&self) -> bool { + self.input_shapes()[0][0] == -1 + } + + pub fn ep(&self) -> &OrtEP { + &self.ep + } + + pub fn task(&self) -> YOLOTask { + self.task.clone() + } + + pub fn names(&self) -> Option> { + // class names, metadata parsing + // String format: `{0: 'person', 1: 'bicycle', 2: 'sports ball', ..., 27: "yellow_lady's_slipper"}` + match self.fetch_from_metadata("names") { + Some(names) => { + let re = Regex::new(r#"(['"])([-()\w '"]+)(['"])"#).unwrap(); + let mut names_ = vec![]; + for (_, [_, name, _]) in re.captures_iter(&names).map(|x| x.extract()) { + names_.push(name.to_string()); + } + Some(names_) + } + None => None, + } + } + + pub fn nk(&self) -> Option { + // num_keypoints, metadata parsing: String `nk` in onnx model: `[17, 3]` + match self.fetch_from_metadata("kpt_shape") { + None => None, + Some(kpt_string) => { + let re = Regex::new(r"([0-9]+), ([0-9]+)").unwrap(); + let caps = re.captures(&kpt_string).unwrap(); + Some(caps.get(1).unwrap().as_str().parse::().unwrap()) + } + } + } + + pub fn nc(&self) -> Option { + // num_classes + match self.names() { + // by names + Some(names) => Some(names.len() as u32), + None => match self.task() { + // by task calculation + YOLOTask::Classify => Some(self.output_shapes()[0][1] as u32), + YOLOTask::Detect => { + if self.output_shapes()[0][1] == -1 { + None + } else { + // cxywhclss + Some(self.output_shapes()[0][1] as u32 - 4) + } + } + YOLOTask::Pose => { + match self.nk() { + None => None, + Some(nk) => { + if self.output_shapes()[0][1] == -1 { + None + } else { + // cxywhclss3*kpt + Some(self.output_shapes()[0][1] as u32 - 4 - 3 * nk) + } + } + } + } + YOLOTask::Segment => { + if self.output_shapes()[0][1] == -1 { + None + } else { + // cxywhclssnm + Some((self.output_shapes()[0][1] - self.output_shapes()[1][1]) as u32 - 4) + } + } + }, + } + } + + pub fn nm(&self) -> Option { + // num_masks + match self.task() { + YOLOTask::Segment => Some(self.output_shapes()[1][1] as u32), + _ => None, + } + } + + pub fn na(&self) -> Option { + // num_anchors + match self.task() { + YOLOTask::Segment | YOLOTask::Detect | YOLOTask::Pose => { + if self.output_shapes()[0][2] == -1 { + None + } else { + Some(self.output_shapes()[0][2] as u32) + } + } + _ => None, + } + } + + pub fn author(&self) -> Option { + self.fetch_from_metadata("author") + } + + pub fn version(&self) -> Option { + self.fetch_from_metadata("version") + } +} diff --git a/examples/YOLOv8-ONNXRuntime-Rust/src/yolo_result.rs b/examples/YOLOv8-ONNXRuntime-Rust/src/yolo_result.rs new file mode 100644 index 0000000..2fcc6d8 --- /dev/null +++ b/examples/YOLOv8-ONNXRuntime-Rust/src/yolo_result.rs @@ -0,0 +1,235 @@ +use ndarray::{Array, Axis, IxDyn}; + +#[derive(Clone, PartialEq, Default)] +pub struct YOLOResult { + // YOLO tasks results of an image + pub probs: Option, + pub bboxes: Option>, + pub keypoints: Option>>, + pub masks: Option>>, +} + +impl std::fmt::Debug for YOLOResult { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("YOLOResult") + .field( + "Probs(top5)", + &format_args!("{:?}", self.probs().map(|probs| probs.topk(5))), + ) + .field("Bboxes", &self.bboxes) + .field("Keypoints", &self.keypoints) + .field( + "Masks", + &format_args!("{:?}", self.masks().map(|masks| masks.len())), + ) + .finish() + } +} + +impl YOLOResult { + pub fn new( + probs: Option, + bboxes: Option>, + keypoints: Option>>, + masks: Option>>, + ) -> Self { + Self { + probs, + bboxes, + keypoints, + masks, + } + } + + pub fn probs(&self) -> Option<&Embedding> { + self.probs.as_ref() + } + + pub fn keypoints(&self) -> Option<&Vec>> { + self.keypoints.as_ref() + } + + pub fn masks(&self) -> Option<&Vec>> { + self.masks.as_ref() + } + + pub fn bboxes(&self) -> Option<&Vec> { + self.bboxes.as_ref() + } + + pub fn bboxes_mut(&mut self) -> Option<&mut Vec> { + self.bboxes.as_mut() + } +} + +#[derive(Debug, PartialEq, Clone, Default)] +pub struct Point2 { + // A point2d with x, y, conf + x: f32, + y: f32, + confidence: f32, +} + +impl Point2 { + pub fn new_with_conf(x: f32, y: f32, confidence: f32) -> Self { + Self { x, y, confidence } + } + + pub fn new(x: f32, y: f32) -> Self { + Self { + x, + y, + ..Default::default() + } + } + + pub fn x(&self) -> f32 { + self.x + } + + pub fn y(&self) -> f32 { + self.y + } + + pub fn confidence(&self) -> f32 { + self.confidence + } +} + +#[derive(Debug, Clone, PartialEq, Default)] +pub struct Embedding { + // An float32 n-dims tensor + data: Array, +} + +impl Embedding { + pub fn new(data: Array) -> Self { + Self { data } + } + + pub fn data(&self) -> &Array { + &self.data + } + + pub fn topk(&self, k: usize) -> Vec<(usize, f32)> { + let mut probs = self + .data + .iter() + .enumerate() + .map(|(a, b)| (a, *b)) + .collect::>(); + probs.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap()); + let mut topk = Vec::new(); + for &(id, confidence) in probs.iter().take(k) { + topk.push((id, confidence)); + } + topk + } + + pub fn norm(&self) -> Array { + let std_ = self.data.mapv(|x| x * x).sum_axis(Axis(0)).mapv(f32::sqrt); + self.data.clone() / std_ + } + + pub fn top1(&self) -> (usize, f32) { + self.topk(1)[0] + } +} + +#[derive(Debug, Clone, PartialEq, Default)] +pub struct Bbox { + // a bounding box around an object + xmin: f32, + ymin: f32, + width: f32, + height: f32, + id: usize, + confidence: f32, +} + +impl Bbox { + pub fn new_from_xywh(xmin: f32, ymin: f32, width: f32, height: f32) -> Self { + Self { + xmin, + ymin, + width, + height, + ..Default::default() + } + } + + pub fn new(xmin: f32, ymin: f32, width: f32, height: f32, id: usize, confidence: f32) -> Self { + Self { + xmin, + ymin, + width, + height, + id, + confidence, + } + } + + pub fn width(&self) -> f32 { + self.width + } + + pub fn height(&self) -> f32 { + self.height + } + + pub fn xmin(&self) -> f32 { + self.xmin + } + + pub fn ymin(&self) -> f32 { + self.ymin + } + + pub fn xmax(&self) -> f32 { + self.xmin + self.width + } + + pub fn ymax(&self) -> f32 { + self.ymin + self.height + } + + pub fn tl(&self) -> Point2 { + Point2::new(self.xmin, self.ymin) + } + + pub fn br(&self) -> Point2 { + Point2::new(self.xmax(), self.ymax()) + } + + pub fn cxcy(&self) -> Point2 { + Point2::new(self.xmin + self.width / 2., self.ymin + self.height / 2.) + } + + pub fn id(&self) -> usize { + self.id + } + + pub fn confidence(&self) -> f32 { + self.confidence + } + + pub fn area(&self) -> f32 { + self.width * self.height + } + + pub fn intersection_area(&self, another: &Bbox) -> f32 { + let l = self.xmin.max(another.xmin); + let r = (self.xmin + self.width).min(another.xmin + another.width); + let t = self.ymin.max(another.ymin); + let b = (self.ymin + self.height).min(another.ymin + another.height); + (r - l + 1.).max(0.) * (b - t + 1.).max(0.) + } + + pub fn union(&self, another: &Bbox) -> f32 { + self.area() + another.area() - self.intersection_area(another) + } + + pub fn iou(&self, another: &Bbox) -> f32 { + self.intersection_area(another) / self.union(another) + } +} diff --git a/examples/YOLOv8-ONNXRuntime/README.md b/examples/YOLOv8-ONNXRuntime/README.md new file mode 100644 index 0000000..b206b2e --- /dev/null +++ b/examples/YOLOv8-ONNXRuntime/README.md @@ -0,0 +1,43 @@ +# YOLOv8 - ONNX Runtime + +This project implements YOLOv8 using ONNX Runtime. + +## Installation + +To run this project, you need to install the required dependencies. The following instructions will guide you through the installation process. + +### Installing Required Dependencies + +You can install the required dependencies by running the following command: + +```bash +pip install -r requirements.txt +``` + +### Installing `onnxruntime-gpu` + +If you have an NVIDIA GPU and want to leverage GPU acceleration, you can install the onnxruntime-gpu package using the following command: + +```bash +pip install onnxruntime-gpu +``` + +Note: Make sure you have the appropriate GPU drivers installed on your system. + +### Installing `onnxruntime` (CPU version) + +If you don't have an NVIDIA GPU or prefer to use the CPU version of onnxruntime, you can install the onnxruntime package using the following command: + +```bash +pip install onnxruntime +``` + +### Usage + +After successfully installing the required packages, you can run the YOLOv8 implementation using the following command: + +```bash +python main.py --model yolov8n.onnx --img image.jpg --conf-thres 0.5 --iou-thres 0.5 +``` + +Make sure to replace yolov8n.onnx with the path to your YOLOv8 ONNX model file, image.jpg with the path to your input image, and adjust the confidence threshold (conf-thres) and IoU threshold (iou-thres) values as needed. diff --git a/examples/YOLOv8-ONNXRuntime/main.py b/examples/YOLOv8-ONNXRuntime/main.py new file mode 100644 index 0000000..e1e83f3 --- /dev/null +++ b/examples/YOLOv8-ONNXRuntime/main.py @@ -0,0 +1,231 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import argparse + +import cv2 +import numpy as np +import onnxruntime as ort +import torch + +from ultralytics.utils import ASSETS, yaml_load +from ultralytics.utils.checks import check_requirements, check_yaml + + +class YOLOv8: + """YOLOv8 object detection model class for handling inference and visualization.""" + + def __init__(self, onnx_model, input_image, confidence_thres, iou_thres): + """ + Initializes an instance of the YOLOv8 class. + + Args: + onnx_model: Path to the ONNX model. + input_image: Path to the input image. + confidence_thres: Confidence threshold for filtering detections. + iou_thres: IoU (Intersection over Union) threshold for non-maximum suppression. + """ + self.onnx_model = onnx_model + self.input_image = input_image + self.confidence_thres = confidence_thres + self.iou_thres = iou_thres + + # Load the class names from the COCO dataset + self.classes = yaml_load(check_yaml("coco128.yaml"))["names"] + + # Generate a color palette for the classes + self.color_palette = np.random.uniform(0, 255, size=(len(self.classes), 3)) + + def draw_detections(self, img, box, score, class_id): + """ + Draws bounding boxes and labels on the input image based on the detected objects. + + Args: + img: The input image to draw detections on. + box: Detected bounding box. + score: Corresponding detection score. + class_id: Class ID for the detected object. + + Returns: + None + """ + + # Extract the coordinates of the bounding box + x1, y1, w, h = box + + # Retrieve the color for the class ID + color = self.color_palette[class_id] + + # Draw the bounding box on the image + cv2.rectangle(img, (int(x1), int(y1)), (int(x1 + w), int(y1 + h)), color, 2) + + # Create the label text with class name and score + label = f"{self.classes[class_id]}: {score:.2f}" + + # Calculate the dimensions of the label text + (label_width, label_height), _ = cv2.getTextSize(label, cv2.FONT_HERSHEY_SIMPLEX, 0.5, 1) + + # Calculate the position of the label text + label_x = x1 + label_y = y1 - 10 if y1 - 10 > label_height else y1 + 10 + + # Draw a filled rectangle as the background for the label text + cv2.rectangle( + img, (label_x, label_y - label_height), (label_x + label_width, label_y + label_height), color, cv2.FILLED + ) + + # Draw the label text on the image + cv2.putText(img, label, (label_x, label_y), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 0, 0), 1, cv2.LINE_AA) + + def preprocess(self): + """ + Preprocesses the input image before performing inference. + + Returns: + image_data: Preprocessed image data ready for inference. + """ + # Read the input image using OpenCV + self.img = cv2.imread(self.input_image) + + # Get the height and width of the input image + self.img_height, self.img_width = self.img.shape[:2] + + # Convert the image color space from BGR to RGB + img = cv2.cvtColor(self.img, cv2.COLOR_BGR2RGB) + + # Resize the image to match the input shape + img = cv2.resize(img, (self.input_width, self.input_height)) + + # Normalize the image data by dividing it by 255.0 + image_data = np.array(img) / 255.0 + + # Transpose the image to have the channel dimension as the first dimension + image_data = np.transpose(image_data, (2, 0, 1)) # Channel first + + # Expand the dimensions of the image data to match the expected input shape + image_data = np.expand_dims(image_data, axis=0).astype(np.float32) + + # Return the preprocessed image data + return image_data + + def postprocess(self, input_image, output): + """ + Performs post-processing on the model's output to extract bounding boxes, scores, and class IDs. + + Args: + input_image (numpy.ndarray): The input image. + output (numpy.ndarray): The output of the model. + + Returns: + numpy.ndarray: The input image with detections drawn on it. + """ + + # Transpose and squeeze the output to match the expected shape + outputs = np.transpose(np.squeeze(output[0])) + + # Get the number of rows in the outputs array + rows = outputs.shape[0] + + # Lists to store the bounding boxes, scores, and class IDs of the detections + boxes = [] + scores = [] + class_ids = [] + + # Calculate the scaling factors for the bounding box coordinates + x_factor = self.img_width / self.input_width + y_factor = self.img_height / self.input_height + + # Iterate over each row in the outputs array + for i in range(rows): + # Extract the class scores from the current row + classes_scores = outputs[i][4:] + + # Find the maximum score among the class scores + max_score = np.amax(classes_scores) + + # If the maximum score is above the confidence threshold + if max_score >= self.confidence_thres: + # Get the class ID with the highest score + class_id = np.argmax(classes_scores) + + # Extract the bounding box coordinates from the current row + x, y, w, h = outputs[i][0], outputs[i][1], outputs[i][2], outputs[i][3] + + # Calculate the scaled coordinates of the bounding box + left = int((x - w / 2) * x_factor) + top = int((y - h / 2) * y_factor) + width = int(w * x_factor) + height = int(h * y_factor) + + # Add the class ID, score, and box coordinates to the respective lists + class_ids.append(class_id) + scores.append(max_score) + boxes.append([left, top, width, height]) + + # Apply non-maximum suppression to filter out overlapping bounding boxes + indices = cv2.dnn.NMSBoxes(boxes, scores, self.confidence_thres, self.iou_thres) + + # Iterate over the selected indices after non-maximum suppression + for i in indices: + # Get the box, score, and class ID corresponding to the index + box = boxes[i] + score = scores[i] + class_id = class_ids[i] + + # Draw the detection on the input image + self.draw_detections(input_image, box, score, class_id) + + # Return the modified input image + return input_image + + def main(self): + """ + Performs inference using an ONNX model and returns the output image with drawn detections. + + Returns: + output_img: The output image with drawn detections. + """ + # Create an inference session using the ONNX model and specify execution providers + session = ort.InferenceSession(self.onnx_model, providers=["CUDAExecutionProvider", "CPUExecutionProvider"]) + + # Get the model inputs + model_inputs = session.get_inputs() + + # Store the shape of the input for later use + input_shape = model_inputs[0].shape + self.input_width = input_shape[2] + self.input_height = input_shape[3] + + # Preprocess the image data + img_data = self.preprocess() + + # Run inference using the preprocessed image data + outputs = session.run(None, {model_inputs[0].name: img_data}) + + # Perform post-processing on the outputs to obtain output image. + return self.postprocess(self.img, outputs) # output image + + +if __name__ == "__main__": + # Create an argument parser to handle command-line arguments + parser = argparse.ArgumentParser() + parser.add_argument("--model", type=str, default="yolov8n.onnx", help="Input your ONNX model.") + parser.add_argument("--img", type=str, default=str(ASSETS / "bus.jpg"), help="Path to input image.") + parser.add_argument("--conf-thres", type=float, default=0.5, help="Confidence threshold") + parser.add_argument("--iou-thres", type=float, default=0.5, help="NMS IoU threshold") + args = parser.parse_args() + + # Check the requirements and select the appropriate backend (CPU or GPU) + check_requirements("onnxruntime-gpu" if torch.cuda.is_available() else "onnxruntime") + + # Create an instance of the YOLOv8 class with the specified arguments + detection = YOLOv8(args.model, args.img, args.conf_thres, args.iou_thres) + + # Perform object detection and obtain the output image + output_image = detection.main() + + # Display the output image in a window + cv2.namedWindow("Output", cv2.WINDOW_NORMAL) + cv2.imshow("Output", output_image) + + # Wait for a key press to exit + cv2.waitKey(0) diff --git a/examples/YOLOv8-OpenCV-ONNX-Python/README.md b/examples/YOLOv8-OpenCV-ONNX-Python/README.md new file mode 100644 index 0000000..c9076fa --- /dev/null +++ b/examples/YOLOv8-OpenCV-ONNX-Python/README.md @@ -0,0 +1,19 @@ +# YOLOv8 - OpenCV + +Implementation YOLOv8 on OpenCV using ONNX Format. + +Just simply clone and run + +```bash +pip install -r requirements.txt +python main.py --model yolov8n.onnx --img image.jpg +``` + +If you start from scratch: + +```bash +pip install ultralytics +yolo export model=yolov8n.pt imgsz=640 format=onnx opset=12 +``` + +_\*Make sure to include "opset=12"_ diff --git a/examples/YOLOv8-OpenCV-ONNX-Python/main.py b/examples/YOLOv8-OpenCV-ONNX-Python/main.py new file mode 100644 index 0000000..8d9c7a5 --- /dev/null +++ b/examples/YOLOv8-OpenCV-ONNX-Python/main.py @@ -0,0 +1,130 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import argparse + +import cv2.dnn +import numpy as np + +from ultralytics.utils import ASSETS, yaml_load +from ultralytics.utils.checks import check_yaml + +CLASSES = yaml_load(check_yaml("coco128.yaml"))["names"] +colors = np.random.uniform(0, 255, size=(len(CLASSES), 3)) + + +def draw_bounding_box(img, class_id, confidence, x, y, x_plus_w, y_plus_h): + """ + Draws bounding boxes on the input image based on the provided arguments. + + Args: + img (numpy.ndarray): The input image to draw the bounding box on. + class_id (int): Class ID of the detected object. + confidence (float): Confidence score of the detected object. + x (int): X-coordinate of the top-left corner of the bounding box. + y (int): Y-coordinate of the top-left corner of the bounding box. + x_plus_w (int): X-coordinate of the bottom-right corner of the bounding box. + y_plus_h (int): Y-coordinate of the bottom-right corner of the bounding box. + """ + label = f"{CLASSES[class_id]} ({confidence:.2f})" + color = colors[class_id] + cv2.rectangle(img, (x, y), (x_plus_w, y_plus_h), color, 2) + cv2.putText(img, label, (x - 10, y - 10), cv2.FONT_HERSHEY_SIMPLEX, 0.5, color, 2) + + +def main(onnx_model, input_image): + """ + Main function to load ONNX model, perform inference, draw bounding boxes, and display the output image. + + Args: + onnx_model (str): Path to the ONNX model. + input_image (str): Path to the input image. + + Returns: + list: List of dictionaries containing detection information such as class_id, class_name, confidence, etc. + """ + # Load the ONNX model + model: cv2.dnn.Net = cv2.dnn.readNetFromONNX(onnx_model) + + # Read the input image + original_image: np.ndarray = cv2.imread(input_image) + [height, width, _] = original_image.shape + + # Prepare a square image for inference + length = max((height, width)) + image = np.zeros((length, length, 3), np.uint8) + image[0:height, 0:width] = original_image + + # Calculate scale factor + scale = length / 640 + + # Preprocess the image and prepare blob for model + blob = cv2.dnn.blobFromImage(image, scalefactor=1 / 255, size=(640, 640), swapRB=True) + model.setInput(blob) + + # Perform inference + outputs = model.forward() + + # Prepare output array + outputs = np.array([cv2.transpose(outputs[0])]) + rows = outputs.shape[1] + + boxes = [] + scores = [] + class_ids = [] + + # Iterate through output to collect bounding boxes, confidence scores, and class IDs + for i in range(rows): + classes_scores = outputs[0][i][4:] + (minScore, maxScore, minClassLoc, (x, maxClassIndex)) = cv2.minMaxLoc(classes_scores) + if maxScore >= 0.25: + box = [ + outputs[0][i][0] - (0.5 * outputs[0][i][2]), + outputs[0][i][1] - (0.5 * outputs[0][i][3]), + outputs[0][i][2], + outputs[0][i][3], + ] + boxes.append(box) + scores.append(maxScore) + class_ids.append(maxClassIndex) + + # Apply NMS (Non-maximum suppression) + result_boxes = cv2.dnn.NMSBoxes(boxes, scores, 0.25, 0.45, 0.5) + + detections = [] + + # Iterate through NMS results to draw bounding boxes and labels + for i in range(len(result_boxes)): + index = result_boxes[i] + box = boxes[index] + detection = { + "class_id": class_ids[index], + "class_name": CLASSES[class_ids[index]], + "confidence": scores[index], + "box": box, + "scale": scale, + } + detections.append(detection) + draw_bounding_box( + original_image, + class_ids[index], + scores[index], + round(box[0] * scale), + round(box[1] * scale), + round((box[0] + box[2]) * scale), + round((box[1] + box[3]) * scale), + ) + + # Display the image with bounding boxes + cv2.imshow("image", original_image) + cv2.waitKey(0) + cv2.destroyAllWindows() + + return detections + + +if __name__ == "__main__": + parser = argparse.ArgumentParser() + parser.add_argument("--model", default="yolov8n.onnx", help="Input your ONNX model.") + parser.add_argument("--img", default=str(ASSETS / "bus.jpg"), help="Path to input image.") + args = parser.parse_args() + main(args.model, args.img) diff --git a/examples/YOLOv8-OpenCV-int8-tflite-Python/README.md b/examples/YOLOv8-OpenCV-int8-tflite-Python/README.md new file mode 100644 index 0000000..ea14e44 --- /dev/null +++ b/examples/YOLOv8-OpenCV-int8-tflite-Python/README.md @@ -0,0 +1,65 @@ +# YOLOv8 - Int8-TFLite Runtime + +Welcome to the YOLOv8 Int8 TFLite Runtime for efficient and optimized object detection project. This README provides comprehensive instructions for installing and using our YOLOv8 implementation. + +## Installation + +Ensure a smooth setup by following these steps to install necessary dependencies. + +### Installing Required Dependencies + +Install all required dependencies with this simple command: + +```bash +pip install -r requirements.txt +``` + +### Installing `tflite-runtime` + +To load TFLite models, install the `tflite-runtime` package using: + +```bash +pip install tflite-runtime +``` + +### Installing `tensorflow-gpu` (For NVIDIA GPU Users) + +Leverage GPU acceleration with NVIDIA GPUs by installing `tensorflow-gpu`: + +```bash +pip install tensorflow-gpu +``` + +**Note:** Ensure you have compatible GPU drivers installed on your system. + +### Installing `tensorflow` (CPU Version) + +For CPU usage or non-NVIDIA GPUs, install TensorFlow with: + +```bash +pip install tensorflow +``` + +## Usage + +Follow these instructions to run YOLOv8 after successful installation. + +Convert the YOLOv8 model to Int8 TFLite format: + +```bash +yolo export model=yolov8n.pt imgsz=640 format=tflite int8 +``` + +Locate the Int8 TFLite model in `yolov8n_saved_model`. Choose `best_full_integer_quant` or verify quantization at [Netron](https://netron.app/). Then, execute the following in your terminal: + +```bash +python main.py --model yolov8n_full_integer_quant.tflite --img image.jpg --conf-thres 0.5 --iou-thres 0.5 +``` + +Replace `best_full_integer_quant.tflite` with your model file's path, `image.jpg` with your input image, and adjust the confidence (conf-thres) and IoU thresholds (iou-thres) as necessary. + +### Output + +The output is displayed as annotated images, showcasing the model's detection capabilities: + +![image](https://github.com/wamiqraza/Attribute-recognition-and-reidentification-Market1501-dataset/blob/main/img/bus.jpg) diff --git a/examples/YOLOv8-OpenCV-int8-tflite-Python/main.py b/examples/YOLOv8-OpenCV-int8-tflite-Python/main.py new file mode 100644 index 0000000..53fba1f --- /dev/null +++ b/examples/YOLOv8-OpenCV-int8-tflite-Python/main.py @@ -0,0 +1,299 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import argparse + +import cv2 +import numpy as np +from tflite_runtime import interpreter as tflite + +from ultralytics.utils import ASSETS, yaml_load +from ultralytics.utils.checks import check_yaml + +# Declare as global variables, can be updated based trained model image size +img_width = 640 +img_height = 640 + + +class LetterBox: + def __init__( + self, new_shape=(img_width, img_height), auto=False, scaleFill=False, scaleup=True, center=True, stride=32 + ): + self.new_shape = new_shape + self.auto = auto + self.scaleFill = scaleFill + self.scaleup = scaleup + self.stride = stride + self.center = center # Put the image in the middle or top-left + + def __call__(self, labels=None, image=None): + """Return updated labels and image with added border.""" + + if labels is None: + labels = {} + img = labels.get("img") if image is None else image + shape = img.shape[:2] # current shape [height, width] + new_shape = labels.pop("rect_shape", self.new_shape) + if isinstance(new_shape, int): + new_shape = (new_shape, new_shape) + + # Scale ratio (new / old) + r = min(new_shape[0] / shape[0], new_shape[1] / shape[1]) + if not self.scaleup: # only scale down, do not scale up (for better val mAP) + r = min(r, 1.0) + + # Compute padding + ratio = r, r # width, height ratios + new_unpad = int(round(shape[1] * r)), int(round(shape[0] * r)) + dw, dh = new_shape[1] - new_unpad[0], new_shape[0] - new_unpad[1] # wh padding + if self.auto: # minimum rectangle + dw, dh = np.mod(dw, self.stride), np.mod(dh, self.stride) # wh padding + elif self.scaleFill: # stretch + dw, dh = 0.0, 0.0 + new_unpad = (new_shape[1], new_shape[0]) + ratio = new_shape[1] / shape[1], new_shape[0] / shape[0] # width, height ratios + + if self.center: + dw /= 2 # divide padding into 2 sides + dh /= 2 + + if shape[::-1] != new_unpad: # resize + img = cv2.resize(img, new_unpad, interpolation=cv2.INTER_LINEAR) + top, bottom = int(round(dh - 0.1)) if self.center else 0, int(round(dh + 0.1)) + left, right = int(round(dw - 0.1)) if self.center else 0, int(round(dw + 0.1)) + img = cv2.copyMakeBorder( + img, top, bottom, left, right, cv2.BORDER_CONSTANT, value=(114, 114, 114) + ) # add border + if labels.get("ratio_pad"): + labels["ratio_pad"] = (labels["ratio_pad"], (left, top)) # for evaluation + + if len(labels): + labels = self._update_labels(labels, ratio, dw, dh) + labels["img"] = img + labels["resized_shape"] = new_shape + return labels + else: + return img + + def _update_labels(self, labels, ratio, padw, padh): + """Update labels.""" + + labels["instances"].convert_bbox(format="xyxy") + labels["instances"].denormalize(*labels["img"].shape[:2][::-1]) + labels["instances"].scale(*ratio) + labels["instances"].add_padding(padw, padh) + return labels + + +class Yolov8TFLite: + def __init__(self, tflite_model, input_image, confidence_thres, iou_thres): + """ + Initializes an instance of the Yolov8TFLite class. + + Args: + tflite_model: Path to the TFLite model. + input_image: Path to the input image. + confidence_thres: Confidence threshold for filtering detections. + iou_thres: IoU (Intersection over Union) threshold for non-maximum suppression. + """ + + self.tflite_model = tflite_model + self.input_image = input_image + self.confidence_thres = confidence_thres + self.iou_thres = iou_thres + + # Load the class names from the COCO dataset + self.classes = yaml_load(check_yaml("coco128.yaml"))["names"] + + # Generate a color palette for the classes + self.color_palette = np.random.uniform(0, 255, size=(len(self.classes), 3)) + + def draw_detections(self, img, box, score, class_id): + """ + Draws bounding boxes and labels on the input image based on the detected objects. + + Args: + img: The input image to draw detections on. + box: Detected bounding box. + score: Corresponding detection score. + class_id: Class ID for the detected object. + + Returns: + None + """ + + # Extract the coordinates of the bounding box + x1, y1, w, h = box + + # Retrieve the color for the class ID + color = self.color_palette[class_id] + + # Draw the bounding box on the image + cv2.rectangle(img, (int(x1), int(y1)), (int(x1 + w), int(y1 + h)), color, 2) + + # Create the label text with class name and score + label = f"{self.classes[class_id]}: {score:.2f}" + + # Calculate the dimensions of the label text + (label_width, label_height), _ = cv2.getTextSize(label, cv2.FONT_HERSHEY_SIMPLEX, 0.5, 1) + + # Calculate the position of the label text + label_x = x1 + label_y = y1 - 10 if y1 - 10 > label_height else y1 + 10 + + # Draw a filled rectangle as the background for the label text + cv2.rectangle( + img, + (int(label_x), int(label_y - label_height)), + (int(label_x + label_width), int(label_y + label_height)), + color, + cv2.FILLED, + ) + + # Draw the label text on the image + cv2.putText(img, label, (int(label_x), int(label_y)), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 0, 0), 1, cv2.LINE_AA) + + def preprocess(self): + """ + Preprocesses the input image before performing inference. + + Returns: + image_data: Preprocessed image data ready for inference. + """ + + # Read the input image using OpenCV + self.img = cv2.imread(self.input_image) + + print("image before", self.img) + # Get the height and width of the input image + self.img_height, self.img_width = self.img.shape[:2] + + letterbox = LetterBox(new_shape=[img_width, img_height], auto=False, stride=32) + image = letterbox(image=self.img) + image = [image] + image = np.stack(image) + image = image[..., ::-1].transpose((0, 3, 1, 2)) + img = np.ascontiguousarray(image) + # n, h, w, c + image = img.astype(np.float32) + return image / 255 + + def postprocess(self, input_image, output): + """ + Performs post-processing on the model's output to extract bounding boxes, scores, and class IDs. + + Args: + input_image (numpy.ndarray): The input image. + output (numpy.ndarray): The output of the model. + + Returns: + numpy.ndarray: The input image with detections drawn on it. + """ + + boxes = [] + scores = [] + class_ids = [] + for pred in output: + pred = np.transpose(pred) + for box in pred: + x, y, w, h = box[:4] + x1 = x - w / 2 + y1 = y - h / 2 + boxes.append([x1, y1, w, h]) + idx = np.argmax(box[4:]) + scores.append(box[idx + 4]) + class_ids.append(idx) + + indices = cv2.dnn.NMSBoxes(boxes, scores, self.confidence_thres, self.iou_thres) + + for i in indices: + # Get the box, score, and class ID corresponding to the index + box = boxes[i] + gain = min(img_width / self.img_width, img_height / self.img_height) + pad = ( + round((img_width - self.img_width * gain) / 2 - 0.1), + round((img_height - self.img_height * gain) / 2 - 0.1), + ) + box[0] = (box[0] - pad[0]) / gain + box[1] = (box[1] - pad[1]) / gain + box[2] = box[2] / gain + box[3] = box[3] / gain + score = scores[i] + class_id = class_ids[i] + if score > 0.25: + print(box, score, class_id) + # Draw the detection on the input image + self.draw_detections(input_image, box, score, class_id) + + return input_image + + def main(self): + """ + Performs inference using a TFLite model and returns the output image with drawn detections. + + Returns: + output_img: The output image with drawn detections. + """ + + # Create an interpreter for the TFLite model + interpreter = tflite.Interpreter(model_path=self.tflite_model) + self.model = interpreter + interpreter.allocate_tensors() + + # Get the model inputs + input_details = interpreter.get_input_details() + output_details = interpreter.get_output_details() + + # Store the shape of the input for later use + input_shape = input_details[0]["shape"] + self.input_width = input_shape[1] + self.input_height = input_shape[2] + + # Preprocess the image data + img_data = self.preprocess() + img_data = img_data + # img_data = img_data.cpu().numpy() + # Set the input tensor to the interpreter + print(input_details[0]["index"]) + print(img_data.shape) + img_data = img_data.transpose((0, 2, 3, 1)) + + scale, zero_point = input_details[0]["quantization"] + interpreter.set_tensor(input_details[0]["index"], img_data) + + # Run inference + interpreter.invoke() + + # Get the output tensor from the interpreter + output = interpreter.get_tensor(output_details[0]["index"]) + scale, zero_point = output_details[0]["quantization"] + output = (output.astype(np.float32) - zero_point) * scale + + output[:, [0, 2]] *= img_width + output[:, [1, 3]] *= img_height + print(output) + # Perform post-processing on the outputs to obtain output image. + return self.postprocess(self.img, output) + + +if __name__ == "__main__": + # Create an argument parser to handle command-line arguments + parser = argparse.ArgumentParser() + parser.add_argument( + "--model", type=str, default="yolov8n_full_integer_quant.tflite", help="Input your TFLite model." + ) + parser.add_argument("--img", type=str, default=str(ASSETS / "bus.jpg"), help="Path to input image.") + parser.add_argument("--conf-thres", type=float, default=0.5, help="Confidence threshold") + parser.add_argument("--iou-thres", type=float, default=0.5, help="NMS IoU threshold") + args = parser.parse_args() + + # Create an instance of the Yolov8TFLite class with the specified arguments + detection = Yolov8TFLite(args.model, args.img, args.conf_thres, args.iou_thres) + + # Perform object detection and obtain the output image + output_image = detection.main() + + # Display the output image in a window + cv2.imshow("Output", output_image) + + # Wait for a key press to exit + cv2.waitKey(0) diff --git a/examples/YOLOv8-Region-Counter/readme.md b/examples/YOLOv8-Region-Counter/readme.md new file mode 100644 index 0000000..2acf0a5 --- /dev/null +++ b/examples/YOLOv8-Region-Counter/readme.md @@ -0,0 +1,123 @@ +# Regions Counting Using YOLOv8 (Inference on Video) + +- Region counting is a method employed to tally the objects within a specified area, allowing for more sophisticated analyses when multiple regions are considered. These regions can be adjusted interactively using a Left Mouse Click, and the counting process occurs in real time. +- Regions can be adjusted to suit the user's preferences and requirements. + +
+

+ YOLOv8 region counting visual 1 + YOLOv8 region counting visual 2 +

+
+ +## Table of Contents + +- [Step 1: Install the Required Libraries](#step-1-install-the-required-libraries) +- [Step 2: Run the Region Counting Using Ultralytics YOLOv8](#step-2-run-the-region-counting-using-ultralytics-yolov8) +- [Usage Options](#usage-options) +- [FAQ](#faq) + +## Step 1: Install the Required Libraries + +Clone the repository, install dependencies and `cd` to this local directory for commands in Step 2. + +```bash +# Clone ultralytics repo +git clone https://github.com/ultralytics/ultralytics + +# cd to local directory +cd ultralytics/examples/YOLOv8-Region-Counter +``` + +## Step 2: Run the Region Counting Using Ultralytics YOLOv8 + +Here are the basic commands for running the inference: + +### Note + +After the video begins playing, you can freely move the region anywhere within the video by simply clicking and dragging using the left mouse button. + +```bash +# If you want to save results +python yolov8_region_counter.py --source "path/to/video.mp4" --save-img --view-img + +# If you want to run model on CPU +python yolov8_region_counter.py --source "path/to/video.mp4" --save-img --view-img --device cpu + +# If you want to change model file +python yolov8_region_counter.py --source "path/to/video.mp4" --save-img --weights "path/to/model.pt" + +# If you want to detect specific class (first class and third class) +python yolov8_region_counter.py --source "path/to/video.mp4" --classes 0 2 --weights "path/to/model.pt" + +# If you dont want to save results +python yolov8_region_counter.py --source "path/to/video.mp4" --view-img +``` + +## Usage Options + +- `--source`: Specifies the path to the video file you want to run inference on. +- `--device`: Specifies the device `cpu` or `0` +- `--save-img`: Flag to save the detection results as images. +- `--weights`: Specifies a different YOLOv8 model file (e.g., `yolov8n.pt`, `yolov8s.pt`, `yolov8m.pt`, `yolov8l.pt`, `yolov8x.pt`). +- `--classes`: Specifies the class to be detected +- `--line-thickness`: Specifies the bounding box thickness +- `--region-thickness`: Specifies the region boxes thickness +- `--track-thickness`: Specifies the track line thickness + +## FAQ + +**1. What Does Region Counting Involve?** + +Region counting is a computational method utilized to ascertain the quantity of objects within a specific area in recorded video or real-time streams. This technique finds frequent application in image processing, computer vision, and pattern recognition, facilitating the analysis and segmentation of objects or features based on their spatial relationships. + +**2. Is Friendly Region Plotting Supported by the Region Counter?** + +The Region Counter offers the capability to create regions in various formats, such as polygons and rectangles. You have the flexibility to modify region attributes, including coordinates, colors, and other details, as demonstrated in the following code: + +```python +from shapely.geometry import Polygon + +counting_regions = [ + { + "name": "YOLOv8 Polygon Region", + "polygon": Polygon( + [(50, 80), (250, 20), (450, 80), (400, 350), (100, 350)] + ), # Polygon with five points (Pentagon) + "counts": 0, + "dragging": False, + "region_color": (255, 42, 4), # BGR Value + "text_color": (255, 255, 255), # Region Text Color + }, + { + "name": "YOLOv8 Rectangle Region", + "polygon": Polygon( + [(200, 250), (440, 250), (440, 550), (200, 550)] + ), # Rectangle with four points + "counts": 0, + "dragging": False, + "region_color": (37, 255, 225), # BGR Value + "text_color": (0, 0, 0), # Region Text Color + }, +] +``` + +**3. Why Combine Region Counting with YOLOv8?** + +YOLOv8 specializes in the detection and tracking of objects in video streams. Region counting complements this by enabling object counting within designated areas, making it a valuable application of YOLOv8. + +**4. How Can I Troubleshoot Issues?** + +To gain more insights during inference, you can include the `--debug` flag in your command: + +```bash +python yolov8_region_counter.py --source "path to video file" --debug +``` + +**5. Can I Employ Other YOLO Versions?** + +Certainly, you have the flexibility to specify different YOLO model weights using the `--weights` option. + +**6. Where Can I Access Additional Information?** + +For a comprehensive guide on using YOLOv8 with Object Tracking, please refer to [Multi-Object Tracking with Ultralytics YOLO](https://docs.ultralytics.com/modes/track/). diff --git a/examples/YOLOv8-Region-Counter/yolov8_region_counter.py b/examples/YOLOv8-Region-Counter/yolov8_region_counter.py new file mode 100644 index 0000000..b7e9c3b --- /dev/null +++ b/examples/YOLOv8-Region-Counter/yolov8_region_counter.py @@ -0,0 +1,251 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import argparse +from collections import defaultdict +from pathlib import Path + +import cv2 +import numpy as np +from shapely.geometry import Polygon +from shapely.geometry.point import Point + +from ultralytics import YOLO +from ultralytics.utils.files import increment_path +from ultralytics.utils.plotting import Annotator, colors + +track_history = defaultdict(list) + +current_region = None +counting_regions = [ + { + "name": "YOLOv8 Polygon Region", + "polygon": Polygon([(50, 80), (250, 20), (450, 80), (400, 350), (100, 350)]), # Polygon points + "counts": 0, + "dragging": False, + "region_color": (255, 42, 4), # BGR Value + "text_color": (255, 255, 255), # Region Text Color + }, + { + "name": "YOLOv8 Rectangle Region", + "polygon": Polygon([(200, 250), (440, 250), (440, 550), (200, 550)]), # Polygon points + "counts": 0, + "dragging": False, + "region_color": (37, 255, 225), # BGR Value + "text_color": (0, 0, 0), # Region Text Color + }, +] + + +def mouse_callback(event, x, y, flags, param): + """ + Handles mouse events for region manipulation. + + Parameters: + event (int): The mouse event type (e.g., cv2.EVENT_LBUTTONDOWN). + x (int): The x-coordinate of the mouse pointer. + y (int): The y-coordinate of the mouse pointer. + flags (int): Additional flags passed by OpenCV. + param: Additional parameters passed to the callback (not used in this function). + + Global Variables: + current_region (dict): A dictionary representing the current selected region. + + Mouse Events: + - LBUTTONDOWN: Initiates dragging for the region containing the clicked point. + - MOUSEMOVE: Moves the selected region if dragging is active. + - LBUTTONUP: Ends dragging for the selected region. + + Notes: + - This function is intended to be used as a callback for OpenCV mouse events. + - Requires the existence of the 'counting_regions' list and the 'Polygon' class. + + Example: + >>> cv2.setMouseCallback(window_name, mouse_callback) + """ + global current_region + + # Mouse left button down event + if event == cv2.EVENT_LBUTTONDOWN: + for region in counting_regions: + if region["polygon"].contains(Point((x, y))): + current_region = region + current_region["dragging"] = True + current_region["offset_x"] = x + current_region["offset_y"] = y + + # Mouse move event + elif event == cv2.EVENT_MOUSEMOVE: + if current_region is not None and current_region["dragging"]: + dx = x - current_region["offset_x"] + dy = y - current_region["offset_y"] + current_region["polygon"] = Polygon( + [(p[0] + dx, p[1] + dy) for p in current_region["polygon"].exterior.coords] + ) + current_region["offset_x"] = x + current_region["offset_y"] = y + + # Mouse left button up event + elif event == cv2.EVENT_LBUTTONUP: + if current_region is not None and current_region["dragging"]: + current_region["dragging"] = False + + +def run( + weights="yolov8n.pt", + source=None, + device="cpu", + view_img=False, + save_img=False, + exist_ok=False, + classes=None, + line_thickness=2, + track_thickness=2, + region_thickness=2, +): + """ + Run Region counting on a video using YOLOv8 and ByteTrack. + + Supports movable region for real time counting inside specific area. + Supports multiple regions counting. + Regions can be Polygons or rectangle in shape + + Args: + weights (str): Model weights path. + source (str): Video file path. + device (str): processing device cpu, 0, 1 + view_img (bool): Show results. + save_img (bool): Save results. + exist_ok (bool): Overwrite existing files. + classes (list): classes to detect and track + line_thickness (int): Bounding box thickness. + track_thickness (int): Tracking line thickness + region_thickness (int): Region thickness. + """ + vid_frame_count = 0 + + # Check source path + if not Path(source).exists(): + raise FileNotFoundError(f"Source path '{source}' does not exist.") + + # Setup Model + model = YOLO(f"{weights}") + model.to("cuda") if device == "0" else model.to("cpu") + + # Extract classes names + names = model.model.names + + # Video setup + videocapture = cv2.VideoCapture(source) + frame_width, frame_height = int(videocapture.get(3)), int(videocapture.get(4)) + fps, fourcc = int(videocapture.get(5)), cv2.VideoWriter_fourcc(*"mp4v") + + # Output setup + save_dir = increment_path(Path("ultralytics_rc_output") / "exp", exist_ok) + save_dir.mkdir(parents=True, exist_ok=True) + video_writer = cv2.VideoWriter(str(save_dir / f"{Path(source).stem}.mp4"), fourcc, fps, (frame_width, frame_height)) + + # Iterate over video frames + while videocapture.isOpened(): + success, frame = videocapture.read() + if not success: + break + vid_frame_count += 1 + + # Extract the results + results = model.track(frame, persist=True, classes=classes) + + if results[0].boxes.id is not None: + boxes = results[0].boxes.xyxy.cpu() + track_ids = results[0].boxes.id.int().cpu().tolist() + clss = results[0].boxes.cls.cpu().tolist() + + annotator = Annotator(frame, line_width=line_thickness, example=str(names)) + + for box, track_id, cls in zip(boxes, track_ids, clss): + annotator.box_label(box, str(names[cls]), color=colors(cls, True)) + bbox_center = (box[0] + box[2]) / 2, (box[1] + box[3]) / 2 # Bbox center + + track = track_history[track_id] # Tracking Lines plot + track.append((float(bbox_center[0]), float(bbox_center[1]))) + if len(track) > 30: + track.pop(0) + points = np.hstack(track).astype(np.int32).reshape((-1, 1, 2)) + cv2.polylines(frame, [points], isClosed=False, color=colors(cls, True), thickness=track_thickness) + + # Check if detection inside region + for region in counting_regions: + if region["polygon"].contains(Point((bbox_center[0], bbox_center[1]))): + region["counts"] += 1 + + # Draw regions (Polygons/Rectangles) + for region in counting_regions: + region_label = str(region["counts"]) + region_color = region["region_color"] + region_text_color = region["text_color"] + + polygon_coords = np.array(region["polygon"].exterior.coords, dtype=np.int32) + centroid_x, centroid_y = int(region["polygon"].centroid.x), int(region["polygon"].centroid.y) + + text_size, _ = cv2.getTextSize( + region_label, cv2.FONT_HERSHEY_SIMPLEX, fontScale=0.7, thickness=line_thickness + ) + text_x = centroid_x - text_size[0] // 2 + text_y = centroid_y + text_size[1] // 2 + cv2.rectangle( + frame, + (text_x - 5, text_y - text_size[1] - 5), + (text_x + text_size[0] + 5, text_y + 5), + region_color, + -1, + ) + cv2.putText( + frame, region_label, (text_x, text_y), cv2.FONT_HERSHEY_SIMPLEX, 0.7, region_text_color, line_thickness + ) + cv2.polylines(frame, [polygon_coords], isClosed=True, color=region_color, thickness=region_thickness) + + if view_img: + if vid_frame_count == 1: + cv2.namedWindow("Ultralytics YOLOv8 Region Counter Movable") + cv2.setMouseCallback("Ultralytics YOLOv8 Region Counter Movable", mouse_callback) + cv2.imshow("Ultralytics YOLOv8 Region Counter Movable", frame) + + if save_img: + video_writer.write(frame) + + for region in counting_regions: # Reinitialize count for each region + region["counts"] = 0 + + if cv2.waitKey(1) & 0xFF == ord("q"): + break + + del vid_frame_count + video_writer.release() + videocapture.release() + cv2.destroyAllWindows() + + +def parse_opt(): + """Parse command line arguments.""" + parser = argparse.ArgumentParser() + parser.add_argument("--weights", type=str, default="yolov8n.pt", help="initial weights path") + parser.add_argument("--device", default="", help="cuda device, i.e. 0 or 0,1,2,3 or cpu") + parser.add_argument("--source", type=str, required=True, help="video file path") + parser.add_argument("--view-img", action="store_true", help="show results") + parser.add_argument("--save-img", action="store_true", help="save results") + parser.add_argument("--exist-ok", action="store_true", help="existing project/name ok, do not increment") + parser.add_argument("--classes", nargs="+", type=int, help="filter by class: --classes 0, or --classes 0 2 3") + parser.add_argument("--line-thickness", type=int, default=2, help="bounding box thickness") + parser.add_argument("--track-thickness", type=int, default=2, help="Tracking line thickness") + parser.add_argument("--region-thickness", type=int, default=4, help="Region thickness") + + return parser.parse_args() + + +def main(opt): + """Main function.""" + run(**vars(opt)) + + +if __name__ == "__main__": + opt = parse_opt() + main(opt) diff --git a/examples/YOLOv8-SAHI-Inference-Video/readme.md b/examples/YOLOv8-SAHI-Inference-Video/readme.md new file mode 100644 index 0000000..f24df30 --- /dev/null +++ b/examples/YOLOv8-SAHI-Inference-Video/readme.md @@ -0,0 +1,69 @@ +# YOLOv8 with SAHI (Inference on Video) + +[SAHI](https://docs.ultralytics.com/guides/sahi-tiled-inference/) is designed to optimize object detection algorithms for large-scale and high-resolution imagery. It partitions images into manageable slices, performs object detection on each slice, and then stitches the results back together. This tutorial will guide you through the process of running YOLOv8 inference on video files with the aid of SAHI. + +## Table of Contents + +- [Step 1: Install the Required Libraries](#step-1-install-the-required-libraries) +- [Step 2: Run the Inference with SAHI using Ultralytics YOLOv8](#step-2-run-the-inference-with-sahi-using-ultralytics-yolov8) +- [Usage Options](#usage-options) +- [FAQ](#faq) + +## Step 1: Install the Required Libraries + +Clone the repository, install dependencies and `cd` to this local directory for commands in Step 2. + +```bash +# Clone ultralytics repo +git clone https://github.com/ultralytics/ultralytics + +# Install dependencies +pip install sahi ultralytics + +# cd to local directory +cd ultralytics/examples/YOLOv8-SAHI-Inference-Video +``` + +## Step 2: Run the Inference with SAHI using Ultralytics YOLOv8 + +Here are the basic commands for running the inference: + +```bash +#if you want to save results +python yolov8_sahi.py --source "path/to/video.mp4" --save-img + +#if you want to change model file +python yolov8_sahi.py --source "path/to/video.mp4" --save-img --weights "yolov8n.pt" +``` + +## Usage Options + +- `--source`: Specifies the path to the video file you want to run inference on. +- `--save-img`: Flag to save the detection results as images. +- `--weights`: Specifies a different YOLOv8 model file (e.g., `yolov8n.pt`, `yolov8s.pt`, `yolov8m.pt`, `yolov8l.pt`, `yolov8x.pt`). + +## FAQ + +**1. What is SAHI?** + +SAHI stands for Slicing, Analysis, and Healing of Images. It is a library designed to optimize object detection algorithms for large-scale and high-resolution images. The library source code is available on [GitHub](https://github.com/obss/sahi). + +**2. Why use SAHI with YOLOv8?** + +SAHI can handle large-scale images by slicing them into smaller, more manageable sizes without compromising the detection quality. This makes it a great companion to YOLOv8, especially when working with high-resolution videos. + +**3. How do I debug issues?** + +You can add the `--debug` flag to your command to print out more information during inference: + +```bash +python yolov8_sahi.py --source "path to video file" --debug +``` + +**4. Can I use other YOLO versions?** + +Yes, you can specify different YOLO model weights using the `--weights` option. + +**5. Where can I find more information?** + +For a full guide to YOLOv8 with SAHI see [https://docs.ultralytics.com/guides/sahi-tiled-inference](https://docs.ultralytics.com/guides/sahi-tiled-inference/). diff --git a/examples/YOLOv8-SAHI-Inference-Video/yolov8_sahi.py b/examples/YOLOv8-SAHI-Inference-Video/yolov8_sahi.py new file mode 100644 index 0000000..f2b8274 --- /dev/null +++ b/examples/YOLOv8-SAHI-Inference-Video/yolov8_sahi.py @@ -0,0 +1,111 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import argparse +from pathlib import Path + +import cv2 +from sahi import AutoDetectionModel +from sahi.predict import get_sliced_prediction +from sahi.utils.yolov8 import download_yolov8s_model + +from ultralytics.utils.files import increment_path + + +def run(weights="yolov8n.pt", source="test.mp4", view_img=False, save_img=False, exist_ok=False): + """ + Run object detection on a video using YOLOv8 and SAHI. + + Args: + weights (str): Model weights path. + source (str): Video file path. + view_img (bool): Show results. + save_img (bool): Save results. + exist_ok (bool): Overwrite existing files. + """ + + # Check source path + if not Path(source).exists(): + raise FileNotFoundError(f"Source path '{source}' does not exist.") + + yolov8_model_path = f"models/{weights}" + download_yolov8s_model(yolov8_model_path) + detection_model = AutoDetectionModel.from_pretrained( + model_type="yolov8", model_path=yolov8_model_path, confidence_threshold=0.3, device="cpu" + ) + + # Video setup + videocapture = cv2.VideoCapture(source) + frame_width, frame_height = int(videocapture.get(3)), int(videocapture.get(4)) + fps, fourcc = int(videocapture.get(5)), cv2.VideoWriter_fourcc(*"mp4v") + + # Output setup + save_dir = increment_path(Path("ultralytics_results_with_sahi") / "exp", exist_ok) + save_dir.mkdir(parents=True, exist_ok=True) + video_writer = cv2.VideoWriter(str(save_dir / f"{Path(source).stem}.mp4"), fourcc, fps, (frame_width, frame_height)) + + while videocapture.isOpened(): + success, frame = videocapture.read() + if not success: + break + + results = get_sliced_prediction( + frame, detection_model, slice_height=512, slice_width=512, overlap_height_ratio=0.2, overlap_width_ratio=0.2 + ) + object_prediction_list = results.object_prediction_list + + boxes_list = [] + clss_list = [] + for ind, _ in enumerate(object_prediction_list): + boxes = ( + object_prediction_list[ind].bbox.minx, + object_prediction_list[ind].bbox.miny, + object_prediction_list[ind].bbox.maxx, + object_prediction_list[ind].bbox.maxy, + ) + clss = object_prediction_list[ind].category.name + boxes_list.append(boxes) + clss_list.append(clss) + + for box, cls in zip(boxes_list, clss_list): + x1, y1, x2, y2 = box + cv2.rectangle(frame, (int(x1), int(y1)), (int(x2), int(y2)), (56, 56, 255), 2) + label = str(cls) + t_size = cv2.getTextSize(label, 0, fontScale=0.6, thickness=1)[0] + cv2.rectangle( + frame, (int(x1), int(y1) - t_size[1] - 3), (int(x1) + t_size[0], int(y1) + 3), (56, 56, 255), -1 + ) + cv2.putText( + frame, label, (int(x1), int(y1) - 2), 0, 0.6, [255, 255, 255], thickness=1, lineType=cv2.LINE_AA + ) + + if view_img: + cv2.imshow(Path(source).stem, frame) + if save_img: + video_writer.write(frame) + + if cv2.waitKey(1) & 0xFF == ord("q"): + break + video_writer.release() + videocapture.release() + cv2.destroyAllWindows() + + +def parse_opt(): + """Parse command line arguments.""" + parser = argparse.ArgumentParser() + parser.add_argument("--weights", type=str, default="yolov8n.pt", help="initial weights path") + parser.add_argument("--source", type=str, required=True, help="video file path") + parser.add_argument("--view-img", action="store_true", help="show results") + parser.add_argument("--save-img", action="store_true", help="save results") + parser.add_argument("--exist-ok", action="store_true", help="existing project/name ok, do not increment") + return parser.parse_args() + + +def main(opt): + """Main function.""" + run(**vars(opt)) + + +if __name__ == "__main__": + opt = parse_opt() + main(opt) diff --git a/examples/YOLOv8-Segmentation-ONNXRuntime-Python/README.md b/examples/YOLOv8-Segmentation-ONNXRuntime-Python/README.md new file mode 100644 index 0000000..b647700 --- /dev/null +++ b/examples/YOLOv8-Segmentation-ONNXRuntime-Python/README.md @@ -0,0 +1,63 @@ +# YOLOv8-Segmentation-ONNXRuntime-Python Demo + +This repository provides a Python demo for performing segmentation with YOLOv8 using ONNX Runtime, highlighting the interoperability of YOLOv8 models without the need for the full PyTorch stack. + +## Features + +- **Framework Agnostic**: Runs segmentation inference purely on ONNX Runtime without importing PyTorch. +- **Efficient Inference**: Supports both FP32 and FP16 precision for ONNX models, catering to different computational needs. +- **Ease of Use**: Utilizes simple command-line arguments for model execution. +- **Broad Compatibility**: Leverages Numpy and OpenCV for image processing, ensuring broad compatibility with various environments. + +## Installation + +Install the required packages using pip. You will need `ultralytics` for exporting YOLOv8-seg ONNX model and using some utility functions, `onnxruntime-gpu` for GPU-accelerated inference, and `opencv-python` for image processing. + +```bash +pip install ultralytics +pip install onnxruntime-gpu # For GPU support +# pip install onnxruntime # Use this instead if you don't have an NVIDIA GPU +pip install numpy +pip install opencv-python +``` + +## Getting Started + +### 1. Export the YOLOv8 ONNX Model + +Export the YOLOv8 segmentation model to ONNX format using the provided `ultralytics` package. + +```bash +yolo export model=yolov8s-seg.pt imgsz=640 format=onnx opset=12 simplify +``` + +### 2. Run Inference + +Perform inference with the exported ONNX model on your images. + +```bash +python main.py --model --source +``` + +### Example Output + +After running the command, you should see segmentation results similar to this: + +Segmentation Demo + +## Advanced Usage + +For more advanced usage, including real-time video processing, please refer to the `main.py` script's command-line arguments. + +## Contributing + +We welcome contributions to improve this demo! Please submit issues and pull requests for bug reports, feature requests, or submitting a new algorithm enhancement. + +## License + +This project is licensed under the AGPL-3.0 License - see the [LICENSE](https://github.com/ultralytics/ultralytics/blob/main/LICENSE) file for details. + +## Acknowledgments + +- The YOLOv8-Segmentation-ONNXRuntime-Python demo is contributed by GitHub user [jamjamjon](https://github.com/jamjamjon). +- Thanks to the ONNX Runtime community for providing a robust and efficient inference engine. diff --git a/examples/YOLOv8-Segmentation-ONNXRuntime-Python/main.py b/examples/YOLOv8-Segmentation-ONNXRuntime-Python/main.py new file mode 100644 index 0000000..141d21b --- /dev/null +++ b/examples/YOLOv8-Segmentation-ONNXRuntime-Python/main.py @@ -0,0 +1,342 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import argparse + +import cv2 +import numpy as np +import onnxruntime as ort + +from ultralytics.utils import ASSETS, yaml_load +from ultralytics.utils.checks import check_yaml +from ultralytics.utils.plotting import Colors + + +class YOLOv8Seg: + """YOLOv8 segmentation model.""" + + def __init__(self, onnx_model): + """ + Initialization. + + Args: + onnx_model (str): Path to the ONNX model. + """ + + # Build Ort session + self.session = ort.InferenceSession( + onnx_model, + providers=["CUDAExecutionProvider", "CPUExecutionProvider"] + if ort.get_device() == "GPU" + else ["CPUExecutionProvider"], + ) + + # Numpy dtype: support both FP32 and FP16 onnx model + self.ndtype = np.half if self.session.get_inputs()[0].type == "tensor(float16)" else np.single + + # Get model width and height(YOLOv8-seg only has one input) + self.model_height, self.model_width = [x.shape for x in self.session.get_inputs()][0][-2:] + + # Load COCO class names + self.classes = yaml_load(check_yaml("coco128.yaml"))["names"] + + # Create color palette + self.color_palette = Colors() + + def __call__(self, im0, conf_threshold=0.4, iou_threshold=0.45, nm=32): + """ + The whole pipeline: pre-process -> inference -> post-process. + + Args: + im0 (Numpy.ndarray): original input image. + conf_threshold (float): confidence threshold for filtering predictions. + iou_threshold (float): iou threshold for NMS. + nm (int): the number of masks. + + Returns: + boxes (List): list of bounding boxes. + segments (List): list of segments. + masks (np.ndarray): [N, H, W], output masks. + """ + + # Pre-process + im, ratio, (pad_w, pad_h) = self.preprocess(im0) + + # Ort inference + preds = self.session.run(None, {self.session.get_inputs()[0].name: im}) + + # Post-process + boxes, segments, masks = self.postprocess( + preds, + im0=im0, + ratio=ratio, + pad_w=pad_w, + pad_h=pad_h, + conf_threshold=conf_threshold, + iou_threshold=iou_threshold, + nm=nm, + ) + return boxes, segments, masks + + def preprocess(self, img): + """ + Pre-processes the input image. + + Args: + img (Numpy.ndarray): image about to be processed. + + Returns: + img_process (Numpy.ndarray): image preprocessed for inference. + ratio (tuple): width, height ratios in letterbox. + pad_w (float): width padding in letterbox. + pad_h (float): height padding in letterbox. + """ + + # Resize and pad input image using letterbox() (Borrowed from Ultralytics) + shape = img.shape[:2] # original image shape + new_shape = (self.model_height, self.model_width) + r = min(new_shape[0] / shape[0], new_shape[1] / shape[1]) + ratio = r, r + new_unpad = int(round(shape[1] * r)), int(round(shape[0] * r)) + pad_w, pad_h = (new_shape[1] - new_unpad[0]) / 2, (new_shape[0] - new_unpad[1]) / 2 # wh padding + if shape[::-1] != new_unpad: # resize + img = cv2.resize(img, new_unpad, interpolation=cv2.INTER_LINEAR) + top, bottom = int(round(pad_h - 0.1)), int(round(pad_h + 0.1)) + left, right = int(round(pad_w - 0.1)), int(round(pad_w + 0.1)) + img = cv2.copyMakeBorder(img, top, bottom, left, right, cv2.BORDER_CONSTANT, value=(114, 114, 114)) + + # Transforms: HWC to CHW -> BGR to RGB -> div(255) -> contiguous -> add axis(optional) + img = np.ascontiguousarray(np.einsum("HWC->CHW", img)[::-1], dtype=self.ndtype) / 255.0 + img_process = img[None] if len(img.shape) == 3 else img + return img_process, ratio, (pad_w, pad_h) + + def postprocess(self, preds, im0, ratio, pad_w, pad_h, conf_threshold, iou_threshold, nm=32): + """ + Post-process the prediction. + + Args: + preds (Numpy.ndarray): predictions come from ort.session.run(). + im0 (Numpy.ndarray): [h, w, c] original input image. + ratio (tuple): width, height ratios in letterbox. + pad_w (float): width padding in letterbox. + pad_h (float): height padding in letterbox. + conf_threshold (float): conf threshold. + iou_threshold (float): iou threshold. + nm (int): the number of masks. + + Returns: + boxes (List): list of bounding boxes. + segments (List): list of segments. + masks (np.ndarray): [N, H, W], output masks. + """ + x, protos = preds[0], preds[1] # Two outputs: predictions and protos + + # Transpose the first output: (Batch_size, xywh_conf_cls_nm, Num_anchors) -> (Batch_size, Num_anchors, xywh_conf_cls_nm) + x = np.einsum("bcn->bnc", x) + + # Predictions filtering by conf-threshold + x = x[np.amax(x[..., 4:-nm], axis=-1) > conf_threshold] + + # Create a new matrix which merge these(box, score, cls, nm) into one + # For more details about `numpy.c_()`: https://numpy.org/doc/1.26/reference/generated/numpy.c_.html + x = np.c_[x[..., :4], np.amax(x[..., 4:-nm], axis=-1), np.argmax(x[..., 4:-nm], axis=-1), x[..., -nm:]] + + # NMS filtering + x = x[cv2.dnn.NMSBoxes(x[:, :4], x[:, 4], conf_threshold, iou_threshold)] + + # Decode and return + if len(x) > 0: + # Bounding boxes format change: cxcywh -> xyxy + x[..., [0, 1]] -= x[..., [2, 3]] / 2 + x[..., [2, 3]] += x[..., [0, 1]] + + # Rescales bounding boxes from model shape(model_height, model_width) to the shape of original image + x[..., :4] -= [pad_w, pad_h, pad_w, pad_h] + x[..., :4] /= min(ratio) + + # Bounding boxes boundary clamp + x[..., [0, 2]] = x[:, [0, 2]].clip(0, im0.shape[1]) + x[..., [1, 3]] = x[:, [1, 3]].clip(0, im0.shape[0]) + + # Process masks + masks = self.process_mask(protos[0], x[:, 6:], x[:, :4], im0.shape) + + # Masks -> Segments(contours) + segments = self.masks2segments(masks) + return x[..., :6], segments, masks # boxes, segments, masks + else: + return [], [], [] + + @staticmethod + def masks2segments(masks): + """ + It takes a list of masks(n,h,w) and returns a list of segments(n,xy) (Borrowed from + https://github.com/ultralytics/ultralytics/blob/465df3024f44fa97d4fad9986530d5a13cdabdca/ultralytics/utils/ops.py#L750) + + Args: + masks (numpy.ndarray): the output of the model, which is a tensor of shape (batch_size, 160, 160). + + Returns: + segments (List): list of segment masks. + """ + segments = [] + for x in masks.astype("uint8"): + c = cv2.findContours(x, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_NONE)[0] # CHAIN_APPROX_SIMPLE + if c: + c = np.array(c[np.array([len(x) for x in c]).argmax()]).reshape(-1, 2) + else: + c = np.zeros((0, 2)) # no segments found + segments.append(c.astype("float32")) + return segments + + @staticmethod + def crop_mask(masks, boxes): + """ + It takes a mask and a bounding box, and returns a mask that is cropped to the bounding box. (Borrowed from + https://github.com/ultralytics/ultralytics/blob/465df3024f44fa97d4fad9986530d5a13cdabdca/ultralytics/utils/ops.py#L599) + + Args: + masks (Numpy.ndarray): [n, h, w] tensor of masks. + boxes (Numpy.ndarray): [n, 4] tensor of bbox coordinates in relative point form. + + Returns: + (Numpy.ndarray): The masks are being cropped to the bounding box. + """ + n, h, w = masks.shape + x1, y1, x2, y2 = np.split(boxes[:, :, None], 4, 1) + r = np.arange(w, dtype=x1.dtype)[None, None, :] + c = np.arange(h, dtype=x1.dtype)[None, :, None] + return masks * ((r >= x1) * (r < x2) * (c >= y1) * (c < y2)) + + def process_mask(self, protos, masks_in, bboxes, im0_shape): + """ + Takes the output of the mask head, and applies the mask to the bounding boxes. This produces masks of higher quality + but is slower. (Borrowed from https://github.com/ultralytics/ultralytics/blob/465df3024f44fa97d4fad9986530d5a13cdabdca/ultralytics/utils/ops.py#L618) + + Args: + protos (numpy.ndarray): [mask_dim, mask_h, mask_w]. + masks_in (numpy.ndarray): [n, mask_dim], n is number of masks after nms. + bboxes (numpy.ndarray): bboxes re-scaled to original image shape. + im0_shape (tuple): the size of the input image (h,w,c). + + Returns: + (numpy.ndarray): The upsampled masks. + """ + c, mh, mw = protos.shape + masks = np.matmul(masks_in, protos.reshape((c, -1))).reshape((-1, mh, mw)).transpose(1, 2, 0) # HWN + masks = np.ascontiguousarray(masks) + masks = self.scale_mask(masks, im0_shape) # re-scale mask from P3 shape to original input image shape + masks = np.einsum("HWN -> NHW", masks) # HWN -> NHW + masks = self.crop_mask(masks, bboxes) + return np.greater(masks, 0.5) + + @staticmethod + def scale_mask(masks, im0_shape, ratio_pad=None): + """ + Takes a mask, and resizes it to the original image size. (Borrowed from + https://github.com/ultralytics/ultralytics/blob/465df3024f44fa97d4fad9986530d5a13cdabdca/ultralytics/utils/ops.py#L305) + + Args: + masks (np.ndarray): resized and padded masks/images, [h, w, num]/[h, w, 3]. + im0_shape (tuple): the original image shape. + ratio_pad (tuple): the ratio of the padding to the original image. + + Returns: + masks (np.ndarray): The masks that are being returned. + """ + im1_shape = masks.shape[:2] + if ratio_pad is None: # calculate from im0_shape + gain = min(im1_shape[0] / im0_shape[0], im1_shape[1] / im0_shape[1]) # gain = old / new + pad = (im1_shape[1] - im0_shape[1] * gain) / 2, (im1_shape[0] - im0_shape[0] * gain) / 2 # wh padding + else: + pad = ratio_pad[1] + + # Calculate tlbr of mask + top, left = int(round(pad[1] - 0.1)), int(round(pad[0] - 0.1)) # y, x + bottom, right = int(round(im1_shape[0] - pad[1] + 0.1)), int(round(im1_shape[1] - pad[0] + 0.1)) + if len(masks.shape) < 2: + raise ValueError(f'"len of masks shape" should be 2 or 3, but got {len(masks.shape)}') + masks = masks[top:bottom, left:right] + masks = cv2.resize( + masks, (im0_shape[1], im0_shape[0]), interpolation=cv2.INTER_LINEAR + ) # INTER_CUBIC would be better + if len(masks.shape) == 2: + masks = masks[:, :, None] + return masks + + def draw_and_visualize(self, im, bboxes, segments, vis=False, save=True): + """ + Draw and visualize results. + + Args: + im (np.ndarray): original image, shape [h, w, c]. + bboxes (numpy.ndarray): [n, 4], n is number of bboxes. + segments (List): list of segment masks. + vis (bool): imshow using OpenCV. + save (bool): save image annotated. + + Returns: + None + """ + + # Draw rectangles and polygons + im_canvas = im.copy() + for (*box, conf, cls_), segment in zip(bboxes, segments): + # draw contour and fill mask + cv2.polylines(im, np.int32([segment]), True, (255, 255, 255), 2) # white borderline + cv2.fillPoly(im_canvas, np.int32([segment]), self.color_palette(int(cls_), bgr=True)) + + # draw bbox rectangle + cv2.rectangle( + im, + (int(box[0]), int(box[1])), + (int(box[2]), int(box[3])), + self.color_palette(int(cls_), bgr=True), + 1, + cv2.LINE_AA, + ) + cv2.putText( + im, + f"{self.classes[cls_]}: {conf:.3f}", + (int(box[0]), int(box[1] - 9)), + cv2.FONT_HERSHEY_SIMPLEX, + 0.7, + self.color_palette(int(cls_), bgr=True), + 2, + cv2.LINE_AA, + ) + + # Mix image + im = cv2.addWeighted(im_canvas, 0.3, im, 0.7, 0) + + # Show image + if vis: + cv2.imshow("demo", im) + cv2.waitKey(0) + cv2.destroyAllWindows() + + # Save image + if save: + cv2.imwrite("demo.jpg", im) + + +if __name__ == "__main__": + # Create an argument parser to handle command-line arguments + parser = argparse.ArgumentParser() + parser.add_argument("--model", type=str, required=True, help="Path to ONNX model") + parser.add_argument("--source", type=str, default=str(ASSETS / "bus.jpg"), help="Path to input image") + parser.add_argument("--conf", type=float, default=0.25, help="Confidence threshold") + parser.add_argument("--iou", type=float, default=0.45, help="NMS IoU threshold") + args = parser.parse_args() + + # Build model + model = YOLOv8Seg(args.model) + + # Read image by OpenCV + img = cv2.imread(args.source) + + # Inference + boxes, segments, _ = model(img, conf_threshold=args.conf, iou_threshold=args.iou) + + # Draw bboxes and polygons + if len(boxes) > 0: + model.draw_and_visualize(img, boxes, segments, vis=False, save=True) diff --git a/examples/heatmaps.ipynb b/examples/heatmaps.ipynb new file mode 100644 index 0000000..b49e69b --- /dev/null +++ b/examples/heatmaps.ipynb @@ -0,0 +1,145 @@ +{ + "nbformat": 4, + "nbformat_minor": 0, + "metadata": { + "colab": { + "provenance": [], + "gpuType": "T4" + }, + "kernelspec": { + "name": "python3", + "display_name": "Python 3" + }, + "language_info": { + "name": "python" + }, + "accelerator": "GPU" + }, + "cells": [ + { + "cell_type": "markdown", + "source": [ + "
\n", + "\n", + " \n", + " \n", + "\n", + " [中文](https://docs.ultralytics.com/zh/) | [한국어](https://docs.ultralytics.com/ko/) | [日本語](https://docs.ultralytics.com/ja/) | [Русский](https://docs.ultralytics.com/ru/) | [Deutsch](https://docs.ultralytics.com/de/) | [Français](https://docs.ultralytics.com/fr/) | [Español](https://docs.ultralytics.com/es/) | [Português](https://docs.ultralytics.com/pt/) | [हिन्दी](https://docs.ultralytics.com/hi/) | [العربية](https://docs.ultralytics.com/ar/)\n", + "\n", + " \"Open\n", + "\n", + "Welcome to the Ultralytics YOLOv8 🚀 notebook! YOLOv8 is the latest version of the YOLO (You Only Look Once) AI models developed by Ultralytics. This notebook serves as the starting point for exploring the heatmaps and understand its features and capabilities.\n", + "\n", + "YOLOv8 models are fast, accurate, and easy to use, making them ideal for various object detection and image segmentation tasks. They can be trained on large datasets and run on diverse hardware platforms, from CPUs to GPUs.\n", + "\n", + "We hope that the resources in this notebook will help you get the most out of Ultralytics Heatmaps. Please browse the YOLOv8 Docs for details, raise an issue on GitHub for support, and join our Discord community for questions and discussions!\n", + "\n", + "
" + ], + "metadata": { + "id": "PN1cAxdvd61e" + } + }, + { + "cell_type": "markdown", + "source": [ + "# Setup\n", + "\n", + "Pip install `ultralytics` and [dependencies](https://github.com/ultralytics/ultralytics/blob/main/pyproject.toml) and check software and hardware." + ], + "metadata": { + "id": "o68Sg1oOeZm2" + } + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "id": "9dSwz_uOReMI" + }, + "outputs": [], + "source": [ + "!pip install ultralytics" + ] + }, + { + "cell_type": "markdown", + "source": [ + "# Ultralytics Heatmaps\n", + "\n", + "Heatmap is color-coded matrix, generated by Ultralytics YOLOv8, simplifies intricate data by using vibrant colors. This visual representation employs warmer hues for higher intensities and cooler tones for lower values. Heatmaps are effective in illustrating complex data patterns, correlations, and anomalies, providing a user-friendly and engaging way to interpret data across various domains." + ], + "metadata": { + "id": "m7VkxQ2aeg7k" + } + }, + { + "cell_type": "code", + "source": [ + "from ultralytics import YOLO\n", + "from ultralytics.solutions import heatmap\n", + "import cv2\n", + "\n", + "model = YOLO(\"yolov8n.pt\")\n", + "cap = cv2.VideoCapture(\"path/to/video/file.mp4\")\n", + "assert cap.isOpened(), \"Error reading video file\"\n", + "w, h, fps = (int(cap.get(x)) for x in (cv2.CAP_PROP_FRAME_WIDTH, cv2.CAP_PROP_FRAME_HEIGHT, cv2.CAP_PROP_FPS))\n", + "\n", + "# Video writer\n", + "video_writer = cv2.VideoWriter(\"heatmap_output.avi\",\n", + " cv2.VideoWriter_fourcc(*'mp4v'),\n", + " fps,\n", + " (w, h))\n", + "\n", + "# Init heatmap\n", + "heatmap_obj = heatmap.Heatmap()\n", + "heatmap_obj.set_args(colormap=cv2.COLORMAP_PARULA,\n", + " imw=w,\n", + " imh=h,\n", + " view_img=True,\n", + " shape=\"circle\")\n", + "\n", + "while cap.isOpened():\n", + " success, im0 = cap.read()\n", + " if not success:\n", + " print(\"Video frame is empty or video processing has been successfully completed.\")\n", + " break\n", + " tracks = model.track(im0, persist=True, show=False)\n", + "\n", + " im0 = heatmap_obj.generate_heatmap(im0, tracks)\n", + " video_writer.write(im0)\n", + "\n", + "cap.release()\n", + "video_writer.release()\n", + "cv2.destroyAllWindows()" + ], + "metadata": { + "id": "Cx-u59HQdu2o" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "#Community Support\n", + "\n", + "For more information, you can explore Ultralytics Heatmaps Docs\n", + "\n", + "Ultralytics ⚡ resources\n", + "- About Us – https://ultralytics.com/about\n", + "- Join Our Team – https://ultralytics.com/work\n", + "- Contact Us – https://ultralytics.com/contact\n", + "- Discord – https://ultralytics.com/discord\n", + "- Ultralytics License – https://ultralytics.com/license\n", + "\n", + "YOLOv8 🚀 resources\n", + "- GitHub – https://github.com/ultralytics/ultralytics\n", + "- Docs – https://docs.ultralytics.com/" + ], + "metadata": { + "id": "QrlKg-y3fEyD" + } + } + ] +} \ No newline at end of file diff --git a/examples/hub.ipynb b/examples/hub.ipynb new file mode 100644 index 0000000..c6fec03 --- /dev/null +++ b/examples/hub.ipynb @@ -0,0 +1,106 @@ +{ + "nbformat": 4, + "nbformat_minor": 0, + "metadata": { + "colab": { + "name": "Ultralytics HUB", + "provenance": [] + }, + "kernelspec": { + "name": "python3", + "display_name": "Python 3" + }, + "language_info": { + "name": "python" + }, + "accelerator": "GPU" + }, + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "id": "FIzICjaph_Wy" + }, + "source": [ + "\n", + "\n", + "\n", + "
\n", + "\n", + "[中文](https://docs.ultralytics.com/zh/) | [한국어](https://docs.ultralytics.com/ko/) | [日本語](https://docs.ultralytics.com/ja/) | [Русский](https://docs.ultralytics.com/ru/) | [Deutsch](https://docs.ultralytics.com/de/) | [Français](https://docs.ultralytics.com/fr/) | [Español](https://docs.ultralytics.com/es/) | [Português](https://docs.ultralytics.com/pt/) | [हिन्दी](https://docs.ultralytics.com/hi/) | [العربية](https://docs.ultralytics.com/ar/)\n", + "\n", + " \n", + " \"CI\n", + " \n", + " \"Open\n", + "\n", + "Welcome to the [Ultralytics](https://ultralytics.com/) HUB notebook!\n", + "\n", + "This notebook allows you to train Ultralytics [YOLO](https://github.com/ultralytics/ultralytics) 🚀 models using [HUB](https://hub.ultralytics.com/). Please browse the HUB Docs for details, raise an issue on GitHub for support, and join our Discord community for questions and discussions!\n", + "
" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "eRQ2ow94MiOv" + }, + "source": [ + "# Setup\n", + "\n", + "Pip install `ultralytics` and [dependencies](https://github.com/ultralytics/ultralytics/blob/main/pyproject.toml) and check software and hardware." + ] + }, + { + "cell_type": "code", + "metadata": { + "id": "FyDnXd-n4c7Y", + "colab": { + "base_uri": "https://localhost:8080/" + }, + "outputId": "824edff2-510a-4575-c749-396dafb36a47" + }, + "source": [ + "%pip install ultralytics # install\n", + "from ultralytics import YOLO, checks, hub\n", + "checks() # checks" + ], + "execution_count": 1, + "outputs": [ + { + "output_type": "stream", + "name": "stdout", + "text": [ + "Ultralytics YOLOv8.1.47 🚀 Python-3.10.12 torch-2.2.1+cu121 CUDA:0 (Tesla T4, 15102MiB)\n", + "Setup complete ✅ (2 CPUs, 12.7 GB RAM, 29.0/78.2 GB disk)\n" + ] + } + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "cQ9BwaAqxAm4" + }, + "source": [ + "# Start\n", + "\n", + "Login with your [API key](https://hub.ultralytics.com/settings?tab=api+keys), select your YOLO 🚀 model and start training!" + ] + }, + { + "cell_type": "code", + "metadata": { + "id": "XSlZaJ9Iw_iZ" + }, + "source": [ + "hub.login('API_KEY') # use your API key\n", + "\n", + "model = YOLO('https://hub.ultralytics.com/models/MODEL_ID') # use your model URL\n", + "results = model.train() # train model" + ], + "execution_count": null, + "outputs": [] + } + ] +} \ No newline at end of file diff --git a/examples/object_counting.ipynb b/examples/object_counting.ipynb new file mode 100644 index 0000000..83ad873 --- /dev/null +++ b/examples/object_counting.ipynb @@ -0,0 +1,147 @@ +{ + "nbformat": 4, + "nbformat_minor": 0, + "metadata": { + "colab": { + "provenance": [], + "gpuType": "T4" + }, + "kernelspec": { + "name": "python3", + "display_name": "Python 3" + }, + "language_info": { + "name": "python" + }, + "accelerator": "GPU" + }, + "cells": [ + { + "cell_type": "markdown", + "source": [ + "
\n", + "\n", + " \n", + " \n", + "\n", + " [中文](https://docs.ultralytics.com/zh/) | [한국어](https://docs.ultralytics.com/ko/) | [日本語](https://docs.ultralytics.com/ja/) | [Русский](https://docs.ultralytics.com/ru/) | [Deutsch](https://docs.ultralytics.com/de/) | [Français](https://docs.ultralytics.com/fr/) | [Español](https://docs.ultralytics.com/es/) | [Português](https://docs.ultralytics.com/pt/) | [हिन्दी](https://docs.ultralytics.com/hi/) | [العربية](https://docs.ultralytics.com/ar/)\n", + "\n", + " \"Open\n", + "\n", + "Welcome to the Ultralytics YOLOv8 🚀 notebook! YOLOv8 is the latest version of the YOLO (You Only Look Once) AI models developed by Ultralytics. This notebook serves as the starting point for exploring the Object Counting and understand its features and capabilities.\n", + "\n", + "YOLOv8 models are fast, accurate, and easy to use, making them ideal for various object detection and image segmentation tasks. They can be trained on large datasets and run on diverse hardware platforms, from CPUs to GPUs.\n", + "\n", + "We hope that the resources in this notebook will help you get the most out of Ultralytics Object Counting. Please browse the YOLOv8 Docs for details, raise an issue on GitHub for support, and join our Discord community for questions and discussions!\n", + "\n", + "
" + ], + "metadata": { + "id": "PN1cAxdvd61e" + } + }, + { + "cell_type": "markdown", + "source": [ + "# Setup\n", + "\n", + "Pip install `ultralytics` and [dependencies](https://github.com/ultralytics/ultralytics/blob/main/pyproject.toml) and check software and hardware." + ], + "metadata": { + "id": "o68Sg1oOeZm2" + } + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "id": "9dSwz_uOReMI" + }, + "outputs": [], + "source": [ + "!pip install ultralytics" + ] + }, + { + "cell_type": "markdown", + "source": [ + "# Ultralytics Object Counting\n", + "\n", + "Counting objects using Ultralytics YOLOv8 entails the precise detection and enumeration of specific objects within videos and camera streams. YOLOv8 demonstrates exceptional performance in real-time applications, delivering efficient and accurate object counting across diverse scenarios such as crowd analysis and surveillance. This is attributed to its advanced algorithms and deep learning capabilities." + ], + "metadata": { + "id": "m7VkxQ2aeg7k" + } + }, + { + "cell_type": "code", + "source": [ + "from ultralytics import YOLO\n", + "from ultralytics.solutions import object_counter\n", + "import cv2\n", + "\n", + "model = YOLO(\"yolov8n.pt\")\n", + "cap = cv2.VideoCapture(\"path/to/video/file.mp4\")\n", + "assert cap.isOpened(), \"Error reading video file\"\n", + "w, h, fps = (int(cap.get(x)) for x in (cv2.CAP_PROP_FRAME_WIDTH, cv2.CAP_PROP_FRAME_HEIGHT, cv2.CAP_PROP_FPS))\n", + "\n", + "# Define region points\n", + "region_points = [(20, 400), (1080, 404), (1080, 360), (20, 360)]\n", + "\n", + "# Video writer\n", + "video_writer = cv2.VideoWriter(\"object_counting_output.avi\",\n", + " cv2.VideoWriter_fourcc(*'mp4v'),\n", + " fps,\n", + " (w, h))\n", + "\n", + "# Init Object Counter\n", + "counter = object_counter.ObjectCounter()\n", + "counter.set_args(view_img=True,\n", + " reg_pts=region_points,\n", + " classes_names=model.names,\n", + " draw_tracks=True)\n", + "\n", + "while cap.isOpened():\n", + " success, im0 = cap.read()\n", + " if not success:\n", + " print(\"Video frame is empty or video processing has been successfully completed.\")\n", + " break\n", + " tracks = model.track(im0, persist=True, show=False)\n", + "\n", + " im0 = counter.start_counting(im0, tracks)\n", + " video_writer.write(im0)\n", + "\n", + "cap.release()\n", + "video_writer.release()\n", + "cv2.destroyAllWindows()" + ], + "metadata": { + "id": "Cx-u59HQdu2o" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "#Community Support\n", + "\n", + "For more information, you can explore Ultralytics Object Counting Docs\n", + "\n", + "Ultralytics ⚡ resources\n", + "- About Us – https://ultralytics.com/about\n", + "- Join Our Team – https://ultralytics.com/work\n", + "- Contact Us – https://ultralytics.com/contact\n", + "- Discord – https://ultralytics.com/discord\n", + "- Ultralytics License – https://ultralytics.com/license\n", + "\n", + "YOLOv8 🚀 resources\n", + "- GitHub – https://github.com/ultralytics/ultralytics\n", + "- Docs – https://docs.ultralytics.com/" + ], + "metadata": { + "id": "QrlKg-y3fEyD" + } + } + ] +} \ No newline at end of file diff --git a/examples/object_tracking.ipynb b/examples/object_tracking.ipynb new file mode 100644 index 0000000..1825f69 --- /dev/null +++ b/examples/object_tracking.ipynb @@ -0,0 +1,203 @@ +{ + "nbformat": 4, + "nbformat_minor": 0, + "metadata": { + "colab": { + "provenance": [], + "gpuType": "T4" + }, + "kernelspec": { + "name": "python3", + "display_name": "Python 3" + }, + "language_info": { + "name": "python" + }, + "accelerator": "GPU" + }, + "cells": [ + { + "cell_type": "markdown", + "source": [ + "
\n", + "\n", + " \n", + " \n", + "\n", + " [中文](https://docs.ultralytics.com/zh/) | [한국어](https://docs.ultralytics.com/ko/) | [日本語](https://docs.ultralytics.com/ja/) | [Русский](https://docs.ultralytics.com/ru/) | [Deutsch](https://docs.ultralytics.com/de/) | [Français](https://docs.ultralytics.com/fr/) | [Español](https://docs.ultralytics.com/es/) | [Português](https://docs.ultralytics.com/pt/) | [हिन्दी](https://docs.ultralytics.com/hi/) | [العربية](https://docs.ultralytics.com/ar/)\n", + "\n", + " \"Open\n", + "\n", + "Welcome to the Ultralytics YOLOv8 🚀 notebook! YOLOv8 is the latest version of the YOLO (You Only Look Once) AI models developed by Ultralytics. This notebook serves as the starting point for exploring the Object Tracking and understand its features and capabilities.\n", + "\n", + "YOLOv8 models are fast, accurate, and easy to use, making them ideal for various object detection and image segmentation tasks. They can be trained on large datasets and run on diverse hardware platforms, from CPUs to GPUs.\n", + "\n", + "We hope that the resources in this notebook will help you get the most out of Ultralytics Object Tracking. Please browse the YOLOv8 Docs for details, raise an issue on GitHub for support, and join our Discord community for questions and discussions!\n", + "\n", + "
" + ], + "metadata": { + "id": "PN1cAxdvd61e" + } + }, + { + "cell_type": "markdown", + "source": [ + "# Setup\n", + "\n", + "Pip install `ultralytics` and [dependencies](https://github.com/ultralytics/ultralytics/blob/main/pyproject.toml) and check software and hardware." + ], + "metadata": { + "id": "o68Sg1oOeZm2" + } + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "id": "9dSwz_uOReMI" + }, + "outputs": [], + "source": [ + "!pip install ultralytics" + ] + }, + { + "cell_type": "markdown", + "source": [ + "# Ultralytics Object Tracking\n", + "\n", + "Within the domain of video analytics, object tracking stands out as a crucial undertaking. It goes beyond merely identifying the location and class of objects within the frame; it also involves assigning a unique ID to each detected object as the video unfolds. The applications of this technology are vast, spanning from surveillance and security to real-time sports analytics." + ], + "metadata": { + "id": "m7VkxQ2aeg7k" + } + }, + { + "cell_type": "markdown", + "source": [ + "## CLI" + ], + "metadata": { + "id": "-ZF9DM6e6gz0" + } + }, + { + "cell_type": "code", + "source": [ + "!yolo track source=\"/path/to/video/file.mp4\" save=True" + ], + "metadata": { + "id": "-XJqhOwo6iqT" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "## Python\n", + "\n", + "- Draw Object tracking trails" + ], + "metadata": { + "id": "XRcw0vIE6oNb" + } + }, + { + "cell_type": "code", + "source": [ + "import cv2\n", + "import numpy as np\n", + "from ultralytics import YOLO\n", + "\n", + "from ultralytics.utils.checks import check_imshow\n", + "from ultralytics.utils.plotting import Annotator, colors\n", + "\n", + "from collections import defaultdict\n", + "\n", + "track_history = defaultdict(lambda: [])\n", + "model = YOLO(\"yolov8n.pt\")\n", + "names = model.model.names\n", + "\n", + "video_path = \"/path/to/video/file.mp4\"\n", + "cap = cv2.VideoCapture(video_path)\n", + "assert cap.isOpened(), \"Error reading video file\"\n", + "\n", + "w, h, fps = (int(cap.get(x)) for x in (cv2.CAP_PROP_FRAME_WIDTH, cv2.CAP_PROP_FRAME_HEIGHT, cv2.CAP_PROP_FPS))\n", + "\n", + "result = cv2.VideoWriter(\"object_tracking.avi\",\n", + " cv2.VideoWriter_fourcc(*'mp4v'),\n", + " fps,\n", + " (w, h))\n", + "\n", + "while cap.isOpened():\n", + " success, frame = cap.read()\n", + " if success:\n", + " results = model.track(frame, persist=True, verbose=False)\n", + " boxes = results[0].boxes.xyxy.cpu()\n", + "\n", + " if results[0].boxes.id is not None:\n", + "\n", + " # Extract prediction results\n", + " clss = results[0].boxes.cls.cpu().tolist()\n", + " track_ids = results[0].boxes.id.int().cpu().tolist()\n", + " confs = results[0].boxes.conf.float().cpu().tolist()\n", + "\n", + " # Annotator Init\n", + " annotator = Annotator(frame, line_width=2)\n", + "\n", + " for box, cls, track_id in zip(boxes, clss, track_ids):\n", + " annotator.box_label(box, color=colors(int(cls), True), label=names[int(cls)])\n", + "\n", + " # Store tracking history\n", + " track = track_history[track_id]\n", + " track.append((int((box[0] + box[2]) / 2), int((box[1] + box[3]) / 2)))\n", + " if len(track) > 30:\n", + " track.pop(0)\n", + "\n", + " # Plot tracks\n", + " points = np.array(track, dtype=np.int32).reshape((-1, 1, 2))\n", + " cv2.circle(frame, (track[-1]), 7, colors(int(cls), True), -1)\n", + " cv2.polylines(frame, [points], isClosed=False, color=colors(int(cls), True), thickness=2)\n", + "\n", + " result.write(frame)\n", + " if cv2.waitKey(1) & 0xFF == ord(\"q\"):\n", + " break\n", + " else:\n", + " break\n", + "\n", + "result.release()\n", + "cap.release()\n", + "cv2.destroyAllWindows()" + ], + "metadata": { + "id": "Cx-u59HQdu2o" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "#Community Support\n", + "\n", + "For more information, you can explore Ultralytics Object Tracking Docs\n", + "\n", + "Ultralytics ⚡ resources\n", + "- About Us – https://ultralytics.com/about\n", + "- Join Our Team – https://ultralytics.com/work\n", + "- Contact Us – https://ultralytics.com/contact\n", + "- Discord – https://ultralytics.com/discord\n", + "- Ultralytics License – https://ultralytics.com/license\n", + "\n", + "YOLOv8 🚀 resources\n", + "- GitHub – https://github.com/ultralytics/ultralytics\n", + "- Docs – https://docs.ultralytics.com/" + ], + "metadata": { + "id": "QrlKg-y3fEyD" + } + } + ] +} diff --git a/examples/tutorial.ipynb b/examples/tutorial.ipynb new file mode 100644 index 0000000..51e5c8f --- /dev/null +++ b/examples/tutorial.ipynb @@ -0,0 +1,649 @@ +{ + "nbformat": 4, + "nbformat_minor": 0, + "metadata": { + "colab": { + "name": "YOLOv8 Tutorial", + "provenance": [], + "toc_visible": true + }, + "kernelspec": { + "name": "python3", + "display_name": "Python 3" + }, + "accelerator": "GPU" + }, + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "id": "t6MPjfT5NrKQ" + }, + "source": [ + "
\n", + "\n", + " \n", + " \n", + "\n", + " [中文](https://docs.ultralytics.com/zh/) | [한국어](https://docs.ultralytics.com/ko/) | [日本語](https://docs.ultralytics.com/ja/) | [Русский](https://docs.ultralytics.com/ru/) | [Deutsch](https://docs.ultralytics.com/de/) | [Français](https://docs.ultralytics.com/fr/) | [Español](https://docs.ultralytics.com/es/) | [Português](https://docs.ultralytics.com/pt/) | [हिन्दी](https://docs.ultralytics.com/hi/) | [العربية](https://docs.ultralytics.com/ar/)\n", + "\n", + " \"Run\n", + " \"Open\n", + " \"Open\n", + "\n", + "Welcome to the Ultralytics YOLOv8 🚀 notebook! YOLOv8 is the latest version of the YOLO (You Only Look Once) AI models developed by Ultralytics. This notebook serves as the starting point for exploring the various resources available to help you get started with YOLOv8 and understand its features and capabilities.\n", + "\n", + "YOLOv8 models are fast, accurate, and easy to use, making them ideal for various object detection and image segmentation tasks. They can be trained on large datasets and run on diverse hardware platforms, from CPUs to GPUs.\n", + "\n", + "We hope that the resources in this notebook will help you get the most out of YOLOv8. Please browse the YOLOv8 Docs for details, raise an issue on GitHub for support, and join our Discord community for questions and discussions!\n", + "\n", + "
" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "7mGmQbAO5pQb" + }, + "source": [ + "# Setup\n", + "\n", + "Pip install `ultralytics` and [dependencies](https://github.com/ultralytics/ultralytics/blob/main/pyproject.toml) and check software and hardware." + ] + }, + { + "cell_type": "code", + "metadata": { + "id": "wbvMlHd_QwMG", + "colab": { + "base_uri": "https://localhost:8080/" + }, + "outputId": "51d15672-e688-4fb8-d9d0-00d1916d3532" + }, + "source": [ + "%pip install ultralytics\n", + "import ultralytics\n", + "ultralytics.checks()" + ], + "execution_count": 1, + "outputs": [ + { + "output_type": "stream", + "name": "stdout", + "text": [ + "Ultralytics YOLOv8.1.23 🚀 Python-3.10.12 torch-2.1.0+cu121 CUDA:0 (Tesla T4, 15102MiB)\n", + "Setup complete ✅ (2 CPUs, 12.7 GB RAM, 26.3/78.2 GB disk)\n" + ] + } + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "4JnkELT0cIJg" + }, + "source": [ + "# 1. Predict\n", + "\n", + "YOLOv8 may be used directly in the Command Line Interface (CLI) with a `yolo` command for a variety of tasks and modes and accepts additional arguments, i.e. `imgsz=640`. See a full list of available `yolo` [arguments](https://docs.ultralytics.com/usage/cfg/) and other details in the [YOLOv8 Predict Docs](https://docs.ultralytics.com/modes/train/).\n" + ] + }, + { + "cell_type": "code", + "metadata": { + "id": "zR9ZbuQCH7FX", + "colab": { + "base_uri": "https://localhost:8080/" + }, + "outputId": "37738db7-4284-47de-b3ed-b82f2431ed23" + }, + "source": [ + "# Run inference on an image with YOLOv8n\n", + "!yolo predict model=yolov8n.pt source='https://ultralytics.com/images/zidane.jpg'" + ], + "execution_count": 2, + "outputs": [ + { + "output_type": "stream", + "name": "stdout", + "text": [ + "Downloading https://github.com/ultralytics/assets/releases/download/v8.1.0/yolov8n.pt to 'yolov8n.pt'...\n", + "100% 6.23M/6.23M [00:00<00:00, 72.6MB/s]\n", + "Ultralytics YOLOv8.1.23 🚀 Python-3.10.12 torch-2.1.0+cu121 CUDA:0 (Tesla T4, 15102MiB)\n", + "YOLOv8n summary (fused): 168 layers, 3151904 parameters, 0 gradients, 8.7 GFLOPs\n", + "\n", + "Downloading https://ultralytics.com/images/zidane.jpg to 'zidane.jpg'...\n", + "100% 165k/165k [00:00<00:00, 7.05MB/s]\n", + "image 1/1 /content/zidane.jpg: 384x640 2 persons, 1 tie, 162.0ms\n", + "Speed: 13.9ms preprocess, 162.0ms inference, 1259.5ms postprocess per image at shape (1, 3, 384, 640)\n", + "Results saved to \u001b[1mruns/detect/predict\u001b[0m\n", + "💡 Learn more at https://docs.ultralytics.com/modes/predict\n" + ] + } + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "hkAzDWJ7cWTr" + }, + "source": [ + "        \n", + "" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "0eq1SMWl6Sfn" + }, + "source": [ + "# 2. Val\n", + "Validate a model's accuracy on the [COCO](https://docs.ultralytics.com/datasets/detect/coco/) dataset's `val` or `test` splits. The latest YOLOv8 [models](https://github.com/ultralytics/ultralytics#models) are downloaded automatically the first time they are used. See [YOLOv8 Val Docs](https://docs.ultralytics.com/modes/val/) for more information." + ] + }, + { + "cell_type": "code", + "metadata": { + "id": "WQPtK1QYVaD_" + }, + "source": [ + "# Download COCO val\n", + "import torch\n", + "torch.hub.download_url_to_file('https://ultralytics.com/assets/coco2017val.zip', 'tmp.zip') # download (780M - 5000 images)\n", + "!unzip -q tmp.zip -d datasets && rm tmp.zip # unzip" + ], + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "code", + "metadata": { + "id": "X58w8JLpMnjH", + "outputId": "61001937-ccd2-4157-a373-156a57495231", + "colab": { + "base_uri": "https://localhost:8080/" + } + }, + "source": [ + "# Validate YOLOv8n on COCO8 val\n", + "!yolo val model=yolov8n.pt data=coco8.yaml" + ], + "execution_count": 3, + "outputs": [ + { + "output_type": "stream", + "name": "stdout", + "text": [ + "Ultralytics YOLOv8.1.23 🚀 Python-3.10.12 torch-2.1.0+cu121 CUDA:0 (Tesla T4, 15102MiB)\n", + "YOLOv8n summary (fused): 168 layers, 3151904 parameters, 0 gradients, 8.7 GFLOPs\n", + "\n", + "Dataset 'coco8.yaml' images not found ⚠️, missing path '/content/datasets/coco8/images/val'\n", + "Downloading https://ultralytics.com/assets/coco8.zip to '/content/datasets/coco8.zip'...\n", + "100% 433k/433k [00:00<00:00, 12.5MB/s]\n", + "Unzipping /content/datasets/coco8.zip to /content/datasets/coco8...: 100% 25/25 [00:00<00:00, 4546.38file/s]\n", + "Dataset download success ✅ (0.9s), saved to \u001b[1m/content/datasets\u001b[0m\n", + "\n", + "Downloading https://ultralytics.com/assets/Arial.ttf to '/root/.config/Ultralytics/Arial.ttf'...\n", + "100% 755k/755k [00:00<00:00, 17.8MB/s]\n", + "\u001b[34m\u001b[1mval: \u001b[0mScanning /content/datasets/coco8/labels/val... 4 images, 0 backgrounds, 0 corrupt: 100% 4/4 [00:00<00:00, 275.94it/s]\n", + "\u001b[34m\u001b[1mval: \u001b[0mNew cache created: /content/datasets/coco8/labels/val.cache\n", + " Class Images Instances Box(P R mAP50 mAP50-95): 100% 1/1 [00:02<00:00, 2.23s/it]\n", + " all 4 17 0.621 0.833 0.888 0.63\n", + " person 4 10 0.721 0.5 0.519 0.269\n", + " dog 4 1 0.37 1 0.995 0.597\n", + " horse 4 2 0.751 1 0.995 0.631\n", + " elephant 4 2 0.505 0.5 0.828 0.394\n", + " umbrella 4 1 0.564 1 0.995 0.995\n", + " potted plant 4 1 0.814 1 0.995 0.895\n", + "Speed: 0.3ms preprocess, 56.9ms inference, 0.0ms loss, 222.8ms postprocess per image\n", + "Results saved to \u001b[1mruns/detect/val\u001b[0m\n", + "💡 Learn more at https://docs.ultralytics.com/modes/val\n" + ] + } + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "ZY2VXXXu74w5" + }, + "source": [ + "# 3. Train\n", + "\n", + "

\n", + "\n", + "Train YOLOv8 on [Detect](https://docs.ultralytics.com/tasks/detect/), [Segment](https://docs.ultralytics.com/tasks/segment/), [Classify](https://docs.ultralytics.com/tasks/classify/) and [Pose](https://docs.ultralytics.com/tasks/pose/) datasets. See [YOLOv8 Train Docs](https://docs.ultralytics.com/modes/train/) for more information." + ] + }, + { + "cell_type": "code", + "source": [ + "#@title Select YOLOv8 🚀 logger {run: 'auto'}\n", + "logger = 'Comet' #@param ['Comet', 'TensorBoard']\n", + "\n", + "if logger == 'Comet':\n", + " %pip install -q comet_ml\n", + " import comet_ml; comet_ml.init()\n", + "elif logger == 'TensorBoard':\n", + " %load_ext tensorboard\n", + " %tensorboard --logdir ." + ], + "metadata": { + "id": "ktegpM42AooT" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "code", + "metadata": { + "id": "1NcFxRcFdJ_O", + "outputId": "1ec62d53-41eb-444f-e2f7-cef5c18b9a27", + "colab": { + "base_uri": "https://localhost:8080/" + } + }, + "source": [ + "# Train YOLOv8n on COCO8 for 3 epochs\n", + "!yolo train model=yolov8n.pt data=coco8.yaml epochs=3 imgsz=640" + ], + "execution_count": 4, + "outputs": [ + { + "output_type": "stream", + "name": "stdout", + "text": [ + "Ultralytics YOLOv8.1.23 🚀 Python-3.10.12 torch-2.1.0+cu121 CUDA:0 (Tesla T4, 15102MiB)\n", + "\u001b[34m\u001b[1mengine/trainer: \u001b[0mtask=detect, mode=train, model=yolov8n.pt, data=coco8.yaml, epochs=3, time=None, patience=100, batch=16, imgsz=640, save=True, save_period=-1, cache=False, device=None, workers=8, project=None, name=train, exist_ok=False, pretrained=True, optimizer=auto, verbose=True, seed=0, deterministic=True, single_cls=False, rect=False, cos_lr=False, close_mosaic=10, resume=False, amp=True, fraction=1.0, profile=False, freeze=None, multi_scale=False, overlap_mask=True, mask_ratio=4, dropout=0.0, val=True, split=val, save_json=False, save_hybrid=False, conf=None, iou=0.7, max_det=300, half=False, dnn=False, plots=True, source=None, vid_stride=1, stream_buffer=False, visualize=False, augment=False, agnostic_nms=False, classes=None, retina_masks=False, embed=None, show=False, save_frames=False, save_txt=False, save_conf=False, save_crop=False, show_labels=True, show_conf=True, show_boxes=True, line_width=None, format=torchscript, keras=False, optimize=False, int8=False, dynamic=False, simplify=False, opset=None, workspace=4, nms=False, lr0=0.01, lrf=0.01, momentum=0.937, weight_decay=0.0005, warmup_epochs=3.0, warmup_momentum=0.8, warmup_bias_lr=0.1, box=7.5, cls=0.5, dfl=1.5, pose=12.0, kobj=1.0, label_smoothing=0.0, nbs=64, hsv_h=0.015, hsv_s=0.7, hsv_v=0.4, degrees=0.0, translate=0.1, scale=0.5, shear=0.0, perspective=0.0, flipud=0.0, fliplr=0.5, mosaic=1.0, mixup=0.0, copy_paste=0.0, auto_augment=randaugment, erasing=0.4, crop_fraction=1.0, cfg=None, tracker=botsort.yaml, save_dir=runs/detect/train\n", + "\n", + " from n params module arguments \n", + " 0 -1 1 464 ultralytics.nn.modules.conv.Conv [3, 16, 3, 2] \n", + " 1 -1 1 4672 ultralytics.nn.modules.conv.Conv [16, 32, 3, 2] \n", + " 2 -1 1 7360 ultralytics.nn.modules.block.C2f [32, 32, 1, True] \n", + " 3 -1 1 18560 ultralytics.nn.modules.conv.Conv [32, 64, 3, 2] \n", + " 4 -1 2 49664 ultralytics.nn.modules.block.C2f [64, 64, 2, True] \n", + " 5 -1 1 73984 ultralytics.nn.modules.conv.Conv [64, 128, 3, 2] \n", + " 6 -1 2 197632 ultralytics.nn.modules.block.C2f [128, 128, 2, True] \n", + " 7 -1 1 295424 ultralytics.nn.modules.conv.Conv [128, 256, 3, 2] \n", + " 8 -1 1 460288 ultralytics.nn.modules.block.C2f [256, 256, 1, True] \n", + " 9 -1 1 164608 ultralytics.nn.modules.block.SPPF [256, 256, 5] \n", + " 10 -1 1 0 torch.nn.modules.upsampling.Upsample [None, 2, 'nearest'] \n", + " 11 [-1, 6] 1 0 ultralytics.nn.modules.conv.Concat [1] \n", + " 12 -1 1 148224 ultralytics.nn.modules.block.C2f [384, 128, 1] \n", + " 13 -1 1 0 torch.nn.modules.upsampling.Upsample [None, 2, 'nearest'] \n", + " 14 [-1, 4] 1 0 ultralytics.nn.modules.conv.Concat [1] \n", + " 15 -1 1 37248 ultralytics.nn.modules.block.C2f [192, 64, 1] \n", + " 16 -1 1 36992 ultralytics.nn.modules.conv.Conv [64, 64, 3, 2] \n", + " 17 [-1, 12] 1 0 ultralytics.nn.modules.conv.Concat [1] \n", + " 18 -1 1 123648 ultralytics.nn.modules.block.C2f [192, 128, 1] \n", + " 19 -1 1 147712 ultralytics.nn.modules.conv.Conv [128, 128, 3, 2] \n", + " 20 [-1, 9] 1 0 ultralytics.nn.modules.conv.Concat [1] \n", + " 21 -1 1 493056 ultralytics.nn.modules.block.C2f [384, 256, 1] \n", + " 22 [15, 18, 21] 1 897664 ultralytics.nn.modules.head.Detect [80, [64, 128, 256]] \n", + "Model summary: 225 layers, 3157200 parameters, 3157184 gradients, 8.9 GFLOPs\n", + "\n", + "Transferred 355/355 items from pretrained weights\n", + "\u001b[34m\u001b[1mTensorBoard: \u001b[0mStart with 'tensorboard --logdir runs/detect/train', view at http://localhost:6006/\n", + "Freezing layer 'model.22.dfl.conv.weight'\n", + "\u001b[34m\u001b[1mAMP: \u001b[0mrunning Automatic Mixed Precision (AMP) checks with YOLOv8n...\n", + "\u001b[34m\u001b[1mAMP: \u001b[0mchecks passed ✅\n", + "\u001b[34m\u001b[1mtrain: \u001b[0mScanning /content/datasets/coco8/labels/train... 4 images, 0 backgrounds, 0 corrupt: 100% 4/4 [00:00<00:00, 43351.98it/s]\n", + "\u001b[34m\u001b[1mtrain: \u001b[0mNew cache created: /content/datasets/coco8/labels/train.cache\n", + "\u001b[34m\u001b[1malbumentations: \u001b[0mBlur(p=0.01, blur_limit=(3, 7)), MedianBlur(p=0.01, blur_limit=(3, 7)), ToGray(p=0.01), CLAHE(p=0.01, clip_limit=(1, 4.0), tile_grid_size=(8, 8))\n", + "\u001b[34m\u001b[1mval: \u001b[0mScanning /content/datasets/coco8/labels/val.cache... 4 images, 0 backgrounds, 0 corrupt: 100% 4/4 [00:00\n" + ], + "metadata": { + "id": "Phm9ccmOKye5" + } + }, + { + "cell_type": "markdown", + "source": [ + "## 1. Detection\n", + "\n", + "YOLOv8 _detection_ models have no suffix and are the default YOLOv8 models, i.e. `yolov8n.pt` and are pretrained on COCO. See [Detection Docs](https://docs.ultralytics.com/tasks/detect/) for full details.\n" + ], + "metadata": { + "id": "yq26lwpYK1lq" + } + }, + { + "cell_type": "code", + "source": [ + "# Load YOLOv8n, train it on COCO128 for 3 epochs and predict an image with it\n", + "from ultralytics import YOLO\n", + "\n", + "model = YOLO('yolov8n.pt') # load a pretrained YOLOv8n detection model\n", + "model.train(data='coco128.yaml', epochs=3) # train the model\n", + "model('https://ultralytics.com/images/bus.jpg') # predict on an image" + ], + "metadata": { + "id": "8Go5qqS9LbC5" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "## 2. Segmentation\n", + "\n", + "YOLOv8 _segmentation_ models use the `-seg` suffix, i.e. `yolov8n-seg.pt` and are pretrained on COCO. See [Segmentation Docs](https://docs.ultralytics.com/tasks/segment/) for full details.\n" + ], + "metadata": { + "id": "7ZW58jUzK66B" + } + }, + { + "cell_type": "code", + "source": [ + "# Load YOLOv8n-seg, train it on COCO128-seg for 3 epochs and predict an image with it\n", + "from ultralytics import YOLO\n", + "\n", + "model = YOLO('yolov8n-seg.pt') # load a pretrained YOLOv8n segmentation model\n", + "model.train(data='coco128-seg.yaml', epochs=3) # train the model\n", + "model('https://ultralytics.com/images/bus.jpg') # predict on an image" + ], + "metadata": { + "id": "WFPJIQl_L5HT" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "## 3. Classification\n", + "\n", + "YOLOv8 _classification_ models use the `-cls` suffix, i.e. `yolov8n-cls.pt` and are pretrained on ImageNet. See [Classification Docs](https://docs.ultralytics.com/tasks/classify/) for full details.\n" + ], + "metadata": { + "id": "ax3p94VNK9zR" + } + }, + { + "cell_type": "code", + "source": [ + "# Load YOLOv8n-cls, train it on mnist160 for 3 epochs and predict an image with it\n", + "from ultralytics import YOLO\n", + "\n", + "model = YOLO('yolov8n-cls.pt') # load a pretrained YOLOv8n classification model\n", + "model.train(data='mnist160', epochs=3) # train the model\n", + "model('https://ultralytics.com/images/bus.jpg') # predict on an image" + ], + "metadata": { + "id": "5q9Zu6zlL5rS" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "## 4. Pose\n", + "\n", + "YOLOv8 _pose_ models use the `-pose` suffix, i.e. `yolov8n-pose.pt` and are pretrained on COCO Keypoints. See [Pose Docs](https://docs.ultralytics.com/tasks/pose/) for full details." + ], + "metadata": { + "id": "SpIaFLiO11TG" + } + }, + { + "cell_type": "code", + "source": [ + "# Load YOLOv8n-pose, train it on COCO8-pose for 3 epochs and predict an image with it\n", + "from ultralytics import YOLO\n", + "\n", + "model = YOLO('yolov8n-pose.pt') # load a pretrained YOLOv8n pose model\n", + "model.train(data='coco8-pose.yaml', epochs=3) # train the model\n", + "model('https://ultralytics.com/images/bus.jpg') # predict on an image" + ], + "metadata": { + "id": "si4aKFNg19vX" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "## 4. Oriented Bounding Boxes (OBB)\n", + "\n", + "YOLOv8 _OBB_ models use the `-obb` suffix, i.e. `yolov8n-obb.pt` and are pretrained on the DOTA dataset. See [OBB Docs](https://docs.ultralytics.com/tasks/obb/) for full details." + ], + "metadata": { + "id": "cf5j_T9-B5F0" + } + }, + { + "cell_type": "code", + "source": [ + "# Load YOLOv8n-obb, train it on DOTA8 for 3 epochs and predict an image with it\n", + "from ultralytics import YOLO\n", + "\n", + "model = YOLO('yolov8n-obb.pt') # load a pretrained YOLOv8n OBB model\n", + "model.train(data='coco8-dota.yaml', epochs=3) # train the model\n", + "model('https://ultralytics.com/images/bus.jpg') # predict on an image" + ], + "metadata": { + "id": "IJNKClOOB5YS" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "IEijrePND_2I" + }, + "source": [ + "# Appendix\n", + "\n", + "Additional content below." + ] + }, + { + "cell_type": "code", + "source": [ + "# Pip install from source\n", + "!pip install git+https://github.com/ultralytics/ultralytics@main" + ], + "metadata": { + "id": "pIdE6i8C3LYp" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "code", + "source": [ + "# Git clone and run tests on updates branch\n", + "!git clone https://github.com/ultralytics/ultralytics -b main\n", + "%pip install -qe ultralytics" + ], + "metadata": { + "id": "uRKlwxSJdhd1" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "code", + "source": [ + "# Run tests (Git clone only)\n", + "!pytest ultralytics/tests" + ], + "metadata": { + "id": "GtPlh7mcCGZX" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "code", + "source": [ + "# Validate multiple models\n", + "for x in 'nsmlx':\n", + " !yolo val model=yolov8{x}.pt data=coco.yaml" + ], + "metadata": { + "id": "Wdc6t_bfzDDk" + }, + "execution_count": null, + "outputs": [] + } + ] +} diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..c5cf73a --- /dev/null +++ b/requirements.txt @@ -0,0 +1,29 @@ +# Ultralytics requirements +# Example: pip install -r requirements.txt + +# Base ---------------------------------------- +matplotlib>=3.3.0 +Pillow>=7.1.2 +PyYAML>=5.3.1 +requests>=2.23.0 +scipy>=1.4.1 +tqdm>=4.64.0 +hub-sdk>=0.0.5 + +# Logging ------------------------------------- +# tensorboard>=2.13.0 +# dvclive>=2.12.0 +# comet + +# Plotting ------------------------------------ +pandas>=1.1.4 +seaborn>=0.11.0 + +# Extras -------------------------------------- +psutil # system utilization +py-cpuinfo # display CPU info +thop>=0.1.1 # FLOPs computation +# ipython # interactive notebook +# albumentations>=1.0.3 # training augmentations +# pycocotools>=2.0.6 # COCO mAP +# roboflow diff --git a/setup.cfg b/setup.cfg new file mode 100644 index 0000000..a6fc013 --- /dev/null +++ b/setup.cfg @@ -0,0 +1,70 @@ +# Project-wide configuration file, can be used for package metadata and other toll configurations +# Example usage: global configuration for PEP8 (via flake8) setting or default pytest arguments +# Local usage: pip install pre-commit, pre-commit run --all-files + +[metadata] +license_files = LICENSE +description_file = README.md + +[tool:pytest] +norecursedirs = + .git + dist + build +addopts = + --doctest-modules + --durations=30 + --color=yes + +[coverage:run] +source = ultralytics/ +data_file = tests/.coverage +omit = + ultralytics/utils/callbacks/* + +[flake8] +max-line-length = 120 +exclude = .tox,*.egg,build,temp +select = E,W,F +doctests = True +verbose = 2 +# https://pep8.readthedocs.io/en/latest/intro.html#error-codes +format = pylint +# see: https://www.flake8rules.com/ +ignore = E731,F405,E402,W504,E501 + # E731: Do not assign a lambda expression, use a def + # F405: name may be undefined, or defined from star imports: module + # E402: module level import not at top of file + # W504: line break after binary operator + # E501: line too long + # removed: + # F401: module imported but unused + # E231: missing whitespace after ‘,’, ‘;’, or ‘:’ + # E127: continuation line over-indented for visual indent + # F403: ‘from module import *’ used; unable to detect undefined names + +[isort] +# https://pycqa.github.io/isort/docs/configuration/options.html +line_length = 120 +# see: https://pycqa.github.io/isort/docs/configuration/multi_line_output_modes.html +multi_line_output = 0 + +[yapf] +based_on_style = pep8 +spaces_before_comment = 2 +COLUMN_LIMIT = 120 +COALESCE_BRACKETS = True +SPACES_AROUND_POWER_OPERATOR = True +SPACE_BETWEEN_ENDING_COMMA_AND_CLOSING_BRACKET = True +SPLIT_BEFORE_CLOSING_BRACKET = False +SPLIT_BEFORE_FIRST_ARGUMENT = False +# EACH_DICT_ENTRY_ON_SEPARATE_LINE = False + +[docformatter] +wrap-summaries = 120 +wrap-descriptions = 120 +in-place = true +make-summary-multi-line = false +pre-summary-newline = true +force-wrap = false +close-quotes-on-newline = true diff --git a/setup.py b/setup.py new file mode 100644 index 0000000..b7673ef --- /dev/null +++ b/setup.py @@ -0,0 +1,98 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import re +from pathlib import Path + +from setuptools import setup + +# Settings +FILE = Path(__file__).resolve() +PARENT = FILE.parent # root directory +README = (PARENT / 'README.md').read_text(encoding='utf-8') + + +def get_version(): + """ + Retrieve the version number from the 'ultralytics/__init__.py' file. + + Returns: + (str): The version number extracted from the '__version__' attribute in the 'ultralytics/__init__.py' file. + """ + file = PARENT / 'ultralytics/__init__.py' + return re.search(r'^__version__ = [\'"]([^\'"]*)[\'"]', file.read_text(encoding='utf-8'), re.M)[1] + + +def parse_requirements(file_path: Path): + """ + Parse a requirements.txt file, ignoring lines that start with '#' and any text after '#'. + + Args: + file_path (str | Path): Path to the requirements.txt file. + + Returns: + (List[str]): List of parsed requirements. + """ + requirements = [] + for line in Path(file_path).read_text().splitlines(): + line = line.strip() + if line and not line.startswith('#'): + requirements.append(line.split('#')[0].strip()) # ignore inline comments + + return requirements + + +setup( + name='vsensebox-ultralytics', # name of pypi package + version=get_version(), # version of pypi package + python_requires='>=3.8', + license='AGPL-3.0', + description=('Ultralytics YOLOv8 for SOTA object detection, multi-object tracking, instance segmentation, ' + 'pose estimation and image classification.'), + long_description=README, + long_description_content_type='text/markdown', + url='https://github.com/rathaumons/ultralytics-for-vsensebox', + project_urls={ + 'Bug Reports': 'https://github.com/rathaumons/ultralytics-for-vsensebox/issues', + 'Funding': 'https://ultralytics.com', + 'Source': 'https://github.com/rathaumons/ultralytics-for-vsensebox'}, + packages=['ultralytics'] + [str(x) for x in Path('ultralytics').rglob('*/') if x.is_dir() and '__' not in str(x)], + package_data={ + '': ['*.yaml'], + 'ultralytics.assets': ['*.jpg']}, + include_package_data=True, + install_requires=parse_requirements(PARENT / 'requirements.txt'), + extras_require={ + 'export': [ + 'numpy==1.23.5', + 'onnx>=1.12.0', # ONNX export + 'coremltools>=7.0', + 'openvino>=2024.0.0', # OpenVINO export + ], + 'explorer': [ + 'lancedb', # vector search + 'duckdb<=0.9.2', # SQL queries, duckdb==0.10.0 bug https://github.com/ultralytics/ultralytics/pull/8181 + 'streamlit', # visualizing with GUI + ] + }, + classifiers=[ + 'Development Status :: 4 - Beta', + 'Intended Audience :: Developers', + 'Intended Audience :: Education', + 'Intended Audience :: Science/Research', + 'License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)', + 'Programming Language :: Python :: 3', + 'Programming Language :: Python :: 3.8', + 'Programming Language :: Python :: 3.9', + 'Programming Language :: Python :: 3.10', + 'Programming Language :: Python :: 3.11', + 'Programming Language :: Python :: 3.12', + 'Topic :: Software Development', + 'Topic :: Scientific/Engineering', + 'Topic :: Scientific/Engineering :: Artificial Intelligence', + 'Topic :: Scientific/Engineering :: Image Recognition', + 'Operating System :: POSIX :: Linux', + 'Operating System :: MacOS', + 'Operating System :: Microsoft :: Windows', ], + keywords='machine-learning, deep-learning, vision, ML, DL, AI, YOLO, YOLOv3, YOLOv5, YOLOv8, HUB, Ultralytics', + entry_points={'console_scripts': ['yolo = ultralytics.cfg:entrypoint', 'ultralytics = ultralytics.cfg:entrypoint']} +) diff --git a/tests/conftest.py b/tests/conftest.py new file mode 100644 index 0000000..58c07b7 --- /dev/null +++ b/tests/conftest.py @@ -0,0 +1,71 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import shutil +from pathlib import Path + +TMP = Path(__file__).resolve().parent / "tmp" # temp directory for test files + + +def pytest_addoption(parser): + """ + Add custom command-line options to pytest. + + Args: + parser (pytest.config.Parser): The pytest parser object. + """ + parser.addoption("--slow", action="store_true", default=False, help="Run slow tests") + + +def pytest_collection_modifyitems(config, items): + """ + Modify the list of test items to remove tests marked as slow if the --slow option is not provided. + + Args: + config (pytest.config.Config): The pytest config object. + items (list): List of test items to be executed. + """ + if not config.getoption("--slow"): + # Remove the item entirely from the list of test items if it's marked as 'slow' + items[:] = [item for item in items if "slow" not in item.keywords] + + +def pytest_sessionstart(session): + """ + Initialize session configurations for pytest. + + This function is automatically called by pytest after the 'Session' object has been created but before performing + test collection. It sets the initial seeds and prepares the temporary directory for the test session. + + Args: + session (pytest.Session): The pytest session object. + """ + from ultralytics.utils.torch_utils import init_seeds + + init_seeds() + shutil.rmtree(TMP, ignore_errors=True) # delete any existing tests/tmp directory + TMP.mkdir(parents=True, exist_ok=True) # create a new empty directory + + +def pytest_terminal_summary(terminalreporter, exitstatus, config): + """ + Cleanup operations after pytest session. + + This function is automatically called by pytest at the end of the entire test session. It removes certain files + and directories used during testing. + + Args: + terminalreporter (pytest.terminal.TerminalReporter): The terminal reporter object. + exitstatus (int): The exit status of the test run. + config (pytest.config.Config): The pytest config object. + """ + from ultralytics.utils import WEIGHTS_DIR + + # Remove files + models = [path for x in ["*.onnx", "*.torchscript"] for path in WEIGHTS_DIR.rglob(x)] + for file in ["bus.jpg", "yolov8n.onnx", "yolov8n.torchscript"] + models: + Path(file).unlink(missing_ok=True) + + # Remove directories + models = [path for x in ["*.mlpackage", "*_openvino_model"] for path in WEIGHTS_DIR.rglob(x)] + for directory in [TMP.parents[1] / ".pytest_cache", TMP] + models: + shutil.rmtree(directory, ignore_errors=True) diff --git a/tests/test_cli.py b/tests/test_cli.py new file mode 100644 index 0000000..eeeab07 --- /dev/null +++ b/tests/test_cli.py @@ -0,0 +1,138 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import subprocess + +import pytest + +from ultralytics.utils import ASSETS, WEIGHTS_DIR, checks + +CUDA_IS_AVAILABLE = checks.cuda_is_available() +CUDA_DEVICE_COUNT = checks.cuda_device_count() +TASK_ARGS = [ + ("detect", "yolov8n", "coco8.yaml"), + ("segment", "yolov8n-seg", "coco8-seg.yaml"), + ("classify", "yolov8n-cls", "imagenet10"), + ("pose", "yolov8n-pose", "coco8-pose.yaml"), + ("obb", "yolov8n-obb", "dota8.yaml"), +] # (task, model, data) +EXPORT_ARGS = [ + ("yolov8n", "torchscript"), + ("yolov8n-seg", "torchscript"), + ("yolov8n-cls", "torchscript"), + ("yolov8n-pose", "torchscript"), + ("yolov8n-obb", "torchscript"), +] # (model, format) + + +def run(cmd): + """Execute a shell command using subprocess.""" + subprocess.run(cmd.split(), check=True) + + +def test_special_modes(): + """Test various special command modes of YOLO.""" + run("yolo help") + run("yolo checks") + run("yolo version") + run("yolo settings reset") + run("yolo cfg") + + +@pytest.mark.parametrize("task,model,data", TASK_ARGS) +def test_train(task, model, data): + """Test YOLO training for a given task, model, and data.""" + run(f"yolo train {task} model={model}.yaml data={data} imgsz=32 epochs=1 cache=disk") + + +@pytest.mark.parametrize("task,model,data", TASK_ARGS) +def test_val(task, model, data): + """Test YOLO validation for a given task, model, and data.""" + run(f"yolo val {task} model={WEIGHTS_DIR / model}.pt data={data} imgsz=32 save_txt save_json") + + +@pytest.mark.parametrize("task,model,data", TASK_ARGS) +def test_predict(task, model, data): + """Test YOLO prediction on sample assets for a given task and model.""" + run(f"yolo predict model={WEIGHTS_DIR / model}.pt source={ASSETS} imgsz=32 save save_crop save_txt") + + +@pytest.mark.parametrize("model,format", EXPORT_ARGS) +def test_export(model, format): + """Test exporting a YOLO model to different formats.""" + run(f"yolo export model={WEIGHTS_DIR / model}.pt format={format} imgsz=32") + + +def test_rtdetr(task="detect", model="yolov8n-rtdetr.yaml", data="coco8.yaml"): + """Test the RTDETR functionality with the Ultralytics framework.""" + # Warning: MUST use imgsz=640 + run(f"yolo train {task} model={model} data={data} --imgsz= 160 epochs =1, cache = disk") # add coma, spaces to args + run(f"yolo predict {task} model={model} source={ASSETS / 'bus.jpg'} imgsz=160 save save_crop save_txt") + + +@pytest.mark.skipif(checks.IS_PYTHON_3_12, reason="MobileSAM with CLIP is not supported in Python 3.12") +def test_fastsam(task="segment", model=WEIGHTS_DIR / "FastSAM-s.pt", data="coco8-seg.yaml"): + """Test FastSAM segmentation functionality within Ultralytics.""" + source = ASSETS / "bus.jpg" + + run(f"yolo segment val {task} model={model} data={data} imgsz=32") + run(f"yolo segment predict model={model} source={source} imgsz=32 save save_crop save_txt") + + from ultralytics import FastSAM + from ultralytics.models.fastsam import FastSAMPrompt + from ultralytics.models.sam import Predictor + + # Create a FastSAM model + sam_model = FastSAM(model) # or FastSAM-x.pt + + # Run inference on an image + everything_results = sam_model(source, device="cpu", retina_masks=True, imgsz=1024, conf=0.4, iou=0.9) + + # Remove small regions + new_masks, _ = Predictor.remove_small_regions(everything_results[0].masks.data, min_area=20) + + # Everything prompt + prompt_process = FastSAMPrompt(source, everything_results, device="cpu") + ann = prompt_process.everything_prompt() + + # Bbox default shape [0,0,0,0] -> [x1,y1,x2,y2] + ann = prompt_process.box_prompt(bbox=[200, 200, 300, 300]) + + # Text prompt + ann = prompt_process.text_prompt(text="a photo of a dog") + + # Point prompt + # Points default [[0,0]] [[x1,y1],[x2,y2]] + # Point_label default [0] [1,0] 0:background, 1:foreground + ann = prompt_process.point_prompt(points=[[200, 200]], pointlabel=[1]) + prompt_process.plot(annotations=ann, output="./") + + +def test_mobilesam(): + """Test MobileSAM segmentation functionality using Ultralytics.""" + from ultralytics import SAM + + # Load the model + model = SAM(WEIGHTS_DIR / "mobile_sam.pt") + + # Source + source = ASSETS / "zidane.jpg" + + # Predict a segment based on a point prompt + model.predict(source, points=[900, 370], labels=[1]) + + # Predict a segment based on a box prompt + model.predict(source, bboxes=[439, 437, 524, 709]) + + # Predict all + # model(source) + + +# Slow Tests ----------------------------------------------------------------------------------------------------------- +@pytest.mark.slow +@pytest.mark.parametrize("task,model,data", TASK_ARGS) +@pytest.mark.skipif(not CUDA_IS_AVAILABLE, reason="CUDA is not available") +@pytest.mark.skipif(CUDA_DEVICE_COUNT < 2, reason="DDP is not available") +def test_train_gpu(task, model, data): + """Test YOLO training on GPU(s) for various tasks and models.""" + run(f"yolo train {task} model={model}.yaml data={data} imgsz=32 epochs=1 device=0") # single GPU + run(f"yolo train {task} model={model}.pt data={data} imgsz=32 epochs=1 device=0,1") # multi GPU diff --git a/tests/test_engine.py b/tests/test_engine.py new file mode 100644 index 0000000..31088d9 --- /dev/null +++ b/tests/test_engine.py @@ -0,0 +1,133 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import sys +from unittest import mock + +from ultralytics import YOLO +from ultralytics.cfg import get_cfg +from ultralytics.engine.exporter import Exporter +from ultralytics.models.yolo import classify, detect, segment +from ultralytics.utils import ASSETS, DEFAULT_CFG, WEIGHTS_DIR + +CFG_DET = "yolov8n.yaml" +CFG_SEG = "yolov8n-seg.yaml" +CFG_CLS = "yolov8n-cls.yaml" # or 'squeezenet1_0' +CFG = get_cfg(DEFAULT_CFG) +MODEL = WEIGHTS_DIR / "yolov8n" + + +def test_func(*args): # noqa + """Test function callback.""" + print("callback test passed") + + +def test_export(): + """Test model exporting functionality.""" + exporter = Exporter() + exporter.add_callback("on_export_start", test_func) + assert test_func in exporter.callbacks["on_export_start"], "callback test failed" + f = exporter(model=YOLO(CFG_DET).model) + YOLO(f)(ASSETS) # exported model inference + + +def test_detect(): + """Test object detection functionality.""" + overrides = {"data": "coco8.yaml", "model": CFG_DET, "imgsz": 32, "epochs": 1, "save": False} + CFG.data = "coco8.yaml" + CFG.imgsz = 32 + + # Trainer + trainer = detect.DetectionTrainer(overrides=overrides) + trainer.add_callback("on_train_start", test_func) + assert test_func in trainer.callbacks["on_train_start"], "callback test failed" + trainer.train() + + # Validator + val = detect.DetectionValidator(args=CFG) + val.add_callback("on_val_start", test_func) + assert test_func in val.callbacks["on_val_start"], "callback test failed" + val(model=trainer.best) # validate best.pt + + # Predictor + pred = detect.DetectionPredictor(overrides={"imgsz": [64, 64]}) + pred.add_callback("on_predict_start", test_func) + assert test_func in pred.callbacks["on_predict_start"], "callback test failed" + # Confirm there is no issue with sys.argv being empty. + with mock.patch.object(sys, "argv", []): + result = pred(source=ASSETS, model=f"{MODEL}.pt") + assert len(result), "predictor test failed" + + overrides["resume"] = trainer.last + trainer = detect.DetectionTrainer(overrides=overrides) + try: + trainer.train() + except Exception as e: + print(f"Expected exception caught: {e}") + return + + Exception("Resume test failed!") + + +def test_segment(): + """Test image segmentation functionality.""" + overrides = {"data": "coco8-seg.yaml", "model": CFG_SEG, "imgsz": 32, "epochs": 1, "save": False} + CFG.data = "coco8-seg.yaml" + CFG.imgsz = 32 + # YOLO(CFG_SEG).train(**overrides) # works + + # Trainer + trainer = segment.SegmentationTrainer(overrides=overrides) + trainer.add_callback("on_train_start", test_func) + assert test_func in trainer.callbacks["on_train_start"], "callback test failed" + trainer.train() + + # Validator + val = segment.SegmentationValidator(args=CFG) + val.add_callback("on_val_start", test_func) + assert test_func in val.callbacks["on_val_start"], "callback test failed" + val(model=trainer.best) # validate best.pt + + # Predictor + pred = segment.SegmentationPredictor(overrides={"imgsz": [64, 64]}) + pred.add_callback("on_predict_start", test_func) + assert test_func in pred.callbacks["on_predict_start"], "callback test failed" + result = pred(source=ASSETS, model=f"{MODEL}-seg.pt") + assert len(result), "predictor test failed" + + # Test resume + overrides["resume"] = trainer.last + trainer = segment.SegmentationTrainer(overrides=overrides) + try: + trainer.train() + except Exception as e: + print(f"Expected exception caught: {e}") + return + + Exception("Resume test failed!") + + +def test_classify(): + """Test image classification functionality.""" + overrides = {"data": "imagenet10", "model": CFG_CLS, "imgsz": 32, "epochs": 1, "save": False} + CFG.data = "imagenet10" + CFG.imgsz = 32 + # YOLO(CFG_SEG).train(**overrides) # works + + # Trainer + trainer = classify.ClassificationTrainer(overrides=overrides) + trainer.add_callback("on_train_start", test_func) + assert test_func in trainer.callbacks["on_train_start"], "callback test failed" + trainer.train() + + # Validator + val = classify.ClassificationValidator(args=CFG) + val.add_callback("on_val_start", test_func) + assert test_func in val.callbacks["on_val_start"], "callback test failed" + val(model=trainer.best) + + # Predictor + pred = classify.ClassificationPredictor(overrides={"imgsz": [64, 64]}) + pred.add_callback("on_predict_start", test_func) + assert test_func in pred.callbacks["on_predict_start"], "callback test failed" + result = pred(source=ASSETS, model=trainer.best) + assert len(result), "predictor test failed" diff --git a/tests/test_python.py b/tests/test_python.py new file mode 100644 index 0000000..8869360 --- /dev/null +++ b/tests/test_python.py @@ -0,0 +1,664 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import contextlib +from copy import copy +from pathlib import Path + +import cv2 +import numpy as np +import pytest +import torch +import yaml +from PIL import Image + +from ultralytics import RTDETR, YOLO +from ultralytics.cfg import TASK2DATA +from ultralytics.data.build import load_inference_source +from ultralytics.utils import ( + ASSETS, + DEFAULT_CFG, + DEFAULT_CFG_PATH, + LINUX, + MACOS, + ONLINE, + ROOT, + WEIGHTS_DIR, + WINDOWS, + Retry, + checks, + is_dir_writeable, +) +from ultralytics.utils.downloads import download +from ultralytics.utils.torch_utils import TORCH_1_9, TORCH_1_13 + +MODEL = WEIGHTS_DIR / "path with spaces" / "yolov8n.pt" # test spaces in path +CFG = "yolov8n.yaml" +SOURCE = ASSETS / "bus.jpg" +TMP = (ROOT / "../tests/tmp").resolve() # temp directory for test files +IS_TMP_WRITEABLE = is_dir_writeable(TMP) + + +def test_model_forward(): + """Test the forward pass of the YOLO model.""" + model = YOLO(CFG) + model(source=None, imgsz=32, augment=True) # also test no source and augment + + +def test_model_methods(): + """Test various methods and properties of the YOLO model.""" + model = YOLO(MODEL) + + # Model methods + model.info(verbose=True, detailed=True) + model = model.reset_weights() + model = model.load(MODEL) + model.to("cpu") + model.fuse() + model.clear_callback("on_train_start") + model.reset_callbacks() + + # Model properties + _ = model.names + _ = model.device + _ = model.transforms + _ = model.task_map + + +def test_model_profile(): + """Test profiling of the YOLO model with 'profile=True' argument.""" + from ultralytics.nn.tasks import DetectionModel + + model = DetectionModel() # build model + im = torch.randn(1, 3, 64, 64) # requires min imgsz=64 + _ = model.predict(im, profile=True) + + +@pytest.mark.skipif(not IS_TMP_WRITEABLE, reason="directory is not writeable") +def test_predict_txt(): + """Test YOLO predictions with sources (file, dir, glob, recursive glob) specified in a text file.""" + txt_file = TMP / "sources.txt" + with open(txt_file, "w") as f: + for x in [ASSETS / "bus.jpg", ASSETS, ASSETS / "*", ASSETS / "**/*.jpg"]: + f.write(f"{x}\n") + _ = YOLO(MODEL)(source=txt_file, imgsz=32) + + +def test_predict_img(): + """Test YOLO prediction on various types of image sources.""" + model = YOLO(MODEL) + seg_model = YOLO(WEIGHTS_DIR / "yolov8n-seg.pt") + cls_model = YOLO(WEIGHTS_DIR / "yolov8n-cls.pt") + pose_model = YOLO(WEIGHTS_DIR / "yolov8n-pose.pt") + obb_model = YOLO(WEIGHTS_DIR / "yolov8n-obb.pt") + im = cv2.imread(str(SOURCE)) + assert len(model(source=Image.open(SOURCE), save=True, verbose=True, imgsz=32)) == 1 # PIL + assert len(model(source=im, save=True, save_txt=True, imgsz=32)) == 1 # ndarray + assert len(model(source=[im, im], save=True, save_txt=True, imgsz=32)) == 2 # batch + assert len(list(model(source=[im, im], save=True, stream=True, imgsz=32))) == 2 # stream + assert len(model(torch.zeros(320, 640, 3).numpy(), imgsz=32)) == 1 # tensor to numpy + batch = [ + str(SOURCE), # filename + Path(SOURCE), # Path + "https://ultralytics.com/images/zidane.jpg" if ONLINE else SOURCE, # URI + cv2.imread(str(SOURCE)), # OpenCV + Image.open(SOURCE), # PIL + np.zeros((320, 640, 3)), + ] # numpy + assert len(model(batch, imgsz=32)) == len(batch) # multiple sources in a batch + + # Test tensor inference + im = torch.rand((4, 3, 32, 32)) # batch-size 4, FP32 0.0-1.0 RGB order + results = model(im, imgsz=32) + assert len(results) == im.shape[0] + results = seg_model(im, imgsz=32) + assert len(results) == im.shape[0] + results = cls_model(im, imgsz=32) + assert len(results) == im.shape[0] + results = pose_model(im, imgsz=32) + assert len(results) == im.shape[0] + results = obb_model(im, imgsz=32) + assert len(results) == im.shape[0] + + +def test_predict_grey_and_4ch(): + """Test YOLO prediction on SOURCE converted to greyscale and 4-channel images.""" + im = Image.open(SOURCE) + directory = TMP / "im4" + directory.mkdir(parents=True, exist_ok=True) + + source_greyscale = directory / "greyscale.jpg" + source_rgba = directory / "4ch.png" + source_non_utf = directory / "non_UTF_测试文件_tést_image.jpg" + source_spaces = directory / "image with spaces.jpg" + + im.convert("L").save(source_greyscale) # greyscale + im.convert("RGBA").save(source_rgba) # 4-ch PNG with alpha + im.save(source_non_utf) # non-UTF characters in filename + im.save(source_spaces) # spaces in filename + + # Inference + model = YOLO(MODEL) + for f in source_rgba, source_greyscale, source_non_utf, source_spaces: + for source in Image.open(f), cv2.imread(str(f)), f: + results = model(source, save=True, verbose=True, imgsz=32) + assert len(results) == 1 # verify that an image was run + f.unlink() # cleanup + + +@pytest.mark.slow +@pytest.mark.skipif(not ONLINE, reason="environment is offline") +@Retry(times=3, delay=10) +def test_youtube(): + """ + Test YouTube inference. + + Marked --slow to reduce YouTube API rate limits risk. + """ + model = YOLO(MODEL) + model.predict("https://youtu.be/G17sBkb38XQ", imgsz=96, save=True) + + +@pytest.mark.skipif(not ONLINE, reason="environment is offline") +@pytest.mark.skipif(not IS_TMP_WRITEABLE, reason="directory is not writeable") +def test_track_stream(): + """ + Test streaming tracking (short 10 frame video) with non-default ByteTrack tracker. + + Note imgsz=160 required for tracking for higher confidence and better matches + """ + video_url = "https://ultralytics.com/assets/decelera_portrait_min.mov" + model = YOLO(MODEL) + model.track(video_url, imgsz=160, tracker="bytetrack.yaml") + model.track(video_url, imgsz=160, tracker="botsort.yaml", save_frames=True) # test frame saving also + + # Test Global Motion Compensation (GMC) methods + for gmc in "orb", "sift", "ecc": + with open(ROOT / "cfg/trackers/botsort.yaml", encoding="utf-8") as f: + data = yaml.safe_load(f) + tracker = TMP / f"botsort-{gmc}.yaml" + data["gmc_method"] = gmc + with open(tracker, "w", encoding="utf-8") as f: + yaml.safe_dump(data, f) + model.track(video_url, imgsz=160, tracker=tracker) + + +def test_val(): + """Test the validation mode of the YOLO model.""" + YOLO(MODEL).val(data="coco8.yaml", imgsz=32, save_hybrid=True) + + +def test_train_scratch(): + """Test training the YOLO model from scratch.""" + model = YOLO(CFG) + model.train(data="coco8.yaml", epochs=2, imgsz=32, cache="disk", batch=-1, close_mosaic=1, name="model") + model(SOURCE) + + +def test_train_pretrained(): + """Test training the YOLO model from a pre-trained state.""" + model = YOLO(WEIGHTS_DIR / "yolov8n-seg.pt") + model.train(data="coco8-seg.yaml", epochs=1, imgsz=32, cache="ram", copy_paste=0.5, mixup=0.5, name=0) + model(SOURCE) + + +def test_export_torchscript(): + """Test exporting the YOLO model to TorchScript format.""" + f = YOLO(MODEL).export(format="torchscript", optimize=False) + YOLO(f)(SOURCE) # exported model inference + + +def test_export_onnx(): + """Test exporting the YOLO model to ONNX format.""" + f = YOLO(MODEL).export(format="onnx", dynamic=True) + YOLO(f)(SOURCE) # exported model inference + + +@pytest.mark.skipif(checks.IS_PYTHON_3_12, reason="OpenVINO not supported in Python 3.12") +@pytest.mark.skipif(not TORCH_1_13, reason="OpenVINO requires torch>=1.13") +def test_export_openvino(): + """Test exporting the YOLO model to OpenVINO format.""" + f = YOLO(MODEL).export(format="openvino") + YOLO(f)(SOURCE) # exported model inference + + +@pytest.mark.skipif(checks.IS_PYTHON_3_12, reason="CoreML not supported in Python 3.12") +def test_export_coreml(): + """Test exporting the YOLO model to CoreML format.""" + if not WINDOWS: # RuntimeError: BlobWriter not loaded with coremltools 7.0 on windows + if MACOS: + f = YOLO(MODEL).export(format="coreml") + YOLO(f)(SOURCE) # model prediction only supported on macOS for nms=False models + else: + YOLO(MODEL).export(format="coreml", nms=True) + + +def test_export_tflite(enabled=False): + """ + Test exporting the YOLO model to TFLite format. + + Note TF suffers from install conflicts on Windows and macOS. + """ + if enabled and LINUX: + model = YOLO(MODEL) + f = model.export(format="tflite") + YOLO(f)(SOURCE) + + +def test_export_pb(enabled=False): + """ + Test exporting the YOLO model to *.pb format. + + Note TF suffers from install conflicts on Windows and macOS. + """ + if enabled and LINUX: + model = YOLO(MODEL) + f = model.export(format="pb") + YOLO(f)(SOURCE) + + +def test_export_paddle(enabled=False): + """ + Test exporting the YOLO model to Paddle format. + + Note Paddle protobuf requirements conflicting with onnx protobuf requirements. + """ + if enabled: + YOLO(MODEL).export(format="paddle") + + +@pytest.mark.slow +def test_export_ncnn(): + """Test exporting the YOLO model to NCNN format.""" + f = YOLO(MODEL).export(format="ncnn") + YOLO(f)(SOURCE) # exported model inference + + +def test_all_model_yamls(): + """Test YOLO model creation for all available YAML configurations.""" + for m in (ROOT / "cfg" / "models").rglob("*.yaml"): + if "rtdetr" in m.name: + if TORCH_1_9: # torch<=1.8 issue - TypeError: __init__() got an unexpected keyword argument 'batch_first' + _ = RTDETR(m.name)(SOURCE, imgsz=640) # must be 640 + else: + YOLO(m.name) + + +def test_workflow(): + """Test the complete workflow including training, validation, prediction, and exporting.""" + model = YOLO(MODEL) + model.train(data="coco8.yaml", epochs=1, imgsz=32, optimizer="SGD") + model.val(imgsz=32) + model.predict(SOURCE, imgsz=32) + model.export(format="onnx") # export a model to ONNX format + + +def test_predict_callback_and_setup(): + """Test callback functionality during YOLO prediction.""" + + def on_predict_batch_end(predictor): + """Callback function that handles operations at the end of a prediction batch.""" + path, im0s, _ = predictor.batch + im0s = im0s if isinstance(im0s, list) else [im0s] + bs = [predictor.dataset.bs for _ in range(len(path))] + predictor.results = zip(predictor.results, im0s, bs) # results is List[batch_size] + + model = YOLO(MODEL) + model.add_callback("on_predict_batch_end", on_predict_batch_end) + + dataset = load_inference_source(source=SOURCE) + bs = dataset.bs # noqa access predictor properties + results = model.predict(dataset, stream=True, imgsz=160) # source already setup + for r, im0, bs in results: + print("test_callback", im0.shape) + print("test_callback", bs) + boxes = r.boxes # Boxes object for bbox outputs + print(boxes) + + +def test_results(): + """Test various result formats for the YOLO model.""" + for m in "yolov8n-pose.pt", "yolov8n-seg.pt", "yolov8n.pt", "yolov8n-cls.pt": + results = YOLO(WEIGHTS_DIR / m)([SOURCE, SOURCE], imgsz=160) + for r in results: + r = r.cpu().numpy() + r = r.to(device="cpu", dtype=torch.float32) + r.save_txt(txt_file=TMP / "runs/tests/label.txt", save_conf=True) + r.save_crop(save_dir=TMP / "runs/tests/crops/") + r.tojson(normalize=True) + r.plot(pil=True) + r.plot(conf=True, boxes=True) + print(r, len(r), r.path) + + +def test_labels_and_crops(): + """Test output from prediction args for saving detection labels and crops.""" + imgs = [SOURCE, ASSETS / "zidane.jpg"] + results = YOLO(WEIGHTS_DIR / "yolov8n.pt")(imgs, imgsz=160, save_txt=True, save_crop=True) + save_path = Path(results[0].save_dir) + for r in results: + im_name = Path(r.path).stem + cls_idxs = r.boxes.cls.int().tolist() + # Check label path + labels = save_path / f"labels/{im_name}.txt" + assert labels.exists() + # Check detections match label count + assert len(r.boxes.data) == len([l for l in labels.read_text().splitlines() if l]) + # Check crops path and files + crop_dirs = [p for p in (save_path / "crops").iterdir()] + crop_files = [f for p in crop_dirs for f in p.glob("*")] + # Crop directories match detections + assert all([r.names.get(c) in {d.name for d in crop_dirs} for c in cls_idxs]) + # Same number of crops as detections + assert len([f for f in crop_files if im_name in f.name]) == len(r.boxes.data) + + +@pytest.mark.skipif(not ONLINE, reason="environment is offline") +def test_data_utils(): + """Test utility functions in ultralytics/data/utils.py.""" + from ultralytics.data.utils import HUBDatasetStats, autosplit + from ultralytics.utils.downloads import zip_directory + + # from ultralytics.utils.files import WorkingDirectory + # with WorkingDirectory(ROOT.parent / 'tests'): + + for task in "detect", "segment", "pose", "classify": + file = Path(TASK2DATA[task]).with_suffix(".zip") # i.e. coco8.zip + download(f"https://github.com/ultralytics/hub/raw/main/example_datasets/{file}", unzip=False, dir=TMP) + stats = HUBDatasetStats(TMP / file, task=task) + stats.get_json(save=True) + stats.process_images() + + autosplit(TMP / "coco8") + zip_directory(TMP / "coco8/images/val") # zip + + +@pytest.mark.skipif(not ONLINE, reason="environment is offline") +def test_data_converter(): + """Test dataset converters.""" + from ultralytics.data.converter import coco80_to_coco91_class, convert_coco + + file = "instances_val2017.json" + download(f"https://github.com/ultralytics/yolov5/releases/download/v1.0/{file}", dir=TMP) + convert_coco(labels_dir=TMP, save_dir=TMP / "yolo_labels", use_segments=True, use_keypoints=False, cls91to80=True) + coco80_to_coco91_class() + + +def test_data_annotator(): + """Test automatic data annotation.""" + from ultralytics.data.annotator import auto_annotate + + auto_annotate( + ASSETS, + det_model=WEIGHTS_DIR / "yolov8n.pt", + sam_model=WEIGHTS_DIR / "mobile_sam.pt", + output_dir=TMP / "auto_annotate_labels", + ) + + +def test_events(): + """Test event sending functionality.""" + from ultralytics.hub.utils import Events + + events = Events() + events.enabled = True + cfg = copy(DEFAULT_CFG) # does not require deepcopy + cfg.mode = "test" + events(cfg) + + +def test_cfg_init(): + """Test configuration initialization utilities.""" + from ultralytics.cfg import check_dict_alignment, copy_default_cfg, smart_value + + with contextlib.suppress(SyntaxError): + check_dict_alignment({"a": 1}, {"b": 2}) + copy_default_cfg() + (Path.cwd() / DEFAULT_CFG_PATH.name.replace(".yaml", "_copy.yaml")).unlink(missing_ok=False) + [smart_value(x) for x in ["none", "true", "false"]] + + +def test_utils_init(): + """Test initialization utilities.""" + from ultralytics.utils import get_git_branch, get_git_origin_url, get_ubuntu_version, is_github_action_running + + get_ubuntu_version() + is_github_action_running() + get_git_origin_url() + get_git_branch() + + +def test_utils_checks(): + """Test various utility checks.""" + checks.check_yolov5u_filename("yolov5n.pt") + checks.git_describe(ROOT) + checks.check_requirements() # check requirements.txt + checks.check_imgsz([600, 600], max_dim=1) + checks.check_imshow() + checks.check_version("ultralytics", "8.0.0") + checks.print_args() + # checks.check_imshow(warn=True) + + +def test_utils_benchmarks(): + """Test model benchmarking.""" + from ultralytics.utils.benchmarks import ProfileModels + + ProfileModels(["yolov8n.yaml"], imgsz=32, min_time=1, num_timed_runs=3, num_warmup_runs=1).profile() + + +def test_utils_torchutils(): + """Test Torch utility functions.""" + from ultralytics.nn.modules.conv import Conv + from ultralytics.utils.torch_utils import get_flops_with_torch_profiler, profile, time_sync + + x = torch.randn(1, 64, 20, 20) + m = Conv(64, 64, k=1, s=2) + + profile(x, [m], n=3) + get_flops_with_torch_profiler(m) + time_sync() + + +@pytest.mark.slow +@pytest.mark.skipif(not ONLINE, reason="environment is offline") +def test_utils_downloads(): + """Test file download utilities.""" + from ultralytics.utils.downloads import get_google_drive_file_info + + get_google_drive_file_info("https://drive.google.com/file/d/1cqT-cJgANNrhIHCrEufUYhQ4RqiWG_lJ/view?usp=drive_link") + + +def test_utils_ops(): + """Test various operations utilities.""" + from ultralytics.utils.ops import ( + ltwh2xywh, + ltwh2xyxy, + make_divisible, + xywh2ltwh, + xywh2xyxy, + xywhn2xyxy, + xywhr2xyxyxyxy, + xyxy2ltwh, + xyxy2xywh, + xyxy2xywhn, + xyxyxyxy2xywhr, + ) + + make_divisible(17, torch.tensor([8])) + + boxes = torch.rand(10, 4) # xywh + torch.allclose(boxes, xyxy2xywh(xywh2xyxy(boxes))) + torch.allclose(boxes, xyxy2xywhn(xywhn2xyxy(boxes))) + torch.allclose(boxes, ltwh2xywh(xywh2ltwh(boxes))) + torch.allclose(boxes, xyxy2ltwh(ltwh2xyxy(boxes))) + + boxes = torch.rand(10, 5) # xywhr for OBB + boxes[:, 4] = torch.randn(10) * 30 + torch.allclose(boxes, xyxyxyxy2xywhr(xywhr2xyxyxyxy(boxes)), rtol=1e-3) + + +def test_utils_files(): + """Test file handling utilities.""" + from ultralytics.utils.files import file_age, file_date, get_latest_run, spaces_in_path + + file_age(SOURCE) + file_date(SOURCE) + get_latest_run(ROOT / "runs") + + path = TMP / "path/with spaces" + path.mkdir(parents=True, exist_ok=True) + with spaces_in_path(path) as new_path: + print(new_path) + + +@pytest.mark.slow +def test_utils_patches_torch_save(): + """Test torch_save backoff when _torch_save throws RuntimeError.""" + from unittest.mock import MagicMock, patch + + from ultralytics.utils.patches import torch_save + + mock = MagicMock(side_effect=RuntimeError) + + with patch("ultralytics.utils.patches._torch_save", new=mock): + with pytest.raises(RuntimeError): + torch_save(torch.zeros(1), TMP / "test.pt") + + assert mock.call_count == 4, "torch_save was not attempted the expected number of times" + + +def test_nn_modules_conv(): + """Test Convolutional Neural Network modules.""" + from ultralytics.nn.modules.conv import CBAM, Conv2, ConvTranspose, DWConvTranspose2d, Focus + + c1, c2 = 8, 16 # input and output channels + x = torch.zeros(4, c1, 10, 10) # BCHW + + # Run all modules not otherwise covered in tests + DWConvTranspose2d(c1, c2)(x) + ConvTranspose(c1, c2)(x) + Focus(c1, c2)(x) + CBAM(c1)(x) + + # Fuse ops + m = Conv2(c1, c2) + m.fuse_convs() + m(x) + + +def test_nn_modules_block(): + """Test Neural Network block modules.""" + from ultralytics.nn.modules.block import C1, C3TR, BottleneckCSP, C3Ghost, C3x + + c1, c2 = 8, 16 # input and output channels + x = torch.zeros(4, c1, 10, 10) # BCHW + + # Run all modules not otherwise covered in tests + C1(c1, c2)(x) + C3x(c1, c2)(x) + C3TR(c1, c2)(x) + C3Ghost(c1, c2)(x) + BottleneckCSP(c1, c2)(x) + + +@pytest.mark.skipif(not ONLINE, reason="environment is offline") +def test_hub(): + """Test Ultralytics HUB functionalities.""" + from ultralytics.hub import export_fmts_hub, logout + from ultralytics.hub.utils import smart_request + + export_fmts_hub() + logout() + smart_request("GET", "https://github.com", progress=True) + + +@pytest.fixture +def image(): + """Loads an image from a predefined source using OpenCV.""" + return cv2.imread(str(SOURCE)) + + +@pytest.mark.parametrize( + "auto_augment, erasing, force_color_jitter", + [ + (None, 0.0, False), + ("randaugment", 0.5, True), + ("augmix", 0.2, False), + ("autoaugment", 0.0, True), + ], +) +def test_classify_transforms_train(image, auto_augment, erasing, force_color_jitter): + """Tests classification transforms during training with various augmentation settings.""" + from ultralytics.data.augment import classify_augmentations + + transform = classify_augmentations( + size=224, + mean=(0.5, 0.5, 0.5), + std=(0.5, 0.5, 0.5), + scale=(0.08, 1.0), + ratio=(3.0 / 4.0, 4.0 / 3.0), + hflip=0.5, + vflip=0.5, + auto_augment=auto_augment, + hsv_h=0.015, + hsv_s=0.4, + hsv_v=0.4, + force_color_jitter=force_color_jitter, + erasing=erasing, + ) + + transformed_image = transform(Image.fromarray(cv2.cvtColor(image, cv2.COLOR_BGR2RGB))) + + assert transformed_image.shape == (3, 224, 224) + assert torch.is_tensor(transformed_image) + assert transformed_image.dtype == torch.float32 + + +@pytest.mark.slow +@pytest.mark.skipif(not ONLINE, reason="environment is offline") +def test_model_tune(): + """Tune YOLO model for performance.""" + YOLO("yolov8n-pose.pt").tune(data="coco8-pose.yaml", plots=False, imgsz=32, epochs=1, iterations=2, device="cpu") + YOLO("yolov8n-cls.pt").tune(data="imagenet10", plots=False, imgsz=32, epochs=1, iterations=2, device="cpu") + + +def test_model_embeddings(): + """Test YOLO model embeddings.""" + model_detect = YOLO(MODEL) + model_segment = YOLO(WEIGHTS_DIR / "yolov8n-seg.pt") + + for batch in [SOURCE], [SOURCE, SOURCE]: # test batch size 1 and 2 + assert len(model_detect.embed(source=batch, imgsz=32)) == len(batch) + assert len(model_segment.embed(source=batch, imgsz=32)) == len(batch) + + +@pytest.mark.skipif(checks.IS_PYTHON_3_12, reason="YOLOWorld with CLIP is not supported in Python 3.12") +def test_yolo_world(): + model = YOLO("yolov8s-world.pt") # no YOLOv8n-world model yet + model.set_classes(["tree", "window"]) + model(ASSETS / "bus.jpg", conf=0.01) + + # Training from yaml + model = YOLO("yolov8s-worldv2.yaml") # no YOLOv8n-world model yet + model.train(data="coco8.yaml", epochs=2, imgsz=32, cache="disk", batch=-1, close_mosaic=1, name="yolo-world") + + model = YOLO("yolov8s-worldv2.pt") # no YOLOv8n-world model yet + # val + model.val(data="coco8.yaml", imgsz=32, save_txt=True, save_json=True) + # Training from pretrain + model.train(data="coco8.yaml", epochs=2, imgsz=32, cache="disk", batch=-1, close_mosaic=1, name="yolo-world") + + # test WorWorldTrainerFromScratch + from ultralytics.models.yolo.world.train_world import WorldTrainerFromScratch + + model = YOLO("yolov8s-worldv2.yaml") # no YOLOv8n-world model yet + model.train( + data={"train": {"yolo_data": ["coco8.yaml"]}, "val": {"yolo_data": ["coco8.yaml"]}}, + epochs=2, + imgsz=32, + cache="disk", + batch=-1, + close_mosaic=1, + name="yolo-world", + trainer=WorldTrainerFromScratch, + ) diff --git a/ultralytics/__init__.py b/ultralytics/__init__.py new file mode 100644 index 0000000..ddb2cc2 --- /dev/null +++ b/ultralytics/__init__.py @@ -0,0 +1,27 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +__version__ = "8.1.48" + +from ultralytics.data.explorer.explorer import Explorer +from ultralytics.models import RTDETR, SAM, YOLO, YOLOWorld +from ultralytics.models.fastsam import FastSAM +from ultralytics.models.nas import NAS +from ultralytics.utils import ASSETS, SETTINGS +from ultralytics.utils.checks import check_yolo as checks +from ultralytics.utils.downloads import download + +settings = SETTINGS +__all__ = ( + "__version__", + "ASSETS", + "YOLO", + "YOLOWorld", + "NAS", + "SAM", + "FastSAM", + "RTDETR", + "checks", + "download", + "settings", + "Explorer", +) diff --git a/ultralytics/assets/bus.jpg b/ultralytics/assets/bus.jpg new file mode 100644 index 0000000000000000000000000000000000000000..40eaaf5c330d0c498fbe1dcacf9bb8bf566797fe GIT binary patch literal 137419 zcmb4K7~12mkvb%De3M;nkANAO1cF^atR43r9%*D9=6#rfQ4&Y8Ji-PbkO%z0XR`UxP`P*GO_pr8N%D9;z*=?6d&K#Ye^h>uH5NI*zR zLQF=@38bc^q!wg-LC+~AEF&!`EFmtZX09ctWTY%Eq2s1&WM%8*>?Et{_1@Fo-`v5; z?!O=?B&4L&6x94cAitf0go54w+n)LWB-rQ@XdpBc762*<3K|K@(-43b06;}U`ER@b zv*#r`1^^T5*{MSeKt(}C!+17yEKCe^0M_#gK!Q%nj6o(SughZN6`F!6RNUB4&Z?j{ zBW&xvNx`P5AC`J1V&_xRbWZs~DSTEGoHl@E@0;GtzV#fD<~h}W_P=D$_veu47|$+F zlIO>$sHi9y|M}7Wdj$oR1dW+gP#&F(MM&31ft*#?EA(jvfdA}#_K*Nx0cPTVL`cvk z$gy@A_-$)Z?AC4TNaFd^8j;K-6?jS+`P7C{o&1??FWlDEUjq{?Mp_doIKwSg{lWH@ z3hO{H85ArI{EQm-x31Zz@!9}&FhawKWZ+-{S9y#*#4G~F!>j4gKAV*V*P-K-Z*DlW zQ*o0Um@M-*kdMu!U9`-__+ZxN5*%A`*%29XDKgXCk8b4bq7fh>cUh5;#2@sw+gYBy zY<{-50<^0+HrscoV~7Rq;{I5&^_X7dqxHdRUkL~Q{q=$(>MoLsd)1Fz#bo{fw*Aj^ zbb31OIeo~UTFtH|lh$}qmmXJ}X#2HpOh#A~idF9HQpV=U)<|A{21s+U7+Ig{ymh|E zZ|m=(;lJ3VX2yW-Rn{VyN#I)M335{!Q_;tx8`PtA4&v4unmGuS8~5EDx%{@$nlP2x z)Qc7JBW6v2DKJ6M(GXPB&Y?AXcHZsog6??``IT8u`G~MEy&`OA*`R(XH2t%nb|Wwo zYoPs=i{I?!^hBDIyzp=5*roz%`j3<%98RS!-B91&16f2fNBfW$IWMKV-E2id*NC|N zM5lv`Fq1gG#4UuI$8|qm`A_mI&V{6m0CncZqc9#n4taw{l-GcnQlfRLZgCrU7c{9^ z%+b%xJ5#9Qp>NI%_-FLpU|9hX=r21py&C5j_C0~uo`(V3(vqY)lL{lO%QaBrF(WWd zTcnQWn428^KxmKasIkP+WTw8~qkiCTx$J;-6k9XX?tp=8CZv>ad{}8&iA&%hA^9^q z{5^a0n{NYD=cv)UQuIU$T>3a?Q9LoSbcD2h-j5l}J2~>-yUflEDX$H?(i8-^{<#xz z18s-)M8+qk?ll#9XjF_;Rj?ASKY%^z`fY7hPm>A6xx{6tqEX5*tnI}RgXa27Q;q<- z&X2sx`@bZ|4?@4p&xXEU$`jaLGtxJ;SUV}aaMVl1kH;)M043{|RDDVCSgbFQoEF3q z6gw?;KEcwM9DVJx{1sQ7&>q^zK9qpH7mQ4gS^cGB#7!t?oP^A;PX?4~z@_886!lPH zTaxQ#S#B0C-=ve0J!oS0aO^4z#EHm@>9dUieEi4?b|DRNmajpszM=ud*>+*1n9-g)Kb@X2Jg9?pW4{&*_^gxgN9 z;FsEm8DqTc4m8$#Td+ZxSI+aMlyfsknPDkjy{X9(>HK#eR(+?u!-@su;s_KLtpg6G zblY(_*F?u}UYX)th(sFlc(2}7YAg<4wf0Olphx=nROCP+k;(aQG>Vq9&HwDkB7%tz zegvR~gbhfV?V6jJm=)BH3N{QTPGv46?Hj3-z(za}zp4Itp5L2PA1q2$!9*94Wk@hv zt`-Y8!Jy19K@l&D2?b79xZhY!^3$_H)`zs2%=JWAtSeNy#`sR7Iex|eU7xKMz2i{A z9NmnHhUrFLRB=5SiS-PiWRtgQ+j72Ou?e1TVub06#rMr0@lX~t&W*gVUmn~_q(%8e zy16sKl3Gtg5TyQ7v~n~q>@ABVinXYIDG@821ADh2Pr}>0&)<0d8@li|+lEqV(D>cJ z{Wsl|R^Ub9Hu&ey`Qs9FAF29IcoF-p-aNnd5gY`-rlN!&@7cavW)>e z29B{o4~CR(f!GRqLa~lN59xpJg0wPTeRnVU?32B(*DVOP{8vFpP6vwuo-f*`R2EQe ziDIo?RLP!KOOU9Kpn9faY?n)=B);&}BUWQsNdn3n0piP6y=#O6N=Is}9p6*e(8l>t zIC}URPAjfaEQmEwkmD#fRuEFcEG;;P5eQFsyDk_vMOS~Sv&gHeI#G0CG{SRJexRbW zG6GAWegC!Y=tx2}IaG}Wx%-+&0;>5j=(4L5SnNu4a$n_b#Wfe%R+&CzNiuY32QC={l4jW?Fp$?x)AR)vgBv+7|LY8soXWjBI^y%e__>$ z^C&jYAT2E2)9jjdc12v#k@6f?zVf^cb*$`Sj$|07C>2LfJbV~mRsRhz7JFj00!gtT zjoE_Blw)KGoKwc8@(zSmhanDJIh~_`Vg3o4qd`Q3sO#vlpx7|nNW@8?W)iGe@6h%| zfUh;}rN{!6je<%TLZ~8z?N1T6Jv70GR5s&lqBZ6%hasIt6$s+k=*> z+S8aN@XnJ3=&cE}tPlCRDRU~t^Z4+eHQvsR14)uB4+QDkjsNN8IN;dG7VN_=$ki^Y zj)&|Yb{ensZ7q0wf#)K7yG;%$XjZUprpZsKXyI=1`d+)5su+A8`%37aZKq&5Mbh4> z09gtnvc@ZSu7nkqosTb2Le42geOV@V$T3&>Tr~+db)&J#UEC4yTwC>{BQ-q5mv}DD zJ4V+6w+mcXDqK|Sp{G+y&W}>De{I|Xsu4FSdS*;bVK1X_dkjR*InbgL)KYPp2)*L> z0;BfT2pbU@!~OqEcvRs5@0pE)_7ZRq*~W26e14XJe3V{x=<&f^&HN*Xo!s{-@3^uD zYVP{LqfBk(wlcp|igTKjpMcQR;#F{U3xaaD^V)Aq5S0>58tcCoAlwoVGgxR_Uk**^1 z_ZK_Is5}E#Jkri23$)VXQ)LGR?Q=P2e*jEL#AfB8l~&weq{MAe7#2gu2RZS{3oD~0 z7wh$*v46gZIQl6RuFVX60ezMI@v%a?1B4x$?t;fJd@jZ$k;alsH$$%7=ZPw z9jx-#zDSZiv2@!vxZIvXsuvX6WKoZZNFR~BQr6NVL#2<Tgt&XjkyB#t8jFARvx{^v-Sr_rbydL z!?$$eIkJsn)2?rME7%y(tu#~JN3S$~pUqtR_x+%*a(AB|lK6+P#H^OLOByx~Qy9VS zB_KL9JS+fjSc)#f=%5J>Ixb|(eiOMvw1mFf8hLsMuPg4Uoja!Ae0rWABG2ksAFBVM zST<8tHo5bUVq1Y}#sJAxP$7Ta zUfz3sxkrTL!_e)5TK@{q$GI2tBtEw9XQ-z+9beE)Wi?{WMHQ$BiKP+CflwUT3gsZ0 z#-ES&SWIk_-^{R{QnV~qU*kr^-x>E5Ez!%ji}>5TFQ#G@sTPqIC4T}mZSJJ;QBl{? z(Z4W{2!s&gkzq5Hl712td|OL|ihWkYekj#=Ab`^{KXtyvTA-%_c$3M8b;?hq@$Pcu zlrTHqom7oA1^nC4gq*C;7#a*3S-O)HG*-D&n#;rpmFL2BRqr@(`Py(Mc(hj;14z|e zo4_B~iTjbgtv7betw&HCnoqFKN68lIiWHZ|NH8B)y{H$CTb8hDvms@YOBVF<_Q)Ka z%PKIBmya5@O?jK&Ze53~Qb&i9PPQyQ`@sDzlWY@dbqHAj|E)ECn>b_6<6kj|Z|;i1 z6W7_mKCs9kdSBz}Id6>QnbWFXx_HpA;x90%{-OAWykPgE9|nE4ha{!=xEA80m9PH- zeQqxj&+=#0BHSu(jX|`9WK&nq*<(Wv(cK=t#jC=9BSV0i0#}>&tfQEQ^f|jrD-$n< zc4M>QrqmP5fKU-C2qyp7&r&Sh5uWUQyI5L?fi>)++%(+@jYC=kVh=Y6*sE$^Pv!t1 z^A}CSrbw(tZZ@BEAm16gA=Svicw29BXbAIy>GKyRgP8#3=4hUgf4_i#|>=^8BH}sK$p+(~QJ z5dV>1TCQ}}BDfm^Es1Dj;sjbLQ@f|T5P}PET!X&0vfYP+z=@(?hrl`#U)mDzctz@6Z>LknVR3J%deSkfj!)p6u`tR;JuHn3D&)Oi z)lU(aCV*Z9R*JtJPXBUGOK+$te)Js0?yPE433Aehn-U>8k+S1ve%`b?be^n@*_r!` zKJu*OYdx8Ih9-vTYce+1UXrsa(yH0p`vYvRfrb7b<_EwBW$0HCXGAp(3i6Xw+*?<| zTt;L(1;ggVN6D92wOi0cyN# zHcx;A`Lb3@Od18D&ug}-#k26R+5k32TnJMyF04PxX7f$X;@h%h&FwaLuLfB-4wtcm zKXMf{3UE0)(#?LXHvb-|Z(Yom++qCqVmfxwj@qU%Is}%e^B!|Nh(OT}AK%cwJaKiL zt_RV4rH=XKFfP#?VxLkH|4X*(z~$|D91VGR!@-&>#1!g@EMTW4VzX(Ka1i>)Qe*cq zh=A<~rV7E?)fB<^NfPk8o}Xz|LHY%<68o_k-yE8_ND`m?q5a!kGi@hkA0|EtE~eti z!kS)h_)H}7ju*XHQowwJd-07QTsSECWRhnnWqKj{yS->QT`LtG7jC~pgP=?=iqx%s zp$f~7Pw|ORFS7&TWgmqm)Ys$j!MwGB@2AlnG|>n%MIkSy2+m3T%}i;q^)nA1_B>28 zKsB^`ge{;pGXmqkKcyDFs2K5t-w!NoIO-AVkM`7nCae80e|LEmCkb_caOg*McMTbd zSO~`qMY0!(BjPX(zYX~oakskmyZdkO16_rFIT*FricMmRPdp}Iz7wBRzXqC7u!Xtu z4lMR+WU|2{(q4{SNTty?g~&`x%&~wo&T3f6Y!@3(W*5}dzEqK;(lWP=r{vBJgkV@J zq}_Eu>DTizs#@}ndS^}+nMg+!v`GvFma>1Z9D*cSq=mhv({j7c3PRa$TDBJ3E7(Fq zsFP{%P*?eFMk?dcY{X5hHfIX48L;KR z#s(WO)eviCOxu=blyrp%72{JoG>Xkx;R?-q*pHD{A-+nBR0|`?GuU#?c3x-F5m_aM zB?0-`DYyLry`dtFLaL}EKgCyY_<}j9CeD$GK6yAHUPB%_pD|&U%QJUL_peMFLv7)} zn$E1$LFTq+cE{?!`>Ipc4~j&AjH@zyOuXE(b;CW0iy)l*tfA4?|Quz6U3ter2lbOPtDxI`e52@QBp^RY2`9_ zH6oEZBgu9JHin1Li&nb6NW{LX9;%LQ&uXe?&WbRJ;ca1N&F6gr=q+gGjvl?#T~u(& zi#|bkwk~QiMp9luv0tqYUzpBI-$Qx9L{4X8I69;xl?>dbPBC?UuuYBOR&!y|(0ON< zmUyqnibs}`lyLu@>n4WYIm6CZp-Kpp}oq>|W z>|OK&_0n%SF?EE|(sI9?N5a-P)n1JHsf$BVJ|c+a_VslGVpFEVJN=D}yeUNJ^`T(! zfhIbHs4MU=bbb-IDbHa_DzdFQe#rwhzymFAR{9yN{9~AM?@3Ec@J$cCG1v6t;8Y;X+t4YC?u>TbXr-Qbsy7wWVTr0rVJM z1XW@GwgQLuIMeeE^&;^uvHIr2?Iz#r#4?*0iN=}JLx>`1f0XZu?C=_pBAaGA=AtFl zUV-q??yDnAOGbW0he&=FRG_sGJu70?mjnLX&|rduA?B}jO^d*ZXahyzy2=(hypc8A zN}^S*rBm(u%F3Z77<~=4Sg+?T%Yd*%-W4V3OG??21k+WFB&!ck01(M=mz%z!X|8Y( z(=H9;aQZFK_H{82kE~^`o^~gvD@r@S-^DDaBFhIg3!M?|b&d}J1KwAdp?g6xbWID4 z;_G)kr9srwn*H=Jy@=UDFnv#_6>Dpxm{rOYGxK)=&$?`~N^dFmZog*Kz14jk50V?7 zB9b_A+a0Oftp0@mnv(s%&Cb9J+hjtTQ5u!KrXz0`NLVX7TmMgbI>YKCDK#J(78u@)CECL?$kpF-C~F?4G|QBBOa>Ca@3k zdIFHH27>alrS(wXVH{r<2R;E%>Ib?rqUS%Rletedja00x#vv$oCwGW1=`sf!iiV90-zRYdHMtmjLPzggU*Uca`W%y_oG6L?cpx9F2$>&ekMe&J zr?{g3J^K;djPA6?p%oc2Ax%YEswDN525m6{kSsW9-0*5`1<^9whhMb%i;dVtjZV_h zz`_^#NWm)e~CL;LJ2TWff_dE zRjDFSlblvff2xF7S=x3@a{H$57wguC!n-SDW3KGjxVa;70+{h8a)5=K#-5W%2P)3d zH6|}ay=CQRt|ixHV}VI`KsT^vw*ocPkh5Mj&6aVvRqdi)Q2R}cua*RJhS$>#%n)=!S4(aGEzOY7d(yi-CaO_lM>B=)Bl4@IfD5#Y-Hjw$uXOV(fj>vGx z4?i>%vvbT8;b=*rcmm{B*?^w_n{H)w>f-rn>)hd`3MQ#C5fLsg#aHoMZZZ)>WF|{x zhRf}~ta4|@!7)&UUyY`IMx%MwpN9;RT_h$e@%v){DNsKcm+ORw=|*O~`pHc!JS>{K z8H>ORYLFu{v&F5TjT_4fSB4S8ZQhEDH;~JP_^k;(Z9Fj%9sUVWVQ1h_@cJOQH2 zwja{?waKXy)8)TZV{{ssd$M#BvJ!j{74MB;-;SVDqO_L4_*?#ZpCja)f~Rx6{m(i1 zi`r3rlX&X_W#fT>`fW8VxamM>%KgWT>b+*{4p|Cq+A`#+=m!!g@mKiCxBYg^~PhVnZ!q4wbje-!y}E`8bu8aVzAb9|I@1xsXZ(Z z2Ft3l&%}>1&nh}-(?wk^ETmLdfxn!XA{V!!$VCqX(p1)zFQFMvm8&dd04JXKRZ}9% zY&nd{{QohLcuO3X8zY6t_$Fk8zmjDPKGDR+g>h)>iM#a@@DQ+sslPp`$58osp{B&tW#yP|Gs{lc9<(C z9ZNXrEIh!GGD3rdt=1&r>1gbgBqgAT4!|6~ppATr19D$spoq{xqfkB^Fui0cQi{c0 z|H8XHmjL^*#x&2_TCgBT;WjPalhs%Tf}ehAJ0q>!G*Y|!^3DKipz860u{pWTCnQ+I zThQh$Kzz5m{?OoB?d34N*o)=<4*c-qaus?o=P{RzOJ4?kng^PW>Bufc_I?0VGuJ2D z9M!z$arg8LMzY)Cf>+O-R+-@`X-wf{g%1uf)Jx=O2d^%qfXhGs zk8-N0p5&T*w|Cdq;z)(kKg*+orh?42{4`j_EPs{p8*3vNrL4~CJ`<8h_F12k2CbBe zi*ecgQm)Z6ZW}~k+*)aXJwX(p3L%f>LnD_8Lk{cKQxUCu5#0W$g1^_uz%Se+IE`b2 zIoA5WJ%gZg6Xa9gBO`(y{$7}QbT1@iTYsD8fagXl7|F<124p10l;K;TRa%}Y_v@ik z5`fwhz>;ErJG9ve6w$?htG7F-Fhh|>$eSm?@-uw<{@_Mm*UV|tx}O_+ZMkqcu22k) zZe!;L71<;RJmpF3hQs($yMH|7VoD{QF&!s$Bft0EOg%Z^sVzbW2Tk_-xlNTGAyK z^svd$n8x35zim5?l2n$C%7TB*4q|gnVXNdp{+}b>^GMJ(7#kZCN^@%kHM5087m=Xy zs0Ek9O=j>?u_^273<$MsQBw&s$<-3&$1$R$kt_u~JkKFGqR|pKj&=Z=3GLnpLtkp7 z`U{kN7kFNa9EB~9nb6yYy{~v4I9q=1meRbhJLTx9ou&#(uu3+{nO*xeLl?CW1|H5+ zOX)9{G2gvd6r^NI_D{k+!W9_ai~(Xu{ab-q?AZQ+s4vt4ddKTFZB%lFGz5N?9x7dR zlcxnmQRg*${UXM;4+Spdd}gQ52i*005{!02S-{3ye&$LIrKrVnQ`A2q+V5S$8KZp% zzhs-4AEB8nDqz}-H=898WK=8;#Su>G7;`z2+G0LI2*iq{j7!$B&3Ve@|;>JsF2Ug;Pkw zS6?=eb+7w_V_U-O>O{$vbG9VR=^Rl_bR!KmGyI9=c9F@mYK;!D0P}Y4+213#1TGh4 zb5eZTJ!VY;*4T8S=O?vaoszHYbBwt74iesSL?mTdK);HcnK;`=TcmMz*GcGocgf%{ z-Zm=oY*(avpQH0O?uYyc@;5jqQ++MNKo0QM-|x?^X%^(Dbw|1;;&iI>YW|t6ni`oG z+D+=l?N^o)s38}KKY*tp7}T3^EZUV0Ul=a`z&Zs}Y*EZ?ct{C{2AZt|BM5;CXlv}FN)pw?&)^;kNh_QwY+n)gT6LUix-72FYH6EDG%`9<;2Hs+4tf)ka zmIdv}qIOzQ>vrSFxTV4~> z2p$T)t#Kk6?&4;&4!(@;jd=nbh{B_!+9HhSFG~|`1;5v2GJ-1siz7G$(wQ$sBWr?3h$7zB zjLpxRK} zQrcf`%*MZRAr(JM1&z>Bx2HL%n7u{3I)vLRbsQHr!s+mB`REirXV<+|RX1h$h@gqy zAqs^Vc6+fjOs;jF{%r2xF8pY*)2U!SzwdDQ1+Ap&(Ab8 zjPvn(>32EG!B@;YZGsCFoh#Z2FwmLCiowLCrHsh--LOMd{yzFP&rheNvynDW+?{p&LeI>S;`b_juDt_kJa8w%h#(Ce|BT)`|McvA7eCL69j+c1%(EX#xA+|JJliYcb-H zb}6Tkm!(efv7v8pv1SFcnvDC+=}M@3u|hTlg54&=^b5!gRCF{$rG7-$8|1<2S({MY zn(-%<*UFM%_tL>u5g%$tI=ubNhO7@?j})g7WcW!&5JL-GjDNLKnU;eoLeEt= zxwd~=pu?8WENbf)PNiyuGn#Z!y0xK*-xMq5qI{8zvN@^h0|QCekcqE(Yg@>+`|X8? zWuDW^GQs9XHol7AN%9t`$)SbI-)TL|zy52gl|t8=Bdn-xQft5>X|+@$;MSm=$Wf%1 zm|x$1y^ky_RT;Lt>6kauKqXhml$Z&ZGn$QtDu`B5$OA*Tt0_YYmo>47dG#KTt0i94 zYedh}glTm7s@hInmowahY_@X}eD&_GDb!(aV!V&e| zXQ`T!N!*u?3Twr<07HKHW@tf=Y2&0kTT)xzT{z79SC zaBgzv2faLSReqP_dp-6%qV4KLHCrT7jf&synztgnCw|mYOU>s^$ASjRbaAbKFRH+O zk~2D(9SCBnd5j_4M8CzlBF7wO0+Jb*4`Ck+Q;3Q;_l>{!XXFAzd#!*gkb$fC6cHe) zP$5O_^C3SvNwZP@wfjW`a+Pa2J&weKL@`4fEg1LYmpLx_c2p-sUF&>PDK67n`@(n|SojWrvS{i!-PelG?xOc*BYk~-#U<}8 zy5$f<$>$KWt zOo?eysa)ofwRwV(1%>s|a3aCi^WK}P?1+fyJoc9)sc*{EJnY~eG_7uPcB0>EvT1>n zNz{vXGu@V-ery|(QAO=IetH6A8`g=6wU#aEh8qk`Tnm!C^1-jjea+jf2Ek!5j0gf4CXOT{H?1aVRL z_!lMzDnR1-bGKXIC1q7Z6Sf(Aqzk1ECC!2;BWYmX{w?o@g=SsIQj8yP^$&WGDzcb^ zpoXN99$N$=icIapw3S-;Q&noJiDSU#H$B^oDfW9>FZU+&P&t3M@j31X*ICOOKOL|i z@-Mr{_!~n)%vhq?(2%rsHo|a?`8IKN?K?bR9H(Si-bPM#_Cm zzfpXrrv^GYBMcin)+rGd73seRHU$A5BxV(!w7=^|s$Vw>Ty-gziX&#mu0@BTwdz4U z0hb~wOf?Q@z1Mkhpfm?> zNh)dA7Bo;2*){j3Ag|f0CO*u?^R9j7WI5jwxkvDUU+TNTP)&(yOrrTln8A3EGWGBl zOG;@L2J<+dsTjU&Mtm=Oy(f(aBvK*=?8c9_xs1VE_>{|blRHTH%0G4_ds6f z*)NG5`94u9+GJ%fRt7=V@}%^0>2<;?`oD#;*5%T_U&I&bbrfE*-ySvdtDbZ7U!dfA z8T2ii_K)~>Kx|vo@aA?bOLhvYIZsUBWS1+CtbvT8Jz9Mf5EPiI9+gce

Yf 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 literal 0 HcmV?d00001 diff --git a/ultralytics/assets/zidane.jpg b/ultralytics/assets/zidane.jpg new file mode 100644 index 0000000000000000000000000000000000000000..eeab1cdcb282b0e026a57c5bf85df36024b4e1f6 GIT binary patch literal 50427 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 List[str]: + """ + Merges arguments around isolated '=' args in a list of strings. The function considers cases where the first + argument ends with '=' or the second starts with '=', as well as when the middle one is an equals sign. + + Args: + args (List[str]): A list of strings where each element is an argument. + + Returns: + (List[str]): A list of strings where the arguments around isolated '=' are merged. + """ + new_args = [] + for i, arg in enumerate(args): + if arg == "=" and 0 < i < len(args) - 1: # merge ['arg', '=', 'val'] + new_args[-1] += f"={args[i + 1]}" + del args[i + 1] + elif arg.endswith("=") and i < len(args) - 1 and "=" not in args[i + 1]: # merge ['arg=', 'val'] + new_args.append(f"{arg}{args[i + 1]}") + del args[i + 1] + elif arg.startswith("=") and i > 0: # merge ['arg', '=val'] + new_args[-1] += arg + else: + new_args.append(arg) + return new_args + + +def handle_yolo_hub(args: List[str]) -> None: + """ + Handle Ultralytics HUB command-line interface (CLI) commands. + + This function processes Ultralytics HUB CLI commands such as login and logout. + It should be called when executing a script with arguments related to HUB authentication. + + Args: + args (List[str]): A list of command line arguments + + Example: + ```bash + python my_script.py hub login your_api_key + ``` + """ + from ultralytics import hub + + if args[0] == "login": + key = args[1] if len(args) > 1 else "" + # Log in to Ultralytics HUB using the provided API key + hub.login(key) + elif args[0] == "logout": + # Log out from Ultralytics HUB + hub.logout() + + +def handle_yolo_settings(args: List[str]) -> None: + """ + Handle YOLO settings command-line interface (CLI) commands. + + This function processes YOLO settings CLI commands such as reset. + It should be called when executing a script with arguments related to YOLO settings management. + + Args: + args (List[str]): A list of command line arguments for YOLO settings management. + + Example: + ```bash + python my_script.py yolo settings reset + ``` + """ + url = "https://docs.ultralytics.com/quickstart/#ultralytics-settings" # help URL + try: + if any(args): + if args[0] == "reset": + SETTINGS_YAML.unlink() # delete the settings file + SETTINGS.reset() # create new settings + LOGGER.info("Settings reset successfully") # inform the user that settings have been reset + else: # save a new setting + new = dict(parse_key_value_pair(a) for a in args) + check_dict_alignment(SETTINGS, new) + SETTINGS.update(new) + + LOGGER.info(f"💡 Learn about settings at {url}") + yaml_print(SETTINGS_YAML) # print the current settings + except Exception as e: + LOGGER.warning(f"WARNING ⚠️ settings error: '{e}'. Please see {url} for help.") + + +def handle_explorer(): + """Open the Ultralytics Explorer GUI.""" + checks.check_requirements("streamlit") + LOGGER.info("💡 Loading Explorer dashboard...") + subprocess.run(["streamlit", "run", ROOT / "data/explorer/gui/dash.py", "--server.maxMessageSize", "2048"]) + + +def parse_key_value_pair(pair): + """Parse one 'key=value' pair and return key and value.""" + k, v = pair.split("=", 1) # split on first '=' sign + k, v = k.strip(), v.strip() # remove spaces + assert v, f"missing '{k}' value" + return k, smart_value(v) + + +def smart_value(v): + """Convert a string to an underlying type such as int, float, bool, etc.""" + v_lower = v.lower() + if v_lower == "none": + return None + elif v_lower == "true": + return True + elif v_lower == "false": + return False + else: + with contextlib.suppress(Exception): + return eval(v) + return v + + +def entrypoint(debug=""): + """ + This function is the ultralytics package entrypoint, it's responsible for parsing the command line arguments passed + to the package. + + This function allows for: + - passing mandatory YOLO args as a list of strings + - specifying the task to be performed, either 'detect', 'segment' or 'classify' + - specifying the mode, either 'train', 'val', 'test', or 'predict' + - running special modes like 'checks' + - passing overrides to the package's configuration + + It uses the package's default cfg and initializes it using the passed overrides. + Then it calls the CLI function with the composed cfg + """ + args = (debug.split(" ") if debug else ARGV)[1:] + if not args: # no arguments passed + LOGGER.info(CLI_HELP_MSG) + return + + special = { + "help": lambda: LOGGER.info(CLI_HELP_MSG), + "checks": checks.collect_system_info, + "version": lambda: LOGGER.info(__version__), + "settings": lambda: handle_yolo_settings(args[1:]), + "cfg": lambda: yaml_print(DEFAULT_CFG_PATH), + "hub": lambda: handle_yolo_hub(args[1:]), + "login": lambda: handle_yolo_hub(args), + "copy-cfg": copy_default_cfg, + "explorer": lambda: handle_explorer(), + } + full_args_dict = {**DEFAULT_CFG_DICT, **{k: None for k in TASKS}, **{k: None for k in MODES}, **special} + + # Define common misuses of special commands, i.e. -h, -help, --help + special.update({k[0]: v for k, v in special.items()}) # singular + special.update({k[:-1]: v for k, v in special.items() if len(k) > 1 and k.endswith("s")}) # singular + special = {**special, **{f"-{k}": v for k, v in special.items()}, **{f"--{k}": v for k, v in special.items()}} + + overrides = {} # basic overrides, i.e. imgsz=320 + for a in merge_equals_args(args): # merge spaces around '=' sign + if a.startswith("--"): + LOGGER.warning(f"WARNING ⚠️ argument '{a}' does not require leading dashes '--', updating to '{a[2:]}'.") + a = a[2:] + if a.endswith(","): + LOGGER.warning(f"WARNING ⚠️ argument '{a}' does not require trailing comma ',', updating to '{a[:-1]}'.") + a = a[:-1] + if "=" in a: + try: + k, v = parse_key_value_pair(a) + if k == "cfg" and v is not None: # custom.yaml passed + LOGGER.info(f"Overriding {DEFAULT_CFG_PATH} with {v}") + overrides = {k: val for k, val in yaml_load(checks.check_yaml(v)).items() if k != "cfg"} + else: + overrides[k] = v + except (NameError, SyntaxError, ValueError, AssertionError) as e: + check_dict_alignment(full_args_dict, {a: ""}, e) + + elif a in TASKS: + overrides["task"] = a + elif a in MODES: + overrides["mode"] = a + elif a.lower() in special: + special[a.lower()]() + return + elif a in DEFAULT_CFG_DICT and isinstance(DEFAULT_CFG_DICT[a], bool): + overrides[a] = True # auto-True for default bool args, i.e. 'yolo show' sets show=True + elif a in DEFAULT_CFG_DICT: + raise SyntaxError( + f"'{colorstr('red', 'bold', a)}' is a valid YOLO argument but is missing an '=' sign " + f"to set its value, i.e. try '{a}={DEFAULT_CFG_DICT[a]}'\n{CLI_HELP_MSG}" + ) + else: + check_dict_alignment(full_args_dict, {a: ""}) + + # Check keys + check_dict_alignment(full_args_dict, overrides) + + # Mode + mode = overrides.get("mode") + if mode is None: + mode = DEFAULT_CFG.mode or "predict" + LOGGER.warning(f"WARNING ⚠️ 'mode' argument is missing. Valid modes are {MODES}. Using default 'mode={mode}'.") + elif mode not in MODES: + raise ValueError(f"Invalid 'mode={mode}'. Valid modes are {MODES}.\n{CLI_HELP_MSG}") + + # Task + task = overrides.pop("task", None) + if task: + if task not in TASKS: + raise ValueError(f"Invalid 'task={task}'. Valid tasks are {TASKS}.\n{CLI_HELP_MSG}") + if "model" not in overrides: + overrides["model"] = TASK2MODEL[task] + + # Model + model = overrides.pop("model", DEFAULT_CFG.model) + if model is None: + model = "yolov8n.pt" + LOGGER.warning(f"WARNING ⚠️ 'model' argument is missing. Using default 'model={model}'.") + overrides["model"] = model + stem = Path(model).stem.lower() + if "rtdetr" in stem: # guess architecture + from ultralytics import RTDETR + + model = RTDETR(model) # no task argument + elif "fastsam" in stem: + from ultralytics import FastSAM + + model = FastSAM(model) + elif "sam" in stem: + from ultralytics import SAM + + model = SAM(model) + else: + from ultralytics import YOLO + + model = YOLO(model, task=task) + if isinstance(overrides.get("pretrained"), str): + model.load(overrides["pretrained"]) + + # Task Update + if task != model.task: + if task: + LOGGER.warning( + f"WARNING ⚠️ conflicting 'task={task}' passed with 'task={model.task}' model. " + f"Ignoring 'task={task}' and updating to 'task={model.task}' to match model." + ) + task = model.task + + # Mode + if mode in {"predict", "track"} and "source" not in overrides: + overrides["source"] = DEFAULT_CFG.source or ASSETS + LOGGER.warning(f"WARNING ⚠️ 'source' argument is missing. Using default 'source={overrides['source']}'.") + elif mode in {"train", "val"}: + if "data" not in overrides and "resume" not in overrides: + overrides["data"] = DEFAULT_CFG.data or TASK2DATA.get(task or DEFAULT_CFG.task, DEFAULT_CFG.data) + LOGGER.warning(f"WARNING ⚠️ 'data' argument is missing. Using default 'data={overrides['data']}'.") + elif mode == "export": + if "format" not in overrides: + overrides["format"] = DEFAULT_CFG.format or "torchscript" + LOGGER.warning(f"WARNING ⚠️ 'format' argument is missing. Using default 'format={overrides['format']}'.") + + # Run command in python + getattr(model, mode)(**overrides) # default args from model + + # Show help + LOGGER.info(f"💡 Learn more at https://docs.ultralytics.com/modes/{mode}") + + +# Special modes -------------------------------------------------------------------------------------------------------- +def copy_default_cfg(): + """Copy and create a new default configuration file with '_copy' appended to its name.""" + new_file = Path.cwd() / DEFAULT_CFG_PATH.name.replace(".yaml", "_copy.yaml") + shutil.copy2(DEFAULT_CFG_PATH, new_file) + LOGGER.info( + f"{DEFAULT_CFG_PATH} copied to {new_file}\n" + f"Example YOLO command with this new custom cfg:\n yolo cfg='{new_file}' imgsz=320 batch=8" + ) + + +if __name__ == "__main__": + # Example: entrypoint(debug='yolo predict model=yolov8n.pt') + entrypoint(debug="") diff --git a/ultralytics/cfg/datasets/Argoverse.yaml b/ultralytics/cfg/datasets/Argoverse.yaml new file mode 100644 index 0000000..43755f7 --- /dev/null +++ b/ultralytics/cfg/datasets/Argoverse.yaml @@ -0,0 +1,74 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# Argoverse-HD dataset (ring-front-center camera) https://www.cs.cmu.edu/~mengtial/proj/streaming/ by Argo AI +# Documentation: https://docs.ultralytics.com/datasets/detect/argoverse/ +# Example usage: yolo train data=Argoverse.yaml +# parent +# ├── ultralytics +# └── datasets +# └── Argoverse ← downloads here (31.5 GB) + +# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..] +path: ../datasets/Argoverse # dataset root dir +train: Argoverse-1.1/images/train/ # train images (relative to 'path') 39384 images +val: Argoverse-1.1/images/val/ # val images (relative to 'path') 15062 images +test: Argoverse-1.1/images/test/ # test images (optional) https://eval.ai/web/challenges/challenge-page/800/overview + +# Classes +names: + 0: person + 1: bicycle + 2: car + 3: motorcycle + 4: bus + 5: truck + 6: traffic_light + 7: stop_sign + +# Download script/URL (optional) --------------------------------------------------------------------------------------- +download: | + import json + from tqdm import tqdm + from ultralytics.utils.downloads import download + from pathlib import Path + + def argoverse2yolo(set): + labels = {} + a = json.load(open(set, "rb")) + for annot in tqdm(a['annotations'], desc=f"Converting {set} to YOLOv5 format..."): + img_id = annot['image_id'] + img_name = a['images'][img_id]['name'] + img_label_name = f'{img_name[:-3]}txt' + + cls = annot['category_id'] # instance class id + x_center, y_center, width, height = annot['bbox'] + x_center = (x_center + width / 2) / 1920.0 # offset and scale + y_center = (y_center + height / 2) / 1200.0 # offset and scale + width /= 1920.0 # scale + height /= 1200.0 # scale + + img_dir = set.parents[2] / 'Argoverse-1.1' / 'labels' / a['seq_dirs'][a['images'][annot['image_id']]['sid']] + if not img_dir.exists(): + img_dir.mkdir(parents=True, exist_ok=True) + + k = str(img_dir / img_label_name) + if k not in labels: + labels[k] = [] + labels[k].append(f"{cls} {x_center} {y_center} {width} {height}\n") + + for k in labels: + with open(k, "w") as f: + f.writelines(labels[k]) + + + # Download 'https://argoverse-hd.s3.us-east-2.amazonaws.com/Argoverse-HD-Full.zip' (deprecated S3 link) + dir = Path(yaml['path']) # dataset root dir + urls = ['https://drive.google.com/file/d/1st9qW3BeIwQsnR0t8mRpvbsSWIo16ACi/view?usp=drive_link'] + print("\n\nWARNING: Argoverse dataset MUST be downloaded manually, autodownload will NOT work.") + print(f"WARNING: Manually download Argoverse dataset '{urls[0]}' to '{dir}' and re-run your command.\n\n") + # download(urls, dir=dir) + + # Convert + annotations_dir = 'Argoverse-HD/annotations/' + (dir / 'Argoverse-1.1' / 'tracking').rename(dir / 'Argoverse-1.1' / 'images') # rename 'tracking' to 'images' + for d in "train.json", "val.json": + argoverse2yolo(dir / annotations_dir / d) # convert Argoverse annotations to YOLO labels diff --git a/ultralytics/cfg/datasets/DOTAv1.5.yaml b/ultralytics/cfg/datasets/DOTAv1.5.yaml new file mode 100644 index 0000000..701535f --- /dev/null +++ b/ultralytics/cfg/datasets/DOTAv1.5.yaml @@ -0,0 +1,36 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# DOTA 1.5 dataset https://captain-whu.github.io/DOTA/index.html for object detection in aerial images by Wuhan University +# Documentation: https://docs.ultralytics.com/datasets/obb/dota-v2/ +# Example usage: yolo train model=yolov8n-obb.pt data=DOTAv1.5.yaml +# parent +# ├── ultralytics +# └── datasets +# └── dota1.5 ← downloads here (2GB) + +# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..] +path: ../datasets/DOTAv1.5 # dataset root dir +train: images/train # train images (relative to 'path') 1411 images +val: images/val # val images (relative to 'path') 458 images +test: images/test # test images (optional) 937 images + +# Classes for DOTA 1.5 +names: + 0: plane + 1: ship + 2: storage tank + 3: baseball diamond + 4: tennis court + 5: basketball court + 6: ground track field + 7: harbor + 8: bridge + 9: large vehicle + 10: small vehicle + 11: helicopter + 12: roundabout + 13: soccer ball field + 14: swimming pool + 15: container crane + +# Download script/URL (optional) +download: https://github.com/ultralytics/yolov5/releases/download/v1.0/DOTAv1.5.zip diff --git a/ultralytics/cfg/datasets/DOTAv1.yaml b/ultralytics/cfg/datasets/DOTAv1.yaml new file mode 100644 index 0000000..f6364d3 --- /dev/null +++ b/ultralytics/cfg/datasets/DOTAv1.yaml @@ -0,0 +1,35 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# DOTA 1.0 dataset https://captain-whu.github.io/DOTA/index.html for object detection in aerial images by Wuhan University +# Documentation: https://docs.ultralytics.com/datasets/obb/dota-v2/ +# Example usage: yolo train model=yolov8n-obb.pt data=DOTAv1.yaml +# parent +# ├── ultralytics +# └── datasets +# └── dota1 ← downloads here (2GB) + +# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..] +path: ../datasets/DOTAv1 # dataset root dir +train: images/train # train images (relative to 'path') 1411 images +val: images/val # val images (relative to 'path') 458 images +test: images/test # test images (optional) 937 images + +# Classes for DOTA 1.0 +names: + 0: plane + 1: ship + 2: storage tank + 3: baseball diamond + 4: tennis court + 5: basketball court + 6: ground track field + 7: harbor + 8: bridge + 9: large vehicle + 10: small vehicle + 11: helicopter + 12: roundabout + 13: soccer ball field + 14: swimming pool + +# Download script/URL (optional) +download: https://github.com/ultralytics/yolov5/releases/download/v1.0/DOTAv1.zip diff --git a/ultralytics/cfg/datasets/GlobalWheat2020.yaml b/ultralytics/cfg/datasets/GlobalWheat2020.yaml new file mode 100644 index 0000000..ae6bfa0 --- /dev/null +++ b/ultralytics/cfg/datasets/GlobalWheat2020.yaml @@ -0,0 +1,53 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# Global Wheat 2020 dataset https://www.global-wheat.com/ by University of Saskatchewan +# Documentation: https://docs.ultralytics.com/datasets/detect/globalwheat2020/ +# Example usage: yolo train data=GlobalWheat2020.yaml +# parent +# ├── ultralytics +# └── datasets +# └── GlobalWheat2020 ← downloads here (7.0 GB) + +# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..] +path: ../datasets/GlobalWheat2020 # dataset root dir +train: # train images (relative to 'path') 3422 images + - images/arvalis_1 + - images/arvalis_2 + - images/arvalis_3 + - images/ethz_1 + - images/rres_1 + - images/inrae_1 + - images/usask_1 +val: # val images (relative to 'path') 748 images (WARNING: train set contains ethz_1) + - images/ethz_1 +test: # test images (optional) 1276 images + - images/utokyo_1 + - images/utokyo_2 + - images/nau_1 + - images/uq_1 + +# Classes +names: + 0: wheat_head + +# Download script/URL (optional) --------------------------------------------------------------------------------------- +download: | + from ultralytics.utils.downloads import download + from pathlib import Path + + # Download + dir = Path(yaml['path']) # dataset root dir + urls = ['https://zenodo.org/record/4298502/files/global-wheat-codalab-official.zip', + 'https://github.com/ultralytics/yolov5/releases/download/v1.0/GlobalWheat2020_labels.zip'] + download(urls, dir=dir) + + # Make Directories + for p in 'annotations', 'images', 'labels': + (dir / p).mkdir(parents=True, exist_ok=True) + + # Move + for p in 'arvalis_1', 'arvalis_2', 'arvalis_3', 'ethz_1', 'rres_1', 'inrae_1', 'usask_1', \ + 'utokyo_1', 'utokyo_2', 'nau_1', 'uq_1': + (dir / 'global-wheat-codalab-official' / p).rename(dir / 'images' / p) # move to /images + f = (dir / 'global-wheat-codalab-official' / p).with_suffix('.json') # json file + if f.exists(): + f.rename((dir / 'annotations' / p).with_suffix('.json')) # move to /annotations diff --git a/ultralytics/cfg/datasets/ImageNet.yaml b/ultralytics/cfg/datasets/ImageNet.yaml new file mode 100644 index 0000000..0dc344a --- /dev/null +++ b/ultralytics/cfg/datasets/ImageNet.yaml @@ -0,0 +1,2024 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# ImageNet-1k dataset https://www.image-net.org/index.php by Stanford University +# Simplified class names from https://github.com/anishathalye/imagenet-simple-labels +# Documentation: https://docs.ultralytics.com/datasets/classify/imagenet/ +# Example usage: yolo train task=classify data=imagenet +# parent +# ├── ultralytics +# └── datasets +# └── imagenet ← downloads here (144 GB) + +# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..] +path: ../datasets/imagenet # dataset root dir +train: train # train images (relative to 'path') 1281167 images +val: val # val images (relative to 'path') 50000 images +test: # test images (optional) + +# Classes +names: + 0: tench + 1: goldfish + 2: great white shark + 3: tiger shark + 4: hammerhead shark + 5: electric ray + 6: stingray + 7: cock + 8: hen + 9: ostrich + 10: brambling + 11: goldfinch + 12: house finch + 13: junco + 14: indigo bunting + 15: American robin + 16: bulbul + 17: jay + 18: magpie + 19: chickadee + 20: American dipper + 21: kite + 22: bald eagle + 23: vulture + 24: great grey owl + 25: fire salamander + 26: smooth newt + 27: newt + 28: spotted salamander + 29: axolotl + 30: American bullfrog + 31: tree frog + 32: tailed frog + 33: loggerhead sea turtle + 34: leatherback sea turtle + 35: mud turtle + 36: terrapin + 37: box turtle + 38: banded gecko + 39: green iguana + 40: Carolina anole + 41: desert grassland whiptail lizard + 42: agama + 43: frilled-necked lizard + 44: alligator lizard + 45: Gila monster + 46: European green lizard + 47: chameleon + 48: Komodo dragon + 49: Nile crocodile + 50: American alligator + 51: triceratops + 52: worm snake + 53: ring-necked snake + 54: eastern hog-nosed snake + 55: smooth green snake + 56: kingsnake + 57: garter snake + 58: water snake + 59: vine snake + 60: night snake + 61: boa constrictor + 62: African rock python + 63: Indian cobra + 64: green mamba + 65: sea snake + 66: Saharan horned viper + 67: eastern diamondback rattlesnake + 68: sidewinder + 69: trilobite + 70: harvestman + 71: scorpion + 72: yellow garden spider + 73: barn spider + 74: European garden spider + 75: southern black widow + 76: tarantula + 77: wolf spider + 78: tick + 79: centipede + 80: black grouse + 81: ptarmigan + 82: ruffed grouse + 83: prairie grouse + 84: peacock + 85: quail + 86: partridge + 87: grey parrot + 88: macaw + 89: sulphur-crested cockatoo + 90: lorikeet + 91: coucal + 92: bee eater + 93: hornbill + 94: hummingbird + 95: jacamar + 96: toucan + 97: duck + 98: red-breasted merganser + 99: goose + 100: black swan + 101: tusker + 102: echidna + 103: platypus + 104: wallaby + 105: koala + 106: wombat + 107: jellyfish + 108: sea anemone + 109: brain coral + 110: flatworm + 111: nematode + 112: conch + 113: snail + 114: slug + 115: sea slug + 116: chiton + 117: chambered nautilus + 118: Dungeness crab + 119: rock crab + 120: fiddler crab + 121: red king crab + 122: American lobster + 123: spiny lobster + 124: crayfish + 125: hermit crab + 126: isopod + 127: white stork + 128: black stork + 129: spoonbill + 130: flamingo + 131: little blue heron + 132: great egret + 133: bittern + 134: crane (bird) + 135: limpkin + 136: common gallinule + 137: American coot + 138: bustard + 139: ruddy turnstone + 140: dunlin + 141: common redshank + 142: dowitcher + 143: oystercatcher + 144: pelican + 145: king penguin + 146: albatross + 147: grey whale + 148: killer whale + 149: dugong + 150: sea lion + 151: Chihuahua + 152: Japanese Chin + 153: Maltese + 154: Pekingese + 155: Shih Tzu + 156: King Charles Spaniel + 157: Papillon + 158: toy terrier + 159: Rhodesian Ridgeback + 160: Afghan Hound + 161: Basset Hound + 162: Beagle + 163: Bloodhound + 164: Bluetick Coonhound + 165: Black and Tan Coonhound + 166: Treeing Walker Coonhound + 167: English foxhound + 168: Redbone Coonhound + 169: borzoi + 170: Irish Wolfhound + 171: Italian Greyhound + 172: Whippet + 173: Ibizan Hound + 174: Norwegian Elkhound + 175: Otterhound + 176: Saluki + 177: Scottish Deerhound + 178: Weimaraner + 179: Staffordshire Bull Terrier + 180: American Staffordshire Terrier + 181: Bedlington Terrier + 182: Border Terrier + 183: Kerry Blue Terrier + 184: Irish Terrier + 185: Norfolk Terrier + 186: Norwich Terrier + 187: Yorkshire Terrier + 188: Wire Fox Terrier + 189: Lakeland Terrier + 190: Sealyham Terrier + 191: Airedale Terrier + 192: Cairn Terrier + 193: Australian Terrier + 194: Dandie Dinmont Terrier + 195: Boston Terrier + 196: Miniature Schnauzer + 197: Giant Schnauzer + 198: Standard Schnauzer + 199: Scottish Terrier + 200: Tibetan Terrier + 201: Australian Silky Terrier + 202: Soft-coated Wheaten Terrier + 203: West Highland White Terrier + 204: Lhasa Apso + 205: Flat-Coated Retriever + 206: Curly-coated Retriever + 207: Golden Retriever + 208: Labrador Retriever + 209: Chesapeake Bay Retriever + 210: German Shorthaired Pointer + 211: Vizsla + 212: English Setter + 213: Irish Setter + 214: Gordon Setter + 215: Brittany + 216: Clumber Spaniel + 217: English Springer Spaniel + 218: Welsh Springer Spaniel + 219: Cocker Spaniels + 220: Sussex Spaniel + 221: Irish Water Spaniel + 222: Kuvasz + 223: Schipperke + 224: Groenendael + 225: Malinois + 226: Briard + 227: Australian Kelpie + 228: Komondor + 229: Old English Sheepdog + 230: Shetland Sheepdog + 231: collie + 232: Border Collie + 233: Bouvier des Flandres + 234: Rottweiler + 235: German Shepherd Dog + 236: Dobermann + 237: Miniature Pinscher + 238: Greater Swiss Mountain Dog + 239: Bernese Mountain Dog + 240: Appenzeller Sennenhund + 241: Entlebucher Sennenhund + 242: Boxer + 243: Bullmastiff + 244: Tibetan Mastiff + 245: French Bulldog + 246: Great Dane + 247: St. Bernard + 248: husky + 249: Alaskan Malamute + 250: Siberian Husky + 251: Dalmatian + 252: Affenpinscher + 253: Basenji + 254: pug + 255: Leonberger + 256: Newfoundland + 257: Pyrenean Mountain Dog + 258: Samoyed + 259: Pomeranian + 260: Chow Chow + 261: Keeshond + 262: Griffon Bruxellois + 263: Pembroke Welsh Corgi + 264: Cardigan Welsh Corgi + 265: Toy Poodle + 266: Miniature Poodle + 267: Standard Poodle + 268: Mexican hairless dog + 269: grey wolf + 270: Alaskan tundra wolf + 271: red wolf + 272: coyote + 273: dingo + 274: dhole + 275: African wild dog + 276: hyena + 277: red fox + 278: kit fox + 279: Arctic fox + 280: grey fox + 281: tabby cat + 282: tiger cat + 283: Persian cat + 284: Siamese cat + 285: Egyptian Mau + 286: cougar + 287: lynx + 288: leopard + 289: snow leopard + 290: jaguar + 291: lion + 292: tiger + 293: cheetah + 294: brown bear + 295: American black bear + 296: polar bear + 297: sloth bear + 298: mongoose + 299: meerkat + 300: tiger beetle + 301: ladybug + 302: ground beetle + 303: longhorn beetle + 304: leaf beetle + 305: dung beetle + 306: rhinoceros beetle + 307: weevil + 308: fly + 309: bee + 310: ant + 311: grasshopper + 312: cricket + 313: stick insect + 314: cockroach + 315: mantis + 316: cicada + 317: leafhopper + 318: lacewing + 319: dragonfly + 320: damselfly + 321: red admiral + 322: ringlet + 323: monarch butterfly + 324: small white + 325: sulphur butterfly + 326: gossamer-winged butterfly + 327: starfish + 328: sea urchin + 329: sea cucumber + 330: cottontail rabbit + 331: hare + 332: Angora rabbit + 333: hamster + 334: porcupine + 335: fox squirrel + 336: marmot + 337: beaver + 338: guinea pig + 339: common sorrel + 340: zebra + 341: pig + 342: wild boar + 343: warthog + 344: hippopotamus + 345: ox + 346: water buffalo + 347: bison + 348: ram + 349: bighorn sheep + 350: Alpine ibex + 351: hartebeest + 352: impala + 353: gazelle + 354: dromedary + 355: llama + 356: weasel + 357: mink + 358: European polecat + 359: black-footed ferret + 360: otter + 361: skunk + 362: badger + 363: armadillo + 364: three-toed sloth + 365: orangutan + 366: gorilla + 367: chimpanzee + 368: gibbon + 369: siamang + 370: guenon + 371: patas monkey + 372: baboon + 373: macaque + 374: langur + 375: black-and-white colobus + 376: proboscis monkey + 377: marmoset + 378: white-headed capuchin + 379: howler monkey + 380: titi + 381: Geoffroy's spider monkey + 382: common squirrel monkey + 383: ring-tailed lemur + 384: indri + 385: Asian elephant + 386: African bush elephant + 387: red panda + 388: giant panda + 389: snoek + 390: eel + 391: coho salmon + 392: rock beauty + 393: clownfish + 394: sturgeon + 395: garfish + 396: lionfish + 397: pufferfish + 398: abacus + 399: abaya + 400: academic gown + 401: accordion + 402: acoustic guitar + 403: aircraft carrier + 404: airliner + 405: airship + 406: altar + 407: ambulance + 408: amphibious vehicle + 409: analog clock + 410: apiary + 411: apron + 412: waste container + 413: assault rifle + 414: backpack + 415: bakery + 416: balance beam + 417: balloon + 418: ballpoint pen + 419: Band-Aid + 420: banjo + 421: baluster + 422: barbell + 423: barber chair + 424: barbershop + 425: barn + 426: barometer + 427: barrel + 428: wheelbarrow + 429: baseball + 430: basketball + 431: bassinet + 432: bassoon + 433: swimming cap + 434: bath towel + 435: bathtub + 436: station wagon + 437: lighthouse + 438: beaker + 439: military cap + 440: beer bottle + 441: beer glass + 442: bell-cot + 443: bib + 444: tandem bicycle + 445: bikini + 446: ring binder + 447: binoculars + 448: birdhouse + 449: boathouse + 450: bobsleigh + 451: bolo tie + 452: poke bonnet + 453: bookcase + 454: bookstore + 455: bottle cap + 456: bow + 457: bow tie + 458: brass + 459: bra + 460: breakwater + 461: breastplate + 462: broom + 463: bucket + 464: buckle + 465: bulletproof vest + 466: high-speed train + 467: butcher shop + 468: taxicab + 469: cauldron + 470: candle + 471: cannon + 472: canoe + 473: can opener + 474: cardigan + 475: car mirror + 476: carousel + 477: tool kit + 478: carton + 479: car wheel + 480: automated teller machine + 481: cassette + 482: cassette player + 483: castle + 484: catamaran + 485: CD player + 486: cello + 487: mobile phone + 488: chain + 489: chain-link fence + 490: chain mail + 491: chainsaw + 492: chest + 493: chiffonier + 494: chime + 495: china cabinet + 496: Christmas stocking + 497: church + 498: movie theater + 499: cleaver + 500: cliff dwelling + 501: cloak + 502: clogs + 503: cocktail shaker + 504: coffee mug + 505: coffeemaker + 506: coil + 507: combination lock + 508: computer keyboard + 509: confectionery store + 510: container ship + 511: convertible + 512: corkscrew + 513: cornet + 514: cowboy boot + 515: cowboy hat + 516: cradle + 517: crane (machine) + 518: crash helmet + 519: crate + 520: infant bed + 521: Crock Pot + 522: croquet ball + 523: crutch + 524: cuirass + 525: dam + 526: desk + 527: desktop computer + 528: rotary dial telephone + 529: diaper + 530: digital clock + 531: digital watch + 532: dining table + 533: dishcloth + 534: dishwasher + 535: disc brake + 536: dock + 537: dog sled + 538: dome + 539: doormat + 540: drilling rig + 541: drum + 542: drumstick + 543: dumbbell + 544: Dutch oven + 545: electric fan + 546: electric guitar + 547: electric locomotive + 548: entertainment center + 549: envelope + 550: espresso machine + 551: face powder + 552: feather boa + 553: filing cabinet + 554: fireboat + 555: fire engine + 556: fire screen sheet + 557: flagpole + 558: flute + 559: folding chair + 560: football helmet + 561: forklift + 562: fountain + 563: fountain pen + 564: four-poster bed + 565: freight car + 566: French horn + 567: frying pan + 568: fur coat + 569: garbage truck + 570: gas mask + 571: gas pump + 572: goblet + 573: go-kart + 574: golf ball + 575: golf cart + 576: gondola + 577: gong + 578: gown + 579: grand piano + 580: greenhouse + 581: grille + 582: grocery store + 583: guillotine + 584: barrette + 585: hair spray + 586: half-track + 587: hammer + 588: hamper + 589: hair dryer + 590: hand-held computer + 591: handkerchief + 592: hard disk drive + 593: harmonica + 594: harp + 595: harvester + 596: hatchet + 597: holster + 598: home theater + 599: honeycomb + 600: hook + 601: hoop skirt + 602: horizontal bar + 603: horse-drawn vehicle + 604: hourglass + 605: iPod + 606: clothes iron + 607: jack-o'-lantern + 608: jeans + 609: jeep + 610: T-shirt + 611: jigsaw puzzle + 612: pulled rickshaw + 613: joystick + 614: kimono + 615: knee pad + 616: knot + 617: lab coat + 618: ladle + 619: lampshade + 620: laptop computer + 621: lawn mower + 622: lens cap + 623: paper knife + 624: library + 625: lifeboat + 626: lighter + 627: limousine + 628: ocean liner + 629: lipstick + 630: slip-on shoe + 631: lotion + 632: speaker + 633: loupe + 634: sawmill + 635: magnetic compass + 636: mail bag + 637: mailbox + 638: tights + 639: tank suit + 640: manhole cover + 641: maraca + 642: marimba + 643: mask + 644: match + 645: maypole + 646: maze + 647: measuring cup + 648: medicine chest + 649: megalith + 650: microphone + 651: microwave oven + 652: military uniform + 653: milk can + 654: minibus + 655: miniskirt + 656: minivan + 657: missile + 658: mitten + 659: mixing bowl + 660: mobile home + 661: Model T + 662: modem + 663: monastery + 664: monitor + 665: moped + 666: mortar + 667: square academic cap + 668: mosque + 669: mosquito net + 670: scooter + 671: mountain bike + 672: tent + 673: computer mouse + 674: mousetrap + 675: moving van + 676: muzzle + 677: nail + 678: neck brace + 679: necklace + 680: nipple + 681: notebook computer + 682: obelisk + 683: oboe + 684: ocarina + 685: odometer + 686: oil filter + 687: organ + 688: oscilloscope + 689: overskirt + 690: bullock cart + 691: oxygen mask + 692: packet + 693: paddle + 694: paddle wheel + 695: padlock + 696: paintbrush + 697: pajamas + 698: palace + 699: pan flute + 700: paper towel + 701: parachute + 702: parallel bars + 703: park bench + 704: parking meter + 705: passenger car + 706: patio + 707: payphone + 708: pedestal + 709: pencil case + 710: pencil sharpener + 711: perfume + 712: Petri dish + 713: photocopier + 714: plectrum + 715: Pickelhaube + 716: picket fence + 717: pickup truck + 718: pier + 719: piggy bank + 720: pill bottle + 721: pillow + 722: ping-pong ball + 723: pinwheel + 724: pirate ship + 725: pitcher + 726: hand plane + 727: planetarium + 728: plastic bag + 729: plate rack + 730: plow + 731: plunger + 732: Polaroid camera + 733: pole + 734: police van + 735: poncho + 736: billiard table + 737: soda bottle + 738: pot + 739: potter's wheel + 740: power drill + 741: prayer rug + 742: printer + 743: prison + 744: projectile + 745: projector + 746: hockey puck + 747: punching bag + 748: purse + 749: quill + 750: quilt + 751: race car + 752: racket + 753: radiator + 754: radio + 755: radio telescope + 756: rain barrel + 757: recreational vehicle + 758: reel + 759: reflex camera + 760: refrigerator + 761: remote control + 762: restaurant + 763: revolver + 764: rifle + 765: rocking chair + 766: rotisserie + 767: eraser + 768: rugby ball + 769: ruler + 770: running shoe + 771: safe + 772: safety pin + 773: salt shaker + 774: sandal + 775: sarong + 776: saxophone + 777: scabbard + 778: weighing scale + 779: school bus + 780: schooner + 781: scoreboard + 782: CRT screen + 783: screw + 784: screwdriver + 785: seat belt + 786: sewing machine + 787: shield + 788: shoe store + 789: shoji + 790: shopping basket + 791: shopping cart + 792: shovel + 793: shower cap + 794: shower curtain + 795: ski + 796: ski mask + 797: sleeping bag + 798: slide rule + 799: sliding door + 800: slot machine + 801: snorkel + 802: snowmobile + 803: snowplow + 804: soap dispenser + 805: soccer ball + 806: sock + 807: solar thermal collector + 808: sombrero + 809: soup bowl + 810: space bar + 811: space heater + 812: space shuttle + 813: spatula + 814: motorboat + 815: spider web + 816: spindle + 817: sports car + 818: spotlight + 819: stage + 820: steam locomotive + 821: through arch bridge + 822: steel drum + 823: stethoscope + 824: scarf + 825: stone wall + 826: stopwatch + 827: stove + 828: strainer + 829: tram + 830: stretcher + 831: couch + 832: stupa + 833: submarine + 834: suit + 835: sundial + 836: sunglass + 837: sunglasses + 838: sunscreen + 839: suspension bridge + 840: mop + 841: sweatshirt + 842: swimsuit + 843: swing + 844: switch + 845: syringe + 846: table lamp + 847: tank + 848: tape player + 849: teapot + 850: teddy bear + 851: television + 852: tennis ball + 853: thatched roof + 854: front curtain + 855: thimble + 856: threshing machine + 857: throne + 858: tile roof + 859: toaster + 860: tobacco shop + 861: toilet seat + 862: torch + 863: totem pole + 864: tow truck + 865: toy store + 866: tractor + 867: semi-trailer truck + 868: tray + 869: trench coat + 870: tricycle + 871: trimaran + 872: tripod + 873: triumphal arch + 874: trolleybus + 875: trombone + 876: tub + 877: turnstile + 878: typewriter keyboard + 879: umbrella + 880: unicycle + 881: upright piano + 882: vacuum cleaner + 883: vase + 884: vault + 885: velvet + 886: vending machine + 887: vestment + 888: viaduct + 889: violin + 890: volleyball + 891: waffle iron + 892: wall clock + 893: wallet + 894: wardrobe + 895: military aircraft + 896: sink + 897: washing machine + 898: water bottle + 899: water jug + 900: water tower + 901: whiskey jug + 902: whistle + 903: wig + 904: window screen + 905: window shade + 906: Windsor tie + 907: wine bottle + 908: wing + 909: wok + 910: wooden spoon + 911: wool + 912: split-rail fence + 913: shipwreck + 914: yawl + 915: yurt + 916: website + 917: comic book + 918: crossword + 919: traffic sign + 920: traffic light + 921: dust jacket + 922: menu + 923: plate + 924: guacamole + 925: consomme + 926: hot pot + 927: trifle + 928: ice cream + 929: ice pop + 930: baguette + 931: bagel + 932: pretzel + 933: cheeseburger + 934: hot dog + 935: mashed potato + 936: cabbage + 937: broccoli + 938: cauliflower + 939: zucchini + 940: spaghetti squash + 941: acorn squash + 942: butternut squash + 943: cucumber + 944: artichoke + 945: bell pepper + 946: cardoon + 947: mushroom + 948: Granny Smith + 949: strawberry + 950: orange + 951: lemon + 952: fig + 953: pineapple + 954: banana + 955: jackfruit + 956: custard apple + 957: pomegranate + 958: hay + 959: carbonara + 960: chocolate syrup + 961: dough + 962: meatloaf + 963: pizza + 964: pot pie + 965: burrito + 966: red wine + 967: espresso + 968: cup + 969: eggnog + 970: alp + 971: bubble + 972: cliff + 973: coral reef + 974: geyser + 975: lakeshore + 976: promontory + 977: shoal + 978: seashore + 979: valley + 980: volcano + 981: baseball player + 982: bridegroom + 983: scuba diver + 984: rapeseed + 985: daisy + 986: yellow lady's slipper + 987: corn + 988: acorn + 989: rose hip + 990: horse chestnut seed + 991: coral fungus + 992: agaric + 993: gyromitra + 994: stinkhorn mushroom + 995: earth star + 996: hen-of-the-woods + 997: bolete + 998: ear + 999: toilet paper + +# Imagenet class codes to human-readable names +map: + n01440764: tench + n01443537: goldfish + n01484850: great_white_shark + n01491361: tiger_shark + n01494475: hammerhead + n01496331: electric_ray + n01498041: stingray + n01514668: cock + n01514859: hen + n01518878: ostrich + n01530575: brambling + n01531178: goldfinch + n01532829: house_finch + n01534433: junco + n01537544: indigo_bunting + n01558993: robin + n01560419: bulbul + n01580077: jay + n01582220: magpie + n01592084: chickadee + n01601694: water_ouzel + n01608432: kite + n01614925: bald_eagle + n01616318: vulture + n01622779: great_grey_owl + n01629819: European_fire_salamander + n01630670: common_newt + n01631663: eft + n01632458: spotted_salamander + n01632777: axolotl + n01641577: bullfrog + n01644373: tree_frog + n01644900: tailed_frog + n01664065: loggerhead + n01665541: leatherback_turtle + n01667114: mud_turtle + n01667778: terrapin + n01669191: box_turtle + n01675722: banded_gecko + n01677366: common_iguana + n01682714: American_chameleon + n01685808: whiptail + n01687978: agama + n01688243: frilled_lizard + n01689811: alligator_lizard + n01692333: Gila_monster + n01693334: green_lizard + n01694178: African_chameleon + n01695060: Komodo_dragon + n01697457: African_crocodile + n01698640: American_alligator + n01704323: triceratops + n01728572: thunder_snake + n01728920: ringneck_snake + n01729322: hognose_snake + n01729977: green_snake + n01734418: king_snake + n01735189: garter_snake + n01737021: water_snake + n01739381: vine_snake + n01740131: night_snake + n01742172: boa_constrictor + n01744401: rock_python + n01748264: Indian_cobra + n01749939: green_mamba + n01751748: sea_snake + n01753488: horned_viper + n01755581: diamondback + n01756291: sidewinder + n01768244: trilobite + n01770081: harvestman + n01770393: scorpion + n01773157: black_and_gold_garden_spider + n01773549: barn_spider + n01773797: garden_spider + n01774384: black_widow + n01774750: tarantula + n01775062: wolf_spider + n01776313: tick + n01784675: centipede + n01795545: black_grouse + n01796340: ptarmigan + n01797886: ruffed_grouse + n01798484: prairie_chicken + n01806143: peacock + n01806567: quail + n01807496: partridge + n01817953: African_grey + n01818515: macaw + n01819313: sulphur-crested_cockatoo + n01820546: lorikeet + n01824575: coucal + n01828970: bee_eater + n01829413: hornbill + n01833805: hummingbird + n01843065: jacamar + n01843383: toucan + n01847000: drake + n01855032: red-breasted_merganser + n01855672: goose + n01860187: black_swan + n01871265: tusker + n01872401: echidna + n01873310: platypus + n01877812: wallaby + n01882714: koala + n01883070: wombat + n01910747: jellyfish + n01914609: sea_anemone + n01917289: brain_coral + n01924916: flatworm + n01930112: nematode + n01943899: conch + n01944390: snail + n01945685: slug + n01950731: sea_slug + n01955084: chiton + n01968897: chambered_nautilus + n01978287: Dungeness_crab + n01978455: rock_crab + n01980166: fiddler_crab + n01981276: king_crab + n01983481: American_lobster + n01984695: spiny_lobster + n01985128: crayfish + n01986214: hermit_crab + n01990800: isopod + n02002556: white_stork + n02002724: black_stork + n02006656: spoonbill + n02007558: flamingo + n02009229: little_blue_heron + n02009912: American_egret + n02011460: bittern + n02012849: crane_(bird) + n02013706: limpkin + n02017213: European_gallinule + n02018207: American_coot + n02018795: bustard + n02025239: ruddy_turnstone + n02027492: red-backed_sandpiper + n02028035: redshank + n02033041: dowitcher + n02037110: oystercatcher + n02051845: pelican + n02056570: king_penguin + n02058221: albatross + n02066245: grey_whale + n02071294: killer_whale + n02074367: dugong + n02077923: sea_lion + n02085620: Chihuahua + n02085782: Japanese_spaniel + n02085936: Maltese_dog + n02086079: Pekinese + n02086240: Shih-Tzu + n02086646: Blenheim_spaniel + n02086910: papillon + n02087046: toy_terrier + n02087394: Rhodesian_ridgeback + n02088094: Afghan_hound + n02088238: basset + n02088364: beagle + n02088466: bloodhound + n02088632: bluetick + n02089078: black-and-tan_coonhound + n02089867: Walker_hound + n02089973: English_foxhound + n02090379: redbone + n02090622: borzoi + n02090721: Irish_wolfhound + n02091032: Italian_greyhound + n02091134: whippet + n02091244: Ibizan_hound + n02091467: Norwegian_elkhound + n02091635: otterhound + n02091831: Saluki + n02092002: Scottish_deerhound + n02092339: Weimaraner + n02093256: Staffordshire_bullterrier + n02093428: American_Staffordshire_terrier + n02093647: Bedlington_terrier + n02093754: Border_terrier + n02093859: Kerry_blue_terrier + n02093991: Irish_terrier + n02094114: Norfolk_terrier + n02094258: Norwich_terrier + n02094433: Yorkshire_terrier + n02095314: wire-haired_fox_terrier + n02095570: Lakeland_terrier + n02095889: Sealyham_terrier + n02096051: Airedale + n02096177: cairn + n02096294: Australian_terrier + n02096437: Dandie_Dinmont + n02096585: Boston_bull + n02097047: miniature_schnauzer + n02097130: giant_schnauzer + n02097209: standard_schnauzer + n02097298: Scotch_terrier + n02097474: Tibetan_terrier + n02097658: silky_terrier + n02098105: soft-coated_wheaten_terrier + n02098286: West_Highland_white_terrier + n02098413: Lhasa + n02099267: flat-coated_retriever + n02099429: curly-coated_retriever + n02099601: golden_retriever + n02099712: Labrador_retriever + n02099849: Chesapeake_Bay_retriever + n02100236: German_short-haired_pointer + n02100583: vizsla + n02100735: English_setter + n02100877: Irish_setter + n02101006: Gordon_setter + n02101388: Brittany_spaniel + n02101556: clumber + n02102040: English_springer + n02102177: Welsh_springer_spaniel + n02102318: cocker_spaniel + n02102480: Sussex_spaniel + n02102973: Irish_water_spaniel + n02104029: kuvasz + n02104365: schipperke + n02105056: groenendael + n02105162: malinois + n02105251: briard + n02105412: kelpie + n02105505: komondor + n02105641: Old_English_sheepdog + n02105855: Shetland_sheepdog + n02106030: collie + n02106166: Border_collie + n02106382: Bouvier_des_Flandres + n02106550: Rottweiler + n02106662: German_shepherd + n02107142: Doberman + n02107312: miniature_pinscher + n02107574: Greater_Swiss_Mountain_dog + n02107683: Bernese_mountain_dog + n02107908: Appenzeller + n02108000: EntleBucher + n02108089: boxer + n02108422: bull_mastiff + n02108551: Tibetan_mastiff + n02108915: French_bulldog + n02109047: Great_Dane + n02109525: Saint_Bernard + n02109961: Eskimo_dog + n02110063: malamute + n02110185: Siberian_husky + n02110341: dalmatian + n02110627: affenpinscher + n02110806: basenji + n02110958: pug + n02111129: Leonberg + n02111277: Newfoundland + n02111500: Great_Pyrenees + n02111889: Samoyed + n02112018: Pomeranian + n02112137: chow + n02112350: keeshond + n02112706: Brabancon_griffon + n02113023: Pembroke + n02113186: Cardigan + n02113624: toy_poodle + n02113712: miniature_poodle + n02113799: standard_poodle + n02113978: Mexican_hairless + n02114367: timber_wolf + n02114548: white_wolf + n02114712: red_wolf + n02114855: coyote + n02115641: dingo + n02115913: dhole + n02116738: African_hunting_dog + n02117135: hyena + n02119022: red_fox + n02119789: kit_fox + n02120079: Arctic_fox + n02120505: grey_fox + n02123045: tabby + n02123159: tiger_cat + n02123394: Persian_cat + n02123597: Siamese_cat + n02124075: Egyptian_cat + n02125311: cougar + n02127052: lynx + n02128385: leopard + n02128757: snow_leopard + n02128925: jaguar + n02129165: lion + n02129604: tiger + n02130308: cheetah + n02132136: brown_bear + n02133161: American_black_bear + n02134084: ice_bear + n02134418: sloth_bear + n02137549: mongoose + n02138441: meerkat + n02165105: tiger_beetle + n02165456: ladybug + n02167151: ground_beetle + n02168699: long-horned_beetle + n02169497: leaf_beetle + n02172182: dung_beetle + n02174001: rhinoceros_beetle + n02177972: weevil + n02190166: fly + n02206856: bee + n02219486: ant + n02226429: grasshopper + n02229544: cricket + n02231487: walking_stick + n02233338: cockroach + n02236044: mantis + n02256656: cicada + n02259212: leafhopper + n02264363: lacewing + n02268443: dragonfly + n02268853: damselfly + n02276258: admiral + n02277742: ringlet + n02279972: monarch + n02280649: cabbage_butterfly + n02281406: sulphur_butterfly + n02281787: lycaenid + n02317335: starfish + n02319095: sea_urchin + n02321529: sea_cucumber + n02325366: wood_rabbit + n02326432: hare + n02328150: Angora + n02342885: hamster + n02346627: porcupine + n02356798: fox_squirrel + n02361337: marmot + n02363005: beaver + n02364673: guinea_pig + n02389026: sorrel + n02391049: zebra + n02395406: hog + n02396427: wild_boar + n02397096: warthog + n02398521: hippopotamus + n02403003: ox + n02408429: water_buffalo + n02410509: bison + n02412080: ram + n02415577: bighorn + n02417914: ibex + n02422106: hartebeest + n02422699: impala + n02423022: gazelle + n02437312: Arabian_camel + n02437616: llama + n02441942: weasel + n02442845: mink + n02443114: polecat + n02443484: black-footed_ferret + n02444819: otter + n02445715: skunk + n02447366: badger + n02454379: armadillo + n02457408: three-toed_sloth + n02480495: orangutan + n02480855: gorilla + n02481823: chimpanzee + n02483362: gibbon + n02483708: siamang + n02484975: guenon + n02486261: patas + n02486410: baboon + n02487347: macaque + n02488291: langur + n02488702: colobus + n02489166: proboscis_monkey + n02490219: marmoset + n02492035: capuchin + n02492660: howler_monkey + n02493509: titi + n02493793: spider_monkey + n02494079: squirrel_monkey + n02497673: Madagascar_cat + n02500267: indri + n02504013: Indian_elephant + n02504458: African_elephant + n02509815: lesser_panda + n02510455: giant_panda + n02514041: barracouta + n02526121: eel + n02536864: coho + n02606052: rock_beauty + n02607072: anemone_fish + n02640242: sturgeon + n02641379: gar + n02643566: lionfish + n02655020: puffer + n02666196: abacus + n02667093: abaya + n02669723: academic_gown + n02672831: accordion + n02676566: acoustic_guitar + n02687172: aircraft_carrier + n02690373: airliner + n02692877: airship + n02699494: altar + n02701002: ambulance + n02704792: amphibian + n02708093: analog_clock + n02727426: apiary + n02730930: apron + n02747177: ashcan + n02749479: assault_rifle + n02769748: backpack + n02776631: bakery + n02777292: balance_beam + n02782093: balloon + n02783161: ballpoint + n02786058: Band_Aid + n02787622: banjo + n02788148: bannister + n02790996: barbell + n02791124: barber_chair + n02791270: barbershop + n02793495: barn + n02794156: barometer + n02795169: barrel + n02797295: barrow + n02799071: baseball + n02802426: basketball + n02804414: bassinet + n02804610: bassoon + n02807133: bathing_cap + n02808304: bath_towel + n02808440: bathtub + n02814533: beach_wagon + n02814860: beacon + n02815834: beaker + n02817516: bearskin + n02823428: beer_bottle + n02823750: beer_glass + n02825657: bell_cote + n02834397: bib + n02835271: bicycle-built-for-two + n02837789: bikini + n02840245: binder + n02841315: binoculars + n02843684: birdhouse + n02859443: boathouse + n02860847: bobsled + n02865351: bolo_tie + n02869837: bonnet + n02870880: bookcase + n02871525: bookshop + n02877765: bottlecap + n02879718: bow + n02883205: bow_tie + n02892201: brass + n02892767: brassiere + n02894605: breakwater + n02895154: breastplate + n02906734: broom + n02909870: bucket + n02910353: buckle + n02916936: bulletproof_vest + n02917067: bullet_train + n02927161: butcher_shop + n02930766: cab + n02939185: caldron + n02948072: candle + n02950826: cannon + n02951358: canoe + n02951585: can_opener + n02963159: cardigan + n02965783: car_mirror + n02966193: carousel + n02966687: carpenter's_kit + n02971356: carton + n02974003: car_wheel + n02977058: cash_machine + n02978881: cassette + n02979186: cassette_player + n02980441: castle + n02981792: catamaran + n02988304: CD_player + n02992211: cello + n02992529: cellular_telephone + n02999410: chain + n03000134: chainlink_fence + n03000247: chain_mail + n03000684: chain_saw + n03014705: chest + n03016953: chiffonier + n03017168: chime + n03018349: china_cabinet + n03026506: Christmas_stocking + n03028079: church + n03032252: cinema + n03041632: cleaver + n03042490: cliff_dwelling + n03045698: cloak + n03047690: clog + n03062245: cocktail_shaker + n03063599: coffee_mug + n03063689: coffeepot + n03065424: coil + n03075370: combination_lock + n03085013: computer_keyboard + n03089624: confectionery + n03095699: container_ship + n03100240: convertible + n03109150: corkscrew + n03110669: cornet + n03124043: cowboy_boot + n03124170: cowboy_hat + n03125729: cradle + n03126707: crane_(machine) + n03127747: crash_helmet + n03127925: crate + n03131574: crib + n03133878: Crock_Pot + n03134739: croquet_ball + n03141823: crutch + n03146219: cuirass + n03160309: dam + n03179701: desk + n03180011: desktop_computer + n03187595: dial_telephone + n03188531: diaper + n03196217: digital_clock + n03197337: digital_watch + n03201208: dining_table + n03207743: dishrag + n03207941: dishwasher + n03208938: disk_brake + n03216828: dock + n03218198: dogsled + n03220513: dome + n03223299: doormat + n03240683: drilling_platform + n03249569: drum + n03250847: drumstick + n03255030: dumbbell + n03259280: Dutch_oven + n03271574: electric_fan + n03272010: electric_guitar + n03272562: electric_locomotive + n03290653: entertainment_center + n03291819: envelope + n03297495: espresso_maker + n03314780: face_powder + n03325584: feather_boa + n03337140: file + n03344393: fireboat + n03345487: fire_engine + n03347037: fire_screen + n03355925: flagpole + n03372029: flute + n03376595: folding_chair + n03379051: football_helmet + n03384352: forklift + n03388043: fountain + n03388183: fountain_pen + n03388549: four-poster + n03393912: freight_car + n03394916: French_horn + n03400231: frying_pan + n03404251: fur_coat + n03417042: garbage_truck + n03424325: gasmask + n03425413: gas_pump + n03443371: goblet + n03444034: go-kart + n03445777: golf_ball + n03445924: golfcart + n03447447: gondola + n03447721: gong + n03450230: gown + n03452741: grand_piano + n03457902: greenhouse + n03459775: grille + n03461385: grocery_store + n03467068: guillotine + n03476684: hair_slide + n03476991: hair_spray + n03478589: half_track + n03481172: hammer + n03482405: hamper + n03483316: hand_blower + n03485407: hand-held_computer + n03485794: handkerchief + n03492542: hard_disc + n03494278: harmonica + n03495258: harp + n03496892: harvester + n03498962: hatchet + n03527444: holster + n03529860: home_theater + n03530642: honeycomb + n03532672: hook + n03534580: hoopskirt + n03535780: horizontal_bar + n03538406: horse_cart + n03544143: hourglass + n03584254: iPod + n03584829: iron + n03590841: jack-o'-lantern + n03594734: jean + n03594945: jeep + n03595614: jersey + n03598930: jigsaw_puzzle + n03599486: jinrikisha + n03602883: joystick + n03617480: kimono + n03623198: knee_pad + n03627232: knot + n03630383: lab_coat + n03633091: ladle + n03637318: lampshade + n03642806: laptop + n03649909: lawn_mower + n03657121: lens_cap + n03658185: letter_opener + n03661043: library + n03662601: lifeboat + n03666591: lighter + n03670208: limousine + n03673027: liner + n03676483: lipstick + n03680355: Loafer + n03690938: lotion + n03691459: loudspeaker + n03692522: loupe + n03697007: lumbermill + n03706229: magnetic_compass + n03709823: mailbag + n03710193: mailbox + n03710637: maillot_(tights) + n03710721: maillot_(tank_suit) + n03717622: manhole_cover + n03720891: maraca + n03721384: marimba + n03724870: mask + n03729826: matchstick + n03733131: maypole + n03733281: maze + n03733805: measuring_cup + n03742115: medicine_chest + n03743016: megalith + n03759954: microphone + n03761084: microwave + n03763968: military_uniform + n03764736: milk_can + n03769881: minibus + n03770439: miniskirt + n03770679: minivan + n03773504: missile + n03775071: mitten + n03775546: mixing_bowl + n03776460: mobile_home + n03777568: Model_T + n03777754: modem + n03781244: monastery + n03782006: monitor + n03785016: moped + n03786901: mortar + n03787032: mortarboard + n03788195: mosque + n03788365: mosquito_net + n03791053: motor_scooter + n03792782: mountain_bike + n03792972: mountain_tent + n03793489: mouse + n03794056: mousetrap + n03796401: moving_van + n03803284: muzzle + n03804744: nail + n03814639: neck_brace + n03814906: necklace + n03825788: nipple + n03832673: notebook + n03837869: obelisk + n03838899: oboe + n03840681: ocarina + n03841143: odometer + n03843555: oil_filter + n03854065: organ + n03857828: oscilloscope + n03866082: overskirt + n03868242: oxcart + n03868863: oxygen_mask + n03871628: packet + n03873416: paddle + n03874293: paddlewheel + n03874599: padlock + n03876231: paintbrush + n03877472: pajama + n03877845: palace + n03884397: panpipe + n03887697: paper_towel + n03888257: parachute + n03888605: parallel_bars + n03891251: park_bench + n03891332: parking_meter + n03895866: passenger_car + n03899768: patio + n03902125: pay-phone + n03903868: pedestal + n03908618: pencil_box + n03908714: pencil_sharpener + n03916031: perfume + n03920288: Petri_dish + n03924679: photocopier + n03929660: pick + n03929855: pickelhaube + n03930313: picket_fence + n03930630: pickup + n03933933: pier + n03935335: piggy_bank + n03937543: pill_bottle + n03938244: pillow + n03942813: ping-pong_ball + n03944341: pinwheel + n03947888: pirate + n03950228: pitcher + n03954731: plane + n03956157: planetarium + n03958227: plastic_bag + n03961711: plate_rack + n03967562: plow + n03970156: plunger + n03976467: Polaroid_camera + n03976657: pole + n03977966: police_van + n03980874: poncho + n03982430: pool_table + n03983396: pop_bottle + n03991062: pot + n03992509: potter's_wheel + n03995372: power_drill + n03998194: prayer_rug + n04004767: printer + n04005630: prison + n04008634: projectile + n04009552: projector + n04019541: puck + n04023962: punching_bag + n04026417: purse + n04033901: quill + n04033995: quilt + n04037443: racer + n04039381: racket + n04040759: radiator + n04041544: radio + n04044716: radio_telescope + n04049303: rain_barrel + n04065272: recreational_vehicle + n04067472: reel + n04069434: reflex_camera + n04070727: refrigerator + n04074963: remote_control + n04081281: restaurant + n04086273: revolver + n04090263: rifle + n04099969: rocking_chair + n04111531: rotisserie + n04116512: rubber_eraser + n04118538: rugby_ball + n04118776: rule + n04120489: running_shoe + n04125021: safe + n04127249: safety_pin + n04131690: saltshaker + n04133789: sandal + n04136333: sarong + n04141076: sax + n04141327: scabbard + n04141975: scale + n04146614: school_bus + n04147183: schooner + n04149813: scoreboard + n04152593: screen + n04153751: screw + n04154565: screwdriver + n04162706: seat_belt + n04179913: sewing_machine + n04192698: shield + n04200800: shoe_shop + n04201297: shoji + n04204238: shopping_basket + n04204347: shopping_cart + n04208210: shovel + n04209133: shower_cap + n04209239: shower_curtain + n04228054: ski + n04229816: ski_mask + n04235860: sleeping_bag + n04238763: slide_rule + n04239074: sliding_door + n04243546: slot + n04251144: snorkel + n04252077: snowmobile + n04252225: snowplow + n04254120: soap_dispenser + n04254680: soccer_ball + n04254777: sock + n04258138: solar_dish + n04259630: sombrero + n04263257: soup_bowl + n04264628: space_bar + n04265275: space_heater + n04266014: space_shuttle + n04270147: spatula + n04273569: speedboat + n04275548: spider_web + n04277352: spindle + n04285008: sports_car + n04286575: spotlight + n04296562: stage + n04310018: steam_locomotive + n04311004: steel_arch_bridge + n04311174: steel_drum + n04317175: stethoscope + n04325704: stole + n04326547: stone_wall + n04328186: stopwatch + n04330267: stove + n04332243: strainer + n04335435: streetcar + n04336792: stretcher + n04344873: studio_couch + n04346328: stupa + n04347754: submarine + n04350905: suit + n04355338: sundial + n04355933: sunglass + n04356056: sunglasses + n04357314: sunscreen + n04366367: suspension_bridge + n04367480: swab + n04370456: sweatshirt + n04371430: swimming_trunks + n04371774: swing + n04372370: switch + n04376876: syringe + n04380533: table_lamp + n04389033: tank + n04392985: tape_player + n04398044: teapot + n04399382: teddy + n04404412: television + n04409515: tennis_ball + n04417672: thatch + n04418357: theater_curtain + n04423845: thimble + n04428191: thresher + n04429376: throne + n04435653: tile_roof + n04442312: toaster + n04443257: tobacco_shop + n04447861: toilet_seat + n04456115: torch + n04458633: totem_pole + n04461696: tow_truck + n04462240: toyshop + n04465501: tractor + n04467665: trailer_truck + n04476259: tray + n04479046: trench_coat + n04482393: tricycle + n04483307: trimaran + n04485082: tripod + n04486054: triumphal_arch + n04487081: trolleybus + n04487394: trombone + n04493381: tub + n04501370: turnstile + n04505470: typewriter_keyboard + n04507155: umbrella + n04509417: unicycle + n04515003: upright + n04517823: vacuum + n04522168: vase + n04523525: vault + n04525038: velvet + n04525305: vending_machine + n04532106: vestment + n04532670: viaduct + n04536866: violin + n04540053: volleyball + n04542943: waffle_iron + n04548280: wall_clock + n04548362: wallet + n04550184: wardrobe + n04552348: warplane + n04553703: washbasin + n04554684: washer + n04557648: water_bottle + n04560804: water_jug + n04562935: water_tower + n04579145: whiskey_jug + n04579432: whistle + n04584207: wig + n04589890: window_screen + n04590129: window_shade + n04591157: Windsor_tie + n04591713: wine_bottle + n04592741: wing + n04596742: wok + n04597913: wooden_spoon + n04599235: wool + n04604644: worm_fence + n04606251: wreck + n04612504: yawl + n04613696: yurt + n06359193: web_site + n06596364: comic_book + n06785654: crossword_puzzle + n06794110: street_sign + n06874185: traffic_light + n07248320: book_jacket + n07565083: menu + n07579787: plate + n07583066: guacamole + n07584110: consomme + n07590611: hot_pot + n07613480: trifle + n07614500: ice_cream + n07615774: ice_lolly + n07684084: French_loaf + n07693725: bagel + n07695742: pretzel + n07697313: cheeseburger + n07697537: hotdog + n07711569: mashed_potato + n07714571: head_cabbage + n07714990: broccoli + n07715103: cauliflower + n07716358: zucchini + n07716906: spaghetti_squash + n07717410: acorn_squash + n07717556: butternut_squash + n07718472: cucumber + n07718747: artichoke + n07720875: bell_pepper + n07730033: cardoon + n07734744: mushroom + n07742313: Granny_Smith + n07745940: strawberry + n07747607: orange + n07749582: lemon + n07753113: fig + n07753275: pineapple + n07753592: banana + n07754684: jackfruit + n07760859: custard_apple + n07768694: pomegranate + n07802026: hay + n07831146: carbonara + n07836838: chocolate_sauce + n07860988: dough + n07871810: meat_loaf + n07873807: pizza + n07875152: potpie + n07880968: burrito + n07892512: red_wine + n07920052: espresso + n07930864: cup + n07932039: eggnog + n09193705: alp + n09229709: bubble + n09246464: cliff + n09256479: coral_reef + n09288635: geyser + n09332890: lakeside + n09399592: promontory + n09421951: sandbar + n09428293: seashore + n09468604: valley + n09472597: volcano + n09835506: ballplayer + n10148035: groom + n10565667: scuba_diver + n11879895: rapeseed + n11939491: daisy + n12057211: yellow_lady's_slipper + n12144580: corn + n12267677: acorn + n12620546: hip + n12768682: buckeye + n12985857: coral_fungus + n12998815: agaric + n13037406: gyromitra + n13040303: stinkhorn + n13044778: earthstar + n13052670: hen-of-the-woods + n13054560: bolete + n13133613: ear + n15075141: toilet_tissue + +# Download script/URL (optional) +download: yolo/data/scripts/get_imagenet.sh diff --git a/ultralytics/cfg/datasets/Objects365.yaml b/ultralytics/cfg/datasets/Objects365.yaml new file mode 100644 index 0000000..9b11720 --- /dev/null +++ b/ultralytics/cfg/datasets/Objects365.yaml @@ -0,0 +1,442 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# Objects365 dataset https://www.objects365.org/ by Megvii +# Documentation: https://docs.ultralytics.com/datasets/detect/objects365/ +# Example usage: yolo train data=Objects365.yaml +# parent +# ├── ultralytics +# └── datasets +# └── Objects365 ← downloads here (712 GB = 367G data + 345G zips) + +# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..] +path: ../datasets/Objects365 # dataset root dir +train: images/train # train images (relative to 'path') 1742289 images +val: images/val # val images (relative to 'path') 80000 images +test: # test images (optional) + +# Classes +names: + 0: Person + 1: Sneakers + 2: Chair + 3: Other Shoes + 4: Hat + 5: Car + 6: Lamp + 7: Glasses + 8: Bottle + 9: Desk + 10: Cup + 11: Street Lights + 12: Cabinet/shelf + 13: Handbag/Satchel + 14: Bracelet + 15: Plate + 16: Picture/Frame + 17: Helmet + 18: Book + 19: Gloves + 20: Storage box + 21: Boat + 22: Leather Shoes + 23: Flower + 24: Bench + 25: Potted Plant + 26: Bowl/Basin + 27: Flag + 28: Pillow + 29: Boots + 30: Vase + 31: Microphone + 32: Necklace + 33: Ring + 34: SUV + 35: Wine Glass + 36: Belt + 37: Monitor/TV + 38: Backpack + 39: Umbrella + 40: Traffic Light + 41: Speaker + 42: Watch + 43: Tie + 44: Trash bin Can + 45: Slippers + 46: Bicycle + 47: Stool + 48: Barrel/bucket + 49: Van + 50: Couch + 51: Sandals + 52: Basket + 53: Drum + 54: Pen/Pencil + 55: Bus + 56: Wild Bird + 57: High Heels + 58: Motorcycle + 59: Guitar + 60: Carpet + 61: Cell Phone + 62: Bread + 63: Camera + 64: Canned + 65: Truck + 66: Traffic cone + 67: Cymbal + 68: Lifesaver + 69: Towel + 70: Stuffed Toy + 71: Candle + 72: Sailboat + 73: Laptop + 74: Awning + 75: Bed + 76: Faucet + 77: Tent + 78: Horse + 79: Mirror + 80: Power outlet + 81: Sink + 82: Apple + 83: Air Conditioner + 84: Knife + 85: Hockey Stick + 86: Paddle + 87: Pickup Truck + 88: Fork + 89: Traffic Sign + 90: Balloon + 91: Tripod + 92: Dog + 93: Spoon + 94: Clock + 95: Pot + 96: Cow + 97: Cake + 98: Dinning Table + 99: Sheep + 100: Hanger + 101: Blackboard/Whiteboard + 102: Napkin + 103: Other Fish + 104: Orange/Tangerine + 105: Toiletry + 106: Keyboard + 107: Tomato + 108: Lantern + 109: Machinery Vehicle + 110: Fan + 111: Green Vegetables + 112: Banana + 113: Baseball Glove + 114: Airplane + 115: Mouse + 116: Train + 117: Pumpkin + 118: Soccer + 119: Skiboard + 120: Luggage + 121: Nightstand + 122: Tea pot + 123: Telephone + 124: Trolley + 125: Head Phone + 126: Sports Car + 127: Stop Sign + 128: Dessert + 129: Scooter + 130: Stroller + 131: Crane + 132: Remote + 133: Refrigerator + 134: Oven + 135: Lemon + 136: Duck + 137: Baseball Bat + 138: Surveillance Camera + 139: Cat + 140: Jug + 141: Broccoli + 142: Piano + 143: Pizza + 144: Elephant + 145: Skateboard + 146: Surfboard + 147: Gun + 148: Skating and Skiing shoes + 149: Gas stove + 150: Donut + 151: Bow Tie + 152: Carrot + 153: Toilet + 154: Kite + 155: Strawberry + 156: Other Balls + 157: Shovel + 158: Pepper + 159: Computer Box + 160: Toilet Paper + 161: Cleaning Products + 162: Chopsticks + 163: Microwave + 164: Pigeon + 165: Baseball + 166: Cutting/chopping Board + 167: Coffee Table + 168: Side Table + 169: Scissors + 170: Marker + 171: Pie + 172: Ladder + 173: Snowboard + 174: Cookies + 175: Radiator + 176: Fire Hydrant + 177: Basketball + 178: Zebra + 179: Grape + 180: Giraffe + 181: Potato + 182: Sausage + 183: Tricycle + 184: Violin + 185: Egg + 186: Fire Extinguisher + 187: Candy + 188: Fire Truck + 189: Billiards + 190: Converter + 191: Bathtub + 192: Wheelchair + 193: Golf Club + 194: Briefcase + 195: Cucumber + 196: Cigar/Cigarette + 197: Paint Brush + 198: Pear + 199: Heavy Truck + 200: Hamburger + 201: Extractor + 202: Extension Cord + 203: Tong + 204: Tennis Racket + 205: Folder + 206: American Football + 207: earphone + 208: Mask + 209: Kettle + 210: Tennis + 211: Ship + 212: Swing + 213: Coffee Machine + 214: Slide + 215: Carriage + 216: Onion + 217: Green beans + 218: Projector + 219: Frisbee + 220: Washing Machine/Drying Machine + 221: Chicken + 222: Printer + 223: Watermelon + 224: Saxophone + 225: Tissue + 226: Toothbrush + 227: Ice cream + 228: Hot-air balloon + 229: Cello + 230: French Fries + 231: Scale + 232: Trophy + 233: Cabbage + 234: Hot dog + 235: Blender + 236: Peach + 237: Rice + 238: Wallet/Purse + 239: Volleyball + 240: Deer + 241: Goose + 242: Tape + 243: Tablet + 244: Cosmetics + 245: Trumpet + 246: Pineapple + 247: Golf Ball + 248: Ambulance + 249: Parking meter + 250: Mango + 251: Key + 252: Hurdle + 253: Fishing Rod + 254: Medal + 255: Flute + 256: Brush + 257: Penguin + 258: Megaphone + 259: Corn + 260: Lettuce + 261: Garlic + 262: Swan + 263: Helicopter + 264: Green Onion + 265: Sandwich + 266: Nuts + 267: Speed Limit Sign + 268: Induction Cooker + 269: Broom + 270: Trombone + 271: Plum + 272: Rickshaw + 273: Goldfish + 274: Kiwi fruit + 275: Router/modem + 276: Poker Card + 277: Toaster + 278: Shrimp + 279: Sushi + 280: Cheese + 281: Notepaper + 282: Cherry + 283: Pliers + 284: CD + 285: Pasta + 286: Hammer + 287: Cue + 288: Avocado + 289: Hamimelon + 290: Flask + 291: Mushroom + 292: Screwdriver + 293: Soap + 294: Recorder + 295: Bear + 296: Eggplant + 297: Board Eraser + 298: Coconut + 299: Tape Measure/Ruler + 300: Pig + 301: Showerhead + 302: Globe + 303: Chips + 304: Steak + 305: Crosswalk Sign + 306: Stapler + 307: Camel + 308: Formula 1 + 309: Pomegranate + 310: Dishwasher + 311: Crab + 312: Hoverboard + 313: Meat ball + 314: Rice Cooker + 315: Tuba + 316: Calculator + 317: Papaya + 318: Antelope + 319: Parrot + 320: Seal + 321: Butterfly + 322: Dumbbell + 323: Donkey + 324: Lion + 325: Urinal + 326: Dolphin + 327: Electric Drill + 328: Hair Dryer + 329: Egg tart + 330: Jellyfish + 331: Treadmill + 332: Lighter + 333: Grapefruit + 334: Game board + 335: Mop + 336: Radish + 337: Baozi + 338: Target + 339: French + 340: Spring Rolls + 341: Monkey + 342: Rabbit + 343: Pencil Case + 344: Yak + 345: Red Cabbage + 346: Binoculars + 347: Asparagus + 348: Barbell + 349: Scallop + 350: Noddles + 351: Comb + 352: Dumpling + 353: Oyster + 354: Table Tennis paddle + 355: Cosmetics Brush/Eyeliner Pencil + 356: Chainsaw + 357: Eraser + 358: Lobster + 359: Durian + 360: Okra + 361: Lipstick + 362: Cosmetics Mirror + 363: Curling + 364: Table Tennis + +# Download script/URL (optional) --------------------------------------------------------------------------------------- +download: | + from tqdm import tqdm + + from ultralytics.utils.checks import check_requirements + from ultralytics.utils.downloads import download + from ultralytics.utils.ops import xyxy2xywhn + + import numpy as np + from pathlib import Path + + check_requirements(('pycocotools>=2.0',)) + from pycocotools.coco import COCO + + # Make Directories + dir = Path(yaml['path']) # dataset root dir + for p in 'images', 'labels': + (dir / p).mkdir(parents=True, exist_ok=True) + for q in 'train', 'val': + (dir / p / q).mkdir(parents=True, exist_ok=True) + + # Train, Val Splits + for split, patches in [('train', 50 + 1), ('val', 43 + 1)]: + print(f"Processing {split} in {patches} patches ...") + images, labels = dir / 'images' / split, dir / 'labels' / split + + # Download + url = f"https://dorc.ks3-cn-beijing.ksyun.com/data-set/2020Objects365%E6%95%B0%E6%8D%AE%E9%9B%86/{split}/" + if split == 'train': + download([f'{url}zhiyuan_objv2_{split}.tar.gz'], dir=dir) # annotations json + download([f'{url}patch{i}.tar.gz' for i in range(patches)], dir=images, curl=True, threads=8) + elif split == 'val': + download([f'{url}zhiyuan_objv2_{split}.json'], dir=dir) # annotations json + download([f'{url}images/v1/patch{i}.tar.gz' for i in range(15 + 1)], dir=images, curl=True, threads=8) + download([f'{url}images/v2/patch{i}.tar.gz' for i in range(16, patches)], dir=images, curl=True, threads=8) + + # Move + for f in tqdm(images.rglob('*.jpg'), desc=f'Moving {split} images'): + f.rename(images / f.name) # move to /images/{split} + + # Labels + coco = COCO(dir / f'zhiyuan_objv2_{split}.json') + names = [x["name"] for x in coco.loadCats(coco.getCatIds())] + for cid, cat in enumerate(names): + catIds = coco.getCatIds(catNms=[cat]) + imgIds = coco.getImgIds(catIds=catIds) + for im in tqdm(coco.loadImgs(imgIds), desc=f'Class {cid + 1}/{len(names)} {cat}'): + width, height = im["width"], im["height"] + path = Path(im["file_name"]) # image filename + try: + with open(labels / path.with_suffix('.txt').name, 'a') as file: + annIds = coco.getAnnIds(imgIds=im["id"], catIds=catIds, iscrowd=None) + for a in coco.loadAnns(annIds): + x, y, w, h = a['bbox'] # bounding box in xywh (xy top-left corner) + xyxy = np.array([x, y, x + w, y + h])[None] # pixels(1,4) + x, y, w, h = xyxy2xywhn(xyxy, w=width, h=height, clip=True)[0] # normalized and clipped + file.write(f"{cid} {x:.5f} {y:.5f} {w:.5f} {h:.5f}\n") + except Exception as e: + print(e) diff --git a/ultralytics/cfg/datasets/SKU-110K.yaml b/ultralytics/cfg/datasets/SKU-110K.yaml new file mode 100644 index 0000000..fff1baa --- /dev/null +++ b/ultralytics/cfg/datasets/SKU-110K.yaml @@ -0,0 +1,57 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# SKU-110K retail items dataset https://github.com/eg4000/SKU110K_CVPR19 by Trax Retail +# Documentation: https://docs.ultralytics.com/datasets/detect/sku-110k/ +# Example usage: yolo train data=SKU-110K.yaml +# parent +# ├── ultralytics +# └── datasets +# └── SKU-110K ← downloads here (13.6 GB) + +# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..] +path: ../datasets/SKU-110K # dataset root dir +train: train.txt # train images (relative to 'path') 8219 images +val: val.txt # val images (relative to 'path') 588 images +test: test.txt # test images (optional) 2936 images + +# Classes +names: + 0: object + +# Download script/URL (optional) --------------------------------------------------------------------------------------- +download: | + import shutil + from pathlib import Path + + import numpy as np + import pandas as pd + from tqdm import tqdm + + from ultralytics.utils.downloads import download + from ultralytics.utils.ops import xyxy2xywh + + # Download + dir = Path(yaml['path']) # dataset root dir + parent = Path(dir.parent) # download dir + urls = ['http://trax-geometry.s3.amazonaws.com/cvpr_challenge/SKU110K_fixed.tar.gz'] + download(urls, dir=parent) + + # Rename directories + if dir.exists(): + shutil.rmtree(dir) + (parent / 'SKU110K_fixed').rename(dir) # rename dir + (dir / 'labels').mkdir(parents=True, exist_ok=True) # create labels dir + + # Convert labels + names = 'image', 'x1', 'y1', 'x2', 'y2', 'class', 'image_width', 'image_height' # column names + for d in 'annotations_train.csv', 'annotations_val.csv', 'annotations_test.csv': + x = pd.read_csv(dir / 'annotations' / d, names=names).values # annotations + images, unique_images = x[:, 0], np.unique(x[:, 0]) + with open((dir / d).with_suffix('.txt').__str__().replace('annotations_', ''), 'w') as f: + f.writelines(f'./images/{s}\n' for s in unique_images) + for im in tqdm(unique_images, desc=f'Converting {dir / d}'): + cls = 0 # single-class dataset + with open((dir / 'labels' / im).with_suffix('.txt'), 'a') as f: + for r in x[images == im]: + w, h = r[6], r[7] # image width, height + xywh = xyxy2xywh(np.array([[r[1] / w, r[2] / h, r[3] / w, r[4] / h]]))[0] # instance + f.write(f"{cls} {xywh[0]:.5f} {xywh[1]:.5f} {xywh[2]:.5f} {xywh[3]:.5f}\n") # write label diff --git a/ultralytics/cfg/datasets/VOC.yaml b/ultralytics/cfg/datasets/VOC.yaml new file mode 100644 index 0000000..cd6d5ad --- /dev/null +++ b/ultralytics/cfg/datasets/VOC.yaml @@ -0,0 +1,99 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# PASCAL VOC dataset http://host.robots.ox.ac.uk/pascal/VOC by University of Oxford +# Documentation: # Documentation: https://docs.ultralytics.com/datasets/detect/voc/ +# Example usage: yolo train data=VOC.yaml +# parent +# ├── ultralytics +# └── datasets +# └── VOC ← downloads here (2.8 GB) + +# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..] +path: ../datasets/VOC +train: # train images (relative to 'path') 16551 images + - images/train2012 + - images/train2007 + - images/val2012 + - images/val2007 +val: # val images (relative to 'path') 4952 images + - images/test2007 +test: # test images (optional) + - images/test2007 + +# Classes +names: + 0: aeroplane + 1: bicycle + 2: bird + 3: boat + 4: bottle + 5: bus + 6: car + 7: cat + 8: chair + 9: cow + 10: diningtable + 11: dog + 12: horse + 13: motorbike + 14: person + 15: pottedplant + 16: sheep + 17: sofa + 18: train + 19: tvmonitor + +# Download script/URL (optional) --------------------------------------------------------------------------------------- +download: | + import xml.etree.ElementTree as ET + + from tqdm import tqdm + from ultralytics.utils.downloads import download + from pathlib import Path + + def convert_label(path, lb_path, year, image_id): + def convert_box(size, box): + dw, dh = 1. / size[0], 1. / size[1] + x, y, w, h = (box[0] + box[1]) / 2.0 - 1, (box[2] + box[3]) / 2.0 - 1, box[1] - box[0], box[3] - box[2] + return x * dw, y * dh, w * dw, h * dh + + in_file = open(path / f'VOC{year}/Annotations/{image_id}.xml') + out_file = open(lb_path, 'w') + tree = ET.parse(in_file) + root = tree.getroot() + size = root.find('size') + w = int(size.find('width').text) + h = int(size.find('height').text) + + names = list(yaml['names'].values()) # names list + for obj in root.iter('object'): + cls = obj.find('name').text + if cls in names and int(obj.find('difficult').text) != 1: + xmlbox = obj.find('bndbox') + bb = convert_box((w, h), [float(xmlbox.find(x).text) for x in ('xmin', 'xmax', 'ymin', 'ymax')]) + cls_id = names.index(cls) # class id + out_file.write(" ".join(str(a) for a in (cls_id, *bb)) + '\n') + + + # Download + dir = Path(yaml['path']) # dataset root dir + url = 'https://github.com/ultralytics/yolov5/releases/download/v1.0/' + urls = [f'{url}VOCtrainval_06-Nov-2007.zip', # 446MB, 5012 images + f'{url}VOCtest_06-Nov-2007.zip', # 438MB, 4953 images + f'{url}VOCtrainval_11-May-2012.zip'] # 1.95GB, 17126 images + download(urls, dir=dir / 'images', curl=True, threads=3, exist_ok=True) # download and unzip over existing paths (required) + + # Convert + path = dir / 'images/VOCdevkit' + for year, image_set in ('2012', 'train'), ('2012', 'val'), ('2007', 'train'), ('2007', 'val'), ('2007', 'test'): + imgs_path = dir / 'images' / f'{image_set}{year}' + lbs_path = dir / 'labels' / f'{image_set}{year}' + imgs_path.mkdir(exist_ok=True, parents=True) + lbs_path.mkdir(exist_ok=True, parents=True) + + with open(path / f'VOC{year}/ImageSets/Main/{image_set}.txt') as f: + image_ids = f.read().strip().split() + for id in tqdm(image_ids, desc=f'{image_set}{year}'): + f = path / f'VOC{year}/JPEGImages/{id}.jpg' # old img path + lb_path = (lbs_path / f.name).with_suffix('.txt') # new label path + f.rename(imgs_path / f.name) # move image + convert_label(path, lb_path, year, id) # convert labels to YOLO format diff --git a/ultralytics/cfg/datasets/VisDrone.yaml b/ultralytics/cfg/datasets/VisDrone.yaml new file mode 100644 index 0000000..773f0b0 --- /dev/null +++ b/ultralytics/cfg/datasets/VisDrone.yaml @@ -0,0 +1,72 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# VisDrone2019-DET dataset https://github.com/VisDrone/VisDrone-Dataset by Tianjin University +# Documentation: https://docs.ultralytics.com/datasets/detect/visdrone/ +# Example usage: yolo train data=VisDrone.yaml +# parent +# ├── ultralytics +# └── datasets +# └── VisDrone ← downloads here (2.3 GB) + +# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..] +path: ../datasets/VisDrone # dataset root dir +train: VisDrone2019-DET-train/images # train images (relative to 'path') 6471 images +val: VisDrone2019-DET-val/images # val images (relative to 'path') 548 images +test: VisDrone2019-DET-test-dev/images # test images (optional) 1610 images + +# Classes +names: + 0: pedestrian + 1: people + 2: bicycle + 3: car + 4: van + 5: truck + 6: tricycle + 7: awning-tricycle + 8: bus + 9: motor + +# Download script/URL (optional) --------------------------------------------------------------------------------------- +download: | + import os + from pathlib import Path + + from ultralytics.utils.downloads import download + + def visdrone2yolo(dir): + from PIL import Image + from tqdm import tqdm + + def convert_box(size, box): + # Convert VisDrone box to YOLO xywh box + dw = 1. / size[0] + dh = 1. / size[1] + return (box[0] + box[2] / 2) * dw, (box[1] + box[3] / 2) * dh, box[2] * dw, box[3] * dh + + (dir / 'labels').mkdir(parents=True, exist_ok=True) # make labels directory + pbar = tqdm((dir / 'annotations').glob('*.txt'), desc=f'Converting {dir}') + for f in pbar: + img_size = Image.open((dir / 'images' / f.name).with_suffix('.jpg')).size + lines = [] + with open(f, 'r') as file: # read annotation.txt + for row in [x.split(',') for x in file.read().strip().splitlines()]: + if row[4] == '0': # VisDrone 'ignored regions' class 0 + continue + cls = int(row[5]) - 1 + box = convert_box(img_size, tuple(map(int, row[:4]))) + lines.append(f"{cls} {' '.join(f'{x:.6f}' for x in box)}\n") + with open(str(f).replace(f'{os.sep}annotations{os.sep}', f'{os.sep}labels{os.sep}'), 'w') as fl: + fl.writelines(lines) # write label.txt + + + # Download + dir = Path(yaml['path']) # dataset root dir + urls = ['https://github.com/ultralytics/yolov5/releases/download/v1.0/VisDrone2019-DET-train.zip', + 'https://github.com/ultralytics/yolov5/releases/download/v1.0/VisDrone2019-DET-val.zip', + 'https://github.com/ultralytics/yolov5/releases/download/v1.0/VisDrone2019-DET-test-dev.zip', + 'https://github.com/ultralytics/yolov5/releases/download/v1.0/VisDrone2019-DET-test-challenge.zip'] + download(urls, dir=dir, curl=True, threads=4) + + # Convert + for d in 'VisDrone2019-DET-train', 'VisDrone2019-DET-val', 'VisDrone2019-DET-test-dev': + visdrone2yolo(dir / d) # convert VisDrone annotations to YOLO labels diff --git a/ultralytics/cfg/datasets/african-wildlife.yaml b/ultralytics/cfg/datasets/african-wildlife.yaml new file mode 100644 index 0000000..af8af36 --- /dev/null +++ b/ultralytics/cfg/datasets/african-wildlife.yaml @@ -0,0 +1,24 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# African-wildlife dataset by Ultralytics +# Documentation: https://docs.ultralytics.com/datasets/detect/african-wildlife/ +# Example usage: yolo train data=african-wildlife.yaml +# parent +# ├── ultralytics +# └── datasets +# └── african-wildlife ← downloads here (100 MB) + +# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..] +path: ../datasets/african-wildlife # dataset root dir +train: train/images # train images (relative to 'path') 1052 images +val: valid/images # val images (relative to 'path') 225 images +test: test/images # test images (relative to 'path') 227 images + +# Classes +names: + 0: buffalo + 1: elephant + 2: rhino + 3: zebra + +# Download script/URL (optional) +download: https://ultralytics.com/assets/african-wildlife.zip diff --git a/ultralytics/cfg/datasets/brain-tumor.yaml b/ultralytics/cfg/datasets/brain-tumor.yaml new file mode 100644 index 0000000..be61098 --- /dev/null +++ b/ultralytics/cfg/datasets/brain-tumor.yaml @@ -0,0 +1,22 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# Brain-tumor dataset by Ultralytics +# Documentation: https://docs.ultralytics.com/datasets/detect/brain-tumor/ +# Example usage: yolo train data=brain-tumor.yaml +# parent +# ├── ultralytics +# └── datasets +# └── brain-tumor ← downloads here (4.05 MB) + +# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..] +path: ../datasets/brain-tumor # dataset root dir +train: train/images # train images (relative to 'path') 893 images +val: valid/images # val images (relative to 'path') 223 images +test: # test images (relative to 'path') + +# Classes +names: + 0: negative + 1: positive + +# Download script/URL (optional) +download: https://ultralytics.com/assets/brain-tumor.zip diff --git a/ultralytics/cfg/datasets/carparts-seg.yaml b/ultralytics/cfg/datasets/carparts-seg.yaml new file mode 100644 index 0000000..a1c25ba --- /dev/null +++ b/ultralytics/cfg/datasets/carparts-seg.yaml @@ -0,0 +1,43 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# Carparts-seg dataset by Ultralytics +# Documentation: https://docs.ultralytics.com/datasets/segment/carparts-seg/ +# Example usage: yolo train data=carparts-seg.yaml +# parent +# ├── ultralytics +# └── datasets +# └── carparts-seg ← downloads here (132 MB) + +# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..] +path: ../datasets/carparts-seg # dataset root dir +train: train/images # train images (relative to 'path') 3516 images +val: valid/images # val images (relative to 'path') 276 images +test: test/images # test images (relative to 'path') 401 images + +# Classes +names: + 0: back_bumper + 1: back_door + 2: back_glass + 3: back_left_door + 4: back_left_light + 5: back_light + 6: back_right_door + 7: back_right_light + 8: front_bumper + 9: front_door + 10: front_glass + 11: front_left_door + 12: front_left_light + 13: front_light + 14: front_right_door + 15: front_right_light + 16: hood + 17: left_mirror + 18: object + 19: right_mirror + 20: tailgate + 21: trunk + 22: wheel + +# Download script/URL (optional) +download: https://ultralytics.com/assets/carparts-seg.zip diff --git a/ultralytics/cfg/datasets/coco-pose.yaml b/ultralytics/cfg/datasets/coco-pose.yaml new file mode 100644 index 0000000..b50b7a5 --- /dev/null +++ b/ultralytics/cfg/datasets/coco-pose.yaml @@ -0,0 +1,38 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# COCO 2017 dataset https://cocodataset.org by Microsoft +# Documentation: https://docs.ultralytics.com/datasets/pose/coco/ +# Example usage: yolo train data=coco-pose.yaml +# parent +# ├── ultralytics +# └── datasets +# └── coco-pose ← downloads here (20.1 GB) + +# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..] +path: ../datasets/coco-pose # dataset root dir +train: train2017.txt # train images (relative to 'path') 118287 images +val: val2017.txt # val images (relative to 'path') 5000 images +test: test-dev2017.txt # 20288 of 40670 images, submit to https://competitions.codalab.org/competitions/20794 + +# Keypoints +kpt_shape: [17, 3] # number of keypoints, number of dims (2 for x,y or 3 for x,y,visible) +flip_idx: [0, 2, 1, 4, 3, 6, 5, 8, 7, 10, 9, 12, 11, 14, 13, 16, 15] + +# Classes +names: + 0: person + +# Download script/URL (optional) +download: | + from ultralytics.utils.downloads import download + from pathlib import Path + + # Download labels + dir = Path(yaml['path']) # dataset root dir + url = 'https://github.com/ultralytics/yolov5/releases/download/v1.0/' + urls = [url + 'coco2017labels-pose.zip'] # labels + download(urls, dir=dir.parent) + # Download data + urls = ['http://images.cocodataset.org/zips/train2017.zip', # 19G, 118k images + 'http://images.cocodataset.org/zips/val2017.zip', # 1G, 5k images + 'http://images.cocodataset.org/zips/test2017.zip'] # 7G, 41k images (optional) + download(urls, dir=dir / 'images', threads=3) diff --git a/ultralytics/cfg/datasets/coco.yaml b/ultralytics/cfg/datasets/coco.yaml new file mode 100644 index 0000000..d0297f7 --- /dev/null +++ b/ultralytics/cfg/datasets/coco.yaml @@ -0,0 +1,114 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# COCO 2017 dataset https://cocodataset.org by Microsoft +# Documentation: https://docs.ultralytics.com/datasets/detect/coco/ +# Example usage: yolo train data=coco.yaml +# parent +# ├── ultralytics +# └── datasets +# └── coco ← downloads here (20.1 GB) + +# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..] +path: ../datasets/coco # dataset root dir +train: train2017.txt # train images (relative to 'path') 118287 images +val: val2017.txt # val images (relative to 'path') 5000 images +test: test-dev2017.txt # 20288 of 40670 images, submit to https://competitions.codalab.org/competitions/20794 + +# Classes +names: + 0: person + 1: bicycle + 2: car + 3: motorcycle + 4: airplane + 5: bus + 6: train + 7: truck + 8: boat + 9: traffic light + 10: fire hydrant + 11: stop sign + 12: parking meter + 13: bench + 14: bird + 15: cat + 16: dog + 17: horse + 18: sheep + 19: cow + 20: elephant + 21: bear + 22: zebra + 23: giraffe + 24: backpack + 25: umbrella + 26: handbag + 27: tie + 28: suitcase + 29: frisbee + 30: skis + 31: snowboard + 32: sports ball + 33: kite + 34: baseball bat + 35: baseball glove + 36: skateboard + 37: surfboard + 38: tennis racket + 39: bottle + 40: wine glass + 41: cup + 42: fork + 43: knife + 44: spoon + 45: bowl + 46: banana + 47: apple + 48: sandwich + 49: orange + 50: broccoli + 51: carrot + 52: hot dog + 53: pizza + 54: donut + 55: cake + 56: chair + 57: couch + 58: potted plant + 59: bed + 60: dining table + 61: toilet + 62: tv + 63: laptop + 64: mouse + 65: remote + 66: keyboard + 67: cell phone + 68: microwave + 69: oven + 70: toaster + 71: sink + 72: refrigerator + 73: book + 74: clock + 75: vase + 76: scissors + 77: teddy bear + 78: hair drier + 79: toothbrush + +# Download script/URL (optional) +download: | + from ultralytics.utils.downloads import download + from pathlib import Path + + # Download labels + segments = True # segment or box labels + dir = Path(yaml['path']) # dataset root dir + url = 'https://github.com/ultralytics/yolov5/releases/download/v1.0/' + urls = [url + ('coco2017labels-segments.zip' if segments else 'coco2017labels.zip')] # labels + download(urls, dir=dir.parent) + # Download data + urls = ['http://images.cocodataset.org/zips/train2017.zip', # 19G, 118k images + 'http://images.cocodataset.org/zips/val2017.zip', # 1G, 5k images + 'http://images.cocodataset.org/zips/test2017.zip'] # 7G, 41k images (optional) + download(urls, dir=dir / 'images', threads=3) diff --git a/ultralytics/cfg/datasets/coco128-seg.yaml b/ultralytics/cfg/datasets/coco128-seg.yaml new file mode 100644 index 0000000..e898a40 --- /dev/null +++ b/ultralytics/cfg/datasets/coco128-seg.yaml @@ -0,0 +1,100 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# COCO128-seg dataset https://www.kaggle.com/ultralytics/coco128 (first 128 images from COCO train2017) by Ultralytics +# Documentation: https://docs.ultralytics.com/datasets/segment/coco/ +# Example usage: yolo train data=coco128.yaml +# parent +# ├── ultralytics +# └── datasets +# └── coco128-seg ← downloads here (7 MB) + +# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..] +path: ../datasets/coco128-seg # dataset root dir +train: images/train2017 # train images (relative to 'path') 128 images +val: images/train2017 # val images (relative to 'path') 128 images +test: # test images (optional) + +# Classes +names: + 0: person + 1: bicycle + 2: car + 3: motorcycle + 4: airplane + 5: bus + 6: train + 7: truck + 8: boat + 9: traffic light + 10: fire hydrant + 11: stop sign + 12: parking meter + 13: bench + 14: bird + 15: cat + 16: dog + 17: horse + 18: sheep + 19: cow + 20: elephant + 21: bear + 22: zebra + 23: giraffe + 24: backpack + 25: umbrella + 26: handbag + 27: tie + 28: suitcase + 29: frisbee + 30: skis + 31: snowboard + 32: sports ball + 33: kite + 34: baseball bat + 35: baseball glove + 36: skateboard + 37: surfboard + 38: tennis racket + 39: bottle + 40: wine glass + 41: cup + 42: fork + 43: knife + 44: spoon + 45: bowl + 46: banana + 47: apple + 48: sandwich + 49: orange + 50: broccoli + 51: carrot + 52: hot dog + 53: pizza + 54: donut + 55: cake + 56: chair + 57: couch + 58: potted plant + 59: bed + 60: dining table + 61: toilet + 62: tv + 63: laptop + 64: mouse + 65: remote + 66: keyboard + 67: cell phone + 68: microwave + 69: oven + 70: toaster + 71: sink + 72: refrigerator + 73: book + 74: clock + 75: vase + 76: scissors + 77: teddy bear + 78: hair drier + 79: toothbrush + +# Download script/URL (optional) +download: https://ultralytics.com/assets/coco128-seg.zip diff --git a/ultralytics/cfg/datasets/coco128.yaml b/ultralytics/cfg/datasets/coco128.yaml new file mode 100644 index 0000000..8d47ee0 --- /dev/null +++ b/ultralytics/cfg/datasets/coco128.yaml @@ -0,0 +1,100 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# COCO128 dataset https://www.kaggle.com/ultralytics/coco128 (first 128 images from COCO train2017) by Ultralytics +# Documentation: https://docs.ultralytics.com/datasets/detect/coco/ +# Example usage: yolo train data=coco128.yaml +# parent +# ├── ultralytics +# └── datasets +# └── coco128 ← downloads here (7 MB) + +# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..] +path: ../datasets/coco128 # dataset root dir +train: images/train2017 # train images (relative to 'path') 128 images +val: images/train2017 # val images (relative to 'path') 128 images +test: # test images (optional) + +# Classes +names: + 0: person + 1: bicycle + 2: car + 3: motorcycle + 4: airplane + 5: bus + 6: train + 7: truck + 8: boat + 9: traffic light + 10: fire hydrant + 11: stop sign + 12: parking meter + 13: bench + 14: bird + 15: cat + 16: dog + 17: horse + 18: sheep + 19: cow + 20: elephant + 21: bear + 22: zebra + 23: giraffe + 24: backpack + 25: umbrella + 26: handbag + 27: tie + 28: suitcase + 29: frisbee + 30: skis + 31: snowboard + 32: sports ball + 33: kite + 34: baseball bat + 35: baseball glove + 36: skateboard + 37: surfboard + 38: tennis racket + 39: bottle + 40: wine glass + 41: cup + 42: fork + 43: knife + 44: spoon + 45: bowl + 46: banana + 47: apple + 48: sandwich + 49: orange + 50: broccoli + 51: carrot + 52: hot dog + 53: pizza + 54: donut + 55: cake + 56: chair + 57: couch + 58: potted plant + 59: bed + 60: dining table + 61: toilet + 62: tv + 63: laptop + 64: mouse + 65: remote + 66: keyboard + 67: cell phone + 68: microwave + 69: oven + 70: toaster + 71: sink + 72: refrigerator + 73: book + 74: clock + 75: vase + 76: scissors + 77: teddy bear + 78: hair drier + 79: toothbrush + +# Download script/URL (optional) +download: https://ultralytics.com/assets/coco128.zip diff --git a/ultralytics/cfg/datasets/coco8-pose.yaml b/ultralytics/cfg/datasets/coco8-pose.yaml new file mode 100644 index 0000000..4dee5be --- /dev/null +++ b/ultralytics/cfg/datasets/coco8-pose.yaml @@ -0,0 +1,25 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# COCO8-pose dataset (first 8 images from COCO train2017) by Ultralytics +# Documentation: https://docs.ultralytics.com/datasets/pose/coco8-pose/ +# Example usage: yolo train data=coco8-pose.yaml +# parent +# ├── ultralytics +# └── datasets +# └── coco8-pose ← downloads here (1 MB) + +# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..] +path: ../datasets/coco8-pose # dataset root dir +train: images/train # train images (relative to 'path') 4 images +val: images/val # val images (relative to 'path') 4 images +test: # test images (optional) + +# Keypoints +kpt_shape: [17, 3] # number of keypoints, number of dims (2 for x,y or 3 for x,y,visible) +flip_idx: [0, 2, 1, 4, 3, 6, 5, 8, 7, 10, 9, 12, 11, 14, 13, 16, 15] + +# Classes +names: + 0: person + +# Download script/URL (optional) +download: https://ultralytics.com/assets/coco8-pose.zip diff --git a/ultralytics/cfg/datasets/coco8-seg.yaml b/ultralytics/cfg/datasets/coco8-seg.yaml new file mode 100644 index 0000000..d8b6ed2 --- /dev/null +++ b/ultralytics/cfg/datasets/coco8-seg.yaml @@ -0,0 +1,100 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# COCO8-seg dataset (first 8 images from COCO train2017) by Ultralytics +# Documentation: https://docs.ultralytics.com/datasets/segment/coco8-seg/ +# Example usage: yolo train data=coco8-seg.yaml +# parent +# ├── ultralytics +# └── datasets +# └── coco8-seg ← downloads here (1 MB) + +# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..] +path: ../datasets/coco8-seg # dataset root dir +train: images/train # train images (relative to 'path') 4 images +val: images/val # val images (relative to 'path') 4 images +test: # test images (optional) + +# Classes +names: + 0: person + 1: bicycle + 2: car + 3: motorcycle + 4: airplane + 5: bus + 6: train + 7: truck + 8: boat + 9: traffic light + 10: fire hydrant + 11: stop sign + 12: parking meter + 13: bench + 14: bird + 15: cat + 16: dog + 17: horse + 18: sheep + 19: cow + 20: elephant + 21: bear + 22: zebra + 23: giraffe + 24: backpack + 25: umbrella + 26: handbag + 27: tie + 28: suitcase + 29: frisbee + 30: skis + 31: snowboard + 32: sports ball + 33: kite + 34: baseball bat + 35: baseball glove + 36: skateboard + 37: surfboard + 38: tennis racket + 39: bottle + 40: wine glass + 41: cup + 42: fork + 43: knife + 44: spoon + 45: bowl + 46: banana + 47: apple + 48: sandwich + 49: orange + 50: broccoli + 51: carrot + 52: hot dog + 53: pizza + 54: donut + 55: cake + 56: chair + 57: couch + 58: potted plant + 59: bed + 60: dining table + 61: toilet + 62: tv + 63: laptop + 64: mouse + 65: remote + 66: keyboard + 67: cell phone + 68: microwave + 69: oven + 70: toaster + 71: sink + 72: refrigerator + 73: book + 74: clock + 75: vase + 76: scissors + 77: teddy bear + 78: hair drier + 79: toothbrush + +# Download script/URL (optional) +download: https://ultralytics.com/assets/coco8-seg.zip diff --git a/ultralytics/cfg/datasets/coco8.yaml b/ultralytics/cfg/datasets/coco8.yaml new file mode 100644 index 0000000..2925f81 --- /dev/null +++ b/ultralytics/cfg/datasets/coco8.yaml @@ -0,0 +1,100 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# COCO8 dataset (first 8 images from COCO train2017) by Ultralytics +# Documentation: https://docs.ultralytics.com/datasets/detect/coco8/ +# Example usage: yolo train data=coco8.yaml +# parent +# ├── ultralytics +# └── datasets +# └── coco8 ← downloads here (1 MB) + +# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..] +path: ../datasets/coco8 # dataset root dir +train: images/train # train images (relative to 'path') 4 images +val: images/val # val images (relative to 'path') 4 images +test: # test images (optional) + +# Classes +names: + 0: person + 1: bicycle + 2: car + 3: motorcycle + 4: airplane + 5: bus + 6: train + 7: truck + 8: boat + 9: traffic light + 10: fire hydrant + 11: stop sign + 12: parking meter + 13: bench + 14: bird + 15: cat + 16: dog + 17: horse + 18: sheep + 19: cow + 20: elephant + 21: bear + 22: zebra + 23: giraffe + 24: backpack + 25: umbrella + 26: handbag + 27: tie + 28: suitcase + 29: frisbee + 30: skis + 31: snowboard + 32: sports ball + 33: kite + 34: baseball bat + 35: baseball glove + 36: skateboard + 37: surfboard + 38: tennis racket + 39: bottle + 40: wine glass + 41: cup + 42: fork + 43: knife + 44: spoon + 45: bowl + 46: banana + 47: apple + 48: sandwich + 49: orange + 50: broccoli + 51: carrot + 52: hot dog + 53: pizza + 54: donut + 55: cake + 56: chair + 57: couch + 58: potted plant + 59: bed + 60: dining table + 61: toilet + 62: tv + 63: laptop + 64: mouse + 65: remote + 66: keyboard + 67: cell phone + 68: microwave + 69: oven + 70: toaster + 71: sink + 72: refrigerator + 73: book + 74: clock + 75: vase + 76: scissors + 77: teddy bear + 78: hair drier + 79: toothbrush + +# Download script/URL (optional) +download: https://ultralytics.com/assets/coco8.zip diff --git a/ultralytics/cfg/datasets/crack-seg.yaml b/ultralytics/cfg/datasets/crack-seg.yaml new file mode 100644 index 0000000..2054f62 --- /dev/null +++ b/ultralytics/cfg/datasets/crack-seg.yaml @@ -0,0 +1,21 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# Crack-seg dataset by Ultralytics +# Documentation: https://docs.ultralytics.com/datasets/segment/crack-seg/ +# Example usage: yolo train data=crack-seg.yaml +# parent +# ├── ultralytics +# └── datasets +# └── crack-seg ← downloads here (91.2 MB) + +# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..] +path: ../datasets/crack-seg # dataset root dir +train: train/images # train images (relative to 'path') 3717 images +val: valid/images # val images (relative to 'path') 112 images +test: test/images # test images (relative to 'path') 200 images + +# Classes +names: + 0: crack + +# Download script/URL (optional) +download: https://ultralytics.com/assets/crack-seg.zip diff --git a/ultralytics/cfg/datasets/dota8.yaml b/ultralytics/cfg/datasets/dota8.yaml new file mode 100644 index 0000000..f58b501 --- /dev/null +++ b/ultralytics/cfg/datasets/dota8.yaml @@ -0,0 +1,34 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# DOTA8 dataset 8 images from split DOTAv1 dataset by Ultralytics +# Documentation: https://docs.ultralytics.com/datasets/obb/dota8/ +# Example usage: yolo train model=yolov8n-obb.pt data=dota8.yaml +# parent +# ├── ultralytics +# └── datasets +# └── dota8 ← downloads here (1MB) + +# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..] +path: ../datasets/dota8 # dataset root dir +train: images/train # train images (relative to 'path') 4 images +val: images/val # val images (relative to 'path') 4 images + +# Classes for DOTA 1.0 +names: + 0: plane + 1: ship + 2: storage tank + 3: baseball diamond + 4: tennis court + 5: basketball court + 6: ground track field + 7: harbor + 8: bridge + 9: large vehicle + 10: small vehicle + 11: helicopter + 12: roundabout + 13: soccer ball field + 14: swimming pool + +# Download script/URL (optional) +download: https://github.com/ultralytics/yolov5/releases/download/v1.0/dota8.zip diff --git a/ultralytics/cfg/datasets/lvis.yaml b/ultralytics/cfg/datasets/lvis.yaml new file mode 100644 index 0000000..98149ed --- /dev/null +++ b/ultralytics/cfg/datasets/lvis.yaml @@ -0,0 +1,1239 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# LVIS dataset http://www.lvisdataset.org by Facebook AI Research. +# Documentation: https://docs.ultralytics.com/datasets/detect/lvis/ +# Example usage: yolo train data=lvis.yaml +# parent +# ├── ultralytics +# └── datasets +# └── lvis ← downloads here (20.1 GB) + +# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..] +path: ../datasets/lvis # dataset root dir +train: train.txt # train images (relative to 'path') 100170 images +val: val.txt # val images (relative to 'path') 19809 images +minival: minival.txt # minval images (relative to 'path') 5000 images + +names: + 0: aerosol can/spray can + 1: air conditioner + 2: airplane/aeroplane + 3: alarm clock + 4: alcohol/alcoholic beverage + 5: alligator/gator + 6: almond + 7: ambulance + 8: amplifier + 9: anklet/ankle bracelet + 10: antenna/aerial/transmitting aerial + 11: apple + 12: applesauce + 13: apricot + 14: apron + 15: aquarium/fish tank + 16: arctic/arctic type of shoe/galosh/golosh/rubber/rubber type of shoe/gumshoe + 17: armband + 18: armchair + 19: armoire + 20: armor/armour + 21: artichoke + 22: trash can/garbage can/wastebin/dustbin/trash barrel/trash bin + 23: ashtray + 24: asparagus + 25: atomizer/atomiser/spray/sprayer/nebulizer/nebuliser + 26: avocado + 27: award/accolade + 28: awning + 29: ax/axe + 30: baboon + 31: baby buggy/baby carriage/perambulator/pram/stroller + 32: basketball backboard + 33: backpack/knapsack/packsack/rucksack/haversack + 34: handbag/purse/pocketbook + 35: suitcase/baggage/luggage + 36: bagel/beigel + 37: bagpipe + 38: baguet/baguette + 39: bait/lure + 40: ball + 41: ballet skirt/tutu + 42: balloon + 43: bamboo + 44: banana + 45: Band Aid + 46: bandage + 47: bandanna/bandana + 48: banjo + 49: banner/streamer + 50: barbell + 51: barge + 52: barrel/cask + 53: barrette + 54: barrow/garden cart/lawn cart/wheelbarrow + 55: baseball base + 56: baseball + 57: baseball bat + 58: baseball cap/jockey cap/golf cap + 59: baseball glove/baseball mitt + 60: basket/handbasket + 61: basketball + 62: bass horn/sousaphone/tuba + 63: bat/bat animal + 64: bath mat + 65: bath towel + 66: bathrobe + 67: bathtub/bathing tub + 68: batter/batter food + 69: battery + 70: beachball + 71: bead + 72: bean curd/tofu + 73: beanbag + 74: beanie/beany + 75: bear + 76: bed + 77: bedpan + 78: bedspread/bedcover/bed covering/counterpane/spread + 79: cow + 80: beef/beef food/boeuf/boeuf food + 81: beeper/pager + 82: beer bottle + 83: beer can + 84: beetle + 85: bell + 86: bell pepper/capsicum + 87: belt + 88: belt buckle + 89: bench + 90: beret + 91: bib + 92: Bible + 93: bicycle/bike/bike bicycle + 94: visor/vizor + 95: billboard + 96: binder/ring-binder + 97: binoculars/field glasses/opera glasses + 98: bird + 99: birdfeeder + 100: birdbath + 101: birdcage + 102: birdhouse + 103: birthday cake + 104: birthday card + 105: pirate flag + 106: black sheep + 107: blackberry + 108: blackboard/chalkboard + 109: blanket + 110: blazer/sport jacket/sport coat/sports jacket/sports coat + 111: blender/liquidizer/liquidiser + 112: blimp + 113: blinker/flasher + 114: blouse + 115: blueberry + 116: gameboard + 117: boat/ship/ship boat + 118: bob/bobber/bobfloat + 119: bobbin/spool/reel + 120: bobby pin/hairgrip + 121: boiled egg/coddled egg + 122: bolo tie/bolo/bola tie/bola + 123: deadbolt + 124: bolt + 125: bonnet + 126: book + 127: bookcase + 128: booklet/brochure/leaflet/pamphlet + 129: bookmark/bookmarker + 130: boom microphone/microphone boom + 131: boot + 132: bottle + 133: bottle opener + 134: bouquet + 135: bow/bow weapon + 136: bow/bow decorative ribbons + 137: bow-tie/bowtie + 138: bowl + 139: pipe bowl + 140: bowler hat/bowler/derby hat/derby/plug hat + 141: bowling ball + 142: box + 143: boxing glove + 144: suspenders + 145: bracelet/bangle + 146: brass plaque + 147: brassiere/bra/bandeau + 148: bread-bin/breadbox + 149: bread + 150: breechcloth/breechclout/loincloth + 151: bridal gown/wedding gown/wedding dress + 152: briefcase + 153: broccoli + 154: broach + 155: broom + 156: brownie + 157: brussels sprouts + 158: bubble gum + 159: bucket/pail + 160: horse buggy + 161: horned cow + 162: bulldog + 163: bulldozer/dozer + 164: bullet train + 165: bulletin board/notice board + 166: bulletproof vest + 167: bullhorn/megaphone + 168: bun/roll + 169: bunk bed + 170: buoy + 171: burrito + 172: bus/bus vehicle/autobus/charabanc/double-decker/motorbus/motorcoach + 173: business card + 174: butter + 175: butterfly + 176: button + 177: cab/cab taxi/taxi/taxicab + 178: cabana + 179: cabin car/caboose + 180: cabinet + 181: locker/storage locker + 182: cake + 183: calculator + 184: calendar + 185: calf + 186: camcorder + 187: camel + 188: camera + 189: camera lens + 190: camper/camper vehicle/camping bus/motor home + 191: can/tin can + 192: can opener/tin opener + 193: candle/candlestick + 194: candle holder + 195: candy bar + 196: candy cane + 197: walking cane + 198: canister/canister + 199: canoe + 200: cantaloup/cantaloupe + 201: canteen + 202: cap/cap headwear + 203: bottle cap/cap/cap container lid + 204: cape + 205: cappuccino/coffee cappuccino + 206: car/car automobile/auto/auto automobile/automobile + 207: railcar/railcar part of a train/railway car/railway car part of a train/railroad + car/railroad car part of a train + 208: elevator car + 209: car battery/automobile battery + 210: identity card + 211: card + 212: cardigan + 213: cargo ship/cargo vessel + 214: carnation + 215: horse carriage + 216: carrot + 217: tote bag + 218: cart + 219: carton + 220: cash register/register/register for cash transactions + 221: casserole + 222: cassette + 223: cast/plaster cast/plaster bandage + 224: cat + 225: cauliflower + 226: cayenne/cayenne spice/cayenne pepper/cayenne pepper spice/red pepper/red pepper + spice + 227: CD player + 228: celery + 229: cellular telephone/cellular phone/cellphone/mobile phone/smart phone + 230: chain mail/ring mail/chain armor/chain armour/ring armor/ring armour + 231: chair + 232: chaise longue/chaise/daybed + 233: chalice + 234: chandelier + 235: chap + 236: checkbook/chequebook + 237: checkerboard + 238: cherry + 239: chessboard + 240: chicken/chicken animal + 241: chickpea/garbanzo + 242: chili/chili vegetable/chili pepper/chili pepper vegetable/chilli/chilli vegetable/chilly/chilly + vegetable/chile/chile vegetable + 243: chime/gong + 244: chinaware + 245: crisp/crisp potato chip/potato chip + 246: poker chip + 247: chocolate bar + 248: chocolate cake + 249: chocolate milk + 250: chocolate mousse + 251: choker/collar/neckband + 252: chopping board/cutting board/chopping block + 253: chopstick + 254: Christmas tree + 255: slide + 256: cider/cyder + 257: cigar box + 258: cigarette + 259: cigarette case/cigarette pack + 260: cistern/water tank + 261: clarinet + 262: clasp + 263: cleansing agent/cleanser/cleaner + 264: cleat/cleat for securing rope + 265: clementine + 266: clip + 267: clipboard + 268: clippers/clippers for plants + 269: cloak + 270: clock/timepiece/timekeeper + 271: clock tower + 272: clothes hamper/laundry basket/clothes basket + 273: clothespin/clothes peg + 274: clutch bag + 275: coaster + 276: coat + 277: coat hanger/clothes hanger/dress hanger + 278: coatrack/hatrack + 279: cock/rooster + 280: cockroach + 281: cocoa/cocoa beverage/hot chocolate/hot chocolate beverage/drinking chocolate + 282: coconut/cocoanut + 283: coffee maker/coffee machine + 284: coffee table/cocktail table + 285: coffeepot + 286: coil + 287: coin + 288: colander/cullender + 289: coleslaw/slaw + 290: coloring material/colouring material + 291: combination lock + 292: pacifier/teething ring + 293: comic book + 294: compass + 295: computer keyboard/keyboard/keyboard computer + 296: condiment + 297: cone/traffic cone + 298: control/controller + 299: convertible/convertible automobile + 300: sofa bed + 301: cooker + 302: cookie/cooky/biscuit/biscuit cookie + 303: cooking utensil + 304: cooler/cooler for food/ice chest + 305: cork/cork bottle plug/bottle cork + 306: corkboard + 307: corkscrew/bottle screw + 308: edible corn/corn/maize + 309: cornbread + 310: cornet/horn/trumpet + 311: cornice/valance/valance board/pelmet + 312: cornmeal + 313: corset/girdle + 314: costume + 315: cougar/puma/catamount/mountain lion/panther + 316: coverall + 317: cowbell + 318: cowboy hat/ten-gallon hat + 319: crab/crab animal + 320: crabmeat + 321: cracker + 322: crape/crepe/French pancake + 323: crate + 324: crayon/wax crayon + 325: cream pitcher + 326: crescent roll/croissant + 327: crib/cot + 328: crock pot/earthenware jar + 329: crossbar + 330: crouton + 331: crow + 332: crowbar/wrecking bar/pry bar + 333: crown + 334: crucifix + 335: cruise ship/cruise liner + 336: police cruiser/patrol car/police car/squad car + 337: crumb + 338: crutch + 339: cub/cub animal + 340: cube/square block + 341: cucumber/cuke + 342: cufflink + 343: cup + 344: trophy cup + 345: cupboard/closet + 346: cupcake + 347: hair curler/hair roller/hair crimper + 348: curling iron + 349: curtain/drapery + 350: cushion + 351: cylinder + 352: cymbal + 353: dagger + 354: dalmatian + 355: dartboard + 356: date/date fruit + 357: deck chair/beach chair + 358: deer/cervid + 359: dental floss/floss + 360: desk + 361: detergent + 362: diaper + 363: diary/journal + 364: die/dice + 365: dinghy/dory/rowboat + 366: dining table + 367: tux/tuxedo + 368: dish + 369: dish antenna + 370: dishrag/dishcloth + 371: dishtowel/tea towel + 372: dishwasher/dishwashing machine + 373: dishwasher detergent/dishwashing detergent/dishwashing liquid/dishsoap + 374: dispenser + 375: diving board + 376: Dixie cup/paper cup + 377: dog + 378: dog collar + 379: doll + 380: dollar/dollar bill/one dollar bill + 381: dollhouse/doll's house + 382: dolphin + 383: domestic ass/donkey + 384: doorknob/doorhandle + 385: doormat/welcome mat + 386: doughnut/donut + 387: dove + 388: dragonfly + 389: drawer + 390: underdrawers/boxers/boxershorts + 391: dress/frock + 392: dress hat/high hat/opera hat/silk hat/top hat + 393: dress suit + 394: dresser + 395: drill + 396: drone + 397: dropper/eye dropper + 398: drum/drum musical instrument + 399: drumstick + 400: duck + 401: duckling + 402: duct tape + 403: duffel bag/duffle bag/duffel/duffle + 404: dumbbell + 405: dumpster + 406: dustpan + 407: eagle + 408: earphone/earpiece/headphone + 409: earplug + 410: earring + 411: easel + 412: eclair + 413: eel + 414: egg/eggs + 415: egg roll/spring roll + 416: egg yolk/yolk/yolk egg + 417: eggbeater/eggwhisk + 418: eggplant/aubergine + 419: electric chair + 420: refrigerator + 421: elephant + 422: elk/moose + 423: envelope + 424: eraser + 425: escargot + 426: eyepatch + 427: falcon + 428: fan + 429: faucet/spigot/tap + 430: fedora + 431: ferret + 432: Ferris wheel + 433: ferry/ferryboat + 434: fig/fig fruit + 435: fighter jet/fighter aircraft/attack aircraft + 436: figurine + 437: file cabinet/filing cabinet + 438: file/file tool + 439: fire alarm/smoke alarm + 440: fire engine/fire truck + 441: fire extinguisher/extinguisher + 442: fire hose + 443: fireplace + 444: fireplug/fire hydrant/hydrant + 445: first-aid kit + 446: fish + 447: fish/fish food + 448: fishbowl/goldfish bowl + 449: fishing rod/fishing pole + 450: flag + 451: flagpole/flagstaff + 452: flamingo + 453: flannel + 454: flap + 455: flash/flashbulb + 456: flashlight/torch + 457: fleece + 458: flip-flop/flip-flop sandal + 459: flipper/flipper footwear/fin/fin footwear + 460: flower arrangement/floral arrangement + 461: flute glass/champagne flute + 462: foal + 463: folding chair + 464: food processor + 465: football/football American + 466: football helmet + 467: footstool/footrest + 468: fork + 469: forklift + 470: freight car + 471: French toast + 472: freshener/air freshener + 473: frisbee + 474: frog/toad/toad frog + 475: fruit juice + 476: frying pan/frypan/skillet + 477: fudge + 478: funnel + 479: futon + 480: gag/muzzle + 481: garbage + 482: garbage truck + 483: garden hose + 484: gargle/mouthwash + 485: gargoyle + 486: garlic/ail + 487: gasmask/respirator/gas helmet + 488: gazelle + 489: gelatin/jelly + 490: gemstone + 491: generator + 492: giant panda/panda/panda bear + 493: gift wrap + 494: ginger/gingerroot + 495: giraffe + 496: cincture/sash/waistband/waistcloth + 497: glass/glass drink container/drinking glass + 498: globe + 499: glove + 500: goat + 501: goggles + 502: goldfish + 503: golf club/golf-club + 504: golfcart + 505: gondola/gondola boat + 506: goose + 507: gorilla + 508: gourd + 509: grape + 510: grater + 511: gravestone/headstone/tombstone + 512: gravy boat/gravy holder + 513: green bean + 514: green onion/spring onion/scallion + 515: griddle + 516: grill/grille/grillwork/radiator grille + 517: grits/hominy grits + 518: grizzly/grizzly bear + 519: grocery bag + 520: guitar + 521: gull/seagull + 522: gun + 523: hairbrush + 524: hairnet + 525: hairpin + 526: halter top + 527: ham/jambon/gammon + 528: hamburger/beefburger/burger + 529: hammer + 530: hammock + 531: hamper + 532: hamster + 533: hair dryer + 534: hand glass/hand mirror + 535: hand towel/face towel + 536: handcart/pushcart/hand truck + 537: handcuff + 538: handkerchief + 539: handle/grip/handgrip + 540: handsaw/carpenter's saw + 541: hardback book/hardcover book + 542: harmonium/organ/organ musical instrument/reed organ/reed organ musical instrument + 543: hat + 544: hatbox + 545: veil + 546: headband + 547: headboard + 548: headlight/headlamp + 549: headscarf + 550: headset + 551: headstall/headstall for horses/headpiece/headpiece for horses + 552: heart + 553: heater/warmer + 554: helicopter + 555: helmet + 556: heron + 557: highchair/feeding chair + 558: hinge + 559: hippopotamus + 560: hockey stick + 561: hog/pig + 562: home plate/home plate baseball/home base/home base baseball + 563: honey + 564: fume hood/exhaust hood + 565: hook + 566: hookah/narghile/nargileh/sheesha/shisha/water pipe + 567: hornet + 568: horse + 569: hose/hosepipe + 570: hot-air balloon + 571: hotplate + 572: hot sauce + 573: hourglass + 574: houseboat + 575: hummingbird + 576: hummus/humus/hommos/hoummos/humous + 577: polar bear + 578: icecream + 579: popsicle + 580: ice maker + 581: ice pack/ice bag + 582: ice skate + 583: igniter/ignitor/lighter + 584: inhaler/inhalator + 585: iPod + 586: iron/iron for clothing/smoothing iron/smoothing iron for clothing + 587: ironing board + 588: jacket + 589: jam + 590: jar + 591: jean/blue jean/denim + 592: jeep/landrover + 593: jelly bean/jelly egg + 594: jersey/T-shirt/tee shirt + 595: jet plane/jet-propelled plane + 596: jewel/gem/precious stone + 597: jewelry/jewellery + 598: joystick + 599: jumpsuit + 600: kayak + 601: keg + 602: kennel/doghouse + 603: kettle/boiler + 604: key + 605: keycard + 606: kilt + 607: kimono + 608: kitchen sink + 609: kitchen table + 610: kite + 611: kitten/kitty + 612: kiwi fruit + 613: knee pad + 614: knife + 615: knitting needle + 616: knob + 617: knocker/knocker on a door/doorknocker + 618: koala/koala bear + 619: lab coat/laboratory coat + 620: ladder + 621: ladle + 622: ladybug/ladybeetle/ladybird beetle + 623: lamb/lamb animal + 624: lamb-chop/lambchop + 625: lamp + 626: lamppost + 627: lampshade + 628: lantern + 629: lanyard/laniard + 630: laptop computer/notebook computer + 631: lasagna/lasagne + 632: latch + 633: lawn mower + 634: leather + 635: legging/legging clothing/leging/leging clothing/leg covering + 636: Lego/Lego set + 637: legume + 638: lemon + 639: lemonade + 640: lettuce + 641: license plate/numberplate + 642: life buoy/lifesaver/life belt/life ring + 643: life jacket/life vest + 644: lightbulb + 645: lightning rod/lightning conductor + 646: lime + 647: limousine + 648: lion + 649: lip balm + 650: liquor/spirits/hard liquor/liqueur/cordial + 651: lizard + 652: log + 653: lollipop + 654: speaker/speaker stereo equipment + 655: loveseat + 656: machine gun + 657: magazine + 658: magnet + 659: mail slot + 660: mailbox/mailbox at home/letter box/letter box at home + 661: mallard + 662: mallet + 663: mammoth + 664: manatee + 665: mandarin orange + 666: manager/through + 667: manhole + 668: map + 669: marker + 670: martini + 671: mascot + 672: mashed potato + 673: masher + 674: mask/facemask + 675: mast + 676: mat/mat gym equipment/gym mat + 677: matchbox + 678: mattress + 679: measuring cup + 680: measuring stick/ruler/ruler measuring stick/measuring rod + 681: meatball + 682: medicine + 683: melon + 684: microphone + 685: microscope + 686: microwave oven + 687: milestone/milepost + 688: milk + 689: milk can + 690: milkshake + 691: minivan + 692: mint candy + 693: mirror + 694: mitten + 695: mixer/mixer kitchen tool/stand mixer + 696: money + 697: monitor/monitor computer equipment + 698: monkey + 699: motor + 700: motor scooter/scooter + 701: motor vehicle/automotive vehicle + 702: motorcycle + 703: mound/mound baseball/pitcher's mound + 704: mouse/mouse computer equipment/computer mouse + 705: mousepad + 706: muffin + 707: mug + 708: mushroom + 709: music stool/piano stool + 710: musical instrument/instrument/instrument musical + 711: nailfile + 712: napkin/table napkin/serviette + 713: neckerchief + 714: necklace + 715: necktie/tie/tie necktie + 716: needle + 717: nest + 718: newspaper/paper/paper newspaper + 719: newsstand + 720: nightshirt/nightwear/sleepwear/nightclothes + 721: nosebag/nosebag for animals/feedbag + 722: noseband/noseband for animals/nosepiece/nosepiece for animals + 723: notebook + 724: notepad + 725: nut + 726: nutcracker + 727: oar + 728: octopus/octopus food + 729: octopus/octopus animal + 730: oil lamp/kerosene lamp/kerosine lamp + 731: olive oil + 732: omelet/omelette + 733: onion + 734: orange/orange fruit + 735: orange juice + 736: ostrich + 737: ottoman/pouf/pouffe/hassock + 738: oven + 739: overalls/overalls clothing + 740: owl + 741: packet + 742: inkpad/inking pad/stamp pad + 743: pad + 744: paddle/boat paddle + 745: padlock + 746: paintbrush + 747: painting + 748: pajamas/pyjamas + 749: palette/pallet + 750: pan/pan for cooking/cooking pan + 751: pan/pan metal container + 752: pancake + 753: pantyhose + 754: papaya + 755: paper plate + 756: paper towel + 757: paperback book/paper-back book/softback book/soft-cover book + 758: paperweight + 759: parachute + 760: parakeet/parrakeet/parroket/paraquet/paroquet/parroquet + 761: parasail/parasail sports + 762: parasol/sunshade + 763: parchment + 764: parka/anorak + 765: parking meter + 766: parrot + 767: passenger car/passenger car part of a train/coach/coach part of a train + 768: passenger ship + 769: passport + 770: pastry + 771: patty/patty food + 772: pea/pea food + 773: peach + 774: peanut butter + 775: pear + 776: peeler/peeler tool for fruit and vegetables + 777: wooden leg/pegleg + 778: pegboard + 779: pelican + 780: pen + 781: pencil + 782: pencil box/pencil case + 783: pencil sharpener + 784: pendulum + 785: penguin + 786: pennant + 787: penny/penny coin + 788: pepper/peppercorn + 789: pepper mill/pepper grinder + 790: perfume + 791: persimmon + 792: person/baby/child/boy/girl/man/woman/human + 793: pet + 794: pew/pew church bench/church bench + 795: phonebook/telephone book/telephone directory + 796: phonograph record/phonograph recording/record/record phonograph recording + 797: piano + 798: pickle + 799: pickup truck + 800: pie + 801: pigeon + 802: piggy bank/penny bank + 803: pillow + 804: pin/pin non jewelry + 805: pineapple + 806: pinecone + 807: ping-pong ball + 808: pinwheel + 809: tobacco pipe + 810: pipe/piping + 811: pistol/handgun + 812: pita/pita bread/pocket bread + 813: pitcher/pitcher vessel for liquid/ewer + 814: pitchfork + 815: pizza + 816: place mat + 817: plate + 818: platter + 819: playpen + 820: pliers/plyers + 821: plow/plow farm equipment/plough/plough farm equipment + 822: plume + 823: pocket watch + 824: pocketknife + 825: poker/poker fire stirring tool/stove poker/fire hook + 826: pole/post + 827: polo shirt/sport shirt + 828: poncho + 829: pony + 830: pool table/billiard table/snooker table + 831: pop/pop soda/soda/soda pop/tonic/soft drink + 832: postbox/postbox public/mailbox/mailbox public + 833: postcard/postal card/mailing-card + 834: poster/placard + 835: pot + 836: flowerpot + 837: potato + 838: potholder + 839: pottery/clayware + 840: pouch + 841: power shovel/excavator/digger + 842: prawn/shrimp + 843: pretzel + 844: printer/printing machine + 845: projectile/projectile weapon/missile + 846: projector + 847: propeller/propellor + 848: prune + 849: pudding + 850: puffer/puffer fish/pufferfish/blowfish/globefish + 851: puffin + 852: pug-dog + 853: pumpkin + 854: puncher + 855: puppet/marionette + 856: puppy + 857: quesadilla + 858: quiche + 859: quilt/comforter + 860: rabbit + 861: race car/racing car + 862: racket/racquet + 863: radar + 864: radiator + 865: radio receiver/radio set/radio/tuner/tuner radio + 866: radish/daikon + 867: raft + 868: rag doll + 869: raincoat/waterproof jacket + 870: ram/ram animal + 871: raspberry + 872: rat + 873: razorblade + 874: reamer/reamer juicer/juicer/juice reamer + 875: rearview mirror + 876: receipt + 877: recliner/reclining chair/lounger/lounger chair + 878: record player/phonograph/phonograph record player/turntable + 879: reflector + 880: remote control + 881: rhinoceros + 882: rib/rib food + 883: rifle + 884: ring + 885: river boat + 886: road map + 887: robe + 888: rocking chair + 889: rodent + 890: roller skate + 891: Rollerblade + 892: rolling pin + 893: root beer + 894: router/router computer equipment + 895: rubber band/elastic band + 896: runner/runner carpet + 897: plastic bag/paper bag + 898: saddle/saddle on an animal + 899: saddle blanket/saddlecloth/horse blanket + 900: saddlebag + 901: safety pin + 902: sail + 903: salad + 904: salad plate/salad bowl + 905: salami + 906: salmon/salmon fish + 907: salmon/salmon food + 908: salsa + 909: saltshaker + 910: sandal/sandal type of shoe + 911: sandwich + 912: satchel + 913: saucepan + 914: saucer + 915: sausage + 916: sawhorse/sawbuck + 917: saxophone + 918: scale/scale measuring instrument + 919: scarecrow/strawman + 920: scarf + 921: school bus + 922: scissors + 923: scoreboard + 924: scraper + 925: screwdriver + 926: scrubbing brush + 927: sculpture + 928: seabird/seafowl + 929: seahorse + 930: seaplane/hydroplane + 931: seashell + 932: sewing machine + 933: shaker + 934: shampoo + 935: shark + 936: sharpener + 937: Sharpie + 938: shaver/shaver electric/electric shaver/electric razor + 939: shaving cream/shaving soap + 940: shawl + 941: shears + 942: sheep + 943: shepherd dog/sheepdog + 944: sherbert/sherbet + 945: shield + 946: shirt + 947: shoe/sneaker/sneaker type of shoe/tennis shoe + 948: shopping bag + 949: shopping cart + 950: short pants/shorts/shorts clothing/trunks/trunks clothing + 951: shot glass + 952: shoulder bag + 953: shovel + 954: shower head + 955: shower cap + 956: shower curtain + 957: shredder/shredder for paper + 958: signboard + 959: silo + 960: sink + 961: skateboard + 962: skewer + 963: ski + 964: ski boot + 965: ski parka/ski jacket + 966: ski pole + 967: skirt + 968: skullcap + 969: sled/sledge/sleigh + 970: sleeping bag + 971: sling/sling bandage/triangular bandage + 972: slipper/slipper footwear/carpet slipper/carpet slipper footwear + 973: smoothie + 974: snake/serpent + 975: snowboard + 976: snowman + 977: snowmobile + 978: soap + 979: soccer ball + 980: sock + 981: sofa/couch/lounge + 982: softball + 983: solar array/solar battery/solar panel + 984: sombrero + 985: soup + 986: soup bowl + 987: soupspoon + 988: sour cream/soured cream + 989: soya milk/soybean milk/soymilk + 990: space shuttle + 991: sparkler/sparkler fireworks + 992: spatula + 993: spear/lance + 994: spectacles/specs/eyeglasses/glasses + 995: spice rack + 996: spider + 997: crawfish/crayfish + 998: sponge + 999: spoon + 1000: sportswear/athletic wear/activewear + 1001: spotlight + 1002: squid/squid food/calamari/calamary + 1003: squirrel + 1004: stagecoach + 1005: stapler/stapler stapling machine + 1006: starfish/sea star + 1007: statue/statue sculpture + 1008: steak/steak food + 1009: steak knife + 1010: steering wheel + 1011: stepladder + 1012: step stool + 1013: stereo/stereo sound system + 1014: stew + 1015: stirrer + 1016: stirrup + 1017: stool + 1018: stop sign + 1019: brake light + 1020: stove/kitchen stove/range/range kitchen appliance/kitchen range/cooking stove + 1021: strainer + 1022: strap + 1023: straw/straw for drinking/drinking straw + 1024: strawberry + 1025: street sign + 1026: streetlight/street lamp + 1027: string cheese + 1028: stylus + 1029: subwoofer + 1030: sugar bowl + 1031: sugarcane/sugarcane plant + 1032: suit/suit clothing + 1033: sunflower + 1034: sunglasses + 1035: sunhat + 1036: surfboard + 1037: sushi + 1038: mop + 1039: sweat pants + 1040: sweatband + 1041: sweater + 1042: sweatshirt + 1043: sweet potato + 1044: swimsuit/swimwear/bathing suit/swimming costume/bathing costume/swimming trunks/bathing + trunks + 1045: sword + 1046: syringe + 1047: Tabasco sauce + 1048: table-tennis table/ping-pong table + 1049: table + 1050: table lamp + 1051: tablecloth + 1052: tachometer + 1053: taco + 1054: tag + 1055: taillight/rear light + 1056: tambourine + 1057: army tank/armored combat vehicle/armoured combat vehicle + 1058: tank/tank storage vessel/storage tank + 1059: tank top/tank top clothing + 1060: tape/tape sticky cloth or paper + 1061: tape measure/measuring tape + 1062: tapestry + 1063: tarp + 1064: tartan/plaid + 1065: tassel + 1066: tea bag + 1067: teacup + 1068: teakettle + 1069: teapot + 1070: teddy bear + 1071: telephone/phone/telephone set + 1072: telephone booth/phone booth/call box/telephone box/telephone kiosk + 1073: telephone pole/telegraph pole/telegraph post + 1074: telephoto lens/zoom lens + 1075: television camera/tv camera + 1076: television set/tv/tv set + 1077: tennis ball + 1078: tennis racket + 1079: tequila + 1080: thermometer + 1081: thermos bottle + 1082: thermostat + 1083: thimble + 1084: thread/yarn + 1085: thumbtack/drawing pin/pushpin + 1086: tiara + 1087: tiger + 1088: tights/tights clothing/leotards + 1089: timer/stopwatch + 1090: tinfoil + 1091: tinsel + 1092: tissue paper + 1093: toast/toast food + 1094: toaster + 1095: toaster oven + 1096: toilet + 1097: toilet tissue/toilet paper/bathroom tissue + 1098: tomato + 1099: tongs + 1100: toolbox + 1101: toothbrush + 1102: toothpaste + 1103: toothpick + 1104: cover + 1105: tortilla + 1106: tow truck + 1107: towel + 1108: towel rack/towel rail/towel bar + 1109: toy + 1110: tractor/tractor farm equipment + 1111: traffic light + 1112: dirt bike + 1113: trailer truck/tractor trailer/trucking rig/articulated lorry/semi truck + 1114: train/train railroad vehicle/railroad train + 1115: trampoline + 1116: tray + 1117: trench coat + 1118: triangle/triangle musical instrument + 1119: tricycle + 1120: tripod + 1121: trousers/pants/pants clothing + 1122: truck + 1123: truffle/truffle chocolate/chocolate truffle + 1124: trunk + 1125: vat + 1126: turban + 1127: turkey/turkey food + 1128: turnip + 1129: turtle + 1130: turtleneck/turtleneck clothing/polo-neck + 1131: typewriter + 1132: umbrella + 1133: underwear/underclothes/underclothing/underpants + 1134: unicycle + 1135: urinal + 1136: urn + 1137: vacuum cleaner + 1138: vase + 1139: vending machine + 1140: vent/blowhole/air vent + 1141: vest/waistcoat + 1142: videotape + 1143: vinegar + 1144: violin/fiddle + 1145: vodka + 1146: volleyball + 1147: vulture + 1148: waffle + 1149: waffle iron + 1150: wagon + 1151: wagon wheel + 1152: walking stick + 1153: wall clock + 1154: wall socket/wall plug/electric outlet/electrical outlet/outlet/electric receptacle + 1155: wallet/billfold + 1156: walrus + 1157: wardrobe + 1158: washbasin/basin/basin for washing/washbowl/washstand/handbasin + 1159: automatic washer/washing machine + 1160: watch/wristwatch + 1161: water bottle + 1162: water cooler + 1163: water faucet/water tap/tap/tap water faucet + 1164: water heater/hot-water heater + 1165: water jug + 1166: water gun/squirt gun + 1167: water scooter/sea scooter/jet ski + 1168: water ski + 1169: water tower + 1170: watering can + 1171: watermelon + 1172: weathervane/vane/vane weathervane/wind vane + 1173: webcam + 1174: wedding cake/bridecake + 1175: wedding ring/wedding band + 1176: wet suit + 1177: wheel + 1178: wheelchair + 1179: whipped cream + 1180: whistle + 1181: wig + 1182: wind chime + 1183: windmill + 1184: window box/window box for plants + 1185: windshield wiper/windscreen wiper/wiper/wiper for windshield or screen + 1186: windsock/air sock/air-sleeve/wind sleeve/wind cone + 1187: wine bottle + 1188: wine bucket/wine cooler + 1189: wineglass + 1190: blinder/blinder for horses + 1191: wok + 1192: wolf + 1193: wooden spoon + 1194: wreath + 1195: wrench/spanner + 1196: wristband + 1197: wristlet/wrist band + 1198: yacht + 1199: yogurt/yoghurt/yoghourt + 1200: yoke/yoke animal equipment + 1201: zebra + 1202: zucchini/courgette + +# Download script/URL (optional) +download: | + from ultralytics.utils.downloads import download + from pathlib import Path + + # Download labels + dir = Path(yaml['path']) # dataset root dir + url = 'https://github.com/ultralytics/yolov5/releases/download/v1.0/' + urls = [url + 'lvis-labels-segments.zip'] # labels + download(urls, dir=dir.parent) + # Download data + urls = ['http://images.cocodataset.org/zips/train2017.zip', # 19G, 118k images + 'http://images.cocodataset.org/zips/val2017.zip', # 1G, 5k images + 'http://images.cocodataset.org/zips/test2017.zip'] # 7G, 41k images (optional) + download(urls, dir=dir / 'images', threads=3) diff --git a/ultralytics/cfg/datasets/open-images-v7.yaml b/ultralytics/cfg/datasets/open-images-v7.yaml new file mode 100644 index 0000000..d9cad9f --- /dev/null +++ b/ultralytics/cfg/datasets/open-images-v7.yaml @@ -0,0 +1,660 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# Open Images v7 dataset https://storage.googleapis.com/openimages/web/index.html by Google +# Documentation: https://docs.ultralytics.com/datasets/detect/open-images-v7/ +# Example usage: yolo train data=open-images-v7.yaml +# parent +# ├── ultralytics +# └── datasets +# └── open-images-v7 ← downloads here (561 GB) + +# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..] +path: ../datasets/open-images-v7 # dataset root dir +train: images/train # train images (relative to 'path') 1743042 images +val: images/val # val images (relative to 'path') 41620 images +test: # test images (optional) + +# Classes +names: + 0: Accordion + 1: Adhesive tape + 2: Aircraft + 3: Airplane + 4: Alarm clock + 5: Alpaca + 6: Ambulance + 7: Animal + 8: Ant + 9: Antelope + 10: Apple + 11: Armadillo + 12: Artichoke + 13: Auto part + 14: Axe + 15: Backpack + 16: Bagel + 17: Baked goods + 18: Balance beam + 19: Ball + 20: Balloon + 21: Banana + 22: Band-aid + 23: Banjo + 24: Barge + 25: Barrel + 26: Baseball bat + 27: Baseball glove + 28: Bat (Animal) + 29: Bathroom accessory + 30: Bathroom cabinet + 31: Bathtub + 32: Beaker + 33: Bear + 34: Bed + 35: Bee + 36: Beehive + 37: Beer + 38: Beetle + 39: Bell pepper + 40: Belt + 41: Bench + 42: Bicycle + 43: Bicycle helmet + 44: Bicycle wheel + 45: Bidet + 46: Billboard + 47: Billiard table + 48: Binoculars + 49: Bird + 50: Blender + 51: Blue jay + 52: Boat + 53: Bomb + 54: Book + 55: Bookcase + 56: Boot + 57: Bottle + 58: Bottle opener + 59: Bow and arrow + 60: Bowl + 61: Bowling equipment + 62: Box + 63: Boy + 64: Brassiere + 65: Bread + 66: Briefcase + 67: Broccoli + 68: Bronze sculpture + 69: Brown bear + 70: Building + 71: Bull + 72: Burrito + 73: Bus + 74: Bust + 75: Butterfly + 76: Cabbage + 77: Cabinetry + 78: Cake + 79: Cake stand + 80: Calculator + 81: Camel + 82: Camera + 83: Can opener + 84: Canary + 85: Candle + 86: Candy + 87: Cannon + 88: Canoe + 89: Cantaloupe + 90: Car + 91: Carnivore + 92: Carrot + 93: Cart + 94: Cassette deck + 95: Castle + 96: Cat + 97: Cat furniture + 98: Caterpillar + 99: Cattle + 100: Ceiling fan + 101: Cello + 102: Centipede + 103: Chainsaw + 104: Chair + 105: Cheese + 106: Cheetah + 107: Chest of drawers + 108: Chicken + 109: Chime + 110: Chisel + 111: Chopsticks + 112: Christmas tree + 113: Clock + 114: Closet + 115: Clothing + 116: Coat + 117: Cocktail + 118: Cocktail shaker + 119: Coconut + 120: Coffee + 121: Coffee cup + 122: Coffee table + 123: Coffeemaker + 124: Coin + 125: Common fig + 126: Common sunflower + 127: Computer keyboard + 128: Computer monitor + 129: Computer mouse + 130: Container + 131: Convenience store + 132: Cookie + 133: Cooking spray + 134: Corded phone + 135: Cosmetics + 136: Couch + 137: Countertop + 138: Cowboy hat + 139: Crab + 140: Cream + 141: Cricket ball + 142: Crocodile + 143: Croissant + 144: Crown + 145: Crutch + 146: Cucumber + 147: Cupboard + 148: Curtain + 149: Cutting board + 150: Dagger + 151: Dairy Product + 152: Deer + 153: Desk + 154: Dessert + 155: Diaper + 156: Dice + 157: Digital clock + 158: Dinosaur + 159: Dishwasher + 160: Dog + 161: Dog bed + 162: Doll + 163: Dolphin + 164: Door + 165: Door handle + 166: Doughnut + 167: Dragonfly + 168: Drawer + 169: Dress + 170: Drill (Tool) + 171: Drink + 172: Drinking straw + 173: Drum + 174: Duck + 175: Dumbbell + 176: Eagle + 177: Earrings + 178: Egg (Food) + 179: Elephant + 180: Envelope + 181: Eraser + 182: Face powder + 183: Facial tissue holder + 184: Falcon + 185: Fashion accessory + 186: Fast food + 187: Fax + 188: Fedora + 189: Filing cabinet + 190: Fire hydrant + 191: Fireplace + 192: Fish + 193: Flag + 194: Flashlight + 195: Flower + 196: Flowerpot + 197: Flute + 198: Flying disc + 199: Food + 200: Food processor + 201: Football + 202: Football helmet + 203: Footwear + 204: Fork + 205: Fountain + 206: Fox + 207: French fries + 208: French horn + 209: Frog + 210: Fruit + 211: Frying pan + 212: Furniture + 213: Garden Asparagus + 214: Gas stove + 215: Giraffe + 216: Girl + 217: Glasses + 218: Glove + 219: Goat + 220: Goggles + 221: Goldfish + 222: Golf ball + 223: Golf cart + 224: Gondola + 225: Goose + 226: Grape + 227: Grapefruit + 228: Grinder + 229: Guacamole + 230: Guitar + 231: Hair dryer + 232: Hair spray + 233: Hamburger + 234: Hammer + 235: Hamster + 236: Hand dryer + 237: Handbag + 238: Handgun + 239: Harbor seal + 240: Harmonica + 241: Harp + 242: Harpsichord + 243: Hat + 244: Headphones + 245: Heater + 246: Hedgehog + 247: Helicopter + 248: Helmet + 249: High heels + 250: Hiking equipment + 251: Hippopotamus + 252: Home appliance + 253: Honeycomb + 254: Horizontal bar + 255: Horse + 256: Hot dog + 257: House + 258: Houseplant + 259: Human arm + 260: Human beard + 261: Human body + 262: Human ear + 263: Human eye + 264: Human face + 265: Human foot + 266: Human hair + 267: Human hand + 268: Human head + 269: Human leg + 270: Human mouth + 271: Human nose + 272: Humidifier + 273: Ice cream + 274: Indoor rower + 275: Infant bed + 276: Insect + 277: Invertebrate + 278: Ipod + 279: Isopod + 280: Jacket + 281: Jacuzzi + 282: Jaguar (Animal) + 283: Jeans + 284: Jellyfish + 285: Jet ski + 286: Jug + 287: Juice + 288: Kangaroo + 289: Kettle + 290: Kitchen & dining room table + 291: Kitchen appliance + 292: Kitchen knife + 293: Kitchen utensil + 294: Kitchenware + 295: Kite + 296: Knife + 297: Koala + 298: Ladder + 299: Ladle + 300: Ladybug + 301: Lamp + 302: Land vehicle + 303: Lantern + 304: Laptop + 305: Lavender (Plant) + 306: Lemon + 307: Leopard + 308: Light bulb + 309: Light switch + 310: Lighthouse + 311: Lily + 312: Limousine + 313: Lion + 314: Lipstick + 315: Lizard + 316: Lobster + 317: Loveseat + 318: Luggage and bags + 319: Lynx + 320: Magpie + 321: Mammal + 322: Man + 323: Mango + 324: Maple + 325: Maracas + 326: Marine invertebrates + 327: Marine mammal + 328: Measuring cup + 329: Mechanical fan + 330: Medical equipment + 331: Microphone + 332: Microwave oven + 333: Milk + 334: Miniskirt + 335: Mirror + 336: Missile + 337: Mixer + 338: Mixing bowl + 339: Mobile phone + 340: Monkey + 341: Moths and butterflies + 342: Motorcycle + 343: Mouse + 344: Muffin + 345: Mug + 346: Mule + 347: Mushroom + 348: Musical instrument + 349: Musical keyboard + 350: Nail (Construction) + 351: Necklace + 352: Nightstand + 353: Oboe + 354: Office building + 355: Office supplies + 356: Orange + 357: Organ (Musical Instrument) + 358: Ostrich + 359: Otter + 360: Oven + 361: Owl + 362: Oyster + 363: Paddle + 364: Palm tree + 365: Pancake + 366: Panda + 367: Paper cutter + 368: Paper towel + 369: Parachute + 370: Parking meter + 371: Parrot + 372: Pasta + 373: Pastry + 374: Peach + 375: Pear + 376: Pen + 377: Pencil case + 378: Pencil sharpener + 379: Penguin + 380: Perfume + 381: Person + 382: Personal care + 383: Personal flotation device + 384: Piano + 385: Picnic basket + 386: Picture frame + 387: Pig + 388: Pillow + 389: Pineapple + 390: Pitcher (Container) + 391: Pizza + 392: Pizza cutter + 393: Plant + 394: Plastic bag + 395: Plate + 396: Platter + 397: Plumbing fixture + 398: Polar bear + 399: Pomegranate + 400: Popcorn + 401: Porch + 402: Porcupine + 403: Poster + 404: Potato + 405: Power plugs and sockets + 406: Pressure cooker + 407: Pretzel + 408: Printer + 409: Pumpkin + 410: Punching bag + 411: Rabbit + 412: Raccoon + 413: Racket + 414: Radish + 415: Ratchet (Device) + 416: Raven + 417: Rays and skates + 418: Red panda + 419: Refrigerator + 420: Remote control + 421: Reptile + 422: Rhinoceros + 423: Rifle + 424: Ring binder + 425: Rocket + 426: Roller skates + 427: Rose + 428: Rugby ball + 429: Ruler + 430: Salad + 431: Salt and pepper shakers + 432: Sandal + 433: Sandwich + 434: Saucer + 435: Saxophone + 436: Scale + 437: Scarf + 438: Scissors + 439: Scoreboard + 440: Scorpion + 441: Screwdriver + 442: Sculpture + 443: Sea lion + 444: Sea turtle + 445: Seafood + 446: Seahorse + 447: Seat belt + 448: Segway + 449: Serving tray + 450: Sewing machine + 451: Shark + 452: Sheep + 453: Shelf + 454: Shellfish + 455: Shirt + 456: Shorts + 457: Shotgun + 458: Shower + 459: Shrimp + 460: Sink + 461: Skateboard + 462: Ski + 463: Skirt + 464: Skull + 465: Skunk + 466: Skyscraper + 467: Slow cooker + 468: Snack + 469: Snail + 470: Snake + 471: Snowboard + 472: Snowman + 473: Snowmobile + 474: Snowplow + 475: Soap dispenser + 476: Sock + 477: Sofa bed + 478: Sombrero + 479: Sparrow + 480: Spatula + 481: Spice rack + 482: Spider + 483: Spoon + 484: Sports equipment + 485: Sports uniform + 486: Squash (Plant) + 487: Squid + 488: Squirrel + 489: Stairs + 490: Stapler + 491: Starfish + 492: Stationary bicycle + 493: Stethoscope + 494: Stool + 495: Stop sign + 496: Strawberry + 497: Street light + 498: Stretcher + 499: Studio couch + 500: Submarine + 501: Submarine sandwich + 502: Suit + 503: Suitcase + 504: Sun hat + 505: Sunglasses + 506: Surfboard + 507: Sushi + 508: Swan + 509: Swim cap + 510: Swimming pool + 511: Swimwear + 512: Sword + 513: Syringe + 514: Table + 515: Table tennis racket + 516: Tablet computer + 517: Tableware + 518: Taco + 519: Tank + 520: Tap + 521: Tart + 522: Taxi + 523: Tea + 524: Teapot + 525: Teddy bear + 526: Telephone + 527: Television + 528: Tennis ball + 529: Tennis racket + 530: Tent + 531: Tiara + 532: Tick + 533: Tie + 534: Tiger + 535: Tin can + 536: Tire + 537: Toaster + 538: Toilet + 539: Toilet paper + 540: Tomato + 541: Tool + 542: Toothbrush + 543: Torch + 544: Tortoise + 545: Towel + 546: Tower + 547: Toy + 548: Traffic light + 549: Traffic sign + 550: Train + 551: Training bench + 552: Treadmill + 553: Tree + 554: Tree house + 555: Tripod + 556: Trombone + 557: Trousers + 558: Truck + 559: Trumpet + 560: Turkey + 561: Turtle + 562: Umbrella + 563: Unicycle + 564: Van + 565: Vase + 566: Vegetable + 567: Vehicle + 568: Vehicle registration plate + 569: Violin + 570: Volleyball (Ball) + 571: Waffle + 572: Waffle iron + 573: Wall clock + 574: Wardrobe + 575: Washing machine + 576: Waste container + 577: Watch + 578: Watercraft + 579: Watermelon + 580: Weapon + 581: Whale + 582: Wheel + 583: Wheelchair + 584: Whisk + 585: Whiteboard + 586: Willow + 587: Window + 588: Window blind + 589: Wine + 590: Wine glass + 591: Wine rack + 592: Winter melon + 593: Wok + 594: Woman + 595: Wood-burning stove + 596: Woodpecker + 597: Worm + 598: Wrench + 599: Zebra + 600: Zucchini + +# Download script/URL (optional) --------------------------------------------------------------------------------------- +download: | + from ultralytics.utils import LOGGER, SETTINGS, Path, is_ubuntu, get_ubuntu_version + from ultralytics.utils.checks import check_requirements, check_version + + check_requirements('fiftyone') + if is_ubuntu() and check_version(get_ubuntu_version(), '>=22.04'): + # Ubuntu>=22.04 patch https://github.com/voxel51/fiftyone/issues/2961#issuecomment-1666519347 + check_requirements('fiftyone-db-ubuntu2204') + + import fiftyone as fo + import fiftyone.zoo as foz + import warnings + + name = 'open-images-v7' + fraction = 1.0 # fraction of full dataset to use + LOGGER.warning('WARNING ⚠️ Open Images V7 dataset requires at least **561 GB of free space. Starting download...') + for split in 'train', 'validation': # 1743042 train, 41620 val images + train = split == 'train' + + # Load Open Images dataset + dataset = foz.load_zoo_dataset(name, + split=split, + label_types=['detections'], + dataset_dir=Path(SETTINGS['datasets_dir']) / 'fiftyone' / name, + max_samples=round((1743042 if train else 41620) * fraction)) + + # Define classes + if train: + classes = dataset.default_classes # all classes + # classes = dataset.distinct('ground_truth.detections.label') # only observed classes + + # Export to YOLO format + with warnings.catch_warnings(): + warnings.filterwarnings("ignore", category=UserWarning, module="fiftyone.utils.yolo") + dataset.export(export_dir=str(Path(SETTINGS['datasets_dir']) / name), + dataset_type=fo.types.YOLOv5Dataset, + label_field='ground_truth', + split='val' if split == 'validation' else split, + classes=classes, + overwrite=train) diff --git a/ultralytics/cfg/datasets/package-seg.yaml b/ultralytics/cfg/datasets/package-seg.yaml new file mode 100644 index 0000000..44fe550 --- /dev/null +++ b/ultralytics/cfg/datasets/package-seg.yaml @@ -0,0 +1,21 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# Package-seg dataset by Ultralytics +# Documentation: https://docs.ultralytics.com/datasets/segment/package-seg/ +# Example usage: yolo train data=package-seg.yaml +# parent +# ├── ultralytics +# └── datasets +# └── package-seg ← downloads here (102 MB) + +# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..] +path: ../datasets/package-seg # dataset root dir +train: images/train # train images (relative to 'path') 1920 images +val: images/val # val images (relative to 'path') 89 images +test: test/images # test images (relative to 'path') 188 images + +# Classes +names: + 0: package + +# Download script/URL (optional) +download: https://ultralytics.com/assets/package-seg.zip diff --git a/ultralytics/cfg/datasets/tiger-pose.yaml b/ultralytics/cfg/datasets/tiger-pose.yaml new file mode 100644 index 0000000..d37df04 --- /dev/null +++ b/ultralytics/cfg/datasets/tiger-pose.yaml @@ -0,0 +1,24 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# Tiger Pose dataset by Ultralytics +# Documentation: https://docs.ultralytics.com/datasets/pose/tiger-pose/ +# Example usage: yolo train data=tiger-pose.yaml +# parent +# ├── ultralytics +# └── datasets +# └── tiger-pose ← downloads here (75.3 MB) + +# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..] +path: ../datasets/tiger-pose # dataset root dir +train: train # train images (relative to 'path') 210 images +val: val # val images (relative to 'path') 53 images + +# Keypoints +kpt_shape: [12, 2] # number of keypoints, number of dims (2 for x,y or 3 for x,y,visible) +flip_idx: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11] + +# Classes +names: + 0: tiger + +# Download script/URL (optional) +download: https://ultralytics.com/assets/tiger-pose.zip diff --git a/ultralytics/cfg/datasets/xView.yaml b/ultralytics/cfg/datasets/xView.yaml new file mode 100644 index 0000000..d2e957a --- /dev/null +++ b/ultralytics/cfg/datasets/xView.yaml @@ -0,0 +1,152 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# DIUx xView 2018 Challenge https://challenge.xviewdataset.org by U.S. National Geospatial-Intelligence Agency (NGA) +# -------- DOWNLOAD DATA MANUALLY and jar xf val_images.zip to 'datasets/xView' before running train command! -------- +# Documentation: https://docs.ultralytics.com/datasets/detect/xview/ +# Example usage: yolo train data=xView.yaml +# parent +# ├── ultralytics +# └── datasets +# └── xView ← downloads here (20.7 GB) + +# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..] +path: ../datasets/xView # dataset root dir +train: images/autosplit_train.txt # train images (relative to 'path') 90% of 847 train images +val: images/autosplit_val.txt # train images (relative to 'path') 10% of 847 train images + +# Classes +names: + 0: Fixed-wing Aircraft + 1: Small Aircraft + 2: Cargo Plane + 3: Helicopter + 4: Passenger Vehicle + 5: Small Car + 6: Bus + 7: Pickup Truck + 8: Utility Truck + 9: Truck + 10: Cargo Truck + 11: Truck w/Box + 12: Truck Tractor + 13: Trailer + 14: Truck w/Flatbed + 15: Truck w/Liquid + 16: Crane Truck + 17: Railway Vehicle + 18: Passenger Car + 19: Cargo Car + 20: Flat Car + 21: Tank car + 22: Locomotive + 23: Maritime Vessel + 24: Motorboat + 25: Sailboat + 26: Tugboat + 27: Barge + 28: Fishing Vessel + 29: Ferry + 30: Yacht + 31: Container Ship + 32: Oil Tanker + 33: Engineering Vehicle + 34: Tower crane + 35: Container Crane + 36: Reach Stacker + 37: Straddle Carrier + 38: Mobile Crane + 39: Dump Truck + 40: Haul Truck + 41: Scraper/Tractor + 42: Front loader/Bulldozer + 43: Excavator + 44: Cement Mixer + 45: Ground Grader + 46: Hut/Tent + 47: Shed + 48: Building + 49: Aircraft Hangar + 50: Damaged Building + 51: Facility + 52: Construction Site + 53: Vehicle Lot + 54: Helipad + 55: Storage Tank + 56: Shipping container lot + 57: Shipping Container + 58: Pylon + 59: Tower + +# Download script/URL (optional) --------------------------------------------------------------------------------------- +download: | + import json + import os + from pathlib import Path + + import numpy as np + from PIL import Image + from tqdm import tqdm + + from ultralytics.data.utils import autosplit + from ultralytics.utils.ops import xyxy2xywhn + + + def convert_labels(fname=Path('xView/xView_train.geojson')): + # Convert xView geoJSON labels to YOLO format + path = fname.parent + with open(fname) as f: + print(f'Loading {fname}...') + data = json.load(f) + + # Make dirs + labels = Path(path / 'labels' / 'train') + os.system(f'rm -rf {labels}') + labels.mkdir(parents=True, exist_ok=True) + + # xView classes 11-94 to 0-59 + xview_class2index = [-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 0, 1, 2, -1, 3, -1, 4, 5, 6, 7, 8, -1, 9, 10, 11, + 12, 13, 14, 15, -1, -1, 16, 17, 18, 19, 20, 21, 22, -1, 23, 24, 25, -1, 26, 27, -1, 28, -1, + 29, 30, 31, 32, 33, 34, 35, 36, 37, -1, 38, 39, 40, 41, 42, 43, 44, 45, -1, -1, -1, -1, 46, + 47, 48, 49, -1, 50, 51, -1, 52, -1, -1, -1, 53, 54, -1, 55, -1, -1, 56, -1, 57, -1, 58, 59] + + shapes = {} + for feature in tqdm(data['features'], desc=f'Converting {fname}'): + p = feature['properties'] + if p['bounds_imcoords']: + id = p['image_id'] + file = path / 'train_images' / id + if file.exists(): # 1395.tif missing + try: + box = np.array([int(num) for num in p['bounds_imcoords'].split(",")]) + assert box.shape[0] == 4, f'incorrect box shape {box.shape[0]}' + cls = p['type_id'] + cls = xview_class2index[int(cls)] # xView class to 0-60 + assert 59 >= cls >= 0, f'incorrect class index {cls}' + + # Write YOLO label + if id not in shapes: + shapes[id] = Image.open(file).size + box = xyxy2xywhn(box[None].astype(np.float), w=shapes[id][0], h=shapes[id][1], clip=True) + with open((labels / id).with_suffix('.txt'), 'a') as f: + f.write(f"{cls} {' '.join(f'{x:.6f}' for x in box[0])}\n") # write label.txt + except Exception as e: + print(f'WARNING: skipping one label for {file}: {e}') + + + # Download manually from https://challenge.xviewdataset.org + dir = Path(yaml['path']) # dataset root dir + # urls = ['https://d307kc0mrhucc3.cloudfront.net/train_labels.zip', # train labels + # 'https://d307kc0mrhucc3.cloudfront.net/train_images.zip', # 15G, 847 train images + # 'https://d307kc0mrhucc3.cloudfront.net/val_images.zip'] # 5G, 282 val images (no labels) + # download(urls, dir=dir) + + # Convert labels + convert_labels(dir / 'xView_train.geojson') + + # Move images + images = Path(dir / 'images') + images.mkdir(parents=True, exist_ok=True) + Path(dir / 'train_images').rename(dir / 'images' / 'train') + Path(dir / 'val_images').rename(dir / 'images' / 'val') + + # Split + autosplit(dir / 'images' / 'train') diff --git a/ultralytics/cfg/default.yaml b/ultralytics/cfg/default.yaml new file mode 100644 index 0000000..78b5f43 --- /dev/null +++ b/ultralytics/cfg/default.yaml @@ -0,0 +1,126 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# Default training settings and hyperparameters for medium-augmentation COCO training + +task: detect # (str) YOLO task, i.e. detect, segment, classify, pose +mode: train # (str) YOLO mode, i.e. train, val, predict, export, track, benchmark + +# Train settings ------------------------------------------------------------------------------------------------------- +model: # (str, optional) path to model file, i.e. yolov8n.pt, yolov8n.yaml +data: # (str, optional) path to data file, i.e. coco128.yaml +epochs: 100 # (int) number of epochs to train for +time: # (float, optional) number of hours to train for, overrides epochs if supplied +patience: 100 # (int) epochs to wait for no observable improvement for early stopping of training +batch: 16 # (int) number of images per batch (-1 for AutoBatch) +imgsz: 640 # (int | list) input images size as int for train and val modes, or list[w,h] for predict and export modes +save: True # (bool) save train checkpoints and predict results +save_period: -1 # (int) Save checkpoint every x epochs (disabled if < 1) +cache: False # (bool) True/ram, disk or False. Use cache for data loading +device: # (int | str | list, optional) device to run on, i.e. cuda device=0 or device=0,1,2,3 or device=cpu +workers: 8 # (int) number of worker threads for data loading (per RANK if DDP) +project: # (str, optional) project name +name: # (str, optional) experiment name, results saved to 'project/name' directory +exist_ok: False # (bool) whether to overwrite existing experiment +pretrained: True # (bool | str) whether to use a pretrained model (bool) or a model to load weights from (str) +optimizer: auto # (str) optimizer to use, choices=[SGD, Adam, Adamax, AdamW, NAdam, RAdam, RMSProp, auto] +verbose: True # (bool) whether to print verbose output +seed: 0 # (int) random seed for reproducibility +deterministic: True # (bool) whether to enable deterministic mode +single_cls: False # (bool) train multi-class data as single-class +rect: False # (bool) rectangular training if mode='train' or rectangular validation if mode='val' +cos_lr: False # (bool) use cosine learning rate scheduler +close_mosaic: 10 # (int) disable mosaic augmentation for final epochs (0 to disable) +resume: False # (bool) resume training from last checkpoint +amp: True # (bool) Automatic Mixed Precision (AMP) training, choices=[True, False], True runs AMP check +fraction: 1.0 # (float) dataset fraction to train on (default is 1.0, all images in train set) +profile: False # (bool) profile ONNX and TensorRT speeds during training for loggers +freeze: None # (int | list, optional) freeze first n layers, or freeze list of layer indices during training +multi_scale: False # (bool) Whether to use multiscale during training +# Segmentation +overlap_mask: True # (bool) masks should overlap during training (segment train only) +mask_ratio: 4 # (int) mask downsample ratio (segment train only) +# Classification +dropout: 0.0 # (float) use dropout regularization (classify train only) + +# Val/Test settings ---------------------------------------------------------------------------------------------------- +val: True # (bool) validate/test during training +split: val # (str) dataset split to use for validation, i.e. 'val', 'test' or 'train' +save_json: False # (bool) save results to JSON file +save_hybrid: False # (bool) save hybrid version of labels (labels + additional predictions) +conf: # (float, optional) object confidence threshold for detection (default 0.25 predict, 0.001 val) +iou: 0.7 # (float) intersection over union (IoU) threshold for NMS +max_det: 300 # (int) maximum number of detections per image +half: False # (bool) use half precision (FP16) +dnn: False # (bool) use OpenCV DNN for ONNX inference +plots: True # (bool) save plots and images during train/val + +# Predict settings ----------------------------------------------------------------------------------------------------- +source: # (str, optional) source directory for images or videos +vid_stride: 1 # (int) video frame-rate stride +stream_buffer: False # (bool) buffer all streaming frames (True) or return the most recent frame (False) +visualize: False # (bool) visualize model features +augment: False # (bool) apply image augmentation to prediction sources +agnostic_nms: False # (bool) class-agnostic NMS +classes: # (int | list[int], optional) filter results by class, i.e. classes=0, or classes=[0,2,3] +retina_masks: False # (bool) use high-resolution segmentation masks +embed: # (list[int], optional) return feature vectors/embeddings from given layers + +# Visualize settings --------------------------------------------------------------------------------------------------- +show: False # (bool) show predicted images and videos if environment allows +save_frames: False # (bool) save predicted individual video frames +save_txt: False # (bool) save results as .txt file +save_conf: False # (bool) save results with confidence scores +save_crop: False # (bool) save cropped images with results +show_labels: True # (bool) show prediction labels, i.e. 'person' +show_conf: True # (bool) show prediction confidence, i.e. '0.99' +show_boxes: True # (bool) show prediction boxes +line_width: # (int, optional) line width of the bounding boxes. Scaled to image size if None. + +# Export settings ------------------------------------------------------------------------------------------------------ +format: torchscript # (str) format to export to, choices at https://docs.ultralytics.com/modes/export/#export-formats +keras: False # (bool) use Kera=s +optimize: False # (bool) TorchScript: optimize for mobile +int8: False # (bool) CoreML/TF INT8 quantization +dynamic: False # (bool) ONNX/TF/TensorRT: dynamic axes +simplify: False # (bool) ONNX: simplify model +opset: # (int, optional) ONNX: opset version +workspace: 4 # (int) TensorRT: workspace size (GB) +nms: False # (bool) CoreML: add NMS + +# Hyperparameters ------------------------------------------------------------------------------------------------------ +lr0: 0.01 # (float) initial learning rate (i.e. SGD=1E-2, Adam=1E-3) +lrf: 0.01 # (float) final learning rate (lr0 * lrf) +momentum: 0.937 # (float) SGD momentum/Adam beta1 +weight_decay: 0.0005 # (float) optimizer weight decay 5e-4 +warmup_epochs: 3.0 # (float) warmup epochs (fractions ok) +warmup_momentum: 0.8 # (float) warmup initial momentum +warmup_bias_lr: 0.1 # (float) warmup initial bias lr +box: 7.5 # (float) box loss gain +cls: 0.5 # (float) cls loss gain (scale with pixels) +dfl: 1.5 # (float) dfl loss gain +pose: 12.0 # (float) pose loss gain +kobj: 1.0 # (float) keypoint obj loss gain +label_smoothing: 0.0 # (float) label smoothing (fraction) +nbs: 64 # (int) nominal batch size +hsv_h: 0.015 # (float) image HSV-Hue augmentation (fraction) +hsv_s: 0.7 # (float) image HSV-Saturation augmentation (fraction) +hsv_v: 0.4 # (float) image HSV-Value augmentation (fraction) +degrees: 0.0 # (float) image rotation (+/- deg) +translate: 0.1 # (float) image translation (+/- fraction) +scale: 0.5 # (float) image scale (+/- gain) +shear: 0.0 # (float) image shear (+/- deg) +perspective: 0.0 # (float) image perspective (+/- fraction), range 0-0.001 +flipud: 0.0 # (float) image flip up-down (probability) +fliplr: 0.5 # (float) image flip left-right (probability) +bgr: 0.0 # (float) image channel BGR (probability) +mosaic: 1.0 # (float) image mosaic (probability) +mixup: 0.0 # (float) image mixup (probability) +copy_paste: 0.0 # (float) segment copy-paste (probability) +auto_augment: randaugment # (str) auto augmentation policy for classification (randaugment, autoaugment, augmix) +erasing: 0.4 # (float) probability of random erasing during classification training (0-0.9), 0 means no erasing, must be less than 1.0. +crop_fraction: 1.0 # (float) image crop fraction for classification (0.1-1), 1.0 means no crop, must be greater than 0. + +# Custom config.yaml --------------------------------------------------------------------------------------------------- +cfg: # (str, optional) for overriding defaults.yaml + +# Tracker settings ------------------------------------------------------------------------------------------------------ +tracker: botsort.yaml # (str) tracker type, choices=[botsort.yaml, bytetrack.yaml] diff --git a/ultralytics/cfg/models/README.md b/ultralytics/cfg/models/README.md new file mode 100644 index 0000000..c022fb5 --- /dev/null +++ b/ultralytics/cfg/models/README.md @@ -0,0 +1,40 @@ +## Models + +Welcome to the Ultralytics Models directory! Here you will find a wide variety of pre-configured model configuration files (`*.yaml`s) that can be used to create custom YOLO models. The models in this directory have been expertly crafted and fine-tuned by the Ultralytics team to provide the best performance for a wide range of object detection and image segmentation tasks. + +These model configurations cover a wide range of scenarios, from simple object detection to more complex tasks like instance segmentation and object tracking. They are also designed to run efficiently on a variety of hardware platforms, from CPUs to GPUs. Whether you are a seasoned machine learning practitioner or just getting started with YOLO, this directory provides a great starting point for your custom model development needs. + +To get started, simply browse through the models in this directory and find one that best suits your needs. Once you've selected a model, you can use the provided `*.yaml` file to train and deploy your custom YOLO model with ease. See full details at the Ultralytics [Docs](https://docs.ultralytics.com/models), and if you need help or have any questions, feel free to reach out to the Ultralytics team for support. So, don't wait, start creating your custom YOLO model now! + +### Usage + +Model `*.yaml` files may be used directly in the Command Line Interface (CLI) with a `yolo` command: + +```bash +yolo task=detect mode=train model=yolov8n.yaml data=coco128.yaml epochs=100 +``` + +They may also be used directly in a Python environment, and accepts the same [arguments](https://docs.ultralytics.com/usage/cfg/) as in the CLI example above: + +```python +from ultralytics import YOLO + +model = YOLO("model.yaml") # build a YOLOv8n model from scratch +# YOLO("model.pt") use pre-trained model if available +model.info() # display model information +model.train(data="coco128.yaml", epochs=100) # train the model +``` + +## Pre-trained Model Architectures + +Ultralytics supports many model architectures. Visit https://docs.ultralytics.com/models to view detailed information and usage. Any of these models can be used by loading their configs or pretrained checkpoints if available. + +## Contribute New Models + +Have you trained a new YOLO variant or achieved state-of-the-art performance with specific tuning? We'd love to showcase your work in our Models section! Contributions from the community in the form of new models, architectures, or optimizations are highly valued and can significantly enrich our repository. + +By contributing to this section, you're helping us offer a wider array of model choices and configurations to the community. It's a fantastic way to share your knowledge and expertise while making the Ultralytics YOLO ecosystem even more versatile. + +To get started, please consult our [Contributing Guide](https://docs.ultralytics.com/help/contributing) for step-by-step instructions on how to submit a Pull Request (PR) 🛠️. Your contributions are eagerly awaited! + +Let's join hands to extend the range and capabilities of the Ultralytics YOLO models 🙏! diff --git a/ultralytics/cfg/models/rt-detr/rtdetr-l.yaml b/ultralytics/cfg/models/rt-detr/rtdetr-l.yaml new file mode 100644 index 0000000..c6eb0b3 --- /dev/null +++ b/ultralytics/cfg/models/rt-detr/rtdetr-l.yaml @@ -0,0 +1,50 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# RT-DETR-l object detection model with P3-P5 outputs. For details see https://docs.ultralytics.com/models/rtdetr + +# Parameters +nc: 80 # number of classes +scales: # model compound scaling constants, i.e. 'model=yolov8n-cls.yaml' will call yolov8-cls.yaml with scale 'n' + # [depth, width, max_channels] + l: [1.00, 1.00, 1024] + +backbone: + # [from, repeats, module, args] + - [-1, 1, HGStem, [32, 48]] # 0-P2/4 + - [-1, 6, HGBlock, [48, 128, 3]] # stage 1 + + - [-1, 1, DWConv, [128, 3, 2, 1, False]] # 2-P3/8 + - [-1, 6, HGBlock, [96, 512, 3]] # stage 2 + + - [-1, 1, DWConv, [512, 3, 2, 1, False]] # 4-P3/16 + - [-1, 6, HGBlock, [192, 1024, 5, True, False]] # cm, c2, k, light, shortcut + - [-1, 6, HGBlock, [192, 1024, 5, True, True]] + - [-1, 6, HGBlock, [192, 1024, 5, True, True]] # stage 3 + + - [-1, 1, DWConv, [1024, 3, 2, 1, False]] # 8-P4/32 + - [-1, 6, HGBlock, [384, 2048, 5, True, False]] # stage 4 + +head: + - [-1, 1, Conv, [256, 1, 1, None, 1, 1, False]] # 10 input_proj.2 + - [-1, 1, AIFI, [1024, 8]] + - [-1, 1, Conv, [256, 1, 1]] # 12, Y5, lateral_convs.0 + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [7, 1, Conv, [256, 1, 1, None, 1, 1, False]] # 14 input_proj.1 + - [[-2, -1], 1, Concat, [1]] + - [-1, 3, RepC3, [256]] # 16, fpn_blocks.0 + - [-1, 1, Conv, [256, 1, 1]] # 17, Y4, lateral_convs.1 + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [3, 1, Conv, [256, 1, 1, None, 1, 1, False]] # 19 input_proj.0 + - [[-2, -1], 1, Concat, [1]] # cat backbone P4 + - [-1, 3, RepC3, [256]] # X3 (21), fpn_blocks.1 + + - [-1, 1, Conv, [256, 3, 2]] # 22, downsample_convs.0 + - [[-1, 17], 1, Concat, [1]] # cat Y4 + - [-1, 3, RepC3, [256]] # F4 (24), pan_blocks.0 + + - [-1, 1, Conv, [256, 3, 2]] # 25, downsample_convs.1 + - [[-1, 12], 1, Concat, [1]] # cat Y5 + - [-1, 3, RepC3, [256]] # F5 (27), pan_blocks.1 + + - [[21, 24, 27], 1, RTDETRDecoder, [nc]] # Detect(P3, P4, P5) diff --git a/ultralytics/cfg/models/rt-detr/rtdetr-resnet101.yaml b/ultralytics/cfg/models/rt-detr/rtdetr-resnet101.yaml new file mode 100644 index 0000000..a68bb5d --- /dev/null +++ b/ultralytics/cfg/models/rt-detr/rtdetr-resnet101.yaml @@ -0,0 +1,42 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# RT-DETR-ResNet101 object detection model with P3-P5 outputs. + +# Parameters +nc: 80 # number of classes +scales: # model compound scaling constants, i.e. 'model=yolov8n-cls.yaml' will call yolov8-cls.yaml with scale 'n' + # [depth, width, max_channels] + l: [1.00, 1.00, 1024] + +backbone: + # [from, repeats, module, args] + - [-1, 1, ResNetLayer, [3, 64, 1, True, 1]] # 0 + - [-1, 1, ResNetLayer, [64, 64, 1, False, 3]] # 1 + - [-1, 1, ResNetLayer, [256, 128, 2, False, 4]] # 2 + - [-1, 1, ResNetLayer, [512, 256, 2, False, 23]] # 3 + - [-1, 1, ResNetLayer, [1024, 512, 2, False, 3]] # 4 + +head: + - [-1, 1, Conv, [256, 1, 1, None, 1, 1, False]] # 5 + - [-1, 1, AIFI, [1024, 8]] + - [-1, 1, Conv, [256, 1, 1]] # 7 + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [3, 1, Conv, [256, 1, 1, None, 1, 1, False]] # 9 + - [[-2, -1], 1, Concat, [1]] + - [-1, 3, RepC3, [256]] # 11 + - [-1, 1, Conv, [256, 1, 1]] # 12 + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [2, 1, Conv, [256, 1, 1, None, 1, 1, False]] # 14 + - [[-2, -1], 1, Concat, [1]] # cat backbone P4 + - [-1, 3, RepC3, [256]] # X3 (16), fpn_blocks.1 + + - [-1, 1, Conv, [256, 3, 2]] # 17, downsample_convs.0 + - [[-1, 12], 1, Concat, [1]] # cat Y4 + - [-1, 3, RepC3, [256]] # F4 (19), pan_blocks.0 + + - [-1, 1, Conv, [256, 3, 2]] # 20, downsample_convs.1 + - [[-1, 7], 1, Concat, [1]] # cat Y5 + - [-1, 3, RepC3, [256]] # F5 (22), pan_blocks.1 + + - [[16, 19, 22], 1, RTDETRDecoder, [nc]] # Detect(P3, P4, P5) diff --git a/ultralytics/cfg/models/rt-detr/rtdetr-resnet50.yaml b/ultralytics/cfg/models/rt-detr/rtdetr-resnet50.yaml new file mode 100644 index 0000000..7145910 --- /dev/null +++ b/ultralytics/cfg/models/rt-detr/rtdetr-resnet50.yaml @@ -0,0 +1,42 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# RT-DETR-ResNet50 object detection model with P3-P5 outputs. + +# Parameters +nc: 80 # number of classes +scales: # model compound scaling constants, i.e. 'model=yolov8n-cls.yaml' will call yolov8-cls.yaml with scale 'n' + # [depth, width, max_channels] + l: [1.00, 1.00, 1024] + +backbone: + # [from, repeats, module, args] + - [-1, 1, ResNetLayer, [3, 64, 1, True, 1]] # 0 + - [-1, 1, ResNetLayer, [64, 64, 1, False, 3]] # 1 + - [-1, 1, ResNetLayer, [256, 128, 2, False, 4]] # 2 + - [-1, 1, ResNetLayer, [512, 256, 2, False, 6]] # 3 + - [-1, 1, ResNetLayer, [1024, 512, 2, False, 3]] # 4 + +head: + - [-1, 1, Conv, [256, 1, 1, None, 1, 1, False]] # 5 + - [-1, 1, AIFI, [1024, 8]] + - [-1, 1, Conv, [256, 1, 1]] # 7 + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [3, 1, Conv, [256, 1, 1, None, 1, 1, False]] # 9 + - [[-2, -1], 1, Concat, [1]] + - [-1, 3, RepC3, [256]] # 11 + - [-1, 1, Conv, [256, 1, 1]] # 12 + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [2, 1, Conv, [256, 1, 1, None, 1, 1, False]] # 14 + - [[-2, -1], 1, Concat, [1]] # cat backbone P4 + - [-1, 3, RepC3, [256]] # X3 (16), fpn_blocks.1 + + - [-1, 1, Conv, [256, 3, 2]] # 17, downsample_convs.0 + - [[-1, 12], 1, Concat, [1]] # cat Y4 + - [-1, 3, RepC3, [256]] # F4 (19), pan_blocks.0 + + - [-1, 1, Conv, [256, 3, 2]] # 20, downsample_convs.1 + - [[-1, 7], 1, Concat, [1]] # cat Y5 + - [-1, 3, RepC3, [256]] # F5 (22), pan_blocks.1 + + - [[16, 19, 22], 1, RTDETRDecoder, [nc]] # Detect(P3, P4, P5) diff --git a/ultralytics/cfg/models/rt-detr/rtdetr-x.yaml b/ultralytics/cfg/models/rt-detr/rtdetr-x.yaml new file mode 100644 index 0000000..0e819b0 --- /dev/null +++ b/ultralytics/cfg/models/rt-detr/rtdetr-x.yaml @@ -0,0 +1,54 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# RT-DETR-x object detection model with P3-P5 outputs. For details see https://docs.ultralytics.com/models/rtdetr + +# Parameters +nc: 80 # number of classes +scales: # model compound scaling constants, i.e. 'model=yolov8n-cls.yaml' will call yolov8-cls.yaml with scale 'n' + # [depth, width, max_channels] + x: [1.00, 1.00, 2048] + +backbone: + # [from, repeats, module, args] + - [-1, 1, HGStem, [32, 64]] # 0-P2/4 + - [-1, 6, HGBlock, [64, 128, 3]] # stage 1 + + - [-1, 1, DWConv, [128, 3, 2, 1, False]] # 2-P3/8 + - [-1, 6, HGBlock, [128, 512, 3]] + - [-1, 6, HGBlock, [128, 512, 3, False, True]] # 4-stage 2 + + - [-1, 1, DWConv, [512, 3, 2, 1, False]] # 5-P3/16 + - [-1, 6, HGBlock, [256, 1024, 5, True, False]] # cm, c2, k, light, shortcut + - [-1, 6, HGBlock, [256, 1024, 5, True, True]] + - [-1, 6, HGBlock, [256, 1024, 5, True, True]] + - [-1, 6, HGBlock, [256, 1024, 5, True, True]] + - [-1, 6, HGBlock, [256, 1024, 5, True, True]] # 10-stage 3 + + - [-1, 1, DWConv, [1024, 3, 2, 1, False]] # 11-P4/32 + - [-1, 6, HGBlock, [512, 2048, 5, True, False]] + - [-1, 6, HGBlock, [512, 2048, 5, True, True]] # 13-stage 4 + +head: + - [-1, 1, Conv, [384, 1, 1, None, 1, 1, False]] # 14 input_proj.2 + - [-1, 1, AIFI, [2048, 8]] + - [-1, 1, Conv, [384, 1, 1]] # 16, Y5, lateral_convs.0 + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [10, 1, Conv, [384, 1, 1, None, 1, 1, False]] # 18 input_proj.1 + - [[-2, -1], 1, Concat, [1]] + - [-1, 3, RepC3, [384]] # 20, fpn_blocks.0 + - [-1, 1, Conv, [384, 1, 1]] # 21, Y4, lateral_convs.1 + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [4, 1, Conv, [384, 1, 1, None, 1, 1, False]] # 23 input_proj.0 + - [[-2, -1], 1, Concat, [1]] # cat backbone P4 + - [-1, 3, RepC3, [384]] # X3 (25), fpn_blocks.1 + + - [-1, 1, Conv, [384, 3, 2]] # 26, downsample_convs.0 + - [[-1, 21], 1, Concat, [1]] # cat Y4 + - [-1, 3, RepC3, [384]] # F4 (28), pan_blocks.0 + + - [-1, 1, Conv, [384, 3, 2]] # 29, downsample_convs.1 + - [[-1, 16], 1, Concat, [1]] # cat Y5 + - [-1, 3, RepC3, [384]] # F5 (31), pan_blocks.1 + + - [[25, 28, 31], 1, RTDETRDecoder, [nc]] # Detect(P3, P4, P5) diff --git a/ultralytics/cfg/models/v3/yolov3-spp.yaml b/ultralytics/cfg/models/v3/yolov3-spp.yaml new file mode 100644 index 0000000..6724f4e --- /dev/null +++ b/ultralytics/cfg/models/v3/yolov3-spp.yaml @@ -0,0 +1,46 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# YOLOv3-SPP object detection model with P3-P5 outputs. For details see https://docs.ultralytics.com/models/yolov3 + +# Parameters +nc: 80 # number of classes +depth_multiple: 1.0 # model depth multiple +width_multiple: 1.0 # layer channel multiple + +# darknet53 backbone +backbone: + # [from, number, module, args] + - [-1, 1, Conv, [32, 3, 1]] # 0 + - [-1, 1, Conv, [64, 3, 2]] # 1-P1/2 + - [-1, 1, Bottleneck, [64]] + - [-1, 1, Conv, [128, 3, 2]] # 3-P2/4 + - [-1, 2, Bottleneck, [128]] + - [-1, 1, Conv, [256, 3, 2]] # 5-P3/8 + - [-1, 8, Bottleneck, [256]] + - [-1, 1, Conv, [512, 3, 2]] # 7-P4/16 + - [-1, 8, Bottleneck, [512]] + - [-1, 1, Conv, [1024, 3, 2]] # 9-P5/32 + - [-1, 4, Bottleneck, [1024]] # 10 + +# YOLOv3-SPP head +head: + - [-1, 1, Bottleneck, [1024, False]] + - [-1, 1, SPP, [512, [5, 9, 13]]] + - [-1, 1, Conv, [1024, 3, 1]] + - [-1, 1, Conv, [512, 1, 1]] + - [-1, 1, Conv, [1024, 3, 1]] # 15 (P5/32-large) + + - [-2, 1, Conv, [256, 1, 1]] + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 8], 1, Concat, [1]] # cat backbone P4 + - [-1, 1, Bottleneck, [512, False]] + - [-1, 1, Bottleneck, [512, False]] + - [-1, 1, Conv, [256, 1, 1]] + - [-1, 1, Conv, [512, 3, 1]] # 22 (P4/16-medium) + + - [-2, 1, Conv, [128, 1, 1]] + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 6], 1, Concat, [1]] # cat backbone P3 + - [-1, 1, Bottleneck, [256, False]] + - [-1, 2, Bottleneck, [256, False]] # 27 (P3/8-small) + + - [[27, 22, 15], 1, Detect, [nc]] # Detect(P3, P4, P5) diff --git a/ultralytics/cfg/models/v3/yolov3-tiny.yaml b/ultralytics/cfg/models/v3/yolov3-tiny.yaml new file mode 100644 index 0000000..f3fe257 --- /dev/null +++ b/ultralytics/cfg/models/v3/yolov3-tiny.yaml @@ -0,0 +1,37 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# YOLOv3-tiny object detection model with P4-P5 outputs. For details see https://docs.ultralytics.com/models/yolov3 + +# Parameters +nc: 80 # number of classes +depth_multiple: 1.0 # model depth multiple +width_multiple: 1.0 # layer channel multiple + +# YOLOv3-tiny backbone +backbone: + # [from, number, module, args] + - [-1, 1, Conv, [16, 3, 1]] # 0 + - [-1, 1, nn.MaxPool2d, [2, 2, 0]] # 1-P1/2 + - [-1, 1, Conv, [32, 3, 1]] + - [-1, 1, nn.MaxPool2d, [2, 2, 0]] # 3-P2/4 + - [-1, 1, Conv, [64, 3, 1]] + - [-1, 1, nn.MaxPool2d, [2, 2, 0]] # 5-P3/8 + - [-1, 1, Conv, [128, 3, 1]] + - [-1, 1, nn.MaxPool2d, [2, 2, 0]] # 7-P4/16 + - [-1, 1, Conv, [256, 3, 1]] + - [-1, 1, nn.MaxPool2d, [2, 2, 0]] # 9-P5/32 + - [-1, 1, Conv, [512, 3, 1]] + - [-1, 1, nn.ZeroPad2d, [[0, 1, 0, 1]]] # 11 + - [-1, 1, nn.MaxPool2d, [2, 1, 0]] # 12 + +# YOLOv3-tiny head +head: + - [-1, 1, Conv, [1024, 3, 1]] + - [-1, 1, Conv, [256, 1, 1]] + - [-1, 1, Conv, [512, 3, 1]] # 15 (P5/32-large) + + - [-2, 1, Conv, [128, 1, 1]] + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 8], 1, Concat, [1]] # cat backbone P4 + - [-1, 1, Conv, [256, 3, 1]] # 19 (P4/16-medium) + + - [[19, 15], 1, Detect, [nc]] # Detect(P4, P5) diff --git a/ultralytics/cfg/models/v3/yolov3.yaml b/ultralytics/cfg/models/v3/yolov3.yaml new file mode 100644 index 0000000..716866a --- /dev/null +++ b/ultralytics/cfg/models/v3/yolov3.yaml @@ -0,0 +1,46 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# YOLOv3 object detection model with P3-P5 outputs. For details see https://docs.ultralytics.com/models/yolov3 + +# Parameters +nc: 80 # number of classes +depth_multiple: 1.0 # model depth multiple +width_multiple: 1.0 # layer channel multiple + +# darknet53 backbone +backbone: + # [from, number, module, args] + - [-1, 1, Conv, [32, 3, 1]] # 0 + - [-1, 1, Conv, [64, 3, 2]] # 1-P1/2 + - [-1, 1, Bottleneck, [64]] + - [-1, 1, Conv, [128, 3, 2]] # 3-P2/4 + - [-1, 2, Bottleneck, [128]] + - [-1, 1, Conv, [256, 3, 2]] # 5-P3/8 + - [-1, 8, Bottleneck, [256]] + - [-1, 1, Conv, [512, 3, 2]] # 7-P4/16 + - [-1, 8, Bottleneck, [512]] + - [-1, 1, Conv, [1024, 3, 2]] # 9-P5/32 + - [-1, 4, Bottleneck, [1024]] # 10 + +# YOLOv3 head +head: + - [-1, 1, Bottleneck, [1024, False]] + - [-1, 1, Conv, [512, 1, 1]] + - [-1, 1, Conv, [1024, 3, 1]] + - [-1, 1, Conv, [512, 1, 1]] + - [-1, 1, Conv, [1024, 3, 1]] # 15 (P5/32-large) + + - [-2, 1, Conv, [256, 1, 1]] + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 8], 1, Concat, [1]] # cat backbone P4 + - [-1, 1, Bottleneck, [512, False]] + - [-1, 1, Bottleneck, [512, False]] + - [-1, 1, Conv, [256, 1, 1]] + - [-1, 1, Conv, [512, 3, 1]] # 22 (P4/16-medium) + + - [-2, 1, Conv, [128, 1, 1]] + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 6], 1, Concat, [1]] # cat backbone P3 + - [-1, 1, Bottleneck, [256, False]] + - [-1, 2, Bottleneck, [256, False]] # 27 (P3/8-small) + + - [[27, 22, 15], 1, Detect, [nc]] # Detect(P3, P4, P5) diff --git a/ultralytics/cfg/models/v5/yolov5-p6.yaml b/ultralytics/cfg/models/v5/yolov5-p6.yaml new file mode 100644 index 0000000..2fd3ac7 --- /dev/null +++ b/ultralytics/cfg/models/v5/yolov5-p6.yaml @@ -0,0 +1,59 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# YOLOv5 object detection model with P3-P6 outputs. For details see https://docs.ultralytics.com/models/yolov5 + +# Parameters +nc: 80 # number of classes +scales: # model compound scaling constants, i.e. 'model=yolov5n-p6.yaml' will call yolov5-p6.yaml with scale 'n' + # [depth, width, max_channels] + n: [0.33, 0.25, 1024] + s: [0.33, 0.50, 1024] + m: [0.67, 0.75, 1024] + l: [1.00, 1.00, 1024] + x: [1.33, 1.25, 1024] + +# YOLOv5 v6.0 backbone +backbone: + # [from, number, module, args] + - [-1, 1, Conv, [64, 6, 2, 2]] # 0-P1/2 + - [-1, 1, Conv, [128, 3, 2]] # 1-P2/4 + - [-1, 3, C3, [128]] + - [-1, 1, Conv, [256, 3, 2]] # 3-P3/8 + - [-1, 6, C3, [256]] + - [-1, 1, Conv, [512, 3, 2]] # 5-P4/16 + - [-1, 9, C3, [512]] + - [-1, 1, Conv, [768, 3, 2]] # 7-P5/32 + - [-1, 3, C3, [768]] + - [-1, 1, Conv, [1024, 3, 2]] # 9-P6/64 + - [-1, 3, C3, [1024]] + - [-1, 1, SPPF, [1024, 5]] # 11 + +# YOLOv5 v6.0 head +head: + - [-1, 1, Conv, [768, 1, 1]] + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 8], 1, Concat, [1]] # cat backbone P5 + - [-1, 3, C3, [768, False]] # 15 + + - [-1, 1, Conv, [512, 1, 1]] + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 6], 1, Concat, [1]] # cat backbone P4 + - [-1, 3, C3, [512, False]] # 19 + + - [-1, 1, Conv, [256, 1, 1]] + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 4], 1, Concat, [1]] # cat backbone P3 + - [-1, 3, C3, [256, False]] # 23 (P3/8-small) + + - [-1, 1, Conv, [256, 3, 2]] + - [[-1, 20], 1, Concat, [1]] # cat head P4 + - [-1, 3, C3, [512, False]] # 26 (P4/16-medium) + + - [-1, 1, Conv, [512, 3, 2]] + - [[-1, 16], 1, Concat, [1]] # cat head P5 + - [-1, 3, C3, [768, False]] # 29 (P5/32-large) + + - [-1, 1, Conv, [768, 3, 2]] + - [[-1, 12], 1, Concat, [1]] # cat head P6 + - [-1, 3, C3, [1024, False]] # 32 (P6/64-xlarge) + + - [[23, 26, 29, 32], 1, Detect, [nc]] # Detect(P3, P4, P5, P6) diff --git a/ultralytics/cfg/models/v5/yolov5.yaml b/ultralytics/cfg/models/v5/yolov5.yaml new file mode 100644 index 0000000..8fdc79e --- /dev/null +++ b/ultralytics/cfg/models/v5/yolov5.yaml @@ -0,0 +1,48 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# YOLOv5 object detection model with P3-P5 outputs. For details see https://docs.ultralytics.com/models/yolov5 + +# Parameters +nc: 80 # number of classes +scales: # model compound scaling constants, i.e. 'model=yolov5n.yaml' will call yolov5.yaml with scale 'n' + # [depth, width, max_channels] + n: [0.33, 0.25, 1024] + s: [0.33, 0.50, 1024] + m: [0.67, 0.75, 1024] + l: [1.00, 1.00, 1024] + x: [1.33, 1.25, 1024] + +# YOLOv5 v6.0 backbone +backbone: + # [from, number, module, args] + - [-1, 1, Conv, [64, 6, 2, 2]] # 0-P1/2 + - [-1, 1, Conv, [128, 3, 2]] # 1-P2/4 + - [-1, 3, C3, [128]] + - [-1, 1, Conv, [256, 3, 2]] # 3-P3/8 + - [-1, 6, C3, [256]] + - [-1, 1, Conv, [512, 3, 2]] # 5-P4/16 + - [-1, 9, C3, [512]] + - [-1, 1, Conv, [1024, 3, 2]] # 7-P5/32 + - [-1, 3, C3, [1024]] + - [-1, 1, SPPF, [1024, 5]] # 9 + +# YOLOv5 v6.0 head +head: + - [-1, 1, Conv, [512, 1, 1]] + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 6], 1, Concat, [1]] # cat backbone P4 + - [-1, 3, C3, [512, False]] # 13 + + - [-1, 1, Conv, [256, 1, 1]] + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 4], 1, Concat, [1]] # cat backbone P3 + - [-1, 3, C3, [256, False]] # 17 (P3/8-small) + + - [-1, 1, Conv, [256, 3, 2]] + - [[-1, 14], 1, Concat, [1]] # cat head P4 + - [-1, 3, C3, [512, False]] # 20 (P4/16-medium) + + - [-1, 1, Conv, [512, 3, 2]] + - [[-1, 10], 1, Concat, [1]] # cat head P5 + - [-1, 3, C3, [1024, False]] # 23 (P5/32-large) + + - [[17, 20, 23], 1, Detect, [nc]] # Detect(P3, P4, P5) diff --git a/ultralytics/cfg/models/v6/yolov6.yaml b/ultralytics/cfg/models/v6/yolov6.yaml new file mode 100644 index 0000000..f39dfb4 --- /dev/null +++ b/ultralytics/cfg/models/v6/yolov6.yaml @@ -0,0 +1,53 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# YOLOv6 object detection model with P3-P5 outputs. For Usage examples see https://docs.ultralytics.com/models/yolov6 + +# Parameters +nc: 80 # number of classes +activation: nn.ReLU() # (optional) model default activation function +scales: # model compound scaling constants, i.e. 'model=yolov6n.yaml' will call yolov8.yaml with scale 'n' + # [depth, width, max_channels] + n: [0.33, 0.25, 1024] + s: [0.33, 0.50, 1024] + m: [0.67, 0.75, 768] + l: [1.00, 1.00, 512] + x: [1.00, 1.25, 512] + +# YOLOv6-3.0s backbone +backbone: + # [from, repeats, module, args] + - [-1, 1, Conv, [64, 3, 2]] # 0-P1/2 + - [-1, 1, Conv, [128, 3, 2]] # 1-P2/4 + - [-1, 6, Conv, [128, 3, 1]] + - [-1, 1, Conv, [256, 3, 2]] # 3-P3/8 + - [-1, 12, Conv, [256, 3, 1]] + - [-1, 1, Conv, [512, 3, 2]] # 5-P4/16 + - [-1, 18, Conv, [512, 3, 1]] + - [-1, 1, Conv, [1024, 3, 2]] # 7-P5/32 + - [-1, 6, Conv, [1024, 3, 1]] + - [-1, 1, SPPF, [1024, 5]] # 9 + +# YOLOv6-3.0s head +head: + - [-1, 1, Conv, [256, 1, 1]] + - [-1, 1, nn.ConvTranspose2d, [256, 2, 2, 0]] + - [[-1, 6], 1, Concat, [1]] # cat backbone P4 + - [-1, 1, Conv, [256, 3, 1]] + - [-1, 9, Conv, [256, 3, 1]] # 14 + + - [-1, 1, Conv, [128, 1, 1]] + - [-1, 1, nn.ConvTranspose2d, [128, 2, 2, 0]] + - [[-1, 4], 1, Concat, [1]] # cat backbone P3 + - [-1, 1, Conv, [128, 3, 1]] + - [-1, 9, Conv, [128, 3, 1]] # 19 + + - [-1, 1, Conv, [128, 3, 2]] + - [[-1, 15], 1, Concat, [1]] # cat head P4 + - [-1, 1, Conv, [256, 3, 1]] + - [-1, 9, Conv, [256, 3, 1]] # 23 + + - [-1, 1, Conv, [256, 3, 2]] + - [[-1, 10], 1, Concat, [1]] # cat head P5 + - [-1, 1, Conv, [512, 3, 1]] + - [-1, 9, Conv, [512, 3, 1]] # 27 + + - [[19, 23, 27], 1, Detect, [nc]] # Detect(P3, P4, P5) diff --git a/ultralytics/cfg/models/v8/yolov8-cls-resnet101.yaml b/ultralytics/cfg/models/v8/yolov8-cls-resnet101.yaml new file mode 100644 index 0000000..6867f88 --- /dev/null +++ b/ultralytics/cfg/models/v8/yolov8-cls-resnet101.yaml @@ -0,0 +1,25 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# YOLOv8-cls image classification model. For Usage examples see https://docs.ultralytics.com/tasks/classify + +# Parameters +nc: 1000 # number of classes +scales: # model compound scaling constants, i.e. 'model=yolov8n-cls.yaml' will call yolov8-cls.yaml with scale 'n' + # [depth, width, max_channels] + n: [0.33, 0.25, 1024] + s: [0.33, 0.50, 1024] + m: [0.67, 0.75, 1024] + l: [1.00, 1.00, 1024] + x: [1.00, 1.25, 1024] + +# YOLOv8.0n backbone +backbone: + # [from, repeats, module, args] + - [-1, 1, ResNetLayer, [3, 64, 1, True, 1]] # 0-P1/2 + - [-1, 1, ResNetLayer, [64, 64, 1, False, 3]] # 1-P2/4 + - [-1, 1, ResNetLayer, [256, 128, 2, False, 4]] # 2-P3/8 + - [-1, 1, ResNetLayer, [512, 256, 2, False, 23]] # 3-P4/16 + - [-1, 1, ResNetLayer, [1024, 512, 2, False, 3]] # 4-P5/32 + +# YOLOv8.0n head +head: + - [-1, 1, Classify, [nc]] # Classify diff --git a/ultralytics/cfg/models/v8/yolov8-cls-resnet50.yaml b/ultralytics/cfg/models/v8/yolov8-cls-resnet50.yaml new file mode 100644 index 0000000..8ffd111 --- /dev/null +++ b/ultralytics/cfg/models/v8/yolov8-cls-resnet50.yaml @@ -0,0 +1,25 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# YOLOv8-cls image classification model. For Usage examples see https://docs.ultralytics.com/tasks/classify + +# Parameters +nc: 1000 # number of classes +scales: # model compound scaling constants, i.e. 'model=yolov8n-cls.yaml' will call yolov8-cls.yaml with scale 'n' + # [depth, width, max_channels] + n: [0.33, 0.25, 1024] + s: [0.33, 0.50, 1024] + m: [0.67, 0.75, 1024] + l: [1.00, 1.00, 1024] + x: [1.00, 1.25, 1024] + +# YOLOv8.0n backbone +backbone: + # [from, repeats, module, args] + - [-1, 1, ResNetLayer, [3, 64, 1, True, 1]] # 0-P1/2 + - [-1, 1, ResNetLayer, [64, 64, 1, False, 3]] # 1-P2/4 + - [-1, 1, ResNetLayer, [256, 128, 2, False, 4]] # 2-P3/8 + - [-1, 1, ResNetLayer, [512, 256, 2, False, 6]] # 3-P4/16 + - [-1, 1, ResNetLayer, [1024, 512, 2, False, 3]] # 4-P5/32 + +# YOLOv8.0n head +head: + - [-1, 1, Classify, [nc]] # Classify diff --git a/ultralytics/cfg/models/v8/yolov8-cls.yaml b/ultralytics/cfg/models/v8/yolov8-cls.yaml new file mode 100644 index 0000000..180fc65 --- /dev/null +++ b/ultralytics/cfg/models/v8/yolov8-cls.yaml @@ -0,0 +1,29 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# YOLOv8-cls image classification model. For Usage examples see https://docs.ultralytics.com/tasks/classify + +# Parameters +nc: 1000 # number of classes +scales: # model compound scaling constants, i.e. 'model=yolov8n-cls.yaml' will call yolov8-cls.yaml with scale 'n' + # [depth, width, max_channels] + n: [0.33, 0.25, 1024] + s: [0.33, 0.50, 1024] + m: [0.67, 0.75, 1024] + l: [1.00, 1.00, 1024] + x: [1.00, 1.25, 1024] + +# YOLOv8.0n backbone +backbone: + # [from, repeats, module, args] + - [-1, 1, Conv, [64, 3, 2]] # 0-P1/2 + - [-1, 1, Conv, [128, 3, 2]] # 1-P2/4 + - [-1, 3, C2f, [128, True]] + - [-1, 1, Conv, [256, 3, 2]] # 3-P3/8 + - [-1, 6, C2f, [256, True]] + - [-1, 1, Conv, [512, 3, 2]] # 5-P4/16 + - [-1, 6, C2f, [512, True]] + - [-1, 1, Conv, [1024, 3, 2]] # 7-P5/32 + - [-1, 3, C2f, [1024, True]] + +# YOLOv8.0n head +head: + - [-1, 1, Classify, [nc]] # Classify diff --git a/ultralytics/cfg/models/v8/yolov8-ghost-p2.yaml b/ultralytics/cfg/models/v8/yolov8-ghost-p2.yaml new file mode 100644 index 0000000..aee2093 --- /dev/null +++ b/ultralytics/cfg/models/v8/yolov8-ghost-p2.yaml @@ -0,0 +1,54 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# YOLOv8 object detection model with P2-P5 outputs. For Usage examples see https://docs.ultralytics.com/tasks/detect + +# Parameters +nc: 80 # number of classes +scales: # model compound scaling constants, i.e. 'model=yolov8n.yaml' will call yolov8.yaml with scale 'n' + # [depth, width, max_channels] + n: [0.33, 0.25, 1024] # YOLOv8n-ghost-p2 summary: 491 layers, 2033944 parameters, 2033928 gradients, 13.8 GFLOPs + s: [0.33, 0.50, 1024] # YOLOv8s-ghost-p2 summary: 491 layers, 5562080 parameters, 5562064 gradients, 25.1 GFLOPs + m: [0.67, 0.75, 768] # YOLOv8m-ghost-p2 summary: 731 layers, 9031728 parameters, 9031712 gradients, 42.8 GFLOPs + l: [1.00, 1.00, 512] # YOLOv8l-ghost-p2 summary: 971 layers, 12214448 parameters, 12214432 gradients, 69.1 GFLOPs + x: [1.00, 1.25, 512] # YOLOv8x-ghost-p2 summary: 971 layers, 18664776 parameters, 18664760 gradients, 103.3 GFLOPs + +# YOLOv8.0-ghost backbone +backbone: + # [from, repeats, module, args] + - [-1, 1, Conv, [64, 3, 2]] # 0-P1/2 + - [-1, 1, GhostConv, [128, 3, 2]] # 1-P2/4 + - [-1, 3, C3Ghost, [128, True]] + - [-1, 1, GhostConv, [256, 3, 2]] # 3-P3/8 + - [-1, 6, C3Ghost, [256, True]] + - [-1, 1, GhostConv, [512, 3, 2]] # 5-P4/16 + - [-1, 6, C3Ghost, [512, True]] + - [-1, 1, GhostConv, [1024, 3, 2]] # 7-P5/32 + - [-1, 3, C3Ghost, [1024, True]] + - [-1, 1, SPPF, [1024, 5]] # 9 + +# YOLOv8.0-ghost-p2 head +head: + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 6], 1, Concat, [1]] # cat backbone P4 + - [-1, 3, C3Ghost, [512]] # 12 + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 4], 1, Concat, [1]] # cat backbone P3 + - [-1, 3, C3Ghost, [256]] # 15 (P3/8-small) + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 2], 1, Concat, [1]] # cat backbone P2 + - [-1, 3, C3Ghost, [128]] # 18 (P2/4-xsmall) + + - [-1, 1, GhostConv, [128, 3, 2]] + - [[-1, 15], 1, Concat, [1]] # cat head P3 + - [-1, 3, C3Ghost, [256]] # 21 (P3/8-small) + + - [-1, 1, GhostConv, [256, 3, 2]] + - [[-1, 12], 1, Concat, [1]] # cat head P4 + - [-1, 3, C3Ghost, [512]] # 24 (P4/16-medium) + + - [-1, 1, GhostConv, [512, 3, 2]] + - [[-1, 9], 1, Concat, [1]] # cat head P5 + - [-1, 3, C3Ghost, [1024]] # 27 (P5/32-large) + + - [[18, 21, 24, 27], 1, Detect, [nc]] # Detect(P2, P3, P4, P5) diff --git a/ultralytics/cfg/models/v8/yolov8-ghost-p6.yaml b/ultralytics/cfg/models/v8/yolov8-ghost-p6.yaml new file mode 100644 index 0000000..b35f4cd --- /dev/null +++ b/ultralytics/cfg/models/v8/yolov8-ghost-p6.yaml @@ -0,0 +1,56 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# YOLOv8 object detection model with P3-P6 outputs. For Usage examples see https://docs.ultralytics.com/tasks/detect + +# Parameters +nc: 80 # number of classes +scales: # model compound scaling constants, i.e. 'model=yolov8n-p6.yaml' will call yolov8-p6.yaml with scale 'n' + # [depth, width, max_channels] + n: [0.33, 0.25, 1024] # YOLOv8n-ghost-p6 summary: 529 layers, 2901100 parameters, 2901084 gradients, 5.8 GFLOPs + s: [0.33, 0.50, 1024] # YOLOv8s-ghost-p6 summary: 529 layers, 9520008 parameters, 9519992 gradients, 16.4 GFLOPs + m: [0.67, 0.75, 768] # YOLOv8m-ghost-p6 summary: 789 layers, 18002904 parameters, 18002888 gradients, 34.4 GFLOPs + l: [1.00, 1.00, 512] # YOLOv8l-ghost-p6 summary: 1049 layers, 21227584 parameters, 21227568 gradients, 55.3 GFLOPs + x: [1.00, 1.25, 512] # YOLOv8x-ghost-p6 summary: 1049 layers, 33057852 parameters, 33057836 gradients, 85.7 GFLOPs + +# YOLOv8.0-ghost backbone +backbone: + # [from, repeats, module, args] + - [-1, 1, Conv, [64, 3, 2]] # 0-P1/2 + - [-1, 1, GhostConv, [128, 3, 2]] # 1-P2/4 + - [-1, 3, C3Ghost, [128, True]] + - [-1, 1, GhostConv, [256, 3, 2]] # 3-P3/8 + - [-1, 6, C3Ghost, [256, True]] + - [-1, 1, GhostConv, [512, 3, 2]] # 5-P4/16 + - [-1, 6, C3Ghost, [512, True]] + - [-1, 1, GhostConv, [768, 3, 2]] # 7-P5/32 + - [-1, 3, C3Ghost, [768, True]] + - [-1, 1, GhostConv, [1024, 3, 2]] # 9-P6/64 + - [-1, 3, C3Ghost, [1024, True]] + - [-1, 1, SPPF, [1024, 5]] # 11 + +# YOLOv8.0-ghost-p6 head +head: + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 8], 1, Concat, [1]] # cat backbone P5 + - [-1, 3, C3Ghost, [768]] # 14 + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 6], 1, Concat, [1]] # cat backbone P4 + - [-1, 3, C3Ghost, [512]] # 17 + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 4], 1, Concat, [1]] # cat backbone P3 + - [-1, 3, C3Ghost, [256]] # 20 (P3/8-small) + + - [-1, 1, GhostConv, [256, 3, 2]] + - [[-1, 17], 1, Concat, [1]] # cat head P4 + - [-1, 3, C3Ghost, [512]] # 23 (P4/16-medium) + + - [-1, 1, GhostConv, [512, 3, 2]] + - [[-1, 14], 1, Concat, [1]] # cat head P5 + - [-1, 3, C3Ghost, [768]] # 26 (P5/32-large) + + - [-1, 1, GhostConv, [768, 3, 2]] + - [[-1, 11], 1, Concat, [1]] # cat head P6 + - [-1, 3, C3Ghost, [1024]] # 29 (P6/64-xlarge) + + - [[20, 23, 26, 29], 1, Detect, [nc]] # Detect(P3, P4, P5, P6) diff --git a/ultralytics/cfg/models/v8/yolov8-ghost.yaml b/ultralytics/cfg/models/v8/yolov8-ghost.yaml new file mode 100644 index 0000000..adc1802 --- /dev/null +++ b/ultralytics/cfg/models/v8/yolov8-ghost.yaml @@ -0,0 +1,47 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# YOLOv8 object detection model with P3-P5 outputs. For Usage examples see https://docs.ultralytics.com/tasks/detect +# Employs Ghost convolutions and modules proposed in Huawei's GhostNet in https://arxiv.org/abs/1911.11907v2 + +# Parameters +nc: 80 # number of classes +scales: # model compound scaling constants, i.e. 'model=yolov8n.yaml' will call yolov8.yaml with scale 'n' + # [depth, width, max_channels] + n: [0.33, 0.25, 1024] # YOLOv8n-ghost summary: 403 layers, 1865316 parameters, 1865300 gradients, 5.8 GFLOPs + s: [0.33, 0.50, 1024] # YOLOv8s-ghost summary: 403 layers, 5960072 parameters, 5960056 gradients, 16.4 GFLOPs + m: [0.67, 0.75, 768] # YOLOv8m-ghost summary: 603 layers, 10336312 parameters, 10336296 gradients, 32.7 GFLOPs + l: [1.00, 1.00, 512] # YOLOv8l-ghost summary: 803 layers, 14277872 parameters, 14277856 gradients, 53.7 GFLOPs + x: [1.00, 1.25, 512] # YOLOv8x-ghost summary: 803 layers, 22229308 parameters, 22229292 gradients, 83.3 GFLOPs + +# YOLOv8.0n-ghost backbone +backbone: + # [from, repeats, module, args] + - [-1, 1, Conv, [64, 3, 2]] # 0-P1/2 + - [-1, 1, GhostConv, [128, 3, 2]] # 1-P2/4 + - [-1, 3, C3Ghost, [128, True]] + - [-1, 1, GhostConv, [256, 3, 2]] # 3-P3/8 + - [-1, 6, C3Ghost, [256, True]] + - [-1, 1, GhostConv, [512, 3, 2]] # 5-P4/16 + - [-1, 6, C3Ghost, [512, True]] + - [-1, 1, GhostConv, [1024, 3, 2]] # 7-P5/32 + - [-1, 3, C3Ghost, [1024, True]] + - [-1, 1, SPPF, [1024, 5]] # 9 + +# YOLOv8.0n head +head: + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 6], 1, Concat, [1]] # cat backbone P4 + - [-1, 3, C3Ghost, [512]] # 12 + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 4], 1, Concat, [1]] # cat backbone P3 + - [-1, 3, C3Ghost, [256]] # 15 (P3/8-small) + + - [-1, 1, GhostConv, [256, 3, 2]] + - [[-1, 12], 1, Concat, [1]] # cat head P4 + - [-1, 3, C3Ghost, [512]] # 18 (P4/16-medium) + + - [-1, 1, GhostConv, [512, 3, 2]] + - [[-1, 9], 1, Concat, [1]] # cat head P5 + - [-1, 3, C3Ghost, [1024]] # 21 (P5/32-large) + + - [[15, 18, 21], 1, Detect, [nc]] # Detect(P3, P4, P5) diff --git a/ultralytics/cfg/models/v8/yolov8-obb.yaml b/ultralytics/cfg/models/v8/yolov8-obb.yaml new file mode 100644 index 0000000..7a7f60c --- /dev/null +++ b/ultralytics/cfg/models/v8/yolov8-obb.yaml @@ -0,0 +1,46 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# YOLOv8 Oriented Bounding Boxes (OBB) model with P3-P5 outputs. For Usage examples see https://docs.ultralytics.com/tasks/detect + +# Parameters +nc: 80 # number of classes +scales: # model compound scaling constants, i.e. 'model=yolov8n.yaml' will call yolov8.yaml with scale 'n' + # [depth, width, max_channels] + n: [0.33, 0.25, 1024] # YOLOv8n summary: 225 layers, 3157200 parameters, 3157184 gradients, 8.9 GFLOPs + s: [0.33, 0.50, 1024] # YOLOv8s summary: 225 layers, 11166560 parameters, 11166544 gradients, 28.8 GFLOPs + m: [0.67, 0.75, 768] # YOLOv8m summary: 295 layers, 25902640 parameters, 25902624 gradients, 79.3 GFLOPs + l: [1.00, 1.00, 512] # YOLOv8l summary: 365 layers, 43691520 parameters, 43691504 gradients, 165.7 GFLOPs + x: [1.00, 1.25, 512] # YOLOv8x summary: 365 layers, 68229648 parameters, 68229632 gradients, 258.5 GFLOPs + +# YOLOv8.0n backbone +backbone: + # [from, repeats, module, args] + - [-1, 1, Conv, [64, 3, 2]] # 0-P1/2 + - [-1, 1, Conv, [128, 3, 2]] # 1-P2/4 + - [-1, 3, C2f, [128, True]] + - [-1, 1, Conv, [256, 3, 2]] # 3-P3/8 + - [-1, 6, C2f, [256, True]] + - [-1, 1, Conv, [512, 3, 2]] # 5-P4/16 + - [-1, 6, C2f, [512, True]] + - [-1, 1, Conv, [1024, 3, 2]] # 7-P5/32 + - [-1, 3, C2f, [1024, True]] + - [-1, 1, SPPF, [1024, 5]] # 9 + +# YOLOv8.0n head +head: + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 6], 1, Concat, [1]] # cat backbone P4 + - [-1, 3, C2f, [512]] # 12 + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 4], 1, Concat, [1]] # cat backbone P3 + - [-1, 3, C2f, [256]] # 15 (P3/8-small) + + - [-1, 1, Conv, [256, 3, 2]] + - [[-1, 12], 1, Concat, [1]] # cat head P4 + - [-1, 3, C2f, [512]] # 18 (P4/16-medium) + + - [-1, 1, Conv, [512, 3, 2]] + - [[-1, 9], 1, Concat, [1]] # cat head P5 + - [-1, 3, C2f, [1024]] # 21 (P5/32-large) + + - [[15, 18, 21], 1, OBB, [nc, 1]] # OBB(P3, P4, P5) diff --git a/ultralytics/cfg/models/v8/yolov8-p2.yaml b/ultralytics/cfg/models/v8/yolov8-p2.yaml new file mode 100644 index 0000000..5392774 --- /dev/null +++ b/ultralytics/cfg/models/v8/yolov8-p2.yaml @@ -0,0 +1,54 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# YOLOv8 object detection model with P2-P5 outputs. For Usage examples see https://docs.ultralytics.com/tasks/detect + +# Parameters +nc: 80 # number of classes +scales: # model compound scaling constants, i.e. 'model=yolov8n.yaml' will call yolov8.yaml with scale 'n' + # [depth, width, max_channels] + n: [0.33, 0.25, 1024] + s: [0.33, 0.50, 1024] + m: [0.67, 0.75, 768] + l: [1.00, 1.00, 512] + x: [1.00, 1.25, 512] + +# YOLOv8.0 backbone +backbone: + # [from, repeats, module, args] + - [-1, 1, Conv, [64, 3, 2]] # 0-P1/2 + - [-1, 1, Conv, [128, 3, 2]] # 1-P2/4 + - [-1, 3, C2f, [128, True]] + - [-1, 1, Conv, [256, 3, 2]] # 3-P3/8 + - [-1, 6, C2f, [256, True]] + - [-1, 1, Conv, [512, 3, 2]] # 5-P4/16 + - [-1, 6, C2f, [512, True]] + - [-1, 1, Conv, [1024, 3, 2]] # 7-P5/32 + - [-1, 3, C2f, [1024, True]] + - [-1, 1, SPPF, [1024, 5]] # 9 + +# YOLOv8.0-p2 head +head: + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 6], 1, Concat, [1]] # cat backbone P4 + - [-1, 3, C2f, [512]] # 12 + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 4], 1, Concat, [1]] # cat backbone P3 + - [-1, 3, C2f, [256]] # 15 (P3/8-small) + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 2], 1, Concat, [1]] # cat backbone P2 + - [-1, 3, C2f, [128]] # 18 (P2/4-xsmall) + + - [-1, 1, Conv, [128, 3, 2]] + - [[-1, 15], 1, Concat, [1]] # cat head P3 + - [-1, 3, C2f, [256]] # 21 (P3/8-small) + + - [-1, 1, Conv, [256, 3, 2]] + - [[-1, 12], 1, Concat, [1]] # cat head P4 + - [-1, 3, C2f, [512]] # 24 (P4/16-medium) + + - [-1, 1, Conv, [512, 3, 2]] + - [[-1, 9], 1, Concat, [1]] # cat head P5 + - [-1, 3, C2f, [1024]] # 27 (P5/32-large) + + - [[18, 21, 24, 27], 1, Detect, [nc]] # Detect(P2, P3, P4, P5) diff --git a/ultralytics/cfg/models/v8/yolov8-p6.yaml b/ultralytics/cfg/models/v8/yolov8-p6.yaml new file mode 100644 index 0000000..2d6d5f9 --- /dev/null +++ b/ultralytics/cfg/models/v8/yolov8-p6.yaml @@ -0,0 +1,56 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# YOLOv8 object detection model with P3-P6 outputs. For Usage examples see https://docs.ultralytics.com/tasks/detect + +# Parameters +nc: 80 # number of classes +scales: # model compound scaling constants, i.e. 'model=yolov8n-p6.yaml' will call yolov8-p6.yaml with scale 'n' + # [depth, width, max_channels] + n: [0.33, 0.25, 1024] + s: [0.33, 0.50, 1024] + m: [0.67, 0.75, 768] + l: [1.00, 1.00, 512] + x: [1.00, 1.25, 512] + +# YOLOv8.0x6 backbone +backbone: + # [from, repeats, module, args] + - [-1, 1, Conv, [64, 3, 2]] # 0-P1/2 + - [-1, 1, Conv, [128, 3, 2]] # 1-P2/4 + - [-1, 3, C2f, [128, True]] + - [-1, 1, Conv, [256, 3, 2]] # 3-P3/8 + - [-1, 6, C2f, [256, True]] + - [-1, 1, Conv, [512, 3, 2]] # 5-P4/16 + - [-1, 6, C2f, [512, True]] + - [-1, 1, Conv, [768, 3, 2]] # 7-P5/32 + - [-1, 3, C2f, [768, True]] + - [-1, 1, Conv, [1024, 3, 2]] # 9-P6/64 + - [-1, 3, C2f, [1024, True]] + - [-1, 1, SPPF, [1024, 5]] # 11 + +# YOLOv8.0x6 head +head: + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 8], 1, Concat, [1]] # cat backbone P5 + - [-1, 3, C2, [768, False]] # 14 + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 6], 1, Concat, [1]] # cat backbone P4 + - [-1, 3, C2, [512, False]] # 17 + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 4], 1, Concat, [1]] # cat backbone P3 + - [-1, 3, C2, [256, False]] # 20 (P3/8-small) + + - [-1, 1, Conv, [256, 3, 2]] + - [[-1, 17], 1, Concat, [1]] # cat head P4 + - [-1, 3, C2, [512, False]] # 23 (P4/16-medium) + + - [-1, 1, Conv, [512, 3, 2]] + - [[-1, 14], 1, Concat, [1]] # cat head P5 + - [-1, 3, C2, [768, False]] # 26 (P5/32-large) + + - [-1, 1, Conv, [768, 3, 2]] + - [[-1, 11], 1, Concat, [1]] # cat head P6 + - [-1, 3, C2, [1024, False]] # 29 (P6/64-xlarge) + + - [[20, 23, 26, 29], 1, Detect, [nc]] # Detect(P3, P4, P5, P6) diff --git a/ultralytics/cfg/models/v8/yolov8-pose-p6.yaml b/ultralytics/cfg/models/v8/yolov8-pose-p6.yaml new file mode 100644 index 0000000..60007ac --- /dev/null +++ b/ultralytics/cfg/models/v8/yolov8-pose-p6.yaml @@ -0,0 +1,57 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# YOLOv8-pose-p6 keypoints/pose estimation model. For Usage examples see https://docs.ultralytics.com/tasks/pose + +# Parameters +nc: 1 # number of classes +kpt_shape: [17, 3] # number of keypoints, number of dims (2 for x,y or 3 for x,y,visible) +scales: # model compound scaling constants, i.e. 'model=yolov8n-p6.yaml' will call yolov8-p6.yaml with scale 'n' + # [depth, width, max_channels] + n: [0.33, 0.25, 1024] + s: [0.33, 0.50, 1024] + m: [0.67, 0.75, 768] + l: [1.00, 1.00, 512] + x: [1.00, 1.25, 512] + +# YOLOv8.0x6 backbone +backbone: + # [from, repeats, module, args] + - [-1, 1, Conv, [64, 3, 2]] # 0-P1/2 + - [-1, 1, Conv, [128, 3, 2]] # 1-P2/4 + - [-1, 3, C2f, [128, True]] + - [-1, 1, Conv, [256, 3, 2]] # 3-P3/8 + - [-1, 6, C2f, [256, True]] + - [-1, 1, Conv, [512, 3, 2]] # 5-P4/16 + - [-1, 6, C2f, [512, True]] + - [-1, 1, Conv, [768, 3, 2]] # 7-P5/32 + - [-1, 3, C2f, [768, True]] + - [-1, 1, Conv, [1024, 3, 2]] # 9-P6/64 + - [-1, 3, C2f, [1024, True]] + - [-1, 1, SPPF, [1024, 5]] # 11 + +# YOLOv8.0x6 head +head: + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 8], 1, Concat, [1]] # cat backbone P5 + - [-1, 3, C2, [768, False]] # 14 + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 6], 1, Concat, [1]] # cat backbone P4 + - [-1, 3, C2, [512, False]] # 17 + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 4], 1, Concat, [1]] # cat backbone P3 + - [-1, 3, C2, [256, False]] # 20 (P3/8-small) + + - [-1, 1, Conv, [256, 3, 2]] + - [[-1, 17], 1, Concat, [1]] # cat head P4 + - [-1, 3, C2, [512, False]] # 23 (P4/16-medium) + + - [-1, 1, Conv, [512, 3, 2]] + - [[-1, 14], 1, Concat, [1]] # cat head P5 + - [-1, 3, C2, [768, False]] # 26 (P5/32-large) + + - [-1, 1, Conv, [768, 3, 2]] + - [[-1, 11], 1, Concat, [1]] # cat head P6 + - [-1, 3, C2, [1024, False]] # 29 (P6/64-xlarge) + + - [[20, 23, 26, 29], 1, Pose, [nc, kpt_shape]] # Pose(P3, P4, P5, P6) diff --git a/ultralytics/cfg/models/v8/yolov8-pose.yaml b/ultralytics/cfg/models/v8/yolov8-pose.yaml new file mode 100644 index 0000000..60388ef --- /dev/null +++ b/ultralytics/cfg/models/v8/yolov8-pose.yaml @@ -0,0 +1,47 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# YOLOv8-pose keypoints/pose estimation model. For Usage examples see https://docs.ultralytics.com/tasks/pose + +# Parameters +nc: 1 # number of classes +kpt_shape: [17, 3] # number of keypoints, number of dims (2 for x,y or 3 for x,y,visible) +scales: # model compound scaling constants, i.e. 'model=yolov8n-pose.yaml' will call yolov8-pose.yaml with scale 'n' + # [depth, width, max_channels] + n: [0.33, 0.25, 1024] + s: [0.33, 0.50, 1024] + m: [0.67, 0.75, 768] + l: [1.00, 1.00, 512] + x: [1.00, 1.25, 512] + +# YOLOv8.0n backbone +backbone: + # [from, repeats, module, args] + - [-1, 1, Conv, [64, 3, 2]] # 0-P1/2 + - [-1, 1, Conv, [128, 3, 2]] # 1-P2/4 + - [-1, 3, C2f, [128, True]] + - [-1, 1, Conv, [256, 3, 2]] # 3-P3/8 + - [-1, 6, C2f, [256, True]] + - [-1, 1, Conv, [512, 3, 2]] # 5-P4/16 + - [-1, 6, C2f, [512, True]] + - [-1, 1, Conv, [1024, 3, 2]] # 7-P5/32 + - [-1, 3, C2f, [1024, True]] + - [-1, 1, SPPF, [1024, 5]] # 9 + +# YOLOv8.0n head +head: + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 6], 1, Concat, [1]] # cat backbone P4 + - [-1, 3, C2f, [512]] # 12 + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 4], 1, Concat, [1]] # cat backbone P3 + - [-1, 3, C2f, [256]] # 15 (P3/8-small) + + - [-1, 1, Conv, [256, 3, 2]] + - [[-1, 12], 1, Concat, [1]] # cat head P4 + - [-1, 3, C2f, [512]] # 18 (P4/16-medium) + + - [-1, 1, Conv, [512, 3, 2]] + - [[-1, 9], 1, Concat, [1]] # cat head P5 + - [-1, 3, C2f, [1024]] # 21 (P5/32-large) + + - [[15, 18, 21], 1, Pose, [nc, kpt_shape]] # Pose(P3, P4, P5) diff --git a/ultralytics/cfg/models/v8/yolov8-rtdetr.yaml b/ultralytics/cfg/models/v8/yolov8-rtdetr.yaml new file mode 100644 index 0000000..27b790b --- /dev/null +++ b/ultralytics/cfg/models/v8/yolov8-rtdetr.yaml @@ -0,0 +1,46 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# YOLOv8 object detection model with P3-P5 outputs. For Usage examples see https://docs.ultralytics.com/tasks/detect + +# Parameters +nc: 80 # number of classes +scales: # model compound scaling constants, i.e. 'model=yolov8n.yaml' will call yolov8.yaml with scale 'n' + # [depth, width, max_channels] + n: [0.33, 0.25, 1024] # YOLOv8n summary: 225 layers, 3157200 parameters, 3157184 gradients, 8.9 GFLOPs + s: [0.33, 0.50, 1024] # YOLOv8s summary: 225 layers, 11166560 parameters, 11166544 gradients, 28.8 GFLOPs + m: [0.67, 0.75, 768] # YOLOv8m summary: 295 layers, 25902640 parameters, 25902624 gradients, 79.3 GFLOPs + l: [1.00, 1.00, 512] # YOLOv8l summary: 365 layers, 43691520 parameters, 43691504 gradients, 165.7 GFLOPs + x: [1.00, 1.25, 512] # YOLOv8x summary: 365 layers, 68229648 parameters, 68229632 gradients, 258.5 GFLOPs + +# YOLOv8.0n backbone +backbone: + # [from, repeats, module, args] + - [-1, 1, Conv, [64, 3, 2]] # 0-P1/2 + - [-1, 1, Conv, [128, 3, 2]] # 1-P2/4 + - [-1, 3, C2f, [128, True]] + - [-1, 1, Conv, [256, 3, 2]] # 3-P3/8 + - [-1, 6, C2f, [256, True]] + - [-1, 1, Conv, [512, 3, 2]] # 5-P4/16 + - [-1, 6, C2f, [512, True]] + - [-1, 1, Conv, [1024, 3, 2]] # 7-P5/32 + - [-1, 3, C2f, [1024, True]] + - [-1, 1, SPPF, [1024, 5]] # 9 + +# YOLOv8.0n head +head: + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 6], 1, Concat, [1]] # cat backbone P4 + - [-1, 3, C2f, [512]] # 12 + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 4], 1, Concat, [1]] # cat backbone P3 + - [-1, 3, C2f, [256]] # 15 (P3/8-small) + + - [-1, 1, Conv, [256, 3, 2]] + - [[-1, 12], 1, Concat, [1]] # cat head P4 + - [-1, 3, C2f, [512]] # 18 (P4/16-medium) + + - [-1, 1, Conv, [512, 3, 2]] + - [[-1, 9], 1, Concat, [1]] # cat head P5 + - [-1, 3, C2f, [1024]] # 21 (P5/32-large) + + - [[15, 18, 21], 1, RTDETRDecoder, [nc]] # Detect(P3, P4, P5) diff --git a/ultralytics/cfg/models/v8/yolov8-seg-p6.yaml b/ultralytics/cfg/models/v8/yolov8-seg-p6.yaml new file mode 100644 index 0000000..78c0444 --- /dev/null +++ b/ultralytics/cfg/models/v8/yolov8-seg-p6.yaml @@ -0,0 +1,56 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# YOLOv8-seg-p6 instance segmentation model. For Usage examples see https://docs.ultralytics.com/tasks/segment + +# Parameters +nc: 80 # number of classes +scales: # model compound scaling constants, i.e. 'model=yolov8n-seg-p6.yaml' will call yolov8-seg-p6.yaml with scale 'n' + # [depth, width, max_channels] + n: [0.33, 0.25, 1024] + s: [0.33, 0.50, 1024] + m: [0.67, 0.75, 768] + l: [1.00, 1.00, 512] + x: [1.00, 1.25, 512] + +# YOLOv8.0x6 backbone +backbone: + # [from, repeats, module, args] + - [-1, 1, Conv, [64, 3, 2]] # 0-P1/2 + - [-1, 1, Conv, [128, 3, 2]] # 1-P2/4 + - [-1, 3, C2f, [128, True]] + - [-1, 1, Conv, [256, 3, 2]] # 3-P3/8 + - [-1, 6, C2f, [256, True]] + - [-1, 1, Conv, [512, 3, 2]] # 5-P4/16 + - [-1, 6, C2f, [512, True]] + - [-1, 1, Conv, [768, 3, 2]] # 7-P5/32 + - [-1, 3, C2f, [768, True]] + - [-1, 1, Conv, [1024, 3, 2]] # 9-P6/64 + - [-1, 3, C2f, [1024, True]] + - [-1, 1, SPPF, [1024, 5]] # 11 + +# YOLOv8.0x6 head +head: + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 8], 1, Concat, [1]] # cat backbone P5 + - [-1, 3, C2, [768, False]] # 14 + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 6], 1, Concat, [1]] # cat backbone P4 + - [-1, 3, C2, [512, False]] # 17 + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 4], 1, Concat, [1]] # cat backbone P3 + - [-1, 3, C2, [256, False]] # 20 (P3/8-small) + + - [-1, 1, Conv, [256, 3, 2]] + - [[-1, 17], 1, Concat, [1]] # cat head P4 + - [-1, 3, C2, [512, False]] # 23 (P4/16-medium) + + - [-1, 1, Conv, [512, 3, 2]] + - [[-1, 14], 1, Concat, [1]] # cat head P5 + - [-1, 3, C2, [768, False]] # 26 (P5/32-large) + + - [-1, 1, Conv, [768, 3, 2]] + - [[-1, 11], 1, Concat, [1]] # cat head P6 + - [-1, 3, C2, [1024, False]] # 29 (P6/64-xlarge) + + - [[20, 23, 26, 29], 1, Segment, [nc, 32, 256]] # Pose(P3, P4, P5, P6) diff --git a/ultralytics/cfg/models/v8/yolov8-seg.yaml b/ultralytics/cfg/models/v8/yolov8-seg.yaml new file mode 100644 index 0000000..700b795 --- /dev/null +++ b/ultralytics/cfg/models/v8/yolov8-seg.yaml @@ -0,0 +1,46 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# YOLOv8-seg instance segmentation model. For Usage examples see https://docs.ultralytics.com/tasks/segment + +# Parameters +nc: 80 # number of classes +scales: # model compound scaling constants, i.e. 'model=yolov8n-seg.yaml' will call yolov8-seg.yaml with scale 'n' + # [depth, width, max_channels] + n: [0.33, 0.25, 1024] + s: [0.33, 0.50, 1024] + m: [0.67, 0.75, 768] + l: [1.00, 1.00, 512] + x: [1.00, 1.25, 512] + +# YOLOv8.0n backbone +backbone: + # [from, repeats, module, args] + - [-1, 1, Conv, [64, 3, 2]] # 0-P1/2 + - [-1, 1, Conv, [128, 3, 2]] # 1-P2/4 + - [-1, 3, C2f, [128, True]] + - [-1, 1, Conv, [256, 3, 2]] # 3-P3/8 + - [-1, 6, C2f, [256, True]] + - [-1, 1, Conv, [512, 3, 2]] # 5-P4/16 + - [-1, 6, C2f, [512, True]] + - [-1, 1, Conv, [1024, 3, 2]] # 7-P5/32 + - [-1, 3, C2f, [1024, True]] + - [-1, 1, SPPF, [1024, 5]] # 9 + +# YOLOv8.0n head +head: + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 6], 1, Concat, [1]] # cat backbone P4 + - [-1, 3, C2f, [512]] # 12 + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 4], 1, Concat, [1]] # cat backbone P3 + - [-1, 3, C2f, [256]] # 15 (P3/8-small) + + - [-1, 1, Conv, [256, 3, 2]] + - [[-1, 12], 1, Concat, [1]] # cat head P4 + - [-1, 3, C2f, [512]] # 18 (P4/16-medium) + + - [-1, 1, Conv, [512, 3, 2]] + - [[-1, 9], 1, Concat, [1]] # cat head P5 + - [-1, 3, C2f, [1024]] # 21 (P5/32-large) + + - [[15, 18, 21], 1, Segment, [nc, 32, 256]] # Segment(P3, P4, P5) diff --git a/ultralytics/cfg/models/v8/yolov8-world.yaml b/ultralytics/cfg/models/v8/yolov8-world.yaml new file mode 100644 index 0000000..c21a7f0 --- /dev/null +++ b/ultralytics/cfg/models/v8/yolov8-world.yaml @@ -0,0 +1,48 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# YOLOv8-World object detection model with P3-P5 outputs. For details see https://docs.ultralytics.com/tasks/detect + +# Parameters +nc: 80 # number of classes +scales: # model compound scaling constants, i.e. 'model=yolov8n.yaml' will call yolov8.yaml with scale 'n' + # [depth, width, max_channels] + n: [0.33, 0.25, 1024] # YOLOv8n summary: 225 layers, 3157200 parameters, 3157184 gradients, 8.9 GFLOPs + s: [0.33, 0.50, 1024] # YOLOv8s summary: 225 layers, 11166560 parameters, 11166544 gradients, 28.8 GFLOPs + m: [0.67, 0.75, 768] # YOLOv8m summary: 295 layers, 25902640 parameters, 25902624 gradients, 79.3 GFLOPs + l: [1.00, 1.00, 512] # YOLOv8l summary: 365 layers, 43691520 parameters, 43691504 gradients, 165.7 GFLOPs + x: [1.00, 1.25, 512] # YOLOv8x summary: 365 layers, 68229648 parameters, 68229632 gradients, 258.5 GFLOPs + +# YOLOv8.0n backbone +backbone: + # [from, repeats, module, args] + - [-1, 1, Conv, [64, 3, 2]] # 0-P1/2 + - [-1, 1, Conv, [128, 3, 2]] # 1-P2/4 + - [-1, 3, C2f, [128, True]] + - [-1, 1, Conv, [256, 3, 2]] # 3-P3/8 + - [-1, 6, C2f, [256, True]] + - [-1, 1, Conv, [512, 3, 2]] # 5-P4/16 + - [-1, 6, C2f, [512, True]] + - [-1, 1, Conv, [1024, 3, 2]] # 7-P5/32 + - [-1, 3, C2f, [1024, True]] + - [-1, 1, SPPF, [1024, 5]] # 9 + +# YOLOv8.0n head +head: + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 6], 1, Concat, [1]] # cat backbone P4 + - [-1, 3, C2fAttn, [512, 256, 8]] # 12 + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 4], 1, Concat, [1]] # cat backbone P3 + - [-1, 3, C2fAttn, [256, 128, 4]] # 15 (P3/8-small) + + - [[15, 12, 9], 1, ImagePoolingAttn, [256]] # 16 (P3/8-small) + + - [15, 1, Conv, [256, 3, 2]] + - [[-1, 12], 1, Concat, [1]] # cat head P4 + - [-1, 3, C2fAttn, [512, 256, 8]] # 19 (P4/16-medium) + + - [-1, 1, Conv, [512, 3, 2]] + - [[-1, 9], 1, Concat, [1]] # cat head P5 + - [-1, 3, C2fAttn, [1024, 512, 16]] # 22 (P5/32-large) + + - [[15, 19, 22], 1, WorldDetect, [nc, 512, False]] # Detect(P3, P4, P5) diff --git a/ultralytics/cfg/models/v8/yolov8-worldv2.yaml b/ultralytics/cfg/models/v8/yolov8-worldv2.yaml new file mode 100644 index 0000000..322b97d --- /dev/null +++ b/ultralytics/cfg/models/v8/yolov8-worldv2.yaml @@ -0,0 +1,46 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# YOLOv8-World-v2 object detection model with P3-P5 outputs. For details see https://docs.ultralytics.com/tasks/detect + +# Parameters +nc: 80 # number of classes +scales: # model compound scaling constants, i.e. 'model=yolov8n.yaml' will call yolov8.yaml with scale 'n' + # [depth, width, max_channels] + n: [0.33, 0.25, 1024] # YOLOv8n summary: 225 layers, 3157200 parameters, 3157184 gradients, 8.9 GFLOPs + s: [0.33, 0.50, 1024] # YOLOv8s summary: 225 layers, 11166560 parameters, 11166544 gradients, 28.8 GFLOPs + m: [0.67, 0.75, 768] # YOLOv8m summary: 295 layers, 25902640 parameters, 25902624 gradients, 79.3 GFLOPs + l: [1.00, 1.00, 512] # YOLOv8l summary: 365 layers, 43691520 parameters, 43691504 gradients, 165.7 GFLOPs + x: [1.00, 1.25, 512] # YOLOv8x summary: 365 layers, 68229648 parameters, 68229632 gradients, 258.5 GFLOPs + +# YOLOv8.0n backbone +backbone: + # [from, repeats, module, args] + - [-1, 1, Conv, [64, 3, 2]] # 0-P1/2 + - [-1, 1, Conv, [128, 3, 2]] # 1-P2/4 + - [-1, 3, C2f, [128, True]] + - [-1, 1, Conv, [256, 3, 2]] # 3-P3/8 + - [-1, 6, C2f, [256, True]] + - [-1, 1, Conv, [512, 3, 2]] # 5-P4/16 + - [-1, 6, C2f, [512, True]] + - [-1, 1, Conv, [1024, 3, 2]] # 7-P5/32 + - [-1, 3, C2f, [1024, True]] + - [-1, 1, SPPF, [1024, 5]] # 9 + +# YOLOv8.0n head +head: + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 6], 1, Concat, [1]] # cat backbone P4 + - [-1, 3, C2fAttn, [512, 256, 8]] # 12 + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 4], 1, Concat, [1]] # cat backbone P3 + - [-1, 3, C2fAttn, [256, 128, 4]] # 15 (P3/8-small) + + - [15, 1, Conv, [256, 3, 2]] + - [[-1, 12], 1, Concat, [1]] # cat head P4 + - [-1, 3, C2fAttn, [512, 256, 8]] # 18 (P4/16-medium) + + - [-1, 1, Conv, [512, 3, 2]] + - [[-1, 9], 1, Concat, [1]] # cat head P5 + - [-1, 3, C2fAttn, [1024, 512, 16]] # 21 (P5/32-large) + + - [[15, 18, 21], 1, WorldDetect, [nc, 512, True]] # Detect(P3, P4, P5) diff --git a/ultralytics/cfg/models/v8/yolov8.yaml b/ultralytics/cfg/models/v8/yolov8.yaml new file mode 100644 index 0000000..b328e98 --- /dev/null +++ b/ultralytics/cfg/models/v8/yolov8.yaml @@ -0,0 +1,46 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# YOLOv8 object detection model with P3-P5 outputs. For Usage examples see https://docs.ultralytics.com/tasks/detect + +# Parameters +nc: 80 # number of classes +scales: # model compound scaling constants, i.e. 'model=yolov8n.yaml' will call yolov8.yaml with scale 'n' + # [depth, width, max_channels] + n: [0.33, 0.25, 1024] # YOLOv8n summary: 225 layers, 3157200 parameters, 3157184 gradients, 8.9 GFLOPs + s: [0.33, 0.50, 1024] # YOLOv8s summary: 225 layers, 11166560 parameters, 11166544 gradients, 28.8 GFLOPs + m: [0.67, 0.75, 768] # YOLOv8m summary: 295 layers, 25902640 parameters, 25902624 gradients, 79.3 GFLOPs + l: [1.00, 1.00, 512] # YOLOv8l summary: 365 layers, 43691520 parameters, 43691504 gradients, 165.7 GFLOPs + x: [1.00, 1.25, 512] # YOLOv8x summary: 365 layers, 68229648 parameters, 68229632 gradients, 258.5 GFLOPs + +# YOLOv8.0n backbone +backbone: + # [from, repeats, module, args] + - [-1, 1, Conv, [64, 3, 2]] # 0-P1/2 + - [-1, 1, Conv, [128, 3, 2]] # 1-P2/4 + - [-1, 3, C2f, [128, True]] + - [-1, 1, Conv, [256, 3, 2]] # 3-P3/8 + - [-1, 6, C2f, [256, True]] + - [-1, 1, Conv, [512, 3, 2]] # 5-P4/16 + - [-1, 6, C2f, [512, True]] + - [-1, 1, Conv, [1024, 3, 2]] # 7-P5/32 + - [-1, 3, C2f, [1024, True]] + - [-1, 1, SPPF, [1024, 5]] # 9 + +# YOLOv8.0n head +head: + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 6], 1, Concat, [1]] # cat backbone P4 + - [-1, 3, C2f, [512]] # 12 + + - [-1, 1, nn.Upsample, [None, 2, "nearest"]] + - [[-1, 4], 1, Concat, [1]] # cat backbone P3 + - [-1, 3, C2f, [256]] # 15 (P3/8-small) + + - [-1, 1, Conv, [256, 3, 2]] + - [[-1, 12], 1, Concat, [1]] # cat head P4 + - [-1, 3, C2f, [512]] # 18 (P4/16-medium) + + - [-1, 1, Conv, [512, 3, 2]] + - [[-1, 9], 1, Concat, [1]] # cat head P5 + - [-1, 3, C2f, [1024]] # 21 (P5/32-large) + + - [[15, 18, 21], 1, Detect, [nc]] # Detect(P3, P4, P5) diff --git a/ultralytics/cfg/models/v9/yolov9c-seg.yaml b/ultralytics/cfg/models/v9/yolov9c-seg.yaml new file mode 100644 index 0000000..784a2dc --- /dev/null +++ b/ultralytics/cfg/models/v9/yolov9c-seg.yaml @@ -0,0 +1,38 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# YOLOv9c-seg +# 654 layers, 27897120 parameters, 159.4 GFLOPs + +# parameters +nc: 80 # number of classes + +# gelan backbone +backbone: + - [-1, 1, Conv, [64, 3, 2]] # 0-P1/2 + - [-1, 1, Conv, [128, 3, 2]] # 1-P2/4 + - [-1, 1, RepNCSPELAN4, [256, 128, 64, 1]] # 2 + - [-1, 1, ADown, [256]] # 3-P3/8 + - [-1, 1, RepNCSPELAN4, [512, 256, 128, 1]] # 4 + - [-1, 1, ADown, [512]] # 5-P4/16 + - [-1, 1, RepNCSPELAN4, [512, 512, 256, 1]] # 6 + - [-1, 1, ADown, [512]] # 7-P5/32 + - [-1, 1, RepNCSPELAN4, [512, 512, 256, 1]] # 8 + - [-1, 1, SPPELAN, [512, 256]] # 9 + +head: + - [-1, 1, nn.Upsample, [None, 2, 'nearest']] + - [[-1, 6], 1, Concat, [1]] # cat backbone P4 + - [-1, 1, RepNCSPELAN4, [512, 512, 256, 1]] # 12 + + - [-1, 1, nn.Upsample, [None, 2, 'nearest']] + - [[-1, 4], 1, Concat, [1]] # cat backbone P3 + - [-1, 1, RepNCSPELAN4, [256, 256, 128, 1]] # 15 (P3/8-small) + + - [-1, 1, ADown, [256]] + - [[-1, 12], 1, Concat, [1]] # cat head P4 + - [-1, 1, RepNCSPELAN4, [512, 512, 256, 1]] # 18 (P4/16-medium) + + - [-1, 1, ADown, [512]] + - [[-1, 9], 1, Concat, [1]] # cat head P5 + - [-1, 1, RepNCSPELAN4, [512, 512, 256, 1]] # 21 (P5/32-large) + + - [[15, 18, 21], 1, Segment, [nc, 32, 256]] # Segment(P3, P4, P5) diff --git a/ultralytics/cfg/models/v9/yolov9c.yaml b/ultralytics/cfg/models/v9/yolov9c.yaml new file mode 100644 index 0000000..4bea187 --- /dev/null +++ b/ultralytics/cfg/models/v9/yolov9c.yaml @@ -0,0 +1,38 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# YOLOv9c +# 618 layers, 25590912 parameters, 104.0 GFLOPs + +# parameters +nc: 80 # number of classes + +# gelan backbone +backbone: + - [-1, 1, Conv, [64, 3, 2]] # 0-P1/2 + - [-1, 1, Conv, [128, 3, 2]] # 1-P2/4 + - [-1, 1, RepNCSPELAN4, [256, 128, 64, 1]] # 2 + - [-1, 1, ADown, [256]] # 3-P3/8 + - [-1, 1, RepNCSPELAN4, [512, 256, 128, 1]] # 4 + - [-1, 1, ADown, [512]] # 5-P4/16 + - [-1, 1, RepNCSPELAN4, [512, 512, 256, 1]] # 6 + - [-1, 1, ADown, [512]] # 7-P5/32 + - [-1, 1, RepNCSPELAN4, [512, 512, 256, 1]] # 8 + - [-1, 1, SPPELAN, [512, 256]] # 9 + +head: + - [-1, 1, nn.Upsample, [None, 2, 'nearest']] + - [[-1, 6], 1, Concat, [1]] # cat backbone P4 + - [-1, 1, RepNCSPELAN4, [512, 512, 256, 1]] # 12 + + - [-1, 1, nn.Upsample, [None, 2, 'nearest']] + - [[-1, 4], 1, Concat, [1]] # cat backbone P3 + - [-1, 1, RepNCSPELAN4, [256, 256, 128, 1]] # 15 (P3/8-small) + + - [-1, 1, ADown, [256]] + - [[-1, 12], 1, Concat, [1]] # cat head P4 + - [-1, 1, RepNCSPELAN4, [512, 512, 256, 1]] # 18 (P4/16-medium) + + - [-1, 1, ADown, [512]] + - [[-1, 9], 1, Concat, [1]] # cat head P5 + - [-1, 1, RepNCSPELAN4, [512, 512, 256, 1]] # 21 (P5/32-large) + + - [[15, 18, 21], 1, Detect, [nc]] # Detect(P3, P4, P5) diff --git a/ultralytics/cfg/models/v9/yolov9e-seg.yaml b/ultralytics/cfg/models/v9/yolov9e-seg.yaml new file mode 100644 index 0000000..636b78a --- /dev/null +++ b/ultralytics/cfg/models/v9/yolov9e-seg.yaml @@ -0,0 +1,61 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# YOLOv9c-seg +# 1261 layers, 60512800 parameters, 248.4 GFLOPs + +# parameters +nc: 80 # number of classes + +# gelan backbone +backbone: + - [-1, 1, Silence, []] + - [-1, 1, Conv, [64, 3, 2]] # 1-P1/2 + - [-1, 1, Conv, [128, 3, 2]] # 2-P2/4 + - [-1, 1, RepNCSPELAN4, [256, 128, 64, 2]] # 3 + - [-1, 1, ADown, [256]] # 4-P3/8 + - [-1, 1, RepNCSPELAN4, [512, 256, 128, 2]] # 5 + - [-1, 1, ADown, [512]] # 6-P4/16 + - [-1, 1, RepNCSPELAN4, [1024, 512, 256, 2]] # 7 + - [-1, 1, ADown, [1024]] # 8-P5/32 + - [-1, 1, RepNCSPELAN4, [1024, 512, 256, 2]] # 9 + + - [1, 1, CBLinear, [[64]]] # 10 + - [3, 1, CBLinear, [[64, 128]]] # 11 + - [5, 1, CBLinear, [[64, 128, 256]]] # 12 + - [7, 1, CBLinear, [[64, 128, 256, 512]]] # 13 + - [9, 1, CBLinear, [[64, 128, 256, 512, 1024]]] # 14 + + - [0, 1, Conv, [64, 3, 2]] # 15-P1/2 + - [[10, 11, 12, 13, 14, -1], 1, CBFuse, [[0, 0, 0, 0, 0]]] # 16 + - [-1, 1, Conv, [128, 3, 2]] # 17-P2/4 + - [[11, 12, 13, 14, -1], 1, CBFuse, [[1, 1, 1, 1]]] # 18 + - [-1, 1, RepNCSPELAN4, [256, 128, 64, 2]] # 19 + - [-1, 1, ADown, [256]] # 20-P3/8 + - [[12, 13, 14, -1], 1, CBFuse, [[2, 2, 2]]] # 21 + - [-1, 1, RepNCSPELAN4, [512, 256, 128, 2]] # 22 + - [-1, 1, ADown, [512]] # 23-P4/16 + - [[13, 14, -1], 1, CBFuse, [[3, 3]]] # 24 + - [-1, 1, RepNCSPELAN4, [1024, 512, 256, 2]] # 25 + - [-1, 1, ADown, [1024]] # 26-P5/32 + - [[14, -1], 1, CBFuse, [[4]]] # 27 + - [-1, 1, RepNCSPELAN4, [1024, 512, 256, 2]] # 28 + - [-1, 1, SPPELAN, [512, 256]] # 29 + +# gelan head +head: + - [-1, 1, nn.Upsample, [None, 2, 'nearest']] + - [[-1, 25], 1, Concat, [1]] # cat backbone P4 + - [-1, 1, RepNCSPELAN4, [512, 512, 256, 2]] # 32 + + - [-1, 1, nn.Upsample, [None, 2, 'nearest']] + - [[-1, 22], 1, Concat, [1]] # cat backbone P3 + - [-1, 1, RepNCSPELAN4, [256, 256, 128, 2]] # 35 (P3/8-small) + + - [-1, 1, ADown, [256]] + - [[-1, 32], 1, Concat, [1]] # cat head P4 + - [-1, 1, RepNCSPELAN4, [512, 512, 256, 2]] # 38 (P4/16-medium) + + - [-1, 1, ADown, [512]] + - [[-1, 29], 1, Concat, [1]] # cat head P5 + - [-1, 1, RepNCSPELAN4, [512, 1024, 512, 2]] # 41 (P5/32-large) + + - [[35, 38, 41], 1, Segment, [nc, 32, 256]] # Segment (P3, P4, P5) diff --git a/ultralytics/cfg/models/v9/yolov9e.yaml b/ultralytics/cfg/models/v9/yolov9e.yaml new file mode 100644 index 0000000..ed2594b --- /dev/null +++ b/ultralytics/cfg/models/v9/yolov9e.yaml @@ -0,0 +1,61 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# YOLOv9e +# 1225 layers, 58206592 parameters, 193.0 GFLOPs + +# parameters +nc: 80 # number of classes + +# gelan backbone +backbone: + - [-1, 1, Silence, []] + - [-1, 1, Conv, [64, 3, 2]] # 1-P1/2 + - [-1, 1, Conv, [128, 3, 2]] # 2-P2/4 + - [-1, 1, RepNCSPELAN4, [256, 128, 64, 2]] # 3 + - [-1, 1, ADown, [256]] # 4-P3/8 + - [-1, 1, RepNCSPELAN4, [512, 256, 128, 2]] # 5 + - [-1, 1, ADown, [512]] # 6-P4/16 + - [-1, 1, RepNCSPELAN4, [1024, 512, 256, 2]] # 7 + - [-1, 1, ADown, [1024]] # 8-P5/32 + - [-1, 1, RepNCSPELAN4, [1024, 512, 256, 2]] # 9 + + - [1, 1, CBLinear, [[64]]] # 10 + - [3, 1, CBLinear, [[64, 128]]] # 11 + - [5, 1, CBLinear, [[64, 128, 256]]] # 12 + - [7, 1, CBLinear, [[64, 128, 256, 512]]] # 13 + - [9, 1, CBLinear, [[64, 128, 256, 512, 1024]]] # 14 + + - [0, 1, Conv, [64, 3, 2]] # 15-P1/2 + - [[10, 11, 12, 13, 14, -1], 1, CBFuse, [[0, 0, 0, 0, 0]]] # 16 + - [-1, 1, Conv, [128, 3, 2]] # 17-P2/4 + - [[11, 12, 13, 14, -1], 1, CBFuse, [[1, 1, 1, 1]]] # 18 + - [-1, 1, RepNCSPELAN4, [256, 128, 64, 2]] # 19 + - [-1, 1, ADown, [256]] # 20-P3/8 + - [[12, 13, 14, -1], 1, CBFuse, [[2, 2, 2]]] # 21 + - [-1, 1, RepNCSPELAN4, [512, 256, 128, 2]] # 22 + - [-1, 1, ADown, [512]] # 23-P4/16 + - [[13, 14, -1], 1, CBFuse, [[3, 3]]] # 24 + - [-1, 1, RepNCSPELAN4, [1024, 512, 256, 2]] # 25 + - [-1, 1, ADown, [1024]] # 26-P5/32 + - [[14, -1], 1, CBFuse, [[4]]] # 27 + - [-1, 1, RepNCSPELAN4, [1024, 512, 256, 2]] # 28 + - [-1, 1, SPPELAN, [512, 256]] # 29 + +# gelan head +head: + - [-1, 1, nn.Upsample, [None, 2, 'nearest']] + - [[-1, 25], 1, Concat, [1]] # cat backbone P4 + - [-1, 1, RepNCSPELAN4, [512, 512, 256, 2]] # 32 + + - [-1, 1, nn.Upsample, [None, 2, 'nearest']] + - [[-1, 22], 1, Concat, [1]] # cat backbone P3 + - [-1, 1, RepNCSPELAN4, [256, 256, 128, 2]] # 35 (P3/8-small) + + - [-1, 1, ADown, [256]] + - [[-1, 32], 1, Concat, [1]] # cat head P4 + - [-1, 1, RepNCSPELAN4, [512, 512, 256, 2]] # 38 (P4/16-medium) + + - [-1, 1, ADown, [512]] + - [[-1, 29], 1, Concat, [1]] # cat head P5 + - [-1, 1, RepNCSPELAN4, [512, 1024, 512, 2]] # 41 (P5/32-large) + + - [[35, 38, 41], 1, Detect, [nc]] # Detect(P3, P4, P5) diff --git a/ultralytics/cfg/trackers/botsort.yaml b/ultralytics/cfg/trackers/botsort.yaml new file mode 100644 index 0000000..0c66dc6 --- /dev/null +++ b/ultralytics/cfg/trackers/botsort.yaml @@ -0,0 +1,18 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# Default YOLO tracker settings for BoT-SORT tracker https://github.com/NirAharon/BoT-SORT + +tracker_type: botsort # tracker type, ['botsort', 'bytetrack'] +track_high_thresh: 0.5 # threshold for the first association +track_low_thresh: 0.1 # threshold for the second association +new_track_thresh: 0.6 # threshold for init new track if the detection does not match any tracks +track_buffer: 30 # buffer to calculate the time when to remove tracks +match_thresh: 0.8 # threshold for matching tracks +# min_box_area: 10 # threshold for min box areas(for tracker evaluation, not used for now) +# mot20: False # for tracker evaluation(not used for now) + +# BoT-SORT settings +gmc_method: sparseOptFlow # method of global motion compensation +# ReID model related thresh (not supported yet) +proximity_thresh: 0.5 +appearance_thresh: 0.25 +with_reid: False diff --git a/ultralytics/cfg/trackers/bytetrack.yaml b/ultralytics/cfg/trackers/bytetrack.yaml new file mode 100644 index 0000000..29d352c --- /dev/null +++ b/ultralytics/cfg/trackers/bytetrack.yaml @@ -0,0 +1,11 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +# Default YOLO tracker settings for ByteTrack tracker https://github.com/ifzhang/ByteTrack + +tracker_type: bytetrack # tracker type, ['botsort', 'bytetrack'] +track_high_thresh: 0.5 # threshold for the first association +track_low_thresh: 0.1 # threshold for the second association +new_track_thresh: 0.6 # threshold for init new track if the detection does not match any tracks +track_buffer: 30 # buffer to calculate the time when to remove tracks +match_thresh: 0.8 # threshold for matching tracks +# min_box_area: 10 # threshold for min box areas(for tracker evaluation, not used for now) +# mot20: False # for tracker evaluation(not used for now) diff --git a/ultralytics/data/__init__.py b/ultralytics/data/__init__.py new file mode 100644 index 0000000..834432e --- /dev/null +++ b/ultralytics/data/__init__.py @@ -0,0 +1,26 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from .base import BaseDataset +from .build import build_dataloader, build_grounding, build_yolo_dataset, load_inference_source +from .dataset import ( + ClassificationDataset, + GroundingDataset, + SemanticDataset, + YOLOConcatDataset, + YOLODataset, + YOLOMultiModalDataset, +) + +__all__ = ( + "BaseDataset", + "ClassificationDataset", + "SemanticDataset", + "YOLODataset", + "YOLOMultiModalDataset", + "YOLOConcatDataset", + "GroundingDataset", + "build_yolo_dataset", + "build_grounding", + "build_dataloader", + "load_inference_source", +) diff --git a/ultralytics/data/annotator.py b/ultralytics/data/annotator.py new file mode 100644 index 0000000..b5b899c --- /dev/null +++ b/ultralytics/data/annotator.py @@ -0,0 +1,50 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from pathlib import Path + +from ultralytics import SAM, YOLO + + +def auto_annotate(data, det_model="yolov8x.pt", sam_model="sam_b.pt", device="", output_dir=None): + """ + Automatically annotates images using a YOLO object detection model and a SAM segmentation model. + + Args: + data (str): Path to a folder containing images to be annotated. + det_model (str, optional): Pre-trained YOLO detection model. Defaults to 'yolov8x.pt'. + sam_model (str, optional): Pre-trained SAM segmentation model. Defaults to 'sam_b.pt'. + device (str, optional): Device to run the models on. Defaults to an empty string (CPU or GPU, if available). + output_dir (str | None | optional): Directory to save the annotated results. + Defaults to a 'labels' folder in the same directory as 'data'. + + Example: + ```python + from ultralytics.data.annotator import auto_annotate + + auto_annotate(data='ultralytics/assets', det_model='yolov8n.pt', sam_model='mobile_sam.pt') + ``` + """ + det_model = YOLO(det_model) + sam_model = SAM(sam_model) + + data = Path(data) + if not output_dir: + output_dir = data.parent / f"{data.stem}_auto_annotate_labels" + Path(output_dir).mkdir(exist_ok=True, parents=True) + + det_results = det_model(data, stream=True, device=device) + + for result in det_results: + class_ids = result.boxes.cls.int().tolist() # noqa + if len(class_ids): + boxes = result.boxes.xyxy # Boxes object for bbox outputs + sam_results = sam_model(result.orig_img, bboxes=boxes, verbose=False, save=False, device=device) + segments = sam_results[0].masks.xyn # noqa + + with open(f"{Path(output_dir) / Path(result.path).stem}.txt", "w") as f: + for i in range(len(segments)): + s = segments[i] + if len(s) == 0: + continue + segment = map(str, segments[i].reshape(-1).tolist()) + f.write(f"{class_ids[i]} " + " ".join(segment) + "\n") diff --git a/ultralytics/data/augment.py b/ultralytics/data/augment.py new file mode 100644 index 0000000..6b6e35a --- /dev/null +++ b/ultralytics/data/augment.py @@ -0,0 +1,1384 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import math +import random +from copy import deepcopy +from typing import Tuple, Union + +import cv2 +import numpy as np +import torch +from PIL import Image + +from ultralytics.utils import LOGGER, colorstr +from ultralytics.utils.checks import check_version +from ultralytics.utils.instance import Instances +from ultralytics.utils.metrics import bbox_ioa +from ultralytics.utils.ops import segment2box, xyxyxyxy2xywhr +from ultralytics.utils.torch_utils import TORCHVISION_0_10, TORCHVISION_0_11, TORCHVISION_0_13 + +from .utils import polygons2masks, polygons2masks_overlap + +DEFAULT_MEAN = (0.0, 0.0, 0.0) +DEFAULT_STD = (1.0, 1.0, 1.0) +DEFAULT_CROP_FRACTION = 1.0 + + +# TODO: we might need a BaseTransform to make all these augments be compatible with both classification and semantic +class BaseTransform: + """ + Base class for image transformations. + + This is a generic transformation class that can be extended for specific image processing needs. + The class is designed to be compatible with both classification and semantic segmentation tasks. + + Methods: + __init__: Initializes the BaseTransform object. + apply_image: Applies image transformation to labels. + apply_instances: Applies transformations to object instances in labels. + apply_semantic: Applies semantic segmentation to an image. + __call__: Applies all label transformations to an image, instances, and semantic masks. + """ + + def __init__(self) -> None: + """Initializes the BaseTransform object.""" + pass + + def apply_image(self, labels): + """Applies image transformations to labels.""" + pass + + def apply_instances(self, labels): + """Applies transformations to object instances in labels.""" + pass + + def apply_semantic(self, labels): + """Applies semantic segmentation to an image.""" + pass + + def __call__(self, labels): + """Applies all label transformations to an image, instances, and semantic masks.""" + self.apply_image(labels) + self.apply_instances(labels) + self.apply_semantic(labels) + + +class Compose: + """Class for composing multiple image transformations.""" + + def __init__(self, transforms): + """Initializes the Compose object with a list of transforms.""" + self.transforms = transforms if isinstance(transforms, list) else [transforms] + + def __call__(self, data): + """Applies a series of transformations to input data.""" + for t in self.transforms: + data = t(data) + return data + + def append(self, transform): + """Appends a new transform to the existing list of transforms.""" + self.transforms.append(transform) + + def insert(self, index, transform): + """Inserts a new transform to the existing list of transforms.""" + self.transforms.insert(index, transform) + + def __getitem__(self, index: Union[list, int]) -> "Compose": + """Retrieve a specific transform or a set of transforms using indexing.""" + assert isinstance(index, (int, list)), f"The indices should be either list or int type but got {type(index)}" + index = [index] if isinstance(index, int) else index + return Compose([self.transforms[i] for i in index]) + + def __setitem__(self, index: Union[list, int], value: Union[list, int]) -> None: + """Retrieve a specific transform or a set of transforms using indexing.""" + assert isinstance(index, (int, list)), f"The indices should be either list or int type but got {type(index)}" + if isinstance(index, list): + assert isinstance( + value, list + ), f"The indices should be the same type as values, but got {type(index)} and {type(value)}" + if isinstance(index, int): + index, value = [index], [value] + for i, v in zip(index, value): + assert i < len(self.transforms), f"list index {i} out of range {len(self.transforms)}." + self.transforms[i] = v + + def tolist(self): + """Converts the list of transforms to a standard Python list.""" + return self.transforms + + def __repr__(self): + """Returns a string representation of the object.""" + return f"{self.__class__.__name__}({', '.join([f'{t}' for t in self.transforms])})" + + +class BaseMixTransform: + """ + Class for base mix (MixUp/Mosaic) transformations. + + This implementation is from mmyolo. + """ + + def __init__(self, dataset, pre_transform=None, p=0.0) -> None: + """Initializes the BaseMixTransform object with dataset, pre_transform, and probability.""" + self.dataset = dataset + self.pre_transform = pre_transform + self.p = p + + def __call__(self, labels): + """Applies pre-processing transforms and mixup/mosaic transforms to labels data.""" + if random.uniform(0, 1) > self.p: + return labels + + # Get index of one or three other images + indexes = self.get_indexes() + if isinstance(indexes, int): + indexes = [indexes] + + # Get images information will be used for Mosaic or MixUp + mix_labels = [self.dataset.get_image_and_label(i) for i in indexes] + + if self.pre_transform is not None: + for i, data in enumerate(mix_labels): + mix_labels[i] = self.pre_transform(data) + labels["mix_labels"] = mix_labels + + # Update cls and texts + labels = self._update_label_text(labels) + # Mosaic or MixUp + labels = self._mix_transform(labels) + labels.pop("mix_labels", None) + return labels + + def _mix_transform(self, labels): + """Applies MixUp or Mosaic augmentation to the label dictionary.""" + raise NotImplementedError + + def get_indexes(self): + """Gets a list of shuffled indexes for mosaic augmentation.""" + raise NotImplementedError + + def _update_label_text(self, labels): + """Update label text.""" + if "texts" not in labels: + return labels + + mix_texts = sum([labels["texts"]] + [x["texts"] for x in labels["mix_labels"]], []) + mix_texts = list({tuple(x) for x in mix_texts}) + text2id = {text: i for i, text in enumerate(mix_texts)} + + for label in [labels] + labels["mix_labels"]: + for i, cls in enumerate(label["cls"].squeeze(-1).tolist()): + text = label["texts"][int(cls)] + label["cls"][i] = text2id[tuple(text)] + label["texts"] = mix_texts + return labels + + +class Mosaic(BaseMixTransform): + """ + Mosaic augmentation. + + This class performs mosaic augmentation by combining multiple (4 or 9) images into a single mosaic image. + The augmentation is applied to a dataset with a given probability. + + Attributes: + dataset: The dataset on which the mosaic augmentation is applied. + imgsz (int, optional): Image size (height and width) after mosaic pipeline of a single image. Default to 640. + p (float, optional): Probability of applying the mosaic augmentation. Must be in the range 0-1. Default to 1.0. + n (int, optional): The grid size, either 4 (for 2x2) or 9 (for 3x3). + """ + + def __init__(self, dataset, imgsz=640, p=1.0, n=4): + """Initializes the object with a dataset, image size, probability, and border.""" + assert 0 <= p <= 1.0, f"The probability should be in range [0, 1], but got {p}." + assert n in {4, 9}, "grid must be equal to 4 or 9." + super().__init__(dataset=dataset, p=p) + self.dataset = dataset + self.imgsz = imgsz + self.border = (-imgsz // 2, -imgsz // 2) # width, height + self.n = n + + def get_indexes(self, buffer=True): + """Return a list of random indexes from the dataset.""" + if buffer: # select images from buffer + return random.choices(list(self.dataset.buffer), k=self.n - 1) + else: # select any images + return [random.randint(0, len(self.dataset) - 1) for _ in range(self.n - 1)] + + def _mix_transform(self, labels): + """Apply mixup transformation to the input image and labels.""" + assert labels.get("rect_shape", None) is None, "rect and mosaic are mutually exclusive." + assert len(labels.get("mix_labels", [])), "There are no other images for mosaic augment." + return ( + self._mosaic3(labels) if self.n == 3 else self._mosaic4(labels) if self.n == 4 else self._mosaic9(labels) + ) # This code is modified for mosaic3 method. + + def _mosaic3(self, labels): + """Create a 1x3 image mosaic.""" + mosaic_labels = [] + s = self.imgsz + for i in range(3): + labels_patch = labels if i == 0 else labels["mix_labels"][i - 1] + # Load image + img = labels_patch["img"] + h, w = labels_patch.pop("resized_shape") + + # Place img in img3 + if i == 0: # center + img3 = np.full((s * 3, s * 3, img.shape[2]), 114, dtype=np.uint8) # base image with 3 tiles + h0, w0 = h, w + c = s, s, s + w, s + h # xmin, ymin, xmax, ymax (base) coordinates + elif i == 1: # right + c = s + w0, s, s + w0 + w, s + h + elif i == 2: # left + c = s - w, s + h0 - h, s, s + h0 + + padw, padh = c[:2] + x1, y1, x2, y2 = (max(x, 0) for x in c) # allocate coords + + img3[y1:y2, x1:x2] = img[y1 - padh :, x1 - padw :] # img3[ymin:ymax, xmin:xmax] + # hp, wp = h, w # height, width previous for next iteration + + # Labels assuming imgsz*2 mosaic size + labels_patch = self._update_labels(labels_patch, padw + self.border[0], padh + self.border[1]) + mosaic_labels.append(labels_patch) + final_labels = self._cat_labels(mosaic_labels) + + final_labels["img"] = img3[-self.border[0] : self.border[0], -self.border[1] : self.border[1]] + return final_labels + + def _mosaic4(self, labels): + """Create a 2x2 image mosaic.""" + mosaic_labels = [] + s = self.imgsz + yc, xc = (int(random.uniform(-x, 2 * s + x)) for x in self.border) # mosaic center x, y + for i in range(4): + labels_patch = labels if i == 0 else labels["mix_labels"][i - 1] + # Load image + img = labels_patch["img"] + h, w = labels_patch.pop("resized_shape") + + # Place img in img4 + if i == 0: # top left + img4 = np.full((s * 2, s * 2, img.shape[2]), 114, dtype=np.uint8) # base image with 4 tiles + x1a, y1a, x2a, y2a = max(xc - w, 0), max(yc - h, 0), xc, yc # xmin, ymin, xmax, ymax (large image) + x1b, y1b, x2b, y2b = w - (x2a - x1a), h - (y2a - y1a), w, h # xmin, ymin, xmax, ymax (small image) + elif i == 1: # top right + x1a, y1a, x2a, y2a = xc, max(yc - h, 0), min(xc + w, s * 2), yc + x1b, y1b, x2b, y2b = 0, h - (y2a - y1a), min(w, x2a - x1a), h + elif i == 2: # bottom left + x1a, y1a, x2a, y2a = max(xc - w, 0), yc, xc, min(s * 2, yc + h) + x1b, y1b, x2b, y2b = w - (x2a - x1a), 0, w, min(y2a - y1a, h) + elif i == 3: # bottom right + x1a, y1a, x2a, y2a = xc, yc, min(xc + w, s * 2), min(s * 2, yc + h) + x1b, y1b, x2b, y2b = 0, 0, min(w, x2a - x1a), min(y2a - y1a, h) + + img4[y1a:y2a, x1a:x2a] = img[y1b:y2b, x1b:x2b] # img4[ymin:ymax, xmin:xmax] + padw = x1a - x1b + padh = y1a - y1b + + labels_patch = self._update_labels(labels_patch, padw, padh) + mosaic_labels.append(labels_patch) + final_labels = self._cat_labels(mosaic_labels) + final_labels["img"] = img4 + return final_labels + + def _mosaic9(self, labels): + """Create a 3x3 image mosaic.""" + mosaic_labels = [] + s = self.imgsz + hp, wp = -1, -1 # height, width previous + for i in range(9): + labels_patch = labels if i == 0 else labels["mix_labels"][i - 1] + # Load image + img = labels_patch["img"] + h, w = labels_patch.pop("resized_shape") + + # Place img in img9 + if i == 0: # center + img9 = np.full((s * 3, s * 3, img.shape[2]), 114, dtype=np.uint8) # base image with 4 tiles + h0, w0 = h, w + c = s, s, s + w, s + h # xmin, ymin, xmax, ymax (base) coordinates + elif i == 1: # top + c = s, s - h, s + w, s + elif i == 2: # top right + c = s + wp, s - h, s + wp + w, s + elif i == 3: # right + c = s + w0, s, s + w0 + w, s + h + elif i == 4: # bottom right + c = s + w0, s + hp, s + w0 + w, s + hp + h + elif i == 5: # bottom + c = s + w0 - w, s + h0, s + w0, s + h0 + h + elif i == 6: # bottom left + c = s + w0 - wp - w, s + h0, s + w0 - wp, s + h0 + h + elif i == 7: # left + c = s - w, s + h0 - h, s, s + h0 + elif i == 8: # top left + c = s - w, s + h0 - hp - h, s, s + h0 - hp + + padw, padh = c[:2] + x1, y1, x2, y2 = (max(x, 0) for x in c) # allocate coords + + # Image + img9[y1:y2, x1:x2] = img[y1 - padh :, x1 - padw :] # img9[ymin:ymax, xmin:xmax] + hp, wp = h, w # height, width previous for next iteration + + # Labels assuming imgsz*2 mosaic size + labels_patch = self._update_labels(labels_patch, padw + self.border[0], padh + self.border[1]) + mosaic_labels.append(labels_patch) + final_labels = self._cat_labels(mosaic_labels) + + final_labels["img"] = img9[-self.border[0] : self.border[0], -self.border[1] : self.border[1]] + return final_labels + + @staticmethod + def _update_labels(labels, padw, padh): + """Update labels.""" + nh, nw = labels["img"].shape[:2] + labels["instances"].convert_bbox(format="xyxy") + labels["instances"].denormalize(nw, nh) + labels["instances"].add_padding(padw, padh) + return labels + + def _cat_labels(self, mosaic_labels): + """Return labels with mosaic border instances clipped.""" + if len(mosaic_labels) == 0: + return {} + cls = [] + instances = [] + imgsz = self.imgsz * 2 # mosaic imgsz + for labels in mosaic_labels: + cls.append(labels["cls"]) + instances.append(labels["instances"]) + # Final labels + final_labels = { + "im_file": mosaic_labels[0]["im_file"], + "ori_shape": mosaic_labels[0]["ori_shape"], + "resized_shape": (imgsz, imgsz), + "cls": np.concatenate(cls, 0), + "instances": Instances.concatenate(instances, axis=0), + "mosaic_border": self.border, + } + final_labels["instances"].clip(imgsz, imgsz) + good = final_labels["instances"].remove_zero_area_boxes() + final_labels["cls"] = final_labels["cls"][good] + if "texts" in mosaic_labels[0]: + final_labels["texts"] = mosaic_labels[0]["texts"] + return final_labels + + +class MixUp(BaseMixTransform): + """Class for applying MixUp augmentation to the dataset.""" + + def __init__(self, dataset, pre_transform=None, p=0.0) -> None: + """Initializes MixUp object with dataset, pre_transform, and probability of applying MixUp.""" + super().__init__(dataset=dataset, pre_transform=pre_transform, p=p) + + def get_indexes(self): + """Get a random index from the dataset.""" + return random.randint(0, len(self.dataset) - 1) + + def _mix_transform(self, labels): + """Applies MixUp augmentation as per https://arxiv.org/pdf/1710.09412.pdf.""" + r = np.random.beta(32.0, 32.0) # mixup ratio, alpha=beta=32.0 + labels2 = labels["mix_labels"][0] + labels["img"] = (labels["img"] * r + labels2["img"] * (1 - r)).astype(np.uint8) + labels["instances"] = Instances.concatenate([labels["instances"], labels2["instances"]], axis=0) + labels["cls"] = np.concatenate([labels["cls"], labels2["cls"]], 0) + return labels + + +class RandomPerspective: + """ + Implements random perspective and affine transformations on images and corresponding bounding boxes, segments, and + keypoints. These transformations include rotation, translation, scaling, and shearing. The class also offers the + option to apply these transformations conditionally with a specified probability. + + Attributes: + degrees (float): Degree range for random rotations. + translate (float): Fraction of total width and height for random translation. + scale (float): Scaling factor interval, e.g., a scale factor of 0.1 allows a resize between 90%-110%. + shear (float): Shear intensity (angle in degrees). + perspective (float): Perspective distortion factor. + border (tuple): Tuple specifying mosaic border. + pre_transform (callable): A function/transform to apply to the image before starting the random transformation. + + Methods: + affine_transform(img, border): Applies a series of affine transformations to the image. + apply_bboxes(bboxes, M): Transforms bounding boxes using the calculated affine matrix. + apply_segments(segments, M): Transforms segments and generates new bounding boxes. + apply_keypoints(keypoints, M): Transforms keypoints. + __call__(labels): Main method to apply transformations to both images and their corresponding annotations. + box_candidates(box1, box2): Filters out bounding boxes that don't meet certain criteria post-transformation. + """ + + def __init__( + self, degrees=0.0, translate=0.1, scale=0.5, shear=0.0, perspective=0.0, border=(0, 0), pre_transform=None + ): + """Initializes RandomPerspective object with transformation parameters.""" + + self.degrees = degrees + self.translate = translate + self.scale = scale + self.shear = shear + self.perspective = perspective + self.border = border # mosaic border + self.pre_transform = pre_transform + + def affine_transform(self, img, border): + """ + Applies a sequence of affine transformations centered around the image center. + + Args: + img (ndarray): Input image. + border (tuple): Border dimensions. + + Returns: + img (ndarray): Transformed image. + M (ndarray): Transformation matrix. + s (float): Scale factor. + """ + + # Center + C = np.eye(3, dtype=np.float32) + + C[0, 2] = -img.shape[1] / 2 # x translation (pixels) + C[1, 2] = -img.shape[0] / 2 # y translation (pixels) + + # Perspective + P = np.eye(3, dtype=np.float32) + P[2, 0] = random.uniform(-self.perspective, self.perspective) # x perspective (about y) + P[2, 1] = random.uniform(-self.perspective, self.perspective) # y perspective (about x) + + # Rotation and Scale + R = np.eye(3, dtype=np.float32) + a = random.uniform(-self.degrees, self.degrees) + # a += random.choice([-180, -90, 0, 90]) # add 90deg rotations to small rotations + s = random.uniform(1 - self.scale, 1 + self.scale) + # s = 2 ** random.uniform(-scale, scale) + R[:2] = cv2.getRotationMatrix2D(angle=a, center=(0, 0), scale=s) + + # Shear + S = np.eye(3, dtype=np.float32) + S[0, 1] = math.tan(random.uniform(-self.shear, self.shear) * math.pi / 180) # x shear (deg) + S[1, 0] = math.tan(random.uniform(-self.shear, self.shear) * math.pi / 180) # y shear (deg) + + # Translation + T = np.eye(3, dtype=np.float32) + T[0, 2] = random.uniform(0.5 - self.translate, 0.5 + self.translate) * self.size[0] # x translation (pixels) + T[1, 2] = random.uniform(0.5 - self.translate, 0.5 + self.translate) * self.size[1] # y translation (pixels) + + # Combined rotation matrix + M = T @ S @ R @ P @ C # order of operations (right to left) is IMPORTANT + # Affine image + if (border[0] != 0) or (border[1] != 0) or (M != np.eye(3)).any(): # image changed + if self.perspective: + img = cv2.warpPerspective(img, M, dsize=self.size, borderValue=(114, 114, 114)) + else: # affine + img = cv2.warpAffine(img, M[:2], dsize=self.size, borderValue=(114, 114, 114)) + return img, M, s + + def apply_bboxes(self, bboxes, M): + """ + Apply affine to bboxes only. + + Args: + bboxes (ndarray): list of bboxes, xyxy format, with shape (num_bboxes, 4). + M (ndarray): affine matrix. + + Returns: + new_bboxes (ndarray): bboxes after affine, [num_bboxes, 4]. + """ + n = len(bboxes) + if n == 0: + return bboxes + + xy = np.ones((n * 4, 3), dtype=bboxes.dtype) + xy[:, :2] = bboxes[:, [0, 1, 2, 3, 0, 3, 2, 1]].reshape(n * 4, 2) # x1y1, x2y2, x1y2, x2y1 + xy = xy @ M.T # transform + xy = (xy[:, :2] / xy[:, 2:3] if self.perspective else xy[:, :2]).reshape(n, 8) # perspective rescale or affine + + # Create new boxes + x = xy[:, [0, 2, 4, 6]] + y = xy[:, [1, 3, 5, 7]] + return np.concatenate((x.min(1), y.min(1), x.max(1), y.max(1)), dtype=bboxes.dtype).reshape(4, n).T + + def apply_segments(self, segments, M): + """ + Apply affine to segments and generate new bboxes from segments. + + Args: + segments (ndarray): list of segments, [num_samples, 500, 2]. + M (ndarray): affine matrix. + + Returns: + new_segments (ndarray): list of segments after affine, [num_samples, 500, 2]. + new_bboxes (ndarray): bboxes after affine, [N, 4]. + """ + n, num = segments.shape[:2] + if n == 0: + return [], segments + + xy = np.ones((n * num, 3), dtype=segments.dtype) + segments = segments.reshape(-1, 2) + xy[:, :2] = segments + xy = xy @ M.T # transform + xy = xy[:, :2] / xy[:, 2:3] + segments = xy.reshape(n, -1, 2) + bboxes = np.stack([segment2box(xy, self.size[0], self.size[1]) for xy in segments], 0) + segments[..., 0] = segments[..., 0].clip(bboxes[:, 0:1], bboxes[:, 2:3]) + segments[..., 1] = segments[..., 1].clip(bboxes[:, 1:2], bboxes[:, 3:4]) + return bboxes, segments + + def apply_keypoints(self, keypoints, M): + """ + Apply affine to keypoints. + + Args: + keypoints (ndarray): keypoints, [N, 17, 3]. + M (ndarray): affine matrix. + + Returns: + new_keypoints (ndarray): keypoints after affine, [N, 17, 3]. + """ + n, nkpt = keypoints.shape[:2] + if n == 0: + return keypoints + xy = np.ones((n * nkpt, 3), dtype=keypoints.dtype) + visible = keypoints[..., 2].reshape(n * nkpt, 1) + xy[:, :2] = keypoints[..., :2].reshape(n * nkpt, 2) + xy = xy @ M.T # transform + xy = xy[:, :2] / xy[:, 2:3] # perspective rescale or affine + out_mask = (xy[:, 0] < 0) | (xy[:, 1] < 0) | (xy[:, 0] > self.size[0]) | (xy[:, 1] > self.size[1]) + visible[out_mask] = 0 + return np.concatenate([xy, visible], axis=-1).reshape(n, nkpt, 3) + + def __call__(self, labels): + """ + Affine images and targets. + + Args: + labels (dict): a dict of `bboxes`, `segments`, `keypoints`. + """ + if self.pre_transform and "mosaic_border" not in labels: + labels = self.pre_transform(labels) + labels.pop("ratio_pad", None) # do not need ratio pad + + img = labels["img"] + cls = labels["cls"] + instances = labels.pop("instances") + # Make sure the coord formats are right + instances.convert_bbox(format="xyxy") + instances.denormalize(*img.shape[:2][::-1]) + + border = labels.pop("mosaic_border", self.border) + self.size = img.shape[1] + border[1] * 2, img.shape[0] + border[0] * 2 # w, h + # M is affine matrix + # Scale for func:`box_candidates` + img, M, scale = self.affine_transform(img, border) + + bboxes = self.apply_bboxes(instances.bboxes, M) + + segments = instances.segments + keypoints = instances.keypoints + # Update bboxes if there are segments. + if len(segments): + bboxes, segments = self.apply_segments(segments, M) + + if keypoints is not None: + keypoints = self.apply_keypoints(keypoints, M) + new_instances = Instances(bboxes, segments, keypoints, bbox_format="xyxy", normalized=False) + # Clip + new_instances.clip(*self.size) + + # Filter instances + instances.scale(scale_w=scale, scale_h=scale, bbox_only=True) + # Make the bboxes have the same scale with new_bboxes + i = self.box_candidates( + box1=instances.bboxes.T, box2=new_instances.bboxes.T, area_thr=0.01 if len(segments) else 0.10 + ) + labels["instances"] = new_instances[i] + labels["cls"] = cls[i] + labels["img"] = img + labels["resized_shape"] = img.shape[:2] + return labels + + def box_candidates(self, box1, box2, wh_thr=2, ar_thr=100, area_thr=0.1, eps=1e-16): + """ + Compute box candidates based on a set of thresholds. This method compares the characteristics of the boxes + before and after augmentation to decide whether a box is a candidate for further processing. + + Args: + box1 (numpy.ndarray): The 4,n bounding box before augmentation, represented as [x1, y1, x2, y2]. + box2 (numpy.ndarray): The 4,n bounding box after augmentation, represented as [x1, y1, x2, y2]. + wh_thr (float, optional): The width and height threshold in pixels. Default is 2. + ar_thr (float, optional): The aspect ratio threshold. Default is 100. + area_thr (float, optional): The area ratio threshold. Default is 0.1. + eps (float, optional): A small epsilon value to prevent division by zero. Default is 1e-16. + + Returns: + (numpy.ndarray): A boolean array indicating which boxes are candidates based on the given thresholds. + """ + w1, h1 = box1[2] - box1[0], box1[3] - box1[1] + w2, h2 = box2[2] - box2[0], box2[3] - box2[1] + ar = np.maximum(w2 / (h2 + eps), h2 / (w2 + eps)) # aspect ratio + return (w2 > wh_thr) & (h2 > wh_thr) & (w2 * h2 / (w1 * h1 + eps) > area_thr) & (ar < ar_thr) # candidates + + +class RandomHSV: + """ + This class is responsible for performing random adjustments to the Hue, Saturation, and Value (HSV) channels of an + image. + + The adjustments are random but within limits set by hgain, sgain, and vgain. + """ + + def __init__(self, hgain=0.5, sgain=0.5, vgain=0.5) -> None: + """ + Initialize RandomHSV class with gains for each HSV channel. + + Args: + hgain (float, optional): Maximum variation for hue. Default is 0.5. + sgain (float, optional): Maximum variation for saturation. Default is 0.5. + vgain (float, optional): Maximum variation for value. Default is 0.5. + """ + self.hgain = hgain + self.sgain = sgain + self.vgain = vgain + + def __call__(self, labels): + """ + Applies random HSV augmentation to an image within the predefined limits. + + The modified image replaces the original image in the input 'labels' dict. + """ + img = labels["img"] + if self.hgain or self.sgain or self.vgain: + r = np.random.uniform(-1, 1, 3) * [self.hgain, self.sgain, self.vgain] + 1 # random gains + hue, sat, val = cv2.split(cv2.cvtColor(img, cv2.COLOR_BGR2HSV)) + dtype = img.dtype # uint8 + + x = np.arange(0, 256, dtype=r.dtype) + lut_hue = ((x * r[0]) % 180).astype(dtype) + lut_sat = np.clip(x * r[1], 0, 255).astype(dtype) + lut_val = np.clip(x * r[2], 0, 255).astype(dtype) + + im_hsv = cv2.merge((cv2.LUT(hue, lut_hue), cv2.LUT(sat, lut_sat), cv2.LUT(val, lut_val))) + cv2.cvtColor(im_hsv, cv2.COLOR_HSV2BGR, dst=img) # no return needed + return labels + + +class RandomFlip: + """ + Applies a random horizontal or vertical flip to an image with a given probability. + + Also updates any instances (bounding boxes, keypoints, etc.) accordingly. + """ + + def __init__(self, p=0.5, direction="horizontal", flip_idx=None) -> None: + """ + Initializes the RandomFlip class with probability and direction. + + Args: + p (float, optional): The probability of applying the flip. Must be between 0 and 1. Default is 0.5. + direction (str, optional): The direction to apply the flip. Must be 'horizontal' or 'vertical'. + Default is 'horizontal'. + flip_idx (array-like, optional): Index mapping for flipping keypoints, if any. + """ + assert direction in {"horizontal", "vertical"}, f"Support direction `horizontal` or `vertical`, got {direction}" + assert 0 <= p <= 1.0 + + self.p = p + self.direction = direction + self.flip_idx = flip_idx + + def __call__(self, labels): + """ + Applies random flip to an image and updates any instances like bounding boxes or keypoints accordingly. + + Args: + labels (dict): A dictionary containing the keys 'img' and 'instances'. 'img' is the image to be flipped. + 'instances' is an object containing bounding boxes and optionally keypoints. + + Returns: + (dict): The same dict with the flipped image and updated instances under the 'img' and 'instances' keys. + """ + img = labels["img"] + instances = labels.pop("instances") + instances.convert_bbox(format="xywh") + h, w = img.shape[:2] + h = 1 if instances.normalized else h + w = 1 if instances.normalized else w + + # Flip up-down + if self.direction == "vertical" and random.random() < self.p: + img = np.flipud(img) + instances.flipud(h) + if self.direction == "horizontal" and random.random() < self.p: + img = np.fliplr(img) + instances.fliplr(w) + # For keypoints + if self.flip_idx is not None and instances.keypoints is not None: + instances.keypoints = np.ascontiguousarray(instances.keypoints[:, self.flip_idx, :]) + labels["img"] = np.ascontiguousarray(img) + labels["instances"] = instances + return labels + + +class LetterBox: + """Resize image and padding for detection, instance segmentation, pose.""" + + def __init__(self, new_shape=(640, 640), auto=False, scaleFill=False, scaleup=True, center=True, stride=32): + """Initialize LetterBox object with specific parameters.""" + self.new_shape = new_shape + self.auto = auto + self.scaleFill = scaleFill + self.scaleup = scaleup + self.stride = stride + self.center = center # Put the image in the middle or top-left + + def __call__(self, labels=None, image=None): + """Return updated labels and image with added border.""" + if labels is None: + labels = {} + img = labels.get("img") if image is None else image + shape = img.shape[:2] # current shape [height, width] + new_shape = labels.pop("rect_shape", self.new_shape) + if isinstance(new_shape, int): + new_shape = (new_shape, new_shape) + + # Scale ratio (new / old) + r = min(new_shape[0] / shape[0], new_shape[1] / shape[1]) + if not self.scaleup: # only scale down, do not scale up (for better val mAP) + r = min(r, 1.0) + + # Compute padding + ratio = r, r # width, height ratios + new_unpad = int(round(shape[1] * r)), int(round(shape[0] * r)) + dw, dh = new_shape[1] - new_unpad[0], new_shape[0] - new_unpad[1] # wh padding + if self.auto: # minimum rectangle + dw, dh = np.mod(dw, self.stride), np.mod(dh, self.stride) # wh padding + elif self.scaleFill: # stretch + dw, dh = 0.0, 0.0 + new_unpad = (new_shape[1], new_shape[0]) + ratio = new_shape[1] / shape[1], new_shape[0] / shape[0] # width, height ratios + + if self.center: + dw /= 2 # divide padding into 2 sides + dh /= 2 + + if shape[::-1] != new_unpad: # resize + img = cv2.resize(img, new_unpad, interpolation=cv2.INTER_LINEAR) + top, bottom = int(round(dh - 0.1)) if self.center else 0, int(round(dh + 0.1)) + left, right = int(round(dw - 0.1)) if self.center else 0, int(round(dw + 0.1)) + img = cv2.copyMakeBorder( + img, top, bottom, left, right, cv2.BORDER_CONSTANT, value=(114, 114, 114) + ) # add border + if labels.get("ratio_pad"): + labels["ratio_pad"] = (labels["ratio_pad"], (left, top)) # for evaluation + + if len(labels): + labels = self._update_labels(labels, ratio, dw, dh) + labels["img"] = img + labels["resized_shape"] = new_shape + return labels + else: + return img + + def _update_labels(self, labels, ratio, padw, padh): + """Update labels.""" + labels["instances"].convert_bbox(format="xyxy") + labels["instances"].denormalize(*labels["img"].shape[:2][::-1]) + labels["instances"].scale(*ratio) + labels["instances"].add_padding(padw, padh) + return labels + + +class CopyPaste: + """ + Implements the Copy-Paste augmentation as described in the paper https://arxiv.org/abs/2012.07177. This class is + responsible for applying the Copy-Paste augmentation on images and their corresponding instances. + """ + + def __init__(self, p=0.5) -> None: + """ + Initializes the CopyPaste class with a given probability. + + Args: + p (float, optional): The probability of applying the Copy-Paste augmentation. Must be between 0 and 1. + Default is 0.5. + """ + self.p = p + + def __call__(self, labels): + """ + Applies the Copy-Paste augmentation to the given image and instances. + + Args: + labels (dict): A dictionary containing: + - 'img': The image to augment. + - 'cls': Class labels associated with the instances. + - 'instances': Object containing bounding boxes, and optionally, keypoints and segments. + + Returns: + (dict): Dict with augmented image and updated instances under the 'img', 'cls', and 'instances' keys. + + Notes: + 1. Instances are expected to have 'segments' as one of their attributes for this augmentation to work. + 2. This method modifies the input dictionary 'labels' in place. + """ + im = labels["img"] + cls = labels["cls"] + h, w = im.shape[:2] + instances = labels.pop("instances") + instances.convert_bbox(format="xyxy") + instances.denormalize(w, h) + if self.p and len(instances.segments): + n = len(instances) + _, w, _ = im.shape # height, width, channels + im_new = np.zeros(im.shape, np.uint8) + + # Calculate ioa first then select indexes randomly + ins_flip = deepcopy(instances) + ins_flip.fliplr(w) + + ioa = bbox_ioa(ins_flip.bboxes, instances.bboxes) # intersection over area, (N, M) + indexes = np.nonzero((ioa < 0.30).all(1))[0] # (N, ) + n = len(indexes) + for j in random.sample(list(indexes), k=round(self.p * n)): + cls = np.concatenate((cls, cls[[j]]), axis=0) + instances = Instances.concatenate((instances, ins_flip[[j]]), axis=0) + cv2.drawContours(im_new, instances.segments[[j]].astype(np.int32), -1, (1, 1, 1), cv2.FILLED) + + result = cv2.flip(im, 1) # augment segments (flip left-right) + i = cv2.flip(im_new, 1).astype(bool) + im[i] = result[i] + + labels["img"] = im + labels["cls"] = cls + labels["instances"] = instances + return labels + + +class Albumentations: + """ + Albumentations transformations. + + Optional, uninstall package to disable. Applies Blur, Median Blur, convert to grayscale, Contrast Limited Adaptive + Histogram Equalization, random change of brightness and contrast, RandomGamma and lowering of image quality by + compression. + """ + + def __init__(self, p=1.0): + """Initialize the transform object for YOLO bbox formatted params.""" + self.p = p + self.transform = None + prefix = colorstr("albumentations: ") + try: + import albumentations as A + + check_version(A.__version__, "1.0.3", hard=True) # version requirement + + # Transforms + T = [ + A.Blur(p=0.01), + A.MedianBlur(p=0.01), + A.ToGray(p=0.01), + A.CLAHE(p=0.01), + A.RandomBrightnessContrast(p=0.0), + A.RandomGamma(p=0.0), + A.ImageCompression(quality_lower=75, p=0.0), + ] + self.transform = A.Compose(T, bbox_params=A.BboxParams(format="yolo", label_fields=["class_labels"])) + + LOGGER.info(prefix + ", ".join(f"{x}".replace("always_apply=False, ", "") for x in T if x.p)) + except ImportError: # package not installed, skip + pass + except Exception as e: + LOGGER.info(f"{prefix}{e}") + + def __call__(self, labels): + """Generates object detections and returns a dictionary with detection results.""" + im = labels["img"] + cls = labels["cls"] + if len(cls): + labels["instances"].convert_bbox("xywh") + labels["instances"].normalize(*im.shape[:2][::-1]) + bboxes = labels["instances"].bboxes + # TODO: add supports of segments and keypoints + if self.transform and random.random() < self.p: + new = self.transform(image=im, bboxes=bboxes, class_labels=cls) # transformed + if len(new["class_labels"]) > 0: # skip update if no bbox in new im + labels["img"] = new["image"] + labels["cls"] = np.array(new["class_labels"]) + bboxes = np.array(new["bboxes"], dtype=np.float32) + labels["instances"].update(bboxes=bboxes) + return labels + + +# TODO: technically this is not an augmentation, maybe we should put this to another files +class Format: + """ + Formats image annotations for object detection, instance segmentation, and pose estimation tasks. The class + standardizes the image and instance annotations to be used by the `collate_fn` in PyTorch DataLoader. + + Attributes: + bbox_format (str): Format for bounding boxes. Default is 'xywh'. + normalize (bool): Whether to normalize bounding boxes. Default is True. + return_mask (bool): Return instance masks for segmentation. Default is False. + return_keypoint (bool): Return keypoints for pose estimation. Default is False. + mask_ratio (int): Downsample ratio for masks. Default is 4. + mask_overlap (bool): Whether to overlap masks. Default is True. + batch_idx (bool): Keep batch indexes. Default is True. + bgr (float): The probability to return BGR images. Default is 0.0. + """ + + def __init__( + self, + bbox_format="xywh", + normalize=True, + return_mask=False, + return_keypoint=False, + return_obb=False, + mask_ratio=4, + mask_overlap=True, + batch_idx=True, + bgr=0.0, + ): + """Initializes the Format class with given parameters.""" + self.bbox_format = bbox_format + self.normalize = normalize + self.return_mask = return_mask # set False when training detection only + self.return_keypoint = return_keypoint + self.return_obb = return_obb + self.mask_ratio = mask_ratio + self.mask_overlap = mask_overlap + self.batch_idx = batch_idx # keep the batch indexes + self.bgr = bgr + + def __call__(self, labels): + """Return formatted image, classes, bounding boxes & keypoints to be used by 'collate_fn'.""" + img = labels.pop("img") + h, w = img.shape[:2] + cls = labels.pop("cls") + instances = labels.pop("instances") + instances.convert_bbox(format=self.bbox_format) + instances.denormalize(w, h) + nl = len(instances) + + if self.return_mask: + if nl: + masks, instances, cls = self._format_segments(instances, cls, w, h) + masks = torch.from_numpy(masks) + else: + masks = torch.zeros( + 1 if self.mask_overlap else nl, img.shape[0] // self.mask_ratio, img.shape[1] // self.mask_ratio + ) + labels["masks"] = masks + labels["img"] = self._format_img(img) + labels["cls"] = torch.from_numpy(cls) if nl else torch.zeros(nl) + labels["bboxes"] = torch.from_numpy(instances.bboxes) if nl else torch.zeros((nl, 4)) + if self.return_keypoint: + labels["keypoints"] = torch.from_numpy(instances.keypoints) + if self.normalize: + labels["keypoints"][..., 0] /= w + labels["keypoints"][..., 1] /= h + if self.return_obb: + labels["bboxes"] = ( + xyxyxyxy2xywhr(torch.from_numpy(instances.segments)) if len(instances.segments) else torch.zeros((0, 5)) + ) + # NOTE: need to normalize obb in xywhr format for width-height consistency + if self.normalize: + labels["bboxes"][:, [0, 2]] /= w + labels["bboxes"][:, [1, 3]] /= h + # Then we can use collate_fn + if self.batch_idx: + labels["batch_idx"] = torch.zeros(nl) + return labels + + def _format_img(self, img): + """Format the image for YOLO from Numpy array to PyTorch tensor.""" + if len(img.shape) < 3: + img = np.expand_dims(img, -1) + img = img.transpose(2, 0, 1) + img = np.ascontiguousarray(img[::-1] if random.uniform(0, 1) > self.bgr else img) + img = torch.from_numpy(img) + return img + + def _format_segments(self, instances, cls, w, h): + """Convert polygon points to bitmap.""" + segments = instances.segments + if self.mask_overlap: + masks, sorted_idx = polygons2masks_overlap((h, w), segments, downsample_ratio=self.mask_ratio) + masks = masks[None] # (640, 640) -> (1, 640, 640) + instances = instances[sorted_idx] + cls = cls[sorted_idx] + else: + masks = polygons2masks((h, w), segments, color=1, downsample_ratio=self.mask_ratio) + + return masks, instances, cls + + +class RandomLoadText: + """ + Randomly sample positive texts and negative texts and update the class indices accordingly to the number of samples. + + Attributes: + prompt_format (str): Format for prompt. Default is '{}'. + neg_samples (tuple[int]): A ranger to randomly sample negative texts, Default is (80, 80). + max_samples (int): The max number of different text samples in one image, Default is 80. + padding (bool): Whether to pad texts to max_samples. Default is False. + padding_value (str): The padding text. Default is "". + """ + + def __init__( + self, + prompt_format: str = "{}", + neg_samples: Tuple[int, int] = (80, 80), + max_samples: int = 80, + padding: bool = False, + padding_value: str = "", + ) -> None: + """Initializes the RandomLoadText class with given parameters.""" + self.prompt_format = prompt_format + self.neg_samples = neg_samples + self.max_samples = max_samples + self.padding = padding + self.padding_value = padding_value + + def __call__(self, labels: dict) -> dict: + """Return updated classes and texts.""" + assert "texts" in labels, "No texts found in labels." + class_texts = labels["texts"] + num_classes = len(class_texts) + cls = np.asarray(labels.pop("cls"), dtype=int) + pos_labels = np.unique(cls).tolist() + + if len(pos_labels) > self.max_samples: + pos_labels = set(random.sample(pos_labels, k=self.max_samples)) + + neg_samples = min(min(num_classes, self.max_samples) - len(pos_labels), random.randint(*self.neg_samples)) + neg_labels = [] + for i in range(num_classes): + if i not in pos_labels: + neg_labels.append(i) + neg_labels = random.sample(neg_labels, k=neg_samples) + + sampled_labels = pos_labels + neg_labels + random.shuffle(sampled_labels) + + label2ids = {label: i for i, label in enumerate(sampled_labels)} + valid_idx = np.zeros(len(labels["instances"]), dtype=bool) + new_cls = [] + for i, label in enumerate(cls.squeeze(-1).tolist()): + if label not in label2ids: + continue + valid_idx[i] = True + new_cls.append([label2ids[label]]) + labels["instances"] = labels["instances"][valid_idx] + labels["cls"] = np.array(new_cls) + + # Randomly select one prompt when there's more than one prompts + texts = [] + for label in sampled_labels: + prompts = class_texts[label] + assert len(prompts) > 0 + prompt = self.prompt_format.format(prompts[random.randrange(len(prompts))]) + texts.append(prompt) + + if self.padding: + valid_labels = len(pos_labels) + len(neg_labels) + num_padding = self.max_samples - valid_labels + if num_padding > 0: + texts += [self.padding_value] * num_padding + + labels["texts"] = texts + return labels + + +def v8_transforms(dataset, imgsz, hyp, stretch=False): + """Convert images to a size suitable for YOLOv8 training.""" + pre_transform = Compose( + [ + Mosaic(dataset, imgsz=imgsz, p=hyp.mosaic), + CopyPaste(p=hyp.copy_paste), + RandomPerspective( + degrees=hyp.degrees, + translate=hyp.translate, + scale=hyp.scale, + shear=hyp.shear, + perspective=hyp.perspective, + pre_transform=None if stretch else LetterBox(new_shape=(imgsz, imgsz)), + ), + ] + ) + flip_idx = dataset.data.get("flip_idx", []) # for keypoints augmentation + if dataset.use_keypoints: + kpt_shape = dataset.data.get("kpt_shape", None) + if len(flip_idx) == 0 and hyp.fliplr > 0.0: + hyp.fliplr = 0.0 + LOGGER.warning("WARNING ⚠️ No 'flip_idx' array defined in data.yaml, setting augmentation 'fliplr=0.0'") + elif flip_idx and (len(flip_idx) != kpt_shape[0]): + raise ValueError(f"data.yaml flip_idx={flip_idx} length must be equal to kpt_shape[0]={kpt_shape[0]}") + + return Compose( + [ + pre_transform, + MixUp(dataset, pre_transform=pre_transform, p=hyp.mixup), + Albumentations(p=1.0), + RandomHSV(hgain=hyp.hsv_h, sgain=hyp.hsv_s, vgain=hyp.hsv_v), + RandomFlip(direction="vertical", p=hyp.flipud), + RandomFlip(direction="horizontal", p=hyp.fliplr, flip_idx=flip_idx), + ] + ) # transforms + + +# Classification augmentations ----------------------------------------------------------------------------------------- +def classify_transforms( + size=224, + mean=DEFAULT_MEAN, + std=DEFAULT_STD, + interpolation=Image.BILINEAR, + crop_fraction: float = DEFAULT_CROP_FRACTION, +): + """ + Classification transforms for evaluation/inference. Inspired by timm/data/transforms_factory.py. + + Args: + size (int): image size + mean (tuple): mean values of RGB channels + std (tuple): std values of RGB channels + interpolation (T.InterpolationMode): interpolation mode. default is T.InterpolationMode.BILINEAR. + crop_fraction (float): fraction of image to crop. default is 1.0. + + Returns: + (T.Compose): torchvision transforms + """ + import torchvision.transforms as T # scope for faster 'import ultralytics' + + if isinstance(size, (tuple, list)): + assert len(size) == 2 + scale_size = tuple(math.floor(x / crop_fraction) for x in size) + else: + scale_size = math.floor(size / crop_fraction) + scale_size = (scale_size, scale_size) + + # Aspect ratio is preserved, crops center within image, no borders are added, image is lost + if scale_size[0] == scale_size[1]: + # Simple case, use torchvision built-in Resize with the shortest edge mode (scalar size arg) + tfl = [T.Resize(scale_size[0], interpolation=interpolation)] + else: + # Resize the shortest edge to matching target dim for non-square target + tfl = [T.Resize(scale_size)] + tfl += [T.CenterCrop(size)] + + tfl += [ + T.ToTensor(), + T.Normalize( + mean=torch.tensor(mean), + std=torch.tensor(std), + ), + ] + + return T.Compose(tfl) + + +# Classification training augmentations -------------------------------------------------------------------------------- +def classify_augmentations( + size=224, + mean=DEFAULT_MEAN, + std=DEFAULT_STD, + scale=None, + ratio=None, + hflip=0.5, + vflip=0.0, + auto_augment=None, + hsv_h=0.015, # image HSV-Hue augmentation (fraction) + hsv_s=0.4, # image HSV-Saturation augmentation (fraction) + hsv_v=0.4, # image HSV-Value augmentation (fraction) + force_color_jitter=False, + erasing=0.0, + interpolation=Image.BILINEAR, +): + """ + Classification transforms with augmentation for training. Inspired by timm/data/transforms_factory.py. + + Args: + size (int): image size + scale (tuple): scale range of the image. default is (0.08, 1.0) + ratio (tuple): aspect ratio range of the image. default is (3./4., 4./3.) + mean (tuple): mean values of RGB channels + std (tuple): std values of RGB channels + hflip (float): probability of horizontal flip + vflip (float): probability of vertical flip + auto_augment (str): auto augmentation policy. can be 'randaugment', 'augmix', 'autoaugment' or None. + hsv_h (float): image HSV-Hue augmentation (fraction) + hsv_s (float): image HSV-Saturation augmentation (fraction) + hsv_v (float): image HSV-Value augmentation (fraction) + force_color_jitter (bool): force to apply color jitter even if auto augment is enabled + erasing (float): probability of random erasing + interpolation (T.InterpolationMode): interpolation mode. default is T.InterpolationMode.BILINEAR. + + Returns: + (T.Compose): torchvision transforms + """ + # Transforms to apply if Albumentations not installed + import torchvision.transforms as T # scope for faster 'import ultralytics' + + if not isinstance(size, int): + raise TypeError(f"classify_transforms() size {size} must be integer, not (list, tuple)") + scale = tuple(scale or (0.08, 1.0)) # default imagenet scale range + ratio = tuple(ratio or (3.0 / 4.0, 4.0 / 3.0)) # default imagenet ratio range + primary_tfl = [T.RandomResizedCrop(size, scale=scale, ratio=ratio, interpolation=interpolation)] + if hflip > 0.0: + primary_tfl += [T.RandomHorizontalFlip(p=hflip)] + if vflip > 0.0: + primary_tfl += [T.RandomVerticalFlip(p=vflip)] + + secondary_tfl = [] + disable_color_jitter = False + if auto_augment: + assert isinstance(auto_augment, str) + # color jitter is typically disabled if AA/RA on, + # this allows override without breaking old hparm cfgs + disable_color_jitter = not force_color_jitter + + if auto_augment == "randaugment": + if TORCHVISION_0_11: + secondary_tfl += [T.RandAugment(interpolation=interpolation)] + else: + LOGGER.warning('"auto_augment=randaugment" requires torchvision >= 0.11.0. Disabling it.') + + elif auto_augment == "augmix": + if TORCHVISION_0_13: + secondary_tfl += [T.AugMix(interpolation=interpolation)] + else: + LOGGER.warning('"auto_augment=augmix" requires torchvision >= 0.13.0. Disabling it.') + + elif auto_augment == "autoaugment": + if TORCHVISION_0_10: + secondary_tfl += [T.AutoAugment(interpolation=interpolation)] + else: + LOGGER.warning('"auto_augment=autoaugment" requires torchvision >= 0.10.0. Disabling it.') + + else: + raise ValueError( + f'Invalid auto_augment policy: {auto_augment}. Should be one of "randaugment", ' + f'"augmix", "autoaugment" or None' + ) + + if not disable_color_jitter: + secondary_tfl += [T.ColorJitter(brightness=hsv_v, contrast=hsv_v, saturation=hsv_s, hue=hsv_h)] + + final_tfl = [ + T.ToTensor(), + T.Normalize(mean=torch.tensor(mean), std=torch.tensor(std)), + T.RandomErasing(p=erasing, inplace=True), + ] + + return T.Compose(primary_tfl + secondary_tfl + final_tfl) + + +# NOTE: keep this class for backward compatibility +class ClassifyLetterBox: + """ + YOLOv8 LetterBox class for image preprocessing, designed to be part of a transformation pipeline, e.g., + T.Compose([LetterBox(size), ToTensor()]). + + Attributes: + h (int): Target height of the image. + w (int): Target width of the image. + auto (bool): If True, automatically solves for short side using stride. + stride (int): The stride value, used when 'auto' is True. + """ + + def __init__(self, size=(640, 640), auto=False, stride=32): + """ + Initializes the ClassifyLetterBox class with a target size, auto-flag, and stride. + + Args: + size (Union[int, Tuple[int, int]]): The target dimensions (height, width) for the letterbox. + auto (bool): If True, automatically calculates the short side based on stride. + stride (int): The stride value, used when 'auto' is True. + """ + super().__init__() + self.h, self.w = (size, size) if isinstance(size, int) else size + self.auto = auto # pass max size integer, automatically solve for short side using stride + self.stride = stride # used with auto + + def __call__(self, im): + """ + Resizes the image and pads it with a letterbox method. + + Args: + im (numpy.ndarray): The input image as a numpy array of shape HWC. + + Returns: + (numpy.ndarray): The letterboxed and resized image as a numpy array. + """ + imh, imw = im.shape[:2] + r = min(self.h / imh, self.w / imw) # ratio of new/old dimensions + h, w = round(imh * r), round(imw * r) # resized image dimensions + + # Calculate padding dimensions + hs, ws = (math.ceil(x / self.stride) * self.stride for x in (h, w)) if self.auto else (self.h, self.w) + top, left = round((hs - h) / 2 - 0.1), round((ws - w) / 2 - 0.1) + + # Create padded image + im_out = np.full((hs, ws, 3), 114, dtype=im.dtype) + im_out[top : top + h, left : left + w] = cv2.resize(im, (w, h), interpolation=cv2.INTER_LINEAR) + return im_out + + +# NOTE: keep this class for backward compatibility +class CenterCrop: + """YOLOv8 CenterCrop class for image preprocessing, designed to be part of a transformation pipeline, e.g., + T.Compose([CenterCrop(size), ToTensor()]). + """ + + def __init__(self, size=640): + """Converts an image from numpy array to PyTorch tensor.""" + super().__init__() + self.h, self.w = (size, size) if isinstance(size, int) else size + + def __call__(self, im): + """ + Resizes and crops the center of the image using a letterbox method. + + Args: + im (numpy.ndarray): The input image as a numpy array of shape HWC. + + Returns: + (numpy.ndarray): The center-cropped and resized image as a numpy array. + """ + imh, imw = im.shape[:2] + m = min(imh, imw) # min dimension + top, left = (imh - m) // 2, (imw - m) // 2 + return cv2.resize(im[top : top + m, left : left + m], (self.w, self.h), interpolation=cv2.INTER_LINEAR) + + +# NOTE: keep this class for backward compatibility +class ToTensor: + """YOLOv8 ToTensor class for image preprocessing, i.e., T.Compose([LetterBox(size), ToTensor()]).""" + + def __init__(self, half=False): + """Initialize YOLOv8 ToTensor object with optional half-precision support.""" + super().__init__() + self.half = half + + def __call__(self, im): + """ + Transforms an image from a numpy array to a PyTorch tensor, applying optional half-precision and normalization. + + Args: + im (numpy.ndarray): Input image as a numpy array with shape (H, W, C) in BGR order. + + Returns: + (torch.Tensor): The transformed image as a PyTorch tensor in float32 or float16, normalized to [0, 1]. + """ + im = np.ascontiguousarray(im.transpose((2, 0, 1))[::-1]) # HWC to CHW -> BGR to RGB -> contiguous + im = torch.from_numpy(im) # to torch + im = im.half() if self.half else im.float() # uint8 to fp16/32 + im /= 255.0 # 0-255 to 0.0-1.0 + return im diff --git a/ultralytics/data/base.py b/ultralytics/data/base.py new file mode 100644 index 0000000..6f0ca7f --- /dev/null +++ b/ultralytics/data/base.py @@ -0,0 +1,310 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import glob +import math +import os +import random +from copy import deepcopy +from multiprocessing.pool import ThreadPool +from pathlib import Path +from typing import Optional + +import cv2 +import numpy as np +import psutil +from torch.utils.data import Dataset + +from ultralytics.utils import DEFAULT_CFG, LOCAL_RANK, LOGGER, NUM_THREADS, TQDM + +from .utils import FORMATS_HELP_MSG, HELP_URL, IMG_FORMATS + + +class BaseDataset(Dataset): + """ + Base dataset class for loading and processing image data. + + Args: + img_path (str): Path to the folder containing images. + imgsz (int, optional): Image size. Defaults to 640. + cache (bool, optional): Cache images to RAM or disk during training. Defaults to False. + augment (bool, optional): If True, data augmentation is applied. Defaults to True. + hyp (dict, optional): Hyperparameters to apply data augmentation. Defaults to None. + prefix (str, optional): Prefix to print in log messages. Defaults to ''. + rect (bool, optional): If True, rectangular training is used. Defaults to False. + batch_size (int, optional): Size of batches. Defaults to None. + stride (int, optional): Stride. Defaults to 32. + pad (float, optional): Padding. Defaults to 0.0. + single_cls (bool, optional): If True, single class training is used. Defaults to False. + classes (list): List of included classes. Default is None. + fraction (float): Fraction of dataset to utilize. Default is 1.0 (use all data). + + Attributes: + im_files (list): List of image file paths. + labels (list): List of label data dictionaries. + ni (int): Number of images in the dataset. + ims (list): List of loaded images. + npy_files (list): List of numpy file paths. + transforms (callable): Image transformation function. + """ + + def __init__( + self, + img_path, + imgsz=640, + cache=False, + augment=True, + hyp=DEFAULT_CFG, + prefix="", + rect=False, + batch_size=16, + stride=32, + pad=0.5, + single_cls=False, + classes=None, + fraction=1.0, + ): + """Initialize BaseDataset with given configuration and options.""" + super().__init__() + self.img_path = img_path + self.imgsz = imgsz + self.augment = augment + self.single_cls = single_cls + self.prefix = prefix + self.fraction = fraction + self.im_files = self.get_img_files(self.img_path) + self.labels = self.get_labels() + self.update_labels(include_class=classes) # single_cls and include_class + self.ni = len(self.labels) # number of images + self.rect = rect + self.batch_size = batch_size + self.stride = stride + self.pad = pad + if self.rect: + assert self.batch_size is not None + self.set_rectangle() + + # Buffer thread for mosaic images + self.buffer = [] # buffer size = batch size + self.max_buffer_length = min((self.ni, self.batch_size * 8, 1000)) if self.augment else 0 + + # Cache images (options are cache = True, False, None, "ram", "disk") + self.ims, self.im_hw0, self.im_hw = [None] * self.ni, [None] * self.ni, [None] * self.ni + self.npy_files = [Path(f).with_suffix(".npy") for f in self.im_files] + self.cache = cache.lower() if isinstance(cache, str) else "ram" if cache is True else None + if (self.cache == "ram" and self.check_cache_ram()) or self.cache == "disk": + self.cache_images() + + # Transforms + self.transforms = self.build_transforms(hyp=hyp) + + def get_img_files(self, img_path): + """Read image files.""" + try: + f = [] # image files + for p in img_path if isinstance(img_path, list) else [img_path]: + p = Path(p) # os-agnostic + if p.is_dir(): # dir + f += glob.glob(str(p / "**" / "*.*"), recursive=True) + # F = list(p.rglob('*.*')) # pathlib + elif p.is_file(): # file + with open(p) as t: + t = t.read().strip().splitlines() + parent = str(p.parent) + os.sep + f += [x.replace("./", parent) if x.startswith("./") else x for x in t] # local to global path + # F += [p.parent / x.lstrip(os.sep) for x in t] # local to global path (pathlib) + else: + raise FileNotFoundError(f"{self.prefix}{p} does not exist") + im_files = sorted(x.replace("/", os.sep) for x in f if x.split(".")[-1].lower() in IMG_FORMATS) + # self.img_files = sorted([x for x in f if x.suffix[1:].lower() in IMG_FORMATS]) # pathlib + assert im_files, f"{self.prefix}No images found in {img_path}. {FORMATS_HELP_MSG}" + except Exception as e: + raise FileNotFoundError(f"{self.prefix}Error loading data from {img_path}\n{HELP_URL}") from e + if self.fraction < 1: + im_files = im_files[: round(len(im_files) * self.fraction)] # retain a fraction of the dataset + return im_files + + def update_labels(self, include_class: Optional[list]): + """Update labels to include only these classes (optional).""" + include_class_array = np.array(include_class).reshape(1, -1) + for i in range(len(self.labels)): + if include_class is not None: + cls = self.labels[i]["cls"] + bboxes = self.labels[i]["bboxes"] + segments = self.labels[i]["segments"] + keypoints = self.labels[i]["keypoints"] + j = (cls == include_class_array).any(1) + self.labels[i]["cls"] = cls[j] + self.labels[i]["bboxes"] = bboxes[j] + if segments: + self.labels[i]["segments"] = [segments[si] for si, idx in enumerate(j) if idx] + if keypoints is not None: + self.labels[i]["keypoints"] = keypoints[j] + if self.single_cls: + self.labels[i]["cls"][:, 0] = 0 + + def load_image(self, i, rect_mode=True): + """Loads 1 image from dataset index 'i', returns (im, resized hw).""" + im, f, fn = self.ims[i], self.im_files[i], self.npy_files[i] + if im is None: # not cached in RAM + if fn.exists(): # load npy + try: + im = np.load(fn) + except Exception as e: + LOGGER.warning(f"{self.prefix}WARNING ⚠️ Removing corrupt *.npy image file {fn} due to: {e}") + Path(fn).unlink(missing_ok=True) + im = cv2.imread(f) # BGR + else: # read image + im = cv2.imread(f) # BGR + if im is None: + raise FileNotFoundError(f"Image Not Found {f}") + + h0, w0 = im.shape[:2] # orig hw + if rect_mode: # resize long side to imgsz while maintaining aspect ratio + r = self.imgsz / max(h0, w0) # ratio + if r != 1: # if sizes are not equal + w, h = (min(math.ceil(w0 * r), self.imgsz), min(math.ceil(h0 * r), self.imgsz)) + im = cv2.resize(im, (w, h), interpolation=cv2.INTER_LINEAR) + elif not (h0 == w0 == self.imgsz): # resize by stretching image to square imgsz + im = cv2.resize(im, (self.imgsz, self.imgsz), interpolation=cv2.INTER_LINEAR) + + # Add to buffer if training with augmentations + if self.augment: + self.ims[i], self.im_hw0[i], self.im_hw[i] = im, (h0, w0), im.shape[:2] # im, hw_original, hw_resized + self.buffer.append(i) + if len(self.buffer) >= self.max_buffer_length: + j = self.buffer.pop(0) + if self.cache != "ram": + self.ims[j], self.im_hw0[j], self.im_hw[j] = None, None, None + + return im, (h0, w0), im.shape[:2] + + return self.ims[i], self.im_hw0[i], self.im_hw[i] + + def cache_images(self): + """Cache images to memory or disk.""" + b, gb = 0, 1 << 30 # bytes of cached images, bytes per gigabytes + fcn, storage = (self.cache_images_to_disk, "Disk") if self.cache == "disk" else (self.load_image, "RAM") + with ThreadPool(NUM_THREADS) as pool: + results = pool.imap(fcn, range(self.ni)) + pbar = TQDM(enumerate(results), total=self.ni, disable=LOCAL_RANK > 0) + for i, x in pbar: + if self.cache == "disk": + b += self.npy_files[i].stat().st_size + else: # 'ram' + self.ims[i], self.im_hw0[i], self.im_hw[i] = x # im, hw_orig, hw_resized = load_image(self, i) + b += self.ims[i].nbytes + pbar.desc = f"{self.prefix}Caching images ({b / gb:.1f}GB {storage})" + pbar.close() + + def cache_images_to_disk(self, i): + """Saves an image as an *.npy file for faster loading.""" + f = self.npy_files[i] + if not f.exists(): + np.save(f.as_posix(), cv2.imread(self.im_files[i]), allow_pickle=False) + + def check_cache_ram(self, safety_margin=0.5): + """Check image caching requirements vs available memory.""" + b, gb = 0, 1 << 30 # bytes of cached images, bytes per gigabytes + n = min(self.ni, 30) # extrapolate from 30 random images + for _ in range(n): + im = cv2.imread(random.choice(self.im_files)) # sample image + ratio = self.imgsz / max(im.shape[0], im.shape[1]) # max(h, w) # ratio + b += im.nbytes * ratio**2 + mem_required = b * self.ni / n * (1 + safety_margin) # GB required to cache dataset into RAM + mem = psutil.virtual_memory() + success = mem_required < mem.available # to cache or not to cache, that is the question + if not success: + self.cache = None + LOGGER.info( + f"{self.prefix}{mem_required / gb:.1f}GB RAM required to cache images " + f"with {int(safety_margin * 100)}% safety margin but only " + f"{mem.available / gb:.1f}/{mem.total / gb:.1f}GB available, not caching images ⚠️" + ) + return success + + def set_rectangle(self): + """Sets the shape of bounding boxes for YOLO detections as rectangles.""" + bi = np.floor(np.arange(self.ni) / self.batch_size).astype(int) # batch index + nb = bi[-1] + 1 # number of batches + + s = np.array([x.pop("shape") for x in self.labels]) # hw + ar = s[:, 0] / s[:, 1] # aspect ratio + irect = ar.argsort() + self.im_files = [self.im_files[i] for i in irect] + self.labels = [self.labels[i] for i in irect] + ar = ar[irect] + + # Set training image shapes + shapes = [[1, 1]] * nb + for i in range(nb): + ari = ar[bi == i] + mini, maxi = ari.min(), ari.max() + if maxi < 1: + shapes[i] = [maxi, 1] + elif mini > 1: + shapes[i] = [1, 1 / mini] + + self.batch_shapes = np.ceil(np.array(shapes) * self.imgsz / self.stride + self.pad).astype(int) * self.stride + self.batch = bi # batch index of image + + def __getitem__(self, index): + """Returns transformed label information for given index.""" + return self.transforms(self.get_image_and_label(index)) + + def get_image_and_label(self, index): + """Get and return label information from the dataset.""" + label = deepcopy(self.labels[index]) # requires deepcopy() https://github.com/ultralytics/ultralytics/pull/1948 + label.pop("shape", None) # shape is for rect, remove it + label["img"], label["ori_shape"], label["resized_shape"] = self.load_image(index) + label["ratio_pad"] = ( + label["resized_shape"][0] / label["ori_shape"][0], + label["resized_shape"][1] / label["ori_shape"][1], + ) # for evaluation + if self.rect: + label["rect_shape"] = self.batch_shapes[self.batch[index]] + return self.update_labels_info(label) + + def __len__(self): + """Returns the length of the labels list for the dataset.""" + return len(self.labels) + + def update_labels_info(self, label): + """Custom your label format here.""" + return label + + def build_transforms(self, hyp=None): + """ + Users can customize augmentations here. + + Example: + ```python + if self.augment: + # Training transforms + return Compose([]) + else: + # Val transforms + return Compose([]) + ``` + """ + raise NotImplementedError + + def get_labels(self): + """ + Users can customize their own format here. + + Note: + Ensure output is a dictionary with the following keys: + ```python + dict( + im_file=im_file, + shape=shape, # format: (height, width) + cls=cls, + bboxes=bboxes, # xywh + segments=segments, # xy + keypoints=keypoints, # xy + normalized=True, # or False + bbox_format="xyxy", # or xywh, ltwh + ) + ``` + """ + raise NotImplementedError diff --git a/ultralytics/data/build.py b/ultralytics/data/build.py new file mode 100644 index 0000000..ce8785d --- /dev/null +++ b/ultralytics/data/build.py @@ -0,0 +1,209 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import os +import random +from pathlib import Path + +import numpy as np +import torch +from PIL import Image +from torch.utils.data import dataloader, distributed + +from ultralytics.data.loaders import ( + LOADERS, + LoadImagesAndVideos, + LoadPilAndNumpy, + LoadScreenshots, + LoadStreams, + LoadTensor, + SourceTypes, + autocast_list, +) +from ultralytics.data.utils import IMG_FORMATS, VID_FORMATS +from ultralytics.utils import RANK, colorstr +from ultralytics.utils.checks import check_file + +from .dataset import GroundingDataset, YOLODataset, YOLOMultiModalDataset +from .utils import PIN_MEMORY + + +class InfiniteDataLoader(dataloader.DataLoader): + """ + Dataloader that reuses workers. + + Uses same syntax as vanilla DataLoader. + """ + + def __init__(self, *args, **kwargs): + """Dataloader that infinitely recycles workers, inherits from DataLoader.""" + super().__init__(*args, **kwargs) + object.__setattr__(self, "batch_sampler", _RepeatSampler(self.batch_sampler)) + self.iterator = super().__iter__() + + def __len__(self): + """Returns the length of the batch sampler's sampler.""" + return len(self.batch_sampler.sampler) + + def __iter__(self): + """Creates a sampler that repeats indefinitely.""" + for _ in range(len(self)): + yield next(self.iterator) + + def reset(self): + """ + Reset iterator. + + This is useful when we want to modify settings of dataset while training. + """ + self.iterator = self._get_iterator() + + +class _RepeatSampler: + """ + Sampler that repeats forever. + + Args: + sampler (Dataset.sampler): The sampler to repeat. + """ + + def __init__(self, sampler): + """Initializes an object that repeats a given sampler indefinitely.""" + self.sampler = sampler + + def __iter__(self): + """Iterates over the 'sampler' and yields its contents.""" + while True: + yield from iter(self.sampler) + + +def seed_worker(worker_id): # noqa + """Set dataloader worker seed https://pytorch.org/docs/stable/notes/randomness.html#dataloader.""" + worker_seed = torch.initial_seed() % 2**32 + np.random.seed(worker_seed) + random.seed(worker_seed) + + +def build_yolo_dataset(cfg, img_path, batch, data, mode="train", rect=False, stride=32, multi_modal=False): + """Build YOLO Dataset.""" + dataset = YOLOMultiModalDataset if multi_modal else YOLODataset + return dataset( + img_path=img_path, + imgsz=cfg.imgsz, + batch_size=batch, + augment=mode == "train", # augmentation + hyp=cfg, # TODO: probably add a get_hyps_from_cfg function + rect=cfg.rect or rect, # rectangular batches + cache=cfg.cache or None, + single_cls=cfg.single_cls or False, + stride=int(stride), + pad=0.0 if mode == "train" else 0.5, + prefix=colorstr(f"{mode}: "), + task=cfg.task, + classes=cfg.classes, + data=data, + fraction=cfg.fraction if mode == "train" else 1.0, + ) + + +def build_grounding(cfg, img_path, json_file, batch, mode="train", rect=False, stride=32): + """Build YOLO Dataset.""" + return GroundingDataset( + img_path=img_path, + json_file=json_file, + imgsz=cfg.imgsz, + batch_size=batch, + augment=mode == "train", # augmentation + hyp=cfg, # TODO: probably add a get_hyps_from_cfg function + rect=cfg.rect or rect, # rectangular batches + cache=cfg.cache or None, + single_cls=cfg.single_cls or False, + stride=int(stride), + pad=0.0 if mode == "train" else 0.5, + prefix=colorstr(f"{mode}: "), + task=cfg.task, + classes=cfg.classes, + fraction=cfg.fraction if mode == "train" else 1.0, + ) + + +def build_dataloader(dataset, batch, workers, shuffle=True, rank=-1): + """Return an InfiniteDataLoader or DataLoader for training or validation set.""" + batch = min(batch, len(dataset)) + nd = torch.cuda.device_count() # number of CUDA devices + nw = min([os.cpu_count() // max(nd, 1), workers]) # number of workers + sampler = None if rank == -1 else distributed.DistributedSampler(dataset, shuffle=shuffle) + generator = torch.Generator() + generator.manual_seed(6148914691236517205 + RANK) + return InfiniteDataLoader( + dataset=dataset, + batch_size=batch, + shuffle=shuffle and sampler is None, + num_workers=nw, + sampler=sampler, + pin_memory=PIN_MEMORY, + collate_fn=getattr(dataset, "collate_fn", None), + worker_init_fn=seed_worker, + generator=generator, + ) + + +def check_source(source): + """Check source type and return corresponding flag values.""" + webcam, screenshot, from_img, in_memory, tensor = False, False, False, False, False + if isinstance(source, (str, int, Path)): # int for local usb camera + source = str(source) + is_file = Path(source).suffix[1:] in (IMG_FORMATS | VID_FORMATS) + is_url = source.lower().startswith(("https://", "http://", "rtsp://", "rtmp://", "tcp://")) + webcam = source.isnumeric() or source.endswith(".streams") or (is_url and not is_file) + screenshot = source.lower() == "screen" + if is_url and is_file: + source = check_file(source) # download + elif isinstance(source, LOADERS): + in_memory = True + elif isinstance(source, (list, tuple)): + source = autocast_list(source) # convert all list elements to PIL or np arrays + from_img = True + elif isinstance(source, (Image.Image, np.ndarray)): + from_img = True + elif isinstance(source, torch.Tensor): + tensor = True + else: + raise TypeError("Unsupported image type. For supported types see https://docs.ultralytics.com/modes/predict") + + return source, webcam, screenshot, from_img, in_memory, tensor + + +def load_inference_source(source=None, batch=1, vid_stride=1, buffer=False): + """ + Loads an inference source for object detection and applies necessary transformations. + + Args: + source (str, Path, Tensor, PIL.Image, np.ndarray): The input source for inference. + batch (int, optional): Batch size for dataloaders. Default is 1. + vid_stride (int, optional): The frame interval for video sources. Default is 1. + buffer (bool, optional): Determined whether stream frames will be buffered. Default is False. + + Returns: + dataset (Dataset): A dataset object for the specified input source. + """ + source, stream, screenshot, from_img, in_memory, tensor = check_source(source) + source_type = source.source_type if in_memory else SourceTypes(stream, screenshot, from_img, tensor) + + # Dataloader + if tensor: + dataset = LoadTensor(source) + elif in_memory: + dataset = source + elif stream: + dataset = LoadStreams(source, vid_stride=vid_stride, buffer=buffer) + elif screenshot: + dataset = LoadScreenshots(source) + elif from_img: + dataset = LoadPilAndNumpy(source) + else: + dataset = LoadImagesAndVideos(source, batch=batch, vid_stride=vid_stride) + + # Attach source types to the dataset + setattr(dataset, "source_type", source_type) + + return dataset diff --git a/ultralytics/data/converter.py b/ultralytics/data/converter.py new file mode 100644 index 0000000..239bdb8 --- /dev/null +++ b/ultralytics/data/converter.py @@ -0,0 +1,561 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import json +from collections import defaultdict +from pathlib import Path + +import cv2 +import numpy as np + +from ultralytics.utils import LOGGER, TQDM +from ultralytics.utils.files import increment_path + + +def coco91_to_coco80_class(): + """ + Converts 91-index COCO class IDs to 80-index COCO class IDs. + + Returns: + (list): A list of 91 class IDs where the index represents the 80-index class ID and the value is the + corresponding 91-index class ID. + """ + return [ + 0, + 1, + 2, + 3, + 4, + 5, + 6, + 7, + 8, + 9, + 10, + None, + 11, + 12, + 13, + 14, + 15, + 16, + 17, + 18, + 19, + 20, + 21, + 22, + 23, + None, + 24, + 25, + None, + None, + 26, + 27, + 28, + 29, + 30, + 31, + 32, + 33, + 34, + 35, + 36, + 37, + 38, + 39, + None, + 40, + 41, + 42, + 43, + 44, + 45, + 46, + 47, + 48, + 49, + 50, + 51, + 52, + 53, + 54, + 55, + 56, + 57, + 58, + 59, + None, + 60, + None, + None, + 61, + None, + 62, + 63, + 64, + 65, + 66, + 67, + 68, + 69, + 70, + 71, + 72, + None, + 73, + 74, + 75, + 76, + 77, + 78, + 79, + None, + ] + + +def coco80_to_coco91_class(): + """ + Converts 80-index (val2014) to 91-index (paper). + For details see https://tech.amikelive.com/node-718/what-object-categories-labels-are-in-coco-dataset/. + + Example: + ```python + import numpy as np + + a = np.loadtxt('data/coco.names', dtype='str', delimiter='\n') + b = np.loadtxt('data/coco_paper.names', dtype='str', delimiter='\n') + x1 = [list(a[i] == b).index(True) + 1 for i in range(80)] # darknet to coco + x2 = [list(b[i] == a).index(True) if any(b[i] == a) else None for i in range(91)] # coco to darknet + ``` + """ + return [ + 1, + 2, + 3, + 4, + 5, + 6, + 7, + 8, + 9, + 10, + 11, + 13, + 14, + 15, + 16, + 17, + 18, + 19, + 20, + 21, + 22, + 23, + 24, + 25, + 27, + 28, + 31, + 32, + 33, + 34, + 35, + 36, + 37, + 38, + 39, + 40, + 41, + 42, + 43, + 44, + 46, + 47, + 48, + 49, + 50, + 51, + 52, + 53, + 54, + 55, + 56, + 57, + 58, + 59, + 60, + 61, + 62, + 63, + 64, + 65, + 67, + 70, + 72, + 73, + 74, + 75, + 76, + 77, + 78, + 79, + 80, + 81, + 82, + 84, + 85, + 86, + 87, + 88, + 89, + 90, + ] + + +def convert_coco( + labels_dir="../coco/annotations/", + save_dir="coco_converted/", + use_segments=False, + use_keypoints=False, + cls91to80=True, + lvis=False, +): + """ + Converts COCO dataset annotations to a YOLO annotation format suitable for training YOLO models. + + Args: + labels_dir (str, optional): Path to directory containing COCO dataset annotation files. + save_dir (str, optional): Path to directory to save results to. + use_segments (bool, optional): Whether to include segmentation masks in the output. + use_keypoints (bool, optional): Whether to include keypoint annotations in the output. + cls91to80 (bool, optional): Whether to map 91 COCO class IDs to the corresponding 80 COCO class IDs. + lvis (bool, optional): Whether to convert data in lvis dataset way. + + Example: + ```python + from ultralytics.data.converter import convert_coco + + convert_coco('../datasets/coco/annotations/', use_segments=True, use_keypoints=False, cls91to80=True) + convert_coco('../datasets/lvis/annotations/', use_segments=True, use_keypoints=False, cls91to80=False, lvis=True) + ``` + + Output: + Generates output files in the specified output directory. + """ + + # Create dataset directory + save_dir = increment_path(save_dir) # increment if save directory already exists + for p in save_dir / "labels", save_dir / "images": + p.mkdir(parents=True, exist_ok=True) # make dir + + # Convert classes + coco80 = coco91_to_coco80_class() + + # Import json + for json_file in sorted(Path(labels_dir).resolve().glob("*.json")): + lname = "" if lvis else json_file.stem.replace("instances_", "") + fn = Path(save_dir) / "labels" / lname # folder name + fn.mkdir(parents=True, exist_ok=True) + if lvis: + # NOTE: create folders for both train and val in advance, + # since LVIS val set contains images from COCO 2017 train in addition to the COCO 2017 val split. + (fn / "train2017").mkdir(parents=True, exist_ok=True) + (fn / "val2017").mkdir(parents=True, exist_ok=True) + with open(json_file) as f: + data = json.load(f) + + # Create image dict + images = {f'{x["id"]:d}': x for x in data["images"]} + # Create image-annotations dict + imgToAnns = defaultdict(list) + for ann in data["annotations"]: + imgToAnns[ann["image_id"]].append(ann) + + image_txt = [] + # Write labels file + for img_id, anns in TQDM(imgToAnns.items(), desc=f"Annotations {json_file}"): + img = images[f"{img_id:d}"] + h, w = img["height"], img["width"] + f = str(Path(img["coco_url"]).relative_to("http://images.cocodataset.org")) if lvis else img["file_name"] + if lvis: + image_txt.append(str(Path("./images") / f)) + + bboxes = [] + segments = [] + keypoints = [] + for ann in anns: + if ann.get("iscrowd", False): + continue + # The COCO box format is [top left x, top left y, width, height] + box = np.array(ann["bbox"], dtype=np.float64) + box[:2] += box[2:] / 2 # xy top-left corner to center + box[[0, 2]] /= w # normalize x + box[[1, 3]] /= h # normalize y + if box[2] <= 0 or box[3] <= 0: # if w <= 0 and h <= 0 + continue + + cls = coco80[ann["category_id"] - 1] if cls91to80 else ann["category_id"] - 1 # class + box = [cls] + box.tolist() + if box not in bboxes: + bboxes.append(box) + if use_segments and ann.get("segmentation") is not None: + if len(ann["segmentation"]) == 0: + segments.append([]) + continue + elif len(ann["segmentation"]) > 1: + s = merge_multi_segment(ann["segmentation"]) + s = (np.concatenate(s, axis=0) / np.array([w, h])).reshape(-1).tolist() + else: + s = [j for i in ann["segmentation"] for j in i] # all segments concatenated + s = (np.array(s).reshape(-1, 2) / np.array([w, h])).reshape(-1).tolist() + s = [cls] + s + segments.append(s) + if use_keypoints and ann.get("keypoints") is not None: + keypoints.append( + box + (np.array(ann["keypoints"]).reshape(-1, 3) / np.array([w, h, 1])).reshape(-1).tolist() + ) + + # Write + with open((fn / f).with_suffix(".txt"), "a") as file: + for i in range(len(bboxes)): + if use_keypoints: + line = (*(keypoints[i]),) # cls, box, keypoints + else: + line = ( + *(segments[i] if use_segments and len(segments[i]) > 0 else bboxes[i]), + ) # cls, box or segments + file.write(("%g " * len(line)).rstrip() % line + "\n") + + if lvis: + with open((Path(save_dir) / json_file.name.replace("lvis_v1_", "").replace(".json", ".txt")), "a") as f: + for l in image_txt: + f.write(f"{l}\n") + + LOGGER.info(f"{'LVIS' if lvis else 'COCO'} data converted successfully.\nResults saved to {save_dir.resolve()}") + + +def convert_dota_to_yolo_obb(dota_root_path: str): + """ + Converts DOTA dataset annotations to YOLO OBB (Oriented Bounding Box) format. + + The function processes images in the 'train' and 'val' folders of the DOTA dataset. For each image, it reads the + associated label from the original labels directory and writes new labels in YOLO OBB format to a new directory. + + Args: + dota_root_path (str): The root directory path of the DOTA dataset. + + Example: + ```python + from ultralytics.data.converter import convert_dota_to_yolo_obb + + convert_dota_to_yolo_obb('path/to/DOTA') + ``` + + Notes: + The directory structure assumed for the DOTA dataset: + + - DOTA + ├─ images + │ ├─ train + │ └─ val + └─ labels + ├─ train_original + └─ val_original + + After execution, the function will organize the labels into: + + - DOTA + └─ labels + ├─ train + └─ val + """ + dota_root_path = Path(dota_root_path) + + # Class names to indices mapping + class_mapping = { + "plane": 0, + "ship": 1, + "storage-tank": 2, + "baseball-diamond": 3, + "tennis-court": 4, + "basketball-court": 5, + "ground-track-field": 6, + "harbor": 7, + "bridge": 8, + "large-vehicle": 9, + "small-vehicle": 10, + "helicopter": 11, + "roundabout": 12, + "soccer-ball-field": 13, + "swimming-pool": 14, + "container-crane": 15, + "airport": 16, + "helipad": 17, + } + + def convert_label(image_name, image_width, image_height, orig_label_dir, save_dir): + """Converts a single image's DOTA annotation to YOLO OBB format and saves it to a specified directory.""" + orig_label_path = orig_label_dir / f"{image_name}.txt" + save_path = save_dir / f"{image_name}.txt" + + with orig_label_path.open("r") as f, save_path.open("w") as g: + lines = f.readlines() + for line in lines: + parts = line.strip().split() + if len(parts) < 9: + continue + class_name = parts[8] + class_idx = class_mapping[class_name] + coords = [float(p) for p in parts[:8]] + normalized_coords = [ + coords[i] / image_width if i % 2 == 0 else coords[i] / image_height for i in range(8) + ] + formatted_coords = ["{:.6g}".format(coord) for coord in normalized_coords] + g.write(f"{class_idx} {' '.join(formatted_coords)}\n") + + for phase in ["train", "val"]: + image_dir = dota_root_path / "images" / phase + orig_label_dir = dota_root_path / "labels" / f"{phase}_original" + save_dir = dota_root_path / "labels" / phase + + save_dir.mkdir(parents=True, exist_ok=True) + + image_paths = list(image_dir.iterdir()) + for image_path in TQDM(image_paths, desc=f"Processing {phase} images"): + if image_path.suffix != ".png": + continue + image_name_without_ext = image_path.stem + img = cv2.imread(str(image_path)) + h, w = img.shape[:2] + convert_label(image_name_without_ext, w, h, orig_label_dir, save_dir) + + +def min_index(arr1, arr2): + """ + Find a pair of indexes with the shortest distance between two arrays of 2D points. + + Args: + arr1 (np.ndarray): A NumPy array of shape (N, 2) representing N 2D points. + arr2 (np.ndarray): A NumPy array of shape (M, 2) representing M 2D points. + + Returns: + (tuple): A tuple containing the indexes of the points with the shortest distance in arr1 and arr2 respectively. + """ + dis = ((arr1[:, None, :] - arr2[None, :, :]) ** 2).sum(-1) + return np.unravel_index(np.argmin(dis, axis=None), dis.shape) + + +def merge_multi_segment(segments): + """ + Merge multiple segments into one list by connecting the coordinates with the minimum distance between each segment. + This function connects these coordinates with a thin line to merge all segments into one. + + Args: + segments (List[List]): Original segmentations in COCO's JSON file. + Each element is a list of coordinates, like [segmentation1, segmentation2,...]. + + Returns: + s (List[np.ndarray]): A list of connected segments represented as NumPy arrays. + """ + s = [] + segments = [np.array(i).reshape(-1, 2) for i in segments] + idx_list = [[] for _ in range(len(segments))] + + # Record the indexes with min distance between each segment + for i in range(1, len(segments)): + idx1, idx2 = min_index(segments[i - 1], segments[i]) + idx_list[i - 1].append(idx1) + idx_list[i].append(idx2) + + # Use two round to connect all the segments + for k in range(2): + # Forward connection + if k == 0: + for i, idx in enumerate(idx_list): + # Middle segments have two indexes, reverse the index of middle segments + if len(idx) == 2 and idx[0] > idx[1]: + idx = idx[::-1] + segments[i] = segments[i][::-1, :] + + segments[i] = np.roll(segments[i], -idx[0], axis=0) + segments[i] = np.concatenate([segments[i], segments[i][:1]]) + # Deal with the first segment and the last one + if i in {0, len(idx_list) - 1}: + s.append(segments[i]) + else: + idx = [0, idx[1] - idx[0]] + s.append(segments[i][idx[0] : idx[1] + 1]) + + else: + for i in range(len(idx_list) - 1, -1, -1): + if i not in {0, len(idx_list) - 1}: + idx = idx_list[i] + nidx = abs(idx[1] - idx[0]) + s.append(segments[i][nidx:]) + return s + + +def yolo_bbox2segment(im_dir, save_dir=None, sam_model="sam_b.pt"): + """ + Converts existing object detection dataset (bounding boxes) to segmentation dataset or oriented bounding box (OBB) + in YOLO format. Generates segmentation data using SAM auto-annotator as needed. + + Args: + im_dir (str | Path): Path to image directory to convert. + save_dir (str | Path): Path to save the generated labels, labels will be saved + into `labels-segment` in the same directory level of `im_dir` if save_dir is None. Default: None. + sam_model (str): Segmentation model to use for intermediate segmentation data; optional. + + Notes: + The input directory structure assumed for dataset: + + - im_dir + ├─ 001.jpg + ├─ .. + └─ NNN.jpg + - labels + ├─ 001.txt + ├─ .. + └─ NNN.txt + """ + from tqdm import tqdm + + from ultralytics import SAM + from ultralytics.data import YOLODataset + from ultralytics.utils import LOGGER + from ultralytics.utils.ops import xywh2xyxy + + # NOTE: add placeholder to pass class index check + dataset = YOLODataset(im_dir, data=dict(names=list(range(1000)))) + if len(dataset.labels[0]["segments"]) > 0: # if it's segment data + LOGGER.info("Segmentation labels detected, no need to generate new ones!") + return + + LOGGER.info("Detection labels detected, generating segment labels by SAM model!") + sam_model = SAM(sam_model) + for l in tqdm(dataset.labels, total=len(dataset.labels), desc="Generating segment labels"): + h, w = l["shape"] + boxes = l["bboxes"] + if len(boxes) == 0: # skip empty labels + continue + boxes[:, [0, 2]] *= w + boxes[:, [1, 3]] *= h + im = cv2.imread(l["im_file"]) + sam_results = sam_model(im, bboxes=xywh2xyxy(boxes), verbose=False, save=False) + l["segments"] = sam_results[0].masks.xyn + + save_dir = Path(save_dir) if save_dir else Path(im_dir).parent / "labels-segment" + save_dir.mkdir(parents=True, exist_ok=True) + for l in dataset.labels: + texts = [] + lb_name = Path(l["im_file"]).with_suffix(".txt").name + txt_file = save_dir / lb_name + cls = l["cls"] + for i, s in enumerate(l["segments"]): + line = (int(cls[i]), *s.reshape(-1)) + texts.append(("%g " * len(line)).rstrip() % line) + if texts: + with open(txt_file, "a") as f: + f.writelines(text + "\n" for text in texts) + LOGGER.info(f"Generated segment labels saved in {save_dir}") diff --git a/ultralytics/data/dataset.py b/ultralytics/data/dataset.py new file mode 100644 index 0000000..8bbb08f --- /dev/null +++ b/ultralytics/data/dataset.py @@ -0,0 +1,506 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import contextlib +import json +from collections import defaultdict +from itertools import repeat +from multiprocessing.pool import ThreadPool +from pathlib import Path + +import cv2 +import numpy as np +import torch +from PIL import Image +from torch.utils.data import ConcatDataset + +from ultralytics.utils import LOCAL_RANK, NUM_THREADS, TQDM, colorstr +from ultralytics.utils.ops import resample_segments + +from .augment import ( + Compose, + Format, + Instances, + LetterBox, + RandomLoadText, + classify_augmentations, + classify_transforms, + v8_transforms, +) +from .base import BaseDataset +from .utils import ( + HELP_URL, + LOGGER, + get_hash, + img2label_paths, + load_dataset_cache_file, + save_dataset_cache_file, + verify_image, + verify_image_label, +) + +# Ultralytics dataset *.cache version, >= 1.0.0 for YOLOv8 +DATASET_CACHE_VERSION = "1.0.3" + + +class YOLODataset(BaseDataset): + """ + Dataset class for loading object detection and/or segmentation labels in YOLO format. + + Args: + data (dict, optional): A dataset YAML dictionary. Defaults to None. + task (str): An explicit arg to point current task, Defaults to 'detect'. + + Returns: + (torch.utils.data.Dataset): A PyTorch dataset object that can be used for training an object detection model. + """ + + def __init__(self, *args, data=None, task="detect", **kwargs): + """Initializes the YOLODataset with optional configurations for segments and keypoints.""" + self.use_segments = task == "segment" + self.use_keypoints = task == "pose" + self.use_obb = task == "obb" + self.data = data + assert not (self.use_segments and self.use_keypoints), "Can not use both segments and keypoints." + super().__init__(*args, **kwargs) + + def cache_labels(self, path=Path("./labels.cache")): + """ + Cache dataset labels, check images and read shapes. + + Args: + path (Path): Path where to save the cache file. Default is Path('./labels.cache'). + + Returns: + (dict): labels. + """ + x = {"labels": []} + nm, nf, ne, nc, msgs = 0, 0, 0, 0, [] # number missing, found, empty, corrupt, messages + desc = f"{self.prefix}Scanning {path.parent / path.stem}..." + total = len(self.im_files) + nkpt, ndim = self.data.get("kpt_shape", (0, 0)) + if self.use_keypoints and (nkpt <= 0 or ndim not in {2, 3}): + raise ValueError( + "'kpt_shape' in data.yaml missing or incorrect. Should be a list with [number of " + "keypoints, number of dims (2 for x,y or 3 for x,y,visible)], i.e. 'kpt_shape: [17, 3]'" + ) + with ThreadPool(NUM_THREADS) as pool: + results = pool.imap( + func=verify_image_label, + iterable=zip( + self.im_files, + self.label_files, + repeat(self.prefix), + repeat(self.use_keypoints), + repeat(len(self.data["names"])), + repeat(nkpt), + repeat(ndim), + ), + ) + pbar = TQDM(results, desc=desc, total=total) + for im_file, lb, shape, segments, keypoint, nm_f, nf_f, ne_f, nc_f, msg in pbar: + nm += nm_f + nf += nf_f + ne += ne_f + nc += nc_f + if im_file: + x["labels"].append( + { + "im_file": im_file, + "shape": shape, + "cls": lb[:, 0:1], # n, 1 + "bboxes": lb[:, 1:], # n, 4 + "segments": segments, + "keypoints": keypoint, + "normalized": True, + "bbox_format": "xywh", + } + ) + if msg: + msgs.append(msg) + pbar.desc = f"{desc} {nf} images, {nm + ne} backgrounds, {nc} corrupt" + pbar.close() + + if msgs: + LOGGER.info("\n".join(msgs)) + if nf == 0: + LOGGER.warning(f"{self.prefix}WARNING ⚠️ No labels found in {path}. {HELP_URL}") + x["hash"] = get_hash(self.label_files + self.im_files) + x["results"] = nf, nm, ne, nc, len(self.im_files) + x["msgs"] = msgs # warnings + save_dataset_cache_file(self.prefix, path, x, DATASET_CACHE_VERSION) + return x + + def get_labels(self): + """Returns dictionary of labels for YOLO training.""" + self.label_files = img2label_paths(self.im_files) + cache_path = Path(self.label_files[0]).parent.with_suffix(".cache") + try: + cache, exists = load_dataset_cache_file(cache_path), True # attempt to load a *.cache file + assert cache["version"] == DATASET_CACHE_VERSION # matches current version + assert cache["hash"] == get_hash(self.label_files + self.im_files) # identical hash + except (FileNotFoundError, AssertionError, AttributeError): + cache, exists = self.cache_labels(cache_path), False # run cache ops + + # Display cache + nf, nm, ne, nc, n = cache.pop("results") # found, missing, empty, corrupt, total + if exists and LOCAL_RANK in {-1, 0}: + d = f"Scanning {cache_path}... {nf} images, {nm + ne} backgrounds, {nc} corrupt" + TQDM(None, desc=self.prefix + d, total=n, initial=n) # display results + if cache["msgs"]: + LOGGER.info("\n".join(cache["msgs"])) # display warnings + + # Read cache + [cache.pop(k) for k in ("hash", "version", "msgs")] # remove items + labels = cache["labels"] + if not labels: + LOGGER.warning(f"WARNING ⚠️ No images found in {cache_path}, training may not work correctly. {HELP_URL}") + self.im_files = [lb["im_file"] for lb in labels] # update im_files + + # Check if the dataset is all boxes or all segments + lengths = ((len(lb["cls"]), len(lb["bboxes"]), len(lb["segments"])) for lb in labels) + len_cls, len_boxes, len_segments = (sum(x) for x in zip(*lengths)) + if len_segments and len_boxes != len_segments: + LOGGER.warning( + f"WARNING ⚠️ Box and segment counts should be equal, but got len(segments) = {len_segments}, " + f"len(boxes) = {len_boxes}. To resolve this only boxes will be used and all segments will be removed. " + "To avoid this please supply either a detect or segment dataset, not a detect-segment mixed dataset." + ) + for lb in labels: + lb["segments"] = [] + if len_cls == 0: + LOGGER.warning(f"WARNING ⚠️ No labels found in {cache_path}, training may not work correctly. {HELP_URL}") + return labels + + def build_transforms(self, hyp=None): + """Builds and appends transforms to the list.""" + if self.augment: + hyp.mosaic = hyp.mosaic if self.augment and not self.rect else 0.0 + hyp.mixup = hyp.mixup if self.augment and not self.rect else 0.0 + transforms = v8_transforms(self, self.imgsz, hyp) + else: + transforms = Compose([LetterBox(new_shape=(self.imgsz, self.imgsz), scaleup=False)]) + transforms.append( + Format( + bbox_format="xywh", + normalize=True, + return_mask=self.use_segments, + return_keypoint=self.use_keypoints, + return_obb=self.use_obb, + batch_idx=True, + mask_ratio=hyp.mask_ratio, + mask_overlap=hyp.overlap_mask, + bgr=hyp.bgr if self.augment else 0.0, # only affect training. + ) + ) + return transforms + + def close_mosaic(self, hyp): + """Sets mosaic, copy_paste and mixup options to 0.0 and builds transformations.""" + hyp.mosaic = 0.0 # set mosaic ratio=0.0 + hyp.copy_paste = 0.0 # keep the same behavior as previous v8 close-mosaic + hyp.mixup = 0.0 # keep the same behavior as previous v8 close-mosaic + self.transforms = self.build_transforms(hyp) + + def update_labels_info(self, label): + """ + Custom your label format here. + + Note: + cls is not with bboxes now, classification and semantic segmentation need an independent cls label + Can also support classification and semantic segmentation by adding or removing dict keys there. + """ + bboxes = label.pop("bboxes") + segments = label.pop("segments", []) + keypoints = label.pop("keypoints", None) + bbox_format = label.pop("bbox_format") + normalized = label.pop("normalized") + + # NOTE: do NOT resample oriented boxes + segment_resamples = 100 if self.use_obb else 1000 + if len(segments) > 0: + # list[np.array(1000, 2)] * num_samples + # (N, 1000, 2) + segments = np.stack(resample_segments(segments, n=segment_resamples), axis=0) + else: + segments = np.zeros((0, segment_resamples, 2), dtype=np.float32) + label["instances"] = Instances(bboxes, segments, keypoints, bbox_format=bbox_format, normalized=normalized) + return label + + @staticmethod + def collate_fn(batch): + """Collates data samples into batches.""" + new_batch = {} + keys = batch[0].keys() + values = list(zip(*[list(b.values()) for b in batch])) + for i, k in enumerate(keys): + value = values[i] + if k == "img": + value = torch.stack(value, 0) + if k in {"masks", "keypoints", "bboxes", "cls", "segments", "obb"}: + value = torch.cat(value, 0) + new_batch[k] = value + new_batch["batch_idx"] = list(new_batch["batch_idx"]) + for i in range(len(new_batch["batch_idx"])): + new_batch["batch_idx"][i] += i # add target image index for build_targets() + new_batch["batch_idx"] = torch.cat(new_batch["batch_idx"], 0) + return new_batch + + +class YOLOMultiModalDataset(YOLODataset): + """ + Dataset class for loading object detection and/or segmentation labels in YOLO format. + + Args: + data (dict, optional): A dataset YAML dictionary. Defaults to None. + task (str): An explicit arg to point current task, Defaults to 'detect'. + + Returns: + (torch.utils.data.Dataset): A PyTorch dataset object that can be used for training an object detection model. + """ + + def __init__(self, *args, data=None, task="detect", **kwargs): + """Initializes a dataset object for object detection tasks with optional specifications.""" + super().__init__(*args, data=data, task=task, **kwargs) + + def update_labels_info(self, label): + """Add texts information for multi modal model training.""" + labels = super().update_labels_info(label) + # NOTE: some categories are concatenated with its synonyms by `/`. + labels["texts"] = [v.split("/") for _, v in self.data["names"].items()] + return labels + + def build_transforms(self, hyp=None): + """Enhances data transformations with optional text augmentation for multi-modal training.""" + transforms = super().build_transforms(hyp) + if self.augment: + # NOTE: hard-coded the args for now. + transforms.insert(-1, RandomLoadText(max_samples=min(self.data["nc"], 80), padding=True)) + return transforms + + +class GroundingDataset(YOLODataset): + def __init__(self, *args, task="detect", json_file, **kwargs): + """Initializes a GroundingDataset for object detection, loading annotations from a specified JSON file.""" + assert task == "detect", "`GroundingDataset` only support `detect` task for now!" + self.json_file = json_file + super().__init__(*args, task=task, data={}, **kwargs) + + def get_img_files(self, img_path): + """The image files would be read in `get_labels` function, return empty list here.""" + return [] + + def get_labels(self): + """Loads annotations from a JSON file, filters, and normalizes bounding boxes for each image.""" + labels = [] + LOGGER.info("Loading annotation file...") + with open(self.json_file, "r") as f: + annotations = json.load(f) + images = {f'{x["id"]:d}': x for x in annotations["images"]} + imgToAnns = defaultdict(list) + for ann in annotations["annotations"]: + imgToAnns[ann["image_id"]].append(ann) + for img_id, anns in TQDM(imgToAnns.items(), desc=f"Reading annotations {self.json_file}"): + img = images[f"{img_id:d}"] + h, w, f = img["height"], img["width"], img["file_name"] + im_file = Path(self.img_path) / f + if not im_file.exists(): + continue + self.im_files.append(str(im_file)) + bboxes = [] + cat2id = {} + texts = [] + for ann in anns: + if ann["iscrowd"]: + continue + box = np.array(ann["bbox"], dtype=np.float32) + box[:2] += box[2:] / 2 + box[[0, 2]] /= float(w) + box[[1, 3]] /= float(h) + if box[2] <= 0 or box[3] <= 0: + continue + + cat_name = " ".join([img["caption"][t[0] : t[1]] for t in ann["tokens_positive"]]) + if cat_name not in cat2id: + cat2id[cat_name] = len(cat2id) + texts.append([cat_name]) + cls = cat2id[cat_name] # class + box = [cls] + box.tolist() + if box not in bboxes: + bboxes.append(box) + lb = np.array(bboxes, dtype=np.float32) if len(bboxes) else np.zeros((0, 5), dtype=np.float32) + labels.append( + { + "im_file": im_file, + "shape": (h, w), + "cls": lb[:, 0:1], # n, 1 + "bboxes": lb[:, 1:], # n, 4 + "normalized": True, + "bbox_format": "xywh", + "texts": texts, + } + ) + return labels + + def build_transforms(self, hyp=None): + """Configures augmentations for training with optional text loading; `hyp` adjusts augmentation intensity.""" + transforms = super().build_transforms(hyp) + if self.augment: + # NOTE: hard-coded the args for now. + transforms.insert(-1, RandomLoadText(max_samples=80, padding=True)) + return transforms + + +class YOLOConcatDataset(ConcatDataset): + """ + Dataset as a concatenation of multiple datasets. + + This class is useful to assemble different existing datasets. + """ + + @staticmethod + def collate_fn(batch): + """Collates data samples into batches.""" + return YOLODataset.collate_fn(batch) + + +# TODO: support semantic segmentation +class SemanticDataset(BaseDataset): + """ + Semantic Segmentation Dataset. + + This class is responsible for handling datasets used for semantic segmentation tasks. It inherits functionalities + from the BaseDataset class. + + Note: + This class is currently a placeholder and needs to be populated with methods and attributes for supporting + semantic segmentation tasks. + """ + + def __init__(self): + """Initialize a SemanticDataset object.""" + super().__init__() + + +class ClassificationDataset: + """ + Extends torchvision ImageFolder to support YOLO classification tasks, offering functionalities like image + augmentation, caching, and verification. It's designed to efficiently handle large datasets for training deep + learning models, with optional image transformations and caching mechanisms to speed up training. + + This class allows for augmentations using both torchvision and Albumentations libraries, and supports caching images + in RAM or on disk to reduce IO overhead during training. Additionally, it implements a robust verification process + to ensure data integrity and consistency. + + Attributes: + cache_ram (bool): Indicates if caching in RAM is enabled. + cache_disk (bool): Indicates if caching on disk is enabled. + samples (list): A list of tuples, each containing the path to an image, its class index, path to its .npy cache + file (if caching on disk), and optionally the loaded image array (if caching in RAM). + torch_transforms (callable): PyTorch transforms to be applied to the images. + """ + + def __init__(self, root, args, augment=False, prefix=""): + """ + Initialize YOLO object with root, image size, augmentations, and cache settings. + + Args: + root (str): Path to the dataset directory where images are stored in a class-specific folder structure. + args (Namespace): Configuration containing dataset-related settings such as image size, augmentation + parameters, and cache settings. It includes attributes like `imgsz` (image size), `fraction` (fraction + of data to use), `scale`, `fliplr`, `flipud`, `cache` (disk or RAM caching for faster training), + `auto_augment`, `hsv_h`, `hsv_s`, `hsv_v`, and `crop_fraction`. + augment (bool, optional): Whether to apply augmentations to the dataset. Default is False. + prefix (str, optional): Prefix for logging and cache filenames, aiding in dataset identification and + debugging. Default is an empty string. + """ + import torchvision # scope for faster 'import ultralytics' + + # Base class assigned as attribute rather than used as base class to allow for scoping slow torchvision import + self.base = torchvision.datasets.ImageFolder(root=root) + self.samples = self.base.samples + self.root = self.base.root + + # Initialize attributes + if augment and args.fraction < 1.0: # reduce training fraction + self.samples = self.samples[: round(len(self.samples) * args.fraction)] + self.prefix = colorstr(f"{prefix}: ") if prefix else "" + self.cache_ram = args.cache is True or str(args.cache).lower() == "ram" # cache images into RAM + self.cache_disk = str(args.cache).lower() == "disk" # cache images on hard drive as uncompressed *.npy files + self.samples = self.verify_images() # filter out bad images + self.samples = [list(x) + [Path(x[0]).with_suffix(".npy"), None] for x in self.samples] # file, index, npy, im + scale = (1.0 - args.scale, 1.0) # (0.08, 1.0) + self.torch_transforms = ( + classify_augmentations( + size=args.imgsz, + scale=scale, + hflip=args.fliplr, + vflip=args.flipud, + erasing=args.erasing, + auto_augment=args.auto_augment, + hsv_h=args.hsv_h, + hsv_s=args.hsv_s, + hsv_v=args.hsv_v, + ) + if augment + else classify_transforms(size=args.imgsz, crop_fraction=args.crop_fraction) + ) + + def __getitem__(self, i): + """Returns subset of data and targets corresponding to given indices.""" + f, j, fn, im = self.samples[i] # filename, index, filename.with_suffix('.npy'), image + if self.cache_ram: + if im is None: # Warning: two separate if statements required here, do not combine this with previous line + im = self.samples[i][3] = cv2.imread(f) + elif self.cache_disk: + if not fn.exists(): # load npy + np.save(fn.as_posix(), cv2.imread(f), allow_pickle=False) + im = np.load(fn) + else: # read image + im = cv2.imread(f) # BGR + # Convert NumPy array to PIL image + im = Image.fromarray(cv2.cvtColor(im, cv2.COLOR_BGR2RGB)) + sample = self.torch_transforms(im) + return {"img": sample, "cls": j} + + def __len__(self) -> int: + """Return the total number of samples in the dataset.""" + return len(self.samples) + + def verify_images(self): + """Verify all images in dataset.""" + desc = f"{self.prefix}Scanning {self.root}..." + path = Path(self.root).with_suffix(".cache") # *.cache file path + + with contextlib.suppress(FileNotFoundError, AssertionError, AttributeError): + cache = load_dataset_cache_file(path) # attempt to load a *.cache file + assert cache["version"] == DATASET_CACHE_VERSION # matches current version + assert cache["hash"] == get_hash([x[0] for x in self.samples]) # identical hash + nf, nc, n, samples = cache.pop("results") # found, missing, empty, corrupt, total + if LOCAL_RANK in {-1, 0}: + d = f"{desc} {nf} images, {nc} corrupt" + TQDM(None, desc=d, total=n, initial=n) + if cache["msgs"]: + LOGGER.info("\n".join(cache["msgs"])) # display warnings + return samples + + # Run scan if *.cache retrieval failed + nf, nc, msgs, samples, x = 0, 0, [], [], {} + with ThreadPool(NUM_THREADS) as pool: + results = pool.imap(func=verify_image, iterable=zip(self.samples, repeat(self.prefix))) + pbar = TQDM(results, desc=desc, total=len(self.samples)) + for sample, nf_f, nc_f, msg in pbar: + if nf_f: + samples.append(sample) + if msg: + msgs.append(msg) + nf += nf_f + nc += nc_f + pbar.desc = f"{desc} {nf} images, {nc} corrupt" + pbar.close() + if msgs: + LOGGER.info("\n".join(msgs)) + x["hash"] = get_hash([x[0] for x in self.samples]) + x["results"] = nf, nc, len(samples), samples + x["msgs"] = msgs # warnings + save_dataset_cache_file(self.prefix, path, x, DATASET_CACHE_VERSION) + return samples diff --git a/ultralytics/data/explorer/__init__.py b/ultralytics/data/explorer/__init__.py new file mode 100644 index 0000000..ce594dc --- /dev/null +++ b/ultralytics/data/explorer/__init__.py @@ -0,0 +1,5 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from .utils import plot_query_result + +__all__ = ["plot_query_result"] diff --git a/ultralytics/data/explorer/explorer.py b/ultralytics/data/explorer/explorer.py new file mode 100644 index 0000000..1982ca0 --- /dev/null +++ b/ultralytics/data/explorer/explorer.py @@ -0,0 +1,472 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from io import BytesIO +from pathlib import Path +from typing import Any, List, Tuple, Union + +import cv2 +import numpy as np +import torch +from matplotlib import pyplot as plt +from PIL import Image +from tqdm import tqdm + +from ultralytics.data.augment import Format +from ultralytics.data.dataset import YOLODataset +from ultralytics.data.utils import check_det_dataset +from ultralytics.models.yolo.model import YOLO +from ultralytics.utils import LOGGER, USER_CONFIG_DIR, IterableSimpleNamespace, checks + +from .utils import get_sim_index_schema, get_table_schema, plot_query_result, prompt_sql_query, sanitize_batch + + +class ExplorerDataset(YOLODataset): + def __init__(self, *args, data: dict = None, **kwargs) -> None: + super().__init__(*args, data=data, **kwargs) + + def load_image(self, i: int) -> Union[Tuple[np.ndarray, Tuple[int, int], Tuple[int, int]], Tuple[None, None, None]]: + """Loads 1 image from dataset index 'i' without any resize ops.""" + im, f, fn = self.ims[i], self.im_files[i], self.npy_files[i] + if im is None: # not cached in RAM + if fn.exists(): # load npy + im = np.load(fn) + else: # read image + im = cv2.imread(f) # BGR + if im is None: + raise FileNotFoundError(f"Image Not Found {f}") + h0, w0 = im.shape[:2] # orig hw + return im, (h0, w0), im.shape[:2] + + return self.ims[i], self.im_hw0[i], self.im_hw[i] + + def build_transforms(self, hyp: IterableSimpleNamespace = None): + """Creates transforms for dataset images without resizing.""" + return Format( + bbox_format="xyxy", + normalize=False, + return_mask=self.use_segments, + return_keypoint=self.use_keypoints, + batch_idx=True, + mask_ratio=hyp.mask_ratio, + mask_overlap=hyp.overlap_mask, + ) + + +class Explorer: + def __init__( + self, + data: Union[str, Path] = "coco128.yaml", + model: str = "yolov8n.pt", + uri: str = USER_CONFIG_DIR / "explorer", + ) -> None: + # Note duckdb==0.10.0 bug https://github.com/ultralytics/ultralytics/pull/8181 + checks.check_requirements(["lancedb>=0.4.3", "duckdb<=0.9.2"]) + import lancedb + + self.connection = lancedb.connect(uri) + self.table_name = Path(data).name.lower() + "_" + model.lower() + self.sim_idx_base_name = ( + f"{self.table_name}_sim_idx".lower() + ) # Use this name and append thres and top_k to reuse the table + self.model = YOLO(model) + self.data = data # None + self.choice_set = None + + self.table = None + self.progress = 0 + + def create_embeddings_table(self, force: bool = False, split: str = "train") -> None: + """ + Create LanceDB table containing the embeddings of the images in the dataset. The table will be reused if it + already exists. Pass force=True to overwrite the existing table. + + Args: + force (bool): Whether to overwrite the existing table or not. Defaults to False. + split (str): Split of the dataset to use. Defaults to 'train'. + + Example: + ```python + exp = Explorer() + exp.create_embeddings_table() + ``` + """ + if self.table is not None and not force: + LOGGER.info("Table already exists. Reusing it. Pass force=True to overwrite it.") + return + if self.table_name in self.connection.table_names() and not force: + LOGGER.info(f"Table {self.table_name} already exists. Reusing it. Pass force=True to overwrite it.") + self.table = self.connection.open_table(self.table_name) + self.progress = 1 + return + if self.data is None: + raise ValueError("Data must be provided to create embeddings table") + + data_info = check_det_dataset(self.data) + if split not in data_info: + raise ValueError( + f"Split {split} is not found in the dataset. Available keys in the dataset are {list(data_info.keys())}" + ) + + choice_set = data_info[split] + choice_set = choice_set if isinstance(choice_set, list) else [choice_set] + self.choice_set = choice_set + dataset = ExplorerDataset(img_path=choice_set, data=data_info, augment=False, cache=False, task=self.model.task) + + # Create the table schema + batch = dataset[0] + vector_size = self.model.embed(batch["im_file"], verbose=False)[0].shape[0] + table = self.connection.create_table(self.table_name, schema=get_table_schema(vector_size), mode="overwrite") + table.add( + self._yield_batches( + dataset, + data_info, + self.model, + exclude_keys=["img", "ratio_pad", "resized_shape", "ori_shape", "batch_idx"], + ) + ) + + self.table = table + + def _yield_batches(self, dataset: ExplorerDataset, data_info: dict, model: YOLO, exclude_keys: List[str]): + """Generates batches of data for embedding, excluding specified keys.""" + for i in tqdm(range(len(dataset))): + self.progress = float(i + 1) / len(dataset) + batch = dataset[i] + for k in exclude_keys: + batch.pop(k, None) + batch = sanitize_batch(batch, data_info) + batch["vector"] = model.embed(batch["im_file"], verbose=False)[0].detach().tolist() + yield [batch] + + def query( + self, imgs: Union[str, np.ndarray, List[str], List[np.ndarray]] = None, limit: int = 25 + ) -> Any: # pyarrow.Table + """ + Query the table for similar images. Accepts a single image or a list of images. + + Args: + imgs (str or list): Path to the image or a list of paths to the images. + limit (int): Number of results to return. + + Returns: + (pyarrow.Table): An arrow table containing the results. Supports converting to: + - pandas dataframe: `result.to_pandas()` + - dict of lists: `result.to_pydict()` + + Example: + ```python + exp = Explorer() + exp.create_embeddings_table() + similar = exp.query(img='https://ultralytics.com/images/zidane.jpg') + ``` + """ + if self.table is None: + raise ValueError("Table is not created. Please create the table first.") + if isinstance(imgs, str): + imgs = [imgs] + assert isinstance(imgs, list), f"img must be a string or a list of strings. Got {type(imgs)}" + embeds = self.model.embed(imgs) + # Get avg if multiple images are passed (len > 1) + embeds = torch.mean(torch.stack(embeds), 0).cpu().numpy() if len(embeds) > 1 else embeds[0].cpu().numpy() + return self.table.search(embeds).limit(limit).to_arrow() + + def sql_query( + self, query: str, return_type: str = "pandas" + ) -> Union[Any, None]: # pandas.DataFrame or pyarrow.Table + """ + Run a SQL-Like query on the table. Utilizes LanceDB predicate pushdown. + + Args: + query (str): SQL query to run. + return_type (str): Type of the result to return. Can be either 'pandas' or 'arrow'. Defaults to 'pandas'. + + Returns: + (pyarrow.Table): An arrow table containing the results. + + Example: + ```python + exp = Explorer() + exp.create_embeddings_table() + query = "SELECT * FROM 'table' WHERE labels LIKE '%person%'" + result = exp.sql_query(query) + ``` + """ + assert return_type in { + "pandas", + "arrow", + }, f"Return type should be either `pandas` or `arrow`, but got {return_type}" + import duckdb + + if self.table is None: + raise ValueError("Table is not created. Please create the table first.") + + # Note: using filter pushdown would be a better long term solution. Temporarily using duckdb for this. + table = self.table.to_arrow() # noqa NOTE: Don't comment this. This line is used by DuckDB + if not query.startswith("SELECT") and not query.startswith("WHERE"): + raise ValueError( + f"Query must start with SELECT or WHERE. You can either pass the entire query or just the WHERE " + f"clause. found {query}" + ) + if query.startswith("WHERE"): + query = f"SELECT * FROM 'table' {query}" + LOGGER.info(f"Running query: {query}") + + rs = duckdb.sql(query) + if return_type == "arrow": + return rs.arrow() + elif return_type == "pandas": + return rs.df() + + def plot_sql_query(self, query: str, labels: bool = True) -> Image.Image: + """ + Plot the results of a SQL-Like query on the table. + Args: + query (str): SQL query to run. + labels (bool): Whether to plot the labels or not. + + Returns: + (PIL.Image): Image containing the plot. + + Example: + ```python + exp = Explorer() + exp.create_embeddings_table() + query = "SELECT * FROM 'table' WHERE labels LIKE '%person%'" + result = exp.plot_sql_query(query) + ``` + """ + result = self.sql_query(query, return_type="arrow") + if len(result) == 0: + LOGGER.info("No results found.") + return None + img = plot_query_result(result, plot_labels=labels) + return Image.fromarray(img) + + def get_similar( + self, + img: Union[str, np.ndarray, List[str], List[np.ndarray]] = None, + idx: Union[int, List[int]] = None, + limit: int = 25, + return_type: str = "pandas", + ) -> Any: # pandas.DataFrame or pyarrow.Table + """ + Query the table for similar images. Accepts a single image or a list of images. + + Args: + img (str or list): Path to the image or a list of paths to the images. + idx (int or list): Index of the image in the table or a list of indexes. + limit (int): Number of results to return. Defaults to 25. + return_type (str): Type of the result to return. Can be either 'pandas' or 'arrow'. Defaults to 'pandas'. + + Returns: + (pandas.DataFrame): A dataframe containing the results. + + Example: + ```python + exp = Explorer() + exp.create_embeddings_table() + similar = exp.get_similar(img='https://ultralytics.com/images/zidane.jpg') + ``` + """ + assert return_type in { + "pandas", + "arrow", + }, f"Return type should be either `pandas` or `arrow`, but got {return_type}" + img = self._check_imgs_or_idxs(img, idx) + similar = self.query(img, limit=limit) + + if return_type == "arrow": + return similar + elif return_type == "pandas": + return similar.to_pandas() + + def plot_similar( + self, + img: Union[str, np.ndarray, List[str], List[np.ndarray]] = None, + idx: Union[int, List[int]] = None, + limit: int = 25, + labels: bool = True, + ) -> Image.Image: + """ + Plot the similar images. Accepts images or indexes. + + Args: + img (str or list): Path to the image or a list of paths to the images. + idx (int or list): Index of the image in the table or a list of indexes. + labels (bool): Whether to plot the labels or not. + limit (int): Number of results to return. Defaults to 25. + + Returns: + (PIL.Image): Image containing the plot. + + Example: + ```python + exp = Explorer() + exp.create_embeddings_table() + similar = exp.plot_similar(img='https://ultralytics.com/images/zidane.jpg') + ``` + """ + similar = self.get_similar(img, idx, limit, return_type="arrow") + if len(similar) == 0: + LOGGER.info("No results found.") + return None + img = plot_query_result(similar, plot_labels=labels) + return Image.fromarray(img) + + def similarity_index(self, max_dist: float = 0.2, top_k: float = None, force: bool = False) -> Any: # pd.DataFrame + """ + Calculate the similarity index of all the images in the table. Here, the index will contain the data points that + are max_dist or closer to the image in the embedding space at a given index. + + Args: + max_dist (float): maximum L2 distance between the embeddings to consider. Defaults to 0.2. + top_k (float): Percentage of the closest data points to consider when counting. Used to apply limit. + vector search. Defaults: None. + force (bool): Whether to overwrite the existing similarity index or not. Defaults to True. + + Returns: + (pandas.DataFrame): A dataframe containing the similarity index. Each row corresponds to an image, + and columns include indices of similar images and their respective distances. + + Example: + ```python + exp = Explorer() + exp.create_embeddings_table() + sim_idx = exp.similarity_index() + ``` + """ + if self.table is None: + raise ValueError("Table is not created. Please create the table first.") + sim_idx_table_name = f"{self.sim_idx_base_name}_thres_{max_dist}_top_{top_k}".lower() + if sim_idx_table_name in self.connection.table_names() and not force: + LOGGER.info("Similarity matrix already exists. Reusing it. Pass force=True to overwrite it.") + return self.connection.open_table(sim_idx_table_name).to_pandas() + + if top_k and not (1.0 >= top_k >= 0.0): + raise ValueError(f"top_k must be between 0.0 and 1.0. Got {top_k}") + if max_dist < 0.0: + raise ValueError(f"max_dist must be greater than 0. Got {max_dist}") + + top_k = int(top_k * len(self.table)) if top_k else len(self.table) + top_k = max(top_k, 1) + features = self.table.to_lance().to_table(columns=["vector", "im_file"]).to_pydict() + im_files = features["im_file"] + embeddings = features["vector"] + + sim_table = self.connection.create_table(sim_idx_table_name, schema=get_sim_index_schema(), mode="overwrite") + + def _yield_sim_idx(): + """Generates a dataframe with similarity indices and distances for images.""" + for i in tqdm(range(len(embeddings))): + sim_idx = self.table.search(embeddings[i]).limit(top_k).to_pandas().query(f"_distance <= {max_dist}") + yield [ + { + "idx": i, + "im_file": im_files[i], + "count": len(sim_idx), + "sim_im_files": sim_idx["im_file"].tolist(), + } + ] + + sim_table.add(_yield_sim_idx()) + self.sim_index = sim_table + return sim_table.to_pandas() + + def plot_similarity_index(self, max_dist: float = 0.2, top_k: float = None, force: bool = False) -> Image: + """ + Plot the similarity index of all the images in the table. Here, the index will contain the data points that are + max_dist or closer to the image in the embedding space at a given index. + + Args: + max_dist (float): maximum L2 distance between the embeddings to consider. Defaults to 0.2. + top_k (float): Percentage of closest data points to consider when counting. Used to apply limit when + running vector search. Defaults to 0.01. + force (bool): Whether to overwrite the existing similarity index or not. Defaults to True. + + Returns: + (PIL.Image): Image containing the plot. + + Example: + ```python + exp = Explorer() + exp.create_embeddings_table() + + similarity_idx_plot = exp.plot_similarity_index() + similarity_idx_plot.show() # view image preview + similarity_idx_plot.save('path/to/save/similarity_index_plot.png') # save contents to file + ``` + """ + sim_idx = self.similarity_index(max_dist=max_dist, top_k=top_k, force=force) + sim_count = sim_idx["count"].tolist() + sim_count = np.array(sim_count) + + indices = np.arange(len(sim_count)) + + # Create the bar plot + plt.bar(indices, sim_count) + + # Customize the plot (optional) + plt.xlabel("data idx") + plt.ylabel("Count") + plt.title("Similarity Count") + buffer = BytesIO() + plt.savefig(buffer, format="png") + buffer.seek(0) + + # Use Pillow to open the image from the buffer + return Image.fromarray(np.array(Image.open(buffer))) + + def _check_imgs_or_idxs( + self, img: Union[str, np.ndarray, List[str], List[np.ndarray], None], idx: Union[None, int, List[int]] + ) -> List[np.ndarray]: + if img is None and idx is None: + raise ValueError("Either img or idx must be provided.") + if img is not None and idx is not None: + raise ValueError("Only one of img or idx must be provided.") + if idx is not None: + idx = idx if isinstance(idx, list) else [idx] + img = self.table.to_lance().take(idx, columns=["im_file"]).to_pydict()["im_file"] + + return img if isinstance(img, list) else [img] + + def ask_ai(self, query): + """ + Ask AI a question. + + Args: + query (str): Question to ask. + + Returns: + (pandas.DataFrame): A dataframe containing filtered results to the SQL query. + + Example: + ```python + exp = Explorer() + exp.create_embeddings_table() + answer = exp.ask_ai('Show images with 1 person and 2 dogs') + ``` + """ + result = prompt_sql_query(query) + try: + return self.sql_query(result) + except Exception as e: + LOGGER.error("AI generated query is not valid. Please try again with a different prompt") + LOGGER.error(e) + return None + + def visualize(self, result): + """ + Visualize the results of a query. TODO. + + Args: + result (pyarrow.Table): Table containing the results of a query. + """ + pass + + def generate_report(self, result): + """ + Generate a report of the dataset. + + TODO + """ + pass diff --git a/ultralytics/data/explorer/gui/__init__.py b/ultralytics/data/explorer/gui/__init__.py new file mode 100644 index 0000000..9e68dc1 --- /dev/null +++ b/ultralytics/data/explorer/gui/__init__.py @@ -0,0 +1 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license diff --git a/ultralytics/data/explorer/gui/dash.py b/ultralytics/data/explorer/gui/dash.py new file mode 100644 index 0000000..a53144d --- /dev/null +++ b/ultralytics/data/explorer/gui/dash.py @@ -0,0 +1,268 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import time +from threading import Thread + +from ultralytics import Explorer +from ultralytics.utils import ROOT, SETTINGS +from ultralytics.utils.checks import check_requirements + +check_requirements(("streamlit>=1.29.0", "streamlit-select>=0.3")) + +import streamlit as st +from streamlit_select import image_select + + +def _get_explorer(): + """Initializes and returns an instance of the Explorer class.""" + exp = Explorer(data=st.session_state.get("dataset"), model=st.session_state.get("model")) + thread = Thread( + target=exp.create_embeddings_table, kwargs={"force": st.session_state.get("force_recreate_embeddings")} + ) + thread.start() + progress_bar = st.progress(0, text="Creating embeddings table...") + while exp.progress < 1: + time.sleep(0.1) + progress_bar.progress(exp.progress, text=f"Progress: {exp.progress * 100}%") + thread.join() + st.session_state["explorer"] = exp + progress_bar.empty() + + +def init_explorer_form(): + """Initializes an Explorer instance and creates embeddings table with progress tracking.""" + datasets = ROOT / "cfg" / "datasets" + ds = [d.name for d in datasets.glob("*.yaml")] + models = [ + "yolov8n.pt", + "yolov8s.pt", + "yolov8m.pt", + "yolov8l.pt", + "yolov8x.pt", + "yolov8n-seg.pt", + "yolov8s-seg.pt", + "yolov8m-seg.pt", + "yolov8l-seg.pt", + "yolov8x-seg.pt", + "yolov8n-pose.pt", + "yolov8s-pose.pt", + "yolov8m-pose.pt", + "yolov8l-pose.pt", + "yolov8x-pose.pt", + ] + with st.form(key="explorer_init_form"): + col1, col2 = st.columns(2) + with col1: + st.selectbox("Select dataset", ds, key="dataset", index=ds.index("coco128.yaml")) + with col2: + st.selectbox("Select model", models, key="model") + st.checkbox("Force recreate embeddings", key="force_recreate_embeddings") + + st.form_submit_button("Explore", on_click=_get_explorer) + + +def query_form(): + """Sets up a form in Streamlit to initialize Explorer with dataset and model selection.""" + with st.form("query_form"): + col1, col2 = st.columns([0.8, 0.2]) + with col1: + st.text_input( + "Query", + "WHERE labels LIKE '%person%' AND labels LIKE '%dog%'", + label_visibility="collapsed", + key="query", + ) + with col2: + st.form_submit_button("Query", on_click=run_sql_query) + + +def ai_query_form(): + """Sets up a Streamlit form for user input to initialize Explorer with dataset and model selection.""" + with st.form("ai_query_form"): + col1, col2 = st.columns([0.8, 0.2]) + with col1: + st.text_input("Query", "Show images with 1 person and 1 dog", label_visibility="collapsed", key="ai_query") + with col2: + st.form_submit_button("Ask AI", on_click=run_ai_query) + + +def find_similar_imgs(imgs): + """Initializes a Streamlit form for AI-based image querying with custom input.""" + exp = st.session_state["explorer"] + similar = exp.get_similar(img=imgs, limit=st.session_state.get("limit"), return_type="arrow") + paths = similar.to_pydict()["im_file"] + st.session_state["imgs"] = paths + st.session_state["res"] = similar + + +def similarity_form(selected_imgs): + """Initializes a form for AI-based image querying with custom input in Streamlit.""" + st.write("Similarity Search") + with st.form("similarity_form"): + subcol1, subcol2 = st.columns([1, 1]) + with subcol1: + st.number_input( + "limit", min_value=None, max_value=None, value=25, label_visibility="collapsed", key="limit" + ) + + with subcol2: + disabled = not len(selected_imgs) + st.write("Selected: ", len(selected_imgs)) + st.form_submit_button( + "Search", + disabled=disabled, + on_click=find_similar_imgs, + args=(selected_imgs,), + ) + if disabled: + st.error("Select at least one image to search.") + + +# def persist_reset_form(): +# with st.form("persist_reset"): +# col1, col2 = st.columns([1, 1]) +# with col1: +# st.form_submit_button("Reset", on_click=reset) +# +# with col2: +# st.form_submit_button("Persist", on_click=update_state, args=("PERSISTING", True)) + + +def run_sql_query(): + """Executes an SQL query and returns the results.""" + st.session_state["error"] = None + query = st.session_state.get("query") + if query.rstrip().lstrip(): + exp = st.session_state["explorer"] + res = exp.sql_query(query, return_type="arrow") + st.session_state["imgs"] = res.to_pydict()["im_file"] + st.session_state["res"] = res + + +def run_ai_query(): + """Execute SQL query and update session state with query results.""" + if not SETTINGS["openai_api_key"]: + st.session_state["error"] = ( + 'OpenAI API key not found in settings. Please run yolo settings openai_api_key="..."' + ) + return + import pandas # scope for faster 'import ultralytics' + + st.session_state["error"] = None + query = st.session_state.get("ai_query") + if query.rstrip().lstrip(): + exp = st.session_state["explorer"] + res = exp.ask_ai(query) + if not isinstance(res, pandas.DataFrame) or res.empty: + st.session_state["error"] = "No results found using AI generated query. Try another query or rerun it." + return + st.session_state["imgs"] = res["im_file"].to_list() + st.session_state["res"] = res + + +def reset_explorer(): + """Resets the explorer to its initial state by clearing session variables.""" + st.session_state["explorer"] = None + st.session_state["imgs"] = None + st.session_state["error"] = None + + +def utralytics_explorer_docs_callback(): + """Resets the explorer to its initial state by clearing session variables.""" + with st.container(border=True): + st.image( + "https://raw.githubusercontent.com/ultralytics/assets/main/logo/Ultralytics_Logotype_Original.svg", + width=100, + ) + st.markdown( + "

This demo is built using Ultralytics Explorer API. Visit API docs to try examples & learn more

", + unsafe_allow_html=True, + help=None, + ) + st.link_button("Ultrlaytics Explorer API", "https://docs.ultralytics.com/datasets/explorer/") + + +def layout(): + """Resets explorer session variables and provides documentation with a link to API docs.""" + st.set_page_config(layout="wide", initial_sidebar_state="collapsed") + st.markdown("

Ultralytics Explorer Demo

", unsafe_allow_html=True) + + if st.session_state.get("explorer") is None: + init_explorer_form() + return + + st.button(":arrow_backward: Select Dataset", on_click=reset_explorer) + exp = st.session_state.get("explorer") + col1, col2 = st.columns([0.75, 0.25], gap="small") + imgs = [] + if st.session_state.get("error"): + st.error(st.session_state["error"]) + else: + if st.session_state.get("imgs"): + imgs = st.session_state.get("imgs") + else: + imgs = exp.table.to_lance().to_table(columns=["im_file"]).to_pydict()["im_file"] + st.session_state["res"] = exp.table.to_arrow() + total_imgs, selected_imgs = len(imgs), [] + with col1: + subcol1, subcol2, subcol3, subcol4, subcol5 = st.columns(5) + with subcol1: + st.write("Max Images Displayed:") + with subcol2: + num = st.number_input( + "Max Images Displayed", + min_value=0, + max_value=total_imgs, + value=min(500, total_imgs), + key="num_imgs_displayed", + label_visibility="collapsed", + ) + with subcol3: + st.write("Start Index:") + with subcol4: + start_idx = st.number_input( + "Start Index", + min_value=0, + max_value=total_imgs, + value=0, + key="start_index", + label_visibility="collapsed", + ) + with subcol5: + reset = st.button("Reset", use_container_width=False, key="reset") + if reset: + st.session_state["imgs"] = None + st.experimental_rerun() + + query_form() + ai_query_form() + if total_imgs: + labels, boxes, masks, kpts, classes = None, None, None, None, None + task = exp.model.task + if st.session_state.get("display_labels"): + labels = st.session_state.get("res").to_pydict()["labels"][start_idx : start_idx + num] + boxes = st.session_state.get("res").to_pydict()["bboxes"][start_idx : start_idx + num] + masks = st.session_state.get("res").to_pydict()["masks"][start_idx : start_idx + num] + kpts = st.session_state.get("res").to_pydict()["keypoints"][start_idx : start_idx + num] + classes = st.session_state.get("res").to_pydict()["cls"][start_idx : start_idx + num] + imgs_displayed = imgs[start_idx : start_idx + num] + selected_imgs = image_select( + f"Total samples: {total_imgs}", + images=imgs_displayed, + use_container_width=False, + # indices=[i for i in range(num)] if select_all else None, + labels=labels, + classes=classes, + bboxes=boxes, + masks=masks if task == "segment" else None, + kpts=kpts if task == "pose" else None, + ) + + with col2: + similarity_form(selected_imgs) + display_labels = st.checkbox("Labels", value=False, key="display_labels") + utralytics_explorer_docs_callback() + + +if __name__ == "__main__": + layout() diff --git a/ultralytics/data/explorer/utils.py b/ultralytics/data/explorer/utils.py new file mode 100644 index 0000000..76f2557 --- /dev/null +++ b/ultralytics/data/explorer/utils.py @@ -0,0 +1,167 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import getpass +from typing import List + +import cv2 +import numpy as np + +from ultralytics.data.augment import LetterBox +from ultralytics.utils import LOGGER as logger +from ultralytics.utils import SETTINGS +from ultralytics.utils.checks import check_requirements +from ultralytics.utils.ops import xyxy2xywh +from ultralytics.utils.plotting import plot_images + + +def get_table_schema(vector_size): + """Extracts and returns the schema of a database table.""" + from lancedb.pydantic import LanceModel, Vector + + class Schema(LanceModel): + im_file: str + labels: List[str] + cls: List[int] + bboxes: List[List[float]] + masks: List[List[List[int]]] + keypoints: List[List[List[float]]] + vector: Vector(vector_size) + + return Schema + + +def get_sim_index_schema(): + """Returns a LanceModel schema for a database table with specified vector size.""" + from lancedb.pydantic import LanceModel + + class Schema(LanceModel): + idx: int + im_file: str + count: int + sim_im_files: List[str] + + return Schema + + +def sanitize_batch(batch, dataset_info): + """Sanitizes input batch for inference, ensuring correct format and dimensions.""" + batch["cls"] = batch["cls"].flatten().int().tolist() + box_cls_pair = sorted(zip(batch["bboxes"].tolist(), batch["cls"]), key=lambda x: x[1]) + batch["bboxes"] = [box for box, _ in box_cls_pair] + batch["cls"] = [cls for _, cls in box_cls_pair] + batch["labels"] = [dataset_info["names"][i] for i in batch["cls"]] + batch["masks"] = batch["masks"].tolist() if "masks" in batch else [[[]]] + batch["keypoints"] = batch["keypoints"].tolist() if "keypoints" in batch else [[[]]] + return batch + + +def plot_query_result(similar_set, plot_labels=True): + """ + Plot images from the similar set. + + Args: + similar_set (list): Pyarrow or pandas object containing the similar data points + plot_labels (bool): Whether to plot labels or not + """ + import pandas # scope for faster 'import ultralytics' + + similar_set = ( + similar_set.to_dict(orient="list") if isinstance(similar_set, pandas.DataFrame) else similar_set.to_pydict() + ) + empty_masks = [[[]]] + empty_boxes = [[]] + images = similar_set.get("im_file", []) + bboxes = similar_set.get("bboxes", []) if similar_set.get("bboxes") is not empty_boxes else [] + masks = similar_set.get("masks") if similar_set.get("masks")[0] != empty_masks else [] + kpts = similar_set.get("keypoints") if similar_set.get("keypoints")[0] != empty_masks else [] + cls = similar_set.get("cls", []) + + plot_size = 640 + imgs, batch_idx, plot_boxes, plot_masks, plot_kpts = [], [], [], [], [] + for i, imf in enumerate(images): + im = cv2.imread(imf) + im = cv2.cvtColor(im, cv2.COLOR_BGR2RGB) + h, w = im.shape[:2] + r = min(plot_size / h, plot_size / w) + imgs.append(LetterBox(plot_size, center=False)(image=im).transpose(2, 0, 1)) + if plot_labels: + if len(bboxes) > i and len(bboxes[i]) > 0: + box = np.array(bboxes[i], dtype=np.float32) + box[:, [0, 2]] *= r + box[:, [1, 3]] *= r + plot_boxes.append(box) + if len(masks) > i and len(masks[i]) > 0: + mask = np.array(masks[i], dtype=np.uint8)[0] + plot_masks.append(LetterBox(plot_size, center=False)(image=mask)) + if len(kpts) > i and kpts[i] is not None: + kpt = np.array(kpts[i], dtype=np.float32) + kpt[:, :, :2] *= r + plot_kpts.append(kpt) + batch_idx.append(np.ones(len(np.array(bboxes[i], dtype=np.float32))) * i) + imgs = np.stack(imgs, axis=0) + masks = np.stack(plot_masks, axis=0) if plot_masks else np.zeros(0, dtype=np.uint8) + kpts = np.concatenate(plot_kpts, axis=0) if plot_kpts else np.zeros((0, 51), dtype=np.float32) + boxes = xyxy2xywh(np.concatenate(plot_boxes, axis=0)) if plot_boxes else np.zeros(0, dtype=np.float32) + batch_idx = np.concatenate(batch_idx, axis=0) + cls = np.concatenate([np.array(c, dtype=np.int32) for c in cls], axis=0) + + return plot_images( + imgs, batch_idx, cls, bboxes=boxes, masks=masks, kpts=kpts, max_subplots=len(images), save=False, threaded=False + ) + + +def prompt_sql_query(query): + """Plots images with optional labels from a similar data set.""" + check_requirements("openai>=1.6.1") + from openai import OpenAI + + if not SETTINGS["openai_api_key"]: + logger.warning("OpenAI API key not found in settings. Please enter your API key below.") + openai_api_key = getpass.getpass("OpenAI API key: ") + SETTINGS.update({"openai_api_key": openai_api_key}) + openai = OpenAI(api_key=SETTINGS["openai_api_key"]) + + messages = [ + { + "role": "system", + "content": """ + You are a helpful data scientist proficient in SQL. You need to output exactly one SQL query based on + the following schema and a user request. You only need to output the format with fixed selection + statement that selects everything from "'table'", like `SELECT * from 'table'` + + Schema: + im_file: string not null + labels: list not null + child 0, item: string + cls: list not null + child 0, item: int64 + bboxes: list> not null + child 0, item: list + child 0, item: double + masks: list>> not null + child 0, item: list> + child 0, item: list + child 0, item: int64 + keypoints: list>> not null + child 0, item: list> + child 0, item: list + child 0, item: double + vector: fixed_size_list[256] not null + child 0, item: float + + Some details about the schema: + - the "labels" column contains the string values like 'person' and 'dog' for the respective objects + in each image + - the "cls" column contains the integer values on these classes that map them the labels + + Example of a correct query: + request - Get all data points that contain 2 or more people and at least one dog + correct query- + SELECT * FROM 'table' WHERE ARRAY_LENGTH(cls) >= 2 AND ARRAY_LENGTH(FILTER(labels, x -> x = 'person')) >= 2 AND ARRAY_LENGTH(FILTER(labels, x -> x = 'dog')) >= 1; + """, + }, + {"role": "user", "content": f"{query}"}, + ] + + response = openai.chat.completions.create(model="gpt-3.5-turbo", messages=messages) + return response.choices[0].message.content diff --git a/ultralytics/data/loaders.py b/ultralytics/data/loaders.py new file mode 100644 index 0000000..587ab1f --- /dev/null +++ b/ultralytics/data/loaders.py @@ -0,0 +1,558 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import glob +import math +import os +import time +from dataclasses import dataclass +from pathlib import Path +from threading import Thread +from urllib.parse import urlparse + +import cv2 +import numpy as np +import requests +import torch +from PIL import Image + +from ultralytics.data.utils import FORMATS_HELP_MSG, IMG_FORMATS, VID_FORMATS +from ultralytics.utils import IS_COLAB, IS_KAGGLE, LOGGER, ops +from ultralytics.utils.checks import check_requirements + + +@dataclass +class SourceTypes: + """Class to represent various types of input sources for predictions.""" + + stream: bool = False + screenshot: bool = False + from_img: bool = False + tensor: bool = False + + +class LoadStreams: + """ + Stream Loader for various types of video streams, Supports RTSP, RTMP, HTTP, and TCP streams. + + Attributes: + sources (str): The source input paths or URLs for the video streams. + vid_stride (int): Video frame-rate stride, defaults to 1. + buffer (bool): Whether to buffer input streams, defaults to False. + running (bool): Flag to indicate if the streaming thread is running. + mode (str): Set to 'stream' indicating real-time capture. + imgs (list): List of image frames for each stream. + fps (list): List of FPS for each stream. + frames (list): List of total frames for each stream. + threads (list): List of threads for each stream. + shape (list): List of shapes for each stream. + caps (list): List of cv2.VideoCapture objects for each stream. + bs (int): Batch size for processing. + + Methods: + __init__: Initialize the stream loader. + update: Read stream frames in daemon thread. + close: Close stream loader and release resources. + __iter__: Returns an iterator object for the class. + __next__: Returns source paths, transformed, and original images for processing. + __len__: Return the length of the sources object. + + Example: + ```bash + yolo predict source='rtsp://example.com/media.mp4' + ``` + """ + + def __init__(self, sources="file.streams", vid_stride=1, buffer=False): + """Initialize instance variables and check for consistent input stream shapes.""" + torch.backends.cudnn.benchmark = True # faster for fixed-size inference + self.buffer = buffer # buffer input streams + self.running = True # running flag for Thread + self.mode = "stream" + self.vid_stride = vid_stride # video frame-rate stride + + sources = Path(sources).read_text().rsplit() if os.path.isfile(sources) else [sources] + n = len(sources) + self.bs = n + self.fps = [0] * n # frames per second + self.frames = [0] * n + self.threads = [None] * n + self.caps = [None] * n # video capture objects + self.imgs = [[] for _ in range(n)] # images + self.shape = [[] for _ in range(n)] # image shapes + self.sources = [ops.clean_str(x) for x in sources] # clean source names for later + for i, s in enumerate(sources): # index, source + # Start thread to read frames from video stream + st = f"{i + 1}/{n}: {s}... " + if urlparse(s).hostname in {"www.youtube.com", "youtube.com", "youtu.be"}: # if source is YouTube video + # YouTube format i.e. 'https://www.youtube.com/watch?v=Zgi9g1ksQHc' or 'https://youtu.be/LNwODJXcvt4' + s = get_best_youtube_url(s) + s = eval(s) if s.isnumeric() else s # i.e. s = '0' local webcam + if s == 0 and (IS_COLAB or IS_KAGGLE): + raise NotImplementedError( + "'source=0' webcam not supported in Colab and Kaggle notebooks. " + "Try running 'source=0' in a local environment." + ) + self.caps[i] = cv2.VideoCapture(s) # store video capture object + if not self.caps[i].isOpened(): + raise ConnectionError(f"{st}Failed to open {s}") + w = int(self.caps[i].get(cv2.CAP_PROP_FRAME_WIDTH)) + h = int(self.caps[i].get(cv2.CAP_PROP_FRAME_HEIGHT)) + fps = self.caps[i].get(cv2.CAP_PROP_FPS) # warning: may return 0 or nan + self.frames[i] = max(int(self.caps[i].get(cv2.CAP_PROP_FRAME_COUNT)), 0) or float( + "inf" + ) # infinite stream fallback + self.fps[i] = max((fps if math.isfinite(fps) else 0) % 100, 0) or 30 # 30 FPS fallback + + success, im = self.caps[i].read() # guarantee first frame + if not success or im is None: + raise ConnectionError(f"{st}Failed to read images from {s}") + self.imgs[i].append(im) + self.shape[i] = im.shape + self.threads[i] = Thread(target=self.update, args=([i, self.caps[i], s]), daemon=True) + LOGGER.info(f"{st}Success ✅ ({self.frames[i]} frames of shape {w}x{h} at {self.fps[i]:.2f} FPS)") + self.threads[i].start() + LOGGER.info("") # newline + + def update(self, i, cap, stream): + """Read stream `i` frames in daemon thread.""" + n, f = 0, self.frames[i] # frame number, frame array + while self.running and cap.isOpened() and n < (f - 1): + if len(self.imgs[i]) < 30: # keep a <=30-image buffer + n += 1 + cap.grab() # .read() = .grab() followed by .retrieve() + if n % self.vid_stride == 0: + success, im = cap.retrieve() + if not success: + im = np.zeros(self.shape[i], dtype=np.uint8) + LOGGER.warning("WARNING ⚠️ Video stream unresponsive, please check your IP camera connection.") + cap.open(stream) # re-open stream if signal was lost + if self.buffer: + self.imgs[i].append(im) + else: + self.imgs[i] = [im] + else: + time.sleep(0.01) # wait until the buffer is empty + + def close(self): + """Close stream loader and release resources.""" + self.running = False # stop flag for Thread + for thread in self.threads: + if thread.is_alive(): + thread.join(timeout=5) # Add timeout + for cap in self.caps: # Iterate through the stored VideoCapture objects + try: + cap.release() # release video capture + except Exception as e: + LOGGER.warning(f"WARNING ⚠️ Could not release VideoCapture object: {e}") + cv2.destroyAllWindows() + + def __iter__(self): + """Iterates through YOLO image feed and re-opens unresponsive streams.""" + self.count = -1 + return self + + def __next__(self): + """Returns source paths, transformed and original images for processing.""" + self.count += 1 + + images = [] + for i, x in enumerate(self.imgs): + # Wait until a frame is available in each buffer + while not x: + if not self.threads[i].is_alive() or cv2.waitKey(1) == ord("q"): # q to quit + self.close() + raise StopIteration + time.sleep(1 / min(self.fps)) + x = self.imgs[i] + if not x: + LOGGER.warning(f"WARNING ⚠️ Waiting for stream {i}") + + # Get and remove the first frame from imgs buffer + if self.buffer: + images.append(x.pop(0)) + + # Get the last frame, and clear the rest from the imgs buffer + else: + images.append(x.pop(-1) if x else np.zeros(self.shape[i], dtype=np.uint8)) + x.clear() + + return self.sources, images, [""] * self.bs + + def __len__(self): + """Return the length of the sources object.""" + return self.bs # 1E12 frames = 32 streams at 30 FPS for 30 years + + +class LoadScreenshots: + """ + YOLOv8 screenshot dataloader. + + This class manages the loading of screenshot images for processing with YOLOv8. + Suitable for use with `yolo predict source=screen`. + + Attributes: + source (str): The source input indicating which screen to capture. + screen (int): The screen number to capture. + left (int): The left coordinate for screen capture area. + top (int): The top coordinate for screen capture area. + width (int): The width of the screen capture area. + height (int): The height of the screen capture area. + mode (str): Set to 'stream' indicating real-time capture. + frame (int): Counter for captured frames. + sct (mss.mss): Screen capture object from `mss` library. + bs (int): Batch size, set to 1. + monitor (dict): Monitor configuration details. + + Methods: + __iter__: Returns an iterator object. + __next__: Captures the next screenshot and returns it. + """ + + def __init__(self, source): + """Source = [screen_number left top width height] (pixels).""" + check_requirements("mss") + import mss # noqa + + source, *params = source.split() + self.screen, left, top, width, height = 0, None, None, None, None # default to full screen 0 + if len(params) == 1: + self.screen = int(params[0]) + elif len(params) == 4: + left, top, width, height = (int(x) for x in params) + elif len(params) == 5: + self.screen, left, top, width, height = (int(x) for x in params) + self.mode = "stream" + self.frame = 0 + self.sct = mss.mss() + self.bs = 1 + self.fps = 30 + + # Parse monitor shape + monitor = self.sct.monitors[self.screen] + self.top = monitor["top"] if top is None else (monitor["top"] + top) + self.left = monitor["left"] if left is None else (monitor["left"] + left) + self.width = width or monitor["width"] + self.height = height or monitor["height"] + self.monitor = {"left": self.left, "top": self.top, "width": self.width, "height": self.height} + + def __iter__(self): + """Returns an iterator of the object.""" + return self + + def __next__(self): + """mss screen capture: get raw pixels from the screen as np array.""" + im0 = np.asarray(self.sct.grab(self.monitor))[:, :, :3] # BGRA to BGR + s = f"screen {self.screen} (LTWH): {self.left},{self.top},{self.width},{self.height}: " + + self.frame += 1 + return [str(self.screen)], [im0], [s] # screen, img, string + + +class LoadImagesAndVideos: + """ + YOLOv8 image/video dataloader. + + This class manages the loading and pre-processing of image and video data for YOLOv8. It supports loading from + various formats, including single image files, video files, and lists of image and video paths. + + Attributes: + files (list): List of image and video file paths. + nf (int): Total number of files (images and videos). + video_flag (list): Flags indicating whether a file is a video (True) or an image (False). + mode (str): Current mode, 'image' or 'video'. + vid_stride (int): Stride for video frame-rate, defaults to 1. + bs (int): Batch size, set to 1 for this class. + cap (cv2.VideoCapture): Video capture object for OpenCV. + frame (int): Frame counter for video. + frames (int): Total number of frames in the video. + count (int): Counter for iteration, initialized at 0 during `__iter__()`. + + Methods: + _new_video(path): Create a new cv2.VideoCapture object for a given video path. + """ + + def __init__(self, path, batch=1, vid_stride=1): + """Initialize the Dataloader and raise FileNotFoundError if file not found.""" + parent = None + if isinstance(path, str) and Path(path).suffix == ".txt": # *.txt file with img/vid/dir on each line + parent = Path(path).parent + path = Path(path).read_text().splitlines() # list of sources + files = [] + for p in sorted(path) if isinstance(path, (list, tuple)) else [path]: + a = str(Path(p).absolute()) # do not use .resolve() https://github.com/ultralytics/ultralytics/issues/2912 + if "*" in a: + files.extend(sorted(glob.glob(a, recursive=True))) # glob + elif os.path.isdir(a): + files.extend(sorted(glob.glob(os.path.join(a, "*.*")))) # dir + elif os.path.isfile(a): + files.append(a) # files (absolute or relative to CWD) + elif parent and (parent / p).is_file(): + files.append(str((parent / p).absolute())) # files (relative to *.txt file parent) + else: + raise FileNotFoundError(f"{p} does not exist") + + # Define files as images or videos + images, videos = [], [] + for f in files: + suffix = f.split(".")[-1].lower() # Get file extension without the dot and lowercase + if suffix in IMG_FORMATS: + images.append(f) + elif suffix in VID_FORMATS: + videos.append(f) + ni, nv = len(images), len(videos) + + self.files = images + videos + self.nf = ni + nv # number of files + self.ni = ni # number of images + self.video_flag = [False] * ni + [True] * nv + self.mode = "image" + self.vid_stride = vid_stride # video frame-rate stride + self.bs = batch + if any(videos): + self._new_video(videos[0]) # new video + else: + self.cap = None + if self.nf == 0: + raise FileNotFoundError(f"No images or videos found in {p}. {FORMATS_HELP_MSG}") + + def __iter__(self): + """Returns an iterator object for VideoStream or ImageFolder.""" + self.count = 0 + return self + + def __next__(self): + """Returns the next batch of images or video frames along with their paths and metadata.""" + paths, imgs, info = [], [], [] + while len(imgs) < self.bs: + if self.count >= self.nf: # end of file list + if len(imgs) > 0: + return paths, imgs, info # return last partial batch + else: + raise StopIteration + + path = self.files[self.count] + if self.video_flag[self.count]: + self.mode = "video" + if not self.cap or not self.cap.isOpened(): + self._new_video(path) + + for _ in range(self.vid_stride): + success = self.cap.grab() + if not success: + break # end of video or failure + + if success: + success, im0 = self.cap.retrieve() + if success: + self.frame += 1 + paths.append(path) + imgs.append(im0) + info.append(f"video {self.count + 1}/{self.nf} (frame {self.frame}/{self.frames}) {path}: ") + if self.frame == self.frames: # end of video + self.count += 1 + self.cap.release() + else: + # Move to the next file if the current video ended or failed to open + self.count += 1 + if self.cap: + self.cap.release() + if self.count < self.nf: + self._new_video(self.files[self.count]) + else: + self.mode = "image" + im0 = cv2.imread(path) # BGR + if im0 is None: + raise FileNotFoundError(f"Image Not Found {path}") + paths.append(path) + imgs.append(im0) + info.append(f"image {self.count + 1}/{self.nf} {path}: ") + self.count += 1 # move to the next file + if self.count >= self.ni: # end of image list + break + + return paths, imgs, info + + def _new_video(self, path): + """Creates a new video capture object for the given path.""" + self.frame = 0 + self.cap = cv2.VideoCapture(path) + self.fps = int(self.cap.get(cv2.CAP_PROP_FPS)) + if not self.cap.isOpened(): + raise FileNotFoundError(f"Failed to open video {path}") + self.frames = int(self.cap.get(cv2.CAP_PROP_FRAME_COUNT) / self.vid_stride) + + def __len__(self): + """Returns the number of batches in the object.""" + return math.ceil(self.nf / self.bs) # number of files + + +class LoadPilAndNumpy: + """ + Load images from PIL and Numpy arrays for batch processing. + + This class is designed to manage loading and pre-processing of image data from both PIL and Numpy formats. + It performs basic validation and format conversion to ensure that the images are in the required format for + downstream processing. + + Attributes: + paths (list): List of image paths or autogenerated filenames. + im0 (list): List of images stored as Numpy arrays. + mode (str): Type of data being processed, defaults to 'image'. + bs (int): Batch size, equivalent to the length of `im0`. + + Methods: + _single_check(im): Validate and format a single image to a Numpy array. + """ + + def __init__(self, im0): + """Initialize PIL and Numpy Dataloader.""" + if not isinstance(im0, list): + im0 = [im0] + self.paths = [getattr(im, "filename", f"image{i}.jpg") for i, im in enumerate(im0)] + self.im0 = [self._single_check(im) for im in im0] + self.mode = "image" + self.bs = len(self.im0) + + @staticmethod + def _single_check(im): + """Validate and format an image to numpy array.""" + assert isinstance(im, (Image.Image, np.ndarray)), f"Expected PIL/np.ndarray image type, but got {type(im)}" + if isinstance(im, Image.Image): + if im.mode != "RGB": + im = im.convert("RGB") + im = np.asarray(im)[:, :, ::-1] + im = np.ascontiguousarray(im) # contiguous + return im + + def __len__(self): + """Returns the length of the 'im0' attribute.""" + return len(self.im0) + + def __next__(self): + """Returns batch paths, images, processed images, None, ''.""" + if self.count == 1: # loop only once as it's batch inference + raise StopIteration + self.count += 1 + return self.paths, self.im0, [""] * self.bs + + def __iter__(self): + """Enables iteration for class LoadPilAndNumpy.""" + self.count = 0 + return self + + +class LoadTensor: + """ + Load images from torch.Tensor data. + + This class manages the loading and pre-processing of image data from PyTorch tensors for further processing. + + Attributes: + im0 (torch.Tensor): The input tensor containing the image(s). + bs (int): Batch size, inferred from the shape of `im0`. + mode (str): Current mode, set to 'image'. + paths (list): List of image paths or filenames. + count (int): Counter for iteration, initialized at 0 during `__iter__()`. + + Methods: + _single_check(im, stride): Validate and possibly modify the input tensor. + """ + + def __init__(self, im0) -> None: + """Initialize Tensor Dataloader.""" + self.im0 = self._single_check(im0) + self.bs = self.im0.shape[0] + self.mode = "image" + self.paths = [getattr(im, "filename", f"image{i}.jpg") for i, im in enumerate(im0)] + + @staticmethod + def _single_check(im, stride=32): + """Validate and format an image to torch.Tensor.""" + s = ( + f"WARNING ⚠️ torch.Tensor inputs should be BCHW i.e. shape(1, 3, 640, 640) " + f"divisible by stride {stride}. Input shape{tuple(im.shape)} is incompatible." + ) + if len(im.shape) != 4: + if len(im.shape) != 3: + raise ValueError(s) + LOGGER.warning(s) + im = im.unsqueeze(0) + if im.shape[2] % stride or im.shape[3] % stride: + raise ValueError(s) + if im.max() > 1.0 + torch.finfo(im.dtype).eps: # torch.float32 eps is 1.2e-07 + LOGGER.warning( + f"WARNING ⚠️ torch.Tensor inputs should be normalized 0.0-1.0 but max value is {im.max()}. " + f"Dividing input by 255." + ) + im = im.float() / 255.0 + + return im + + def __iter__(self): + """Returns an iterator object.""" + self.count = 0 + return self + + def __next__(self): + """Return next item in the iterator.""" + if self.count == 1: + raise StopIteration + self.count += 1 + return self.paths, self.im0, [""] * self.bs + + def __len__(self): + """Returns the batch size.""" + return self.bs + + +def autocast_list(source): + """Merges a list of source of different types into a list of numpy arrays or PIL images.""" + files = [] + for im in source: + if isinstance(im, (str, Path)): # filename or uri + files.append(Image.open(requests.get(im, stream=True).raw if str(im).startswith("http") else im)) + elif isinstance(im, (Image.Image, np.ndarray)): # PIL or np Image + files.append(im) + else: + raise TypeError( + f"type {type(im).__name__} is not a supported Ultralytics prediction source type. \n" + f"See https://docs.ultralytics.com/modes/predict for supported source types." + ) + + return files + + +def get_best_youtube_url(url, use_pafy=True): + """ + Retrieves the URL of the best quality MP4 video stream from a given YouTube video. + + This function uses the pafy or yt_dlp library to extract the video info from YouTube. It then finds the highest + quality MP4 format that has video codec but no audio codec, and returns the URL of this video stream. + + Args: + url (str): The URL of the YouTube video. + use_pafy (bool): Use the pafy package, default=True, otherwise use yt_dlp package. + + Returns: + (str): The URL of the best quality MP4 video stream, or None if no suitable stream is found. + """ + if use_pafy: + check_requirements(("pafy", "youtube_dl==2020.12.2")) + import pafy # noqa + + return pafy.new(url).getbestvideo(preftype="mp4").url + else: + check_requirements("yt-dlp") + import yt_dlp + + with yt_dlp.YoutubeDL({"quiet": True}) as ydl: + info_dict = ydl.extract_info(url, download=False) # extract info + for f in reversed(info_dict.get("formats", [])): # reversed because best is usually last + # Find a format with video codec, no audio, *.mp4 extension at least 1920x1080 size + good_size = (f.get("width") or 0) >= 1920 or (f.get("height") or 0) >= 1080 + if good_size and f["vcodec"] != "none" and f["acodec"] == "none" and f["ext"] == "mp4": + return f.get("url") + + +# Define constants +LOADERS = (LoadStreams, LoadPilAndNumpy, LoadImagesAndVideos, LoadScreenshots) diff --git a/ultralytics/data/scripts/download_weights.sh b/ultralytics/data/scripts/download_weights.sh new file mode 100644 index 0000000..87db31f --- /dev/null +++ b/ultralytics/data/scripts/download_weights.sh @@ -0,0 +1,18 @@ +#!/bin/bash +# Ultralytics YOLO 🚀, AGPL-3.0 license +# Download latest models from https://github.com/ultralytics/assets/releases +# Example usage: bash ultralytics/data/scripts/download_weights.sh +# parent +# └── weights +# ├── yolov8n.pt ← downloads here +# ├── yolov8s.pt +# └── ... + +python - < gap, f"invalid crop_size gap pair [{crop_size} {gap}]" + step = crop_size - gap + + xn = 1 if w <= crop_size else ceil((w - crop_size) / step + 1) + xs = [step * i for i in range(xn)] + if len(xs) > 1 and xs[-1] + crop_size > w: + xs[-1] = w - crop_size + + yn = 1 if h <= crop_size else ceil((h - crop_size) / step + 1) + ys = [step * i for i in range(yn)] + if len(ys) > 1 and ys[-1] + crop_size > h: + ys[-1] = h - crop_size + + start = np.array(list(itertools.product(xs, ys)), dtype=np.int64) + stop = start + crop_size + windows.append(np.concatenate([start, stop], axis=1)) + windows = np.concatenate(windows, axis=0) + + im_in_wins = windows.copy() + im_in_wins[:, 0::2] = np.clip(im_in_wins[:, 0::2], 0, w) + im_in_wins[:, 1::2] = np.clip(im_in_wins[:, 1::2], 0, h) + im_areas = (im_in_wins[:, 2] - im_in_wins[:, 0]) * (im_in_wins[:, 3] - im_in_wins[:, 1]) + win_areas = (windows[:, 2] - windows[:, 0]) * (windows[:, 3] - windows[:, 1]) + im_rates = im_areas / win_areas + if not (im_rates > im_rate_thr).any(): + max_rate = im_rates.max() + im_rates[abs(im_rates - max_rate) < eps] = 1 + return windows[im_rates > im_rate_thr] + + +def get_window_obj(anno, windows, iof_thr=0.7): + """Get objects for each window.""" + h, w = anno["ori_size"] + label = anno["label"] + if len(label): + label[:, 1::2] *= w + label[:, 2::2] *= h + iofs = bbox_iof(label[:, 1:], windows) + # Unnormalized and misaligned coordinates + return [(label[iofs[:, i] >= iof_thr]) for i in range(len(windows))] # window_anns + else: + return [np.zeros((0, 9), dtype=np.float32) for _ in range(len(windows))] # window_anns + + +def crop_and_save(anno, windows, window_objs, im_dir, lb_dir): + """ + Crop images and save new labels. + + Args: + anno (dict): Annotation dict, including `filepath`, `label`, `ori_size` as its keys. + windows (list): A list of windows coordinates. + window_objs (list): A list of labels inside each window. + im_dir (str): The output directory path of images. + lb_dir (str): The output directory path of labels. + + Notes: + The directory structure assumed for the DOTA dataset: + - data_root + - images + - train + - val + - labels + - train + - val + """ + im = cv2.imread(anno["filepath"]) + name = Path(anno["filepath"]).stem + for i, window in enumerate(windows): + x_start, y_start, x_stop, y_stop = window.tolist() + new_name = f"{name}__{x_stop - x_start}__{x_start}___{y_start}" + patch_im = im[y_start:y_stop, x_start:x_stop] + ph, pw = patch_im.shape[:2] + + cv2.imwrite(str(Path(im_dir) / f"{new_name}.jpg"), patch_im) + label = window_objs[i] + if len(label) == 0: + continue + label[:, 1::2] -= x_start + label[:, 2::2] -= y_start + label[:, 1::2] /= pw + label[:, 2::2] /= ph + + with open(Path(lb_dir) / f"{new_name}.txt", "w") as f: + for lb in label: + formatted_coords = ["{:.6g}".format(coord) for coord in lb[1:]] + f.write(f"{int(lb[0])} {' '.join(formatted_coords)}\n") + + +def split_images_and_labels(data_root, save_dir, split="train", crop_sizes=[1024], gaps=[200]): + """ + Split both images and labels. + + Notes: + The directory structure assumed for the DOTA dataset: + - data_root + - images + - split + - labels + - split + and the output directory structure is: + - save_dir + - images + - split + - labels + - split + """ + im_dir = Path(save_dir) / "images" / split + im_dir.mkdir(parents=True, exist_ok=True) + lb_dir = Path(save_dir) / "labels" / split + lb_dir.mkdir(parents=True, exist_ok=True) + + annos = load_yolo_dota(data_root, split=split) + for anno in tqdm(annos, total=len(annos), desc=split): + windows = get_windows(anno["ori_size"], crop_sizes, gaps) + window_objs = get_window_obj(anno, windows) + crop_and_save(anno, windows, window_objs, str(im_dir), str(lb_dir)) + + +def split_trainval(data_root, save_dir, crop_size=1024, gap=200, rates=[1.0]): + """ + Split train and val set of DOTA. + + Notes: + The directory structure assumed for the DOTA dataset: + - data_root + - images + - train + - val + - labels + - train + - val + and the output directory structure is: + - save_dir + - images + - train + - val + - labels + - train + - val + """ + crop_sizes, gaps = [], [] + for r in rates: + crop_sizes.append(int(crop_size / r)) + gaps.append(int(gap / r)) + for split in ["train", "val"]: + split_images_and_labels(data_root, save_dir, split, crop_sizes, gaps) + + +def split_test(data_root, save_dir, crop_size=1024, gap=200, rates=[1.0]): + """ + Split test set of DOTA, labels are not included within this set. + + Notes: + The directory structure assumed for the DOTA dataset: + - data_root + - images + - test + and the output directory structure is: + - save_dir + - images + - test + """ + crop_sizes, gaps = [], [] + for r in rates: + crop_sizes.append(int(crop_size / r)) + gaps.append(int(gap / r)) + save_dir = Path(save_dir) / "images" / "test" + save_dir.mkdir(parents=True, exist_ok=True) + + im_dir = Path(data_root) / "images" / "test" + assert im_dir.exists(), f"Can't find {im_dir}, please check your data root." + im_files = glob(str(im_dir / "*")) + for im_file in tqdm(im_files, total=len(im_files), desc="test"): + w, h = exif_size(Image.open(im_file)) + windows = get_windows((h, w), crop_sizes=crop_sizes, gaps=gaps) + im = cv2.imread(im_file) + name = Path(im_file).stem + for window in windows: + x_start, y_start, x_stop, y_stop = window.tolist() + new_name = f"{name}__{x_stop - x_start}__{x_start}___{y_start}" + patch_im = im[y_start:y_stop, x_start:x_stop] + cv2.imwrite(str(save_dir / f"{new_name}.jpg"), patch_im) + + +if __name__ == "__main__": + split_trainval(data_root="DOTAv2", save_dir="DOTAv2-split") + split_test(data_root="DOTAv2", save_dir="DOTAv2-split") diff --git a/ultralytics/data/utils.py b/ultralytics/data/utils.py new file mode 100644 index 0000000..7841426 --- /dev/null +++ b/ultralytics/data/utils.py @@ -0,0 +1,676 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import contextlib +import hashlib +import json +import os +import random +import subprocess +import time +import zipfile +from multiprocessing.pool import ThreadPool +from pathlib import Path +from tarfile import is_tarfile + +import cv2 +import numpy as np +from PIL import Image, ImageOps + +from ultralytics.nn.autobackend import check_class_names +from ultralytics.utils import ( + DATASETS_DIR, + LOGGER, + NUM_THREADS, + ROOT, + SETTINGS_YAML, + TQDM, + clean_url, + colorstr, + emojis, + is_dir_writeable, + yaml_load, + yaml_save, +) +from ultralytics.utils.checks import check_file, check_font, is_ascii +from ultralytics.utils.downloads import download, safe_download, unzip_file +from ultralytics.utils.ops import segments2boxes + +HELP_URL = "See https://docs.ultralytics.com/datasets/detect for dataset formatting guidance." +IMG_FORMATS = {"bmp", "dng", "jpeg", "jpg", "mpo", "png", "tif", "tiff", "webp", "pfm"} # image suffixes +VID_FORMATS = {"asf", "avi", "gif", "m4v", "mkv", "mov", "mp4", "mpeg", "mpg", "ts", "wmv", "webm"} # video suffixes +PIN_MEMORY = str(os.getenv("PIN_MEMORY", True)).lower() == "true" # global pin_memory for dataloaders +FORMATS_HELP_MSG = f"Supported formats are:\nimages: {IMG_FORMATS}\nvideos: {VID_FORMATS}" + + +def img2label_paths(img_paths): + """Define label paths as a function of image paths.""" + sa, sb = f"{os.sep}images{os.sep}", f"{os.sep}labels{os.sep}" # /images/, /labels/ substrings + return [sb.join(x.rsplit(sa, 1)).rsplit(".", 1)[0] + ".txt" for x in img_paths] + + +def get_hash(paths): + """Returns a single hash value of a list of paths (files or dirs).""" + size = sum(os.path.getsize(p) for p in paths if os.path.exists(p)) # sizes + h = hashlib.sha256(str(size).encode()) # hash sizes + h.update("".join(paths).encode()) # hash paths + return h.hexdigest() # return hash + + +def exif_size(img: Image.Image): + """Returns exif-corrected PIL size.""" + s = img.size # (width, height) + if img.format == "JPEG": # only support JPEG images + with contextlib.suppress(Exception): + exif = img.getexif() + if exif: + rotation = exif.get(274, None) # the EXIF key for the orientation tag is 274 + if rotation in {6, 8}: # rotation 270 or 90 + s = s[1], s[0] + return s + + +def verify_image(args): + """Verify one image.""" + (im_file, cls), prefix = args + # Number (found, corrupt), message + nf, nc, msg = 0, 0, "" + try: + im = Image.open(im_file) + im.verify() # PIL verify + shape = exif_size(im) # image size + shape = (shape[1], shape[0]) # hw + assert (shape[0] > 9) & (shape[1] > 9), f"image size {shape} <10 pixels" + assert im.format.lower() in IMG_FORMATS, f"Invalid image format {im.format}. {FORMATS_HELP_MSG}" + if im.format.lower() in {"jpg", "jpeg"}: + with open(im_file, "rb") as f: + f.seek(-2, 2) + if f.read() != b"\xff\xd9": # corrupt JPEG + ImageOps.exif_transpose(Image.open(im_file)).save(im_file, "JPEG", subsampling=0, quality=100) + msg = f"{prefix}WARNING ⚠️ {im_file}: corrupt JPEG restored and saved" + nf = 1 + except Exception as e: + nc = 1 + msg = f"{prefix}WARNING ⚠️ {im_file}: ignoring corrupt image/label: {e}" + return (im_file, cls), nf, nc, msg + + +def verify_image_label(args): + """Verify one image-label pair.""" + im_file, lb_file, prefix, keypoint, num_cls, nkpt, ndim = args + # Number (missing, found, empty, corrupt), message, segments, keypoints + nm, nf, ne, nc, msg, segments, keypoints = 0, 0, 0, 0, "", [], None + try: + # Verify images + im = Image.open(im_file) + im.verify() # PIL verify + shape = exif_size(im) # image size + shape = (shape[1], shape[0]) # hw + assert (shape[0] > 9) & (shape[1] > 9), f"image size {shape} <10 pixels" + assert im.format.lower() in IMG_FORMATS, f"invalid image format {im.format}. {FORMATS_HELP_MSG}" + if im.format.lower() in {"jpg", "jpeg"}: + with open(im_file, "rb") as f: + f.seek(-2, 2) + if f.read() != b"\xff\xd9": # corrupt JPEG + ImageOps.exif_transpose(Image.open(im_file)).save(im_file, "JPEG", subsampling=0, quality=100) + msg = f"{prefix}WARNING ⚠️ {im_file}: corrupt JPEG restored and saved" + + # Verify labels + if os.path.isfile(lb_file): + nf = 1 # label found + with open(lb_file) as f: + lb = [x.split() for x in f.read().strip().splitlines() if len(x)] + if any(len(x) > 6 for x in lb) and (not keypoint): # is segment + classes = np.array([x[0] for x in lb], dtype=np.float32) + segments = [np.array(x[1:], dtype=np.float32).reshape(-1, 2) for x in lb] # (cls, xy1...) + lb = np.concatenate((classes.reshape(-1, 1), segments2boxes(segments)), 1) # (cls, xywh) + lb = np.array(lb, dtype=np.float32) + nl = len(lb) + if nl: + if keypoint: + assert lb.shape[1] == (5 + nkpt * ndim), f"labels require {(5 + nkpt * ndim)} columns each" + points = lb[:, 5:].reshape(-1, ndim)[:, :2] + else: + assert lb.shape[1] == 5, f"labels require 5 columns, {lb.shape[1]} columns detected" + points = lb[:, 1:] + assert points.max() <= 1, f"non-normalized or out of bounds coordinates {points[points > 1]}" + assert lb.min() >= 0, f"negative label values {lb[lb < 0]}" + + # All labels + max_cls = lb[:, 0].max() # max label count + assert max_cls <= num_cls, ( + f"Label class {int(max_cls)} exceeds dataset class count {num_cls}. " + f"Possible class labels are 0-{num_cls - 1}" + ) + _, i = np.unique(lb, axis=0, return_index=True) + if len(i) < nl: # duplicate row check + lb = lb[i] # remove duplicates + if segments: + segments = [segments[x] for x in i] + msg = f"{prefix}WARNING ⚠️ {im_file}: {nl - len(i)} duplicate labels removed" + else: + ne = 1 # label empty + lb = np.zeros((0, (5 + nkpt * ndim) if keypoint else 5), dtype=np.float32) + else: + nm = 1 # label missing + lb = np.zeros((0, (5 + nkpt * ndim) if keypoints else 5), dtype=np.float32) + if keypoint: + keypoints = lb[:, 5:].reshape(-1, nkpt, ndim) + if ndim == 2: + kpt_mask = np.where((keypoints[..., 0] < 0) | (keypoints[..., 1] < 0), 0.0, 1.0).astype(np.float32) + keypoints = np.concatenate([keypoints, kpt_mask[..., None]], axis=-1) # (nl, nkpt, 3) + lb = lb[:, :5] + return im_file, lb, shape, segments, keypoints, nm, nf, ne, nc, msg + except Exception as e: + nc = 1 + msg = f"{prefix}WARNING ⚠️ {im_file}: ignoring corrupt image/label: {e}" + return [None, None, None, None, None, nm, nf, ne, nc, msg] + + +def polygon2mask(imgsz, polygons, color=1, downsample_ratio=1): + """ + Convert a list of polygons to a binary mask of the specified image size. + + Args: + imgsz (tuple): The size of the image as (height, width). + polygons (list[np.ndarray]): A list of polygons. Each polygon is an array with shape [N, M], where + N is the number of polygons, and M is the number of points such that M % 2 = 0. + color (int, optional): The color value to fill in the polygons on the mask. Defaults to 1. + downsample_ratio (int, optional): Factor by which to downsample the mask. Defaults to 1. + + Returns: + (np.ndarray): A binary mask of the specified image size with the polygons filled in. + """ + mask = np.zeros(imgsz, dtype=np.uint8) + polygons = np.asarray(polygons, dtype=np.int32) + polygons = polygons.reshape((polygons.shape[0], -1, 2)) + cv2.fillPoly(mask, polygons, color=color) + nh, nw = (imgsz[0] // downsample_ratio, imgsz[1] // downsample_ratio) + # Note: fillPoly first then resize is trying to keep the same loss calculation method when mask-ratio=1 + return cv2.resize(mask, (nw, nh)) + + +def polygons2masks(imgsz, polygons, color, downsample_ratio=1): + """ + Convert a list of polygons to a set of binary masks of the specified image size. + + Args: + imgsz (tuple): The size of the image as (height, width). + polygons (list[np.ndarray]): A list of polygons. Each polygon is an array with shape [N, M], where + N is the number of polygons, and M is the number of points such that M % 2 = 0. + color (int): The color value to fill in the polygons on the masks. + downsample_ratio (int, optional): Factor by which to downsample each mask. Defaults to 1. + + Returns: + (np.ndarray): A set of binary masks of the specified image size with the polygons filled in. + """ + return np.array([polygon2mask(imgsz, [x.reshape(-1)], color, downsample_ratio) for x in polygons]) + + +def polygons2masks_overlap(imgsz, segments, downsample_ratio=1): + """Return a (640, 640) overlap mask.""" + masks = np.zeros( + (imgsz[0] // downsample_ratio, imgsz[1] // downsample_ratio), + dtype=np.int32 if len(segments) > 255 else np.uint8, + ) + areas = [] + ms = [] + for si in range(len(segments)): + mask = polygon2mask(imgsz, [segments[si].reshape(-1)], downsample_ratio=downsample_ratio, color=1) + ms.append(mask) + areas.append(mask.sum()) + areas = np.asarray(areas) + index = np.argsort(-areas) + ms = np.array(ms)[index] + for i in range(len(segments)): + mask = ms[i] * (i + 1) + masks = masks + mask + masks = np.clip(masks, a_min=0, a_max=i + 1) + return masks, index + + +def find_dataset_yaml(path: Path) -> Path: + """ + Find and return the YAML file associated with a Detect, Segment or Pose dataset. + + This function searches for a YAML file at the root level of the provided directory first, and if not found, it + performs a recursive search. It prefers YAML files that have the same stem as the provided path. An AssertionError + is raised if no YAML file is found or if multiple YAML files are found. + + Args: + path (Path): The directory path to search for the YAML file. + + Returns: + (Path): The path of the found YAML file. + """ + files = list(path.glob("*.yaml")) or list(path.rglob("*.yaml")) # try root level first and then recursive + assert files, f"No YAML file found in '{path.resolve()}'" + if len(files) > 1: + files = [f for f in files if f.stem == path.stem] # prefer *.yaml files that match + assert len(files) == 1, f"Expected 1 YAML file in '{path.resolve()}', but found {len(files)}.\n{files}" + return files[0] + + +def check_det_dataset(dataset, autodownload=True): + """ + Download, verify, and/or unzip a dataset if not found locally. + + This function checks the availability of a specified dataset, and if not found, it has the option to download and + unzip the dataset. It then reads and parses the accompanying YAML data, ensuring key requirements are met and also + resolves paths related to the dataset. + + Args: + dataset (str): Path to the dataset or dataset descriptor (like a YAML file). + autodownload (bool, optional): Whether to automatically download the dataset if not found. Defaults to True. + + Returns: + (dict): Parsed dataset information and paths. + """ + + file = check_file(dataset) + + # Download (optional) + extract_dir = "" + if zipfile.is_zipfile(file) or is_tarfile(file): + new_dir = safe_download(file, dir=DATASETS_DIR, unzip=True, delete=False) + file = find_dataset_yaml(DATASETS_DIR / new_dir) + extract_dir, autodownload = file.parent, False + + # Read YAML + data = yaml_load(file, append_filename=True) # dictionary + + # Checks + for k in "train", "val": + if k not in data: + if k != "val" or "validation" not in data: + raise SyntaxError( + emojis(f"{dataset} '{k}:' key missing ❌.\n'train' and 'val' are required in all data YAMLs.") + ) + LOGGER.info("WARNING ⚠️ renaming data YAML 'validation' key to 'val' to match YOLO format.") + data["val"] = data.pop("validation") # replace 'validation' key with 'val' key + if "names" not in data and "nc" not in data: + raise SyntaxError(emojis(f"{dataset} key missing ❌.\n either 'names' or 'nc' are required in all data YAMLs.")) + if "names" in data and "nc" in data and len(data["names"]) != data["nc"]: + raise SyntaxError(emojis(f"{dataset} 'names' length {len(data['names'])} and 'nc: {data['nc']}' must match.")) + if "names" not in data: + data["names"] = [f"class_{i}" for i in range(data["nc"])] + else: + data["nc"] = len(data["names"]) + + data["names"] = check_class_names(data["names"]) + + # Resolve paths + path = Path(extract_dir or data.get("path") or Path(data.get("yaml_file", "")).parent) # dataset root + if not path.is_absolute(): + path = (DATASETS_DIR / path).resolve() + + # Set paths + data["path"] = path # download scripts + for k in "train", "val", "test", "minival": + if data.get(k): # prepend path + if isinstance(data[k], str): + x = (path / data[k]).resolve() + if not x.exists() and data[k].startswith("../"): + x = (path / data[k][3:]).resolve() + data[k] = str(x) + else: + data[k] = [str((path / x).resolve()) for x in data[k]] + + # Parse YAML + val, s = (data.get(x) for x in ("val", "download")) + if val: + val = [Path(x).resolve() for x in (val if isinstance(val, list) else [val])] # val path + if not all(x.exists() for x in val): + name = clean_url(dataset) # dataset name with URL auth stripped + m = f"\nDataset '{name}' images not found ⚠️, missing path '{[x for x in val if not x.exists()][0]}'" + if s and autodownload: + LOGGER.warning(m) + else: + m += f"\nNote dataset download directory is '{DATASETS_DIR}'. You can update this in '{SETTINGS_YAML}'" + raise FileNotFoundError(m) + t = time.time() + r = None # success + if s.startswith("http") and s.endswith(".zip"): # URL + safe_download(url=s, dir=DATASETS_DIR, delete=True) + elif s.startswith("bash "): # bash script + LOGGER.info(f"Running {s} ...") + r = os.system(s) + else: # python script + exec(s, {"yaml": data}) + dt = f"({round(time.time() - t, 1)}s)" + s = f"success ✅ {dt}, saved to {colorstr('bold', DATASETS_DIR)}" if r in {0, None} else f"failure {dt} ❌" + LOGGER.info(f"Dataset download {s}\n") + check_font("Arial.ttf" if is_ascii(data["names"]) else "Arial.Unicode.ttf") # download fonts + + return data # dictionary + + +def check_cls_dataset(dataset, split=""): + """ + Checks a classification dataset such as Imagenet. + + This function accepts a `dataset` name and attempts to retrieve the corresponding dataset information. + If the dataset is not found locally, it attempts to download the dataset from the internet and save it locally. + + Args: + dataset (str | Path): The name of the dataset. + split (str, optional): The split of the dataset. Either 'val', 'test', or ''. Defaults to ''. + + Returns: + (dict): A dictionary containing the following keys: + - 'train' (Path): The directory path containing the training set of the dataset. + - 'val' (Path): The directory path containing the validation set of the dataset. + - 'test' (Path): The directory path containing the test set of the dataset. + - 'nc' (int): The number of classes in the dataset. + - 'names' (dict): A dictionary of class names in the dataset. + """ + + # Download (optional if dataset=https://file.zip is passed directly) + if str(dataset).startswith(("http:/", "https:/")): + dataset = safe_download(dataset, dir=DATASETS_DIR, unzip=True, delete=False) + elif Path(dataset).suffix in {".zip", ".tar", ".gz"}: + file = check_file(dataset) + dataset = safe_download(file, dir=DATASETS_DIR, unzip=True, delete=False) + + dataset = Path(dataset) + data_dir = (dataset if dataset.is_dir() else (DATASETS_DIR / dataset)).resolve() + if not data_dir.is_dir(): + LOGGER.warning(f"\nDataset not found ⚠️, missing path {data_dir}, attempting download...") + t = time.time() + if str(dataset) == "imagenet": + subprocess.run(f"bash {ROOT / 'data/scripts/get_imagenet.sh'}", shell=True, check=True) + else: + url = f"https://github.com/ultralytics/yolov5/releases/download/v1.0/{dataset}.zip" + download(url, dir=data_dir.parent) + s = f"Dataset download success ✅ ({time.time() - t:.1f}s), saved to {colorstr('bold', data_dir)}\n" + LOGGER.info(s) + train_set = data_dir / "train" + val_set = ( + data_dir / "val" + if (data_dir / "val").exists() + else data_dir / "validation" + if (data_dir / "validation").exists() + else None + ) # data/test or data/val + test_set = data_dir / "test" if (data_dir / "test").exists() else None # data/val or data/test + if split == "val" and not val_set: + LOGGER.warning("WARNING ⚠️ Dataset 'split=val' not found, using 'split=test' instead.") + elif split == "test" and not test_set: + LOGGER.warning("WARNING ⚠️ Dataset 'split=test' not found, using 'split=val' instead.") + + nc = len([x for x in (data_dir / "train").glob("*") if x.is_dir()]) # number of classes + names = [x.name for x in (data_dir / "train").iterdir() if x.is_dir()] # class names list + names = dict(enumerate(sorted(names))) + + # Print to console + for k, v in {"train": train_set, "val": val_set, "test": test_set}.items(): + prefix = f'{colorstr(f"{k}:")} {v}...' + if v is None: + LOGGER.info(prefix) + else: + files = [path for path in v.rglob("*.*") if path.suffix[1:].lower() in IMG_FORMATS] + nf = len(files) # number of files + nd = len({file.parent for file in files}) # number of directories + if nf == 0: + if k == "train": + raise FileNotFoundError(emojis(f"{dataset} '{k}:' no training images found ❌ ")) + else: + LOGGER.warning(f"{prefix} found {nf} images in {nd} classes: WARNING ⚠️ no images found") + elif nd != nc: + LOGGER.warning(f"{prefix} found {nf} images in {nd} classes: ERROR ❌️ requires {nc} classes, not {nd}") + else: + LOGGER.info(f"{prefix} found {nf} images in {nd} classes ✅ ") + + return {"train": train_set, "val": val_set, "test": test_set, "nc": nc, "names": names} + + +class HUBDatasetStats: + """ + A class for generating HUB dataset JSON and `-hub` dataset directory. + + Args: + path (str): Path to data.yaml or data.zip (with data.yaml inside data.zip). Default is 'coco8.yaml'. + task (str): Dataset task. Options are 'detect', 'segment', 'pose', 'classify'. Default is 'detect'. + autodownload (bool): Attempt to download dataset if not found locally. Default is False. + + Example: + Download *.zip files from https://github.com/ultralytics/hub/tree/main/example_datasets + i.e. https://github.com/ultralytics/hub/raw/main/example_datasets/coco8.zip for coco8.zip. + ```python + from ultralytics.data.utils import HUBDatasetStats + + stats = HUBDatasetStats('path/to/coco8.zip', task='detect') # detect dataset + stats = HUBDatasetStats('path/to/coco8-seg.zip', task='segment') # segment dataset + stats = HUBDatasetStats('path/to/coco8-pose.zip', task='pose') # pose dataset + stats = HUBDatasetStats('path/to/imagenet10.zip', task='classify') # classification dataset + + stats.get_json(save=True) + stats.process_images() + ``` + """ + + def __init__(self, path="coco8.yaml", task="detect", autodownload=False): + """Initialize class.""" + path = Path(path).resolve() + LOGGER.info(f"Starting HUB dataset checks for {path}....") + + self.task = task # detect, segment, pose, classify + if self.task == "classify": + unzip_dir = unzip_file(path) + data = check_cls_dataset(unzip_dir) + data["path"] = unzip_dir + else: # detect, segment, pose + _, data_dir, yaml_path = self._unzip(Path(path)) + try: + # Load YAML with checks + data = yaml_load(yaml_path) + data["path"] = "" # strip path since YAML should be in dataset root for all HUB datasets + yaml_save(yaml_path, data) + data = check_det_dataset(yaml_path, autodownload) # dict + data["path"] = data_dir # YAML path should be set to '' (relative) or parent (absolute) + except Exception as e: + raise Exception("error/HUB/dataset_stats/init") from e + + self.hub_dir = Path(f'{data["path"]}-hub') + self.im_dir = self.hub_dir / "images" + self.stats = {"nc": len(data["names"]), "names": list(data["names"].values())} # statistics dictionary + self.data = data + + @staticmethod + def _unzip(path): + """Unzip data.zip.""" + if not str(path).endswith(".zip"): # path is data.yaml + return False, None, path + unzip_dir = unzip_file(path, path=path.parent) + assert unzip_dir.is_dir(), ( + f"Error unzipping {path}, {unzip_dir} not found. " f"path/to/abc.zip MUST unzip to path/to/abc/" + ) + return True, str(unzip_dir), find_dataset_yaml(unzip_dir) # zipped, data_dir, yaml_path + + def _hub_ops(self, f): + """Saves a compressed image for HUB previews.""" + compress_one_image(f, self.im_dir / Path(f).name) # save to dataset-hub + + def get_json(self, save=False, verbose=False): + """Return dataset JSON for Ultralytics HUB.""" + + def _round(labels): + """Update labels to integer class and 4 decimal place floats.""" + if self.task == "detect": + coordinates = labels["bboxes"] + elif self.task == "segment": + coordinates = [x.flatten() for x in labels["segments"]] + elif self.task == "pose": + n = labels["keypoints"].shape[0] + coordinates = np.concatenate((labels["bboxes"], labels["keypoints"].reshape(n, -1)), 1) + else: + raise ValueError("Undefined dataset task.") + zipped = zip(labels["cls"], coordinates) + return [[int(c[0]), *(round(float(x), 4) for x in points)] for c, points in zipped] + + for split in "train", "val", "test": + self.stats[split] = None # predefine + path = self.data.get(split) + + # Check split + if path is None: # no split + continue + files = [f for f in Path(path).rglob("*.*") if f.suffix[1:].lower() in IMG_FORMATS] # image files in split + if not files: # no images + continue + + # Get dataset statistics + if self.task == "classify": + from torchvision.datasets import ImageFolder + + dataset = ImageFolder(self.data[split]) + + x = np.zeros(len(dataset.classes)).astype(int) + for im in dataset.imgs: + x[im[1]] += 1 + + self.stats[split] = { + "instance_stats": {"total": len(dataset), "per_class": x.tolist()}, + "image_stats": {"total": len(dataset), "unlabelled": 0, "per_class": x.tolist()}, + "labels": [{Path(k).name: v} for k, v in dataset.imgs], + } + else: + from ultralytics.data import YOLODataset + + dataset = YOLODataset(img_path=self.data[split], data=self.data, task=self.task) + x = np.array( + [ + np.bincount(label["cls"].astype(int).flatten(), minlength=self.data["nc"]) + for label in TQDM(dataset.labels, total=len(dataset), desc="Statistics") + ] + ) # shape(128x80) + self.stats[split] = { + "instance_stats": {"total": int(x.sum()), "per_class": x.sum(0).tolist()}, + "image_stats": { + "total": len(dataset), + "unlabelled": int(np.all(x == 0, 1).sum()), + "per_class": (x > 0).sum(0).tolist(), + }, + "labels": [{Path(k).name: _round(v)} for k, v in zip(dataset.im_files, dataset.labels)], + } + + # Save, print and return + if save: + self.hub_dir.mkdir(parents=True, exist_ok=True) # makes dataset-hub/ + stats_path = self.hub_dir / "stats.json" + LOGGER.info(f"Saving {stats_path.resolve()}...") + with open(stats_path, "w") as f: + json.dump(self.stats, f) # save stats.json + if verbose: + LOGGER.info(json.dumps(self.stats, indent=2, sort_keys=False)) + return self.stats + + def process_images(self): + """Compress images for Ultralytics HUB.""" + from ultralytics.data import YOLODataset # ClassificationDataset + + self.im_dir.mkdir(parents=True, exist_ok=True) # makes dataset-hub/images/ + for split in "train", "val", "test": + if self.data.get(split) is None: + continue + dataset = YOLODataset(img_path=self.data[split], data=self.data) + with ThreadPool(NUM_THREADS) as pool: + for _ in TQDM(pool.imap(self._hub_ops, dataset.im_files), total=len(dataset), desc=f"{split} images"): + pass + LOGGER.info(f"Done. All images saved to {self.im_dir}") + return self.im_dir + + +def compress_one_image(f, f_new=None, max_dim=1920, quality=50): + """ + Compresses a single image file to reduced size while preserving its aspect ratio and quality using either the Python + Imaging Library (PIL) or OpenCV library. If the input image is smaller than the maximum dimension, it will not be + resized. + + Args: + f (str): The path to the input image file. + f_new (str, optional): The path to the output image file. If not specified, the input file will be overwritten. + max_dim (int, optional): The maximum dimension (width or height) of the output image. Default is 1920 pixels. + quality (int, optional): The image compression quality as a percentage. Default is 50%. + + Example: + ```python + from pathlib import Path + from ultralytics.data.utils import compress_one_image + + for f in Path('path/to/dataset').rglob('*.jpg'): + compress_one_image(f) + ``` + """ + + try: # use PIL + im = Image.open(f) + r = max_dim / max(im.height, im.width) # ratio + if r < 1.0: # image too large + im = im.resize((int(im.width * r), int(im.height * r))) + im.save(f_new or f, "JPEG", quality=quality, optimize=True) # save + except Exception as e: # use OpenCV + LOGGER.info(f"WARNING ⚠️ HUB ops PIL failure {f}: {e}") + im = cv2.imread(f) + im_height, im_width = im.shape[:2] + r = max_dim / max(im_height, im_width) # ratio + if r < 1.0: # image too large + im = cv2.resize(im, (int(im_width * r), int(im_height * r)), interpolation=cv2.INTER_AREA) + cv2.imwrite(str(f_new or f), im) + + +def autosplit(path=DATASETS_DIR / "coco8/images", weights=(0.9, 0.1, 0.0), annotated_only=False): + """ + Automatically split a dataset into train/val/test splits and save the resulting splits into autosplit_*.txt files. + + Args: + path (Path, optional): Path to images directory. Defaults to DATASETS_DIR / 'coco8/images'. + weights (list | tuple, optional): Train, validation, and test split fractions. Defaults to (0.9, 0.1, 0.0). + annotated_only (bool, optional): If True, only images with an associated txt file are used. Defaults to False. + + Example: + ```python + from ultralytics.data.utils import autosplit + + autosplit() + ``` + """ + + path = Path(path) # images dir + files = sorted(x for x in path.rglob("*.*") if x.suffix[1:].lower() in IMG_FORMATS) # image files only + n = len(files) # number of files + random.seed(0) # for reproducibility + indices = random.choices([0, 1, 2], weights=weights, k=n) # assign each image to a split + + txt = ["autosplit_train.txt", "autosplit_val.txt", "autosplit_test.txt"] # 3 txt files + for x in txt: + if (path.parent / x).exists(): + (path.parent / x).unlink() # remove existing + + LOGGER.info(f"Autosplitting images from {path}" + ", using *.txt labeled images only" * annotated_only) + for i, img in TQDM(zip(indices, files), total=n): + if not annotated_only or Path(img2label_paths([str(img)])[0]).exists(): # check label + with open(path.parent / txt[i], "a") as f: + f.write(f"./{img.relative_to(path.parent).as_posix()}" + "\n") # add image to txt file + + +def load_dataset_cache_file(path): + """Load an Ultralytics *.cache dictionary from path.""" + import gc + + gc.disable() # reduce pickle load time https://github.com/ultralytics/ultralytics/pull/1585 + cache = np.load(str(path), allow_pickle=True).item() # load dict + gc.enable() + return cache + + +def save_dataset_cache_file(prefix, path, x, version): + """Save an Ultralytics dataset *.cache dictionary x to path.""" + x["version"] = version # add cache version + if is_dir_writeable(path.parent): + if path.exists(): + path.unlink() # remove *.cache file if exists + np.save(str(path), x) # save cache for next time + path.with_suffix(".cache.npy").rename(path) # remove .npy suffix + LOGGER.info(f"{prefix}New cache created: {path}") + else: + LOGGER.warning(f"{prefix}WARNING ⚠️ Cache directory {path.parent} is not writeable, cache not saved.") diff --git a/ultralytics/engine/__init__.py b/ultralytics/engine/__init__.py new file mode 100644 index 0000000..9e68dc1 --- /dev/null +++ b/ultralytics/engine/__init__.py @@ -0,0 +1 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license diff --git a/ultralytics/engine/exporter.py b/ultralytics/engine/exporter.py new file mode 100644 index 0000000..d387384 --- /dev/null +++ b/ultralytics/engine/exporter.py @@ -0,0 +1,1148 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +""" +Export a YOLOv8 PyTorch model to other formats. TensorFlow exports authored by https://github.com/zldrobit + +Format | `format=argument` | Model +--- | --- | --- +PyTorch | - | yolov8n.pt +TorchScript | `torchscript` | yolov8n.torchscript +ONNX | `onnx` | yolov8n.onnx +OpenVINO | `openvino` | yolov8n_openvino_model/ +TensorRT | `engine` | yolov8n.engine +CoreML | `coreml` | yolov8n.mlpackage +TensorFlow SavedModel | `saved_model` | yolov8n_saved_model/ +TensorFlow GraphDef | `pb` | yolov8n.pb +TensorFlow Lite | `tflite` | yolov8n.tflite +TensorFlow Edge TPU | `edgetpu` | yolov8n_edgetpu.tflite +TensorFlow.js | `tfjs` | yolov8n_web_model/ +PaddlePaddle | `paddle` | yolov8n_paddle_model/ +NCNN | `ncnn` | yolov8n_ncnn_model/ + +Requirements: + $ pip install "ultralytics[export]" + +Python: + from ultralytics import YOLO + model = YOLO('yolov8n.pt') + results = model.export(format='onnx') + +CLI: + $ yolo mode=export model=yolov8n.pt format=onnx + +Inference: + $ yolo predict model=yolov8n.pt # PyTorch + yolov8n.torchscript # TorchScript + yolov8n.onnx # ONNX Runtime or OpenCV DNN with dnn=True + yolov8n_openvino_model # OpenVINO + yolov8n.engine # TensorRT + yolov8n.mlpackage # CoreML (macOS-only) + yolov8n_saved_model # TensorFlow SavedModel + yolov8n.pb # TensorFlow GraphDef + yolov8n.tflite # TensorFlow Lite + yolov8n_edgetpu.tflite # TensorFlow Edge TPU + yolov8n_paddle_model # PaddlePaddle + yolov8n_ncnn_model # NCNN + +TensorFlow.js: + $ cd .. && git clone https://github.com/zldrobit/tfjs-yolov5-example.git && cd tfjs-yolov5-example + $ npm install + $ ln -s ../../yolov5/yolov8n_web_model public/yolov8n_web_model + $ npm start +""" + +import json +import os +import shutil +import subprocess +import time +import warnings +from copy import deepcopy +from datetime import datetime +from pathlib import Path + +import numpy as np +import torch + +from ultralytics.cfg import get_cfg +from ultralytics.data.dataset import YOLODataset +from ultralytics.data.utils import check_det_dataset +from ultralytics.nn.autobackend import check_class_names, default_class_names +from ultralytics.nn.modules import C2f, Detect, RTDETRDecoder +from ultralytics.nn.tasks import DetectionModel, SegmentationModel, WorldModel +from ultralytics.utils import ( + ARM64, + DEFAULT_CFG, + LINUX, + LOGGER, + MACOS, + PYTHON_VERSION, + ROOT, + WINDOWS, + __version__, + callbacks, + colorstr, + get_default_args, + yaml_save, +) +from ultralytics.utils.checks import check_imgsz, check_is_path_safe, check_requirements, check_version +from ultralytics.utils.downloads import attempt_download_asset, get_github_assets +from ultralytics.utils.files import file_size, spaces_in_path +from ultralytics.utils.ops import Profile +from ultralytics.utils.torch_utils import TORCH_1_13, get_latest_opset, select_device, smart_inference_mode + + +def export_formats(): + """YOLOv8 export formats.""" + import pandas # scope for faster 'import ultralytics' + + x = [ + ["PyTorch", "-", ".pt", True, True], + ["TorchScript", "torchscript", ".torchscript", True, True], + ["ONNX", "onnx", ".onnx", True, True], + ["OpenVINO", "openvino", "_openvino_model", True, False], + ["TensorRT", "engine", ".engine", False, True], + ["CoreML", "coreml", ".mlpackage", True, False], + ["TensorFlow SavedModel", "saved_model", "_saved_model", True, True], + ["TensorFlow GraphDef", "pb", ".pb", True, True], + ["TensorFlow Lite", "tflite", ".tflite", True, False], + ["TensorFlow Edge TPU", "edgetpu", "_edgetpu.tflite", True, False], + ["TensorFlow.js", "tfjs", "_web_model", True, False], + ["PaddlePaddle", "paddle", "_paddle_model", True, True], + ["NCNN", "ncnn", "_ncnn_model", True, True], + ] + return pandas.DataFrame(x, columns=["Format", "Argument", "Suffix", "CPU", "GPU"]) + + +def gd_outputs(gd): + """TensorFlow GraphDef model output node names.""" + name_list, input_list = [], [] + for node in gd.node: # tensorflow.core.framework.node_def_pb2.NodeDef + name_list.append(node.name) + input_list.extend(node.input) + return sorted(f"{x}:0" for x in list(set(name_list) - set(input_list)) if not x.startswith("NoOp")) + + +def try_export(inner_func): + """YOLOv8 export decorator, i..e @try_export.""" + inner_args = get_default_args(inner_func) + + def outer_func(*args, **kwargs): + """Export a model.""" + prefix = inner_args["prefix"] + try: + with Profile() as dt: + f, model = inner_func(*args, **kwargs) + LOGGER.info(f"{prefix} export success ✅ {dt.t:.1f}s, saved as '{f}' ({file_size(f):.1f} MB)") + return f, model + except Exception as e: + LOGGER.info(f"{prefix} export failure ❌ {dt.t:.1f}s: {e}") + raise e + + return outer_func + + +class Exporter: + """ + A class for exporting a model. + + Attributes: + args (SimpleNamespace): Configuration for the exporter. + callbacks (list, optional): List of callback functions. Defaults to None. + """ + + def __init__(self, cfg=DEFAULT_CFG, overrides=None, _callbacks=None): + """ + Initializes the Exporter class. + + Args: + cfg (str, optional): Path to a configuration file. Defaults to DEFAULT_CFG. + overrides (dict, optional): Configuration overrides. Defaults to None. + _callbacks (dict, optional): Dictionary of callback functions. Defaults to None. + """ + self.args = get_cfg(cfg, overrides) + if self.args.format.lower() in {"coreml", "mlmodel"}: # fix attempt for protobuf<3.20.x errors + os.environ["PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION"] = "python" # must run before TensorBoard callback + + self.callbacks = _callbacks or callbacks.get_default_callbacks() + callbacks.add_integration_callbacks(self) + + @smart_inference_mode() + def __call__(self, model=None): + """Returns list of exported files/dirs after running callbacks.""" + self.run_callbacks("on_export_start") + t = time.time() + fmt = self.args.format.lower() # to lowercase + if fmt in {"tensorrt", "trt"}: # 'engine' aliases + fmt = "engine" + if fmt in {"mlmodel", "mlpackage", "mlprogram", "apple", "ios", "coreml"}: # 'coreml' aliases + fmt = "coreml" + fmts = tuple(export_formats()["Argument"][1:]) # available export formats + flags = [x == fmt for x in fmts] + if sum(flags) != 1: + raise ValueError(f"Invalid export format='{fmt}'. Valid formats are {fmts}") + jit, onnx, xml, engine, coreml, saved_model, pb, tflite, edgetpu, tfjs, paddle, ncnn = flags # export booleans + + # Device + if fmt == "engine" and self.args.device is None: + LOGGER.warning("WARNING ⚠️ TensorRT requires GPU export, automatically assigning device=0") + self.args.device = "0" + self.device = select_device("cpu" if self.args.device is None else self.args.device) + + # Checks + if not hasattr(model, "names"): + model.names = default_class_names() + model.names = check_class_names(model.names) + if self.args.half and onnx and self.device.type == "cpu": + LOGGER.warning("WARNING ⚠️ half=True only compatible with GPU export, i.e. use device=0") + self.args.half = False + assert not self.args.dynamic, "half=True not compatible with dynamic=True, i.e. use only one." + self.imgsz = check_imgsz(self.args.imgsz, stride=model.stride, min_dim=2) # check image size + if self.args.optimize: + assert not ncnn, "optimize=True not compatible with format='ncnn', i.e. use optimize=False" + assert self.device.type == "cpu", "optimize=True not compatible with cuda devices, i.e. use device='cpu'" + if edgetpu and not LINUX: + raise SystemError("Edge TPU export only supported on Linux. See https://coral.ai/docs/edgetpu/compiler/") + if isinstance(model, WorldModel): + LOGGER.warning( + "WARNING ⚠️ YOLOWorld (original version) export is not supported to any format.\n" + "WARNING ⚠️ YOLOWorldv2 models (i.e. 'yolov8s-worldv2.pt') only support export to " + "(torchscript, onnx, openvino, engine, coreml) formats. " + "See https://docs.ultralytics.com/models/yolo-world for details." + ) + + # Input + im = torch.zeros(self.args.batch, 3, *self.imgsz).to(self.device) + file = Path( + getattr(model, "pt_path", None) or getattr(model, "yaml_file", None) or model.yaml.get("yaml_file", "") + ) + if file.suffix in {".yaml", ".yml"}: + file = Path(file.name) + + # Update model + model = deepcopy(model).to(self.device) + for p in model.parameters(): + p.requires_grad = False + model.eval() + model.float() + model = model.fuse() + for m in model.modules(): + if isinstance(m, (Detect, RTDETRDecoder)): # includes all Detect subclasses like Segment, Pose, OBB + m.dynamic = self.args.dynamic + m.export = True + m.format = self.args.format + elif isinstance(m, C2f) and not any((saved_model, pb, tflite, edgetpu, tfjs)): + # EdgeTPU does not support FlexSplitV while split provides cleaner ONNX graph + m.forward = m.forward_split + + y = None + for _ in range(2): + y = model(im) # dry runs + if self.args.half and onnx and self.device.type != "cpu": + im, model = im.half(), model.half() # to FP16 + + # Filter warnings + warnings.filterwarnings("ignore", category=torch.jit.TracerWarning) # suppress TracerWarning + warnings.filterwarnings("ignore", category=UserWarning) # suppress shape prim::Constant missing ONNX warning + warnings.filterwarnings("ignore", category=DeprecationWarning) # suppress CoreML np.bool deprecation warning + + # Assign + self.im = im + self.model = model + self.file = file + self.output_shape = ( + tuple(y.shape) + if isinstance(y, torch.Tensor) + else tuple(tuple(x.shape if isinstance(x, torch.Tensor) else []) for x in y) + ) + self.pretty_name = Path(self.model.yaml.get("yaml_file", self.file)).stem.replace("yolo", "YOLO") + data = model.args["data"] if hasattr(model, "args") and isinstance(model.args, dict) else "" + description = f'Ultralytics {self.pretty_name} model {f"trained on {data}" if data else ""}' + self.metadata = { + "description": description, + "author": "Ultralytics", + "date": datetime.now().isoformat(), + "version": __version__, + "license": "AGPL-3.0 License (https://ultralytics.com/license)", + "docs": "https://docs.ultralytics.com", + "stride": int(max(model.stride)), + "task": model.task, + "batch": self.args.batch, + "imgsz": self.imgsz, + "names": model.names, + } # model metadata + if model.task == "pose": + self.metadata["kpt_shape"] = model.model[-1].kpt_shape + + LOGGER.info( + f"\n{colorstr('PyTorch:')} starting from '{file}' with input shape {tuple(im.shape)} BCHW and " + f'output shape(s) {self.output_shape} ({file_size(file):.1f} MB)' + ) + + # Exports + f = [""] * len(fmts) # exported filenames + if jit or ncnn: # TorchScript + f[0], _ = self.export_torchscript() + if engine: # TensorRT required before ONNX + f[1], _ = self.export_engine() + if onnx: # ONNX + f[2], _ = self.export_onnx() + if xml: # OpenVINO + f[3], _ = self.export_openvino() + if coreml: # CoreML + f[4], _ = self.export_coreml() + if any((saved_model, pb, tflite, edgetpu, tfjs)): # TensorFlow formats + self.args.int8 |= edgetpu + f[5], keras_model = self.export_saved_model() + if pb or tfjs: # pb prerequisite to tfjs + f[6], _ = self.export_pb(keras_model=keras_model) + if tflite: + f[7], _ = self.export_tflite(keras_model=keras_model, nms=False, agnostic_nms=self.args.agnostic_nms) + if edgetpu: + f[8], _ = self.export_edgetpu(tflite_model=Path(f[5]) / f"{self.file.stem}_full_integer_quant.tflite") + if tfjs: + f[9], _ = self.export_tfjs() + if paddle: # PaddlePaddle + f[10], _ = self.export_paddle() + if ncnn: # NCNN + f[11], _ = self.export_ncnn() + + # Finish + f = [str(x) for x in f if x] # filter out '' and None + if any(f): + f = str(Path(f[-1])) + square = self.imgsz[0] == self.imgsz[1] + s = ( + "" + if square + else f"WARNING ⚠️ non-PyTorch val requires square images, 'imgsz={self.imgsz}' will not " + f"work. Use export 'imgsz={max(self.imgsz)}' if val is required." + ) + imgsz = self.imgsz[0] if square else str(self.imgsz)[1:-1].replace(" ", "") + predict_data = f"data={data}" if model.task == "segment" and fmt == "pb" else "" + q = "int8" if self.args.int8 else "half" if self.args.half else "" # quantization + LOGGER.info( + f'\nExport complete ({time.time() - t:.1f}s)' + f"\nResults saved to {colorstr('bold', file.parent.resolve())}" + f'\nPredict: yolo predict task={model.task} model={f} imgsz={imgsz} {q} {predict_data}' + f'\nValidate: yolo val task={model.task} model={f} imgsz={imgsz} data={data} {q} {s}' + f'\nVisualize: https://netron.app' + ) + + self.run_callbacks("on_export_end") + return f # return list of exported files/dirs + + @try_export + def export_torchscript(self, prefix=colorstr("TorchScript:")): + """YOLOv8 TorchScript model export.""" + LOGGER.info(f"\n{prefix} starting export with torch {torch.__version__}...") + f = self.file.with_suffix(".torchscript") + + ts = torch.jit.trace(self.model, self.im, strict=False) + extra_files = {"config.txt": json.dumps(self.metadata)} # torch._C.ExtraFilesMap() + if self.args.optimize: # https://pytorch.org/tutorials/recipes/mobile_interpreter.html + LOGGER.info(f"{prefix} optimizing for mobile...") + from torch.utils.mobile_optimizer import optimize_for_mobile + + optimize_for_mobile(ts)._save_for_lite_interpreter(str(f), _extra_files=extra_files) + else: + ts.save(str(f), _extra_files=extra_files) + return f, None + + @try_export + def export_onnx(self, prefix=colorstr("ONNX:")): + """YOLOv8 ONNX export.""" + requirements = ["onnx>=1.12.0"] + if self.args.simplify: + requirements += ["onnxsim>=0.4.33", "onnxruntime-gpu" if torch.cuda.is_available() else "onnxruntime"] + if ARM64: + check_requirements("cmake") # 'cmake' is needed to build onnxsim on aarch64 + check_requirements(requirements) + import onnx # noqa + + opset_version = self.args.opset or get_latest_opset() + LOGGER.info(f"\n{prefix} starting export with onnx {onnx.__version__} opset {opset_version}...") + f = str(self.file.with_suffix(".onnx")) + + output_names = ["output0", "output1"] if isinstance(self.model, SegmentationModel) else ["output0"] + dynamic = self.args.dynamic + if dynamic: + dynamic = {"images": {0: "batch", 2: "height", 3: "width"}} # shape(1,3,640,640) + if isinstance(self.model, SegmentationModel): + dynamic["output0"] = {0: "batch", 2: "anchors"} # shape(1, 116, 8400) + dynamic["output1"] = {0: "batch", 2: "mask_height", 3: "mask_width"} # shape(1,32,160,160) + elif isinstance(self.model, DetectionModel): + dynamic["output0"] = {0: "batch", 2: "anchors"} # shape(1, 84, 8400) + + torch.onnx.export( + self.model.cpu() if dynamic else self.model, # dynamic=True only compatible with cpu + self.im.cpu() if dynamic else self.im, + f, + verbose=False, + opset_version=opset_version, + do_constant_folding=True, # WARNING: DNN inference with torch>=1.12 may require do_constant_folding=False + input_names=["images"], + output_names=output_names, + dynamic_axes=dynamic or None, + ) + + # Checks + model_onnx = onnx.load(f) # load onnx model + # onnx.checker.check_model(model_onnx) # check onnx model + + # Simplify + if self.args.simplify: + try: + import onnxsim + + LOGGER.info(f"{prefix} simplifying with onnxsim {onnxsim.__version__}...") + # subprocess.run(f'onnxsim "{f}" "{f}"', shell=True) + model_onnx, check = onnxsim.simplify(model_onnx) + assert check, "Simplified ONNX model could not be validated" + except Exception as e: + LOGGER.info(f"{prefix} simplifier failure: {e}") + + # Metadata + for k, v in self.metadata.items(): + meta = model_onnx.metadata_props.add() + meta.key, meta.value = k, str(v) + + onnx.save(model_onnx, f) + return f, model_onnx + + @try_export + def export_openvino(self, prefix=colorstr("OpenVINO:")): + """YOLOv8 OpenVINO export.""" + check_requirements("openvino>=2024.0.0") # requires openvino: https://pypi.org/project/openvino/ + import openvino as ov + + LOGGER.info(f"\n{prefix} starting export with openvino {ov.__version__}...") + assert TORCH_1_13, f"OpenVINO export requires torch>=1.13.0 but torch=={torch.__version__} is installed" + ov_model = ov.convert_model( + self.model.cpu(), + input=None if self.args.dynamic else [self.im.shape], + example_input=self.im, + ) + + def serialize(ov_model, file): + """Set RT info, serialize and save metadata YAML.""" + ov_model.set_rt_info("YOLOv8", ["model_info", "model_type"]) + ov_model.set_rt_info(True, ["model_info", "reverse_input_channels"]) + ov_model.set_rt_info(114, ["model_info", "pad_value"]) + ov_model.set_rt_info([255.0], ["model_info", "scale_values"]) + ov_model.set_rt_info(self.args.iou, ["model_info", "iou_threshold"]) + ov_model.set_rt_info([v.replace(" ", "_") for v in self.model.names.values()], ["model_info", "labels"]) + if self.model.task != "classify": + ov_model.set_rt_info("fit_to_window_letterbox", ["model_info", "resize_type"]) + + ov.runtime.save_model(ov_model, file, compress_to_fp16=self.args.half) + yaml_save(Path(file).parent / "metadata.yaml", self.metadata) # add metadata.yaml + + if self.args.int8: + fq = str(self.file).replace(self.file.suffix, f"_int8_openvino_model{os.sep}") + fq_ov = str(Path(fq) / self.file.with_suffix(".xml").name) + if not self.args.data: + self.args.data = DEFAULT_CFG.data or "coco128.yaml" + LOGGER.warning( + f"{prefix} WARNING ⚠️ INT8 export requires a missing 'data' arg for calibration. " + f"Using default 'data={self.args.data}'." + ) + check_requirements("nncf>=2.8.0") + import nncf + + def transform_fn(data_item): + """Quantization transform function.""" + assert ( + data_item["img"].dtype == torch.uint8 + ), "Input image must be uint8 for the quantization preprocessing" + im = data_item["img"].numpy().astype(np.float32) / 255.0 # uint8 to fp16/32 and 0 - 255 to 0.0 - 1.0 + return np.expand_dims(im, 0) if im.ndim == 3 else im + + # Generate calibration data for integer quantization + LOGGER.info(f"{prefix} collecting INT8 calibration images from 'data={self.args.data}'") + data = check_det_dataset(self.args.data) + dataset = YOLODataset(data["val"], data=data, task=self.model.task, imgsz=self.imgsz[0], augment=False) + n = len(dataset) + if n < 300: + LOGGER.warning(f"{prefix} WARNING ⚠️ >300 images recommended for INT8 calibration, found {n} images.") + quantization_dataset = nncf.Dataset(dataset, transform_fn) + + ignored_scope = None + if isinstance(self.model.model[-1], Detect): + # Includes all Detect subclasses like Segment, Pose, OBB, WorldDetect + head_module_name = ".".join(list(self.model.named_modules())[-1][0].split(".")[:2]) + + ignored_scope = nncf.IgnoredScope( # ignore operations + patterns=[ + f".*{head_module_name}/.*/Add", + f".*{head_module_name}/.*/Sub*", + f".*{head_module_name}/.*/Mul*", + f".*{head_module_name}/.*/Div*", + f".*{head_module_name}\\.dfl.*", + ], + types=["Sigmoid"], + ) + + quantized_ov_model = nncf.quantize( + ov_model, quantization_dataset, preset=nncf.QuantizationPreset.MIXED, ignored_scope=ignored_scope + ) + serialize(quantized_ov_model, fq_ov) + return fq, None + + f = str(self.file).replace(self.file.suffix, f"_openvino_model{os.sep}") + f_ov = str(Path(f) / self.file.with_suffix(".xml").name) + + serialize(ov_model, f_ov) + return f, None + + @try_export + def export_paddle(self, prefix=colorstr("PaddlePaddle:")): + """YOLOv8 Paddle export.""" + check_requirements(("paddlepaddle", "x2paddle")) + import x2paddle # noqa + from x2paddle.convert import pytorch2paddle # noqa + + LOGGER.info(f"\n{prefix} starting export with X2Paddle {x2paddle.__version__}...") + f = str(self.file).replace(self.file.suffix, f"_paddle_model{os.sep}") + + pytorch2paddle(module=self.model, save_dir=f, jit_type="trace", input_examples=[self.im]) # export + yaml_save(Path(f) / "metadata.yaml", self.metadata) # add metadata.yaml + return f, None + + @try_export + def export_ncnn(self, prefix=colorstr("NCNN:")): + """ + YOLOv8 NCNN export using PNNX https://github.com/pnnx/pnnx. + """ + check_requirements("ncnn") + import ncnn # noqa + + LOGGER.info(f"\n{prefix} starting export with NCNN {ncnn.__version__}...") + f = Path(str(self.file).replace(self.file.suffix, f"_ncnn_model{os.sep}")) + f_ts = self.file.with_suffix(".torchscript") + + name = Path("pnnx.exe" if WINDOWS else "pnnx") # PNNX filename + pnnx = name if name.is_file() else ROOT / name + if not pnnx.is_file(): + LOGGER.warning( + f"{prefix} WARNING ⚠️ PNNX not found. Attempting to download binary file from " + "https://github.com/pnnx/pnnx/.\nNote PNNX Binary file must be placed in current working directory " + f"or in {ROOT}. See PNNX repo for full installation instructions." + ) + system = "macos" if MACOS else "windows" if WINDOWS else "linux-aarch64" if ARM64 else "linux" + try: + _, assets = get_github_assets(repo="pnnx/pnnx") + url = [x for x in assets if f"{system}.zip" in x][0] + assert url, "Unable to retrieve PNNX repo assets" + except Exception as e: + url = f"https://github.com/pnnx/pnnx/releases/download/20240410/pnnx-20240410-{system}.zip" + LOGGER.warning(f"{prefix} WARNING ⚠️ PNNX GitHub assets not found: {e}, using default {url}") + asset = attempt_download_asset(url, repo="pnnx/pnnx", release="latest") + if check_is_path_safe(Path.cwd(), asset): # avoid path traversal security vulnerability + unzip_dir = Path(asset).with_suffix("") + (unzip_dir / name).rename(pnnx) # move binary to ROOT + shutil.rmtree(unzip_dir) # delete unzip dir + Path(asset).unlink() # delete zip + pnnx.chmod(0o777) # set read, write, and execute permissions for everyone + + ncnn_args = [ + f'ncnnparam={f / "model.ncnn.param"}', + f'ncnnbin={f / "model.ncnn.bin"}', + f'ncnnpy={f / "model_ncnn.py"}', + ] + + pnnx_args = [ + f'pnnxparam={f / "model.pnnx.param"}', + f'pnnxbin={f / "model.pnnx.bin"}', + f'pnnxpy={f / "model_pnnx.py"}', + f'pnnxonnx={f / "model.pnnx.onnx"}', + ] + + cmd = [ + str(pnnx), + str(f_ts), + *ncnn_args, + *pnnx_args, + f"fp16={int(self.args.half)}", + f"device={self.device.type}", + f'inputshape="{[self.args.batch, 3, *self.imgsz]}"', + ] + f.mkdir(exist_ok=True) # make ncnn_model directory + LOGGER.info(f"{prefix} running '{' '.join(cmd)}'") + subprocess.run(cmd, check=True) + + # Remove debug files + pnnx_files = [x.split("=")[-1] for x in pnnx_args] + for f_debug in ("debug.bin", "debug.param", "debug2.bin", "debug2.param", *pnnx_files): + Path(f_debug).unlink(missing_ok=True) + + yaml_save(f / "metadata.yaml", self.metadata) # add metadata.yaml + return str(f), None + + @try_export + def export_coreml(self, prefix=colorstr("CoreML:")): + """YOLOv8 CoreML export.""" + mlmodel = self.args.format.lower() == "mlmodel" # legacy *.mlmodel export format requested + check_requirements("coremltools>=6.0,<=6.2" if mlmodel else "coremltools>=7.0") + import coremltools as ct # noqa + + LOGGER.info(f"\n{prefix} starting export with coremltools {ct.__version__}...") + assert not WINDOWS, "CoreML export is not supported on Windows, please run on macOS or Linux." + f = self.file.with_suffix(".mlmodel" if mlmodel else ".mlpackage") + if f.is_dir(): + shutil.rmtree(f) + + bias = [0.0, 0.0, 0.0] + scale = 1 / 255 + classifier_config = None + if self.model.task == "classify": + classifier_config = ct.ClassifierConfig(list(self.model.names.values())) if self.args.nms else None + model = self.model + elif self.model.task == "detect": + model = IOSDetectModel(self.model, self.im) if self.args.nms else self.model + else: + if self.args.nms: + LOGGER.warning(f"{prefix} WARNING ⚠️ 'nms=True' is only available for Detect models like 'yolov8n.pt'.") + # TODO CoreML Segment and Pose model pipelining + model = self.model + + ts = torch.jit.trace(model.eval(), self.im, strict=False) # TorchScript model + ct_model = ct.convert( + ts, + inputs=[ct.ImageType("image", shape=self.im.shape, scale=scale, bias=bias)], + classifier_config=classifier_config, + convert_to="neuralnetwork" if mlmodel else "mlprogram", + ) + bits, mode = (8, "kmeans") if self.args.int8 else (16, "linear") if self.args.half else (32, None) + if bits < 32: + if "kmeans" in mode: + check_requirements("scikit-learn") # scikit-learn package required for k-means quantization + if mlmodel: + ct_model = ct.models.neural_network.quantization_utils.quantize_weights(ct_model, bits, mode) + elif bits == 8: # mlprogram already quantized to FP16 + import coremltools.optimize.coreml as cto + + op_config = cto.OpPalettizerConfig(mode="kmeans", nbits=bits, weight_threshold=512) + config = cto.OptimizationConfig(global_config=op_config) + ct_model = cto.palettize_weights(ct_model, config=config) + if self.args.nms and self.model.task == "detect": + if mlmodel: + # coremltools<=6.2 NMS export requires Python<3.11 + check_version(PYTHON_VERSION, "<3.11", name="Python ", hard=True) + weights_dir = None + else: + ct_model.save(str(f)) # save otherwise weights_dir does not exist + weights_dir = str(f / "Data/com.apple.CoreML/weights") + ct_model = self._pipeline_coreml(ct_model, weights_dir=weights_dir) + + m = self.metadata # metadata dict + ct_model.short_description = m.pop("description") + ct_model.author = m.pop("author") + ct_model.license = m.pop("license") + ct_model.version = m.pop("version") + ct_model.user_defined_metadata.update({k: str(v) for k, v in m.items()}) + try: + ct_model.save(str(f)) # save *.mlpackage + except Exception as e: + LOGGER.warning( + f"{prefix} WARNING ⚠️ CoreML export to *.mlpackage failed ({e}), reverting to *.mlmodel export. " + f"Known coremltools Python 3.11 and Windows bugs https://github.com/apple/coremltools/issues/1928." + ) + f = f.with_suffix(".mlmodel") + ct_model.save(str(f)) + return f, ct_model + + @try_export + def export_engine(self, prefix=colorstr("TensorRT:")): + """YOLOv8 TensorRT export https://developer.nvidia.com/tensorrt.""" + assert self.im.device.type != "cpu", "export running on CPU but must be on GPU, i.e. use 'device=0'" + self.args.simplify = True + f_onnx, _ = self.export_onnx() # run before trt import https://github.com/ultralytics/ultralytics/issues/7016 + + try: + import tensorrt as trt # noqa + except ImportError: + if LINUX: + check_requirements("nvidia-tensorrt", cmds="-U --index-url https://pypi.ngc.nvidia.com") + import tensorrt as trt # noqa + check_version(trt.__version__, "7.0.0", hard=True) # require tensorrt>=7.0.0 + + LOGGER.info(f"\n{prefix} starting export with TensorRT {trt.__version__}...") + is_trt10 = int(trt.__version__.split(".")[0]) >= 10 # is TensorRT >= 10 + assert Path(f_onnx).exists(), f"failed to export ONNX file: {f_onnx}" + f = self.file.with_suffix(".engine") # TensorRT engine file + logger = trt.Logger(trt.Logger.INFO) + if self.args.verbose: + logger.min_severity = trt.Logger.Severity.VERBOSE + + builder = trt.Builder(logger) + config = builder.create_builder_config() + workspace = int(self.args.workspace * (1 << 30)) + if is_trt10: + config.set_memory_pool_limit(trt.MemoryPoolType.WORKSPACE, workspace) + else: # TensorRT versions 7, 8 + config.max_workspace_size = workspace + flag = 1 << int(trt.NetworkDefinitionCreationFlag.EXPLICIT_BATCH) + network = builder.create_network(flag) + parser = trt.OnnxParser(network, logger) + if not parser.parse_from_file(f_onnx): + raise RuntimeError(f"failed to load ONNX file: {f_onnx}") + + inputs = [network.get_input(i) for i in range(network.num_inputs)] + outputs = [network.get_output(i) for i in range(network.num_outputs)] + for inp in inputs: + LOGGER.info(f'{prefix} input "{inp.name}" with shape{inp.shape} {inp.dtype}') + for out in outputs: + LOGGER.info(f'{prefix} output "{out.name}" with shape{out.shape} {out.dtype}') + + if self.args.dynamic: + shape = self.im.shape + if shape[0] <= 1: + LOGGER.warning(f"{prefix} WARNING ⚠️ 'dynamic=True' model requires max batch size, i.e. 'batch=16'") + profile = builder.create_optimization_profile() + min_shape = (1, shape[1], 32, 32) # minimum input shape + opt_shape = (max(1, shape[0] // 2), *shape[1:]) # optimal input shape + max_shape = (*shape[:2], *(max(1, self.args.workspace) * d for d in shape[2:])) # max input shape + for inp in inputs: + profile.set_shape(inp.name, min_shape, opt_shape, max_shape) + config.add_optimization_profile(profile) + + half = builder.platform_has_fast_fp16 and self.args.half + LOGGER.info(f"{prefix} building FP{16 if half else 32} engine as {f}") + if half: + config.set_flag(trt.BuilderFlag.FP16) + + # Free CUDA memory + del self.model + torch.cuda.empty_cache() + + # Write file + build = builder.build_serialized_network if is_trt10 else builder.build_engine + with build(network, config) as engine, open(f, "wb") as t: + # Metadata + meta = json.dumps(self.metadata) + t.write(len(meta).to_bytes(4, byteorder="little", signed=True)) + t.write(meta.encode()) + # Model + t.write(engine if is_trt10 else engine.serialize()) + + return f, None + + @try_export + def export_saved_model(self, prefix=colorstr("TensorFlow SavedModel:")): + """YOLOv8 TensorFlow SavedModel export.""" + cuda = torch.cuda.is_available() + try: + import tensorflow as tf # noqa + except ImportError: + suffix = "-macos" if MACOS else "-aarch64" if ARM64 else "" if cuda else "-cpu" + version = "" if ARM64 else "<=2.13.1" + check_requirements(f"tensorflow{suffix}{version}") + import tensorflow as tf # noqa + if ARM64: + check_requirements("cmake") # 'cmake' is needed to build onnxsim on aarch64 + check_requirements( + ( + "onnx>=1.12.0", + "onnx2tf>=1.15.4,<=1.17.5", + "sng4onnx>=1.0.1", + "onnxsim>=0.4.33", + "onnx_graphsurgeon>=0.3.26", + "tflite_support", + "flatbuffers>=23.5.26,<100", # update old 'flatbuffers' included inside tensorflow package + "onnxruntime-gpu" if cuda else "onnxruntime", + ), + cmds="--extra-index-url https://pypi.ngc.nvidia.com", + ) # onnx_graphsurgeon only on NVIDIA + + LOGGER.info(f"\n{prefix} starting export with tensorflow {tf.__version__}...") + check_version( + tf.__version__, + "<=2.13.1", + name="tensorflow", + verbose=True, + msg="https://github.com/ultralytics/ultralytics/issues/5161", + ) + import onnx2tf + + f = Path(str(self.file).replace(self.file.suffix, "_saved_model")) + if f.is_dir(): + shutil.rmtree(f) # delete output folder + + # Pre-download calibration file to fix https://github.com/PINTO0309/onnx2tf/issues/545 + onnx2tf_file = Path("calibration_image_sample_data_20x128x128x3_float32.npy") + if not onnx2tf_file.exists(): + attempt_download_asset(f"{onnx2tf_file}.zip", unzip=True, delete=True) + + # Export to ONNX + self.args.simplify = True + f_onnx, _ = self.export_onnx() + + # Export to TF + tmp_file = f / "tmp_tflite_int8_calibration_images.npy" # int8 calibration images file + np_data = None + if self.args.int8: + verbosity = "info" + if self.args.data: + # Generate calibration data for integer quantization + LOGGER.info(f"{prefix} collecting INT8 calibration images from 'data={self.args.data}'") + data = check_det_dataset(self.args.data) + dataset = YOLODataset(data["val"], data=data, imgsz=self.imgsz[0], augment=False) + images = [] + for i, batch in enumerate(dataset): + if i >= 100: # maximum number of calibration images + break + im = batch["img"].permute(1, 2, 0)[None] # list to nparray, CHW to BHWC + images.append(im) + f.mkdir() + images = torch.cat(images, 0).float() + # mean = images.view(-1, 3).mean(0) # imagenet mean [123.675, 116.28, 103.53] + # std = images.view(-1, 3).std(0) # imagenet std [58.395, 57.12, 57.375] + np.save(str(tmp_file), images.numpy()) # BHWC + np_data = [["images", tmp_file, [[[[0, 0, 0]]]], [[[[255, 255, 255]]]]]] + else: + verbosity = "error" + + LOGGER.info(f"{prefix} starting TFLite export with onnx2tf {onnx2tf.__version__}...") + onnx2tf.convert( + input_onnx_file_path=f_onnx, + output_folder_path=str(f), + not_use_onnxsim=True, + verbosity=verbosity, + output_integer_quantized_tflite=self.args.int8, + quant_type="per-tensor", # "per-tensor" (faster) or "per-channel" (slower but more accurate) + custom_input_op_name_np_data_path=np_data, + ) + yaml_save(f / "metadata.yaml", self.metadata) # add metadata.yaml + + # Remove/rename TFLite models + if self.args.int8: + tmp_file.unlink(missing_ok=True) + for file in f.rglob("*_dynamic_range_quant.tflite"): + file.rename(file.with_name(file.stem.replace("_dynamic_range_quant", "_int8") + file.suffix)) + for file in f.rglob("*_integer_quant_with_int16_act.tflite"): + file.unlink() # delete extra fp16 activation TFLite files + + # Add TFLite metadata + for file in f.rglob("*.tflite"): + f.unlink() if "quant_with_int16_act.tflite" in str(f) else self._add_tflite_metadata(file) + + return str(f), tf.saved_model.load(f, tags=None, options=None) # load saved_model as Keras model + + @try_export + def export_pb(self, keras_model, prefix=colorstr("TensorFlow GraphDef:")): + """YOLOv8 TensorFlow GraphDef *.pb export https://github.com/leimao/Frozen_Graph_TensorFlow.""" + import tensorflow as tf # noqa + from tensorflow.python.framework.convert_to_constants import convert_variables_to_constants_v2 # noqa + + LOGGER.info(f"\n{prefix} starting export with tensorflow {tf.__version__}...") + f = self.file.with_suffix(".pb") + + m = tf.function(lambda x: keras_model(x)) # full model + m = m.get_concrete_function(tf.TensorSpec(keras_model.inputs[0].shape, keras_model.inputs[0].dtype)) + frozen_func = convert_variables_to_constants_v2(m) + frozen_func.graph.as_graph_def() + tf.io.write_graph(graph_or_graph_def=frozen_func.graph, logdir=str(f.parent), name=f.name, as_text=False) + return f, None + + @try_export + def export_tflite(self, keras_model, nms, agnostic_nms, prefix=colorstr("TensorFlow Lite:")): + """YOLOv8 TensorFlow Lite export.""" + import tensorflow as tf # noqa + + LOGGER.info(f"\n{prefix} starting export with tensorflow {tf.__version__}...") + saved_model = Path(str(self.file).replace(self.file.suffix, "_saved_model")) + if self.args.int8: + f = saved_model / f"{self.file.stem}_int8.tflite" # fp32 in/out + elif self.args.half: + f = saved_model / f"{self.file.stem}_float16.tflite" # fp32 in/out + else: + f = saved_model / f"{self.file.stem}_float32.tflite" + return str(f), None + + @try_export + def export_edgetpu(self, tflite_model="", prefix=colorstr("Edge TPU:")): + """YOLOv8 Edge TPU export https://coral.ai/docs/edgetpu/models-intro/.""" + LOGGER.warning(f"{prefix} WARNING ⚠️ Edge TPU known bug https://github.com/ultralytics/ultralytics/issues/1185") + + cmd = "edgetpu_compiler --version" + help_url = "https://coral.ai/docs/edgetpu/compiler/" + assert LINUX, f"export only supported on Linux. See {help_url}" + if subprocess.run(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, shell=True).returncode != 0: + LOGGER.info(f"\n{prefix} export requires Edge TPU compiler. Attempting install from {help_url}") + sudo = subprocess.run("sudo --version >/dev/null", shell=True).returncode == 0 # sudo installed on system + for c in ( + "curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -", + 'echo "deb https://packages.cloud.google.com/apt coral-edgetpu-stable main" | ' + "sudo tee /etc/apt/sources.list.d/coral-edgetpu.list", + "sudo apt-get update", + "sudo apt-get install edgetpu-compiler", + ): + subprocess.run(c if sudo else c.replace("sudo ", ""), shell=True, check=True) + ver = subprocess.run(cmd, shell=True, capture_output=True, check=True).stdout.decode().split()[-1] + + LOGGER.info(f"\n{prefix} starting export with Edge TPU compiler {ver}...") + f = str(tflite_model).replace(".tflite", "_edgetpu.tflite") # Edge TPU model + + cmd = f'edgetpu_compiler -s -d -k 10 --out_dir "{Path(f).parent}" "{tflite_model}"' + LOGGER.info(f"{prefix} running '{cmd}'") + subprocess.run(cmd, shell=True) + self._add_tflite_metadata(f) + return f, None + + @try_export + def export_tfjs(self, prefix=colorstr("TensorFlow.js:")): + """YOLOv8 TensorFlow.js export.""" + check_requirements("tensorflowjs") + if ARM64: + # Fix error: `np.object` was a deprecated alias for the builtin `object` when exporting to TF.js on ARM64 + check_requirements("numpy==1.23.5") + import tensorflow as tf + import tensorflowjs as tfjs # noqa + + LOGGER.info(f"\n{prefix} starting export with tensorflowjs {tfjs.__version__}...") + f = str(self.file).replace(self.file.suffix, "_web_model") # js dir + f_pb = str(self.file.with_suffix(".pb")) # *.pb path + + gd = tf.Graph().as_graph_def() # TF GraphDef + with open(f_pb, "rb") as file: + gd.ParseFromString(file.read()) + outputs = ",".join(gd_outputs(gd)) + LOGGER.info(f"\n{prefix} output node names: {outputs}") + + quantization = "--quantize_float16" if self.args.half else "--quantize_uint8" if self.args.int8 else "" + with spaces_in_path(f_pb) as fpb_, spaces_in_path(f) as f_: # exporter can not handle spaces in path + cmd = ( + "tensorflowjs_converter " + f'--input_format=tf_frozen_model {quantization} --output_node_names={outputs} "{fpb_}" "{f_}"' + ) + LOGGER.info(f"{prefix} running '{cmd}'") + subprocess.run(cmd, shell=True) + + if " " in f: + LOGGER.warning(f"{prefix} WARNING ⚠️ your model may not work correctly with spaces in path '{f}'.") + + # f_json = Path(f) / 'model.json' # *.json path + # with open(f_json, 'w') as j: # sort JSON Identity_* in ascending order + # subst = re.sub( + # r'{"outputs": {"Identity.?.?": {"name": "Identity.?.?"}, ' + # r'"Identity.?.?": {"name": "Identity.?.?"}, ' + # r'"Identity.?.?": {"name": "Identity.?.?"}, ' + # r'"Identity.?.?": {"name": "Identity.?.?"}}}', + # r'{"outputs": {"Identity": {"name": "Identity"}, ' + # r'"Identity_1": {"name": "Identity_1"}, ' + # r'"Identity_2": {"name": "Identity_2"}, ' + # r'"Identity_3": {"name": "Identity_3"}}}', + # f_json.read_text(), + # ) + # j.write(subst) + yaml_save(Path(f) / "metadata.yaml", self.metadata) # add metadata.yaml + return f, None + + def _add_tflite_metadata(self, file): + """Add metadata to *.tflite models per https://www.tensorflow.org/lite/models/convert/metadata.""" + from tflite_support import flatbuffers # noqa + from tflite_support import metadata as _metadata # noqa + from tflite_support import metadata_schema_py_generated as _metadata_fb # noqa + + # Create model info + model_meta = _metadata_fb.ModelMetadataT() + model_meta.name = self.metadata["description"] + model_meta.version = self.metadata["version"] + model_meta.author = self.metadata["author"] + model_meta.license = self.metadata["license"] + + # Label file + tmp_file = Path(file).parent / "temp_meta.txt" + with open(tmp_file, "w") as f: + f.write(str(self.metadata)) + + label_file = _metadata_fb.AssociatedFileT() + label_file.name = tmp_file.name + label_file.type = _metadata_fb.AssociatedFileType.TENSOR_AXIS_LABELS + + # Create input info + input_meta = _metadata_fb.TensorMetadataT() + input_meta.name = "image" + input_meta.description = "Input image to be detected." + input_meta.content = _metadata_fb.ContentT() + input_meta.content.contentProperties = _metadata_fb.ImagePropertiesT() + input_meta.content.contentProperties.colorSpace = _metadata_fb.ColorSpaceType.RGB + input_meta.content.contentPropertiesType = _metadata_fb.ContentProperties.ImageProperties + + # Create output info + output1 = _metadata_fb.TensorMetadataT() + output1.name = "output" + output1.description = "Coordinates of detected objects, class labels, and confidence score" + output1.associatedFiles = [label_file] + if self.model.task == "segment": + output2 = _metadata_fb.TensorMetadataT() + output2.name = "output" + output2.description = "Mask protos" + output2.associatedFiles = [label_file] + + # Create subgraph info + subgraph = _metadata_fb.SubGraphMetadataT() + subgraph.inputTensorMetadata = [input_meta] + subgraph.outputTensorMetadata = [output1, output2] if self.model.task == "segment" else [output1] + model_meta.subgraphMetadata = [subgraph] + + b = flatbuffers.Builder(0) + b.Finish(model_meta.Pack(b), _metadata.MetadataPopulator.METADATA_FILE_IDENTIFIER) + metadata_buf = b.Output() + + populator = _metadata.MetadataPopulator.with_model_file(str(file)) + populator.load_metadata_buffer(metadata_buf) + populator.load_associated_files([str(tmp_file)]) + populator.populate() + tmp_file.unlink() + + def _pipeline_coreml(self, model, weights_dir=None, prefix=colorstr("CoreML Pipeline:")): + """YOLOv8 CoreML pipeline.""" + import coremltools as ct # noqa + + LOGGER.info(f"{prefix} starting pipeline with coremltools {ct.__version__}...") + _, _, h, w = list(self.im.shape) # BCHW + + # Output shapes + spec = model.get_spec() + out0, out1 = iter(spec.description.output) + if MACOS: + from PIL import Image + + img = Image.new("RGB", (w, h)) # w=192, h=320 + out = model.predict({"image": img}) + out0_shape = out[out0.name].shape # (3780, 80) + out1_shape = out[out1.name].shape # (3780, 4) + else: # linux and windows can not run model.predict(), get sizes from PyTorch model output y + out0_shape = self.output_shape[2], self.output_shape[1] - 4 # (3780, 80) + out1_shape = self.output_shape[2], 4 # (3780, 4) + + # Checks + names = self.metadata["names"] + nx, ny = spec.description.input[0].type.imageType.width, spec.description.input[0].type.imageType.height + _, nc = out0_shape # number of anchors, number of classes + # _, nc = out0.type.multiArrayType.shape + assert len(names) == nc, f"{len(names)} names found for nc={nc}" # check + + # Define output shapes (missing) + out0.type.multiArrayType.shape[:] = out0_shape # (3780, 80) + out1.type.multiArrayType.shape[:] = out1_shape # (3780, 4) + # spec.neuralNetwork.preprocessing[0].featureName = '0' + + # Flexible input shapes + # from coremltools.models.neural_network import flexible_shape_utils + # s = [] # shapes + # s.append(flexible_shape_utils.NeuralNetworkImageSize(320, 192)) + # s.append(flexible_shape_utils.NeuralNetworkImageSize(640, 384)) # (height, width) + # flexible_shape_utils.add_enumerated_image_sizes(spec, feature_name='image', sizes=s) + # r = flexible_shape_utils.NeuralNetworkImageSizeRange() # shape ranges + # r.add_height_range((192, 640)) + # r.add_width_range((192, 640)) + # flexible_shape_utils.update_image_size_range(spec, feature_name='image', size_range=r) + + # Print + # print(spec.description) + + # Model from spec + model = ct.models.MLModel(spec, weights_dir=weights_dir) + + # 3. Create NMS protobuf + nms_spec = ct.proto.Model_pb2.Model() + nms_spec.specificationVersion = 5 + for i in range(2): + decoder_output = model._spec.description.output[i].SerializeToString() + nms_spec.description.input.add() + nms_spec.description.input[i].ParseFromString(decoder_output) + nms_spec.description.output.add() + nms_spec.description.output[i].ParseFromString(decoder_output) + + nms_spec.description.output[0].name = "confidence" + nms_spec.description.output[1].name = "coordinates" + + output_sizes = [nc, 4] + for i in range(2): + ma_type = nms_spec.description.output[i].type.multiArrayType + ma_type.shapeRange.sizeRanges.add() + ma_type.shapeRange.sizeRanges[0].lowerBound = 0 + ma_type.shapeRange.sizeRanges[0].upperBound = -1 + ma_type.shapeRange.sizeRanges.add() + ma_type.shapeRange.sizeRanges[1].lowerBound = output_sizes[i] + ma_type.shapeRange.sizeRanges[1].upperBound = output_sizes[i] + del ma_type.shape[:] + + nms = nms_spec.nonMaximumSuppression + nms.confidenceInputFeatureName = out0.name # 1x507x80 + nms.coordinatesInputFeatureName = out1.name # 1x507x4 + nms.confidenceOutputFeatureName = "confidence" + nms.coordinatesOutputFeatureName = "coordinates" + nms.iouThresholdInputFeatureName = "iouThreshold" + nms.confidenceThresholdInputFeatureName = "confidenceThreshold" + nms.iouThreshold = 0.45 + nms.confidenceThreshold = 0.25 + nms.pickTop.perClass = True + nms.stringClassLabels.vector.extend(names.values()) + nms_model = ct.models.MLModel(nms_spec) + + # 4. Pipeline models together + pipeline = ct.models.pipeline.Pipeline( + input_features=[ + ("image", ct.models.datatypes.Array(3, ny, nx)), + ("iouThreshold", ct.models.datatypes.Double()), + ("confidenceThreshold", ct.models.datatypes.Double()), + ], + output_features=["confidence", "coordinates"], + ) + pipeline.add_model(model) + pipeline.add_model(nms_model) + + # Correct datatypes + pipeline.spec.description.input[0].ParseFromString(model._spec.description.input[0].SerializeToString()) + pipeline.spec.description.output[0].ParseFromString(nms_model._spec.description.output[0].SerializeToString()) + pipeline.spec.description.output[1].ParseFromString(nms_model._spec.description.output[1].SerializeToString()) + + # Update metadata + pipeline.spec.specificationVersion = 5 + pipeline.spec.description.metadata.userDefined.update( + {"IoU threshold": str(nms.iouThreshold), "Confidence threshold": str(nms.confidenceThreshold)} + ) + + # Save the model + model = ct.models.MLModel(pipeline.spec, weights_dir=weights_dir) + model.input_description["image"] = "Input image" + model.input_description["iouThreshold"] = f"(optional) IoU threshold override (default: {nms.iouThreshold})" + model.input_description["confidenceThreshold"] = ( + f"(optional) Confidence threshold override (default: {nms.confidenceThreshold})" + ) + model.output_description["confidence"] = 'Boxes × Class confidence (see user-defined metadata "classes")' + model.output_description["coordinates"] = "Boxes × [x, y, width, height] (relative to image size)" + LOGGER.info(f"{prefix} pipeline success") + return model + + def add_callback(self, event: str, callback): + """Appends the given callback.""" + self.callbacks[event].append(callback) + + def run_callbacks(self, event: str): + """Execute all callbacks for a given event.""" + for callback in self.callbacks.get(event, []): + callback(self) + + +class IOSDetectModel(torch.nn.Module): + """Wrap an Ultralytics YOLO model for Apple iOS CoreML export.""" + + def __init__(self, model, im): + """Initialize the IOSDetectModel class with a YOLO model and example image.""" + super().__init__() + _, _, h, w = im.shape # batch, channel, height, width + self.model = model + self.nc = len(model.names) # number of classes + if w == h: + self.normalize = 1.0 / w # scalar + else: + self.normalize = torch.tensor([1.0 / w, 1.0 / h, 1.0 / w, 1.0 / h]) # broadcast (slower, smaller) + + def forward(self, x): + """Normalize predictions of object detection model with input size-dependent factors.""" + xywh, cls = self.model(x)[0].transpose(0, 1).split((4, self.nc), 1) + return cls, xywh * self.normalize # confidence (3780, 80), coordinates (3780, 4) diff --git a/ultralytics/engine/model.py b/ultralytics/engine/model.py new file mode 100644 index 0000000..677361e --- /dev/null +++ b/ultralytics/engine/model.py @@ -0,0 +1,845 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import inspect +from pathlib import Path +from typing import Union + +import numpy as np +import torch + +from ultralytics.cfg import TASK2DATA, get_cfg, get_save_dir +from ultralytics.hub.utils import HUB_WEB_ROOT +from ultralytics.nn.tasks import attempt_load_one_weight, guess_model_task, nn, yaml_model_load +from ultralytics.utils import ( + ARGV, + ASSETS, + DEFAULT_CFG_DICT, + LOGGER, + RANK, + SETTINGS, + callbacks, + checks, + emojis, + yaml_load, +) + + +class Model(nn.Module): + """ + A base class for implementing YOLO models, unifying APIs across different model types. + + This class provides a common interface for various operations related to YOLO models, such as training, + validation, prediction, exporting, and benchmarking. It handles different types of models, including those + loaded from local files, Ultralytics HUB, or Triton Server. The class is designed to be flexible and + extendable for different tasks and model configurations. + + Args: + model (Union[str, Path], optional): Path or name of the model to load or create. This can be a local file + path, a model name from Ultralytics HUB, or a Triton Server model. Defaults to 'yolov8n.pt'. + task (Any, optional): The task type associated with the YOLO model. This can be used to specify the model's + application domain, such as object detection, segmentation, etc. Defaults to None. + verbose (bool, optional): If True, enables verbose output during the model's operations. Defaults to False. + + Attributes: + callbacks (dict): A dictionary of callback functions for various events during model operations. + predictor (BasePredictor): The predictor object used for making predictions. + model (nn.Module): The underlying PyTorch model. + trainer (BaseTrainer): The trainer object used for training the model. + ckpt (dict): The checkpoint data if the model is loaded from a *.pt file. + cfg (str): The configuration of the model if loaded from a *.yaml file. + ckpt_path (str): The path to the checkpoint file. + overrides (dict): A dictionary of overrides for model configuration. + metrics (dict): The latest training/validation metrics. + session (HUBTrainingSession): The Ultralytics HUB session, if applicable. + task (str): The type of task the model is intended for. + model_name (str): The name of the model. + + Methods: + __call__: Alias for the predict method, enabling the model instance to be callable. + _new: Initializes a new model based on a configuration file. + _load: Loads a model from a checkpoint file. + _check_is_pytorch_model: Ensures that the model is a PyTorch model. + reset_weights: Resets the model's weights to their initial state. + load: Loads model weights from a specified file. + save: Saves the current state of the model to a file. + info: Logs or returns information about the model. + fuse: Fuses Conv2d and BatchNorm2d layers for optimized inference. + predict: Performs object detection predictions. + track: Performs object tracking. + val: Validates the model on a dataset. + benchmark: Benchmarks the model on various export formats. + export: Exports the model to different formats. + train: Trains the model on a dataset. + tune: Performs hyperparameter tuning. + _apply: Applies a function to the model's tensors. + add_callback: Adds a callback function for an event. + clear_callback: Clears all callbacks for an event. + reset_callbacks: Resets all callbacks to their default functions. + _get_hub_session: Retrieves or creates an Ultralytics HUB session. + is_triton_model: Checks if a model is a Triton Server model. + is_hub_model: Checks if a model is an Ultralytics HUB model. + _reset_ckpt_args: Resets checkpoint arguments when loading a PyTorch model. + _smart_load: Loads the appropriate module based on the model task. + task_map: Provides a mapping from model tasks to corresponding classes. + + Raises: + FileNotFoundError: If the specified model file does not exist or is inaccessible. + ValueError: If the model file or configuration is invalid or unsupported. + ImportError: If required dependencies for specific model types (like HUB SDK) are not installed. + TypeError: If the model is not a PyTorch model when required. + AttributeError: If required attributes or methods are not implemented or available. + NotImplementedError: If a specific model task or mode is not supported. + """ + + def __init__( + self, + model: Union[str, Path] = "yolov8n.pt", + task: str = None, + verbose: bool = False, + ) -> None: + """ + Initializes a new instance of the YOLO model class. + + This constructor sets up the model based on the provided model path or name. It handles various types of model + sources, including local files, Ultralytics HUB models, and Triton Server models. The method initializes several + important attributes of the model and prepares it for operations like training, prediction, or export. + + Args: + model (Union[str, Path], optional): The path or model file to load or create. This can be a local + file path, a model name from Ultralytics HUB, or a Triton Server model. Defaults to 'yolov8n.pt'. + task (Any, optional): The task type associated with the YOLO model, specifying its application domain. + Defaults to None. + verbose (bool, optional): If True, enables verbose output during the model's initialization and subsequent + operations. Defaults to False. + + Raises: + FileNotFoundError: If the specified model file does not exist or is inaccessible. + ValueError: If the model file or configuration is invalid or unsupported. + ImportError: If required dependencies for specific model types (like HUB SDK) are not installed. + """ + super().__init__() + self.callbacks = callbacks.get_default_callbacks() + self.predictor = None # reuse predictor + self.model = None # model object + self.trainer = None # trainer object + self.ckpt = None # if loaded from *.pt + self.cfg = None # if loaded from *.yaml + self.ckpt_path = None + self.overrides = {} # overrides for trainer object + self.metrics = None # validation/training metrics + self.session = None # HUB session + self.task = task # task type + model = str(model).strip() + + # Check if Ultralytics HUB model from https://hub.ultralytics.com + if self.is_hub_model(model): + # Fetch model from HUB + checks.check_requirements("hub-sdk>=0.0.6") + self.session = self._get_hub_session(model) + model = self.session.model_file + + # Check if Triton Server model + elif self.is_triton_model(model): + self.model_name = self.model = model + self.task = task + return + + # Load or create new YOLO model + if Path(model).suffix in {".yaml", ".yml"}: + self._new(model, task=task, verbose=verbose) + else: + self._load(model, task=task) + + def __call__( + self, + source: Union[str, Path, int, list, tuple, np.ndarray, torch.Tensor] = None, + stream: bool = False, + **kwargs, + ) -> list: + """ + An alias for the predict method, enabling the model instance to be callable. + + This method simplifies the process of making predictions by allowing the model instance to be called directly + with the required arguments for prediction. + + Args: + source (str | Path | int | PIL.Image | np.ndarray, optional): The source of the image for making + predictions. Accepts various types, including file paths, URLs, PIL images, and numpy arrays. + Defaults to None. + stream (bool, optional): If True, treats the input source as a continuous stream for predictions. + Defaults to False. + **kwargs (any): Additional keyword arguments for configuring the prediction process. + + Returns: + (List[ultralytics.engine.results.Results]): A list of prediction results, encapsulated in the Results class. + """ + return self.predict(source, stream, **kwargs) + + @staticmethod + def _get_hub_session(model: str): + """Creates a session for Hub Training.""" + from ultralytics.hub.session import HUBTrainingSession + + session = HUBTrainingSession(model) + return session if session.client.authenticated else None + + @staticmethod + def is_triton_model(model: str) -> bool: + """Is model a Triton Server URL string, i.e. :////""" + from urllib.parse import urlsplit + + url = urlsplit(model) + return url.netloc and url.path and url.scheme in {"http", "grpc"} + + @staticmethod + def is_hub_model(model: str) -> bool: + """Check if the provided model is a HUB model.""" + return any( + ( + model.startswith(f"{HUB_WEB_ROOT}/models/"), # i.e. https://hub.ultralytics.com/models/MODEL_ID + [len(x) for x in model.split("_")] == [42, 20], # APIKEY_MODEL + len(model) == 20 and not Path(model).exists() and all(x not in model for x in "./\\"), # MODEL + ) + ) + + def _new(self, cfg: str, task=None, model=None, verbose=False) -> None: + """ + Initializes a new model and infers the task type from the model definitions. + + Args: + cfg (str): model configuration file + task (str | None): model task + model (BaseModel): Customized model. + verbose (bool): display model info on load + """ + cfg_dict = yaml_model_load(cfg) + self.cfg = cfg + self.task = task or guess_model_task(cfg_dict) + self.model = (model or self._smart_load("model"))(cfg_dict, verbose=verbose and RANK == -1) # build model + self.overrides["model"] = self.cfg + self.overrides["task"] = self.task + + # Below added to allow export from YAMLs + self.model.args = {**DEFAULT_CFG_DICT, **self.overrides} # combine default and model args (prefer model args) + self.model.task = self.task + self.model_name = cfg + + def _load(self, weights: str, task=None) -> None: + """ + Initializes a new model and infers the task type from the model head. + + Args: + weights (str): model checkpoint to be loaded + task (str | None): model task + """ + if weights.lower().startswith(("https://", "http://", "rtsp://", "rtmp://", "tcp://")): + weights = checks.check_file(weights) # automatically download and return local filename + weights = checks.check_model_file_from_stem(weights) # add suffix, i.e. yolov8n -> yolov8n.pt + + if Path(weights).suffix == ".pt": + self.model, self.ckpt = attempt_load_one_weight(weights) + self.task = self.model.args["task"] + self.overrides = self.model.args = self._reset_ckpt_args(self.model.args) + self.ckpt_path = self.model.pt_path + else: + weights = checks.check_file(weights) # runs in all cases, not redundant with above call + self.model, self.ckpt = weights, None + self.task = task or guess_model_task(weights) + self.ckpt_path = weights + self.overrides["model"] = weights + self.overrides["task"] = self.task + self.model_name = weights + + def _check_is_pytorch_model(self) -> None: + """Raises TypeError is model is not a PyTorch model.""" + pt_str = isinstance(self.model, (str, Path)) and Path(self.model).suffix == ".pt" + pt_module = isinstance(self.model, nn.Module) + if not (pt_module or pt_str): + raise TypeError( + f"model='{self.model}' should be a *.pt PyTorch model to run this method, but is a different format. " + f"PyTorch models can train, val, predict and export, i.e. 'model.train(data=...)', but exported " + f"formats like ONNX, TensorRT etc. only support 'predict' and 'val' modes, " + f"i.e. 'yolo predict model=yolov8n.onnx'.\nTo run CUDA or MPS inference please pass the device " + f"argument directly in your inference command, i.e. 'model.predict(source=..., device=0)'" + ) + + def reset_weights(self) -> "Model": + """ + Resets the model parameters to randomly initialized values, effectively discarding all training information. + + This method iterates through all modules in the model and resets their parameters if they have a + 'reset_parameters' method. It also ensures that all parameters have 'requires_grad' set to True, enabling them + to be updated during training. + + Returns: + self (ultralytics.engine.model.Model): The instance of the class with reset weights. + + Raises: + AssertionError: If the model is not a PyTorch model. + """ + self._check_is_pytorch_model() + for m in self.model.modules(): + if hasattr(m, "reset_parameters"): + m.reset_parameters() + for p in self.model.parameters(): + p.requires_grad = True + return self + + def load(self, weights: Union[str, Path] = "yolov8n.pt") -> "Model": + """ + Loads parameters from the specified weights file into the model. + + This method supports loading weights from a file or directly from a weights object. It matches parameters by + name and shape and transfers them to the model. + + Args: + weights (str | Path): Path to the weights file or a weights object. Defaults to 'yolov8n.pt'. + + Returns: + self (ultralytics.engine.model.Model): The instance of the class with loaded weights. + + Raises: + AssertionError: If the model is not a PyTorch model. + """ + self._check_is_pytorch_model() + if isinstance(weights, (str, Path)): + weights, self.ckpt = attempt_load_one_weight(weights) + self.model.load(weights) + return self + + def save(self, filename: Union[str, Path] = "saved_model.pt", use_dill=True) -> None: + """ + Saves the current model state to a file. + + This method exports the model's checkpoint (ckpt) to the specified filename. + + Args: + filename (str | Path): The name of the file to save the model to. Defaults to 'saved_model.pt'. + use_dill (bool): Whether to try using dill for serialization if available. Defaults to True. + + Raises: + AssertionError: If the model is not a PyTorch model. + """ + self._check_is_pytorch_model() + from datetime import datetime + + from ultralytics import __version__ + + updates = { + "date": datetime.now().isoformat(), + "version": __version__, + "license": "AGPL-3.0 License (https://ultralytics.com/license)", + "docs": "https://docs.ultralytics.com", + } + torch.save({**self.ckpt, **updates}, filename, use_dill=use_dill) + + def info(self, detailed: bool = False, verbose: bool = True): + """ + Logs or returns model information. + + This method provides an overview or detailed information about the model, depending on the arguments passed. + It can control the verbosity of the output. + + Args: + detailed (bool): If True, shows detailed information about the model. Defaults to False. + verbose (bool): If True, prints the information. If False, returns the information. Defaults to True. + + Returns: + (list): Various types of information about the model, depending on the 'detailed' and 'verbose' parameters. + + Raises: + AssertionError: If the model is not a PyTorch model. + """ + self._check_is_pytorch_model() + return self.model.info(detailed=detailed, verbose=verbose) + + def fuse(self): + """ + Fuses Conv2d and BatchNorm2d layers in the model. + + This method optimizes the model by fusing Conv2d and BatchNorm2d layers, which can improve inference speed. + + Raises: + AssertionError: If the model is not a PyTorch model. + """ + self._check_is_pytorch_model() + self.model.fuse() + + def embed( + self, + source: Union[str, Path, int, list, tuple, np.ndarray, torch.Tensor] = None, + stream: bool = False, + **kwargs, + ) -> list: + """ + Generates image embeddings based on the provided source. + + This method is a wrapper around the 'predict()' method, focusing on generating embeddings from an image source. + It allows customization of the embedding process through various keyword arguments. + + Args: + source (str | int | PIL.Image | np.ndarray): The source of the image for generating embeddings. + The source can be a file path, URL, PIL image, numpy array, etc. Defaults to None. + stream (bool): If True, predictions are streamed. Defaults to False. + **kwargs (any): Additional keyword arguments for configuring the embedding process. + + Returns: + (List[torch.Tensor]): A list containing the image embeddings. + + Raises: + AssertionError: If the model is not a PyTorch model. + """ + if not kwargs.get("embed"): + kwargs["embed"] = [len(self.model.model) - 2] # embed second-to-last layer if no indices passed + return self.predict(source, stream, **kwargs) + + def predict( + self, + source: Union[str, Path, int, list, tuple, np.ndarray, torch.Tensor] = None, + stream: bool = False, + predictor=None, + **kwargs, + ) -> list: + """ + Performs predictions on the given image source using the YOLO model. + + This method facilitates the prediction process, allowing various configurations through keyword arguments. + It supports predictions with custom predictors or the default predictor method. The method handles different + types of image sources and can operate in a streaming mode. It also provides support for SAM-type models + through 'prompts'. + + The method sets up a new predictor if not already present and updates its arguments with each call. + It also issues a warning and uses default assets if the 'source' is not provided. The method determines if it + is being called from the command line interface and adjusts its behavior accordingly, including setting defaults + for confidence threshold and saving behavior. + + Args: + source (str | int | PIL.Image | np.ndarray, optional): The source of the image for making predictions. + Accepts various types, including file paths, URLs, PIL images, and numpy arrays. Defaults to ASSETS. + stream (bool, optional): Treats the input source as a continuous stream for predictions. Defaults to False. + predictor (BasePredictor, optional): An instance of a custom predictor class for making predictions. + If None, the method uses a default predictor. Defaults to None. + **kwargs (any): Additional keyword arguments for configuring the prediction process. These arguments allow + for further customization of the prediction behavior. + + Returns: + (List[ultralytics.engine.results.Results]): A list of prediction results, encapsulated in the Results class. + + Raises: + AttributeError: If the predictor is not properly set up. + """ + if source is None: + source = ASSETS + LOGGER.warning(f"WARNING ⚠️ 'source' is missing. Using 'source={source}'.") + + is_cli = (ARGV[0].endswith("yolo") or ARGV[0].endswith("ultralytics")) and any( + x in ARGV for x in ("predict", "track", "mode=predict", "mode=track") + ) + + custom = {"conf": 0.25, "batch": 1, "save": is_cli, "mode": "predict"} # method defaults + args = {**self.overrides, **custom, **kwargs} # highest priority args on the right + prompts = args.pop("prompts", None) # for SAM-type models + + if not self.predictor: + self.predictor = predictor or self._smart_load("predictor")(overrides=args, _callbacks=self.callbacks) + self.predictor.setup_model(model=self.model, verbose=is_cli) + else: # only update args if predictor is already setup + self.predictor.args = get_cfg(self.predictor.args, args) + if "project" in args or "name" in args: + self.predictor.save_dir = get_save_dir(self.predictor.args) + if prompts and hasattr(self.predictor, "set_prompts"): # for SAM-type models + self.predictor.set_prompts(prompts) + return self.predictor.predict_cli(source=source) if is_cli else self.predictor(source=source, stream=stream) + + def track( + self, + source: Union[str, Path, int, list, tuple, np.ndarray, torch.Tensor] = None, + stream: bool = False, + persist: bool = False, + **kwargs, + ) -> list: + """ + Conducts object tracking on the specified input source using the registered trackers. + + This method performs object tracking using the model's predictors and optionally registered trackers. It is + capable of handling different types of input sources such as file paths or video streams. The method supports + customization of the tracking process through various keyword arguments. It registers trackers if they are not + already present and optionally persists them based on the 'persist' flag. + + The method sets a default confidence threshold specifically for ByteTrack-based tracking, which requires low + confidence predictions as input. The tracking mode is explicitly set in the keyword arguments. + + Args: + source (str, optional): The input source for object tracking. It can be a file path, URL, or video stream. + stream (bool, optional): Treats the input source as a continuous video stream. Defaults to False. + persist (bool, optional): Persists the trackers between different calls to this method. Defaults to False. + **kwargs (any): Additional keyword arguments for configuring the tracking process. These arguments allow + for further customization of the tracking behavior. + + Returns: + (List[ultralytics.engine.results.Results]): A list of tracking results, encapsulated in the Results class. + + Raises: + AttributeError: If the predictor does not have registered trackers. + """ + if not hasattr(self.predictor, "trackers"): + from ultralytics.trackers import register_tracker + + register_tracker(self, persist) + kwargs["conf"] = kwargs.get("conf") or 0.1 # ByteTrack-based method needs low confidence predictions as input + kwargs["batch"] = kwargs.get("batch") or 1 # batch-size 1 for tracking in videos + kwargs["mode"] = "track" + return self.predict(source=source, stream=stream, **kwargs) + + def val( + self, + validator=None, + **kwargs, + ): + """ + Validates the model using a specified dataset and validation configuration. + + This method facilitates the model validation process, allowing for a range of customization through various + settings and configurations. It supports validation with a custom validator or the default validation approach. + The method combines default configurations, method-specific defaults, and user-provided arguments to configure + the validation process. After validation, it updates the model's metrics with the results obtained from the + validator. + + The method supports various arguments that allow customization of the validation process. For a comprehensive + list of all configurable options, users should refer to the 'configuration' section in the documentation. + + Args: + validator (BaseValidator, optional): An instance of a custom validator class for validating the model. If + None, the method uses a default validator. Defaults to None. + **kwargs (any): Arbitrary keyword arguments representing the validation configuration. These arguments are + used to customize various aspects of the validation process. + + Returns: + (dict): Validation metrics obtained from the validation process. + + Raises: + AssertionError: If the model is not a PyTorch model. + """ + custom = {"rect": True} # method defaults + args = {**self.overrides, **custom, **kwargs, "mode": "val"} # highest priority args on the right + + validator = (validator or self._smart_load("validator"))(args=args, _callbacks=self.callbacks) + validator(model=self.model) + self.metrics = validator.metrics + return validator.metrics + + def benchmark( + self, + **kwargs, + ): + """ + Benchmarks the model across various export formats to evaluate performance. + + This method assesses the model's performance in different export formats, such as ONNX, TorchScript, etc. + It uses the 'benchmark' function from the ultralytics.utils.benchmarks module. The benchmarking is configured + using a combination of default configuration values, model-specific arguments, method-specific defaults, and + any additional user-provided keyword arguments. + + The method supports various arguments that allow customization of the benchmarking process, such as dataset + choice, image size, precision modes, device selection, and verbosity. For a comprehensive list of all + configurable options, users should refer to the 'configuration' section in the documentation. + + Args: + **kwargs (any): Arbitrary keyword arguments to customize the benchmarking process. These are combined with + default configurations, model-specific arguments, and method defaults. + + Returns: + (dict): A dictionary containing the results of the benchmarking process. + + Raises: + AssertionError: If the model is not a PyTorch model. + """ + self._check_is_pytorch_model() + from ultralytics.utils.benchmarks import benchmark + + custom = {"verbose": False} # method defaults + args = {**DEFAULT_CFG_DICT, **self.model.args, **custom, **kwargs, "mode": "benchmark"} + return benchmark( + model=self, + data=kwargs.get("data"), # if no 'data' argument passed set data=None for default datasets + imgsz=args["imgsz"], + half=args["half"], + int8=args["int8"], + device=args["device"], + verbose=kwargs.get("verbose"), + ) + + def export( + self, + **kwargs, + ): + """ + Exports the model to a different format suitable for deployment. + + This method facilitates the export of the model to various formats (e.g., ONNX, TorchScript) for deployment + purposes. It uses the 'Exporter' class for the export process, combining model-specific overrides, method + defaults, and any additional arguments provided. The combined arguments are used to configure export settings. + + The method supports a wide range of arguments to customize the export process. For a comprehensive list of all + possible arguments, refer to the 'configuration' section in the documentation. + + Args: + **kwargs (any): Arbitrary keyword arguments to customize the export process. These are combined with the + model's overrides and method defaults. + + Returns: + (object): The exported model in the specified format, or an object related to the export process. + + Raises: + AssertionError: If the model is not a PyTorch model. + """ + self._check_is_pytorch_model() + from .exporter import Exporter + + custom = {"imgsz": self.model.args["imgsz"], "batch": 1, "data": None, "verbose": False} # method defaults + args = {**self.overrides, **custom, **kwargs, "mode": "export"} # highest priority args on the right + return Exporter(overrides=args, _callbacks=self.callbacks)(model=self.model) + + def train( + self, + trainer=None, + **kwargs, + ): + """ + Trains the model using the specified dataset and training configuration. + + This method facilitates model training with a range of customizable settings and configurations. It supports + training with a custom trainer or the default training approach defined in the method. The method handles + different scenarios, such as resuming training from a checkpoint, integrating with Ultralytics HUB, and + updating model and configuration after training. + + When using Ultralytics HUB, if the session already has a loaded model, the method prioritizes HUB training + arguments and issues a warning if local arguments are provided. It checks for pip updates and combines default + configurations, method-specific defaults, and user-provided arguments to configure the training process. After + training, it updates the model and its configurations, and optionally attaches metrics. + + Args: + trainer (BaseTrainer, optional): An instance of a custom trainer class for training the model. If None, the + method uses a default trainer. Defaults to None. + **kwargs (any): Arbitrary keyword arguments representing the training configuration. These arguments are + used to customize various aspects of the training process. + + Returns: + (dict | None): Training metrics if available and training is successful; otherwise, None. + + Raises: + AssertionError: If the model is not a PyTorch model. + PermissionError: If there is a permission issue with the HUB session. + ModuleNotFoundError: If the HUB SDK is not installed. + """ + self._check_is_pytorch_model() + if hasattr(self.session, "model") and self.session.model.id: # Ultralytics HUB session with loaded model + if any(kwargs): + LOGGER.warning("WARNING ⚠️ using HUB training arguments, ignoring local training arguments.") + kwargs = self.session.train_args # overwrite kwargs + + checks.check_pip_update_available() + + overrides = yaml_load(checks.check_yaml(kwargs["cfg"])) if kwargs.get("cfg") else self.overrides + custom = { + # NOTE: handle the case when 'cfg' includes 'data'. + "data": overrides.get("data") or DEFAULT_CFG_DICT["data"] or TASK2DATA[self.task], + "model": self.overrides["model"], + "task": self.task, + } # method defaults + args = {**overrides, **custom, **kwargs, "mode": "train"} # highest priority args on the right + if args.get("resume"): + args["resume"] = self.ckpt_path + + self.trainer = (trainer or self._smart_load("trainer"))(overrides=args, _callbacks=self.callbacks) + if not args.get("resume"): # manually set model only if not resuming + self.trainer.model = self.trainer.get_model(weights=self.model if self.ckpt else None, cfg=self.model.yaml) + self.model = self.trainer.model + + if SETTINGS["hub"] is True and not self.session: + # Create a model in HUB + try: + self.session = self._get_hub_session(self.model_name) + if self.session: + self.session.create_model(args) + # Check model was created + if not getattr(self.session.model, "id", None): + self.session = None + except (PermissionError, ModuleNotFoundError): + # Ignore PermissionError and ModuleNotFoundError which indicates hub-sdk not installed + pass + + self.trainer.hub_session = self.session # attach optional HUB session + self.trainer.train() + # Update model and cfg after training + if RANK in {-1, 0}: + ckpt = self.trainer.best if self.trainer.best.exists() else self.trainer.last + self.model, _ = attempt_load_one_weight(ckpt) + self.overrides = self.model.args + self.metrics = getattr(self.trainer.validator, "metrics", None) # TODO: no metrics returned by DDP + return self.metrics + + def tune( + self, + use_ray=False, + iterations=10, + *args, + **kwargs, + ): + """ + Conducts hyperparameter tuning for the model, with an option to use Ray Tune. + + This method supports two modes of hyperparameter tuning: using Ray Tune or a custom tuning method. + When Ray Tune is enabled, it leverages the 'run_ray_tune' function from the ultralytics.utils.tuner module. + Otherwise, it uses the internal 'Tuner' class for tuning. The method combines default, overridden, and + custom arguments to configure the tuning process. + + Args: + use_ray (bool): If True, uses Ray Tune for hyperparameter tuning. Defaults to False. + iterations (int): The number of tuning iterations to perform. Defaults to 10. + *args (list): Variable length argument list for additional arguments. + **kwargs (any): Arbitrary keyword arguments. These are combined with the model's overrides and defaults. + + Returns: + (dict): A dictionary containing the results of the hyperparameter search. + + Raises: + AssertionError: If the model is not a PyTorch model. + """ + self._check_is_pytorch_model() + if use_ray: + from ultralytics.utils.tuner import run_ray_tune + + return run_ray_tune(self, max_samples=iterations, *args, **kwargs) + else: + from .tuner import Tuner + + custom = {} # method defaults + args = {**self.overrides, **custom, **kwargs, "mode": "train"} # highest priority args on the right + return Tuner(args=args, _callbacks=self.callbacks)(model=self, iterations=iterations) + + def _apply(self, fn) -> "Model": + """Apply to(), cpu(), cuda(), half(), float() to model tensors that are not parameters or registered buffers.""" + self._check_is_pytorch_model() + self = super()._apply(fn) # noqa + self.predictor = None # reset predictor as device may have changed + self.overrides["device"] = self.device # was str(self.device) i.e. device(type='cuda', index=0) -> 'cuda:0' + return self + + @property + def names(self) -> list: + """ + Retrieves the class names associated with the loaded model. + + This property returns the class names if they are defined in the model. It checks the class names for validity + using the 'check_class_names' function from the ultralytics.nn.autobackend module. + + Returns: + (list | None): The class names of the model if available, otherwise None. + """ + from ultralytics.nn.autobackend import check_class_names + + if hasattr(self.model, "names"): + return check_class_names(self.model.names) + else: + if not self.predictor: # export formats will not have predictor defined until predict() is called + self.predictor = self._smart_load("predictor")(overrides=self.overrides, _callbacks=self.callbacks) + self.predictor.setup_model(model=self.model, verbose=False) + return self.predictor.model.names + + @property + def device(self) -> torch.device: + """ + Retrieves the device on which the model's parameters are allocated. + + This property is used to determine whether the model's parameters are on CPU or GPU. It only applies to models + that are instances of nn.Module. + + Returns: + (torch.device | None): The device (CPU/GPU) of the model if it is a PyTorch model, otherwise None. + """ + return next(self.model.parameters()).device if isinstance(self.model, nn.Module) else None + + @property + def transforms(self): + """ + Retrieves the transformations applied to the input data of the loaded model. + + This property returns the transformations if they are defined in the model. + + Returns: + (object | None): The transform object of the model if available, otherwise None. + """ + return self.model.transforms if hasattr(self.model, "transforms") else None + + def add_callback(self, event: str, func) -> None: + """ + Adds a callback function for a specified event. + + This method allows the user to register a custom callback function that is triggered on a specific event during + model training or inference. + + Args: + event (str): The name of the event to attach the callback to. + func (callable): The callback function to be registered. + + Raises: + ValueError: If the event name is not recognized. + """ + self.callbacks[event].append(func) + + def clear_callback(self, event: str) -> None: + """ + Clears all callback functions registered for a specified event. + + This method removes all custom and default callback functions associated with the given event. + + Args: + event (str): The name of the event for which to clear the callbacks. + + Raises: + ValueError: If the event name is not recognized. + """ + self.callbacks[event] = [] + + def reset_callbacks(self) -> None: + """ + Resets all callbacks to their default functions. + + This method reinstates the default callback functions for all events, removing any custom callbacks that were + added previously. + """ + for event in callbacks.default_callbacks.keys(): + self.callbacks[event] = [callbacks.default_callbacks[event][0]] + + @staticmethod + def _reset_ckpt_args(args: dict) -> dict: + """Reset arguments when loading a PyTorch model.""" + include = {"imgsz", "data", "task", "single_cls"} # only remember these arguments when loading a PyTorch model + return {k: v for k, v in args.items() if k in include} + + # def __getattr__(self, attr): + # """Raises error if object has no requested attribute.""" + # name = self.__class__.__name__ + # raise AttributeError(f"'{name}' object has no attribute '{attr}'. See valid attributes below.\n{self.__doc__}") + + def _smart_load(self, key: str): + """Load model/trainer/validator/predictor.""" + try: + return self.task_map[self.task][key] + except Exception as e: + name = self.__class__.__name__ + mode = inspect.stack()[1][3] # get the function name. + raise NotImplementedError( + emojis(f"WARNING ⚠️ '{name}' model does not support '{mode}' mode for '{self.task}' task yet.") + ) from e + + @property + def task_map(self) -> dict: + """ + Map head to model, trainer, validator, and predictor classes. + + Returns: + task_map (dict): The map of model task to mode classes. + """ + raise NotImplementedError("Please provide task map for your model!") diff --git a/ultralytics/engine/predictor.py b/ultralytics/engine/predictor.py new file mode 100644 index 0000000..921f273 --- /dev/null +++ b/ultralytics/engine/predictor.py @@ -0,0 +1,397 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +""" +Run prediction on images, videos, directories, globs, YouTube, webcam, streams, etc. + +Usage - sources: + $ yolo mode=predict model=yolov8n.pt source=0 # webcam + img.jpg # image + vid.mp4 # video + screen # screenshot + path/ # directory + list.txt # list of images + list.streams # list of streams + 'path/*.jpg' # glob + 'https://youtu.be/LNwODJXcvt4' # YouTube + 'rtsp://example.com/media.mp4' # RTSP, RTMP, HTTP, TCP stream + +Usage - formats: + $ yolo mode=predict model=yolov8n.pt # PyTorch + yolov8n.torchscript # TorchScript + yolov8n.onnx # ONNX Runtime or OpenCV DNN with dnn=True + yolov8n_openvino_model # OpenVINO + yolov8n.engine # TensorRT + yolov8n.mlpackage # CoreML (macOS-only) + yolov8n_saved_model # TensorFlow SavedModel + yolov8n.pb # TensorFlow GraphDef + yolov8n.tflite # TensorFlow Lite + yolov8n_edgetpu.tflite # TensorFlow Edge TPU + yolov8n_paddle_model # PaddlePaddle + yolov8n_ncnn_model # NCNN +""" + +import platform +import re +import threading +from pathlib import Path + +import cv2 +import numpy as np +import torch + +from ultralytics.cfg import get_cfg, get_save_dir +from ultralytics.data import load_inference_source +from ultralytics.data.augment import LetterBox, classify_transforms +from ultralytics.nn.autobackend import AutoBackend +from ultralytics.utils import DEFAULT_CFG, LOGGER, MACOS, WINDOWS, callbacks, colorstr, ops +from ultralytics.utils.checks import check_imgsz, check_imshow +from ultralytics.utils.files import increment_path +from ultralytics.utils.torch_utils import select_device, smart_inference_mode + +STREAM_WARNING = """ +WARNING ⚠️ inference results will accumulate in RAM unless `stream=True` is passed, causing potential out-of-memory +errors for large sources or long-running streams and videos. See https://docs.ultralytics.com/modes/predict/ for help. + +Example: + results = model(source=..., stream=True) # generator of Results objects + for r in results: + boxes = r.boxes # Boxes object for bbox outputs + masks = r.masks # Masks object for segment masks outputs + probs = r.probs # Class probabilities for classification outputs +""" + + +class BasePredictor: + """ + BasePredictor. + + A base class for creating predictors. + + Attributes: + args (SimpleNamespace): Configuration for the predictor. + save_dir (Path): Directory to save results. + done_warmup (bool): Whether the predictor has finished setup. + model (nn.Module): Model used for prediction. + data (dict): Data configuration. + device (torch.device): Device used for prediction. + dataset (Dataset): Dataset used for prediction. + vid_writer (dict): Dictionary of {save_path: video_writer, ...} writer for saving video output. + """ + + def __init__(self, cfg=DEFAULT_CFG, overrides=None, _callbacks=None): + """ + Initializes the BasePredictor class. + + Args: + cfg (str, optional): Path to a configuration file. Defaults to DEFAULT_CFG. + overrides (dict, optional): Configuration overrides. Defaults to None. + """ + self.args = get_cfg(cfg, overrides) + self.save_dir = get_save_dir(self.args) + if self.args.conf is None: + self.args.conf = 0.25 # default conf=0.25 + self.done_warmup = False + if self.args.show: + self.args.show = check_imshow(warn=True) + + # Usable if setup is done + self.model = None + self.data = self.args.data # data_dict + self.imgsz = None + self.device = None + self.dataset = None + self.vid_writer = {} # dict of {save_path: video_writer, ...} + self.plotted_img = None + self.source_type = None + self.seen = 0 + self.windows = [] + self.batch = None + self.results = None + self.transforms = None + self.callbacks = _callbacks or callbacks.get_default_callbacks() + self.txt_path = None + self._lock = threading.Lock() # for automatic thread-safe inference + callbacks.add_integration_callbacks(self) + + def preprocess(self, im): + """ + Prepares input image before inference. + + Args: + im (torch.Tensor | List(np.ndarray)): BCHW for tensor, [(HWC) x B] for list. + """ + not_tensor = not isinstance(im, torch.Tensor) + if not_tensor: + im = np.stack(self.pre_transform(im)) + im = im[..., ::-1].transpose((0, 3, 1, 2)) # BGR to RGB, BHWC to BCHW, (n, 3, h, w) + im = np.ascontiguousarray(im) # contiguous + im = torch.from_numpy(im) + + im = im.to(self.device) + im = im.half() if self.model.fp16 else im.float() # uint8 to fp16/32 + if not_tensor: + im /= 255 # 0 - 255 to 0.0 - 1.0 + return im + + def inference(self, im, *args, **kwargs): + """Runs inference on a given image using the specified model and arguments.""" + visualize = ( + increment_path(self.save_dir / Path(self.batch[0][0]).stem, mkdir=True) + if self.args.visualize and (not self.source_type.tensor) + else False + ) + return self.model(im, augment=self.args.augment, visualize=visualize, embed=self.args.embed, *args, **kwargs) + + def pre_transform(self, im): + """ + Pre-transform input image before inference. + + Args: + im (List(np.ndarray)): (N, 3, h, w) for tensor, [(h, w, 3) x N] for list. + + Returns: + (list): A list of transformed images. + """ + same_shapes = len({x.shape for x in im}) == 1 + letterbox = LetterBox(self.imgsz, auto=same_shapes and self.model.pt, stride=self.model.stride) + return [letterbox(image=x) for x in im] + + def postprocess(self, preds, img, orig_imgs): + """Post-processes predictions for an image and returns them.""" + return preds + + def __call__(self, source=None, model=None, stream=False, *args, **kwargs): + """Performs inference on an image or stream.""" + self.stream = stream + if stream: + return self.stream_inference(source, model, *args, **kwargs) + else: + return list(self.stream_inference(source, model, *args, **kwargs)) # merge list of Result into one + + def predict_cli(self, source=None, model=None): + """ + Method used for CLI prediction. + + It uses always generator as outputs as not required by CLI mode. + """ + gen = self.stream_inference(source, model) + for _ in gen: # noqa, running CLI inference without accumulating any outputs (do not modify) + pass + + def setup_source(self, source): + """Sets up source and inference mode.""" + self.imgsz = check_imgsz(self.args.imgsz, stride=self.model.stride, min_dim=2) # check image size + self.transforms = ( + getattr( + self.model.model, + "transforms", + classify_transforms(self.imgsz[0], crop_fraction=self.args.crop_fraction), + ) + if self.args.task == "classify" + else None + ) + self.dataset = load_inference_source( + source=source, + batch=self.args.batch, + vid_stride=self.args.vid_stride, + buffer=self.args.stream_buffer, + ) + self.source_type = self.dataset.source_type + if not getattr(self, "stream", True) and ( + self.source_type.stream + or self.source_type.screenshot + or len(self.dataset) > 1000 # many images + or any(getattr(self.dataset, "video_flag", [False])) + ): # videos + LOGGER.warning(STREAM_WARNING) + self.vid_writer = {} + + @smart_inference_mode() + def stream_inference(self, source=None, model=None, *args, **kwargs): + """Streams real-time inference on camera feed and saves results to file.""" + if self.args.verbose: + LOGGER.info("") + + # Setup model + if not self.model: + self.setup_model(model) + + with self._lock: # for thread-safe inference + # Setup source every time predict is called + self.setup_source(source if source is not None else self.args.source) + + # Check if save_dir/ label file exists + if self.args.save or self.args.save_txt: + (self.save_dir / "labels" if self.args.save_txt else self.save_dir).mkdir(parents=True, exist_ok=True) + + # Warmup model + if not self.done_warmup: + self.model.warmup(imgsz=(1 if self.model.pt or self.model.triton else self.dataset.bs, 3, *self.imgsz)) + self.done_warmup = True + + self.seen, self.windows, self.batch = 0, [], None + profilers = ( + ops.Profile(device=self.device), + ops.Profile(device=self.device), + ops.Profile(device=self.device), + ) + self.run_callbacks("on_predict_start") + for self.batch in self.dataset: + self.run_callbacks("on_predict_batch_start") + paths, im0s, s = self.batch + + # Preprocess + with profilers[0]: + im = self.preprocess(im0s) + + # Inference + with profilers[1]: + preds = self.inference(im, *args, **kwargs) + if self.args.embed: + yield from [preds] if isinstance(preds, torch.Tensor) else preds # yield embedding tensors + continue + + # Postprocess + with profilers[2]: + self.results = self.postprocess(preds, im, im0s) + self.run_callbacks("on_predict_postprocess_end") + + # Visualize, save, write results + n = len(im0s) + for i in range(n): + self.seen += 1 + self.results[i].speed = { + "preprocess": profilers[0].dt * 1e3 / n, + "inference": profilers[1].dt * 1e3 / n, + "postprocess": profilers[2].dt * 1e3 / n, + } + if self.args.verbose or self.args.save or self.args.save_txt or self.args.show: + s[i] += self.write_results(i, Path(paths[i]), im, s) + + # Print batch results + if self.args.verbose: + LOGGER.info("\n".join(s)) + + self.run_callbacks("on_predict_batch_end") + yield from self.results + + # Release assets + for v in self.vid_writer.values(): + if isinstance(v, cv2.VideoWriter): + v.release() + + # Print final results + if self.args.verbose and self.seen: + t = tuple(x.t / self.seen * 1e3 for x in profilers) # speeds per image + LOGGER.info( + f"Speed: %.1fms preprocess, %.1fms inference, %.1fms postprocess per image at shape " + f"{(min(self.args.batch, self.seen), 3, *im.shape[2:])}" % t + ) + if self.args.save or self.args.save_txt or self.args.save_crop: + nl = len(list(self.save_dir.glob("labels/*.txt"))) # number of labels + s = f"\n{nl} label{'s' * (nl > 1)} saved to {self.save_dir / 'labels'}" if self.args.save_txt else "" + LOGGER.info(f"Results saved to {colorstr('bold', self.save_dir)}{s}") + self.run_callbacks("on_predict_end") + + def setup_model(self, model, verbose=True): + """Initialize YOLO model with given parameters and set it to evaluation mode.""" + self.model = AutoBackend( + weights=model or self.args.model, + device=select_device(self.args.device, verbose=verbose), + dnn=self.args.dnn, + data=self.args.data, + fp16=self.args.half, + batch=self.args.batch, + fuse=True, + verbose=verbose, + ) + + self.device = self.model.device # update device + self.args.half = self.model.fp16 # update half + self.model.eval() + + def write_results(self, i, p, im, s): + """Write inference results to a file or directory.""" + string = "" # print string + if len(im.shape) == 3: + im = im[None] # expand for batch dim + if self.source_type.stream or self.source_type.from_img or self.source_type.tensor: # batch_size >= 1 + string += f"{i}: " + frame = self.dataset.count + else: + match = re.search(r"frame (\d+)/", s[i]) + frame = int(match.group(1)) if match else None # 0 if frame undetermined + + self.txt_path = self.save_dir / "labels" / (p.stem + ("" if self.dataset.mode == "image" else f"_{frame}")) + string += "%gx%g " % im.shape[2:] + result = self.results[i] + result.save_dir = self.save_dir.__str__() # used in other locations + string += result.verbose() + f"{result.speed['inference']:.1f}ms" + + # Add predictions to image + if self.args.save or self.args.show: + self.plotted_img = result.plot( + line_width=self.args.line_width, + boxes=self.args.show_boxes, + conf=self.args.show_conf, + labels=self.args.show_labels, + im_gpu=None if self.args.retina_masks else im[i], + ) + + # Save results + if self.args.save_txt: + result.save_txt(f"{self.txt_path}.txt", save_conf=self.args.save_conf) + if self.args.save_crop: + result.save_crop(save_dir=self.save_dir / "crops", file_name=self.txt_path.stem) + if self.args.show: + self.show(str(p)) + if self.args.save: + self.save_predicted_images(str(self.save_dir / p.name), frame) + + return string + + def save_predicted_images(self, save_path="", frame=0): + """Save video predictions as mp4 at specified path.""" + im = self.plotted_img + + # Save videos and streams + if self.dataset.mode in {"stream", "video"}: + fps = self.dataset.fps if self.dataset.mode == "video" else 30 + frames_path = f'{save_path.split(".", 1)[0]}_frames/' + if save_path not in self.vid_writer: # new video + if self.args.save_frames: + Path(frames_path).mkdir(parents=True, exist_ok=True) + suffix, fourcc = (".mp4", "avc1") if MACOS else (".avi", "WMV2") if WINDOWS else (".avi", "MJPG") + self.vid_writer[save_path] = cv2.VideoWriter( + filename=str(Path(save_path).with_suffix(suffix)), + fourcc=cv2.VideoWriter_fourcc(*fourcc), + fps=fps, # integer required, floats produce error in MP4 codec + frameSize=(im.shape[1], im.shape[0]), # (width, height) + ) + + # Save video + self.vid_writer[save_path].write(im) + if self.args.save_frames: + cv2.imwrite(f"{frames_path}{frame}.jpg", im) + + # Save images + else: + cv2.imwrite(save_path, im) + + def show(self, p=""): + """Display an image in a window using OpenCV imshow().""" + im = self.plotted_img + if platform.system() == "Linux" and p not in self.windows: + self.windows.append(p) + cv2.namedWindow(p, cv2.WINDOW_NORMAL | cv2.WINDOW_KEEPRATIO) # allow window resize (Linux) + cv2.resizeWindow(p, im.shape[1], im.shape[0]) # (width, height) + cv2.imshow(p, im) + cv2.waitKey(300 if self.dataset.mode == "image" else 1) # 1 millisecond + + def run_callbacks(self, event: str): + """Runs all registered callbacks for a specific event.""" + for callback in self.callbacks.get(event, []): + callback(self) + + def add_callback(self, event: str, func): + """Add callback.""" + self.callbacks[event].append(func) diff --git a/ultralytics/engine/results.py b/ultralytics/engine/results.py new file mode 100644 index 0000000..ba6f213 --- /dev/null +++ b/ultralytics/engine/results.py @@ -0,0 +1,743 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +""" +Ultralytics Results, Boxes and Masks classes for handling inference results. + +Usage: See https://docs.ultralytics.com/modes/predict/ +""" + +from copy import deepcopy +from functools import lru_cache +from pathlib import Path + +import numpy as np +import torch + +from ultralytics.data.augment import LetterBox +from ultralytics.utils import LOGGER, SimpleClass, ops +from ultralytics.utils.plotting import Annotator, colors, save_one_box +from ultralytics.utils.torch_utils import smart_inference_mode + + +class BaseTensor(SimpleClass): + """Base tensor class with additional methods for easy manipulation and device handling.""" + + def __init__(self, data, orig_shape) -> None: + """ + Initialize BaseTensor with data and original shape. + + Args: + data (torch.Tensor | np.ndarray): Predictions, such as bboxes, masks and keypoints. + orig_shape (tuple): Original shape of image. + """ + assert isinstance(data, (torch.Tensor, np.ndarray)) + self.data = data + self.orig_shape = orig_shape + + @property + def shape(self): + """Return the shape of the data tensor.""" + return self.data.shape + + def cpu(self): + """Return a copy of the tensor on CPU memory.""" + return self if isinstance(self.data, np.ndarray) else self.__class__(self.data.cpu(), self.orig_shape) + + def numpy(self): + """Return a copy of the tensor as a numpy array.""" + return self if isinstance(self.data, np.ndarray) else self.__class__(self.data.numpy(), self.orig_shape) + + def cuda(self): + """Return a copy of the tensor on GPU memory.""" + return self.__class__(torch.as_tensor(self.data).cuda(), self.orig_shape) + + def to(self, *args, **kwargs): + """Return a copy of the tensor with the specified device and dtype.""" + return self.__class__(torch.as_tensor(self.data).to(*args, **kwargs), self.orig_shape) + + def __len__(self): # override len(results) + """Return the length of the data tensor.""" + return len(self.data) + + def __getitem__(self, idx): + """Return a BaseTensor with the specified index of the data tensor.""" + return self.__class__(self.data[idx], self.orig_shape) + + +class Results(SimpleClass): + """ + A class for storing and manipulating inference results. + + Attributes: + orig_img (numpy.ndarray): Original image as a numpy array. + orig_shape (tuple): Original image shape in (height, width) format. + boxes (Boxes, optional): Object containing detection bounding boxes. + masks (Masks, optional): Object containing detection masks. + probs (Probs, optional): Object containing class probabilities for classification tasks. + keypoints (Keypoints, optional): Object containing detected keypoints for each object. + speed (dict): Dictionary of preprocess, inference, and postprocess speeds (ms/image). + names (dict): Dictionary of class names. + path (str): Path to the image file. + + Methods: + update(boxes=None, masks=None, probs=None, obb=None): Updates object attributes with new detection results. + cpu(): Returns a copy of the Results object with all tensors on CPU memory. + numpy(): Returns a copy of the Results object with all tensors as numpy arrays. + cuda(): Returns a copy of the Results object with all tensors on GPU memory. + to(*args, **kwargs): Returns a copy of the Results object with tensors on a specified device and dtype. + new(): Returns a new Results object with the same image, path, and names. + plot(...): Plots detection results on an input image, returning an annotated image. + show(): Show annotated results to screen. + save(filename): Save annotated results to file. + verbose(): Returns a log string for each task, detailing detections and classifications. + save_txt(txt_file, save_conf=False): Saves detection results to a text file. + save_crop(save_dir, file_name=Path("im.jpg")): Saves cropped detection images. + tojson(normalize=False): Converts detection results to JSON format. + """ + + def __init__(self, orig_img, path, names, boxes=None, masks=None, probs=None, keypoints=None, obb=None) -> None: + """ + Initialize the Results class. + + Args: + orig_img (numpy.ndarray): The original image as a numpy array. + path (str): The path to the image file. + names (dict): A dictionary of class names. + boxes (torch.tensor, optional): A 2D tensor of bounding box coordinates for each detection. + masks (torch.tensor, optional): A 3D tensor of detection masks, where each mask is a binary image. + probs (torch.tensor, optional): A 1D tensor of probabilities of each class for classification task. + keypoints (torch.tensor, optional): A 2D tensor of keypoint coordinates for each detection. + obb (torch.tensor, optional): A 2D tensor of oriented bounding box coordinates for each detection. + """ + self.orig_img = orig_img + self.orig_shape = orig_img.shape[:2] + self.boxes = Boxes(boxes, self.orig_shape) if boxes is not None else None # native size boxes + self.masks = Masks(masks, self.orig_shape) if masks is not None else None # native size or imgsz masks + self.probs = Probs(probs) if probs is not None else None + self.keypoints = Keypoints(keypoints, self.orig_shape) if keypoints is not None else None + self.obb = OBB(obb, self.orig_shape) if obb is not None else None + self.speed = {"preprocess": None, "inference": None, "postprocess": None} # milliseconds per image + self.names = names + self.path = path + self.save_dir = None + self._keys = "boxes", "masks", "probs", "keypoints", "obb" + + def __getitem__(self, idx): + """Return a Results object for the specified index.""" + return self._apply("__getitem__", idx) + + def __len__(self): + """Return the number of detections in the Results object.""" + for k in self._keys: + v = getattr(self, k) + if v is not None: + return len(v) + + def update(self, boxes=None, masks=None, probs=None, obb=None): + """Update the boxes, masks, and probs attributes of the Results object.""" + if boxes is not None: + self.boxes = Boxes(ops.clip_boxes(boxes, self.orig_shape), self.orig_shape) + if masks is not None: + self.masks = Masks(masks, self.orig_shape) + if probs is not None: + self.probs = probs + if obb is not None: + self.obb = OBB(obb, self.orig_shape) + + def _apply(self, fn, *args, **kwargs): + """ + Applies a function to all non-empty attributes and returns a new Results object with modified attributes. This + function is internally called by methods like .to(), .cuda(), .cpu(), etc. + + Args: + fn (str): The name of the function to apply. + *args: Variable length argument list to pass to the function. + **kwargs: Arbitrary keyword arguments to pass to the function. + + Returns: + Results: A new Results object with attributes modified by the applied function. + """ + r = self.new() + for k in self._keys: + v = getattr(self, k) + if v is not None: + setattr(r, k, getattr(v, fn)(*args, **kwargs)) + return r + + def cpu(self): + """Return a copy of the Results object with all tensors on CPU memory.""" + return self._apply("cpu") + + def numpy(self): + """Return a copy of the Results object with all tensors as numpy arrays.""" + return self._apply("numpy") + + def cuda(self): + """Return a copy of the Results object with all tensors on GPU memory.""" + return self._apply("cuda") + + def to(self, *args, **kwargs): + """Return a copy of the Results object with tensors on the specified device and dtype.""" + return self._apply("to", *args, **kwargs) + + def new(self): + """Return a new Results object with the same image, path, and names.""" + return Results(orig_img=self.orig_img, path=self.path, names=self.names) + + def plot( + self, + conf=True, + line_width=None, + font_size=None, + font="Arial.ttf", + pil=False, + img=None, + im_gpu=None, + kpt_radius=5, + kpt_line=True, + labels=True, + boxes=True, + masks=True, + probs=True, + show=False, + save=False, + filename=None, + ): + """ + Plots the detection results on an input RGB image. Accepts a numpy array (cv2) or a PIL Image. + + Args: + conf (bool): Whether to plot the detection confidence score. + line_width (float, optional): The line width of the bounding boxes. If None, it is scaled to the image size. + font_size (float, optional): The font size of the text. If None, it is scaled to the image size. + font (str): The font to use for the text. + pil (bool): Whether to return the image as a PIL Image. + img (numpy.ndarray): Plot to another image. if not, plot to original image. + im_gpu (torch.Tensor): Normalized image in gpu with shape (1, 3, 640, 640), for faster mask plotting. + kpt_radius (int, optional): Radius of the drawn keypoints. Default is 5. + kpt_line (bool): Whether to draw lines connecting keypoints. + labels (bool): Whether to plot the label of bounding boxes. + boxes (bool): Whether to plot the bounding boxes. + masks (bool): Whether to plot the masks. + probs (bool): Whether to plot classification probability + show (bool): Whether to display the annotated image directly. + save (bool): Whether to save the annotated image to `filename`. + filename (str): Filename to save image to if save is True. + + Returns: + (numpy.ndarray): A numpy array of the annotated image. + + Example: + ```python + from PIL import Image + from ultralytics import YOLO + + model = YOLO('yolov8n.pt') + results = model('bus.jpg') # results list + for r in results: + im_array = r.plot() # plot a BGR numpy array of predictions + im = Image.fromarray(im_array[..., ::-1]) # RGB PIL image + im.show() # show image + im.save('results.jpg') # save image + ``` + """ + if img is None and isinstance(self.orig_img, torch.Tensor): + img = (self.orig_img[0].detach().permute(1, 2, 0).contiguous() * 255).to(torch.uint8).cpu().numpy() + + names = self.names + is_obb = self.obb is not None + pred_boxes, show_boxes = self.obb if is_obb else self.boxes, boxes + pred_masks, show_masks = self.masks, masks + pred_probs, show_probs = self.probs, probs + annotator = Annotator( + deepcopy(self.orig_img if img is None else img), + line_width, + font_size, + font, + pil or (pred_probs is not None and show_probs), # Classify tasks default to pil=True + example=names, + ) + + # Plot Segment results + if pred_masks and show_masks: + if im_gpu is None: + img = LetterBox(pred_masks.shape[1:])(image=annotator.result()) + im_gpu = ( + torch.as_tensor(img, dtype=torch.float16, device=pred_masks.data.device) + .permute(2, 0, 1) + .flip(0) + .contiguous() + / 255 + ) + idx = pred_boxes.cls if pred_boxes else range(len(pred_masks)) + annotator.masks(pred_masks.data, colors=[colors(x, True) for x in idx], im_gpu=im_gpu) + + # Plot Detect results + if pred_boxes is not None and show_boxes: + for d in reversed(pred_boxes): + c, conf, id = int(d.cls), float(d.conf) if conf else None, None if d.id is None else int(d.id.item()) + name = ("" if id is None else f"id:{id} ") + names[c] + label = (f"{name} {conf:.2f}" if conf else name) if labels else None + box = d.xyxyxyxy.reshape(-1, 4, 2).squeeze() if is_obb else d.xyxy.squeeze() + annotator.box_label(box, label, color=colors(c, True), rotated=is_obb) + + # Plot Classify results + if pred_probs is not None and show_probs: + text = ",\n".join(f"{names[j] if names else j} {pred_probs.data[j]:.2f}" for j in pred_probs.top5) + x = round(self.orig_shape[0] * 0.03) + annotator.text([x, x], text, txt_color=(255, 255, 255)) # TODO: allow setting colors + + # Plot Pose results + if self.keypoints is not None: + for k in reversed(self.keypoints.data): + annotator.kpts(k, self.orig_shape, radius=kpt_radius, kpt_line=kpt_line) + + # Show results + if show: + annotator.show(self.path) + + # Save results + if save: + annotator.save(filename) + + return annotator.result() + + def show(self, *args, **kwargs): + """Show annotated results image.""" + self.plot(show=True, *args, **kwargs) + + def save(self, filename=None, *args, **kwargs): + """Save annotated results image.""" + if not filename: + filename = f"results_{Path(self.path).name}" + self.plot(save=True, filename=filename, *args, **kwargs) + return filename + + def verbose(self): + """Return log string for each task.""" + log_string = "" + probs = self.probs + boxes = self.boxes + if len(self) == 0: + return log_string if probs is not None else f"{log_string}(no detections), " + if probs is not None: + log_string += f"{', '.join(f'{self.names[j]} {probs.data[j]:.2f}' for j in probs.top5)}, " + if boxes: + for c in boxes.cls.unique(): + n = (boxes.cls == c).sum() # detections per class + log_string += f"{n} {self.names[int(c)]}{'s' * (n > 1)}, " + return log_string + + def save_txt(self, txt_file, save_conf=False): + """ + Save predictions into txt file. + + Args: + txt_file (str): txt file path. + save_conf (bool): save confidence score or not. + """ + is_obb = self.obb is not None + boxes = self.obb if is_obb else self.boxes + masks = self.masks + probs = self.probs + kpts = self.keypoints + texts = [] + if probs is not None: + # Classify + [texts.append(f"{probs.data[j]:.2f} {self.names[j]}") for j in probs.top5] + elif boxes: + # Detect/segment/pose + for j, d in enumerate(boxes): + c, conf, id = int(d.cls), float(d.conf), None if d.id is None else int(d.id.item()) + line = (c, *(d.xyxyxyxyn.view(-1) if is_obb else d.xywhn.view(-1))) + if masks: + seg = masks[j].xyn[0].copy().reshape(-1) # reversed mask.xyn, (n,2) to (n*2) + line = (c, *seg) + if kpts is not None: + kpt = torch.cat((kpts[j].xyn, kpts[j].conf[..., None]), 2) if kpts[j].has_visible else kpts[j].xyn + line += (*kpt.reshape(-1).tolist(),) + line += (conf,) * save_conf + (() if id is None else (id,)) + texts.append(("%g " * len(line)).rstrip() % line) + + if texts: + Path(txt_file).parent.mkdir(parents=True, exist_ok=True) # make directory + with open(txt_file, "a") as f: + f.writelines(text + "\n" for text in texts) + + def save_crop(self, save_dir, file_name=Path("im.jpg")): + """ + Save cropped predictions to `save_dir/cls/file_name.jpg`. + + Args: + save_dir (str | pathlib.Path): Save path. + file_name (str | pathlib.Path): File name. + """ + if self.probs is not None: + LOGGER.warning("WARNING ⚠️ Classify task do not support `save_crop`.") + return + if self.obb is not None: + LOGGER.warning("WARNING ⚠️ OBB task do not support `save_crop`.") + return + for d in self.boxes: + save_one_box( + d.xyxy, + self.orig_img.copy(), + file=Path(save_dir) / self.names[int(d.cls)] / f"{Path(file_name)}.jpg", + BGR=True, + ) + + def summary(self, normalize=False, decimals=5): + """Convert the results to a summarized format.""" + if self.probs is not None: + LOGGER.warning("Warning: Classify results do not support the `summary()` method yet.") + return + + # Create list of detection dictionaries + results = [] + data = self.boxes.data.cpu().tolist() + h, w = self.orig_shape if normalize else (1, 1) + for i, row in enumerate(data): # xyxy, track_id if tracking, conf, class_id + box = { + "x1": round(row[0] / w, decimals), + "y1": round(row[1] / h, decimals), + "x2": round(row[2] / w, decimals), + "y2": round(row[3] / h, decimals), + } + conf = round(row[-2], decimals) + class_id = int(row[-1]) + result = {"name": self.names[class_id], "class": class_id, "confidence": conf, "box": box} + if self.boxes.is_track: + result["track_id"] = int(row[-3]) # track ID + if self.masks: + result["segments"] = { + "x": (self.masks.xy[i][:, 0] / w).round(decimals).tolist(), + "y": (self.masks.xy[i][:, 1] / h).round(decimals).tolist(), + } + if self.keypoints is not None: + x, y, visible = self.keypoints[i].data[0].cpu().unbind(dim=1) # torch Tensor + result["keypoints"] = { + "x": (x / w).numpy().round(decimals).tolist(), # decimals named argument required + "y": (y / h).numpy().round(decimals).tolist(), + "visible": visible.numpy().round(decimals).tolist(), + } + results.append(result) + + return results + + def tojson(self, normalize=False, decimals=5): + """Convert the results to JSON format.""" + import json + + return json.dumps(self.summary(normalize=normalize, decimals=decimals), indent=2) + + +class Boxes(BaseTensor): + """ + Manages detection boxes, providing easy access and manipulation of box coordinates, confidence scores, class + identifiers, and optional tracking IDs. Supports multiple formats for box coordinates, including both absolute and + normalized forms. + + Attributes: + data (torch.Tensor): The raw tensor containing detection boxes and their associated data. + orig_shape (tuple): The original image size as a tuple (height, width), used for normalization. + is_track (bool): Indicates whether tracking IDs are included in the box data. + + Properties: + xyxy (torch.Tensor | numpy.ndarray): Boxes in [x1, y1, x2, y2] format. + conf (torch.Tensor | numpy.ndarray): Confidence scores for each box. + cls (torch.Tensor | numpy.ndarray): Class labels for each box. + id (torch.Tensor | numpy.ndarray, optional): Tracking IDs for each box, if available. + xywh (torch.Tensor | numpy.ndarray): Boxes in [x, y, width, height] format, calculated on demand. + xyxyn (torch.Tensor | numpy.ndarray): Normalized [x1, y1, x2, y2] boxes, relative to `orig_shape`. + xywhn (torch.Tensor | numpy.ndarray): Normalized [x, y, width, height] boxes, relative to `orig_shape`. + + Methods: + cpu(): Moves the boxes to CPU memory. + numpy(): Converts the boxes to a numpy array format. + cuda(): Moves the boxes to CUDA (GPU) memory. + to(device, dtype=None): Moves the boxes to the specified device. + """ + + def __init__(self, boxes, orig_shape) -> None: + """ + Initialize the Boxes class. + + Args: + boxes (torch.Tensor | numpy.ndarray): A tensor or numpy array containing the detection boxes, with + shape (num_boxes, 6) or (num_boxes, 7). The last two columns contain confidence and class values. + If present, the third last column contains track IDs. + orig_shape (tuple): Original image size, in the format (height, width). + """ + if boxes.ndim == 1: + boxes = boxes[None, :] + n = boxes.shape[-1] + assert n in {6, 7}, f"expected 6 or 7 values but got {n}" # xyxy, track_id, conf, cls + super().__init__(boxes, orig_shape) + self.is_track = n == 7 + self.orig_shape = orig_shape + + @property + def xyxy(self): + """Return the boxes in xyxy format.""" + return self.data[:, :4] + + @property + def conf(self): + """Return the confidence values of the boxes.""" + return self.data[:, -2] + + @property + def cls(self): + """Return the class values of the boxes.""" + return self.data[:, -1] + + @property + def id(self): + """Return the track IDs of the boxes (if available).""" + return self.data[:, -3] if self.is_track else None + + @property + @lru_cache(maxsize=2) # maxsize 1 should suffice + def xywh(self): + """Return the boxes in xywh format.""" + return ops.xyxy2xywh(self.xyxy) + + @property + @lru_cache(maxsize=2) + def xyxyn(self): + """Return the boxes in xyxy format normalized by original image size.""" + xyxy = self.xyxy.clone() if isinstance(self.xyxy, torch.Tensor) else np.copy(self.xyxy) + xyxy[..., [0, 2]] /= self.orig_shape[1] + xyxy[..., [1, 3]] /= self.orig_shape[0] + return xyxy + + @property + @lru_cache(maxsize=2) + def xywhn(self): + """Return the boxes in xywh format normalized by original image size.""" + xywh = ops.xyxy2xywh(self.xyxy) + xywh[..., [0, 2]] /= self.orig_shape[1] + xywh[..., [1, 3]] /= self.orig_shape[0] + return xywh + + +class Masks(BaseTensor): + """ + A class for storing and manipulating detection masks. + + Attributes: + xy (list): A list of segments in pixel coordinates. + xyn (list): A list of normalized segments. + + Methods: + cpu(): Returns the masks tensor on CPU memory. + numpy(): Returns the masks tensor as a numpy array. + cuda(): Returns the masks tensor on GPU memory. + to(device, dtype): Returns the masks tensor with the specified device and dtype. + """ + + def __init__(self, masks, orig_shape) -> None: + """Initialize the Masks class with the given masks tensor and original image shape.""" + if masks.ndim == 2: + masks = masks[None, :] + super().__init__(masks, orig_shape) + + @property + @lru_cache(maxsize=1) + def xyn(self): + """Return normalized segments.""" + return [ + ops.scale_coords(self.data.shape[1:], x, self.orig_shape, normalize=True) + for x in ops.masks2segments(self.data) + ] + + @property + @lru_cache(maxsize=1) + def xy(self): + """Return segments in pixel coordinates.""" + return [ + ops.scale_coords(self.data.shape[1:], x, self.orig_shape, normalize=False) + for x in ops.masks2segments(self.data) + ] + + +class Keypoints(BaseTensor): + """ + A class for storing and manipulating detection keypoints. + + Attributes: + xy (torch.Tensor): A collection of keypoints containing x, y coordinates for each detection. + xyn (torch.Tensor): A normalized version of xy with coordinates in the range [0, 1]. + conf (torch.Tensor): Confidence values associated with keypoints if available, otherwise None. + + Methods: + cpu(): Returns a copy of the keypoints tensor on CPU memory. + numpy(): Returns a copy of the keypoints tensor as a numpy array. + cuda(): Returns a copy of the keypoints tensor on GPU memory. + to(device, dtype): Returns a copy of the keypoints tensor with the specified device and dtype. + """ + + @smart_inference_mode() # avoid keypoints < conf in-place error + def __init__(self, keypoints, orig_shape) -> None: + """Initializes the Keypoints object with detection keypoints and original image size.""" + if keypoints.ndim == 2: + keypoints = keypoints[None, :] + if keypoints.shape[2] == 3: # x, y, conf + mask = keypoints[..., 2] < 0.5 # points with conf < 0.5 (not visible) + keypoints[..., :2][mask] = 0 + super().__init__(keypoints, orig_shape) + self.has_visible = self.data.shape[-1] == 3 + + @property + @lru_cache(maxsize=1) + def xy(self): + """Returns x, y coordinates of keypoints.""" + return self.data[..., :2] + + @property + @lru_cache(maxsize=1) + def xyn(self): + """Returns normalized x, y coordinates of keypoints.""" + xy = self.xy.clone() if isinstance(self.xy, torch.Tensor) else np.copy(self.xy) + xy[..., 0] /= self.orig_shape[1] + xy[..., 1] /= self.orig_shape[0] + return xy + + @property + @lru_cache(maxsize=1) + def conf(self): + """Returns confidence values of keypoints if available, else None.""" + return self.data[..., 2] if self.has_visible else None + + +class Probs(BaseTensor): + """ + A class for storing and manipulating classification predictions. + + Attributes: + top1 (int): Index of the top 1 class. + top5 (list[int]): Indices of the top 5 classes. + top1conf (torch.Tensor): Confidence of the top 1 class. + top5conf (torch.Tensor): Confidences of the top 5 classes. + + Methods: + cpu(): Returns a copy of the probs tensor on CPU memory. + numpy(): Returns a copy of the probs tensor as a numpy array. + cuda(): Returns a copy of the probs tensor on GPU memory. + to(): Returns a copy of the probs tensor with the specified device and dtype. + """ + + def __init__(self, probs, orig_shape=None) -> None: + """Initialize the Probs class with classification probabilities and optional original shape of the image.""" + super().__init__(probs, orig_shape) + + @property + @lru_cache(maxsize=1) + def top1(self): + """Return the index of top 1.""" + return int(self.data.argmax()) + + @property + @lru_cache(maxsize=1) + def top5(self): + """Return the indices of top 5.""" + return (-self.data).argsort(0)[:5].tolist() # this way works with both torch and numpy. + + @property + @lru_cache(maxsize=1) + def top1conf(self): + """Return the confidence of top 1.""" + return self.data[self.top1] + + @property + @lru_cache(maxsize=1) + def top5conf(self): + """Return the confidences of top 5.""" + return self.data[self.top5] + + +class OBB(BaseTensor): + """ + A class for storing and manipulating Oriented Bounding Boxes (OBB). + + Args: + boxes (torch.Tensor | numpy.ndarray): A tensor or numpy array containing the detection boxes, + with shape (num_boxes, 7) or (num_boxes, 8). The last two columns contain confidence and class values. + If present, the third last column contains track IDs, and the fifth column from the left contains rotation. + orig_shape (tuple): Original image size, in the format (height, width). + + Attributes: + xywhr (torch.Tensor | numpy.ndarray): The boxes in [x_center, y_center, width, height, rotation] format. + conf (torch.Tensor | numpy.ndarray): The confidence values of the boxes. + cls (torch.Tensor | numpy.ndarray): The class values of the boxes. + id (torch.Tensor | numpy.ndarray): The track IDs of the boxes (if available). + xyxyxyxyn (torch.Tensor | numpy.ndarray): The rotated boxes in xyxyxyxy format normalized by orig image size. + xyxyxyxy (torch.Tensor | numpy.ndarray): The rotated boxes in xyxyxyxy format. + xyxy (torch.Tensor | numpy.ndarray): The horizontal boxes in xyxyxyxy format. + data (torch.Tensor): The raw OBB tensor (alias for `boxes`). + + Methods: + cpu(): Move the object to CPU memory. + numpy(): Convert the object to a numpy array. + cuda(): Move the object to CUDA memory. + to(*args, **kwargs): Move the object to the specified device. + """ + + def __init__(self, boxes, orig_shape) -> None: + """Initialize the Boxes class.""" + if boxes.ndim == 1: + boxes = boxes[None, :] + n = boxes.shape[-1] + assert n in {7, 8}, f"expected 7 or 8 values but got {n}" # xywh, rotation, track_id, conf, cls + super().__init__(boxes, orig_shape) + self.is_track = n == 8 + self.orig_shape = orig_shape + + @property + def xywhr(self): + """Return the rotated boxes in xywhr format.""" + return self.data[:, :5] + + @property + def conf(self): + """Return the confidence values of the boxes.""" + return self.data[:, -2] + + @property + def cls(self): + """Return the class values of the boxes.""" + return self.data[:, -1] + + @property + def id(self): + """Return the track IDs of the boxes (if available).""" + return self.data[:, -3] if self.is_track else None + + @property + @lru_cache(maxsize=2) + def xyxyxyxy(self): + """Return the boxes in xyxyxyxy format, (N, 4, 2).""" + return ops.xywhr2xyxyxyxy(self.xywhr) + + @property + @lru_cache(maxsize=2) + def xyxyxyxyn(self): + """Return the boxes in xyxyxyxy format, (N, 4, 2).""" + xyxyxyxyn = self.xyxyxyxy.clone() if isinstance(self.xyxyxyxy, torch.Tensor) else np.copy(self.xyxyxyxy) + xyxyxyxyn[..., 0] /= self.orig_shape[1] + xyxyxyxyn[..., 1] /= self.orig_shape[0] + return xyxyxyxyn + + @property + @lru_cache(maxsize=2) + def xyxy(self): + """ + Return the horizontal boxes in xyxy format, (N, 4). + + Accepts both torch and numpy boxes. + """ + x1 = self.xyxyxyxy[..., 0].min(1).values + x2 = self.xyxyxyxy[..., 0].max(1).values + y1 = self.xyxyxyxy[..., 1].min(1).values + y2 = self.xyxyxyxy[..., 1].max(1).values + xyxy = [x1, y1, x2, y2] + return np.stack(xyxy, axis=-1) if isinstance(self.data, np.ndarray) else torch.stack(xyxy, dim=-1) diff --git a/ultralytics/engine/trainer.py b/ultralytics/engine/trainer.py new file mode 100644 index 0000000..1af3721 --- /dev/null +++ b/ultralytics/engine/trainer.py @@ -0,0 +1,761 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +""" +Train a model on a dataset. + +Usage: + $ yolo mode=train model=yolov8n.pt data=coco128.yaml imgsz=640 epochs=100 batch=16 +""" + +import math +import os +import subprocess +import time +import warnings +from copy import deepcopy +from datetime import datetime, timedelta +from pathlib import Path + +import numpy as np +import torch +from torch import distributed as dist +from torch import nn, optim + +from ultralytics.cfg import get_cfg, get_save_dir +from ultralytics.data.utils import check_cls_dataset, check_det_dataset +from ultralytics.nn.tasks import attempt_load_one_weight, attempt_load_weights +from ultralytics.utils import ( + DEFAULT_CFG, + LOGGER, + RANK, + TQDM, + __version__, + callbacks, + clean_url, + colorstr, + emojis, + yaml_save, +) +from ultralytics.utils.autobatch import check_train_batch_size +from ultralytics.utils.checks import check_amp, check_file, check_imgsz, check_model_file_from_stem, print_args +from ultralytics.utils.dist import ddp_cleanup, generate_ddp_command +from ultralytics.utils.files import get_latest_run +from ultralytics.utils.torch_utils import ( + EarlyStopping, + ModelEMA, + convert_optimizer_state_dict_to_fp16, + init_seeds, + one_cycle, + select_device, + strip_optimizer, +) + + +class BaseTrainer: + """ + BaseTrainer. + + A base class for creating trainers. + + Attributes: + args (SimpleNamespace): Configuration for the trainer. + validator (BaseValidator): Validator instance. + model (nn.Module): Model instance. + callbacks (defaultdict): Dictionary of callbacks. + save_dir (Path): Directory to save results. + wdir (Path): Directory to save weights. + last (Path): Path to the last checkpoint. + best (Path): Path to the best checkpoint. + save_period (int): Save checkpoint every x epochs (disabled if < 1). + batch_size (int): Batch size for training. + epochs (int): Number of epochs to train for. + start_epoch (int): Starting epoch for training. + device (torch.device): Device to use for training. + amp (bool): Flag to enable AMP (Automatic Mixed Precision). + scaler (amp.GradScaler): Gradient scaler for AMP. + data (str): Path to data. + trainset (torch.utils.data.Dataset): Training dataset. + testset (torch.utils.data.Dataset): Testing dataset. + ema (nn.Module): EMA (Exponential Moving Average) of the model. + resume (bool): Resume training from a checkpoint. + lf (nn.Module): Loss function. + scheduler (torch.optim.lr_scheduler._LRScheduler): Learning rate scheduler. + best_fitness (float): The best fitness value achieved. + fitness (float): Current fitness value. + loss (float): Current loss value. + tloss (float): Total loss value. + loss_names (list): List of loss names. + csv (Path): Path to results CSV file. + """ + + def __init__(self, cfg=DEFAULT_CFG, overrides=None, _callbacks=None): + """ + Initializes the BaseTrainer class. + + Args: + cfg (str, optional): Path to a configuration file. Defaults to DEFAULT_CFG. + overrides (dict, optional): Configuration overrides. Defaults to None. + """ + self.args = get_cfg(cfg, overrides) + self.check_resume(overrides) + self.device = select_device(self.args.device, self.args.batch) + self.validator = None + self.metrics = None + self.plots = {} + init_seeds(self.args.seed + 1 + RANK, deterministic=self.args.deterministic) + + # Dirs + self.save_dir = get_save_dir(self.args) + self.args.name = self.save_dir.name # update name for loggers + self.wdir = self.save_dir / "weights" # weights dir + if RANK in {-1, 0}: + self.wdir.mkdir(parents=True, exist_ok=True) # make dir + self.args.save_dir = str(self.save_dir) + yaml_save(self.save_dir / "args.yaml", vars(self.args)) # save run args + self.last, self.best = self.wdir / "last.pt", self.wdir / "best.pt" # checkpoint paths + self.save_period = self.args.save_period + + self.batch_size = self.args.batch + self.epochs = self.args.epochs + self.start_epoch = 0 + if RANK == -1: + print_args(vars(self.args)) + + # Device + if self.device.type in {"cpu", "mps"}: + self.args.workers = 0 # faster CPU training as time dominated by inference, not dataloading + + # Model and Dataset + self.model = check_model_file_from_stem(self.args.model) # add suffix, i.e. yolov8n -> yolov8n.pt + self.trainset, self.testset = self.get_dataset() + self.ema = None + + # Optimization utils init + self.lf = None + self.scheduler = None + + # Epoch level metrics + self.best_fitness = None + self.fitness = None + self.loss = None + self.tloss = None + self.loss_names = ["Loss"] + self.csv = self.save_dir / "results.csv" + self.plot_idx = [0, 1, 2] + + # Callbacks + self.callbacks = _callbacks or callbacks.get_default_callbacks() + if RANK in {-1, 0}: + callbacks.add_integration_callbacks(self) + + def add_callback(self, event: str, callback): + """Appends the given callback.""" + self.callbacks[event].append(callback) + + def set_callback(self, event: str, callback): + """Overrides the existing callbacks with the given callback.""" + self.callbacks[event] = [callback] + + def run_callbacks(self, event: str): + """Run all existing callbacks associated with a particular event.""" + for callback in self.callbacks.get(event, []): + callback(self) + + def train(self): + """Allow device='', device=None on Multi-GPU systems to default to device=0.""" + if isinstance(self.args.device, str) and len(self.args.device): # i.e. device='0' or device='0,1,2,3' + world_size = len(self.args.device.split(",")) + elif isinstance(self.args.device, (tuple, list)): # i.e. device=[0, 1, 2, 3] (multi-GPU from CLI is list) + world_size = len(self.args.device) + elif torch.cuda.is_available(): # i.e. device=None or device='' or device=number + world_size = 1 # default to device 0 + else: # i.e. device='cpu' or 'mps' + world_size = 0 + + # Run subprocess if DDP training, else train normally + if world_size > 1 and "LOCAL_RANK" not in os.environ: + # Argument checks + if self.args.rect: + LOGGER.warning("WARNING ⚠️ 'rect=True' is incompatible with Multi-GPU training, setting 'rect=False'") + self.args.rect = False + if self.args.batch == -1: + LOGGER.warning( + "WARNING ⚠️ 'batch=-1' for AutoBatch is incompatible with Multi-GPU training, setting " + "default 'batch=16'" + ) + self.args.batch = 16 + + # Command + cmd, file = generate_ddp_command(world_size, self) + try: + LOGGER.info(f'{colorstr("DDP:")} debug command {" ".join(cmd)}') + subprocess.run(cmd, check=True) + except Exception as e: + raise e + finally: + ddp_cleanup(self, str(file)) + + else: + self._do_train(world_size) + + def _setup_scheduler(self): + """Initialize training learning rate scheduler.""" + if self.args.cos_lr: + self.lf = one_cycle(1, self.args.lrf, self.epochs) # cosine 1->hyp['lrf'] + else: + self.lf = lambda x: max(1 - x / self.epochs, 0) * (1.0 - self.args.lrf) + self.args.lrf # linear + self.scheduler = optim.lr_scheduler.LambdaLR(self.optimizer, lr_lambda=self.lf) + + def _setup_ddp(self, world_size): + """Initializes and sets the DistributedDataParallel parameters for training.""" + torch.cuda.set_device(RANK) + self.device = torch.device("cuda", RANK) + # LOGGER.info(f'DDP info: RANK {RANK}, WORLD_SIZE {world_size}, DEVICE {self.device}') + os.environ["TORCH_NCCL_BLOCKING_WAIT"] = "1" # set to enforce timeout + dist.init_process_group( + backend="nccl" if dist.is_nccl_available() else "gloo", + timeout=timedelta(seconds=10800), # 3 hours + rank=RANK, + world_size=world_size, + ) + + def _setup_train(self, world_size): + """Builds dataloaders and optimizer on correct rank process.""" + + # Model + self.run_callbacks("on_pretrain_routine_start") + ckpt = self.setup_model() + self.model = self.model.to(self.device) + self.set_model_attributes() + + # Freeze layers + freeze_list = ( + self.args.freeze + if isinstance(self.args.freeze, list) + else range(self.args.freeze) + if isinstance(self.args.freeze, int) + else [] + ) + always_freeze_names = [".dfl"] # always freeze these layers + freeze_layer_names = [f"model.{x}." for x in freeze_list] + always_freeze_names + for k, v in self.model.named_parameters(): + # v.register_hook(lambda x: torch.nan_to_num(x)) # NaN to 0 (commented for erratic training results) + if any(x in k for x in freeze_layer_names): + LOGGER.info(f"Freezing layer '{k}'") + v.requires_grad = False + elif not v.requires_grad and v.dtype.is_floating_point: # only floating point Tensor can require gradients + LOGGER.info( + f"WARNING ⚠️ setting 'requires_grad=True' for frozen layer '{k}'. " + "See ultralytics.engine.trainer for customization of frozen layers." + ) + v.requires_grad = True + + # Check AMP + self.amp = torch.tensor(self.args.amp).to(self.device) # True or False + if self.amp and RANK in {-1, 0}: # Single-GPU and DDP + callbacks_backup = callbacks.default_callbacks.copy() # backup callbacks as check_amp() resets them + self.amp = torch.tensor(check_amp(self.model), device=self.device) + callbacks.default_callbacks = callbacks_backup # restore callbacks + if RANK > -1 and world_size > 1: # DDP + dist.broadcast(self.amp, src=0) # broadcast the tensor from rank 0 to all other ranks (returns None) + self.amp = bool(self.amp) # as boolean + self.scaler = torch.cuda.amp.GradScaler(enabled=self.amp) + if world_size > 1: + self.model = nn.parallel.DistributedDataParallel(self.model, device_ids=[RANK]) + + # Check imgsz + gs = max(int(self.model.stride.max() if hasattr(self.model, "stride") else 32), 32) # grid size (max stride) + self.args.imgsz = check_imgsz(self.args.imgsz, stride=gs, floor=gs, max_dim=1) + self.stride = gs # for multiscale training + + # Batch size + if self.batch_size == -1 and RANK == -1: # single-GPU only, estimate best batch size + self.args.batch = self.batch_size = check_train_batch_size(self.model, self.args.imgsz, self.amp) + + # Dataloaders + batch_size = self.batch_size // max(world_size, 1) + self.train_loader = self.get_dataloader(self.trainset, batch_size=batch_size, rank=RANK, mode="train") + if RANK in {-1, 0}: + # Note: When training DOTA dataset, double batch size could get OOM on images with >2000 objects. + self.test_loader = self.get_dataloader( + self.testset, batch_size=batch_size if self.args.task == "obb" else batch_size * 2, rank=-1, mode="val" + ) + self.validator = self.get_validator() + metric_keys = self.validator.metrics.keys + self.label_loss_items(prefix="val") + self.metrics = dict(zip(metric_keys, [0] * len(metric_keys))) + self.ema = ModelEMA(self.model) + if self.args.plots: + self.plot_training_labels() + + # Optimizer + self.accumulate = max(round(self.args.nbs / self.batch_size), 1) # accumulate loss before optimizing + weight_decay = self.args.weight_decay * self.batch_size * self.accumulate / self.args.nbs # scale weight_decay + iterations = math.ceil(len(self.train_loader.dataset) / max(self.batch_size, self.args.nbs)) * self.epochs + self.optimizer = self.build_optimizer( + model=self.model, + name=self.args.optimizer, + lr=self.args.lr0, + momentum=self.args.momentum, + decay=weight_decay, + iterations=iterations, + ) + # Scheduler + self._setup_scheduler() + self.stopper, self.stop = EarlyStopping(patience=self.args.patience), False + self.resume_training(ckpt) + self.scheduler.last_epoch = self.start_epoch - 1 # do not move + self.run_callbacks("on_pretrain_routine_end") + + def _do_train(self, world_size=1): + """Train completed, evaluate and plot if specified by arguments.""" + if world_size > 1: + self._setup_ddp(world_size) + self._setup_train(world_size) + + nb = len(self.train_loader) # number of batches + nw = max(round(self.args.warmup_epochs * nb), 100) if self.args.warmup_epochs > 0 else -1 # warmup iterations + last_opt_step = -1 + self.epoch_time = None + self.epoch_time_start = time.time() + self.train_time_start = time.time() + self.run_callbacks("on_train_start") + LOGGER.info( + f'Image sizes {self.args.imgsz} train, {self.args.imgsz} val\n' + f'Using {self.train_loader.num_workers * (world_size or 1)} dataloader workers\n' + f"Logging results to {colorstr('bold', self.save_dir)}\n" + f'Starting training for ' + (f"{self.args.time} hours..." if self.args.time else f"{self.epochs} epochs...") + ) + if self.args.close_mosaic: + base_idx = (self.epochs - self.args.close_mosaic) * nb + self.plot_idx.extend([base_idx, base_idx + 1, base_idx + 2]) + epoch = self.start_epoch + while True: + self.epoch = epoch + self.run_callbacks("on_train_epoch_start") + with warnings.catch_warnings(): + warnings.simplefilter("ignore") # suppress 'Detected lr_scheduler.step() before optimizer.step()' + self.scheduler.step() + + self.model.train() + if RANK != -1: + self.train_loader.sampler.set_epoch(epoch) + pbar = enumerate(self.train_loader) + # Update dataloader attributes (optional) + if epoch == (self.epochs - self.args.close_mosaic): + self._close_dataloader_mosaic() + self.train_loader.reset() + + if RANK in {-1, 0}: + LOGGER.info(self.progress_string()) + pbar = TQDM(enumerate(self.train_loader), total=nb) + self.tloss = None + self.optimizer.zero_grad() + for i, batch in pbar: + self.run_callbacks("on_train_batch_start") + # Warmup + ni = i + nb * epoch + if ni <= nw: + xi = [0, nw] # x interp + self.accumulate = max(1, int(np.interp(ni, xi, [1, self.args.nbs / self.batch_size]).round())) + for j, x in enumerate(self.optimizer.param_groups): + # Bias lr falls from 0.1 to lr0, all other lrs rise from 0.0 to lr0 + x["lr"] = np.interp( + ni, xi, [self.args.warmup_bias_lr if j == 0 else 0.0, x["initial_lr"] * self.lf(epoch)] + ) + if "momentum" in x: + x["momentum"] = np.interp(ni, xi, [self.args.warmup_momentum, self.args.momentum]) + + # Forward + with torch.cuda.amp.autocast(self.amp): + batch = self.preprocess_batch(batch) + self.loss, self.loss_items = self.model(batch) + if RANK != -1: + self.loss *= world_size + self.tloss = ( + (self.tloss * i + self.loss_items) / (i + 1) if self.tloss is not None else self.loss_items + ) + + # Backward + self.scaler.scale(self.loss).backward() + + # Optimize - https://pytorch.org/docs/master/notes/amp_examples.html + if ni - last_opt_step >= self.accumulate: + self.optimizer_step() + last_opt_step = ni + + # Timed stopping + if self.args.time: + self.stop = (time.time() - self.train_time_start) > (self.args.time * 3600) + if RANK != -1: # if DDP training + broadcast_list = [self.stop if RANK == 0 else None] + dist.broadcast_object_list(broadcast_list, 0) # broadcast 'stop' to all ranks + self.stop = broadcast_list[0] + if self.stop: # training time exceeded + break + + # Log + mem = f"{torch.cuda.memory_reserved() / 1E9 if torch.cuda.is_available() else 0:.3g}G" # (GB) + loss_len = self.tloss.shape[0] if len(self.tloss.shape) else 1 + losses = self.tloss if loss_len > 1 else torch.unsqueeze(self.tloss, 0) + if RANK in {-1, 0}: + pbar.set_description( + ("%11s" * 2 + "%11.4g" * (2 + loss_len)) + % (f"{epoch + 1}/{self.epochs}", mem, *losses, batch["cls"].shape[0], batch["img"].shape[-1]) + ) + self.run_callbacks("on_batch_end") + if self.args.plots and ni in self.plot_idx: + self.plot_training_samples(batch, ni) + + self.run_callbacks("on_train_batch_end") + + self.lr = {f"lr/pg{ir}": x["lr"] for ir, x in enumerate(self.optimizer.param_groups)} # for loggers + self.run_callbacks("on_train_epoch_end") + if RANK in {-1, 0}: + final_epoch = epoch + 1 >= self.epochs + self.ema.update_attr(self.model, include=["yaml", "nc", "args", "names", "stride", "class_weights"]) + + # Validation + if self.args.val or final_epoch or self.stopper.possible_stop or self.stop: + self.metrics, self.fitness = self.validate() + self.save_metrics(metrics={**self.label_loss_items(self.tloss), **self.metrics, **self.lr}) + self.stop |= self.stopper(epoch + 1, self.fitness) or final_epoch + if self.args.time: + self.stop |= (time.time() - self.train_time_start) > (self.args.time * 3600) + + # Save model + if self.args.save or final_epoch: + self.save_model() + self.run_callbacks("on_model_save") + + # Scheduler + t = time.time() + self.epoch_time = t - self.epoch_time_start + self.epoch_time_start = t + if self.args.time: + mean_epoch_time = (t - self.train_time_start) / (epoch - self.start_epoch + 1) + self.epochs = self.args.epochs = math.ceil(self.args.time * 3600 / mean_epoch_time) + self._setup_scheduler() + self.scheduler.last_epoch = self.epoch # do not move + self.stop |= epoch >= self.epochs # stop if exceeded epochs + self.run_callbacks("on_fit_epoch_end") + torch.cuda.empty_cache() # clear GPU memory at end of epoch, may help reduce CUDA out of memory errors + + # Early Stopping + if RANK != -1: # if DDP training + broadcast_list = [self.stop if RANK == 0 else None] + dist.broadcast_object_list(broadcast_list, 0) # broadcast 'stop' to all ranks + self.stop = broadcast_list[0] + if self.stop: + break # must break all DDP ranks + epoch += 1 + + if RANK in {-1, 0}: + # Do final val with best.pt + LOGGER.info( + f"\n{epoch - self.start_epoch + 1} epochs completed in " + f"{(time.time() - self.train_time_start) / 3600:.3f} hours." + ) + self.final_eval() + if self.args.plots: + self.plot_metrics() + self.run_callbacks("on_train_end") + torch.cuda.empty_cache() + self.run_callbacks("teardown") + + def save_model(self): + """Save model training checkpoints with additional metadata.""" + import io + + import pandas as pd # scope for faster 'import ultralytics' + + # Serialize ckpt to a byte buffer once (faster than repeated torch.save() calls) + buffer = io.BytesIO() + torch.save( + { + "epoch": self.epoch, + "best_fitness": self.best_fitness, + "model": None, # resume and final checkpoints derive from EMA + "ema": deepcopy(self.ema.ema).half(), + "updates": self.ema.updates, + "optimizer": convert_optimizer_state_dict_to_fp16(deepcopy(self.optimizer.state_dict())), + "train_args": vars(self.args), # save as dict + "train_metrics": {**self.metrics, **{"fitness": self.fitness}}, + "train_results": {k.strip(): v for k, v in pd.read_csv(self.csv).to_dict(orient="list").items()}, + "date": datetime.now().isoformat(), + "version": __version__, + "license": "AGPL-3.0 (https://ultralytics.com/license)", + "docs": "https://docs.ultralytics.com", + }, + buffer, + ) + serialized_ckpt = buffer.getvalue() # get the serialized content to save + + # Save checkpoints + self.last.write_bytes(serialized_ckpt) # save last.pt + if self.best_fitness == self.fitness: + self.best.write_bytes(serialized_ckpt) # save best.pt + if (self.save_period > 0) and (self.epoch > 0) and (self.epoch % self.save_period == 0): + (self.wdir / f"epoch{self.epoch}.pt").write_bytes(serialized_ckpt) # save epoch, i.e. 'epoch3.pt' + + def get_dataset(self): + """ + Get train, val path from data dict if it exists. + + Returns None if data format is not recognized. + """ + try: + if self.args.task == "classify": + data = check_cls_dataset(self.args.data) + elif self.args.data.split(".")[-1] in {"yaml", "yml"} or self.args.task in { + "detect", + "segment", + "pose", + "obb", + }: + data = check_det_dataset(self.args.data) + if "yaml_file" in data: + self.args.data = data["yaml_file"] # for validating 'yolo train data=url.zip' usage + except Exception as e: + raise RuntimeError(emojis(f"Dataset '{clean_url(self.args.data)}' error ❌ {e}")) from e + self.data = data + return data["train"], data.get("val") or data.get("test") + + def setup_model(self): + """Load/create/download model for any task.""" + if isinstance(self.model, torch.nn.Module): # if model is loaded beforehand. No setup needed + return + + model, weights = self.model, None + ckpt = None + if str(model).endswith(".pt"): + weights, ckpt = attempt_load_one_weight(model) + cfg = weights.yaml + else: + cfg = model + self.model = self.get_model(cfg=cfg, weights=weights, verbose=RANK == -1) # calls Model(cfg, weights) + return ckpt + + def optimizer_step(self): + """Perform a single step of the training optimizer with gradient clipping and EMA update.""" + self.scaler.unscale_(self.optimizer) # unscale gradients + torch.nn.utils.clip_grad_norm_(self.model.parameters(), max_norm=10.0) # clip gradients + self.scaler.step(self.optimizer) + self.scaler.update() + self.optimizer.zero_grad() + if self.ema: + self.ema.update(self.model) + + def preprocess_batch(self, batch): + """Allows custom preprocessing model inputs and ground truths depending on task type.""" + return batch + + def validate(self): + """ + Runs validation on test set using self.validator. + + The returned dict is expected to contain "fitness" key. + """ + metrics = self.validator(self) + fitness = metrics.pop("fitness", -self.loss.detach().cpu().numpy()) # use loss as fitness measure if not found + if not self.best_fitness or self.best_fitness < fitness: + self.best_fitness = fitness + return metrics, fitness + + def get_model(self, cfg=None, weights=None, verbose=True): + """Get model and raise NotImplementedError for loading cfg files.""" + raise NotImplementedError("This task trainer doesn't support loading cfg files") + + def get_validator(self): + """Returns a NotImplementedError when the get_validator function is called.""" + raise NotImplementedError("get_validator function not implemented in trainer") + + def get_dataloader(self, dataset_path, batch_size=16, rank=0, mode="train"): + """Returns dataloader derived from torch.data.Dataloader.""" + raise NotImplementedError("get_dataloader function not implemented in trainer") + + def build_dataset(self, img_path, mode="train", batch=None): + """Build dataset.""" + raise NotImplementedError("build_dataset function not implemented in trainer") + + def label_loss_items(self, loss_items=None, prefix="train"): + """ + Returns a loss dict with labelled training loss items tensor. + + Note: + This is not needed for classification but necessary for segmentation & detection + """ + return {"loss": loss_items} if loss_items is not None else ["loss"] + + def set_model_attributes(self): + """To set or update model parameters before training.""" + self.model.names = self.data["names"] + + def build_targets(self, preds, targets): + """Builds target tensors for training YOLO model.""" + pass + + def progress_string(self): + """Returns a string describing training progress.""" + return "" + + # TODO: may need to put these following functions into callback + def plot_training_samples(self, batch, ni): + """Plots training samples during YOLO training.""" + pass + + def plot_training_labels(self): + """Plots training labels for YOLO model.""" + pass + + def save_metrics(self, metrics): + """Saves training metrics to a CSV file.""" + keys, vals = list(metrics.keys()), list(metrics.values()) + n = len(metrics) + 1 # number of cols + s = "" if self.csv.exists() else (("%23s," * n % tuple(["epoch"] + keys)).rstrip(",") + "\n") # header + with open(self.csv, "a") as f: + f.write(s + ("%23.5g," * n % tuple([self.epoch + 1] + vals)).rstrip(",") + "\n") + + def plot_metrics(self): + """Plot and display metrics visually.""" + pass + + def on_plot(self, name, data=None): + """Registers plots (e.g. to be consumed in callbacks)""" + path = Path(name) + self.plots[path] = {"data": data, "timestamp": time.time()} + + def final_eval(self): + """Performs final evaluation and validation for object detection YOLO model.""" + for f in self.last, self.best: + if f.exists(): + strip_optimizer(f) # strip optimizers + if f is self.best: + LOGGER.info(f"\nValidating {f}...") + self.validator.args.plots = self.args.plots + self.metrics = self.validator(model=f) + self.metrics.pop("fitness", None) + self.run_callbacks("on_fit_epoch_end") + + def check_resume(self, overrides): + """Check if resume checkpoint exists and update arguments accordingly.""" + resume = self.args.resume + if resume: + try: + exists = isinstance(resume, (str, Path)) and Path(resume).exists() + last = Path(check_file(resume) if exists else get_latest_run()) + + # Check that resume data YAML exists, otherwise strip to force re-download of dataset + ckpt_args = attempt_load_weights(last).args + if not Path(ckpt_args["data"]).exists(): + ckpt_args["data"] = self.args.data + + resume = True + self.args = get_cfg(ckpt_args) + self.args.model = self.args.resume = str(last) # reinstate model + for k in "imgsz", "batch", "device": # allow arg updates to reduce memory or update device on resume + if k in overrides: + setattr(self.args, k, overrides[k]) + + except Exception as e: + raise FileNotFoundError( + "Resume checkpoint not found. Please pass a valid checkpoint to resume from, " + "i.e. 'yolo train resume model=path/to/last.pt'" + ) from e + self.resume = resume + + def resume_training(self, ckpt): + """Resume YOLO training from given epoch and best fitness.""" + if ckpt is None or not self.resume: + return + best_fitness = 0.0 + start_epoch = ckpt.get("epoch", -1) + 1 + if ckpt.get("optimizer", None) is not None: + self.optimizer.load_state_dict(ckpt["optimizer"]) # optimizer + best_fitness = ckpt["best_fitness"] + if self.ema and ckpt.get("ema"): + self.ema.ema.load_state_dict(ckpt["ema"].float().state_dict()) # EMA + self.ema.updates = ckpt["updates"] + assert start_epoch > 0, ( + f"{self.args.model} training to {self.epochs} epochs is finished, nothing to resume.\n" + f"Start a new training without resuming, i.e. 'yolo train model={self.args.model}'" + ) + LOGGER.info(f"Resuming training {self.args.model} from epoch {start_epoch + 1} to {self.epochs} total epochs") + if self.epochs < start_epoch: + LOGGER.info( + f"{self.model} has been trained for {ckpt['epoch']} epochs. Fine-tuning for {self.epochs} more epochs." + ) + self.epochs += ckpt["epoch"] # finetune additional epochs + self.best_fitness = best_fitness + self.start_epoch = start_epoch + if start_epoch > (self.epochs - self.args.close_mosaic): + self._close_dataloader_mosaic() + + def _close_dataloader_mosaic(self): + """Update dataloaders to stop using mosaic augmentation.""" + if hasattr(self.train_loader.dataset, "mosaic"): + self.train_loader.dataset.mosaic = False + if hasattr(self.train_loader.dataset, "close_mosaic"): + LOGGER.info("Closing dataloader mosaic") + self.train_loader.dataset.close_mosaic(hyp=self.args) + + def build_optimizer(self, model, name="auto", lr=0.001, momentum=0.9, decay=1e-5, iterations=1e5): + """ + Constructs an optimizer for the given model, based on the specified optimizer name, learning rate, momentum, + weight decay, and number of iterations. + + Args: + model (torch.nn.Module): The model for which to build an optimizer. + name (str, optional): The name of the optimizer to use. If 'auto', the optimizer is selected + based on the number of iterations. Default: 'auto'. + lr (float, optional): The learning rate for the optimizer. Default: 0.001. + momentum (float, optional): The momentum factor for the optimizer. Default: 0.9. + decay (float, optional): The weight decay for the optimizer. Default: 1e-5. + iterations (float, optional): The number of iterations, which determines the optimizer if + name is 'auto'. Default: 1e5. + + Returns: + (torch.optim.Optimizer): The constructed optimizer. + """ + + g = [], [], [] # optimizer parameter groups + bn = tuple(v for k, v in nn.__dict__.items() if "Norm" in k) # normalization layers, i.e. BatchNorm2d() + if name == "auto": + LOGGER.info( + f"{colorstr('optimizer:')} 'optimizer=auto' found, " + f"ignoring 'lr0={self.args.lr0}' and 'momentum={self.args.momentum}' and " + f"determining best 'optimizer', 'lr0' and 'momentum' automatically... " + ) + nc = getattr(model, "nc", 10) # number of classes + lr_fit = round(0.002 * 5 / (4 + nc), 6) # lr0 fit equation to 6 decimal places + name, lr, momentum = ("SGD", 0.01, 0.9) if iterations > 10000 else ("AdamW", lr_fit, 0.9) + self.args.warmup_bias_lr = 0.0 # no higher than 0.01 for Adam + + for module_name, module in model.named_modules(): + for param_name, param in module.named_parameters(recurse=False): + fullname = f"{module_name}.{param_name}" if module_name else param_name + if "bias" in fullname: # bias (no decay) + g[2].append(param) + elif isinstance(module, bn): # weight (no decay) + g[1].append(param) + else: # weight (with decay) + g[0].append(param) + + if name in {"Adam", "Adamax", "AdamW", "NAdam", "RAdam"}: + optimizer = getattr(optim, name, optim.Adam)(g[2], lr=lr, betas=(momentum, 0.999), weight_decay=0.0) + elif name == "RMSProp": + optimizer = optim.RMSprop(g[2], lr=lr, momentum=momentum) + elif name == "SGD": + optimizer = optim.SGD(g[2], lr=lr, momentum=momentum, nesterov=True) + else: + raise NotImplementedError( + f"Optimizer '{name}' not found in list of available optimizers " + f"[Adam, AdamW, NAdam, RAdam, RMSProp, SGD, auto]." + "To request support for addition optimizers please visit https://github.com/ultralytics/ultralytics." + ) + + optimizer.add_param_group({"params": g[0], "weight_decay": decay}) # add g0 with weight_decay + optimizer.add_param_group({"params": g[1], "weight_decay": 0.0}) # add g1 (BatchNorm2d weights) + LOGGER.info( + f"{colorstr('optimizer:')} {type(optimizer).__name__}(lr={lr}, momentum={momentum}) with parameter groups " + f'{len(g[1])} weight(decay=0.0), {len(g[0])} weight(decay={decay}), {len(g[2])} bias(decay=0.0)' + ) + return optimizer diff --git a/ultralytics/engine/tuner.py b/ultralytics/engine/tuner.py new file mode 100644 index 0000000..7fc1897 --- /dev/null +++ b/ultralytics/engine/tuner.py @@ -0,0 +1,242 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +""" +This module provides functionalities for hyperparameter tuning of the Ultralytics YOLO models for object detection, +instance segmentation, image classification, pose estimation, and multi-object tracking. + +Hyperparameter tuning is the process of systematically searching for the optimal set of hyperparameters +that yield the best model performance. This is particularly crucial in deep learning models like YOLO, +where small changes in hyperparameters can lead to significant differences in model accuracy and efficiency. + +Example: + Tune hyperparameters for YOLOv8n on COCO8 at imgsz=640 and epochs=30 for 300 tuning iterations. + ```python + from ultralytics import YOLO + + model = YOLO('yolov8n.pt') + model.tune(data='coco8.yaml', epochs=10, iterations=300, optimizer='AdamW', plots=False, save=False, val=False) + ``` +""" + +import random +import shutil +import subprocess +import time + +import numpy as np +import torch + +from ultralytics.cfg import get_cfg, get_save_dir +from ultralytics.utils import DEFAULT_CFG, LOGGER, callbacks, colorstr, remove_colorstr, yaml_print, yaml_save +from ultralytics.utils.plotting import plot_tune_results + + +class Tuner: + """ + Class responsible for hyperparameter tuning of YOLO models. + + The class evolves YOLO model hyperparameters over a given number of iterations + by mutating them according to the search space and retraining the model to evaluate their performance. + + Attributes: + space (dict): Hyperparameter search space containing bounds and scaling factors for mutation. + tune_dir (Path): Directory where evolution logs and results will be saved. + tune_csv (Path): Path to the CSV file where evolution logs are saved. + + Methods: + _mutate(hyp: dict) -> dict: + Mutates the given hyperparameters within the bounds specified in `self.space`. + + __call__(): + Executes the hyperparameter evolution across multiple iterations. + + Example: + Tune hyperparameters for YOLOv8n on COCO8 at imgsz=640 and epochs=30 for 300 tuning iterations. + ```python + from ultralytics import YOLO + + model = YOLO('yolov8n.pt') + model.tune(data='coco8.yaml', epochs=10, iterations=300, optimizer='AdamW', plots=False, save=False, val=False) + ``` + + Tune with custom search space. + ```python + from ultralytics import YOLO + + model = YOLO('yolov8n.pt') + model.tune(space={key1: val1, key2: val2}) # custom search space dictionary + ``` + """ + + def __init__(self, args=DEFAULT_CFG, _callbacks=None): + """ + Initialize the Tuner with configurations. + + Args: + args (dict, optional): Configuration for hyperparameter evolution. + """ + self.space = args.pop("space", None) or { # key: (min, max, gain(optional)) + # 'optimizer': tune.choice(['SGD', 'Adam', 'AdamW', 'NAdam', 'RAdam', 'RMSProp']), + "lr0": (1e-5, 1e-1), # initial learning rate (i.e. SGD=1E-2, Adam=1E-3) + "lrf": (0.0001, 0.1), # final OneCycleLR learning rate (lr0 * lrf) + "momentum": (0.7, 0.98, 0.3), # SGD momentum/Adam beta1 + "weight_decay": (0.0, 0.001), # optimizer weight decay 5e-4 + "warmup_epochs": (0.0, 5.0), # warmup epochs (fractions ok) + "warmup_momentum": (0.0, 0.95), # warmup initial momentum + "box": (1.0, 20.0), # box loss gain + "cls": (0.2, 4.0), # cls loss gain (scale with pixels) + "dfl": (0.4, 6.0), # dfl loss gain + "hsv_h": (0.0, 0.1), # image HSV-Hue augmentation (fraction) + "hsv_s": (0.0, 0.9), # image HSV-Saturation augmentation (fraction) + "hsv_v": (0.0, 0.9), # image HSV-Value augmentation (fraction) + "degrees": (0.0, 45.0), # image rotation (+/- deg) + "translate": (0.0, 0.9), # image translation (+/- fraction) + "scale": (0.0, 0.95), # image scale (+/- gain) + "shear": (0.0, 10.0), # image shear (+/- deg) + "perspective": (0.0, 0.001), # image perspective (+/- fraction), range 0-0.001 + "flipud": (0.0, 1.0), # image flip up-down (probability) + "fliplr": (0.0, 1.0), # image flip left-right (probability) + "bgr": (0.0, 1.0), # image channel bgr (probability) + "mosaic": (0.0, 1.0), # image mixup (probability) + "mixup": (0.0, 1.0), # image mixup (probability) + "copy_paste": (0.0, 1.0), # segment copy-paste (probability) + } + self.args = get_cfg(overrides=args) + self.tune_dir = get_save_dir(self.args, name="tune") + self.tune_csv = self.tune_dir / "tune_results.csv" + self.callbacks = _callbacks or callbacks.get_default_callbacks() + self.prefix = colorstr("Tuner: ") + callbacks.add_integration_callbacks(self) + LOGGER.info( + f"{self.prefix}Initialized Tuner instance with 'tune_dir={self.tune_dir}'\n" + f"{self.prefix}💡 Learn about tuning at https://docs.ultralytics.com/guides/hyperparameter-tuning" + ) + + def _mutate(self, parent="single", n=5, mutation=0.8, sigma=0.2): + """ + Mutates the hyperparameters based on bounds and scaling factors specified in `self.space`. + + Args: + parent (str): Parent selection method: 'single' or 'weighted'. + n (int): Number of parents to consider. + mutation (float): Probability of a parameter mutation in any given iteration. + sigma (float): Standard deviation for Gaussian random number generator. + + Returns: + (dict): A dictionary containing mutated hyperparameters. + """ + if self.tune_csv.exists(): # if CSV file exists: select best hyps and mutate + # Select parent(s) + x = np.loadtxt(self.tune_csv, ndmin=2, delimiter=",", skiprows=1) + fitness = x[:, 0] # first column + n = min(n, len(x)) # number of previous results to consider + x = x[np.argsort(-fitness)][:n] # top n mutations + w = x[:, 0] - x[:, 0].min() + 1e-6 # weights (sum > 0) + if parent == "single" or len(x) == 1: + # x = x[random.randint(0, n - 1)] # random selection + x = x[random.choices(range(n), weights=w)[0]] # weighted selection + elif parent == "weighted": + x = (x * w.reshape(n, 1)).sum(0) / w.sum() # weighted combination + + # Mutate + r = np.random # method + r.seed(int(time.time())) + g = np.array([v[2] if len(v) == 3 else 1.0 for k, v in self.space.items()]) # gains 0-1 + ng = len(self.space) + v = np.ones(ng) + while all(v == 1): # mutate until a change occurs (prevent duplicates) + v = (g * (r.random(ng) < mutation) * r.randn(ng) * r.random() * sigma + 1).clip(0.3, 3.0) + hyp = {k: float(x[i + 1] * v[i]) for i, k in enumerate(self.space.keys())} + else: + hyp = {k: getattr(self.args, k) for k in self.space.keys()} + + # Constrain to limits + for k, v in self.space.items(): + hyp[k] = max(hyp[k], v[0]) # lower limit + hyp[k] = min(hyp[k], v[1]) # upper limit + hyp[k] = round(hyp[k], 5) # significant digits + + return hyp + + def __call__(self, model=None, iterations=10, cleanup=True): + """ + Executes the hyperparameter evolution process when the Tuner instance is called. + + This method iterates through the number of iterations, performing the following steps in each iteration: + 1. Load the existing hyperparameters or initialize new ones. + 2. Mutate the hyperparameters using the `mutate` method. + 3. Train a YOLO model with the mutated hyperparameters. + 4. Log the fitness score and mutated hyperparameters to a CSV file. + + Args: + model (Model): A pre-initialized YOLO model to be used for training. + iterations (int): The number of generations to run the evolution for. + cleanup (bool): Whether to delete iteration weights to reduce storage space used during tuning. + + Note: + The method utilizes the `self.tune_csv` Path object to read and log hyperparameters and fitness scores. + Ensure this path is set correctly in the Tuner instance. + """ + + t0 = time.time() + best_save_dir, best_metrics = None, None + (self.tune_dir / "weights").mkdir(parents=True, exist_ok=True) + for i in range(iterations): + # Mutate hyperparameters + mutated_hyp = self._mutate() + LOGGER.info(f"{self.prefix}Starting iteration {i + 1}/{iterations} with hyperparameters: {mutated_hyp}") + + metrics = {} + train_args = {**vars(self.args), **mutated_hyp} + save_dir = get_save_dir(get_cfg(train_args)) + weights_dir = save_dir / "weights" + try: + # Train YOLO model with mutated hyperparameters (run in subprocess to avoid dataloader hang) + cmd = ["yolo", "train", *(f"{k}={v}" for k, v in train_args.items())] + return_code = subprocess.run(cmd, check=True).returncode + ckpt_file = weights_dir / ("best.pt" if (weights_dir / "best.pt").exists() else "last.pt") + metrics = torch.load(ckpt_file)["train_metrics"] + assert return_code == 0, "training failed" + + except Exception as e: + LOGGER.warning(f"WARNING ❌️ training failure for hyperparameter tuning iteration {i + 1}\n{e}") + + # Save results and mutated_hyp to CSV + fitness = metrics.get("fitness", 0.0) + log_row = [round(fitness, 5)] + [mutated_hyp[k] for k in self.space.keys()] + headers = "" if self.tune_csv.exists() else (",".join(["fitness"] + list(self.space.keys())) + "\n") + with open(self.tune_csv, "a") as f: + f.write(headers + ",".join(map(str, log_row)) + "\n") + + # Get best results + x = np.loadtxt(self.tune_csv, ndmin=2, delimiter=",", skiprows=1) + fitness = x[:, 0] # first column + best_idx = fitness.argmax() + best_is_current = best_idx == i + if best_is_current: + best_save_dir = save_dir + best_metrics = {k: round(v, 5) for k, v in metrics.items()} + for ckpt in weights_dir.glob("*.pt"): + shutil.copy2(ckpt, self.tune_dir / "weights") + elif cleanup: + shutil.rmtree(weights_dir, ignore_errors=True) # remove iteration weights/ dir to reduce storage space + + # Plot tune results + plot_tune_results(self.tune_csv) + + # Save and print tune results + header = ( + f'{self.prefix}{i + 1}/{iterations} iterations complete ✅ ({time.time() - t0:.2f}s)\n' + f'{self.prefix}Results saved to {colorstr("bold", self.tune_dir)}\n' + f'{self.prefix}Best fitness={fitness[best_idx]} observed at iteration {best_idx + 1}\n' + f'{self.prefix}Best fitness metrics are {best_metrics}\n' + f'{self.prefix}Best fitness model is {best_save_dir}\n' + f'{self.prefix}Best fitness hyperparameters are printed below.\n' + ) + LOGGER.info("\n" + header) + data = {k: float(x[best_idx, i + 1]) for i, k in enumerate(self.space.keys())} + yaml_save( + self.tune_dir / "best_hyperparameters.yaml", + data=data, + header=remove_colorstr(header.replace(self.prefix, "# ")) + "\n", + ) + yaml_print(self.tune_dir / "best_hyperparameters.yaml") diff --git a/ultralytics/engine/validator.py b/ultralytics/engine/validator.py new file mode 100644 index 0000000..9e7b6c1 --- /dev/null +++ b/ultralytics/engine/validator.py @@ -0,0 +1,338 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +""" +Check a model's accuracy on a test or val split of a dataset. + +Usage: + $ yolo mode=val model=yolov8n.pt data=coco128.yaml imgsz=640 + +Usage - formats: + $ yolo mode=val model=yolov8n.pt # PyTorch + yolov8n.torchscript # TorchScript + yolov8n.onnx # ONNX Runtime or OpenCV DNN with dnn=True + yolov8n_openvino_model # OpenVINO + yolov8n.engine # TensorRT + yolov8n.mlpackage # CoreML (macOS-only) + yolov8n_saved_model # TensorFlow SavedModel + yolov8n.pb # TensorFlow GraphDef + yolov8n.tflite # TensorFlow Lite + yolov8n_edgetpu.tflite # TensorFlow Edge TPU + yolov8n_paddle_model # PaddlePaddle + yolov8n_ncnn_model # NCNN +""" + +import json +import time +from pathlib import Path + +import numpy as np +import torch + +from ultralytics.cfg import get_cfg, get_save_dir +from ultralytics.data.utils import check_cls_dataset, check_det_dataset +from ultralytics.nn.autobackend import AutoBackend +from ultralytics.utils import LOGGER, TQDM, callbacks, colorstr, emojis +from ultralytics.utils.checks import check_imgsz +from ultralytics.utils.ops import Profile +from ultralytics.utils.torch_utils import de_parallel, select_device, smart_inference_mode + + +class BaseValidator: + """ + BaseValidator. + + A base class for creating validators. + + Attributes: + args (SimpleNamespace): Configuration for the validator. + dataloader (DataLoader): Dataloader to use for validation. + pbar (tqdm): Progress bar to update during validation. + model (nn.Module): Model to validate. + data (dict): Data dictionary. + device (torch.device): Device to use for validation. + batch_i (int): Current batch index. + training (bool): Whether the model is in training mode. + names (dict): Class names. + seen: Records the number of images seen so far during validation. + stats: Placeholder for statistics during validation. + confusion_matrix: Placeholder for a confusion matrix. + nc: Number of classes. + iouv: (torch.Tensor): IoU thresholds from 0.50 to 0.95 in spaces of 0.05. + jdict (dict): Dictionary to store JSON validation results. + speed (dict): Dictionary with keys 'preprocess', 'inference', 'loss', 'postprocess' and their respective + batch processing times in milliseconds. + save_dir (Path): Directory to save results. + plots (dict): Dictionary to store plots for visualization. + callbacks (dict): Dictionary to store various callback functions. + """ + + def __init__(self, dataloader=None, save_dir=None, pbar=None, args=None, _callbacks=None): + """ + Initializes a BaseValidator instance. + + Args: + dataloader (torch.utils.data.DataLoader): Dataloader to be used for validation. + save_dir (Path, optional): Directory to save results. + pbar (tqdm.tqdm): Progress bar for displaying progress. + args (SimpleNamespace): Configuration for the validator. + _callbacks (dict): Dictionary to store various callback functions. + """ + self.args = get_cfg(overrides=args) + self.dataloader = dataloader + self.pbar = pbar + self.stride = None + self.data = None + self.device = None + self.batch_i = None + self.training = True + self.names = None + self.seen = None + self.stats = None + self.confusion_matrix = None + self.nc = None + self.iouv = None + self.jdict = None + self.speed = {"preprocess": 0.0, "inference": 0.0, "loss": 0.0, "postprocess": 0.0} + + self.save_dir = save_dir or get_save_dir(self.args) + (self.save_dir / "labels" if self.args.save_txt else self.save_dir).mkdir(parents=True, exist_ok=True) + if self.args.conf is None: + self.args.conf = 0.001 # default conf=0.001 + self.args.imgsz = check_imgsz(self.args.imgsz, max_dim=1) + + self.plots = {} + self.callbacks = _callbacks or callbacks.get_default_callbacks() + + @smart_inference_mode() + def __call__(self, trainer=None, model=None): + """Supports validation of a pre-trained model if passed or a model being trained if trainer is passed (trainer + gets priority). + """ + self.training = trainer is not None + augment = self.args.augment and (not self.training) + if self.training: + self.device = trainer.device + self.data = trainer.data + self.args.half = self.device.type != "cpu" # force FP16 val during training + model = trainer.ema.ema or trainer.model + model = model.half() if self.args.half else model.float() + # self.model = model + self.loss = torch.zeros_like(trainer.loss_items, device=trainer.device) + self.args.plots &= trainer.stopper.possible_stop or (trainer.epoch == trainer.epochs - 1) + model.eval() + else: + callbacks.add_integration_callbacks(self) + model = AutoBackend( + weights=model or self.args.model, + device=select_device(self.args.device, self.args.batch), + dnn=self.args.dnn, + data=self.args.data, + fp16=self.args.half, + ) + # self.model = model + self.device = model.device # update device + self.args.half = model.fp16 # update half + stride, pt, jit, engine = model.stride, model.pt, model.jit, model.engine + imgsz = check_imgsz(self.args.imgsz, stride=stride) + if engine: + self.args.batch = model.batch_size + elif not pt and not jit: + self.args.batch = 1 # export.py models default to batch-size 1 + LOGGER.info(f"Forcing batch=1 square inference (1,3,{imgsz},{imgsz}) for non-PyTorch models") + + if str(self.args.data).split(".")[-1] in {"yaml", "yml"}: + self.data = check_det_dataset(self.args.data) + elif self.args.task == "classify": + self.data = check_cls_dataset(self.args.data, split=self.args.split) + else: + raise FileNotFoundError(emojis(f"Dataset '{self.args.data}' for task={self.args.task} not found ❌")) + + if self.device.type in {"cpu", "mps"}: + self.args.workers = 0 # faster CPU val as time dominated by inference, not dataloading + if not pt: + self.args.rect = False + self.stride = model.stride # used in get_dataloader() for padding + self.dataloader = self.dataloader or self.get_dataloader(self.data.get(self.args.split), self.args.batch) + + model.eval() + model.warmup(imgsz=(1 if pt else self.args.batch, 3, imgsz, imgsz)) # warmup + + self.run_callbacks("on_val_start") + dt = ( + Profile(device=self.device), + Profile(device=self.device), + Profile(device=self.device), + Profile(device=self.device), + ) + bar = TQDM(self.dataloader, desc=self.get_desc(), total=len(self.dataloader)) + self.init_metrics(de_parallel(model)) + self.jdict = [] # empty before each val + for batch_i, batch in enumerate(bar): + self.run_callbacks("on_val_batch_start") + self.batch_i = batch_i + # Preprocess + with dt[0]: + batch = self.preprocess(batch) + + # Inference + with dt[1]: + preds = model(batch["img"], augment=augment) + + # Loss + with dt[2]: + if self.training: + self.loss += model.loss(batch, preds)[1] + + # Postprocess + with dt[3]: + preds = self.postprocess(preds) + + self.update_metrics(preds, batch) + if self.args.plots and batch_i < 3: + self.plot_val_samples(batch, batch_i) + self.plot_predictions(batch, preds, batch_i) + + self.run_callbacks("on_val_batch_end") + stats = self.get_stats() + self.check_stats(stats) + self.speed = dict(zip(self.speed.keys(), (x.t / len(self.dataloader.dataset) * 1e3 for x in dt))) + self.finalize_metrics() + self.print_results() + self.run_callbacks("on_val_end") + if self.training: + model.float() + results = {**stats, **trainer.label_loss_items(self.loss.cpu() / len(self.dataloader), prefix="val")} + return {k: round(float(v), 5) for k, v in results.items()} # return results as 5 decimal place floats + else: + LOGGER.info( + "Speed: %.1fms preprocess, %.1fms inference, %.1fms loss, %.1fms postprocess per image" + % tuple(self.speed.values()) + ) + if self.args.save_json and self.jdict: + with open(str(self.save_dir / "predictions.json"), "w") as f: + LOGGER.info(f"Saving {f.name}...") + json.dump(self.jdict, f) # flatten and save + stats = self.eval_json(stats) # update stats + if self.args.plots or self.args.save_json: + LOGGER.info(f"Results saved to {colorstr('bold', self.save_dir)}") + return stats + + def match_predictions(self, pred_classes, true_classes, iou, use_scipy=False): + """ + Matches predictions to ground truth objects (pred_classes, true_classes) using IoU. + + Args: + pred_classes (torch.Tensor): Predicted class indices of shape(N,). + true_classes (torch.Tensor): Target class indices of shape(M,). + iou (torch.Tensor): An NxM tensor containing the pairwise IoU values for predictions and ground of truth + use_scipy (bool): Whether to use scipy for matching (more precise). + + Returns: + (torch.Tensor): Correct tensor of shape(N,10) for 10 IoU thresholds. + """ + # Dx10 matrix, where D - detections, 10 - IoU thresholds + correct = np.zeros((pred_classes.shape[0], self.iouv.shape[0])).astype(bool) + # LxD matrix where L - labels (rows), D - detections (columns) + correct_class = true_classes[:, None] == pred_classes + iou = iou * correct_class # zero out the wrong classes + iou = iou.cpu().numpy() + for i, threshold in enumerate(self.iouv.cpu().tolist()): + if use_scipy: + # WARNING: known issue that reduces mAP in https://github.com/ultralytics/ultralytics/pull/4708 + import scipy # scope import to avoid importing for all commands + + cost_matrix = iou * (iou >= threshold) + if cost_matrix.any(): + labels_idx, detections_idx = scipy.optimize.linear_sum_assignment(cost_matrix, maximize=True) + valid = cost_matrix[labels_idx, detections_idx] > 0 + if valid.any(): + correct[detections_idx[valid], i] = True + else: + matches = np.nonzero(iou >= threshold) # IoU > threshold and classes match + matches = np.array(matches).T + if matches.shape[0]: + if matches.shape[0] > 1: + matches = matches[iou[matches[:, 0], matches[:, 1]].argsort()[::-1]] + matches = matches[np.unique(matches[:, 1], return_index=True)[1]] + # matches = matches[matches[:, 2].argsort()[::-1]] + matches = matches[np.unique(matches[:, 0], return_index=True)[1]] + correct[matches[:, 1].astype(int), i] = True + return torch.tensor(correct, dtype=torch.bool, device=pred_classes.device) + + def add_callback(self, event: str, callback): + """Appends the given callback.""" + self.callbacks[event].append(callback) + + def run_callbacks(self, event: str): + """Runs all callbacks associated with a specified event.""" + for callback in self.callbacks.get(event, []): + callback(self) + + def get_dataloader(self, dataset_path, batch_size): + """Get data loader from dataset path and batch size.""" + raise NotImplementedError("get_dataloader function not implemented for this validator") + + def build_dataset(self, img_path): + """Build dataset.""" + raise NotImplementedError("build_dataset function not implemented in validator") + + def preprocess(self, batch): + """Preprocesses an input batch.""" + return batch + + def postprocess(self, preds): + """Describes and summarizes the purpose of 'postprocess()' but no details mentioned.""" + return preds + + def init_metrics(self, model): + """Initialize performance metrics for the YOLO model.""" + pass + + def update_metrics(self, preds, batch): + """Updates metrics based on predictions and batch.""" + pass + + def finalize_metrics(self, *args, **kwargs): + """Finalizes and returns all metrics.""" + pass + + def get_stats(self): + """Returns statistics about the model's performance.""" + return {} + + def check_stats(self, stats): + """Checks statistics.""" + pass + + def print_results(self): + """Prints the results of the model's predictions.""" + pass + + def get_desc(self): + """Get description of the YOLO model.""" + pass + + @property + def metric_keys(self): + """Returns the metric keys used in YOLO training/validation.""" + return [] + + def on_plot(self, name, data=None): + """Registers plots (e.g. to be consumed in callbacks)""" + self.plots[Path(name)] = {"data": data, "timestamp": time.time()} + + # TODO: may need to put these following functions into callback + def plot_val_samples(self, batch, ni): + """Plots validation samples during training.""" + pass + + def plot_predictions(self, batch, preds, ni): + """Plots YOLO model predictions on batch images.""" + pass + + def pred_to_json(self, preds, batch): + """Convert predictions to JSON format.""" + pass + + def eval_json(self, stats): + """Evaluate and return JSON format of prediction statistics.""" + pass diff --git a/ultralytics/hub/__init__.py b/ultralytics/hub/__init__.py new file mode 100644 index 0000000..4ea2fff --- /dev/null +++ b/ultralytics/hub/__init__.py @@ -0,0 +1,128 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import requests + +from ultralytics.data.utils import HUBDatasetStats +from ultralytics.hub.auth import Auth +from ultralytics.hub.utils import HUB_API_ROOT, HUB_WEB_ROOT, PREFIX +from ultralytics.utils import LOGGER, SETTINGS, checks + + +def login(api_key: str = None, save=True) -> bool: + """ + Log in to the Ultralytics HUB API using the provided API key. + + The session is not stored; a new session is created when needed using the saved SETTINGS or the HUB_API_KEY + environment variable if successfully authenticated. + + Args: + api_key (str, optional): API key to use for authentication. + If not provided, it will be retrieved from SETTINGS or HUB_API_KEY environment variable. + save (bool, optional): Whether to save the API key to SETTINGS if authentication is successful. + + Returns: + (bool): True if authentication is successful, False otherwise. + """ + checks.check_requirements("hub-sdk>=0.0.6") + from hub_sdk import HUBClient + + api_key_url = f"{HUB_WEB_ROOT}/settings?tab=api+keys" # set the redirect URL + saved_key = SETTINGS.get("api_key") + active_key = api_key or saved_key + credentials = {"api_key": active_key} if active_key and active_key != "" else None # set credentials + + client = HUBClient(credentials) # initialize HUBClient + + if client.authenticated: + # Successfully authenticated with HUB + + if save and client.api_key != saved_key: + SETTINGS.update({"api_key": client.api_key}) # update settings with valid API key + + # Set message based on whether key was provided or retrieved from settings + log_message = ( + "New authentication successful ✅" if client.api_key == api_key or not credentials else "Authenticated ✅" + ) + LOGGER.info(f"{PREFIX}{log_message}") + + return True + else: + # Failed to authenticate with HUB + LOGGER.info(f"{PREFIX}Get API key from {api_key_url} and then run 'yolo hub login API_KEY'") + return False + + +def logout(): + """ + Log out of Ultralytics HUB by removing the API key from the settings file. To log in again, use 'yolo hub login'. + + Example: + ```python + from ultralytics import hub + + hub.logout() + ``` + """ + SETTINGS["api_key"] = "" + SETTINGS.save() + LOGGER.info(f"{PREFIX}logged out ✅. To log in again, use 'yolo hub login'.") + + +def reset_model(model_id=""): + """Reset a trained model to an untrained state.""" + r = requests.post(f"{HUB_API_ROOT}/model-reset", json={"modelId": model_id}, headers={"x-api-key": Auth().api_key}) + if r.status_code == 200: + LOGGER.info(f"{PREFIX}Model reset successfully") + return + LOGGER.warning(f"{PREFIX}Model reset failure {r.status_code} {r.reason}") + + +def export_fmts_hub(): + """Returns a list of HUB-supported export formats.""" + from ultralytics.engine.exporter import export_formats + + return list(export_formats()["Argument"][1:]) + ["ultralytics_tflite", "ultralytics_coreml"] + + +def export_model(model_id="", format="torchscript"): + """Export a model to all formats.""" + assert format in export_fmts_hub(), f"Unsupported export format '{format}', valid formats are {export_fmts_hub()}" + r = requests.post( + f"{HUB_API_ROOT}/v1/models/{model_id}/export", json={"format": format}, headers={"x-api-key": Auth().api_key} + ) + assert r.status_code == 200, f"{PREFIX}{format} export failure {r.status_code} {r.reason}" + LOGGER.info(f"{PREFIX}{format} export started ✅") + + +def get_export(model_id="", format="torchscript"): + """Get an exported model dictionary with download URL.""" + assert format in export_fmts_hub(), f"Unsupported export format '{format}', valid formats are {export_fmts_hub()}" + r = requests.post( + f"{HUB_API_ROOT}/get-export", + json={"apiKey": Auth().api_key, "modelId": model_id, "format": format}, + headers={"x-api-key": Auth().api_key}, + ) + assert r.status_code == 200, f"{PREFIX}{format} get_export failure {r.status_code} {r.reason}" + return r.json() + + +def check_dataset(path="", task="detect"): + """ + Function for error-checking HUB dataset Zip file before upload. It checks a dataset for errors before it is uploaded + to the HUB. Usage examples are given below. + + Args: + path (str, optional): Path to data.zip (with data.yaml inside data.zip). Defaults to ''. + task (str, optional): Dataset task. Options are 'detect', 'segment', 'pose', 'classify'. Defaults to 'detect'. + + Example: + ```python + from ultralytics.hub import check_dataset + + check_dataset('path/to/coco8.zip', task='detect') # detect dataset + check_dataset('path/to/coco8-seg.zip', task='segment') # segment dataset + check_dataset('path/to/coco8-pose.zip', task='pose') # pose dataset + ``` + """ + HUBDatasetStats(path=path, task=task).get_json() + LOGGER.info(f"Checks completed correctly ✅. Upload this dataset to {HUB_WEB_ROOT}/datasets/.") diff --git a/ultralytics/hub/auth.py b/ultralytics/hub/auth.py new file mode 100644 index 0000000..95da44e --- /dev/null +++ b/ultralytics/hub/auth.py @@ -0,0 +1,136 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import requests + +from ultralytics.hub.utils import HUB_API_ROOT, HUB_WEB_ROOT, PREFIX, request_with_credentials +from ultralytics.utils import IS_COLAB, LOGGER, SETTINGS, emojis + +API_KEY_URL = f"{HUB_WEB_ROOT}/settings?tab=api+keys" + + +class Auth: + """ + Manages authentication processes including API key handling, cookie-based authentication, and header generation. + + The class supports different methods of authentication: + 1. Directly using an API key. + 2. Authenticating using browser cookies (specifically in Google Colab). + 3. Prompting the user to enter an API key. + + Attributes: + id_token (str or bool): Token used for identity verification, initialized as False. + api_key (str or bool): API key for authentication, initialized as False. + model_key (bool): Placeholder for model key, initialized as False. + """ + + id_token = api_key = model_key = False + + def __init__(self, api_key="", verbose=False): + """ + Initialize the Auth class with an optional API key. + + Args: + api_key (str, optional): May be an API key or a combination API key and model ID, i.e. key_id + """ + # Split the input API key in case it contains a combined key_model and keep only the API key part + api_key = api_key.split("_")[0] + + # Set API key attribute as value passed or SETTINGS API key if none passed + self.api_key = api_key or SETTINGS.get("api_key", "") + + # If an API key is provided + if self.api_key: + # If the provided API key matches the API key in the SETTINGS + if self.api_key == SETTINGS.get("api_key"): + # Log that the user is already logged in + if verbose: + LOGGER.info(f"{PREFIX}Authenticated ✅") + return + else: + # Attempt to authenticate with the provided API key + success = self.authenticate() + # If the API key is not provided and the environment is a Google Colab notebook + elif IS_COLAB: + # Attempt to authenticate using browser cookies + success = self.auth_with_cookies() + else: + # Request an API key + success = self.request_api_key() + + # Update SETTINGS with the new API key after successful authentication + if success: + SETTINGS.update({"api_key": self.api_key}) + # Log that the new login was successful + if verbose: + LOGGER.info(f"{PREFIX}New authentication successful ✅") + elif verbose: + LOGGER.info(f"{PREFIX}Get API key from {API_KEY_URL} and then run 'yolo hub login API_KEY'") + + def request_api_key(self, max_attempts=3): + """ + Prompt the user to input their API key. + + Returns the model ID. + """ + import getpass + + for attempts in range(max_attempts): + LOGGER.info(f"{PREFIX}Login. Attempt {attempts + 1} of {max_attempts}") + input_key = getpass.getpass(f"Enter API key from {API_KEY_URL} ") + self.api_key = input_key.split("_")[0] # remove model id if present + if self.authenticate(): + return True + raise ConnectionError(emojis(f"{PREFIX}Failed to authenticate ❌")) + + def authenticate(self) -> bool: + """ + Attempt to authenticate with the server using either id_token or API key. + + Returns: + (bool): True if authentication is successful, False otherwise. + """ + try: + if header := self.get_auth_header(): + r = requests.post(f"{HUB_API_ROOT}/v1/auth", headers=header) + if not r.json().get("success", False): + raise ConnectionError("Unable to authenticate.") + return True + raise ConnectionError("User has not authenticated locally.") + except ConnectionError: + self.id_token = self.api_key = False # reset invalid + LOGGER.warning(f"{PREFIX}Invalid API key ⚠️") + return False + + def auth_with_cookies(self) -> bool: + """ + Attempt to fetch authentication via cookies and set id_token. User must be logged in to HUB and running in a + supported browser. + + Returns: + (bool): True if authentication is successful, False otherwise. + """ + if not IS_COLAB: + return False # Currently only works with Colab + try: + authn = request_with_credentials(f"{HUB_API_ROOT}/v1/auth/auto") + if authn.get("success", False): + self.id_token = authn.get("data", {}).get("idToken", None) + self.authenticate() + return True + raise ConnectionError("Unable to fetch browser authentication details.") + except ConnectionError: + self.id_token = False # reset invalid + return False + + def get_auth_header(self): + """ + Get the authentication header for making API requests. + + Returns: + (dict): The authentication header if id_token or API key is set, None otherwise. + """ + if self.id_token: + return {"authorization": f"Bearer {self.id_token}"} + elif self.api_key: + return {"x-api-key": self.api_key} + # else returns None diff --git a/ultralytics/hub/session.py b/ultralytics/hub/session.py new file mode 100644 index 0000000..3fb1b56 --- /dev/null +++ b/ultralytics/hub/session.py @@ -0,0 +1,372 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import threading +import time +from http import HTTPStatus +from pathlib import Path + +import requests + +from ultralytics.hub.utils import HELP_MSG, HUB_WEB_ROOT, PREFIX, TQDM +from ultralytics.utils import IS_COLAB, LOGGER, SETTINGS, __version__, checks, emojis +from ultralytics.utils.errors import HUBModelError + +AGENT_NAME = f"python-{__version__}-colab" if IS_COLAB else f"python-{__version__}-local" + + +class HUBTrainingSession: + """ + HUB training session for Ultralytics HUB YOLO models. Handles model initialization, heartbeats, and checkpointing. + + Attributes: + agent_id (str): Identifier for the instance communicating with the server. + model_id (str): Identifier for the YOLO model being trained. + model_url (str): URL for the model in Ultralytics HUB. + api_url (str): API URL for the model in Ultralytics HUB. + auth_header (dict): Authentication header for the Ultralytics HUB API requests. + rate_limits (dict): Rate limits for different API calls (in seconds). + timers (dict): Timers for rate limiting. + metrics_queue (dict): Queue for the model's metrics. + model (dict): Model data fetched from Ultralytics HUB. + alive (bool): Indicates if the heartbeat loop is active. + """ + + def __init__(self, identifier): + """ + Initialize the HUBTrainingSession with the provided model identifier. + + Args: + identifier (str): Model identifier used to initialize the HUB training session. + It can be a URL string or a model key with specific format. + + Raises: + ValueError: If the provided model identifier is invalid. + ConnectionError: If connecting with global API key is not supported. + ModuleNotFoundError: If hub-sdk package is not installed. + """ + from hub_sdk import HUBClient + + self.rate_limits = { + "metrics": 3.0, + "ckpt": 900.0, + "heartbeat": 300.0, + } # rate limits (seconds) + self.metrics_queue = {} # holds metrics for each epoch until upload + self.metrics_upload_failed_queue = {} # holds metrics for each epoch if upload failed + self.timers = {} # holds timers in ultralytics/utils/callbacks/hub.py + + # Parse input + api_key, model_id, self.filename = self._parse_identifier(identifier) + + # Get credentials + active_key = api_key or SETTINGS.get("api_key") + credentials = {"api_key": active_key} if active_key else None # set credentials + + # Initialize client + self.client = HUBClient(credentials) + + if model_id: + self.load_model(model_id) # load existing model + else: + self.model = self.client.model() # load empty model + + def load_model(self, model_id): + """Loads an existing model from Ultralytics HUB using the provided model identifier.""" + self.model = self.client.model(model_id) + if not self.model.data: # then model does not exist + raise ValueError(emojis("❌ The specified HUB model does not exist")) # TODO: improve error handling + + self.model_url = f"{HUB_WEB_ROOT}/models/{self.model.id}" + + self._set_train_args() + + # Start heartbeats for HUB to monitor agent + self.model.start_heartbeat(self.rate_limits["heartbeat"]) + LOGGER.info(f"{PREFIX}View model at {self.model_url} 🚀") + + def create_model(self, model_args): + """Initializes a HUB training session with the specified model identifier.""" + payload = { + "config": { + "batchSize": model_args.get("batch", -1), + "epochs": model_args.get("epochs", 300), + "imageSize": model_args.get("imgsz", 640), + "patience": model_args.get("patience", 100), + "device": model_args.get("device", ""), + "cache": model_args.get("cache", "ram"), + }, + "dataset": {"name": model_args.get("data")}, + "lineage": { + "architecture": { + "name": self.filename.replace(".pt", "").replace(".yaml", ""), + }, + "parent": {}, + }, + "meta": {"name": self.filename}, + } + + if self.filename.endswith(".pt"): + payload["lineage"]["parent"]["name"] = self.filename + + self.model.create_model(payload) + + # Model could not be created + # TODO: improve error handling + if not self.model.id: + return + + self.model_url = f"{HUB_WEB_ROOT}/models/{self.model.id}" + + # Start heartbeats for HUB to monitor agent + self.model.start_heartbeat(self.rate_limits["heartbeat"]) + + LOGGER.info(f"{PREFIX}View model at {self.model_url} 🚀") + + def _parse_identifier(self, identifier): + """ + Parses the given identifier to determine the type of identifier and extract relevant components. + + The method supports different identifier formats: + - A HUB URL, which starts with HUB_WEB_ROOT followed by '/models/' + - An identifier containing an API key and a model ID separated by an underscore + - An identifier that is solely a model ID of a fixed length + - A local filename that ends with '.pt' or '.yaml' + + Args: + identifier (str): The identifier string to be parsed. + + Returns: + (tuple): A tuple containing the API key, model ID, and filename as applicable. + + Raises: + HUBModelError: If the identifier format is not recognized. + """ + + # Initialize variables + api_key, model_id, filename = None, None, None + + # Check if identifier is a HUB URL + if identifier.startswith(f"{HUB_WEB_ROOT}/models/"): + # Extract the model_id after the HUB_WEB_ROOT URL + model_id = identifier.split(f"{HUB_WEB_ROOT}/models/")[-1] + else: + # Split the identifier based on underscores only if it's not a HUB URL + parts = identifier.split("_") + + # Check if identifier is in the format of API key and model ID + if len(parts) == 2 and len(parts[0]) == 42 and len(parts[1]) == 20: + api_key, model_id = parts + # Check if identifier is a single model ID + elif len(parts) == 1 and len(parts[0]) == 20: + model_id = parts[0] + # Check if identifier is a local filename + elif identifier.endswith(".pt") or identifier.endswith(".yaml"): + filename = identifier + else: + raise HUBModelError( + f"model='{identifier}' could not be parsed. Check format is correct. " + f"Supported formats are Ultralytics HUB URL, apiKey_modelId, modelId, local pt or yaml file." + ) + + return api_key, model_id, filename + + def _set_train_args(self): + """ + Initializes training arguments and creates a model entry on the Ultralytics HUB. + + This method sets up training arguments based on the model's state and updates them with any additional + arguments provided. It handles different states of the model, such as whether it's resumable, pretrained, + or requires specific file setup. + + Raises: + ValueError: If the model is already trained, if required dataset information is missing, or if there are + issues with the provided training arguments. + """ + if self.model.is_trained(): + raise ValueError(emojis(f"Model is already trained and uploaded to {self.model_url} 🚀")) + + if self.model.is_resumable(): + # Model has saved weights + self.train_args = {"data": self.model.get_dataset_url(), "resume": True} + self.model_file = self.model.get_weights_url("last") + else: + # Model has no saved weights + self.train_args = self.model.data.get("train_args") # new response + + # Set the model file as either a *.pt or *.yaml file + self.model_file = ( + self.model.get_weights_url("parent") if self.model.is_pretrained() else self.model.get_architecture() + ) + + if "data" not in self.train_args: + # RF bug - datasets are sometimes not exported + raise ValueError("Dataset may still be processing. Please wait a minute and try again.") + + self.model_file = checks.check_yolov5u_filename(self.model_file, verbose=False) # YOLOv5->YOLOv5u + self.model_id = self.model.id + + def request_queue( + self, + request_func, + retry=3, + timeout=30, + thread=True, + verbose=True, + progress_total=None, + stream_reponse=None, + *args, + **kwargs, + ): + def retry_request(): + """Attempts to call `request_func` with retries, timeout, and optional threading.""" + t0 = time.time() # Record the start time for the timeout + for i in range(retry + 1): + if (time.time() - t0) > timeout: + LOGGER.warning(f"{PREFIX}Timeout for request reached. {HELP_MSG}") + break # Timeout reached, exit loop + + response = request_func(*args, **kwargs) + if response is None: + LOGGER.warning(f"{PREFIX}Received no response from the request. {HELP_MSG}") + time.sleep(2**i) # Exponential backoff before retrying + continue # Skip further processing and retry + + if progress_total: + self._show_upload_progress(progress_total, response) + elif stream_reponse: + self._iterate_content(response) + + if HTTPStatus.OK <= response.status_code < HTTPStatus.MULTIPLE_CHOICES: + # if request related to metrics upload + if kwargs.get("metrics"): + self.metrics_upload_failed_queue = {} + return response # Success, no need to retry + + if i == 0: + # Initial attempt, check status code and provide messages + message = self._get_failure_message(response, retry, timeout) + + if verbose: + LOGGER.warning(f"{PREFIX}{message} {HELP_MSG} ({response.status_code})") + + if not self._should_retry(response.status_code): + LOGGER.warning(f"{PREFIX}Request failed. {HELP_MSG} ({response.status_code}") + break # Not an error that should be retried, exit loop + + time.sleep(2**i) # Exponential backoff for retries + + # if request related to metrics upload and exceed retries + if response is None and kwargs.get("metrics"): + self.metrics_upload_failed_queue.update(kwargs.get("metrics", None)) + + return response + + if thread: + # Start a new thread to run the retry_request function + threading.Thread(target=retry_request, daemon=True).start() + else: + # If running in the main thread, call retry_request directly + return retry_request() + + def _should_retry(self, status_code): + """Determines if a request should be retried based on the HTTP status code.""" + retry_codes = { + HTTPStatus.REQUEST_TIMEOUT, + HTTPStatus.BAD_GATEWAY, + HTTPStatus.GATEWAY_TIMEOUT, + } + return status_code in retry_codes + + def _get_failure_message(self, response: requests.Response, retry: int, timeout: int): + """ + Generate a retry message based on the response status code. + + Args: + response: The HTTP response object. + retry: The number of retry attempts allowed. + timeout: The maximum timeout duration. + + Returns: + (str): The retry message. + """ + if self._should_retry(response.status_code): + return f"Retrying {retry}x for {timeout}s." if retry else "" + elif response.status_code == HTTPStatus.TOO_MANY_REQUESTS: # rate limit + headers = response.headers + return ( + f"Rate limit reached ({headers['X-RateLimit-Remaining']}/{headers['X-RateLimit-Limit']}). " + f"Please retry after {headers['Retry-After']}s." + ) + else: + try: + return response.json().get("message", "No JSON message.") + except AttributeError: + return "Unable to read JSON." + + def upload_metrics(self): + """Upload model metrics to Ultralytics HUB.""" + return self.request_queue(self.model.upload_metrics, metrics=self.metrics_queue.copy(), thread=True) + + def upload_model( + self, + epoch: int, + weights: str, + is_best: bool = False, + map: float = 0.0, + final: bool = False, + ) -> None: + """ + Upload a model checkpoint to Ultralytics HUB. + + Args: + epoch (int): The current training epoch. + weights (str): Path to the model weights file. + is_best (bool): Indicates if the current model is the best one so far. + map (float): Mean average precision of the model. + final (bool): Indicates if the model is the final model after training. + """ + if Path(weights).is_file(): + progress_total = Path(weights).stat().st_size if final else None # Only show progress if final + self.request_queue( + self.model.upload_model, + epoch=epoch, + weights=weights, + is_best=is_best, + map=map, + final=final, + retry=10, + timeout=3600, + thread=not final, + progress_total=progress_total, + stream_reponse=True, + ) + else: + LOGGER.warning(f"{PREFIX}WARNING ⚠️ Model upload issue. Missing model {weights}.") + + def _show_upload_progress(self, content_length: int, response: requests.Response) -> None: + """ + Display a progress bar to track the upload progress of a file download. + + Args: + content_length (int): The total size of the content to be downloaded in bytes. + response (requests.Response): The response object from the file download request. + + Returns: + None + """ + with TQDM(total=content_length, unit="B", unit_scale=True, unit_divisor=1024) as pbar: + for data in response.iter_content(chunk_size=1024): + pbar.update(len(data)) + + def _iterate_content(self, response: requests.Response) -> None: + """ + Process the streamed HTTP response data. + + Args: + response (requests.Response): The response object from the file download request. + + Returns: + None + """ + for data in response.iter_content(chunk_size=1024): + pass # Do nothing with data chunks diff --git a/ultralytics/hub/utils.py b/ultralytics/hub/utils.py new file mode 100644 index 0000000..2e84c7d --- /dev/null +++ b/ultralytics/hub/utils.py @@ -0,0 +1,247 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import os +import platform +import random +import threading +import time +from pathlib import Path + +import requests + +from ultralytics.utils import ( + ARGV, + ENVIRONMENT, + IS_COLAB, + IS_GIT_DIR, + IS_PIP_PACKAGE, + LOGGER, + ONLINE, + RANK, + SETTINGS, + TESTS_RUNNING, + TQDM, + TryExcept, + __version__, + colorstr, + get_git_origin_url, +) +from ultralytics.utils.downloads import GITHUB_ASSETS_NAMES + +HUB_API_ROOT = os.environ.get("ULTRALYTICS_HUB_API", "https://api.ultralytics.com") +HUB_WEB_ROOT = os.environ.get("ULTRALYTICS_HUB_WEB", "https://hub.ultralytics.com") + +PREFIX = colorstr("Ultralytics HUB: ") +HELP_MSG = "If this issue persists please visit https://github.com/ultralytics/hub/issues for assistance." + + +def request_with_credentials(url: str) -> any: + """ + Make an AJAX request with cookies attached in a Google Colab environment. + + Args: + url (str): The URL to make the request to. + + Returns: + (any): The response data from the AJAX request. + + Raises: + OSError: If the function is not run in a Google Colab environment. + """ + if not IS_COLAB: + raise OSError("request_with_credentials() must run in a Colab environment") + from google.colab import output # noqa + from IPython import display # noqa + + display.display( + display.Javascript( + """ + window._hub_tmp = new Promise((resolve, reject) => { + const timeout = setTimeout(() => reject("Failed authenticating existing browser session"), 5000) + fetch("%s", { + method: 'POST', + credentials: 'include' + }) + .then((response) => resolve(response.json())) + .then((json) => { + clearTimeout(timeout); + }).catch((err) => { + clearTimeout(timeout); + reject(err); + }); + }); + """ + % url + ) + ) + return output.eval_js("_hub_tmp") + + +def requests_with_progress(method, url, **kwargs): + """ + Make an HTTP request using the specified method and URL, with an optional progress bar. + + Args: + method (str): The HTTP method to use (e.g. 'GET', 'POST'). + url (str): The URL to send the request to. + **kwargs (any): Additional keyword arguments to pass to the underlying `requests.request` function. + + Returns: + (requests.Response): The response object from the HTTP request. + + Note: + - If 'progress' is set to True, the progress bar will display the download progress for responses with a known + content length. + - If 'progress' is a number then progress bar will display assuming content length = progress. + """ + progress = kwargs.pop("progress", False) + if not progress: + return requests.request(method, url, **kwargs) + response = requests.request(method, url, stream=True, **kwargs) + total = int(response.headers.get("content-length", 0) if isinstance(progress, bool) else progress) # total size + try: + pbar = TQDM(total=total, unit="B", unit_scale=True, unit_divisor=1024) + for data in response.iter_content(chunk_size=1024): + pbar.update(len(data)) + pbar.close() + except requests.exceptions.ChunkedEncodingError: # avoid 'Connection broken: IncompleteRead' warnings + response.close() + return response + + +def smart_request(method, url, retry=3, timeout=30, thread=True, code=-1, verbose=True, progress=False, **kwargs): + """ + Makes an HTTP request using the 'requests' library, with exponential backoff retries up to a specified timeout. + + Args: + method (str): The HTTP method to use for the request. Choices are 'post' and 'get'. + url (str): The URL to make the request to. + retry (int, optional): Number of retries to attempt before giving up. Default is 3. + timeout (int, optional): Timeout in seconds after which the function will give up retrying. Default is 30. + thread (bool, optional): Whether to execute the request in a separate daemon thread. Default is True. + code (int, optional): An identifier for the request, used for logging purposes. Default is -1. + verbose (bool, optional): A flag to determine whether to print out to console or not. Default is True. + progress (bool, optional): Whether to show a progress bar during the request. Default is False. + **kwargs (any): Keyword arguments to be passed to the requests function specified in method. + + Returns: + (requests.Response): The HTTP response object. If the request is executed in a separate thread, returns None. + """ + retry_codes = (408, 500) # retry only these codes + + @TryExcept(verbose=verbose) + def func(func_method, func_url, **func_kwargs): + """Make HTTP requests with retries and timeouts, with optional progress tracking.""" + r = None # response + t0 = time.time() # initial time for timer + for i in range(retry + 1): + if (time.time() - t0) > timeout: + break + r = requests_with_progress(func_method, func_url, **func_kwargs) # i.e. get(url, data, json, files) + if r.status_code < 300: # return codes in the 2xx range are generally considered "good" or "successful" + break + try: + m = r.json().get("message", "No JSON message.") + except AttributeError: + m = "Unable to read JSON." + if i == 0: + if r.status_code in retry_codes: + m += f" Retrying {retry}x for {timeout}s." if retry else "" + elif r.status_code == 429: # rate limit + h = r.headers # response headers + m = ( + f"Rate limit reached ({h['X-RateLimit-Remaining']}/{h['X-RateLimit-Limit']}). " + f"Please retry after {h['Retry-After']}s." + ) + if verbose: + LOGGER.warning(f"{PREFIX}{m} {HELP_MSG} ({r.status_code} #{code})") + if r.status_code not in retry_codes: + return r + time.sleep(2**i) # exponential standoff + return r + + args = method, url + kwargs["progress"] = progress + if thread: + threading.Thread(target=func, args=args, kwargs=kwargs, daemon=True).start() + else: + return func(*args, **kwargs) + + +class Events: + """ + A class for collecting anonymous event analytics. Event analytics are enabled when sync=True in settings and + disabled when sync=False. Run 'yolo settings' to see and update settings YAML file. + + Attributes: + url (str): The URL to send anonymous events. + rate_limit (float): The rate limit in seconds for sending events. + metadata (dict): A dictionary containing metadata about the environment. + enabled (bool): A flag to enable or disable Events based on certain conditions. + """ + + url = "https://www.google-analytics.com/mp/collect?measurement_id=G-X8NCJYTQXM&api_secret=QLQrATrNSwGRFRLE-cbHJw" + + def __init__(self): + """Initializes the Events object with default values for events, rate_limit, and metadata.""" + self.events = [] # events list + self.rate_limit = 60.0 # rate limit (seconds) + self.t = 0.0 # rate limit timer (seconds) + self.metadata = { + "cli": Path(ARGV[0]).name == "yolo", + "install": "git" if IS_GIT_DIR else "pip" if IS_PIP_PACKAGE else "other", + "python": ".".join(platform.python_version_tuple()[:2]), # i.e. 3.10 + "version": __version__, + "env": ENVIRONMENT, + "session_id": round(random.random() * 1e15), + "engagement_time_msec": 1000, + } + self.enabled = ( + SETTINGS["sync"] + and RANK in {-1, 0} + and not TESTS_RUNNING + and ONLINE + and (IS_PIP_PACKAGE or get_git_origin_url() == "https://github.com/ultralytics/ultralytics.git") + ) + + def __call__(self, cfg): + """ + Attempts to add a new event to the events list and send events if the rate limit is reached. + + Args: + cfg (IterableSimpleNamespace): The configuration object containing mode and task information. + """ + if not self.enabled: + # Events disabled, do nothing + return + + # Attempt to add to events + if len(self.events) < 25: # Events list limited to 25 events (drop any events past this) + params = { + **self.metadata, + "task": cfg.task, + "model": cfg.model if cfg.model in GITHUB_ASSETS_NAMES else "custom", + } + if cfg.mode == "export": + params["format"] = cfg.format + self.events.append({"name": cfg.mode, "params": params}) + + # Check rate limit + t = time.time() + if (t - self.t) < self.rate_limit: + # Time is under rate limiter, wait to send + return + + # Time is over rate limiter, send now + data = {"client_id": SETTINGS["uuid"], "events": self.events} # SHA-256 anonymized UUID hash and events list + + # POST equivalent to requests.post(self.url, json=data) + smart_request("post", self.url, json=data, retry=0, verbose=False) + + # Reset events and rate limit timer + self.events = [] + self.t = t + + +# Run below code on hub/utils init ------------------------------------------------------------------------------------- +events = Events() diff --git a/ultralytics/models/__init__.py b/ultralytics/models/__init__.py new file mode 100644 index 0000000..b9b6eb3 --- /dev/null +++ b/ultralytics/models/__init__.py @@ -0,0 +1,7 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from .rtdetr import RTDETR +from .sam import SAM +from .yolo import YOLO, YOLOWorld + +__all__ = "YOLO", "RTDETR", "SAM", "YOLOWorld" # allow simpler import diff --git a/ultralytics/models/fastsam/__init__.py b/ultralytics/models/fastsam/__init__.py new file mode 100644 index 0000000..eabf5b9 --- /dev/null +++ b/ultralytics/models/fastsam/__init__.py @@ -0,0 +1,8 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from .model import FastSAM +from .predict import FastSAMPredictor +from .prompt import FastSAMPrompt +from .val import FastSAMValidator + +__all__ = "FastSAMPredictor", "FastSAM", "FastSAMPrompt", "FastSAMValidator" diff --git a/ultralytics/models/fastsam/model.py b/ultralytics/models/fastsam/model.py new file mode 100644 index 0000000..4cc8868 --- /dev/null +++ b/ultralytics/models/fastsam/model.py @@ -0,0 +1,34 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from pathlib import Path + +from ultralytics.engine.model import Model + +from .predict import FastSAMPredictor +from .val import FastSAMValidator + + +class FastSAM(Model): + """ + FastSAM model interface. + + Example: + ```python + from ultralytics import FastSAM + + model = FastSAM('last.pt') + results = model.predict('ultralytics/assets/bus.jpg') + ``` + """ + + def __init__(self, model="FastSAM-x.pt"): + """Call the __init__ method of the parent class (YOLO) with the updated default model.""" + if str(model) == "FastSAM.pt": + model = "FastSAM-x.pt" + assert Path(model).suffix not in {".yaml", ".yml"}, "FastSAM models only support pre-trained models." + super().__init__(model=model, task="segment") + + @property + def task_map(self): + """Returns a dictionary mapping segment task to corresponding predictor and validator classes.""" + return {"segment": {"predictor": FastSAMPredictor, "validator": FastSAMValidator}} diff --git a/ultralytics/models/fastsam/predict.py b/ultralytics/models/fastsam/predict.py new file mode 100644 index 0000000..0ef1803 --- /dev/null +++ b/ultralytics/models/fastsam/predict.py @@ -0,0 +1,86 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import torch + +from ultralytics.engine.results import Results +from ultralytics.models.fastsam.utils import bbox_iou +from ultralytics.models.yolo.detect.predict import DetectionPredictor +from ultralytics.utils import DEFAULT_CFG, ops + + +class FastSAMPredictor(DetectionPredictor): + """ + FastSAMPredictor is specialized for fast SAM (Segment Anything Model) segmentation prediction tasks in Ultralytics + YOLO framework. + + This class extends the DetectionPredictor, customizing the prediction pipeline specifically for fast SAM. + It adjusts post-processing steps to incorporate mask prediction and non-max suppression while optimizing + for single-class segmentation. + + Attributes: + cfg (dict): Configuration parameters for prediction. + overrides (dict, optional): Optional parameter overrides for custom behavior. + _callbacks (dict, optional): Optional list of callback functions to be invoked during prediction. + """ + + def __init__(self, cfg=DEFAULT_CFG, overrides=None, _callbacks=None): + """ + Initializes the FastSAMPredictor class, inheriting from DetectionPredictor and setting the task to 'segment'. + + Args: + cfg (dict): Configuration parameters for prediction. + overrides (dict, optional): Optional parameter overrides for custom behavior. + _callbacks (dict, optional): Optional list of callback functions to be invoked during prediction. + """ + super().__init__(cfg, overrides, _callbacks) + self.args.task = "segment" + + def postprocess(self, preds, img, orig_imgs): + """ + Perform post-processing steps on predictions, including non-max suppression and scaling boxes to original image + size, and returns the final results. + + Args: + preds (list): The raw output predictions from the model. + img (torch.Tensor): The processed image tensor. + orig_imgs (list | torch.Tensor): The original image or list of images. + + Returns: + (list): A list of Results objects, each containing processed boxes, masks, and other metadata. + """ + p = ops.non_max_suppression( + preds[0], + self.args.conf, + self.args.iou, + agnostic=self.args.agnostic_nms, + max_det=self.args.max_det, + nc=1, # set to 1 class since SAM has no class predictions + classes=self.args.classes, + ) + full_box = torch.zeros(p[0].shape[1], device=p[0].device) + full_box[2], full_box[3], full_box[4], full_box[6:] = img.shape[3], img.shape[2], 1.0, 1.0 + full_box = full_box.view(1, -1) + critical_iou_index = bbox_iou(full_box[0][:4], p[0][:, :4], iou_thres=0.9, image_shape=img.shape[2:]) + if critical_iou_index.numel() != 0: + full_box[0][4] = p[0][critical_iou_index][:, 4] + full_box[0][6:] = p[0][critical_iou_index][:, 6:] + p[0][critical_iou_index] = full_box + + if not isinstance(orig_imgs, list): # input images are a torch.Tensor, not a list + orig_imgs = ops.convert_torch2numpy_batch(orig_imgs) + + results = [] + proto = preds[1][-1] if len(preds[1]) == 3 else preds[1] # second output is len 3 if pt, but only 1 if exported + for i, pred in enumerate(p): + orig_img = orig_imgs[i] + img_path = self.batch[0][i] + if not len(pred): # save empty boxes + masks = None + elif self.args.retina_masks: + pred[:, :4] = ops.scale_boxes(img.shape[2:], pred[:, :4], orig_img.shape) + masks = ops.process_mask_native(proto[i], pred[:, 6:], pred[:, :4], orig_img.shape[:2]) # HWC + else: + masks = ops.process_mask(proto[i], pred[:, 6:], pred[:, :4], img.shape[2:], upsample=True) # HWC + pred[:, :4] = ops.scale_boxes(img.shape[2:], pred[:, :4], orig_img.shape) + results.append(Results(orig_img, path=img_path, names=self.model.names, boxes=pred[:, :6], masks=masks)) + return results diff --git a/ultralytics/models/fastsam/prompt.py b/ultralytics/models/fastsam/prompt.py new file mode 100644 index 0000000..59d93da --- /dev/null +++ b/ultralytics/models/fastsam/prompt.py @@ -0,0 +1,359 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import os +from pathlib import Path + +import cv2 +import numpy as np +import torch +from PIL import Image + +from ultralytics.utils import TQDM, checks + + +class FastSAMPrompt: + """ + Fast Segment Anything Model class for image annotation and visualization. + + Attributes: + device (str): Computing device ('cuda' or 'cpu'). + results: Object detection or segmentation results. + source: Source image or image path. + clip: CLIP model for linear assignment. + """ + + def __init__(self, source, results, device="cuda") -> None: + """Initializes FastSAMPrompt with given source, results and device, and assigns clip for linear assignment.""" + self.device = device + self.results = results + self.source = source + + # Import and assign clip + try: + import clip + except ImportError: + checks.check_requirements("git+https://github.com/ultralytics/CLIP.git") + import clip + self.clip = clip + + @staticmethod + def _segment_image(image, bbox): + """Segments the given image according to the provided bounding box coordinates.""" + image_array = np.array(image) + segmented_image_array = np.zeros_like(image_array) + x1, y1, x2, y2 = bbox + segmented_image_array[y1:y2, x1:x2] = image_array[y1:y2, x1:x2] + segmented_image = Image.fromarray(segmented_image_array) + black_image = Image.new("RGB", image.size, (255, 255, 255)) + # transparency_mask = np.zeros_like((), dtype=np.uint8) + transparency_mask = np.zeros((image_array.shape[0], image_array.shape[1]), dtype=np.uint8) + transparency_mask[y1:y2, x1:x2] = 255 + transparency_mask_image = Image.fromarray(transparency_mask, mode="L") + black_image.paste(segmented_image, mask=transparency_mask_image) + return black_image + + @staticmethod + def _format_results(result, filter=0): + """Formats detection results into list of annotations each containing ID, segmentation, bounding box, score and + area. + """ + annotations = [] + n = len(result.masks.data) if result.masks is not None else 0 + for i in range(n): + mask = result.masks.data[i] == 1.0 + if torch.sum(mask) >= filter: + annotation = { + "id": i, + "segmentation": mask.cpu().numpy(), + "bbox": result.boxes.data[i], + "score": result.boxes.conf[i], + } + annotation["area"] = annotation["segmentation"].sum() + annotations.append(annotation) + return annotations + + @staticmethod + def _get_bbox_from_mask(mask): + """Applies morphological transformations to the mask, displays it, and if with_contours is True, draws + contours. + """ + mask = mask.astype(np.uint8) + contours, hierarchy = cv2.findContours(mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE) + x1, y1, w, h = cv2.boundingRect(contours[0]) + x2, y2 = x1 + w, y1 + h + if len(contours) > 1: + for b in contours: + x_t, y_t, w_t, h_t = cv2.boundingRect(b) + x1 = min(x1, x_t) + y1 = min(y1, y_t) + x2 = max(x2, x_t + w_t) + y2 = max(y2, y_t + h_t) + return [x1, y1, x2, y2] + + def plot( + self, + annotations, + output, + bbox=None, + points=None, + point_label=None, + mask_random_color=True, + better_quality=True, + retina=False, + with_contours=True, + ): + """ + Plots annotations, bounding boxes, and points on images and saves the output. + + Args: + annotations (list): Annotations to be plotted. + output (str or Path): Output directory for saving the plots. + bbox (list, optional): Bounding box coordinates [x1, y1, x2, y2]. Defaults to None. + points (list, optional): Points to be plotted. Defaults to None. + point_label (list, optional): Labels for the points. Defaults to None. + mask_random_color (bool, optional): Whether to use random color for masks. Defaults to True. + better_quality (bool, optional): Whether to apply morphological transformations for better mask quality. + Defaults to True. + retina (bool, optional): Whether to use retina mask. Defaults to False. + with_contours (bool, optional): Whether to plot contours. Defaults to True. + """ + import matplotlib.pyplot as plt + + pbar = TQDM(annotations, total=len(annotations)) + for ann in pbar: + result_name = os.path.basename(ann.path) + image = ann.orig_img[..., ::-1] # BGR to RGB + original_h, original_w = ann.orig_shape + # For macOS only + # plt.switch_backend('TkAgg') + plt.figure(figsize=(original_w / 100, original_h / 100)) + # Add subplot with no margin. + plt.subplots_adjust(top=1, bottom=0, right=1, left=0, hspace=0, wspace=0) + plt.margins(0, 0) + plt.gca().xaxis.set_major_locator(plt.NullLocator()) + plt.gca().yaxis.set_major_locator(plt.NullLocator()) + plt.imshow(image) + + if ann.masks is not None: + masks = ann.masks.data + if better_quality: + if isinstance(masks[0], torch.Tensor): + masks = np.array(masks.cpu()) + for i, mask in enumerate(masks): + mask = cv2.morphologyEx(mask.astype(np.uint8), cv2.MORPH_CLOSE, np.ones((3, 3), np.uint8)) + masks[i] = cv2.morphologyEx(mask.astype(np.uint8), cv2.MORPH_OPEN, np.ones((8, 8), np.uint8)) + + self.fast_show_mask( + masks, + plt.gca(), + random_color=mask_random_color, + bbox=bbox, + points=points, + pointlabel=point_label, + retinamask=retina, + target_height=original_h, + target_width=original_w, + ) + + if with_contours: + contour_all = [] + temp = np.zeros((original_h, original_w, 1)) + for i, mask in enumerate(masks): + mask = mask.astype(np.uint8) + if not retina: + mask = cv2.resize(mask, (original_w, original_h), interpolation=cv2.INTER_NEAREST) + contours, _ = cv2.findContours(mask, cv2.RETR_TREE, cv2.CHAIN_APPROX_SIMPLE) + contour_all.extend(iter(contours)) + cv2.drawContours(temp, contour_all, -1, (255, 255, 255), 2) + color = np.array([0 / 255, 0 / 255, 1.0, 0.8]) + contour_mask = temp / 255 * color.reshape(1, 1, -1) + plt.imshow(contour_mask) + + # Save the figure + save_path = Path(output) / result_name + save_path.parent.mkdir(exist_ok=True, parents=True) + plt.axis("off") + plt.savefig(save_path, bbox_inches="tight", pad_inches=0, transparent=True) + plt.close() + pbar.set_description(f"Saving {result_name} to {save_path}") + + @staticmethod + def fast_show_mask( + annotation, + ax, + random_color=False, + bbox=None, + points=None, + pointlabel=None, + retinamask=True, + target_height=960, + target_width=960, + ): + """ + Quickly shows the mask annotations on the given matplotlib axis. + + Args: + annotation (array-like): Mask annotation. + ax (matplotlib.axes.Axes): Matplotlib axis. + random_color (bool, optional): Whether to use random color for masks. Defaults to False. + bbox (list, optional): Bounding box coordinates [x1, y1, x2, y2]. Defaults to None. + points (list, optional): Points to be plotted. Defaults to None. + pointlabel (list, optional): Labels for the points. Defaults to None. + retinamask (bool, optional): Whether to use retina mask. Defaults to True. + target_height (int, optional): Target height for resizing. Defaults to 960. + target_width (int, optional): Target width for resizing. Defaults to 960. + """ + import matplotlib.pyplot as plt + + n, h, w = annotation.shape # batch, height, width + + areas = np.sum(annotation, axis=(1, 2)) + annotation = annotation[np.argsort(areas)] + + index = (annotation != 0).argmax(axis=0) + if random_color: + color = np.random.random((n, 1, 1, 3)) + else: + color = np.ones((n, 1, 1, 3)) * np.array([30 / 255, 144 / 255, 1.0]) + transparency = np.ones((n, 1, 1, 1)) * 0.6 + visual = np.concatenate([color, transparency], axis=-1) + mask_image = np.expand_dims(annotation, -1) * visual + + show = np.zeros((h, w, 4)) + h_indices, w_indices = np.meshgrid(np.arange(h), np.arange(w), indexing="ij") + indices = (index[h_indices, w_indices], h_indices, w_indices, slice(None)) + + show[h_indices, w_indices, :] = mask_image[indices] + if bbox is not None: + x1, y1, x2, y2 = bbox + ax.add_patch(plt.Rectangle((x1, y1), x2 - x1, y2 - y1, fill=False, edgecolor="b", linewidth=1)) + # Draw point + if points is not None: + plt.scatter( + [point[0] for i, point in enumerate(points) if pointlabel[i] == 1], + [point[1] for i, point in enumerate(points) if pointlabel[i] == 1], + s=20, + c="y", + ) + plt.scatter( + [point[0] for i, point in enumerate(points) if pointlabel[i] == 0], + [point[1] for i, point in enumerate(points) if pointlabel[i] == 0], + s=20, + c="m", + ) + + if not retinamask: + show = cv2.resize(show, (target_width, target_height), interpolation=cv2.INTER_NEAREST) + ax.imshow(show) + + @torch.no_grad() + def retrieve(self, model, preprocess, elements, search_text: str, device) -> int: + """Processes images and text with a model, calculates similarity, and returns softmax score.""" + preprocessed_images = [preprocess(image).to(device) for image in elements] + tokenized_text = self.clip.tokenize([search_text]).to(device) + stacked_images = torch.stack(preprocessed_images) + image_features = model.encode_image(stacked_images) + text_features = model.encode_text(tokenized_text) + image_features /= image_features.norm(dim=-1, keepdim=True) + text_features /= text_features.norm(dim=-1, keepdim=True) + probs = 100.0 * image_features @ text_features.T + return probs[:, 0].softmax(dim=0) + + def _crop_image(self, format_results): + """Crops an image based on provided annotation format and returns cropped images and related data.""" + if os.path.isdir(self.source): + raise ValueError(f"'{self.source}' is a directory, not a valid source for this function.") + image = Image.fromarray(cv2.cvtColor(self.results[0].orig_img, cv2.COLOR_BGR2RGB)) + ori_w, ori_h = image.size + annotations = format_results + mask_h, mask_w = annotations[0]["segmentation"].shape + if ori_w != mask_w or ori_h != mask_h: + image = image.resize((mask_w, mask_h)) + cropped_boxes = [] + cropped_images = [] + not_crop = [] + filter_id = [] + for _, mask in enumerate(annotations): + if np.sum(mask["segmentation"]) <= 100: + filter_id.append(_) + continue + bbox = self._get_bbox_from_mask(mask["segmentation"]) # bbox from mask + cropped_boxes.append(self._segment_image(image, bbox)) # save cropped image + cropped_images.append(bbox) # save cropped image bbox + + return cropped_boxes, cropped_images, not_crop, filter_id, annotations + + def box_prompt(self, bbox): + """Modifies the bounding box properties and calculates IoU between masks and bounding box.""" + if self.results[0].masks is not None: + assert bbox[2] != 0 and bbox[3] != 0 + if os.path.isdir(self.source): + raise ValueError(f"'{self.source}' is a directory, not a valid source for this function.") + masks = self.results[0].masks.data + target_height, target_width = self.results[0].orig_shape + h = masks.shape[1] + w = masks.shape[2] + if h != target_height or w != target_width: + bbox = [ + int(bbox[0] * w / target_width), + int(bbox[1] * h / target_height), + int(bbox[2] * w / target_width), + int(bbox[3] * h / target_height), + ] + bbox[0] = max(round(bbox[0]), 0) + bbox[1] = max(round(bbox[1]), 0) + bbox[2] = min(round(bbox[2]), w) + bbox[3] = min(round(bbox[3]), h) + + # IoUs = torch.zeros(len(masks), dtype=torch.float32) + bbox_area = (bbox[3] - bbox[1]) * (bbox[2] - bbox[0]) + + masks_area = torch.sum(masks[:, bbox[1] : bbox[3], bbox[0] : bbox[2]], dim=(1, 2)) + orig_masks_area = torch.sum(masks, dim=(1, 2)) + + union = bbox_area + orig_masks_area - masks_area + iou = masks_area / union + max_iou_index = torch.argmax(iou) + + self.results[0].masks.data = torch.tensor(np.array([masks[max_iou_index].cpu().numpy()])) + return self.results + + def point_prompt(self, points, pointlabel): # numpy + """Adjusts points on detected masks based on user input and returns the modified results.""" + if self.results[0].masks is not None: + if os.path.isdir(self.source): + raise ValueError(f"'{self.source}' is a directory, not a valid source for this function.") + masks = self._format_results(self.results[0], 0) + target_height, target_width = self.results[0].orig_shape + h = masks[0]["segmentation"].shape[0] + w = masks[0]["segmentation"].shape[1] + if h != target_height or w != target_width: + points = [[int(point[0] * w / target_width), int(point[1] * h / target_height)] for point in points] + onemask = np.zeros((h, w)) + for annotation in masks: + mask = annotation["segmentation"] if isinstance(annotation, dict) else annotation + for i, point in enumerate(points): + if mask[point[1], point[0]] == 1 and pointlabel[i] == 1: + onemask += mask + if mask[point[1], point[0]] == 1 and pointlabel[i] == 0: + onemask -= mask + onemask = onemask >= 1 + self.results[0].masks.data = torch.tensor(np.array([onemask])) + return self.results + + def text_prompt(self, text): + """Processes a text prompt, applies it to existing results and returns the updated results.""" + if self.results[0].masks is not None: + format_results = self._format_results(self.results[0], 0) + cropped_boxes, cropped_images, not_crop, filter_id, annotations = self._crop_image(format_results) + clip_model, preprocess = self.clip.load("ViT-B/32", device=self.device) + scores = self.retrieve(clip_model, preprocess, cropped_boxes, text, device=self.device) + max_idx = scores.argsort() + max_idx = max_idx[-1] + max_idx += sum(np.array(filter_id) <= int(max_idx)) + self.results[0].masks.data = torch.tensor(np.array([annotations[max_idx]["segmentation"]])) + return self.results + + def everything_prompt(self): + """Returns the processed results from the previous methods in the class.""" + return self.results diff --git a/ultralytics/models/fastsam/utils.py b/ultralytics/models/fastsam/utils.py new file mode 100644 index 0000000..480e903 --- /dev/null +++ b/ultralytics/models/fastsam/utils.py @@ -0,0 +1,67 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import torch + + +def adjust_bboxes_to_image_border(boxes, image_shape, threshold=20): + """ + Adjust bounding boxes to stick to image border if they are within a certain threshold. + + Args: + boxes (torch.Tensor): (n, 4) + image_shape (tuple): (height, width) + threshold (int): pixel threshold + + Returns: + adjusted_boxes (torch.Tensor): adjusted bounding boxes + """ + + # Image dimensions + h, w = image_shape + + # Adjust boxes + boxes[boxes[:, 0] < threshold, 0] = 0 # x1 + boxes[boxes[:, 1] < threshold, 1] = 0 # y1 + boxes[boxes[:, 2] > w - threshold, 2] = w # x2 + boxes[boxes[:, 3] > h - threshold, 3] = h # y2 + return boxes + + +def bbox_iou(box1, boxes, iou_thres=0.9, image_shape=(640, 640), raw_output=False): + """ + Compute the Intersection-Over-Union of a bounding box with respect to an array of other bounding boxes. + + Args: + box1 (torch.Tensor): (4, ) + boxes (torch.Tensor): (n, 4) + iou_thres (float): IoU threshold + image_shape (tuple): (height, width) + raw_output (bool): If True, return the raw IoU values instead of the indices + + Returns: + high_iou_indices (torch.Tensor): Indices of boxes with IoU > thres + """ + boxes = adjust_bboxes_to_image_border(boxes, image_shape) + # Obtain coordinates for intersections + x1 = torch.max(box1[0], boxes[:, 0]) + y1 = torch.max(box1[1], boxes[:, 1]) + x2 = torch.min(box1[2], boxes[:, 2]) + y2 = torch.min(box1[3], boxes[:, 3]) + + # Compute the area of intersection + intersection = (x2 - x1).clamp(0) * (y2 - y1).clamp(0) + + # Compute the area of both individual boxes + box1_area = (box1[2] - box1[0]) * (box1[3] - box1[1]) + box2_area = (boxes[:, 2] - boxes[:, 0]) * (boxes[:, 3] - boxes[:, 1]) + + # Compute the area of union + union = box1_area + box2_area - intersection + + # Compute the IoU + iou = intersection / union # Should be shape (n, ) + if raw_output: + return 0 if iou.numel() == 0 else iou + + # return indices of boxes with IoU > thres + return torch.nonzero(iou > iou_thres).flatten() diff --git a/ultralytics/models/fastsam/val.py b/ultralytics/models/fastsam/val.py new file mode 100644 index 0000000..9014b27 --- /dev/null +++ b/ultralytics/models/fastsam/val.py @@ -0,0 +1,40 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from ultralytics.models.yolo.segment import SegmentationValidator +from ultralytics.utils.metrics import SegmentMetrics + + +class FastSAMValidator(SegmentationValidator): + """ + Custom validation class for fast SAM (Segment Anything Model) segmentation in Ultralytics YOLO framework. + + Extends the SegmentationValidator class, customizing the validation process specifically for fast SAM. This class + sets the task to 'segment' and uses the SegmentMetrics for evaluation. Additionally, plotting features are disabled + to avoid errors during validation. + + Attributes: + dataloader: The data loader object used for validation. + save_dir (str): The directory where validation results will be saved. + pbar: A progress bar object. + args: Additional arguments for customization. + _callbacks: List of callback functions to be invoked during validation. + """ + + def __init__(self, dataloader=None, save_dir=None, pbar=None, args=None, _callbacks=None): + """ + Initialize the FastSAMValidator class, setting the task to 'segment' and metrics to SegmentMetrics. + + Args: + dataloader (torch.utils.data.DataLoader): Dataloader to be used for validation. + save_dir (Path, optional): Directory to save results. + pbar (tqdm.tqdm): Progress bar for displaying progress. + args (SimpleNamespace): Configuration for the validator. + _callbacks (dict): Dictionary to store various callback functions. + + Notes: + Plots for ConfusionMatrix and other related metrics are disabled in this class to avoid errors. + """ + super().__init__(dataloader, save_dir, pbar, args, _callbacks) + self.args.task = "segment" + self.args.plots = False # disable ConfusionMatrix and other plots to avoid errors + self.metrics = SegmentMetrics(save_dir=self.save_dir, on_plot=self.on_plot) diff --git a/ultralytics/models/nas/__init__.py b/ultralytics/models/nas/__init__.py new file mode 100644 index 0000000..b095a05 --- /dev/null +++ b/ultralytics/models/nas/__init__.py @@ -0,0 +1,7 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from .model import NAS +from .predict import NASPredictor +from .val import NASValidator + +__all__ = "NASPredictor", "NASValidator", "NAS" diff --git a/ultralytics/models/nas/model.py b/ultralytics/models/nas/model.py new file mode 100644 index 0000000..9b75c60 --- /dev/null +++ b/ultralytics/models/nas/model.py @@ -0,0 +1,84 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +""" +YOLO-NAS model interface. + +Example: + ```python + from ultralytics import NAS + + model = NAS('yolo_nas_s') + results = model.predict('ultralytics/assets/bus.jpg') + ``` +""" + +from pathlib import Path + +import torch + +from ultralytics.engine.model import Model +from ultralytics.utils.torch_utils import model_info, smart_inference_mode + +from .predict import NASPredictor +from .val import NASValidator + + +class NAS(Model): + """ + YOLO NAS model for object detection. + + This class provides an interface for the YOLO-NAS models and extends the `Model` class from Ultralytics engine. + It is designed to facilitate the task of object detection using pre-trained or custom-trained YOLO-NAS models. + + Example: + ```python + from ultralytics import NAS + + model = NAS('yolo_nas_s') + results = model.predict('ultralytics/assets/bus.jpg') + ``` + + Attributes: + model (str): Path to the pre-trained model or model name. Defaults to 'yolo_nas_s.pt'. + + Note: + YOLO-NAS models only support pre-trained models. Do not provide YAML configuration files. + """ + + def __init__(self, model="yolo_nas_s.pt") -> None: + """Initializes the NAS model with the provided or default 'yolo_nas_s.pt' model.""" + assert Path(model).suffix not in {".yaml", ".yml"}, "YOLO-NAS models only support pre-trained models." + super().__init__(model, task="detect") + + @smart_inference_mode() + def _load(self, weights: str, task: str): + """Loads an existing NAS model weights or creates a new NAS model with pretrained weights if not provided.""" + import super_gradients + + suffix = Path(weights).suffix + if suffix == ".pt": + self.model = torch.load(weights) + elif suffix == "": + self.model = super_gradients.training.models.get(weights, pretrained_weights="coco") + # Standardize model + self.model.fuse = lambda verbose=True: self.model + self.model.stride = torch.tensor([32]) + self.model.names = dict(enumerate(self.model._class_names)) + self.model.is_fused = lambda: False # for info() + self.model.yaml = {} # for info() + self.model.pt_path = weights # for export() + self.model.task = "detect" # for export() + + def info(self, detailed=False, verbose=True): + """ + Logs model info. + + Args: + detailed (bool): Show detailed information about model. + verbose (bool): Controls verbosity. + """ + return model_info(self.model, detailed=detailed, verbose=verbose, imgsz=640) + + @property + def task_map(self): + """Returns a dictionary mapping tasks to respective predictor and validator classes.""" + return {"detect": {"predictor": NASPredictor, "validator": NASValidator}} diff --git a/ultralytics/models/nas/predict.py b/ultralytics/models/nas/predict.py new file mode 100644 index 0000000..2e48546 --- /dev/null +++ b/ultralytics/models/nas/predict.py @@ -0,0 +1,60 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import torch + +from ultralytics.engine.predictor import BasePredictor +from ultralytics.engine.results import Results +from ultralytics.utils import ops + + +class NASPredictor(BasePredictor): + """ + Ultralytics YOLO NAS Predictor for object detection. + + This class extends the `BasePredictor` from Ultralytics engine and is responsible for post-processing the + raw predictions generated by the YOLO NAS models. It applies operations like non-maximum suppression and + scaling the bounding boxes to fit the original image dimensions. + + Attributes: + args (Namespace): Namespace containing various configurations for post-processing. + + Example: + ```python + from ultralytics import NAS + + model = NAS('yolo_nas_s') + predictor = model.predictor + # Assumes that raw_preds, img, orig_imgs are available + results = predictor.postprocess(raw_preds, img, orig_imgs) + ``` + + Note: + Typically, this class is not instantiated directly. It is used internally within the `NAS` class. + """ + + def postprocess(self, preds_in, img, orig_imgs): + """Postprocess predictions and returns a list of Results objects.""" + + # Cat boxes and class scores + boxes = ops.xyxy2xywh(preds_in[0][0]) + preds = torch.cat((boxes, preds_in[0][1]), -1).permute(0, 2, 1) + + preds = ops.non_max_suppression( + preds, + self.args.conf, + self.args.iou, + agnostic=self.args.agnostic_nms, + max_det=self.args.max_det, + classes=self.args.classes, + ) + + if not isinstance(orig_imgs, list): # input images are a torch.Tensor, not a list + orig_imgs = ops.convert_torch2numpy_batch(orig_imgs) + + results = [] + for i, pred in enumerate(preds): + orig_img = orig_imgs[i] + pred[:, :4] = ops.scale_boxes(img.shape[2:], pred[:, :4], orig_img.shape) + img_path = self.batch[0][i] + results.append(Results(orig_img, path=img_path, names=self.model.names, boxes=pred)) + return results diff --git a/ultralytics/models/nas/val.py b/ultralytics/models/nas/val.py new file mode 100644 index 0000000..a4a4f99 --- /dev/null +++ b/ultralytics/models/nas/val.py @@ -0,0 +1,50 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import torch + +from ultralytics.models.yolo.detect import DetectionValidator +from ultralytics.utils import ops + +__all__ = ["NASValidator"] + + +class NASValidator(DetectionValidator): + """ + Ultralytics YOLO NAS Validator for object detection. + + Extends `DetectionValidator` from the Ultralytics models package and is designed to post-process the raw predictions + generated by YOLO NAS models. It performs non-maximum suppression to remove overlapping and low-confidence boxes, + ultimately producing the final detections. + + Attributes: + args (Namespace): Namespace containing various configurations for post-processing, such as confidence and IoU thresholds. + lb (torch.Tensor): Optional tensor for multilabel NMS. + + Example: + ```python + from ultralytics import NAS + + model = NAS('yolo_nas_s') + validator = model.validator + # Assumes that raw_preds are available + final_preds = validator.postprocess(raw_preds) + ``` + + Note: + This class is generally not instantiated directly but is used internally within the `NAS` class. + """ + + def postprocess(self, preds_in): + """Apply Non-maximum suppression to prediction outputs.""" + boxes = ops.xyxy2xywh(preds_in[0][0]) + preds = torch.cat((boxes, preds_in[0][1]), -1).permute(0, 2, 1) + return ops.non_max_suppression( + preds, + self.args.conf, + self.args.iou, + labels=self.lb, + multi_label=False, + agnostic=self.args.single_cls, + max_det=self.args.max_det, + max_time_img=0.5, + ) diff --git a/ultralytics/models/rtdetr/__init__.py b/ultralytics/models/rtdetr/__init__.py new file mode 100644 index 0000000..172c74b --- /dev/null +++ b/ultralytics/models/rtdetr/__init__.py @@ -0,0 +1,7 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from .model import RTDETR +from .predict import RTDETRPredictor +from .val import RTDETRValidator + +__all__ = "RTDETRPredictor", "RTDETRValidator", "RTDETR" diff --git a/ultralytics/models/rtdetr/model.py b/ultralytics/models/rtdetr/model.py new file mode 100644 index 0000000..440df17 --- /dev/null +++ b/ultralytics/models/rtdetr/model.py @@ -0,0 +1,54 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +""" +Interface for Baidu's RT-DETR, a Vision Transformer-based real-time object detector. RT-DETR offers real-time +performance and high accuracy, excelling in accelerated backends like CUDA with TensorRT. It features an efficient +hybrid encoder and IoU-aware query selection for enhanced detection accuracy. + +For more information on RT-DETR, visit: https://arxiv.org/pdf/2304.08069.pdf +""" + +from ultralytics.engine.model import Model +from ultralytics.nn.tasks import RTDETRDetectionModel + +from .predict import RTDETRPredictor +from .train import RTDETRTrainer +from .val import RTDETRValidator + + +class RTDETR(Model): + """ + Interface for Baidu's RT-DETR model. This Vision Transformer-based object detector provides real-time performance + with high accuracy. It supports efficient hybrid encoding, IoU-aware query selection, and adaptable inference speed. + + Attributes: + model (str): Path to the pre-trained model. Defaults to 'rtdetr-l.pt'. + """ + + def __init__(self, model="rtdetr-l.pt") -> None: + """ + Initializes the RT-DETR model with the given pre-trained model file. Supports .pt and .yaml formats. + + Args: + model (str): Path to the pre-trained model. Defaults to 'rtdetr-l.pt'. + + Raises: + NotImplementedError: If the model file extension is not 'pt', 'yaml', or 'yml'. + """ + super().__init__(model=model, task="detect") + + @property + def task_map(self) -> dict: + """ + Returns a task map for RT-DETR, associating tasks with corresponding Ultralytics classes. + + Returns: + dict: A dictionary mapping task names to Ultralytics task classes for the RT-DETR model. + """ + return { + "detect": { + "predictor": RTDETRPredictor, + "validator": RTDETRValidator, + "trainer": RTDETRTrainer, + "model": RTDETRDetectionModel, + } + } diff --git a/ultralytics/models/rtdetr/predict.py b/ultralytics/models/rtdetr/predict.py new file mode 100644 index 0000000..7fc918b --- /dev/null +++ b/ultralytics/models/rtdetr/predict.py @@ -0,0 +1,86 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import torch + +from ultralytics.data.augment import LetterBox +from ultralytics.engine.predictor import BasePredictor +from ultralytics.engine.results import Results +from ultralytics.utils import ops + + +class RTDETRPredictor(BasePredictor): + """ + RT-DETR (Real-Time Detection Transformer) Predictor extending the BasePredictor class for making predictions using + Baidu's RT-DETR model. + + This class leverages the power of Vision Transformers to provide real-time object detection while maintaining + high accuracy. It supports key features like efficient hybrid encoding and IoU-aware query selection. + + Example: + ```python + from ultralytics.utils import ASSETS + from ultralytics.models.rtdetr import RTDETRPredictor + + args = dict(model='rtdetr-l.pt', source=ASSETS) + predictor = RTDETRPredictor(overrides=args) + predictor.predict_cli() + ``` + + Attributes: + imgsz (int): Image size for inference (must be square and scale-filled). + args (dict): Argument overrides for the predictor. + """ + + def postprocess(self, preds, img, orig_imgs): + """ + Postprocess the raw predictions from the model to generate bounding boxes and confidence scores. + + The method filters detections based on confidence and class if specified in `self.args`. + + Args: + preds (list): List of [predictions, extra] from the model. + img (torch.Tensor): Processed input images. + orig_imgs (list or torch.Tensor): Original, unprocessed images. + + Returns: + (list[Results]): A list of Results objects containing the post-processed bounding boxes, confidence scores, + and class labels. + """ + if not isinstance(preds, (list, tuple)): # list for PyTorch inference but list[0] Tensor for export inference + preds = [preds, None] + + nd = preds[0].shape[-1] + bboxes, scores = preds[0].split((4, nd - 4), dim=-1) + + if not isinstance(orig_imgs, list): # input images are a torch.Tensor, not a list + orig_imgs = ops.convert_torch2numpy_batch(orig_imgs) + + results = [] + for i, bbox in enumerate(bboxes): # (300, 4) + bbox = ops.xywh2xyxy(bbox) + score, cls = scores[i].max(-1, keepdim=True) # (300, 1) + idx = score.squeeze(-1) > self.args.conf # (300, ) + if self.args.classes is not None: + idx = (cls == torch.tensor(self.args.classes, device=cls.device)).any(1) & idx + pred = torch.cat([bbox, score, cls], dim=-1)[idx] # filter + orig_img = orig_imgs[i] + oh, ow = orig_img.shape[:2] + pred[..., [0, 2]] *= ow + pred[..., [1, 3]] *= oh + img_path = self.batch[0][i] + results.append(Results(orig_img, path=img_path, names=self.model.names, boxes=pred)) + return results + + def pre_transform(self, im): + """ + Pre-transforms the input images before feeding them into the model for inference. The input images are + letterboxed to ensure a square aspect ratio and scale-filled. The size must be square(640) and scaleFilled. + + Args: + im (list[np.ndarray] |torch.Tensor): Input images of shape (N,3,h,w) for tensor, [(h,w,3) x N] for list. + + Returns: + (list): List of pre-transformed images ready for model inference. + """ + letterbox = LetterBox(self.imgsz, auto=False, scaleFill=True) + return [letterbox(image=x) for x in im] diff --git a/ultralytics/models/rtdetr/train.py b/ultralytics/models/rtdetr/train.py new file mode 100644 index 0000000..973af64 --- /dev/null +++ b/ultralytics/models/rtdetr/train.py @@ -0,0 +1,102 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from copy import copy + +import torch + +from ultralytics.models.yolo.detect import DetectionTrainer +from ultralytics.nn.tasks import RTDETRDetectionModel +from ultralytics.utils import RANK, colorstr + +from .val import RTDETRDataset, RTDETRValidator + + +class RTDETRTrainer(DetectionTrainer): + """ + Trainer class for the RT-DETR model developed by Baidu for real-time object detection. Extends the DetectionTrainer + class for YOLO to adapt to the specific features and architecture of RT-DETR. This model leverages Vision + Transformers and has capabilities like IoU-aware query selection and adaptable inference speed. + + Notes: + - F.grid_sample used in RT-DETR does not support the `deterministic=True` argument. + - AMP training can lead to NaN outputs and may produce errors during bipartite graph matching. + + Example: + ```python + from ultralytics.models.rtdetr.train import RTDETRTrainer + + args = dict(model='rtdetr-l.yaml', data='coco8.yaml', imgsz=640, epochs=3) + trainer = RTDETRTrainer(overrides=args) + trainer.train() + ``` + """ + + def get_model(self, cfg=None, weights=None, verbose=True): + """ + Initialize and return an RT-DETR model for object detection tasks. + + Args: + cfg (dict, optional): Model configuration. Defaults to None. + weights (str, optional): Path to pre-trained model weights. Defaults to None. + verbose (bool): Verbose logging if True. Defaults to True. + + Returns: + (RTDETRDetectionModel): Initialized model. + """ + model = RTDETRDetectionModel(cfg, nc=self.data["nc"], verbose=verbose and RANK == -1) + if weights: + model.load(weights) + return model + + def build_dataset(self, img_path, mode="val", batch=None): + """ + Build and return an RT-DETR dataset for training or validation. + + Args: + img_path (str): Path to the folder containing images. + mode (str): Dataset mode, either 'train' or 'val'. + batch (int, optional): Batch size for rectangle training. Defaults to None. + + Returns: + (RTDETRDataset): Dataset object for the specific mode. + """ + return RTDETRDataset( + img_path=img_path, + imgsz=self.args.imgsz, + batch_size=batch, + augment=mode == "train", + hyp=self.args, + rect=False, + cache=self.args.cache or None, + prefix=colorstr(f"{mode}: "), + data=self.data, + ) + + def get_validator(self): + """ + Returns a DetectionValidator suitable for RT-DETR model validation. + + Returns: + (RTDETRValidator): Validator object for model validation. + """ + self.loss_names = "giou_loss", "cls_loss", "l1_loss" + return RTDETRValidator(self.test_loader, save_dir=self.save_dir, args=copy(self.args)) + + def preprocess_batch(self, batch): + """ + Preprocess a batch of images. Scales and converts the images to float format. + + Args: + batch (dict): Dictionary containing a batch of images, bboxes, and labels. + + Returns: + (dict): Preprocessed batch. + """ + batch = super().preprocess_batch(batch) + bs = len(batch["img"]) + batch_idx = batch["batch_idx"] + gt_bbox, gt_class = [], [] + for i in range(bs): + gt_bbox.append(batch["bboxes"][batch_idx == i].to(batch_idx.device)) + gt_class.append(batch["cls"][batch_idx == i].to(device=batch_idx.device, dtype=torch.long)) + return batch diff --git a/ultralytics/models/rtdetr/val.py b/ultralytics/models/rtdetr/val.py new file mode 100644 index 0000000..d4d939f --- /dev/null +++ b/ultralytics/models/rtdetr/val.py @@ -0,0 +1,135 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import torch + +from ultralytics.data import YOLODataset +from ultralytics.data.augment import Compose, Format, v8_transforms +from ultralytics.models.yolo.detect import DetectionValidator +from ultralytics.utils import colorstr, ops + +__all__ = ("RTDETRValidator",) # tuple or list + + +class RTDETRDataset(YOLODataset): + """ + Real-Time DEtection and TRacking (RT-DETR) dataset class extending the base YOLODataset class. + + This specialized dataset class is designed for use with the RT-DETR object detection model and is optimized for + real-time detection and tracking tasks. + """ + + def __init__(self, *args, data=None, **kwargs): + """Initialize the RTDETRDataset class by inheriting from the YOLODataset class.""" + super().__init__(*args, data=data, **kwargs) + + # NOTE: add stretch version load_image for RTDETR mosaic + def load_image(self, i, rect_mode=False): + """Loads 1 image from dataset index 'i', returns (im, resized hw).""" + return super().load_image(i=i, rect_mode=rect_mode) + + def build_transforms(self, hyp=None): + """Temporary, only for evaluation.""" + if self.augment: + hyp.mosaic = hyp.mosaic if self.augment and not self.rect else 0.0 + hyp.mixup = hyp.mixup if self.augment and not self.rect else 0.0 + transforms = v8_transforms(self, self.imgsz, hyp, stretch=True) + else: + # transforms = Compose([LetterBox(new_shape=(self.imgsz, self.imgsz), auto=False, scaleFill=True)]) + transforms = Compose([]) + transforms.append( + Format( + bbox_format="xywh", + normalize=True, + return_mask=self.use_segments, + return_keypoint=self.use_keypoints, + batch_idx=True, + mask_ratio=hyp.mask_ratio, + mask_overlap=hyp.overlap_mask, + ) + ) + return transforms + + +class RTDETRValidator(DetectionValidator): + """ + RTDETRValidator extends the DetectionValidator class to provide validation capabilities specifically tailored for + the RT-DETR (Real-Time DETR) object detection model. + + The class allows building of an RTDETR-specific dataset for validation, applies Non-maximum suppression for + post-processing, and updates evaluation metrics accordingly. + + Example: + ```python + from ultralytics.models.rtdetr import RTDETRValidator + + args = dict(model='rtdetr-l.pt', data='coco8.yaml') + validator = RTDETRValidator(args=args) + validator() + ``` + + Note: + For further details on the attributes and methods, refer to the parent DetectionValidator class. + """ + + def build_dataset(self, img_path, mode="val", batch=None): + """ + Build an RTDETR Dataset. + + Args: + img_path (str): Path to the folder containing images. + mode (str): `train` mode or `val` mode, users are able to customize different augmentations for each mode. + batch (int, optional): Size of batches, this is for `rect`. Defaults to None. + """ + return RTDETRDataset( + img_path=img_path, + imgsz=self.args.imgsz, + batch_size=batch, + augment=False, # no augmentation + hyp=self.args, + rect=False, # no rect + cache=self.args.cache or None, + prefix=colorstr(f"{mode}: "), + data=self.data, + ) + + def postprocess(self, preds): + """Apply Non-maximum suppression to prediction outputs.""" + if not isinstance(preds, (list, tuple)): # list for PyTorch inference but list[0] Tensor for export inference + preds = [preds, None] + + bs, _, nd = preds[0].shape + bboxes, scores = preds[0].split((4, nd - 4), dim=-1) + bboxes *= self.args.imgsz + outputs = [torch.zeros((0, 6), device=bboxes.device)] * bs + for i, bbox in enumerate(bboxes): # (300, 4) + bbox = ops.xywh2xyxy(bbox) + score, cls = scores[i].max(-1) # (300, ) + # Do not need threshold for evaluation as only got 300 boxes here + # idx = score > self.args.conf + pred = torch.cat([bbox, score[..., None], cls[..., None]], dim=-1) # filter + # Sort by confidence to correctly get internal metrics + pred = pred[score.argsort(descending=True)] + outputs[i] = pred # [idx] + + return outputs + + def _prepare_batch(self, si, batch): + """Prepares a batch for training or inference by applying transformations.""" + idx = batch["batch_idx"] == si + cls = batch["cls"][idx].squeeze(-1) + bbox = batch["bboxes"][idx] + ori_shape = batch["ori_shape"][si] + imgsz = batch["img"].shape[2:] + ratio_pad = batch["ratio_pad"][si] + if len(cls): + bbox = ops.xywh2xyxy(bbox) # target boxes + bbox[..., [0, 2]] *= ori_shape[1] # native-space pred + bbox[..., [1, 3]] *= ori_shape[0] # native-space pred + return {"cls": cls, "bbox": bbox, "ori_shape": ori_shape, "imgsz": imgsz, "ratio_pad": ratio_pad} + + def _prepare_pred(self, pred, pbatch): + """Prepares and returns a batch with transformed bounding boxes and class labels.""" + predn = pred.clone() + predn[..., [0, 2]] *= pbatch["ori_shape"][1] / self.args.imgsz # native-space pred + predn[..., [1, 3]] *= pbatch["ori_shape"][0] / self.args.imgsz # native-space pred + return predn.float() diff --git a/ultralytics/models/sam/__init__.py b/ultralytics/models/sam/__init__.py new file mode 100644 index 0000000..8701fcc --- /dev/null +++ b/ultralytics/models/sam/__init__.py @@ -0,0 +1,6 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from .model import SAM +from .predict import Predictor + +__all__ = "SAM", "Predictor" # tuple or list diff --git a/ultralytics/models/sam/amg.py b/ultralytics/models/sam/amg.py new file mode 100644 index 0000000..128108f --- /dev/null +++ b/ultralytics/models/sam/amg.py @@ -0,0 +1,187 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import math +from itertools import product +from typing import Any, Generator, List, Tuple + +import numpy as np +import torch + + +def is_box_near_crop_edge( + boxes: torch.Tensor, crop_box: List[int], orig_box: List[int], atol: float = 20.0 +) -> torch.Tensor: + """Return a boolean tensor indicating if boxes are near the crop edge.""" + crop_box_torch = torch.as_tensor(crop_box, dtype=torch.float, device=boxes.device) + orig_box_torch = torch.as_tensor(orig_box, dtype=torch.float, device=boxes.device) + boxes = uncrop_boxes_xyxy(boxes, crop_box).float() + near_crop_edge = torch.isclose(boxes, crop_box_torch[None, :], atol=atol, rtol=0) + near_image_edge = torch.isclose(boxes, orig_box_torch[None, :], atol=atol, rtol=0) + near_crop_edge = torch.logical_and(near_crop_edge, ~near_image_edge) + return torch.any(near_crop_edge, dim=1) + + +def batch_iterator(batch_size: int, *args) -> Generator[List[Any], None, None]: + """Yield batches of data from the input arguments.""" + assert args and all(len(a) == len(args[0]) for a in args), "Batched iteration must have same-size inputs." + n_batches = len(args[0]) // batch_size + int(len(args[0]) % batch_size != 0) + for b in range(n_batches): + yield [arg[b * batch_size : (b + 1) * batch_size] for arg in args] + + +def calculate_stability_score(masks: torch.Tensor, mask_threshold: float, threshold_offset: float) -> torch.Tensor: + """ + Computes the stability score for a batch of masks. + + The stability score is the IoU between the binary masks obtained by thresholding the predicted mask logits at high + and low values. + + Notes: + - One mask is always contained inside the other. + - Save memory by preventing unnecessary cast to torch.int64 + """ + intersections = (masks > (mask_threshold + threshold_offset)).sum(-1, dtype=torch.int16).sum(-1, dtype=torch.int32) + unions = (masks > (mask_threshold - threshold_offset)).sum(-1, dtype=torch.int16).sum(-1, dtype=torch.int32) + return intersections / unions + + +def build_point_grid(n_per_side: int) -> np.ndarray: + """Generate a 2D grid of evenly spaced points in the range [0,1]x[0,1].""" + offset = 1 / (2 * n_per_side) + points_one_side = np.linspace(offset, 1 - offset, n_per_side) + points_x = np.tile(points_one_side[None, :], (n_per_side, 1)) + points_y = np.tile(points_one_side[:, None], (1, n_per_side)) + return np.stack([points_x, points_y], axis=-1).reshape(-1, 2) + + +def build_all_layer_point_grids(n_per_side: int, n_layers: int, scale_per_layer: int) -> List[np.ndarray]: + """Generate point grids for all crop layers.""" + return [build_point_grid(int(n_per_side / (scale_per_layer**i))) for i in range(n_layers + 1)] + + +def generate_crop_boxes( + im_size: Tuple[int, ...], n_layers: int, overlap_ratio: float +) -> Tuple[List[List[int]], List[int]]: + """ + Generates a list of crop boxes of different sizes. + + Each layer has (2**i)**2 boxes for the ith layer. + """ + crop_boxes, layer_idxs = [], [] + im_h, im_w = im_size + short_side = min(im_h, im_w) + + # Original image + crop_boxes.append([0, 0, im_w, im_h]) + layer_idxs.append(0) + + def crop_len(orig_len, n_crops, overlap): + """Crops bounding boxes to the size of the input image.""" + return int(math.ceil((overlap * (n_crops - 1) + orig_len) / n_crops)) + + for i_layer in range(n_layers): + n_crops_per_side = 2 ** (i_layer + 1) + overlap = int(overlap_ratio * short_side * (2 / n_crops_per_side)) + + crop_w = crop_len(im_w, n_crops_per_side, overlap) + crop_h = crop_len(im_h, n_crops_per_side, overlap) + + crop_box_x0 = [int((crop_w - overlap) * i) for i in range(n_crops_per_side)] + crop_box_y0 = [int((crop_h - overlap) * i) for i in range(n_crops_per_side)] + + # Crops in XYWH format + for x0, y0 in product(crop_box_x0, crop_box_y0): + box = [x0, y0, min(x0 + crop_w, im_w), min(y0 + crop_h, im_h)] + crop_boxes.append(box) + layer_idxs.append(i_layer + 1) + + return crop_boxes, layer_idxs + + +def uncrop_boxes_xyxy(boxes: torch.Tensor, crop_box: List[int]) -> torch.Tensor: + """Uncrop bounding boxes by adding the crop box offset.""" + x0, y0, _, _ = crop_box + offset = torch.tensor([[x0, y0, x0, y0]], device=boxes.device) + # Check if boxes has a channel dimension + if len(boxes.shape) == 3: + offset = offset.unsqueeze(1) + return boxes + offset + + +def uncrop_points(points: torch.Tensor, crop_box: List[int]) -> torch.Tensor: + """Uncrop points by adding the crop box offset.""" + x0, y0, _, _ = crop_box + offset = torch.tensor([[x0, y0]], device=points.device) + # Check if points has a channel dimension + if len(points.shape) == 3: + offset = offset.unsqueeze(1) + return points + offset + + +def uncrop_masks(masks: torch.Tensor, crop_box: List[int], orig_h: int, orig_w: int) -> torch.Tensor: + """Uncrop masks by padding them to the original image size.""" + x0, y0, x1, y1 = crop_box + if x0 == 0 and y0 == 0 and x1 == orig_w and y1 == orig_h: + return masks + # Coordinate transform masks + pad_x, pad_y = orig_w - (x1 - x0), orig_h - (y1 - y0) + pad = (x0, pad_x - x0, y0, pad_y - y0) + return torch.nn.functional.pad(masks, pad, value=0) + + +def remove_small_regions(mask: np.ndarray, area_thresh: float, mode: str) -> Tuple[np.ndarray, bool]: + """Remove small disconnected regions or holes in a mask, returning the mask and a modification indicator.""" + import cv2 # type: ignore + + assert mode in {"holes", "islands"} + correct_holes = mode == "holes" + working_mask = (correct_holes ^ mask).astype(np.uint8) + n_labels, regions, stats, _ = cv2.connectedComponentsWithStats(working_mask, 8) + sizes = stats[:, -1][1:] # Row 0 is background label + small_regions = [i + 1 for i, s in enumerate(sizes) if s < area_thresh] + if not small_regions: + return mask, False + fill_labels = [0] + small_regions + if not correct_holes: + # If every region is below threshold, keep largest + fill_labels = [i for i in range(n_labels) if i not in fill_labels] or [int(np.argmax(sizes)) + 1] + mask = np.isin(regions, fill_labels) + return mask, True + + +def batched_mask_to_box(masks: torch.Tensor) -> torch.Tensor: + """ + Calculates boxes in XYXY format around masks. + + Return [0,0,0,0] for an empty mask. For input shape C1xC2x...xHxW, the output shape is C1xC2x...x4. + """ + # torch.max below raises an error on empty inputs, just skip in this case + if torch.numel(masks) == 0: + return torch.zeros(*masks.shape[:-2], 4, device=masks.device) + + # Normalize shape to CxHxW + shape = masks.shape + h, w = shape[-2:] + masks = masks.flatten(0, -3) if len(shape) > 2 else masks.unsqueeze(0) + # Get top and bottom edges + in_height, _ = torch.max(masks, dim=-1) + in_height_coords = in_height * torch.arange(h, device=in_height.device)[None, :] + bottom_edges, _ = torch.max(in_height_coords, dim=-1) + in_height_coords = in_height_coords + h * (~in_height) + top_edges, _ = torch.min(in_height_coords, dim=-1) + + # Get left and right edges + in_width, _ = torch.max(masks, dim=-2) + in_width_coords = in_width * torch.arange(w, device=in_width.device)[None, :] + right_edges, _ = torch.max(in_width_coords, dim=-1) + in_width_coords = in_width_coords + w * (~in_width) + left_edges, _ = torch.min(in_width_coords, dim=-1) + + # If the mask is empty the right edge will be to the left of the left edge. + # Replace these boxes with [0, 0, 0, 0] + empty_filter = (right_edges < left_edges) | (bottom_edges < top_edges) + out = torch.stack([left_edges, top_edges, right_edges, bottom_edges], dim=-1) + out = out * (~empty_filter).unsqueeze(-1) + + # Return to original shape + return out.reshape(*shape[:-2], 4) if len(shape) > 2 else out[0] diff --git a/ultralytics/models/sam/build.py b/ultralytics/models/sam/build.py new file mode 100644 index 0000000..cb3a7c6 --- /dev/null +++ b/ultralytics/models/sam/build.py @@ -0,0 +1,161 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +# Copyright (c) Meta Platforms, Inc. and affiliates. +# All rights reserved. + +# This source code is licensed under the license found in the +# LICENSE file in the root directory of this source tree. + +from functools import partial + +import torch + +from ultralytics.utils.downloads import attempt_download_asset + +from .modules.decoders import MaskDecoder +from .modules.encoders import ImageEncoderViT, PromptEncoder +from .modules.sam import Sam +from .modules.tiny_encoder import TinyViT +from .modules.transformer import TwoWayTransformer + + +def build_sam_vit_h(checkpoint=None): + """Build and return a Segment Anything Model (SAM) h-size model.""" + return _build_sam( + encoder_embed_dim=1280, + encoder_depth=32, + encoder_num_heads=16, + encoder_global_attn_indexes=[7, 15, 23, 31], + checkpoint=checkpoint, + ) + + +def build_sam_vit_l(checkpoint=None): + """Build and return a Segment Anything Model (SAM) l-size model.""" + return _build_sam( + encoder_embed_dim=1024, + encoder_depth=24, + encoder_num_heads=16, + encoder_global_attn_indexes=[5, 11, 17, 23], + checkpoint=checkpoint, + ) + + +def build_sam_vit_b(checkpoint=None): + """Build and return a Segment Anything Model (SAM) b-size model.""" + return _build_sam( + encoder_embed_dim=768, + encoder_depth=12, + encoder_num_heads=12, + encoder_global_attn_indexes=[2, 5, 8, 11], + checkpoint=checkpoint, + ) + + +def build_mobile_sam(checkpoint=None): + """Build and return Mobile Segment Anything Model (Mobile-SAM).""" + return _build_sam( + encoder_embed_dim=[64, 128, 160, 320], + encoder_depth=[2, 2, 6, 2], + encoder_num_heads=[2, 4, 5, 10], + encoder_global_attn_indexes=None, + mobile_sam=True, + checkpoint=checkpoint, + ) + + +def _build_sam( + encoder_embed_dim, encoder_depth, encoder_num_heads, encoder_global_attn_indexes, checkpoint=None, mobile_sam=False +): + """Builds the selected SAM model architecture.""" + prompt_embed_dim = 256 + image_size = 1024 + vit_patch_size = 16 + image_embedding_size = image_size // vit_patch_size + image_encoder = ( + TinyViT( + img_size=1024, + in_chans=3, + num_classes=1000, + embed_dims=encoder_embed_dim, + depths=encoder_depth, + num_heads=encoder_num_heads, + window_sizes=[7, 7, 14, 7], + mlp_ratio=4.0, + drop_rate=0.0, + drop_path_rate=0.0, + use_checkpoint=False, + mbconv_expand_ratio=4.0, + local_conv_size=3, + layer_lr_decay=0.8, + ) + if mobile_sam + else ImageEncoderViT( + depth=encoder_depth, + embed_dim=encoder_embed_dim, + img_size=image_size, + mlp_ratio=4, + norm_layer=partial(torch.nn.LayerNorm, eps=1e-6), + num_heads=encoder_num_heads, + patch_size=vit_patch_size, + qkv_bias=True, + use_rel_pos=True, + global_attn_indexes=encoder_global_attn_indexes, + window_size=14, + out_chans=prompt_embed_dim, + ) + ) + sam = Sam( + image_encoder=image_encoder, + prompt_encoder=PromptEncoder( + embed_dim=prompt_embed_dim, + image_embedding_size=(image_embedding_size, image_embedding_size), + input_image_size=(image_size, image_size), + mask_in_chans=16, + ), + mask_decoder=MaskDecoder( + num_multimask_outputs=3, + transformer=TwoWayTransformer( + depth=2, + embedding_dim=prompt_embed_dim, + mlp_dim=2048, + num_heads=8, + ), + transformer_dim=prompt_embed_dim, + iou_head_depth=3, + iou_head_hidden_dim=256, + ), + pixel_mean=[123.675, 116.28, 103.53], + pixel_std=[58.395, 57.12, 57.375], + ) + if checkpoint is not None: + checkpoint = attempt_download_asset(checkpoint) + with open(checkpoint, "rb") as f: + state_dict = torch.load(f) + sam.load_state_dict(state_dict) + sam.eval() + # sam.load_state_dict(torch.load(checkpoint), strict=True) + # sam.eval() + return sam + + +sam_model_map = { + "sam_h.pt": build_sam_vit_h, + "sam_l.pt": build_sam_vit_l, + "sam_b.pt": build_sam_vit_b, + "mobile_sam.pt": build_mobile_sam, +} + + +def build_sam(ckpt="sam_b.pt"): + """Build a SAM model specified by ckpt.""" + model_builder = None + ckpt = str(ckpt) # to allow Path ckpt types + for k in sam_model_map.keys(): + if ckpt.endswith(k): + model_builder = sam_model_map.get(k) + + if not model_builder: + raise FileNotFoundError(f"{ckpt} is not a supported SAM model. Available models are: \n {sam_model_map.keys()}") + + return model_builder(ckpt) diff --git a/ultralytics/models/sam/model.py b/ultralytics/models/sam/model.py new file mode 100644 index 0000000..feaeb55 --- /dev/null +++ b/ultralytics/models/sam/model.py @@ -0,0 +1,115 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +""" +SAM model interface. + +This module provides an interface to the Segment Anything Model (SAM) from Ultralytics, designed for real-time image +segmentation tasks. The SAM model allows for promptable segmentation with unparalleled versatility in image analysis, +and has been trained on the SA-1B dataset. It features zero-shot performance capabilities, enabling it to adapt to new +image distributions and tasks without prior knowledge. + +Key Features: + - Promptable segmentation + - Real-time performance + - Zero-shot transfer capabilities + - Trained on SA-1B dataset +""" + +from pathlib import Path + +from ultralytics.engine.model import Model +from ultralytics.utils.torch_utils import model_info + +from .build import build_sam +from .predict import Predictor + + +class SAM(Model): + """ + SAM (Segment Anything Model) interface class. + + SAM is designed for promptable real-time image segmentation. It can be used with a variety of prompts such as + bounding boxes, points, or labels. The model has capabilities for zero-shot performance and is trained on the SA-1B + dataset. + """ + + def __init__(self, model="sam_b.pt") -> None: + """ + Initializes the SAM model with a pre-trained model file. + + Args: + model (str): Path to the pre-trained SAM model file. File should have a .pt or .pth extension. + + Raises: + NotImplementedError: If the model file extension is not .pt or .pth. + """ + if model and Path(model).suffix not in {".pt", ".pth"}: + raise NotImplementedError("SAM prediction requires pre-trained *.pt or *.pth model.") + super().__init__(model=model, task="segment") + + def _load(self, weights: str, task=None): + """ + Loads the specified weights into the SAM model. + + Args: + weights (str): Path to the weights file. + task (str, optional): Task name. Defaults to None. + """ + self.model = build_sam(weights) + + def predict(self, source, stream=False, bboxes=None, points=None, labels=None, **kwargs): + """ + Performs segmentation prediction on the given image or video source. + + Args: + source (str): Path to the image or video file, or a PIL.Image object, or a numpy.ndarray object. + stream (bool, optional): If True, enables real-time streaming. Defaults to False. + bboxes (list, optional): List of bounding box coordinates for prompted segmentation. Defaults to None. + points (list, optional): List of points for prompted segmentation. Defaults to None. + labels (list, optional): List of labels for prompted segmentation. Defaults to None. + + Returns: + (list): The model predictions. + """ + overrides = dict(conf=0.25, task="segment", mode="predict", imgsz=1024) + kwargs.update(overrides) + prompts = dict(bboxes=bboxes, points=points, labels=labels) + return super().predict(source, stream, prompts=prompts, **kwargs) + + def __call__(self, source=None, stream=False, bboxes=None, points=None, labels=None, **kwargs): + """ + Alias for the 'predict' method. + + Args: + source (str): Path to the image or video file, or a PIL.Image object, or a numpy.ndarray object. + stream (bool, optional): If True, enables real-time streaming. Defaults to False. + bboxes (list, optional): List of bounding box coordinates for prompted segmentation. Defaults to None. + points (list, optional): List of points for prompted segmentation. Defaults to None. + labels (list, optional): List of labels for prompted segmentation. Defaults to None. + + Returns: + (list): The model predictions. + """ + return self.predict(source, stream, bboxes, points, labels, **kwargs) + + def info(self, detailed=False, verbose=True): + """ + Logs information about the SAM model. + + Args: + detailed (bool, optional): If True, displays detailed information about the model. Defaults to False. + verbose (bool, optional): If True, displays information on the console. Defaults to True. + + Returns: + (tuple): A tuple containing the model's information. + """ + return model_info(self.model, detailed=detailed, verbose=verbose) + + @property + def task_map(self): + """ + Provides a mapping from the 'segment' task to its corresponding 'Predictor'. + + Returns: + (dict): A dictionary mapping the 'segment' task to its corresponding 'Predictor'. + """ + return {"segment": {"predictor": Predictor}} diff --git a/ultralytics/models/sam/modules/__init__.py b/ultralytics/models/sam/modules/__init__.py new file mode 100644 index 0000000..9e68dc1 --- /dev/null +++ b/ultralytics/models/sam/modules/__init__.py @@ -0,0 +1 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license diff --git a/ultralytics/models/sam/modules/decoders.py b/ultralytics/models/sam/modules/decoders.py new file mode 100644 index 0000000..073b1ad --- /dev/null +++ b/ultralytics/models/sam/modules/decoders.py @@ -0,0 +1,190 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from typing import List, Tuple, Type + +import torch +from torch import nn +from torch.nn import functional as F + +from ultralytics.nn.modules import LayerNorm2d + + +class MaskDecoder(nn.Module): + """ + Decoder module for generating masks and their associated quality scores, using a transformer architecture to predict + masks given image and prompt embeddings. + + Attributes: + transformer_dim (int): Channel dimension for the transformer module. + transformer (nn.Module): The transformer module used for mask prediction. + num_multimask_outputs (int): Number of masks to predict for disambiguating masks. + iou_token (nn.Embedding): Embedding for the IoU token. + num_mask_tokens (int): Number of mask tokens. + mask_tokens (nn.Embedding): Embedding for the mask tokens. + output_upscaling (nn.Sequential): Neural network sequence for upscaling the output. + output_hypernetworks_mlps (nn.ModuleList): Hypernetwork MLPs for generating masks. + iou_prediction_head (nn.Module): MLP for predicting mask quality. + """ + + def __init__( + self, + *, + transformer_dim: int, + transformer: nn.Module, + num_multimask_outputs: int = 3, + activation: Type[nn.Module] = nn.GELU, + iou_head_depth: int = 3, + iou_head_hidden_dim: int = 256, + ) -> None: + """ + Predicts masks given an image and prompt embeddings, using a transformer architecture. + + Args: + transformer_dim (int): the channel dimension of the transformer module + transformer (nn.Module): the transformer used to predict masks + num_multimask_outputs (int): the number of masks to predict when disambiguating masks + activation (nn.Module): the type of activation to use when upscaling masks + iou_head_depth (int): the depth of the MLP used to predict mask quality + iou_head_hidden_dim (int): the hidden dimension of the MLP used to predict mask quality + """ + super().__init__() + self.transformer_dim = transformer_dim + self.transformer = transformer + + self.num_multimask_outputs = num_multimask_outputs + + self.iou_token = nn.Embedding(1, transformer_dim) + self.num_mask_tokens = num_multimask_outputs + 1 + self.mask_tokens = nn.Embedding(self.num_mask_tokens, transformer_dim) + + self.output_upscaling = nn.Sequential( + nn.ConvTranspose2d(transformer_dim, transformer_dim // 4, kernel_size=2, stride=2), + LayerNorm2d(transformer_dim // 4), + activation(), + nn.ConvTranspose2d(transformer_dim // 4, transformer_dim // 8, kernel_size=2, stride=2), + activation(), + ) + self.output_hypernetworks_mlps = nn.ModuleList( + [MLP(transformer_dim, transformer_dim, transformer_dim // 8, 3) for _ in range(self.num_mask_tokens)] + ) + + self.iou_prediction_head = MLP(transformer_dim, iou_head_hidden_dim, self.num_mask_tokens, iou_head_depth) + + def forward( + self, + image_embeddings: torch.Tensor, + image_pe: torch.Tensor, + sparse_prompt_embeddings: torch.Tensor, + dense_prompt_embeddings: torch.Tensor, + multimask_output: bool, + ) -> Tuple[torch.Tensor, torch.Tensor]: + """ + Predict masks given image and prompt embeddings. + + Args: + image_embeddings (torch.Tensor): the embeddings from the image encoder + image_pe (torch.Tensor): positional encoding with the shape of image_embeddings + sparse_prompt_embeddings (torch.Tensor): the embeddings of the points and boxes + dense_prompt_embeddings (torch.Tensor): the embeddings of the mask inputs + multimask_output (bool): Whether to return multiple masks or a single mask. + + Returns: + torch.Tensor: batched predicted masks + torch.Tensor: batched predictions of mask quality + """ + masks, iou_pred = self.predict_masks( + image_embeddings=image_embeddings, + image_pe=image_pe, + sparse_prompt_embeddings=sparse_prompt_embeddings, + dense_prompt_embeddings=dense_prompt_embeddings, + ) + + # Select the correct mask or masks for output + mask_slice = slice(1, None) if multimask_output else slice(0, 1) + masks = masks[:, mask_slice, :, :] + iou_pred = iou_pred[:, mask_slice] + + # Prepare output + return masks, iou_pred + + def predict_masks( + self, + image_embeddings: torch.Tensor, + image_pe: torch.Tensor, + sparse_prompt_embeddings: torch.Tensor, + dense_prompt_embeddings: torch.Tensor, + ) -> Tuple[torch.Tensor, torch.Tensor]: + """ + Predicts masks. + + See 'forward' for more details. + """ + # Concatenate output tokens + output_tokens = torch.cat([self.iou_token.weight, self.mask_tokens.weight], dim=0) + output_tokens = output_tokens.unsqueeze(0).expand(sparse_prompt_embeddings.shape[0], -1, -1) + tokens = torch.cat((output_tokens, sparse_prompt_embeddings), dim=1) + + # Expand per-image data in batch direction to be per-mask + src = torch.repeat_interleave(image_embeddings, tokens.shape[0], dim=0) + src = src + dense_prompt_embeddings + pos_src = torch.repeat_interleave(image_pe, tokens.shape[0], dim=0) + b, c, h, w = src.shape + + # Run the transformer + hs, src = self.transformer(src, pos_src, tokens) + iou_token_out = hs[:, 0, :] + mask_tokens_out = hs[:, 1 : (1 + self.num_mask_tokens), :] + + # Upscale mask embeddings and predict masks using the mask tokens + src = src.transpose(1, 2).view(b, c, h, w) + upscaled_embedding = self.output_upscaling(src) + hyper_in_list: List[torch.Tensor] = [ + self.output_hypernetworks_mlps[i](mask_tokens_out[:, i, :]) for i in range(self.num_mask_tokens) + ] + hyper_in = torch.stack(hyper_in_list, dim=1) + b, c, h, w = upscaled_embedding.shape + masks = (hyper_in @ upscaled_embedding.view(b, c, h * w)).view(b, -1, h, w) + + # Generate mask quality predictions + iou_pred = self.iou_prediction_head(iou_token_out) + + return masks, iou_pred + + +class MLP(nn.Module): + """ + MLP (Multi-Layer Perceptron) model lightly adapted from + https://github.com/facebookresearch/MaskFormer/blob/main/mask_former/modeling/transformer/transformer_predictor.py + """ + + def __init__( + self, + input_dim: int, + hidden_dim: int, + output_dim: int, + num_layers: int, + sigmoid_output: bool = False, + ) -> None: + """ + Initializes the MLP (Multi-Layer Perceptron) model. + + Args: + input_dim (int): The dimensionality of the input features. + hidden_dim (int): The dimensionality of the hidden layers. + output_dim (int): The dimensionality of the output layer. + num_layers (int): The number of hidden layers. + sigmoid_output (bool, optional): Apply a sigmoid activation to the output layer. Defaults to False. + """ + super().__init__() + self.num_layers = num_layers + h = [hidden_dim] * (num_layers - 1) + self.layers = nn.ModuleList(nn.Linear(n, k) for n, k in zip([input_dim] + h, h + [output_dim])) + self.sigmoid_output = sigmoid_output + + def forward(self, x): + """Executes feedforward within the neural network module and applies activation.""" + for i, layer in enumerate(self.layers): + x = F.relu(layer(x)) if i < self.num_layers - 1 else layer(x) + if self.sigmoid_output: + x = torch.sigmoid(x) + return x diff --git a/ultralytics/models/sam/modules/encoders.py b/ultralytics/models/sam/modules/encoders.py new file mode 100644 index 0000000..a51c347 --- /dev/null +++ b/ultralytics/models/sam/modules/encoders.py @@ -0,0 +1,603 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from typing import Any, Optional, Tuple, Type + +import numpy as np +import torch +import torch.nn as nn +import torch.nn.functional as F + +from ultralytics.nn.modules import LayerNorm2d, MLPBlock + + +class ImageEncoderViT(nn.Module): + """ + An image encoder using Vision Transformer (ViT) architecture for encoding an image into a compact latent space. The + encoder takes an image, splits it into patches, and processes these patches through a series of transformer blocks. + The encoded patches are then processed through a neck to generate the final encoded representation. + + This class and its supporting functions below lightly adapted from the ViTDet backbone available at + https://github.com/facebookresearch/detectron2/blob/main/detectron2/modeling/backbone/vit.py. + + Attributes: + img_size (int): Dimension of input images, assumed to be square. + patch_embed (PatchEmbed): Module for patch embedding. + pos_embed (nn.Parameter, optional): Absolute positional embedding for patches. + blocks (nn.ModuleList): List of transformer blocks for processing patch embeddings. + neck (nn.Sequential): Neck module to further process the output. + """ + + def __init__( + self, + img_size: int = 1024, + patch_size: int = 16, + in_chans: int = 3, + embed_dim: int = 768, + depth: int = 12, + num_heads: int = 12, + mlp_ratio: float = 4.0, + out_chans: int = 256, + qkv_bias: bool = True, + norm_layer: Type[nn.Module] = nn.LayerNorm, + act_layer: Type[nn.Module] = nn.GELU, + use_abs_pos: bool = True, + use_rel_pos: bool = False, + rel_pos_zero_init: bool = True, + window_size: int = 0, + global_attn_indexes: Tuple[int, ...] = (), + ) -> None: + """ + Args: + img_size (int): Input image size. + patch_size (int): Patch size. + in_chans (int): Number of input image channels. + embed_dim (int): Patch embedding dimension. + depth (int): Depth of ViT. + num_heads (int): Number of attention heads in each ViT block. + mlp_ratio (float): Ratio of mlp hidden dim to embedding dim. + qkv_bias (bool): If True, add a learnable bias to query, key, value. + norm_layer (nn.Module): Normalization layer. + act_layer (nn.Module): Activation layer. + use_abs_pos (bool): If True, use absolute positional embeddings. + use_rel_pos (bool): If True, add relative positional embeddings to the attention map. + rel_pos_zero_init (bool): If True, zero initialize relative positional parameters. + window_size (int): Window size for window attention blocks. + global_attn_indexes (list): Indexes for blocks using global attention. + """ + super().__init__() + self.img_size = img_size + + self.patch_embed = PatchEmbed( + kernel_size=(patch_size, patch_size), + stride=(patch_size, patch_size), + in_chans=in_chans, + embed_dim=embed_dim, + ) + + self.pos_embed: Optional[nn.Parameter] = None + if use_abs_pos: + # Initialize absolute positional embedding with pretrain image size. + self.pos_embed = nn.Parameter(torch.zeros(1, img_size // patch_size, img_size // patch_size, embed_dim)) + + self.blocks = nn.ModuleList() + for i in range(depth): + block = Block( + dim=embed_dim, + num_heads=num_heads, + mlp_ratio=mlp_ratio, + qkv_bias=qkv_bias, + norm_layer=norm_layer, + act_layer=act_layer, + use_rel_pos=use_rel_pos, + rel_pos_zero_init=rel_pos_zero_init, + window_size=window_size if i not in global_attn_indexes else 0, + input_size=(img_size // patch_size, img_size // patch_size), + ) + self.blocks.append(block) + + self.neck = nn.Sequential( + nn.Conv2d( + embed_dim, + out_chans, + kernel_size=1, + bias=False, + ), + LayerNorm2d(out_chans), + nn.Conv2d( + out_chans, + out_chans, + kernel_size=3, + padding=1, + bias=False, + ), + LayerNorm2d(out_chans), + ) + + def forward(self, x: torch.Tensor) -> torch.Tensor: + """Processes input through patch embedding, applies positional embedding if present, and passes through blocks + and neck. + """ + x = self.patch_embed(x) + if self.pos_embed is not None: + x = x + self.pos_embed + for blk in self.blocks: + x = blk(x) + return self.neck(x.permute(0, 3, 1, 2)) + + +class PromptEncoder(nn.Module): + """ + Encodes different types of prompts, including points, boxes, and masks, for input to SAM's mask decoder. The encoder + produces both sparse and dense embeddings for the input prompts. + + Attributes: + embed_dim (int): Dimension of the embeddings. + input_image_size (Tuple[int, int]): Size of the input image as (H, W). + image_embedding_size (Tuple[int, int]): Spatial size of the image embedding as (H, W). + pe_layer (PositionEmbeddingRandom): Module for random position embedding. + num_point_embeddings (int): Number of point embeddings for different types of points. + point_embeddings (nn.ModuleList): List of point embeddings. + not_a_point_embed (nn.Embedding): Embedding for points that are not a part of any label. + mask_input_size (Tuple[int, int]): Size of the input mask. + mask_downscaling (nn.Sequential): Neural network for downscaling the mask. + no_mask_embed (nn.Embedding): Embedding for cases where no mask is provided. + """ + + def __init__( + self, + embed_dim: int, + image_embedding_size: Tuple[int, int], + input_image_size: Tuple[int, int], + mask_in_chans: int, + activation: Type[nn.Module] = nn.GELU, + ) -> None: + """ + Encodes prompts for input to SAM's mask decoder. + + Args: + embed_dim (int): The prompts' embedding dimension + image_embedding_size (tuple(int, int)): The spatial size of the + image embedding, as (H, W). + input_image_size (int): The padded size of the image as input + to the image encoder, as (H, W). + mask_in_chans (int): The number of hidden channels used for + encoding input masks. + activation (nn.Module): The activation to use when encoding + input masks. + """ + super().__init__() + self.embed_dim = embed_dim + self.input_image_size = input_image_size + self.image_embedding_size = image_embedding_size + self.pe_layer = PositionEmbeddingRandom(embed_dim // 2) + + self.num_point_embeddings: int = 4 # pos/neg point + 2 box corners + point_embeddings = [nn.Embedding(1, embed_dim) for _ in range(self.num_point_embeddings)] + self.point_embeddings = nn.ModuleList(point_embeddings) + self.not_a_point_embed = nn.Embedding(1, embed_dim) + + self.mask_input_size = (4 * image_embedding_size[0], 4 * image_embedding_size[1]) + self.mask_downscaling = nn.Sequential( + nn.Conv2d(1, mask_in_chans // 4, kernel_size=2, stride=2), + LayerNorm2d(mask_in_chans // 4), + activation(), + nn.Conv2d(mask_in_chans // 4, mask_in_chans, kernel_size=2, stride=2), + LayerNorm2d(mask_in_chans), + activation(), + nn.Conv2d(mask_in_chans, embed_dim, kernel_size=1), + ) + self.no_mask_embed = nn.Embedding(1, embed_dim) + + def get_dense_pe(self) -> torch.Tensor: + """ + Returns the positional encoding used to encode point prompts, applied to a dense set of points the shape of the + image encoding. + + Returns: + torch.Tensor: Positional encoding with shape 1x(embed_dim)x(embedding_h)x(embedding_w) + """ + return self.pe_layer(self.image_embedding_size).unsqueeze(0) + + def _embed_points(self, points: torch.Tensor, labels: torch.Tensor, pad: bool) -> torch.Tensor: + """Embeds point prompts.""" + points = points + 0.5 # Shift to center of pixel + if pad: + padding_point = torch.zeros((points.shape[0], 1, 2), device=points.device) + padding_label = -torch.ones((labels.shape[0], 1), device=labels.device) + points = torch.cat([points, padding_point], dim=1) + labels = torch.cat([labels, padding_label], dim=1) + point_embedding = self.pe_layer.forward_with_coords(points, self.input_image_size) + point_embedding[labels == -1] = 0.0 + point_embedding[labels == -1] += self.not_a_point_embed.weight + point_embedding[labels == 0] += self.point_embeddings[0].weight + point_embedding[labels == 1] += self.point_embeddings[1].weight + return point_embedding + + def _embed_boxes(self, boxes: torch.Tensor) -> torch.Tensor: + """Embeds box prompts.""" + boxes = boxes + 0.5 # Shift to center of pixel + coords = boxes.reshape(-1, 2, 2) + corner_embedding = self.pe_layer.forward_with_coords(coords, self.input_image_size) + corner_embedding[:, 0, :] += self.point_embeddings[2].weight + corner_embedding[:, 1, :] += self.point_embeddings[3].weight + return corner_embedding + + def _embed_masks(self, masks: torch.Tensor) -> torch.Tensor: + """Embeds mask inputs.""" + return self.mask_downscaling(masks) + + def _get_batch_size( + self, + points: Optional[Tuple[torch.Tensor, torch.Tensor]], + boxes: Optional[torch.Tensor], + masks: Optional[torch.Tensor], + ) -> int: + """Gets the batch size of the output given the batch size of the input prompts.""" + if points is not None: + return points[0].shape[0] + elif boxes is not None: + return boxes.shape[0] + elif masks is not None: + return masks.shape[0] + else: + return 1 + + def _get_device(self) -> torch.device: + """Returns the device of the first point embedding's weight tensor.""" + return self.point_embeddings[0].weight.device + + def forward( + self, + points: Optional[Tuple[torch.Tensor, torch.Tensor]], + boxes: Optional[torch.Tensor], + masks: Optional[torch.Tensor], + ) -> Tuple[torch.Tensor, torch.Tensor]: + """ + Embeds different types of prompts, returning both sparse and dense embeddings. + + Args: + points (tuple(torch.Tensor, torch.Tensor), None): point coordinates and labels to embed. + boxes (torch.Tensor, None): boxes to embed + masks (torch.Tensor, None): masks to embed + + Returns: + torch.Tensor: sparse embeddings for the points and boxes, with shape BxNx(embed_dim), where N is determined + by the number of input points and boxes. + torch.Tensor: dense embeddings for the masks, in the shape Bx(embed_dim)x(embed_H)x(embed_W) + """ + bs = self._get_batch_size(points, boxes, masks) + sparse_embeddings = torch.empty((bs, 0, self.embed_dim), device=self._get_device()) + if points is not None: + coords, labels = points + point_embeddings = self._embed_points(coords, labels, pad=(boxes is None)) + sparse_embeddings = torch.cat([sparse_embeddings, point_embeddings], dim=1) + if boxes is not None: + box_embeddings = self._embed_boxes(boxes) + sparse_embeddings = torch.cat([sparse_embeddings, box_embeddings], dim=1) + + if masks is not None: + dense_embeddings = self._embed_masks(masks) + else: + dense_embeddings = self.no_mask_embed.weight.reshape(1, -1, 1, 1).expand( + bs, -1, self.image_embedding_size[0], self.image_embedding_size[1] + ) + + return sparse_embeddings, dense_embeddings + + +class PositionEmbeddingRandom(nn.Module): + """Positional encoding using random spatial frequencies.""" + + def __init__(self, num_pos_feats: int = 64, scale: Optional[float] = None) -> None: + """Initializes a position embedding using random spatial frequencies.""" + super().__init__() + if scale is None or scale <= 0.0: + scale = 1.0 + self.register_buffer("positional_encoding_gaussian_matrix", scale * torch.randn((2, num_pos_feats))) + + # Set non-deterministic for forward() error 'cumsum_cuda_kernel does not have a deterministic implementation' + torch.use_deterministic_algorithms(False) + torch.backends.cudnn.deterministic = False + + def _pe_encoding(self, coords: torch.Tensor) -> torch.Tensor: + """Positionally encode points that are normalized to [0,1].""" + # Assuming coords are in [0, 1]^2 square and have d_1 x ... x d_n x 2 shape + coords = 2 * coords - 1 + coords = coords @ self.positional_encoding_gaussian_matrix + coords = 2 * np.pi * coords + # Outputs d_1 x ... x d_n x C shape + return torch.cat([torch.sin(coords), torch.cos(coords)], dim=-1) + + def forward(self, size: Tuple[int, int]) -> torch.Tensor: + """Generate positional encoding for a grid of the specified size.""" + h, w = size + device: Any = self.positional_encoding_gaussian_matrix.device + grid = torch.ones((h, w), device=device, dtype=torch.float32) + y_embed = grid.cumsum(dim=0) - 0.5 + x_embed = grid.cumsum(dim=1) - 0.5 + y_embed = y_embed / h + x_embed = x_embed / w + + pe = self._pe_encoding(torch.stack([x_embed, y_embed], dim=-1)) + return pe.permute(2, 0, 1) # C x H x W + + def forward_with_coords(self, coords_input: torch.Tensor, image_size: Tuple[int, int]) -> torch.Tensor: + """Positionally encode points that are not normalized to [0,1].""" + coords = coords_input.clone() + coords[:, :, 0] = coords[:, :, 0] / image_size[1] + coords[:, :, 1] = coords[:, :, 1] / image_size[0] + return self._pe_encoding(coords.to(torch.float)) # B x N x C + + +class Block(nn.Module): + """Transformer blocks with support of window attention and residual propagation blocks.""" + + def __init__( + self, + dim: int, + num_heads: int, + mlp_ratio: float = 4.0, + qkv_bias: bool = True, + norm_layer: Type[nn.Module] = nn.LayerNorm, + act_layer: Type[nn.Module] = nn.GELU, + use_rel_pos: bool = False, + rel_pos_zero_init: bool = True, + window_size: int = 0, + input_size: Optional[Tuple[int, int]] = None, + ) -> None: + """ + Args: + dim (int): Number of input channels. + num_heads (int): Number of attention heads in each ViT block. + mlp_ratio (float): Ratio of mlp hidden dim to embedding dim. + qkv_bias (bool): If True, add a learnable bias to query, key, value. + norm_layer (nn.Module): Normalization layer. + act_layer (nn.Module): Activation layer. + use_rel_pos (bool): If True, add relative positional embeddings to the attention map. + rel_pos_zero_init (bool): If True, zero initialize relative positional parameters. + window_size (int): Window size for window attention blocks. If it equals 0, then + use global attention. + input_size (tuple(int, int), None): Input resolution for calculating the relative + positional parameter size. + """ + super().__init__() + self.norm1 = norm_layer(dim) + self.attn = Attention( + dim, + num_heads=num_heads, + qkv_bias=qkv_bias, + use_rel_pos=use_rel_pos, + rel_pos_zero_init=rel_pos_zero_init, + input_size=input_size if window_size == 0 else (window_size, window_size), + ) + + self.norm2 = norm_layer(dim) + self.mlp = MLPBlock(embedding_dim=dim, mlp_dim=int(dim * mlp_ratio), act=act_layer) + + self.window_size = window_size + + def forward(self, x: torch.Tensor) -> torch.Tensor: + """Executes a forward pass through the transformer block with window attention and non-overlapping windows.""" + shortcut = x + x = self.norm1(x) + # Window partition + if self.window_size > 0: + H, W = x.shape[1], x.shape[2] + x, pad_hw = window_partition(x, self.window_size) + + x = self.attn(x) + # Reverse window partition + if self.window_size > 0: + x = window_unpartition(x, self.window_size, pad_hw, (H, W)) + + x = shortcut + x + return x + self.mlp(self.norm2(x)) + + +class Attention(nn.Module): + """Multi-head Attention block with relative position embeddings.""" + + def __init__( + self, + dim: int, + num_heads: int = 8, + qkv_bias: bool = True, + use_rel_pos: bool = False, + rel_pos_zero_init: bool = True, + input_size: Optional[Tuple[int, int]] = None, + ) -> None: + """ + Initialize Attention module. + + Args: + dim (int): Number of input channels. + num_heads (int): Number of attention heads. + qkv_bias (bool): If True, add a learnable bias to query, key, value. + rel_pos_zero_init (bool): If True, zero initialize relative positional parameters. + input_size (tuple(int, int), None): Input resolution for calculating the relative + positional parameter size. + """ + super().__init__() + self.num_heads = num_heads + head_dim = dim // num_heads + self.scale = head_dim**-0.5 + + self.qkv = nn.Linear(dim, dim * 3, bias=qkv_bias) + self.proj = nn.Linear(dim, dim) + + self.use_rel_pos = use_rel_pos + if self.use_rel_pos: + assert input_size is not None, "Input size must be provided if using relative positional encoding." + # Initialize relative positional embeddings + self.rel_pos_h = nn.Parameter(torch.zeros(2 * input_size[0] - 1, head_dim)) + self.rel_pos_w = nn.Parameter(torch.zeros(2 * input_size[1] - 1, head_dim)) + + def forward(self, x: torch.Tensor) -> torch.Tensor: + """Applies the forward operation including attention, normalization, MLP, and indexing within window limits.""" + B, H, W, _ = x.shape + # qkv with shape (3, B, nHead, H * W, C) + qkv = self.qkv(x).reshape(B, H * W, 3, self.num_heads, -1).permute(2, 0, 3, 1, 4) + # q, k, v with shape (B * nHead, H * W, C) + q, k, v = qkv.reshape(3, B * self.num_heads, H * W, -1).unbind(0) + + attn = (q * self.scale) @ k.transpose(-2, -1) + + if self.use_rel_pos: + attn = add_decomposed_rel_pos(attn, q, self.rel_pos_h, self.rel_pos_w, (H, W), (H, W)) + + attn = attn.softmax(dim=-1) + x = (attn @ v).view(B, self.num_heads, H, W, -1).permute(0, 2, 3, 1, 4).reshape(B, H, W, -1) + return self.proj(x) + + +def window_partition(x: torch.Tensor, window_size: int) -> Tuple[torch.Tensor, Tuple[int, int]]: + """ + Partition into non-overlapping windows with padding if needed. + Args: + x (tensor): input tokens with [B, H, W, C]. + window_size (int): window size. + + Returns: + windows: windows after partition with [B * num_windows, window_size, window_size, C]. + (Hp, Wp): padded height and width before partition + """ + B, H, W, C = x.shape + + pad_h = (window_size - H % window_size) % window_size + pad_w = (window_size - W % window_size) % window_size + if pad_h > 0 or pad_w > 0: + x = F.pad(x, (0, 0, 0, pad_w, 0, pad_h)) + Hp, Wp = H + pad_h, W + pad_w + + x = x.view(B, Hp // window_size, window_size, Wp // window_size, window_size, C) + windows = x.permute(0, 1, 3, 2, 4, 5).contiguous().view(-1, window_size, window_size, C) + return windows, (Hp, Wp) + + +def window_unpartition( + windows: torch.Tensor, window_size: int, pad_hw: Tuple[int, int], hw: Tuple[int, int] +) -> torch.Tensor: + """ + Window unpartition into original sequences and removing padding. + + Args: + windows (tensor): input tokens with [B * num_windows, window_size, window_size, C]. + window_size (int): window size. + pad_hw (Tuple): padded height and width (Hp, Wp). + hw (Tuple): original height and width (H, W) before padding. + + Returns: + x: unpartitioned sequences with [B, H, W, C]. + """ + Hp, Wp = pad_hw + H, W = hw + B = windows.shape[0] // (Hp * Wp // window_size // window_size) + x = windows.view(B, Hp // window_size, Wp // window_size, window_size, window_size, -1) + x = x.permute(0, 1, 3, 2, 4, 5).contiguous().view(B, Hp, Wp, -1) + + if Hp > H or Wp > W: + x = x[:, :H, :W, :].contiguous() + return x + + +def get_rel_pos(q_size: int, k_size: int, rel_pos: torch.Tensor) -> torch.Tensor: + """ + Get relative positional embeddings according to the relative positions of query and key sizes. + + Args: + q_size (int): size of query q. + k_size (int): size of key k. + rel_pos (Tensor): relative position embeddings (L, C). + + Returns: + Extracted positional embeddings according to relative positions. + """ + max_rel_dist = int(2 * max(q_size, k_size) - 1) + # Interpolate rel pos if needed. + if rel_pos.shape[0] != max_rel_dist: + # Interpolate rel pos. + rel_pos_resized = F.interpolate( + rel_pos.reshape(1, rel_pos.shape[0], -1).permute(0, 2, 1), + size=max_rel_dist, + mode="linear", + ) + rel_pos_resized = rel_pos_resized.reshape(-1, max_rel_dist).permute(1, 0) + else: + rel_pos_resized = rel_pos + + # Scale the coords with short length if shapes for q and k are different. + q_coords = torch.arange(q_size)[:, None] * max(k_size / q_size, 1.0) + k_coords = torch.arange(k_size)[None, :] * max(q_size / k_size, 1.0) + relative_coords = (q_coords - k_coords) + (k_size - 1) * max(q_size / k_size, 1.0) + + return rel_pos_resized[relative_coords.long()] + + +def add_decomposed_rel_pos( + attn: torch.Tensor, + q: torch.Tensor, + rel_pos_h: torch.Tensor, + rel_pos_w: torch.Tensor, + q_size: Tuple[int, int], + k_size: Tuple[int, int], +) -> torch.Tensor: + """ + Calculate decomposed Relative Positional Embeddings from mvitv2 paper at + https://github.com/facebookresearch/mvit/blob/main/mvit/models/attention.py. + + Args: + attn (Tensor): attention map. + q (Tensor): query q in the attention layer with shape (B, q_h * q_w, C). + rel_pos_h (Tensor): relative position embeddings (Lh, C) for height axis. + rel_pos_w (Tensor): relative position embeddings (Lw, C) for width axis. + q_size (Tuple): spatial sequence size of query q with (q_h, q_w). + k_size (Tuple): spatial sequence size of key k with (k_h, k_w). + + Returns: + attn (Tensor): attention map with added relative positional embeddings. + """ + q_h, q_w = q_size + k_h, k_w = k_size + Rh = get_rel_pos(q_h, k_h, rel_pos_h) + Rw = get_rel_pos(q_w, k_w, rel_pos_w) + + B, _, dim = q.shape + r_q = q.reshape(B, q_h, q_w, dim) + rel_h = torch.einsum("bhwc,hkc->bhwk", r_q, Rh) + rel_w = torch.einsum("bhwc,wkc->bhwk", r_q, Rw) + + attn = (attn.view(B, q_h, q_w, k_h, k_w) + rel_h[:, :, :, :, None] + rel_w[:, :, :, None, :]).view( + B, q_h * q_w, k_h * k_w + ) + + return attn + + +class PatchEmbed(nn.Module): + """Image to Patch Embedding.""" + + def __init__( + self, + kernel_size: Tuple[int, int] = (16, 16), + stride: Tuple[int, int] = (16, 16), + padding: Tuple[int, int] = (0, 0), + in_chans: int = 3, + embed_dim: int = 768, + ) -> None: + """ + Initialize PatchEmbed module. + + Args: + kernel_size (Tuple): kernel size of the projection layer. + stride (Tuple): stride of the projection layer. + padding (Tuple): padding size of the projection layer. + in_chans (int): Number of input image channels. + embed_dim (int): Patch embedding dimension. + """ + super().__init__() + + self.proj = nn.Conv2d(in_chans, embed_dim, kernel_size=kernel_size, stride=stride, padding=padding) + + def forward(self, x: torch.Tensor) -> torch.Tensor: + """Computes patch embedding by applying convolution and transposing resulting tensor.""" + return self.proj(x).permute(0, 2, 3, 1) # B C H W -> B H W C diff --git a/ultralytics/models/sam/modules/sam.py b/ultralytics/models/sam/modules/sam.py new file mode 100644 index 0000000..95d9bbe --- /dev/null +++ b/ultralytics/models/sam/modules/sam.py @@ -0,0 +1,65 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +# Copyright (c) Meta Platforms, Inc. and affiliates. +# All rights reserved. + +# This source code is licensed under the license found in the +# LICENSE file in the root directory of this source tree. + +from typing import List + +import torch +from torch import nn + +from .decoders import MaskDecoder +from .encoders import ImageEncoderViT, PromptEncoder + + +class Sam(nn.Module): + """ + Sam (Segment Anything Model) is designed for object segmentation tasks. It uses image encoders to generate image + embeddings, and prompt encoders to encode various types of input prompts. These embeddings are then used by the mask + decoder to predict object masks. + + Attributes: + mask_threshold (float): Threshold value for mask prediction. + image_format (str): Format of the input image, default is 'RGB'. + image_encoder (ImageEncoderViT): The backbone used to encode the image into embeddings. + prompt_encoder (PromptEncoder): Encodes various types of input prompts. + mask_decoder (MaskDecoder): Predicts object masks from the image and prompt embeddings. + pixel_mean (List[float]): Mean pixel values for image normalization. + pixel_std (List[float]): Standard deviation values for image normalization. + """ + + mask_threshold: float = 0.0 + image_format: str = "RGB" + + def __init__( + self, + image_encoder: ImageEncoderViT, + prompt_encoder: PromptEncoder, + mask_decoder: MaskDecoder, + pixel_mean: List[float] = (123.675, 116.28, 103.53), + pixel_std: List[float] = (58.395, 57.12, 57.375), + ) -> None: + """ + Initialize the Sam class to predict object masks from an image and input prompts. + + Note: + All forward() operations moved to SAMPredictor. + + Args: + image_encoder (ImageEncoderViT): The backbone used to encode the image into image embeddings. + prompt_encoder (PromptEncoder): Encodes various types of input prompts. + mask_decoder (MaskDecoder): Predicts masks from the image embeddings and encoded prompts. + pixel_mean (List[float], optional): Mean values for normalizing pixels in the input image. Defaults to + (123.675, 116.28, 103.53). + pixel_std (List[float], optional): Std values for normalizing pixels in the input image. Defaults to + (58.395, 57.12, 57.375). + """ + super().__init__() + self.image_encoder = image_encoder + self.prompt_encoder = prompt_encoder + self.mask_decoder = mask_decoder + self.register_buffer("pixel_mean", torch.Tensor(pixel_mean).view(-1, 1, 1), False) + self.register_buffer("pixel_std", torch.Tensor(pixel_std).view(-1, 1, 1), False) diff --git a/ultralytics/models/sam/modules/tiny_encoder.py b/ultralytics/models/sam/modules/tiny_encoder.py new file mode 100644 index 0000000..28b83f1 --- /dev/null +++ b/ultralytics/models/sam/modules/tiny_encoder.py @@ -0,0 +1,742 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +# -------------------------------------------------------- +# TinyViT Model Architecture +# Copyright (c) 2022 Microsoft +# Adapted from LeViT and Swin Transformer +# LeViT: (https://github.com/facebookresearch/levit) +# Swin: (https://github.com/microsoft/swin-transformer) +# Build the TinyViT Model +# -------------------------------------------------------- + +import itertools +from typing import Tuple + +import torch +import torch.nn as nn +import torch.nn.functional as F +import torch.utils.checkpoint as checkpoint + +from ultralytics.utils.instance import to_2tuple + + +class Conv2d_BN(torch.nn.Sequential): + """A sequential container that performs 2D convolution followed by batch normalization.""" + + def __init__(self, a, b, ks=1, stride=1, pad=0, dilation=1, groups=1, bn_weight_init=1): + """Initializes the MBConv model with given input channels, output channels, expansion ratio, activation, and + drop path. + """ + super().__init__() + self.add_module("c", torch.nn.Conv2d(a, b, ks, stride, pad, dilation, groups, bias=False)) + bn = torch.nn.BatchNorm2d(b) + torch.nn.init.constant_(bn.weight, bn_weight_init) + torch.nn.init.constant_(bn.bias, 0) + self.add_module("bn", bn) + + +class PatchEmbed(nn.Module): + """Embeds images into patches and projects them into a specified embedding dimension.""" + + def __init__(self, in_chans, embed_dim, resolution, activation): + """Initialize the PatchMerging class with specified input, output dimensions, resolution and activation + function. + """ + super().__init__() + img_size: Tuple[int, int] = to_2tuple(resolution) + self.patches_resolution = (img_size[0] // 4, img_size[1] // 4) + self.num_patches = self.patches_resolution[0] * self.patches_resolution[1] + self.in_chans = in_chans + self.embed_dim = embed_dim + n = embed_dim + self.seq = nn.Sequential( + Conv2d_BN(in_chans, n // 2, 3, 2, 1), + activation(), + Conv2d_BN(n // 2, n, 3, 2, 1), + ) + + def forward(self, x): + """Runs input tensor 'x' through the PatchMerging model's sequence of operations.""" + return self.seq(x) + + +class MBConv(nn.Module): + """Mobile Inverted Bottleneck Conv (MBConv) layer, part of the EfficientNet architecture.""" + + def __init__(self, in_chans, out_chans, expand_ratio, activation, drop_path): + """Initializes a convolutional layer with specified dimensions, input resolution, depth, and activation + function. + """ + super().__init__() + self.in_chans = in_chans + self.hidden_chans = int(in_chans * expand_ratio) + self.out_chans = out_chans + + self.conv1 = Conv2d_BN(in_chans, self.hidden_chans, ks=1) + self.act1 = activation() + + self.conv2 = Conv2d_BN(self.hidden_chans, self.hidden_chans, ks=3, stride=1, pad=1, groups=self.hidden_chans) + self.act2 = activation() + + self.conv3 = Conv2d_BN(self.hidden_chans, out_chans, ks=1, bn_weight_init=0.0) + self.act3 = activation() + + # NOTE: `DropPath` is needed only for training. + # self.drop_path = DropPath(drop_path) if drop_path > 0. else nn.Identity() + self.drop_path = nn.Identity() + + def forward(self, x): + """Implements the forward pass for the model architecture.""" + shortcut = x + x = self.conv1(x) + x = self.act1(x) + x = self.conv2(x) + x = self.act2(x) + x = self.conv3(x) + x = self.drop_path(x) + x += shortcut + return self.act3(x) + + +class PatchMerging(nn.Module): + """Merges neighboring patches in the feature map and projects to a new dimension.""" + + def __init__(self, input_resolution, dim, out_dim, activation): + """Initializes the ConvLayer with specific dimension, input resolution, depth, activation, drop path, and other + optional parameters. + """ + super().__init__() + + self.input_resolution = input_resolution + self.dim = dim + self.out_dim = out_dim + self.act = activation() + self.conv1 = Conv2d_BN(dim, out_dim, 1, 1, 0) + stride_c = 1 if out_dim in {320, 448, 576} else 2 + self.conv2 = Conv2d_BN(out_dim, out_dim, 3, stride_c, 1, groups=out_dim) + self.conv3 = Conv2d_BN(out_dim, out_dim, 1, 1, 0) + + def forward(self, x): + """Applies forward pass on the input utilizing convolution and activation layers, and returns the result.""" + if x.ndim == 3: + H, W = self.input_resolution + B = len(x) + # (B, C, H, W) + x = x.view(B, H, W, -1).permute(0, 3, 1, 2) + + x = self.conv1(x) + x = self.act(x) + + x = self.conv2(x) + x = self.act(x) + x = self.conv3(x) + return x.flatten(2).transpose(1, 2) + + +class ConvLayer(nn.Module): + """ + Convolutional Layer featuring multiple MobileNetV3-style inverted bottleneck convolutions (MBConv). + + Optionally applies downsample operations to the output, and provides support for gradient checkpointing. + """ + + def __init__( + self, + dim, + input_resolution, + depth, + activation, + drop_path=0.0, + downsample=None, + use_checkpoint=False, + out_dim=None, + conv_expand_ratio=4.0, + ): + """ + Initializes the ConvLayer with the given dimensions and settings. + + Args: + dim (int): The dimensionality of the input and output. + input_resolution (Tuple[int, int]): The resolution of the input image. + depth (int): The number of MBConv layers in the block. + activation (Callable): Activation function applied after each convolution. + drop_path (Union[float, List[float]]): Drop path rate. Single float or a list of floats for each MBConv. + downsample (Optional[Callable]): Function for downsampling the output. None to skip downsampling. + use_checkpoint (bool): Whether to use gradient checkpointing to save memory. + out_dim (Optional[int]): The dimensionality of the output. None means it will be the same as `dim`. + conv_expand_ratio (float): Expansion ratio for the MBConv layers. + """ + super().__init__() + self.dim = dim + self.input_resolution = input_resolution + self.depth = depth + self.use_checkpoint = use_checkpoint + + # Build blocks + self.blocks = nn.ModuleList( + [ + MBConv( + dim, + dim, + conv_expand_ratio, + activation, + drop_path[i] if isinstance(drop_path, list) else drop_path, + ) + for i in range(depth) + ] + ) + + # Patch merging layer + self.downsample = ( + None + if downsample is None + else downsample(input_resolution, dim=dim, out_dim=out_dim, activation=activation) + ) + + def forward(self, x): + """Processes the input through a series of convolutional layers and returns the activated output.""" + for blk in self.blocks: + x = checkpoint.checkpoint(blk, x) if self.use_checkpoint else blk(x) + return x if self.downsample is None else self.downsample(x) + + +class Mlp(nn.Module): + """ + Multi-layer Perceptron (MLP) for transformer architectures. + + This layer takes an input with in_features, applies layer normalization and two fully-connected layers. + """ + + def __init__(self, in_features, hidden_features=None, out_features=None, act_layer=nn.GELU, drop=0.0): + """Initializes Attention module with the given parameters including dimension, key_dim, number of heads, etc.""" + super().__init__() + out_features = out_features or in_features + hidden_features = hidden_features or in_features + self.norm = nn.LayerNorm(in_features) + self.fc1 = nn.Linear(in_features, hidden_features) + self.fc2 = nn.Linear(hidden_features, out_features) + self.act = act_layer() + self.drop = nn.Dropout(drop) + + def forward(self, x): + """Applies operations on input x and returns modified x, runs downsample if not None.""" + x = self.norm(x) + x = self.fc1(x) + x = self.act(x) + x = self.drop(x) + x = self.fc2(x) + return self.drop(x) + + +class Attention(torch.nn.Module): + """ + Multi-head attention module with support for spatial awareness, applying attention biases based on spatial + resolution. Implements trainable attention biases for each unique offset between spatial positions in the resolution + grid. + + Attributes: + ab (Tensor, optional): Cached attention biases for inference, deleted during training. + """ + + def __init__( + self, + dim, + key_dim, + num_heads=8, + attn_ratio=4, + resolution=(14, 14), + ): + """ + Initializes the Attention module. + + Args: + dim (int): The dimensionality of the input and output. + key_dim (int): The dimensionality of the keys and queries. + num_heads (int, optional): Number of attention heads. Default is 8. + attn_ratio (float, optional): Attention ratio, affecting the dimensions of the value vectors. Default is 4. + resolution (Tuple[int, int], optional): Spatial resolution of the input feature map. Default is (14, 14). + + Raises: + AssertionError: If `resolution` is not a tuple of length 2. + """ + super().__init__() + + assert isinstance(resolution, tuple) and len(resolution) == 2 + self.num_heads = num_heads + self.scale = key_dim**-0.5 + self.key_dim = key_dim + self.nh_kd = nh_kd = key_dim * num_heads + self.d = int(attn_ratio * key_dim) + self.dh = int(attn_ratio * key_dim) * num_heads + self.attn_ratio = attn_ratio + h = self.dh + nh_kd * 2 + + self.norm = nn.LayerNorm(dim) + self.qkv = nn.Linear(dim, h) + self.proj = nn.Linear(self.dh, dim) + + points = list(itertools.product(range(resolution[0]), range(resolution[1]))) + N = len(points) + attention_offsets = {} + idxs = [] + for p1 in points: + for p2 in points: + offset = (abs(p1[0] - p2[0]), abs(p1[1] - p2[1])) + if offset not in attention_offsets: + attention_offsets[offset] = len(attention_offsets) + idxs.append(attention_offsets[offset]) + self.attention_biases = torch.nn.Parameter(torch.zeros(num_heads, len(attention_offsets))) + self.register_buffer("attention_bias_idxs", torch.LongTensor(idxs).view(N, N), persistent=False) + + @torch.no_grad() + def train(self, mode=True): + """Sets the module in training mode and handles attribute 'ab' based on the mode.""" + super().train(mode) + if mode and hasattr(self, "ab"): + del self.ab + else: + self.ab = self.attention_biases[:, self.attention_bias_idxs] + + def forward(self, x): # x + """Performs forward pass over the input tensor 'x' by applying normalization and querying keys/values.""" + B, N, _ = x.shape # B, N, C + + # Normalization + x = self.norm(x) + + qkv = self.qkv(x) + # (B, N, num_heads, d) + q, k, v = qkv.view(B, N, self.num_heads, -1).split([self.key_dim, self.key_dim, self.d], dim=3) + # (B, num_heads, N, d) + q = q.permute(0, 2, 1, 3) + k = k.permute(0, 2, 1, 3) + v = v.permute(0, 2, 1, 3) + self.ab = self.ab.to(self.attention_biases.device) + + attn = (q @ k.transpose(-2, -1)) * self.scale + ( + self.attention_biases[:, self.attention_bias_idxs] if self.training else self.ab + ) + attn = attn.softmax(dim=-1) + x = (attn @ v).transpose(1, 2).reshape(B, N, self.dh) + return self.proj(x) + + +class TinyViTBlock(nn.Module): + """TinyViT Block that applies self-attention and a local convolution to the input.""" + + def __init__( + self, + dim, + input_resolution, + num_heads, + window_size=7, + mlp_ratio=4.0, + drop=0.0, + drop_path=0.0, + local_conv_size=3, + activation=nn.GELU, + ): + """ + Initializes the TinyViTBlock. + + Args: + dim (int): The dimensionality of the input and output. + input_resolution (Tuple[int, int]): Spatial resolution of the input feature map. + num_heads (int): Number of attention heads. + window_size (int, optional): Window size for attention. Default is 7. + mlp_ratio (float, optional): Ratio of mlp hidden dim to embedding dim. Default is 4. + drop (float, optional): Dropout rate. Default is 0. + drop_path (float, optional): Stochastic depth rate. Default is 0. + local_conv_size (int, optional): The kernel size of the local convolution. Default is 3. + activation (torch.nn, optional): Activation function for MLP. Default is nn.GELU. + + Raises: + AssertionError: If `window_size` is not greater than 0. + AssertionError: If `dim` is not divisible by `num_heads`. + """ + super().__init__() + self.dim = dim + self.input_resolution = input_resolution + self.num_heads = num_heads + assert window_size > 0, "window_size must be greater than 0" + self.window_size = window_size + self.mlp_ratio = mlp_ratio + + # NOTE: `DropPath` is needed only for training. + # self.drop_path = DropPath(drop_path) if drop_path > 0. else nn.Identity() + self.drop_path = nn.Identity() + + assert dim % num_heads == 0, "dim must be divisible by num_heads" + head_dim = dim // num_heads + + window_resolution = (window_size, window_size) + self.attn = Attention(dim, head_dim, num_heads, attn_ratio=1, resolution=window_resolution) + + mlp_hidden_dim = int(dim * mlp_ratio) + mlp_activation = activation + self.mlp = Mlp(in_features=dim, hidden_features=mlp_hidden_dim, act_layer=mlp_activation, drop=drop) + + pad = local_conv_size // 2 + self.local_conv = Conv2d_BN(dim, dim, ks=local_conv_size, stride=1, pad=pad, groups=dim) + + def forward(self, x): + """Applies attention-based transformation or padding to input 'x' before passing it through a local + convolution. + """ + H, W = self.input_resolution + B, L, C = x.shape + assert L == H * W, "input feature has wrong size" + res_x = x + if H == self.window_size and W == self.window_size: + x = self.attn(x) + else: + x = x.view(B, H, W, C) + pad_b = (self.window_size - H % self.window_size) % self.window_size + pad_r = (self.window_size - W % self.window_size) % self.window_size + padding = pad_b > 0 or pad_r > 0 + + if padding: + x = F.pad(x, (0, 0, 0, pad_r, 0, pad_b)) + + pH, pW = H + pad_b, W + pad_r + nH = pH // self.window_size + nW = pW // self.window_size + # Window partition + x = ( + x.view(B, nH, self.window_size, nW, self.window_size, C) + .transpose(2, 3) + .reshape(B * nH * nW, self.window_size * self.window_size, C) + ) + x = self.attn(x) + # Window reverse + x = x.view(B, nH, nW, self.window_size, self.window_size, C).transpose(2, 3).reshape(B, pH, pW, C) + + if padding: + x = x[:, :H, :W].contiguous() + + x = x.view(B, L, C) + + x = res_x + self.drop_path(x) + + x = x.transpose(1, 2).reshape(B, C, H, W) + x = self.local_conv(x) + x = x.view(B, C, L).transpose(1, 2) + + return x + self.drop_path(self.mlp(x)) + + def extra_repr(self) -> str: + """Returns a formatted string representing the TinyViTBlock's parameters: dimension, input resolution, number of + attentions heads, window size, and MLP ratio. + """ + return ( + f"dim={self.dim}, input_resolution={self.input_resolution}, num_heads={self.num_heads}, " + f"window_size={self.window_size}, mlp_ratio={self.mlp_ratio}" + ) + + +class BasicLayer(nn.Module): + """A basic TinyViT layer for one stage in a TinyViT architecture.""" + + def __init__( + self, + dim, + input_resolution, + depth, + num_heads, + window_size, + mlp_ratio=4.0, + drop=0.0, + drop_path=0.0, + downsample=None, + use_checkpoint=False, + local_conv_size=3, + activation=nn.GELU, + out_dim=None, + ): + """ + Initializes the BasicLayer. + + Args: + dim (int): The dimensionality of the input and output. + input_resolution (Tuple[int, int]): Spatial resolution of the input feature map. + depth (int): Number of TinyViT blocks. + num_heads (int): Number of attention heads. + window_size (int): Local window size. + mlp_ratio (float, optional): Ratio of mlp hidden dim to embedding dim. Default is 4. + drop (float, optional): Dropout rate. Default is 0. + drop_path (float | tuple[float], optional): Stochastic depth rate. Default is 0. + downsample (nn.Module | None, optional): Downsample layer at the end of the layer. Default is None. + use_checkpoint (bool, optional): Whether to use checkpointing to save memory. Default is False. + local_conv_size (int, optional): Kernel size of the local convolution. Default is 3. + activation (torch.nn, optional): Activation function for MLP. Default is nn.GELU. + out_dim (int | None, optional): The output dimension of the layer. Default is None. + + Raises: + ValueError: If `drop_path` is a list of float but its length doesn't match `depth`. + """ + super().__init__() + self.dim = dim + self.input_resolution = input_resolution + self.depth = depth + self.use_checkpoint = use_checkpoint + + # Build blocks + self.blocks = nn.ModuleList( + [ + TinyViTBlock( + dim=dim, + input_resolution=input_resolution, + num_heads=num_heads, + window_size=window_size, + mlp_ratio=mlp_ratio, + drop=drop, + drop_path=drop_path[i] if isinstance(drop_path, list) else drop_path, + local_conv_size=local_conv_size, + activation=activation, + ) + for i in range(depth) + ] + ) + + # Patch merging layer + self.downsample = ( + None + if downsample is None + else downsample(input_resolution, dim=dim, out_dim=out_dim, activation=activation) + ) + + def forward(self, x): + """Performs forward propagation on the input tensor and returns a normalized tensor.""" + for blk in self.blocks: + x = checkpoint.checkpoint(blk, x) if self.use_checkpoint else blk(x) + return x if self.downsample is None else self.downsample(x) + + def extra_repr(self) -> str: + """Returns a string representation of the extra_repr function with the layer's parameters.""" + return f"dim={self.dim}, input_resolution={self.input_resolution}, depth={self.depth}" + + +class LayerNorm2d(nn.Module): + """A PyTorch implementation of Layer Normalization in 2D.""" + + def __init__(self, num_channels: int, eps: float = 1e-6) -> None: + """Initialize LayerNorm2d with the number of channels and an optional epsilon.""" + super().__init__() + self.weight = nn.Parameter(torch.ones(num_channels)) + self.bias = nn.Parameter(torch.zeros(num_channels)) + self.eps = eps + + def forward(self, x: torch.Tensor) -> torch.Tensor: + """Perform a forward pass, normalizing the input tensor.""" + u = x.mean(1, keepdim=True) + s = (x - u).pow(2).mean(1, keepdim=True) + x = (x - u) / torch.sqrt(s + self.eps) + return self.weight[:, None, None] * x + self.bias[:, None, None] + + +class TinyViT(nn.Module): + """ + The TinyViT architecture for vision tasks. + + Attributes: + img_size (int): Input image size. + in_chans (int): Number of input channels. + num_classes (int): Number of classification classes. + embed_dims (List[int]): List of embedding dimensions for each layer. + depths (List[int]): List of depths for each layer. + num_heads (List[int]): List of number of attention heads for each layer. + window_sizes (List[int]): List of window sizes for each layer. + mlp_ratio (float): Ratio of MLP hidden dimension to embedding dimension. + drop_rate (float): Dropout rate for drop layers. + drop_path_rate (float): Drop path rate for stochastic depth. + use_checkpoint (bool): Use checkpointing for efficient memory usage. + mbconv_expand_ratio (float): Expansion ratio for MBConv layer. + local_conv_size (int): Local convolution kernel size. + layer_lr_decay (float): Layer-wise learning rate decay. + + Note: + This implementation is generalized to accept a list of depths, attention heads, + embedding dimensions and window sizes, which allows you to create a + "stack" of TinyViT models of varying configurations. + """ + + def __init__( + self, + img_size=224, + in_chans=3, + num_classes=1000, + embed_dims=[96, 192, 384, 768], + depths=[2, 2, 6, 2], + num_heads=[3, 6, 12, 24], + window_sizes=[7, 7, 14, 7], + mlp_ratio=4.0, + drop_rate=0.0, + drop_path_rate=0.1, + use_checkpoint=False, + mbconv_expand_ratio=4.0, + local_conv_size=3, + layer_lr_decay=1.0, + ): + """ + Initializes the TinyViT model. + + Args: + img_size (int, optional): The input image size. Defaults to 224. + in_chans (int, optional): Number of input channels. Defaults to 3. + num_classes (int, optional): Number of classification classes. Defaults to 1000. + embed_dims (List[int], optional): List of embedding dimensions per layer. Defaults to [96, 192, 384, 768]. + depths (List[int], optional): List of depths for each layer. Defaults to [2, 2, 6, 2]. + num_heads (List[int], optional): List of number of attention heads per layer. Defaults to [3, 6, 12, 24]. + window_sizes (List[int], optional): List of window sizes for each layer. Defaults to [7, 7, 14, 7]. + mlp_ratio (float, optional): Ratio of MLP hidden dimension to embedding dimension. Defaults to 4. + drop_rate (float, optional): Dropout rate. Defaults to 0. + drop_path_rate (float, optional): Drop path rate for stochastic depth. Defaults to 0.1. + use_checkpoint (bool, optional): Whether to use checkpointing for efficient memory usage. Defaults to False. + mbconv_expand_ratio (float, optional): Expansion ratio for MBConv layer. Defaults to 4.0. + local_conv_size (int, optional): Local convolution kernel size. Defaults to 3. + layer_lr_decay (float, optional): Layer-wise learning rate decay. Defaults to 1.0. + """ + super().__init__() + self.img_size = img_size + self.num_classes = num_classes + self.depths = depths + self.num_layers = len(depths) + self.mlp_ratio = mlp_ratio + + activation = nn.GELU + + self.patch_embed = PatchEmbed( + in_chans=in_chans, embed_dim=embed_dims[0], resolution=img_size, activation=activation + ) + + patches_resolution = self.patch_embed.patches_resolution + self.patches_resolution = patches_resolution + + # Stochastic depth + dpr = [x.item() for x in torch.linspace(0, drop_path_rate, sum(depths))] # stochastic depth decay rule + + # Build layers + self.layers = nn.ModuleList() + for i_layer in range(self.num_layers): + kwargs = dict( + dim=embed_dims[i_layer], + input_resolution=( + patches_resolution[0] // (2 ** (i_layer - 1 if i_layer == 3 else i_layer)), + patches_resolution[1] // (2 ** (i_layer - 1 if i_layer == 3 else i_layer)), + ), + # input_resolution=(patches_resolution[0] // (2 ** i_layer), + # patches_resolution[1] // (2 ** i_layer)), + depth=depths[i_layer], + drop_path=dpr[sum(depths[:i_layer]) : sum(depths[: i_layer + 1])], + downsample=PatchMerging if (i_layer < self.num_layers - 1) else None, + use_checkpoint=use_checkpoint, + out_dim=embed_dims[min(i_layer + 1, len(embed_dims) - 1)], + activation=activation, + ) + if i_layer == 0: + layer = ConvLayer(conv_expand_ratio=mbconv_expand_ratio, **kwargs) + else: + layer = BasicLayer( + num_heads=num_heads[i_layer], + window_size=window_sizes[i_layer], + mlp_ratio=self.mlp_ratio, + drop=drop_rate, + local_conv_size=local_conv_size, + **kwargs, + ) + self.layers.append(layer) + + # Classifier head + self.norm_head = nn.LayerNorm(embed_dims[-1]) + self.head = nn.Linear(embed_dims[-1], num_classes) if num_classes > 0 else torch.nn.Identity() + + # Init weights + self.apply(self._init_weights) + self.set_layer_lr_decay(layer_lr_decay) + self.neck = nn.Sequential( + nn.Conv2d( + embed_dims[-1], + 256, + kernel_size=1, + bias=False, + ), + LayerNorm2d(256), + nn.Conv2d( + 256, + 256, + kernel_size=3, + padding=1, + bias=False, + ), + LayerNorm2d(256), + ) + + def set_layer_lr_decay(self, layer_lr_decay): + """Sets the learning rate decay for each layer in the TinyViT model.""" + decay_rate = layer_lr_decay + + # Layers -> blocks (depth) + depth = sum(self.depths) + lr_scales = [decay_rate ** (depth - i - 1) for i in range(depth)] + + def _set_lr_scale(m, scale): + """Sets the learning rate scale for each layer in the model based on the layer's depth.""" + for p in m.parameters(): + p.lr_scale = scale + + self.patch_embed.apply(lambda x: _set_lr_scale(x, lr_scales[0])) + i = 0 + for layer in self.layers: + for block in layer.blocks: + block.apply(lambda x: _set_lr_scale(x, lr_scales[i])) + i += 1 + if layer.downsample is not None: + layer.downsample.apply(lambda x: _set_lr_scale(x, lr_scales[i - 1])) + assert i == depth + for m in [self.norm_head, self.head]: + m.apply(lambda x: _set_lr_scale(x, lr_scales[-1])) + + for k, p in self.named_parameters(): + p.param_name = k + + def _check_lr_scale(m): + """Checks if the learning rate scale attribute is present in module's parameters.""" + for p in m.parameters(): + assert hasattr(p, "lr_scale"), p.param_name + + self.apply(_check_lr_scale) + + def _init_weights(self, m): + """Initializes weights for linear layers and layer normalization in the given module.""" + if isinstance(m, nn.Linear): + # NOTE: This initialization is needed only for training. + # trunc_normal_(m.weight, std=.02) + if m.bias is not None: + nn.init.constant_(m.bias, 0) + elif isinstance(m, nn.LayerNorm): + nn.init.constant_(m.bias, 0) + nn.init.constant_(m.weight, 1.0) + + @torch.jit.ignore + def no_weight_decay_keywords(self): + """Returns a dictionary of parameter names where weight decay should not be applied.""" + return {"attention_biases"} + + def forward_features(self, x): + """Runs the input through the model layers and returns the transformed output.""" + x = self.patch_embed(x) # x input is (N, C, H, W) + + x = self.layers[0](x) + start_i = 1 + + for i in range(start_i, len(self.layers)): + layer = self.layers[i] + x = layer(x) + B, _, C = x.shape + x = x.view(B, 64, 64, C) + x = x.permute(0, 3, 1, 2) + return self.neck(x) + + def forward(self, x): + """Executes a forward pass on the input tensor through the constructed model layers.""" + return self.forward_features(x) diff --git a/ultralytics/models/sam/modules/transformer.py b/ultralytics/models/sam/modules/transformer.py new file mode 100644 index 0000000..db684f8 --- /dev/null +++ b/ultralytics/models/sam/modules/transformer.py @@ -0,0 +1,274 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import math +from typing import Tuple, Type + +import torch +from torch import Tensor, nn + +from ultralytics.nn.modules import MLPBlock + + +class TwoWayTransformer(nn.Module): + """ + A Two-Way Transformer module that enables the simultaneous attention to both image and query points. This class + serves as a specialized transformer decoder that attends to an input image using queries whose positional embedding + is supplied. This is particularly useful for tasks like object detection, image segmentation, and point cloud + processing. + + Attributes: + depth (int): The number of layers in the transformer. + embedding_dim (int): The channel dimension for the input embeddings. + num_heads (int): The number of heads for multihead attention. + mlp_dim (int): The internal channel dimension for the MLP block. + layers (nn.ModuleList): The list of TwoWayAttentionBlock layers that make up the transformer. + final_attn_token_to_image (Attention): The final attention layer applied from the queries to the image. + norm_final_attn (nn.LayerNorm): The layer normalization applied to the final queries. + """ + + def __init__( + self, + depth: int, + embedding_dim: int, + num_heads: int, + mlp_dim: int, + activation: Type[nn.Module] = nn.ReLU, + attention_downsample_rate: int = 2, + ) -> None: + """ + A transformer decoder that attends to an input image using queries whose positional embedding is supplied. + + Args: + depth (int): number of layers in the transformer + embedding_dim (int): the channel dimension for the input embeddings + num_heads (int): the number of heads for multihead attention. Must + divide embedding_dim + mlp_dim (int): the channel dimension internal to the MLP block + activation (nn.Module): the activation to use in the MLP block + """ + super().__init__() + self.depth = depth + self.embedding_dim = embedding_dim + self.num_heads = num_heads + self.mlp_dim = mlp_dim + self.layers = nn.ModuleList() + + for i in range(depth): + self.layers.append( + TwoWayAttentionBlock( + embedding_dim=embedding_dim, + num_heads=num_heads, + mlp_dim=mlp_dim, + activation=activation, + attention_downsample_rate=attention_downsample_rate, + skip_first_layer_pe=(i == 0), + ) + ) + + self.final_attn_token_to_image = Attention(embedding_dim, num_heads, downsample_rate=attention_downsample_rate) + self.norm_final_attn = nn.LayerNorm(embedding_dim) + + def forward( + self, + image_embedding: Tensor, + image_pe: Tensor, + point_embedding: Tensor, + ) -> Tuple[Tensor, Tensor]: + """ + Args: + image_embedding (torch.Tensor): image to attend to. Should be shape B x embedding_dim x h x w for any h and w. + image_pe (torch.Tensor): the positional encoding to add to the image. Must have same shape as image_embedding. + point_embedding (torch.Tensor): the embedding to add to the query points. + Must have shape B x N_points x embedding_dim for any N_points. + + Returns: + (torch.Tensor): the processed point_embedding + (torch.Tensor): the processed image_embedding + """ + # BxCxHxW -> BxHWxC == B x N_image_tokens x C + bs, c, h, w = image_embedding.shape + image_embedding = image_embedding.flatten(2).permute(0, 2, 1) + image_pe = image_pe.flatten(2).permute(0, 2, 1) + + # Prepare queries + queries = point_embedding + keys = image_embedding + + # Apply transformer blocks and final layernorm + for layer in self.layers: + queries, keys = layer( + queries=queries, + keys=keys, + query_pe=point_embedding, + key_pe=image_pe, + ) + + # Apply the final attention layer from the points to the image + q = queries + point_embedding + k = keys + image_pe + attn_out = self.final_attn_token_to_image(q=q, k=k, v=keys) + queries = queries + attn_out + queries = self.norm_final_attn(queries) + + return queries, keys + + +class TwoWayAttentionBlock(nn.Module): + """ + An attention block that performs both self-attention and cross-attention in two directions: queries to keys and + keys to queries. This block consists of four main layers: (1) self-attention on sparse inputs, (2) cross-attention + of sparse inputs to dense inputs, (3) an MLP block on sparse inputs, and (4) cross-attention of dense inputs to + sparse inputs. + + Attributes: + self_attn (Attention): The self-attention layer for the queries. + norm1 (nn.LayerNorm): Layer normalization following the first attention block. + cross_attn_token_to_image (Attention): Cross-attention layer from queries to keys. + norm2 (nn.LayerNorm): Layer normalization following the second attention block. + mlp (MLPBlock): MLP block that transforms the query embeddings. + norm3 (nn.LayerNorm): Layer normalization following the MLP block. + norm4 (nn.LayerNorm): Layer normalization following the third attention block. + cross_attn_image_to_token (Attention): Cross-attention layer from keys to queries. + skip_first_layer_pe (bool): Whether to skip the positional encoding in the first layer. + """ + + def __init__( + self, + embedding_dim: int, + num_heads: int, + mlp_dim: int = 2048, + activation: Type[nn.Module] = nn.ReLU, + attention_downsample_rate: int = 2, + skip_first_layer_pe: bool = False, + ) -> None: + """ + A transformer block with four layers: (1) self-attention of sparse inputs, (2) cross attention of sparse + inputs to dense inputs, (3) mlp block on sparse inputs, and (4) cross attention of dense inputs to sparse + inputs. + + Args: + embedding_dim (int): the channel dimension of the embeddings + num_heads (int): the number of heads in the attention layers + mlp_dim (int): the hidden dimension of the mlp block + activation (nn.Module): the activation of the mlp block + skip_first_layer_pe (bool): skip the PE on the first layer + """ + super().__init__() + self.self_attn = Attention(embedding_dim, num_heads) + self.norm1 = nn.LayerNorm(embedding_dim) + + self.cross_attn_token_to_image = Attention(embedding_dim, num_heads, downsample_rate=attention_downsample_rate) + self.norm2 = nn.LayerNorm(embedding_dim) + + self.mlp = MLPBlock(embedding_dim, mlp_dim, activation) + self.norm3 = nn.LayerNorm(embedding_dim) + + self.norm4 = nn.LayerNorm(embedding_dim) + self.cross_attn_image_to_token = Attention(embedding_dim, num_heads, downsample_rate=attention_downsample_rate) + + self.skip_first_layer_pe = skip_first_layer_pe + + def forward(self, queries: Tensor, keys: Tensor, query_pe: Tensor, key_pe: Tensor) -> Tuple[Tensor, Tensor]: + """Apply self-attention and cross-attention to queries and keys and return the processed embeddings.""" + + # Self attention block + if self.skip_first_layer_pe: + queries = self.self_attn(q=queries, k=queries, v=queries) + else: + q = queries + query_pe + attn_out = self.self_attn(q=q, k=q, v=queries) + queries = queries + attn_out + queries = self.norm1(queries) + + # Cross attention block, tokens attending to image embedding + q = queries + query_pe + k = keys + key_pe + attn_out = self.cross_attn_token_to_image(q=q, k=k, v=keys) + queries = queries + attn_out + queries = self.norm2(queries) + + # MLP block + mlp_out = self.mlp(queries) + queries = queries + mlp_out + queries = self.norm3(queries) + + # Cross attention block, image embedding attending to tokens + q = queries + query_pe + k = keys + key_pe + attn_out = self.cross_attn_image_to_token(q=k, k=q, v=queries) + keys = keys + attn_out + keys = self.norm4(keys) + + return queries, keys + + +class Attention(nn.Module): + """An attention layer that allows for downscaling the size of the embedding after projection to queries, keys, and + values. + """ + + def __init__( + self, + embedding_dim: int, + num_heads: int, + downsample_rate: int = 1, + ) -> None: + """ + Initializes the Attention model with the given dimensions and settings. + + Args: + embedding_dim (int): The dimensionality of the input embeddings. + num_heads (int): The number of attention heads. + downsample_rate (int, optional): The factor by which the internal dimensions are downsampled. Defaults to 1. + + Raises: + AssertionError: If 'num_heads' does not evenly divide the internal dim (embedding_dim / downsample_rate). + """ + super().__init__() + self.embedding_dim = embedding_dim + self.internal_dim = embedding_dim // downsample_rate + self.num_heads = num_heads + assert self.internal_dim % num_heads == 0, "num_heads must divide embedding_dim." + + self.q_proj = nn.Linear(embedding_dim, self.internal_dim) + self.k_proj = nn.Linear(embedding_dim, self.internal_dim) + self.v_proj = nn.Linear(embedding_dim, self.internal_dim) + self.out_proj = nn.Linear(self.internal_dim, embedding_dim) + + @staticmethod + def _separate_heads(x: Tensor, num_heads: int) -> Tensor: + """Separate the input tensor into the specified number of attention heads.""" + b, n, c = x.shape + x = x.reshape(b, n, num_heads, c // num_heads) + return x.transpose(1, 2) # B x N_heads x N_tokens x C_per_head + + @staticmethod + def _recombine_heads(x: Tensor) -> Tensor: + """Recombine the separated attention heads into a single tensor.""" + b, n_heads, n_tokens, c_per_head = x.shape + x = x.transpose(1, 2) + return x.reshape(b, n_tokens, n_heads * c_per_head) # B x N_tokens x C + + def forward(self, q: Tensor, k: Tensor, v: Tensor) -> Tensor: + """Compute the attention output given the input query, key, and value tensors.""" + + # Input projections + q = self.q_proj(q) + k = self.k_proj(k) + v = self.v_proj(v) + + # Separate into heads + q = self._separate_heads(q, self.num_heads) + k = self._separate_heads(k, self.num_heads) + v = self._separate_heads(v, self.num_heads) + + # Attention + _, _, _, c_per_head = q.shape + attn = q @ k.permute(0, 1, 3, 2) # B x N_heads x N_tokens x N_tokens + attn = attn / math.sqrt(c_per_head) + attn = torch.softmax(attn, dim=-1) + + # Get output + out = attn @ v + out = self._recombine_heads(out) + return self.out_proj(out) diff --git a/ultralytics/models/sam/predict.py b/ultralytics/models/sam/predict.py new file mode 100644 index 0000000..4980fda --- /dev/null +++ b/ultralytics/models/sam/predict.py @@ -0,0 +1,478 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +""" +Generate predictions using the Segment Anything Model (SAM). + +SAM is an advanced image segmentation model offering features like promptable segmentation and zero-shot performance. +This module contains the implementation of the prediction logic and auxiliary utilities required to perform segmentation +using SAM. It forms an integral part of the Ultralytics framework and is designed for high-performance, real-time image +segmentation tasks. +""" + +import numpy as np +import torch +import torch.nn.functional as F + +from ultralytics.data.augment import LetterBox +from ultralytics.engine.predictor import BasePredictor +from ultralytics.engine.results import Results +from ultralytics.utils import DEFAULT_CFG, ops +from ultralytics.utils.torch_utils import select_device + +from .amg import ( + batch_iterator, + batched_mask_to_box, + build_all_layer_point_grids, + calculate_stability_score, + generate_crop_boxes, + is_box_near_crop_edge, + remove_small_regions, + uncrop_boxes_xyxy, + uncrop_masks, +) +from .build import build_sam + + +class Predictor(BasePredictor): + """ + Predictor class for the Segment Anything Model (SAM), extending BasePredictor. + + The class provides an interface for model inference tailored to image segmentation tasks. + With advanced architecture and promptable segmentation capabilities, it facilitates flexible and real-time + mask generation. The class is capable of working with various types of prompts such as bounding boxes, + points, and low-resolution masks. + + Attributes: + cfg (dict): Configuration dictionary specifying model and task-related parameters. + overrides (dict): Dictionary containing values that override the default configuration. + _callbacks (dict): Dictionary of user-defined callback functions to augment behavior. + args (namespace): Namespace to hold command-line arguments or other operational variables. + im (torch.Tensor): Preprocessed input image tensor. + features (torch.Tensor): Extracted image features used for inference. + prompts (dict): Collection of various prompt types, such as bounding boxes and points. + segment_all (bool): Flag to control whether to segment all objects in the image or only specified ones. + """ + + def __init__(self, cfg=DEFAULT_CFG, overrides=None, _callbacks=None): + """ + Initialize the Predictor with configuration, overrides, and callbacks. + + The method sets up the Predictor object and applies any configuration overrides or callbacks provided. It + initializes task-specific settings for SAM, such as retina_masks being set to True for optimal results. + + Args: + cfg (dict): Configuration dictionary. + overrides (dict, optional): Dictionary of values to override default configuration. + _callbacks (dict, optional): Dictionary of callback functions to customize behavior. + """ + if overrides is None: + overrides = {} + overrides.update(dict(task="segment", mode="predict", imgsz=1024)) + super().__init__(cfg, overrides, _callbacks) + self.args.retina_masks = True + self.im = None + self.features = None + self.prompts = {} + self.segment_all = False + + def preprocess(self, im): + """ + Preprocess the input image for model inference. + + The method prepares the input image by applying transformations and normalization. + It supports both torch.Tensor and list of np.ndarray as input formats. + + Args: + im (torch.Tensor | List[np.ndarray]): BCHW tensor format or list of HWC numpy arrays. + + Returns: + (torch.Tensor): The preprocessed image tensor. + """ + if self.im is not None: + return self.im + not_tensor = not isinstance(im, torch.Tensor) + if not_tensor: + im = np.stack(self.pre_transform(im)) + im = im[..., ::-1].transpose((0, 3, 1, 2)) + im = np.ascontiguousarray(im) + im = torch.from_numpy(im) + + im = im.to(self.device) + im = im.half() if self.model.fp16 else im.float() + if not_tensor: + im = (im - self.mean) / self.std + return im + + def pre_transform(self, im): + """ + Perform initial transformations on the input image for preprocessing. + + The method applies transformations such as resizing to prepare the image for further preprocessing. + Currently, batched inference is not supported; hence the list length should be 1. + + Args: + im (List[np.ndarray]): List containing images in HWC numpy array format. + + Returns: + (List[np.ndarray]): List of transformed images. + """ + assert len(im) == 1, "SAM model does not currently support batched inference" + letterbox = LetterBox(self.args.imgsz, auto=False, center=False) + return [letterbox(image=x) for x in im] + + def inference(self, im, bboxes=None, points=None, labels=None, masks=None, multimask_output=False, *args, **kwargs): + """ + Perform image segmentation inference based on the given input cues, using the currently loaded image. This + method leverages SAM's (Segment Anything Model) architecture consisting of image encoder, prompt encoder, and + mask decoder for real-time and promptable segmentation tasks. + + Args: + im (torch.Tensor): The preprocessed input image in tensor format, with shape (N, C, H, W). + bboxes (np.ndarray | List, optional): Bounding boxes with shape (N, 4), in XYXY format. + points (np.ndarray | List, optional): Points indicating object locations with shape (N, 2), in pixels. + labels (np.ndarray | List, optional): Labels for point prompts, shape (N, ). 1 = foreground, 0 = background. + masks (np.ndarray, optional): Low-resolution masks from previous predictions shape (N,H,W). For SAM H=W=256. + multimask_output (bool, optional): Flag to return multiple masks. Helpful for ambiguous prompts. + + Returns: + (tuple): Contains the following three elements. + - np.ndarray: The output masks in shape CxHxW, where C is the number of generated masks. + - np.ndarray: An array of length C containing quality scores predicted by the model for each mask. + - np.ndarray: Low-resolution logits of shape CxHxW for subsequent inference, where H=W=256. + """ + # Override prompts if any stored in self.prompts + bboxes = self.prompts.pop("bboxes", bboxes) + points = self.prompts.pop("points", points) + masks = self.prompts.pop("masks", masks) + + if all(i is None for i in [bboxes, points, masks]): + return self.generate(im, *args, **kwargs) + + return self.prompt_inference(im, bboxes, points, labels, masks, multimask_output) + + def prompt_inference(self, im, bboxes=None, points=None, labels=None, masks=None, multimask_output=False): + """ + Internal function for image segmentation inference based on cues like bounding boxes, points, and masks. + Leverages SAM's specialized architecture for prompt-based, real-time segmentation. + + Args: + im (torch.Tensor): The preprocessed input image in tensor format, with shape (N, C, H, W). + bboxes (np.ndarray | List, optional): Bounding boxes with shape (N, 4), in XYXY format. + points (np.ndarray | List, optional): Points indicating object locations with shape (N, 2), in pixels. + labels (np.ndarray | List, optional): Labels for point prompts, shape (N, ). 1 = foreground, 0 = background. + masks (np.ndarray, optional): Low-resolution masks from previous predictions shape (N,H,W). For SAM H=W=256. + multimask_output (bool, optional): Flag to return multiple masks. Helpful for ambiguous prompts. + + Returns: + (tuple): Contains the following three elements. + - np.ndarray: The output masks in shape CxHxW, where C is the number of generated masks. + - np.ndarray: An array of length C containing quality scores predicted by the model for each mask. + - np.ndarray: Low-resolution logits of shape CxHxW for subsequent inference, where H=W=256. + """ + features = self.model.image_encoder(im) if self.features is None else self.features + + src_shape, dst_shape = self.batch[1][0].shape[:2], im.shape[2:] + r = 1.0 if self.segment_all else min(dst_shape[0] / src_shape[0], dst_shape[1] / src_shape[1]) + # Transform input prompts + if points is not None: + points = torch.as_tensor(points, dtype=torch.float32, device=self.device) + points = points[None] if points.ndim == 1 else points + # Assuming labels are all positive if users don't pass labels. + if labels is None: + labels = np.ones(points.shape[0]) + labels = torch.as_tensor(labels, dtype=torch.int32, device=self.device) + points *= r + # (N, 2) --> (N, 1, 2), (N, ) --> (N, 1) + points, labels = points[:, None, :], labels[:, None] + if bboxes is not None: + bboxes = torch.as_tensor(bboxes, dtype=torch.float32, device=self.device) + bboxes = bboxes[None] if bboxes.ndim == 1 else bboxes + bboxes *= r + if masks is not None: + masks = torch.as_tensor(masks, dtype=torch.float32, device=self.device).unsqueeze(1) + + points = (points, labels) if points is not None else None + # Embed prompts + sparse_embeddings, dense_embeddings = self.model.prompt_encoder(points=points, boxes=bboxes, masks=masks) + + # Predict masks + pred_masks, pred_scores = self.model.mask_decoder( + image_embeddings=features, + image_pe=self.model.prompt_encoder.get_dense_pe(), + sparse_prompt_embeddings=sparse_embeddings, + dense_prompt_embeddings=dense_embeddings, + multimask_output=multimask_output, + ) + + # (N, d, H, W) --> (N*d, H, W), (N, d) --> (N*d, ) + # `d` could be 1 or 3 depends on `multimask_output`. + return pred_masks.flatten(0, 1), pred_scores.flatten(0, 1) + + def generate( + self, + im, + crop_n_layers=0, + crop_overlap_ratio=512 / 1500, + crop_downscale_factor=1, + point_grids=None, + points_stride=32, + points_batch_size=64, + conf_thres=0.88, + stability_score_thresh=0.95, + stability_score_offset=0.95, + crop_nms_thresh=0.7, + ): + """ + Perform image segmentation using the Segment Anything Model (SAM). + + This function segments an entire image into constituent parts by leveraging SAM's advanced architecture + and real-time performance capabilities. It can optionally work on image crops for finer segmentation. + + Args: + im (torch.Tensor): Input tensor representing the preprocessed image with dimensions (N, C, H, W). + crop_n_layers (int): Specifies the number of layers for additional mask predictions on image crops. + Each layer produces 2**i_layer number of image crops. + crop_overlap_ratio (float): Determines the overlap between crops. Scaled down in subsequent layers. + crop_downscale_factor (int): Scaling factor for the number of sampled points-per-side in each layer. + point_grids (list[np.ndarray], optional): Custom grids for point sampling normalized to [0,1]. + Used in the nth crop layer. + points_stride (int, optional): Number of points to sample along each side of the image. + Exclusive with 'point_grids'. + points_batch_size (int): Batch size for the number of points processed simultaneously. + conf_thres (float): Confidence threshold [0,1] for filtering based on the model's mask quality prediction. + stability_score_thresh (float): Stability threshold [0,1] for mask filtering based on mask stability. + stability_score_offset (float): Offset value for calculating stability score. + crop_nms_thresh (float): IoU cutoff for NMS to remove duplicate masks between crops. + + Returns: + (tuple): A tuple containing segmented masks, confidence scores, and bounding boxes. + """ + import torchvision # scope for faster 'import ultralytics' + + self.segment_all = True + ih, iw = im.shape[2:] + crop_regions, layer_idxs = generate_crop_boxes((ih, iw), crop_n_layers, crop_overlap_ratio) + if point_grids is None: + point_grids = build_all_layer_point_grids(points_stride, crop_n_layers, crop_downscale_factor) + pred_masks, pred_scores, pred_bboxes, region_areas = [], [], [], [] + for crop_region, layer_idx in zip(crop_regions, layer_idxs): + x1, y1, x2, y2 = crop_region + w, h = x2 - x1, y2 - y1 + area = torch.tensor(w * h, device=im.device) + points_scale = np.array([[w, h]]) # w, h + # Crop image and interpolate to input size + crop_im = F.interpolate(im[..., y1:y2, x1:x2], (ih, iw), mode="bilinear", align_corners=False) + # (num_points, 2) + points_for_image = point_grids[layer_idx] * points_scale + crop_masks, crop_scores, crop_bboxes = [], [], [] + for (points,) in batch_iterator(points_batch_size, points_for_image): + pred_mask, pred_score = self.prompt_inference(crop_im, points=points, multimask_output=True) + # Interpolate predicted masks to input size + pred_mask = F.interpolate(pred_mask[None], (h, w), mode="bilinear", align_corners=False)[0] + idx = pred_score > conf_thres + pred_mask, pred_score = pred_mask[idx], pred_score[idx] + + stability_score = calculate_stability_score( + pred_mask, self.model.mask_threshold, stability_score_offset + ) + idx = stability_score > stability_score_thresh + pred_mask, pred_score = pred_mask[idx], pred_score[idx] + # Bool type is much more memory-efficient. + pred_mask = pred_mask > self.model.mask_threshold + # (N, 4) + pred_bbox = batched_mask_to_box(pred_mask).float() + keep_mask = ~is_box_near_crop_edge(pred_bbox, crop_region, [0, 0, iw, ih]) + if not torch.all(keep_mask): + pred_bbox, pred_mask, pred_score = pred_bbox[keep_mask], pred_mask[keep_mask], pred_score[keep_mask] + + crop_masks.append(pred_mask) + crop_bboxes.append(pred_bbox) + crop_scores.append(pred_score) + + # Do nms within this crop + crop_masks = torch.cat(crop_masks) + crop_bboxes = torch.cat(crop_bboxes) + crop_scores = torch.cat(crop_scores) + keep = torchvision.ops.nms(crop_bboxes, crop_scores, self.args.iou) # NMS + crop_bboxes = uncrop_boxes_xyxy(crop_bboxes[keep], crop_region) + crop_masks = uncrop_masks(crop_masks[keep], crop_region, ih, iw) + crop_scores = crop_scores[keep] + + pred_masks.append(crop_masks) + pred_bboxes.append(crop_bboxes) + pred_scores.append(crop_scores) + region_areas.append(area.expand(len(crop_masks))) + + pred_masks = torch.cat(pred_masks) + pred_bboxes = torch.cat(pred_bboxes) + pred_scores = torch.cat(pred_scores) + region_areas = torch.cat(region_areas) + + # Remove duplicate masks between crops + if len(crop_regions) > 1: + scores = 1 / region_areas + keep = torchvision.ops.nms(pred_bboxes, scores, crop_nms_thresh) + pred_masks, pred_bboxes, pred_scores = pred_masks[keep], pred_bboxes[keep], pred_scores[keep] + + return pred_masks, pred_scores, pred_bboxes + + def setup_model(self, model, verbose=True): + """ + Initializes the Segment Anything Model (SAM) for inference. + + This method sets up the SAM model by allocating it to the appropriate device and initializing the necessary + parameters for image normalization and other Ultralytics compatibility settings. + + Args: + model (torch.nn.Module): A pre-trained SAM model. If None, a model will be built based on configuration. + verbose (bool): If True, prints selected device information. + + Attributes: + model (torch.nn.Module): The SAM model allocated to the chosen device for inference. + device (torch.device): The device to which the model and tensors are allocated. + mean (torch.Tensor): The mean values for image normalization. + std (torch.Tensor): The standard deviation values for image normalization. + """ + device = select_device(self.args.device, verbose=verbose) + if model is None: + model = build_sam(self.args.model) + model.eval() + self.model = model.to(device) + self.device = device + self.mean = torch.tensor([123.675, 116.28, 103.53]).view(-1, 1, 1).to(device) + self.std = torch.tensor([58.395, 57.12, 57.375]).view(-1, 1, 1).to(device) + + # Ultralytics compatibility settings + self.model.pt = False + self.model.triton = False + self.model.stride = 32 + self.model.fp16 = False + self.done_warmup = True + + def postprocess(self, preds, img, orig_imgs): + """ + Post-processes SAM's inference outputs to generate object detection masks and bounding boxes. + + The method scales masks and boxes to the original image size and applies a threshold to the mask predictions. + The SAM model uses advanced architecture and promptable segmentation tasks to achieve real-time performance. + + Args: + preds (tuple): The output from SAM model inference, containing masks, scores, and optional bounding boxes. + img (torch.Tensor): The processed input image tensor. + orig_imgs (list | torch.Tensor): The original, unprocessed images. + + Returns: + (list): List of Results objects containing detection masks, bounding boxes, and other metadata. + """ + # (N, 1, H, W), (N, 1) + pred_masks, pred_scores = preds[:2] + pred_bboxes = preds[2] if self.segment_all else None + names = dict(enumerate(str(i) for i in range(len(pred_masks)))) + + if not isinstance(orig_imgs, list): # input images are a torch.Tensor, not a list + orig_imgs = ops.convert_torch2numpy_batch(orig_imgs) + + results = [] + for i, masks in enumerate([pred_masks]): + orig_img = orig_imgs[i] + if pred_bboxes is not None: + pred_bboxes = ops.scale_boxes(img.shape[2:], pred_bboxes.float(), orig_img.shape, padding=False) + cls = torch.arange(len(pred_masks), dtype=torch.int32, device=pred_masks.device) + pred_bboxes = torch.cat([pred_bboxes, pred_scores[:, None], cls[:, None]], dim=-1) + + masks = ops.scale_masks(masks[None].float(), orig_img.shape[:2], padding=False)[0] + masks = masks > self.model.mask_threshold # to bool + img_path = self.batch[0][i] + results.append(Results(orig_img, path=img_path, names=names, masks=masks, boxes=pred_bboxes)) + # Reset segment-all mode. + self.segment_all = False + return results + + def setup_source(self, source): + """ + Sets up the data source for inference. + + This method configures the data source from which images will be fetched for inference. The source could be a + directory, a video file, or other types of image data sources. + + Args: + source (str | Path): The path to the image data source for inference. + """ + if source is not None: + super().setup_source(source) + + def set_image(self, image): + """ + Preprocesses and sets a single image for inference. + + This function sets up the model if not already initialized, configures the data source to the specified image, + and preprocesses the image for feature extraction. Only one image can be set at a time. + + Args: + image (str | np.ndarray): Image file path as a string, or a np.ndarray image read by cv2. + + Raises: + AssertionError: If more than one image is set. + """ + if self.model is None: + model = build_sam(self.args.model) + self.setup_model(model) + self.setup_source(image) + assert len(self.dataset) == 1, "`set_image` only supports setting one image!" + for batch in self.dataset: + im = self.preprocess(batch[1]) + self.features = self.model.image_encoder(im) + self.im = im + break + + def set_prompts(self, prompts): + """Set prompts in advance.""" + self.prompts = prompts + + def reset_image(self): + """Resets the image and its features to None.""" + self.im = None + self.features = None + + @staticmethod + def remove_small_regions(masks, min_area=0, nms_thresh=0.7): + """ + Perform post-processing on segmentation masks generated by the Segment Anything Model (SAM). Specifically, this + function removes small disconnected regions and holes from the input masks, and then performs Non-Maximum + Suppression (NMS) to eliminate any newly created duplicate boxes. + + Args: + masks (torch.Tensor): A tensor containing the masks to be processed. Shape should be (N, H, W), where N is + the number of masks, H is height, and W is width. + min_area (int): The minimum area below which disconnected regions and holes will be removed. Defaults to 0. + nms_thresh (float): The IoU threshold for the NMS algorithm. Defaults to 0.7. + + Returns: + (tuple([torch.Tensor, List[int]])): + - new_masks (torch.Tensor): The processed masks with small regions removed. Shape is (N, H, W). + - keep (List[int]): The indices of the remaining masks post-NMS, which can be used to filter the boxes. + """ + import torchvision # scope for faster 'import ultralytics' + + if len(masks) == 0: + return masks + + # Filter small disconnected regions and holes + new_masks = [] + scores = [] + for mask in masks: + mask = mask.cpu().numpy().astype(np.uint8) + mask, changed = remove_small_regions(mask, min_area, mode="holes") + unchanged = not changed + mask, changed = remove_small_regions(mask, min_area, mode="islands") + unchanged = unchanged and not changed + + new_masks.append(torch.as_tensor(mask).unsqueeze(0)) + # Give score=0 to changed masks and 1 to unchanged masks so NMS prefers masks not needing postprocessing + scores.append(float(unchanged)) + + # Recalculate boxes and remove any new duplicates + new_masks = torch.cat(new_masks, dim=0) + boxes = batched_mask_to_box(new_masks) + keep = torchvision.ops.nms(boxes.float(), torch.as_tensor(scores), nms_thresh) + + return new_masks[keep].to(device=masks.device, dtype=masks.dtype), keep diff --git a/ultralytics/models/utils/__init__.py b/ultralytics/models/utils/__init__.py new file mode 100644 index 0000000..9e68dc1 --- /dev/null +++ b/ultralytics/models/utils/__init__.py @@ -0,0 +1 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license diff --git a/ultralytics/models/utils/loss.py b/ultralytics/models/utils/loss.py new file mode 100644 index 0000000..41870fd --- /dev/null +++ b/ultralytics/models/utils/loss.py @@ -0,0 +1,346 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import torch +import torch.nn as nn +import torch.nn.functional as F + +from ultralytics.utils.loss import FocalLoss, VarifocalLoss +from ultralytics.utils.metrics import bbox_iou + +from .ops import HungarianMatcher + + +class DETRLoss(nn.Module): + """ + DETR (DEtection TRansformer) Loss class. This class calculates and returns the different loss components for the + DETR object detection model. It computes classification loss, bounding box loss, GIoU loss, and optionally auxiliary + losses. + + Attributes: + nc (int): The number of classes. + loss_gain (dict): Coefficients for different loss components. + aux_loss (bool): Whether to compute auxiliary losses. + use_fl (bool): Use FocalLoss or not. + use_vfl (bool): Use VarifocalLoss or not. + use_uni_match (bool): Whether to use a fixed layer to assign labels for the auxiliary branch. + uni_match_ind (int): The fixed indices of a layer to use if `use_uni_match` is True. + matcher (HungarianMatcher): Object to compute matching cost and indices. + fl (FocalLoss or None): Focal Loss object if `use_fl` is True, otherwise None. + vfl (VarifocalLoss or None): Varifocal Loss object if `use_vfl` is True, otherwise None. + device (torch.device): Device on which tensors are stored. + """ + + def __init__( + self, nc=80, loss_gain=None, aux_loss=True, use_fl=True, use_vfl=False, use_uni_match=False, uni_match_ind=0 + ): + """ + DETR loss function. + + Args: + nc (int): The number of classes. + loss_gain (dict): The coefficient of loss. + aux_loss (bool): If 'aux_loss = True', loss at each decoder layer are to be used. + use_vfl (bool): Use VarifocalLoss or not. + use_uni_match (bool): Whether to use a fixed layer to assign labels for auxiliary branch. + uni_match_ind (int): The fixed indices of a layer. + """ + super().__init__() + + if loss_gain is None: + loss_gain = {"class": 1, "bbox": 5, "giou": 2, "no_object": 0.1, "mask": 1, "dice": 1} + self.nc = nc + self.matcher = HungarianMatcher(cost_gain={"class": 2, "bbox": 5, "giou": 2}) + self.loss_gain = loss_gain + self.aux_loss = aux_loss + self.fl = FocalLoss() if use_fl else None + self.vfl = VarifocalLoss() if use_vfl else None + + self.use_uni_match = use_uni_match + self.uni_match_ind = uni_match_ind + self.device = None + + def _get_loss_class(self, pred_scores, targets, gt_scores, num_gts, postfix=""): + """Computes the classification loss based on predictions, target values, and ground truth scores.""" + # Logits: [b, query, num_classes], gt_class: list[[n, 1]] + name_class = f"loss_class{postfix}" + bs, nq = pred_scores.shape[:2] + # one_hot = F.one_hot(targets, self.nc + 1)[..., :-1] # (bs, num_queries, num_classes) + one_hot = torch.zeros((bs, nq, self.nc + 1), dtype=torch.int64, device=targets.device) + one_hot.scatter_(2, targets.unsqueeze(-1), 1) + one_hot = one_hot[..., :-1] + gt_scores = gt_scores.view(bs, nq, 1) * one_hot + + if self.fl: + if num_gts and self.vfl: + loss_cls = self.vfl(pred_scores, gt_scores, one_hot) + else: + loss_cls = self.fl(pred_scores, one_hot.float()) + loss_cls /= max(num_gts, 1) / nq + else: + loss_cls = nn.BCEWithLogitsLoss(reduction="none")(pred_scores, gt_scores).mean(1).sum() # YOLO CLS loss + + return {name_class: loss_cls.squeeze() * self.loss_gain["class"]} + + def _get_loss_bbox(self, pred_bboxes, gt_bboxes, postfix=""): + """Calculates and returns the bounding box loss and GIoU loss for the predicted and ground truth bounding + boxes. + """ + # Boxes: [b, query, 4], gt_bbox: list[[n, 4]] + name_bbox = f"loss_bbox{postfix}" + name_giou = f"loss_giou{postfix}" + + loss = {} + if len(gt_bboxes) == 0: + loss[name_bbox] = torch.tensor(0.0, device=self.device) + loss[name_giou] = torch.tensor(0.0, device=self.device) + return loss + + loss[name_bbox] = self.loss_gain["bbox"] * F.l1_loss(pred_bboxes, gt_bboxes, reduction="sum") / len(gt_bboxes) + loss[name_giou] = 1.0 - bbox_iou(pred_bboxes, gt_bboxes, xywh=True, GIoU=True) + loss[name_giou] = loss[name_giou].sum() / len(gt_bboxes) + loss[name_giou] = self.loss_gain["giou"] * loss[name_giou] + return {k: v.squeeze() for k, v in loss.items()} + + # This function is for future RT-DETR Segment models + # def _get_loss_mask(self, masks, gt_mask, match_indices, postfix=''): + # # masks: [b, query, h, w], gt_mask: list[[n, H, W]] + # name_mask = f'loss_mask{postfix}' + # name_dice = f'loss_dice{postfix}' + # + # loss = {} + # if sum(len(a) for a in gt_mask) == 0: + # loss[name_mask] = torch.tensor(0., device=self.device) + # loss[name_dice] = torch.tensor(0., device=self.device) + # return loss + # + # num_gts = len(gt_mask) + # src_masks, target_masks = self._get_assigned_bboxes(masks, gt_mask, match_indices) + # src_masks = F.interpolate(src_masks.unsqueeze(0), size=target_masks.shape[-2:], mode='bilinear')[0] + # # TODO: torch does not have `sigmoid_focal_loss`, but it's not urgent since we don't use mask branch for now. + # loss[name_mask] = self.loss_gain['mask'] * F.sigmoid_focal_loss(src_masks, target_masks, + # torch.tensor([num_gts], dtype=torch.float32)) + # loss[name_dice] = self.loss_gain['dice'] * self._dice_loss(src_masks, target_masks, num_gts) + # return loss + + # This function is for future RT-DETR Segment models + # @staticmethod + # def _dice_loss(inputs, targets, num_gts): + # inputs = F.sigmoid(inputs).flatten(1) + # targets = targets.flatten(1) + # numerator = 2 * (inputs * targets).sum(1) + # denominator = inputs.sum(-1) + targets.sum(-1) + # loss = 1 - (numerator + 1) / (denominator + 1) + # return loss.sum() / num_gts + + def _get_loss_aux( + self, + pred_bboxes, + pred_scores, + gt_bboxes, + gt_cls, + gt_groups, + match_indices=None, + postfix="", + masks=None, + gt_mask=None, + ): + """Get auxiliary losses.""" + # NOTE: loss class, bbox, giou, mask, dice + loss = torch.zeros(5 if masks is not None else 3, device=pred_bboxes.device) + if match_indices is None and self.use_uni_match: + match_indices = self.matcher( + pred_bboxes[self.uni_match_ind], + pred_scores[self.uni_match_ind], + gt_bboxes, + gt_cls, + gt_groups, + masks=masks[self.uni_match_ind] if masks is not None else None, + gt_mask=gt_mask, + ) + for i, (aux_bboxes, aux_scores) in enumerate(zip(pred_bboxes, pred_scores)): + aux_masks = masks[i] if masks is not None else None + loss_ = self._get_loss( + aux_bboxes, + aux_scores, + gt_bboxes, + gt_cls, + gt_groups, + masks=aux_masks, + gt_mask=gt_mask, + postfix=postfix, + match_indices=match_indices, + ) + loss[0] += loss_[f"loss_class{postfix}"] + loss[1] += loss_[f"loss_bbox{postfix}"] + loss[2] += loss_[f"loss_giou{postfix}"] + # if masks is not None and gt_mask is not None: + # loss_ = self._get_loss_mask(aux_masks, gt_mask, match_indices, postfix) + # loss[3] += loss_[f'loss_mask{postfix}'] + # loss[4] += loss_[f'loss_dice{postfix}'] + + loss = { + f"loss_class_aux{postfix}": loss[0], + f"loss_bbox_aux{postfix}": loss[1], + f"loss_giou_aux{postfix}": loss[2], + } + # if masks is not None and gt_mask is not None: + # loss[f'loss_mask_aux{postfix}'] = loss[3] + # loss[f'loss_dice_aux{postfix}'] = loss[4] + return loss + + @staticmethod + def _get_index(match_indices): + """Returns batch indices, source indices, and destination indices from provided match indices.""" + batch_idx = torch.cat([torch.full_like(src, i) for i, (src, _) in enumerate(match_indices)]) + src_idx = torch.cat([src for (src, _) in match_indices]) + dst_idx = torch.cat([dst for (_, dst) in match_indices]) + return (batch_idx, src_idx), dst_idx + + def _get_assigned_bboxes(self, pred_bboxes, gt_bboxes, match_indices): + """Assigns predicted bounding boxes to ground truth bounding boxes based on the match indices.""" + pred_assigned = torch.cat( + [ + t[i] if len(i) > 0 else torch.zeros(0, t.shape[-1], device=self.device) + for t, (i, _) in zip(pred_bboxes, match_indices) + ] + ) + gt_assigned = torch.cat( + [ + t[j] if len(j) > 0 else torch.zeros(0, t.shape[-1], device=self.device) + for t, (_, j) in zip(gt_bboxes, match_indices) + ] + ) + return pred_assigned, gt_assigned + + def _get_loss( + self, + pred_bboxes, + pred_scores, + gt_bboxes, + gt_cls, + gt_groups, + masks=None, + gt_mask=None, + postfix="", + match_indices=None, + ): + """Get losses.""" + if match_indices is None: + match_indices = self.matcher( + pred_bboxes, pred_scores, gt_bboxes, gt_cls, gt_groups, masks=masks, gt_mask=gt_mask + ) + + idx, gt_idx = self._get_index(match_indices) + pred_bboxes, gt_bboxes = pred_bboxes[idx], gt_bboxes[gt_idx] + + bs, nq = pred_scores.shape[:2] + targets = torch.full((bs, nq), self.nc, device=pred_scores.device, dtype=gt_cls.dtype) + targets[idx] = gt_cls[gt_idx] + + gt_scores = torch.zeros([bs, nq], device=pred_scores.device) + if len(gt_bboxes): + gt_scores[idx] = bbox_iou(pred_bboxes.detach(), gt_bboxes, xywh=True).squeeze(-1) + + loss = {} + loss.update(self._get_loss_class(pred_scores, targets, gt_scores, len(gt_bboxes), postfix)) + loss.update(self._get_loss_bbox(pred_bboxes, gt_bboxes, postfix)) + # if masks is not None and gt_mask is not None: + # loss.update(self._get_loss_mask(masks, gt_mask, match_indices, postfix)) + return loss + + def forward(self, pred_bboxes, pred_scores, batch, postfix="", **kwargs): + """ + Args: + pred_bboxes (torch.Tensor): [l, b, query, 4] + pred_scores (torch.Tensor): [l, b, query, num_classes] + batch (dict): A dict includes: + gt_cls (torch.Tensor) with shape [num_gts, ], + gt_bboxes (torch.Tensor): [num_gts, 4], + gt_groups (List(int)): a list of batch size length includes the number of gts of each image. + postfix (str): postfix of loss name. + """ + self.device = pred_bboxes.device + match_indices = kwargs.get("match_indices", None) + gt_cls, gt_bboxes, gt_groups = batch["cls"], batch["bboxes"], batch["gt_groups"] + + total_loss = self._get_loss( + pred_bboxes[-1], pred_scores[-1], gt_bboxes, gt_cls, gt_groups, postfix=postfix, match_indices=match_indices + ) + + if self.aux_loss: + total_loss.update( + self._get_loss_aux( + pred_bboxes[:-1], pred_scores[:-1], gt_bboxes, gt_cls, gt_groups, match_indices, postfix + ) + ) + + return total_loss + + +class RTDETRDetectionLoss(DETRLoss): + """ + Real-Time DeepTracker (RT-DETR) Detection Loss class that extends the DETRLoss. + + This class computes the detection loss for the RT-DETR model, which includes the standard detection loss as well as + an additional denoising training loss when provided with denoising metadata. + """ + + def forward(self, preds, batch, dn_bboxes=None, dn_scores=None, dn_meta=None): + """ + Forward pass to compute the detection loss. + + Args: + preds (tuple): Predicted bounding boxes and scores. + batch (dict): Batch data containing ground truth information. + dn_bboxes (torch.Tensor, optional): Denoising bounding boxes. Default is None. + dn_scores (torch.Tensor, optional): Denoising scores. Default is None. + dn_meta (dict, optional): Metadata for denoising. Default is None. + + Returns: + (dict): Dictionary containing the total loss and, if applicable, the denoising loss. + """ + pred_bboxes, pred_scores = preds + total_loss = super().forward(pred_bboxes, pred_scores, batch) + + # Check for denoising metadata to compute denoising training loss + if dn_meta is not None: + dn_pos_idx, dn_num_group = dn_meta["dn_pos_idx"], dn_meta["dn_num_group"] + assert len(batch["gt_groups"]) == len(dn_pos_idx) + + # Get the match indices for denoising + match_indices = self.get_dn_match_indices(dn_pos_idx, dn_num_group, batch["gt_groups"]) + + # Compute the denoising training loss + dn_loss = super().forward(dn_bboxes, dn_scores, batch, postfix="_dn", match_indices=match_indices) + total_loss.update(dn_loss) + else: + # If no denoising metadata is provided, set denoising loss to zero + total_loss.update({f"{k}_dn": torch.tensor(0.0, device=self.device) for k in total_loss.keys()}) + + return total_loss + + @staticmethod + def get_dn_match_indices(dn_pos_idx, dn_num_group, gt_groups): + """ + Get the match indices for denoising. + + Args: + dn_pos_idx (List[torch.Tensor]): List of tensors containing positive indices for denoising. + dn_num_group (int): Number of denoising groups. + gt_groups (List[int]): List of integers representing the number of ground truths for each image. + + Returns: + (List[tuple]): List of tuples containing matched indices for denoising. + """ + dn_match_indices = [] + idx_groups = torch.as_tensor([0, *gt_groups[:-1]]).cumsum_(0) + for i, num_gt in enumerate(gt_groups): + if num_gt > 0: + gt_idx = torch.arange(end=num_gt, dtype=torch.long) + idx_groups[i] + gt_idx = gt_idx.repeat(dn_num_group) + assert len(dn_pos_idx[i]) == len(gt_idx), "Expected the same length, " + f"but got {len(dn_pos_idx[i])} and {len(gt_idx)} respectively." + dn_match_indices.append((dn_pos_idx[i], gt_idx)) + else: + dn_match_indices.append((torch.zeros([0], dtype=torch.long), torch.zeros([0], dtype=torch.long))) + return dn_match_indices diff --git a/ultralytics/models/utils/ops.py b/ultralytics/models/utils/ops.py new file mode 100644 index 0000000..4f66fee --- /dev/null +++ b/ultralytics/models/utils/ops.py @@ -0,0 +1,263 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import torch +import torch.nn as nn +import torch.nn.functional as F +from scipy.optimize import linear_sum_assignment + +from ultralytics.utils.metrics import bbox_iou +from ultralytics.utils.ops import xywh2xyxy, xyxy2xywh + + +class HungarianMatcher(nn.Module): + """ + A module implementing the HungarianMatcher, which is a differentiable module to solve the assignment problem in an + end-to-end fashion. + + HungarianMatcher performs optimal assignment over the predicted and ground truth bounding boxes using a cost + function that considers classification scores, bounding box coordinates, and optionally, mask predictions. + + Attributes: + cost_gain (dict): Dictionary of cost coefficients: 'class', 'bbox', 'giou', 'mask', and 'dice'. + use_fl (bool): Indicates whether to use Focal Loss for the classification cost calculation. + with_mask (bool): Indicates whether the model makes mask predictions. + num_sample_points (int): The number of sample points used in mask cost calculation. + alpha (float): The alpha factor in Focal Loss calculation. + gamma (float): The gamma factor in Focal Loss calculation. + + Methods: + forward(pred_bboxes, pred_scores, gt_bboxes, gt_cls, gt_groups, masks=None, gt_mask=None): Computes the + assignment between predictions and ground truths for a batch. + _cost_mask(bs, num_gts, masks=None, gt_mask=None): Computes the mask cost and dice cost if masks are predicted. + """ + + def __init__(self, cost_gain=None, use_fl=True, with_mask=False, num_sample_points=12544, alpha=0.25, gamma=2.0): + """Initializes HungarianMatcher with cost coefficients, Focal Loss, mask prediction, sample points, and alpha + gamma factors. + """ + super().__init__() + if cost_gain is None: + cost_gain = {"class": 1, "bbox": 5, "giou": 2, "mask": 1, "dice": 1} + self.cost_gain = cost_gain + self.use_fl = use_fl + self.with_mask = with_mask + self.num_sample_points = num_sample_points + self.alpha = alpha + self.gamma = gamma + + def forward(self, pred_bboxes, pred_scores, gt_bboxes, gt_cls, gt_groups, masks=None, gt_mask=None): + """ + Forward pass for HungarianMatcher. This function computes costs based on prediction and ground truth + (classification cost, L1 cost between boxes and GIoU cost between boxes) and finds the optimal matching between + predictions and ground truth based on these costs. + + Args: + pred_bboxes (Tensor): Predicted bounding boxes with shape [batch_size, num_queries, 4]. + pred_scores (Tensor): Predicted scores with shape [batch_size, num_queries, num_classes]. + gt_cls (torch.Tensor): Ground truth classes with shape [num_gts, ]. + gt_bboxes (torch.Tensor): Ground truth bounding boxes with shape [num_gts, 4]. + gt_groups (List[int]): List of length equal to batch size, containing the number of ground truths for + each image. + masks (Tensor, optional): Predicted masks with shape [batch_size, num_queries, height, width]. + Defaults to None. + gt_mask (List[Tensor], optional): List of ground truth masks, each with shape [num_masks, Height, Width]. + Defaults to None. + + Returns: + (List[Tuple[Tensor, Tensor]]): A list of size batch_size, each element is a tuple (index_i, index_j), where: + - index_i is the tensor of indices of the selected predictions (in order) + - index_j is the tensor of indices of the corresponding selected ground truth targets (in order) + For each batch element, it holds: + len(index_i) = len(index_j) = min(num_queries, num_target_boxes) + """ + + bs, nq, nc = pred_scores.shape + + if sum(gt_groups) == 0: + return [(torch.tensor([], dtype=torch.long), torch.tensor([], dtype=torch.long)) for _ in range(bs)] + + # We flatten to compute the cost matrices in a batch + # [batch_size * num_queries, num_classes] + pred_scores = pred_scores.detach().view(-1, nc) + pred_scores = F.sigmoid(pred_scores) if self.use_fl else F.softmax(pred_scores, dim=-1) + # [batch_size * num_queries, 4] + pred_bboxes = pred_bboxes.detach().view(-1, 4) + + # Compute the classification cost + pred_scores = pred_scores[:, gt_cls] + if self.use_fl: + neg_cost_class = (1 - self.alpha) * (pred_scores**self.gamma) * (-(1 - pred_scores + 1e-8).log()) + pos_cost_class = self.alpha * ((1 - pred_scores) ** self.gamma) * (-(pred_scores + 1e-8).log()) + cost_class = pos_cost_class - neg_cost_class + else: + cost_class = -pred_scores + + # Compute the L1 cost between boxes + cost_bbox = (pred_bboxes.unsqueeze(1) - gt_bboxes.unsqueeze(0)).abs().sum(-1) # (bs*num_queries, num_gt) + + # Compute the GIoU cost between boxes, (bs*num_queries, num_gt) + cost_giou = 1.0 - bbox_iou(pred_bboxes.unsqueeze(1), gt_bboxes.unsqueeze(0), xywh=True, GIoU=True).squeeze(-1) + + # Final cost matrix + C = ( + self.cost_gain["class"] * cost_class + + self.cost_gain["bbox"] * cost_bbox + + self.cost_gain["giou"] * cost_giou + ) + # Compute the mask cost and dice cost + if self.with_mask: + C += self._cost_mask(bs, gt_groups, masks, gt_mask) + + # Set invalid values (NaNs and infinities) to 0 (fixes ValueError: matrix contains invalid numeric entries) + C[C.isnan() | C.isinf()] = 0.0 + + C = C.view(bs, nq, -1).cpu() + indices = [linear_sum_assignment(c[i]) for i, c in enumerate(C.split(gt_groups, -1))] + gt_groups = torch.as_tensor([0, *gt_groups[:-1]]).cumsum_(0) # (idx for queries, idx for gt) + return [ + (torch.tensor(i, dtype=torch.long), torch.tensor(j, dtype=torch.long) + gt_groups[k]) + for k, (i, j) in enumerate(indices) + ] + + # This function is for future RT-DETR Segment models + # def _cost_mask(self, bs, num_gts, masks=None, gt_mask=None): + # assert masks is not None and gt_mask is not None, 'Make sure the input has `mask` and `gt_mask`' + # # all masks share the same set of points for efficient matching + # sample_points = torch.rand([bs, 1, self.num_sample_points, 2]) + # sample_points = 2.0 * sample_points - 1.0 + # + # out_mask = F.grid_sample(masks.detach(), sample_points, align_corners=False).squeeze(-2) + # out_mask = out_mask.flatten(0, 1) + # + # tgt_mask = torch.cat(gt_mask).unsqueeze(1) + # sample_points = torch.cat([a.repeat(b, 1, 1, 1) for a, b in zip(sample_points, num_gts) if b > 0]) + # tgt_mask = F.grid_sample(tgt_mask, sample_points, align_corners=False).squeeze([1, 2]) + # + # with torch.cuda.amp.autocast(False): + # # binary cross entropy cost + # pos_cost_mask = F.binary_cross_entropy_with_logits(out_mask, torch.ones_like(out_mask), reduction='none') + # neg_cost_mask = F.binary_cross_entropy_with_logits(out_mask, torch.zeros_like(out_mask), reduction='none') + # cost_mask = torch.matmul(pos_cost_mask, tgt_mask.T) + torch.matmul(neg_cost_mask, 1 - tgt_mask.T) + # cost_mask /= self.num_sample_points + # + # # dice cost + # out_mask = F.sigmoid(out_mask) + # numerator = 2 * torch.matmul(out_mask, tgt_mask.T) + # denominator = out_mask.sum(-1, keepdim=True) + tgt_mask.sum(-1).unsqueeze(0) + # cost_dice = 1 - (numerator + 1) / (denominator + 1) + # + # C = self.cost_gain['mask'] * cost_mask + self.cost_gain['dice'] * cost_dice + # return C + + +def get_cdn_group( + batch, num_classes, num_queries, class_embed, num_dn=100, cls_noise_ratio=0.5, box_noise_scale=1.0, training=False +): + """ + Get contrastive denoising training group. This function creates a contrastive denoising training group with positive + and negative samples from the ground truths (gt). It applies noise to the class labels and bounding box coordinates, + and returns the modified labels, bounding boxes, attention mask and meta information. + + Args: + batch (dict): A dict that includes 'gt_cls' (torch.Tensor with shape [num_gts, ]), 'gt_bboxes' + (torch.Tensor with shape [num_gts, 4]), 'gt_groups' (List(int)) which is a list of batch size length + indicating the number of gts of each image. + num_classes (int): Number of classes. + num_queries (int): Number of queries. + class_embed (torch.Tensor): Embedding weights to map class labels to embedding space. + num_dn (int, optional): Number of denoising. Defaults to 100. + cls_noise_ratio (float, optional): Noise ratio for class labels. Defaults to 0.5. + box_noise_scale (float, optional): Noise scale for bounding box coordinates. Defaults to 1.0. + training (bool, optional): If it's in training mode. Defaults to False. + + Returns: + (Tuple[Optional[Tensor], Optional[Tensor], Optional[Tensor], Optional[Dict]]): The modified class embeddings, + bounding boxes, attention mask and meta information for denoising. If not in training mode or 'num_dn' + is less than or equal to 0, the function returns None for all elements in the tuple. + """ + + if (not training) or num_dn <= 0: + return None, None, None, None + gt_groups = batch["gt_groups"] + total_num = sum(gt_groups) + max_nums = max(gt_groups) + if max_nums == 0: + return None, None, None, None + + num_group = num_dn // max_nums + num_group = 1 if num_group == 0 else num_group + # Pad gt to max_num of a batch + bs = len(gt_groups) + gt_cls = batch["cls"] # (bs*num, ) + gt_bbox = batch["bboxes"] # bs*num, 4 + b_idx = batch["batch_idx"] + + # Each group has positive and negative queries. + dn_cls = gt_cls.repeat(2 * num_group) # (2*num_group*bs*num, ) + dn_bbox = gt_bbox.repeat(2 * num_group, 1) # 2*num_group*bs*num, 4 + dn_b_idx = b_idx.repeat(2 * num_group).view(-1) # (2*num_group*bs*num, ) + + # Positive and negative mask + # (bs*num*num_group, ), the second total_num*num_group part as negative samples + neg_idx = torch.arange(total_num * num_group, dtype=torch.long, device=gt_bbox.device) + num_group * total_num + + if cls_noise_ratio > 0: + # Half of bbox prob + mask = torch.rand(dn_cls.shape) < (cls_noise_ratio * 0.5) + idx = torch.nonzero(mask).squeeze(-1) + # Randomly put a new one here + new_label = torch.randint_like(idx, 0, num_classes, dtype=dn_cls.dtype, device=dn_cls.device) + dn_cls[idx] = new_label + + if box_noise_scale > 0: + known_bbox = xywh2xyxy(dn_bbox) + + diff = (dn_bbox[..., 2:] * 0.5).repeat(1, 2) * box_noise_scale # 2*num_group*bs*num, 4 + + rand_sign = torch.randint_like(dn_bbox, 0, 2) * 2.0 - 1.0 + rand_part = torch.rand_like(dn_bbox) + rand_part[neg_idx] += 1.0 + rand_part *= rand_sign + known_bbox += rand_part * diff + known_bbox.clip_(min=0.0, max=1.0) + dn_bbox = xyxy2xywh(known_bbox) + dn_bbox = torch.logit(dn_bbox, eps=1e-6) # inverse sigmoid + + num_dn = int(max_nums * 2 * num_group) # total denoising queries + # class_embed = torch.cat([class_embed, torch.zeros([1, class_embed.shape[-1]], device=class_embed.device)]) + dn_cls_embed = class_embed[dn_cls] # bs*num * 2 * num_group, 256 + padding_cls = torch.zeros(bs, num_dn, dn_cls_embed.shape[-1], device=gt_cls.device) + padding_bbox = torch.zeros(bs, num_dn, 4, device=gt_bbox.device) + + map_indices = torch.cat([torch.tensor(range(num), dtype=torch.long) for num in gt_groups]) + pos_idx = torch.stack([map_indices + max_nums * i for i in range(num_group)], dim=0) + + map_indices = torch.cat([map_indices + max_nums * i for i in range(2 * num_group)]) + padding_cls[(dn_b_idx, map_indices)] = dn_cls_embed + padding_bbox[(dn_b_idx, map_indices)] = dn_bbox + + tgt_size = num_dn + num_queries + attn_mask = torch.zeros([tgt_size, tgt_size], dtype=torch.bool) + # Match query cannot see the reconstruct + attn_mask[num_dn:, :num_dn] = True + # Reconstruct cannot see each other + for i in range(num_group): + if i == 0: + attn_mask[max_nums * 2 * i : max_nums * 2 * (i + 1), max_nums * 2 * (i + 1) : num_dn] = True + if i == num_group - 1: + attn_mask[max_nums * 2 * i : max_nums * 2 * (i + 1), : max_nums * i * 2] = True + else: + attn_mask[max_nums * 2 * i : max_nums * 2 * (i + 1), max_nums * 2 * (i + 1) : num_dn] = True + attn_mask[max_nums * 2 * i : max_nums * 2 * (i + 1), : max_nums * 2 * i] = True + dn_meta = { + "dn_pos_idx": [p.reshape(-1) for p in pos_idx.cpu().split(list(gt_groups), dim=1)], + "dn_num_group": num_group, + "dn_num_split": [num_dn, num_queries], + } + + return ( + padding_cls.to(class_embed.device), + padding_bbox.to(class_embed.device), + attn_mask.to(class_embed.device), + dn_meta, + ) diff --git a/ultralytics/models/yolo/__init__.py b/ultralytics/models/yolo/__init__.py new file mode 100644 index 0000000..8d9aedf --- /dev/null +++ b/ultralytics/models/yolo/__init__.py @@ -0,0 +1,7 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from ultralytics.models.yolo import classify, detect, obb, pose, segment, world + +from .model import YOLO, YOLOWorld + +__all__ = "classify", "segment", "detect", "pose", "obb", "world", "YOLO", "YOLOWorld" diff --git a/ultralytics/models/yolo/classify/__init__.py b/ultralytics/models/yolo/classify/__init__.py new file mode 100644 index 0000000..ca92f89 --- /dev/null +++ b/ultralytics/models/yolo/classify/__init__.py @@ -0,0 +1,7 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from ultralytics.models.yolo.classify.predict import ClassificationPredictor +from ultralytics.models.yolo.classify.train import ClassificationTrainer +from ultralytics.models.yolo.classify.val import ClassificationValidator + +__all__ = "ClassificationPredictor", "ClassificationTrainer", "ClassificationValidator" diff --git a/ultralytics/models/yolo/classify/predict.py b/ultralytics/models/yolo/classify/predict.py new file mode 100644 index 0000000..853ef04 --- /dev/null +++ b/ultralytics/models/yolo/classify/predict.py @@ -0,0 +1,61 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import cv2 +import torch +from PIL import Image + +from ultralytics.engine.predictor import BasePredictor +from ultralytics.engine.results import Results +from ultralytics.utils import DEFAULT_CFG, ops + + +class ClassificationPredictor(BasePredictor): + """ + A class extending the BasePredictor class for prediction based on a classification model. + + Notes: + - Torchvision classification models can also be passed to the 'model' argument, i.e. model='resnet18'. + + Example: + ```python + from ultralytics.utils import ASSETS + from ultralytics.models.yolo.classify import ClassificationPredictor + + args = dict(model='yolov8n-cls.pt', source=ASSETS) + predictor = ClassificationPredictor(overrides=args) + predictor.predict_cli() + ``` + """ + + def __init__(self, cfg=DEFAULT_CFG, overrides=None, _callbacks=None): + """Initializes ClassificationPredictor setting the task to 'classify'.""" + super().__init__(cfg, overrides, _callbacks) + self.args.task = "classify" + self._legacy_transform_name = "ultralytics.yolo.data.augment.ToTensor" + + def preprocess(self, img): + """Converts input image to model-compatible data type.""" + if not isinstance(img, torch.Tensor): + is_legacy_transform = any( + self._legacy_transform_name in str(transform) for transform in self.transforms.transforms + ) + if is_legacy_transform: # to handle legacy transforms + img = torch.stack([self.transforms(im) for im in img], dim=0) + else: + img = torch.stack( + [self.transforms(Image.fromarray(cv2.cvtColor(im, cv2.COLOR_BGR2RGB))) for im in img], dim=0 + ) + img = (img if isinstance(img, torch.Tensor) else torch.from_numpy(img)).to(self.model.device) + return img.half() if self.model.fp16 else img.float() # uint8 to fp16/32 + + def postprocess(self, preds, img, orig_imgs): + """Post-processes predictions to return Results objects.""" + if not isinstance(orig_imgs, list): # input images are a torch.Tensor, not a list + orig_imgs = ops.convert_torch2numpy_batch(orig_imgs) + + results = [] + for i, pred in enumerate(preds): + orig_img = orig_imgs[i] + img_path = self.batch[0][i] + results.append(Results(orig_img, path=img_path, names=self.model.names, probs=pred)) + return results diff --git a/ultralytics/models/yolo/classify/train.py b/ultralytics/models/yolo/classify/train.py new file mode 100644 index 0000000..e049313 --- /dev/null +++ b/ultralytics/models/yolo/classify/train.py @@ -0,0 +1,159 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import torch + +from ultralytics.data import ClassificationDataset, build_dataloader +from ultralytics.engine.trainer import BaseTrainer +from ultralytics.models import yolo +from ultralytics.nn.tasks import ClassificationModel, attempt_load_one_weight +from ultralytics.utils import DEFAULT_CFG, LOGGER, RANK, colorstr +from ultralytics.utils.plotting import plot_images, plot_results +from ultralytics.utils.torch_utils import is_parallel, strip_optimizer, torch_distributed_zero_first + + +class ClassificationTrainer(BaseTrainer): + """ + A class extending the BaseTrainer class for training based on a classification model. + + Notes: + - Torchvision classification models can also be passed to the 'model' argument, i.e. model='resnet18'. + + Example: + ```python + from ultralytics.models.yolo.classify import ClassificationTrainer + + args = dict(model='yolov8n-cls.pt', data='imagenet10', epochs=3) + trainer = ClassificationTrainer(overrides=args) + trainer.train() + ``` + """ + + def __init__(self, cfg=DEFAULT_CFG, overrides=None, _callbacks=None): + """Initialize a ClassificationTrainer object with optional configuration overrides and callbacks.""" + if overrides is None: + overrides = {} + overrides["task"] = "classify" + if overrides.get("imgsz") is None: + overrides["imgsz"] = 224 + super().__init__(cfg, overrides, _callbacks) + + def set_model_attributes(self): + """Set the YOLO model's class names from the loaded dataset.""" + self.model.names = self.data["names"] + + def get_model(self, cfg=None, weights=None, verbose=True): + """Returns a modified PyTorch model configured for training YOLO.""" + model = ClassificationModel(cfg, nc=self.data["nc"], verbose=verbose and RANK == -1) + if weights: + model.load(weights) + + for m in model.modules(): + if not self.args.pretrained and hasattr(m, "reset_parameters"): + m.reset_parameters() + if isinstance(m, torch.nn.Dropout) and self.args.dropout: + m.p = self.args.dropout # set dropout + for p in model.parameters(): + p.requires_grad = True # for training + return model + + def setup_model(self): + """Load, create or download model for any task.""" + import torchvision # scope for faster 'import ultralytics' + + if isinstance(self.model, torch.nn.Module): # if model is loaded beforehand. No setup needed + return + + model, ckpt = str(self.model), None + # Load a YOLO model locally, from torchvision, or from Ultralytics assets + if model.endswith(".pt"): + self.model, ckpt = attempt_load_one_weight(model, device="cpu") + for p in self.model.parameters(): + p.requires_grad = True # for training + elif model.split(".")[-1] in {"yaml", "yml"}: + self.model = self.get_model(cfg=model) + elif model in torchvision.models.__dict__: + self.model = torchvision.models.__dict__[model](weights="IMAGENET1K_V1" if self.args.pretrained else None) + else: + raise FileNotFoundError(f"ERROR: model={model} not found locally or online. Please check model name.") + ClassificationModel.reshape_outputs(self.model, self.data["nc"]) + + return ckpt + + def build_dataset(self, img_path, mode="train", batch=None): + """Creates a ClassificationDataset instance given an image path, and mode (train/test etc.).""" + return ClassificationDataset(root=img_path, args=self.args, augment=mode == "train", prefix=mode) + + def get_dataloader(self, dataset_path, batch_size=16, rank=0, mode="train"): + """Returns PyTorch DataLoader with transforms to preprocess images for inference.""" + with torch_distributed_zero_first(rank): # init dataset *.cache only once if DDP + dataset = self.build_dataset(dataset_path, mode) + + loader = build_dataloader(dataset, batch_size, self.args.workers, rank=rank) + # Attach inference transforms + if mode != "train": + if is_parallel(self.model): + self.model.module.transforms = loader.dataset.torch_transforms + else: + self.model.transforms = loader.dataset.torch_transforms + return loader + + def preprocess_batch(self, batch): + """Preprocesses a batch of images and classes.""" + batch["img"] = batch["img"].to(self.device) + batch["cls"] = batch["cls"].to(self.device) + return batch + + def progress_string(self): + """Returns a formatted string showing training progress.""" + return ("\n" + "%11s" * (4 + len(self.loss_names))) % ( + "Epoch", + "GPU_mem", + *self.loss_names, + "Instances", + "Size", + ) + + def get_validator(self): + """Returns an instance of ClassificationValidator for validation.""" + self.loss_names = ["loss"] + return yolo.classify.ClassificationValidator(self.test_loader, self.save_dir, _callbacks=self.callbacks) + + def label_loss_items(self, loss_items=None, prefix="train"): + """ + Returns a loss dict with labelled training loss items tensor. + + Not needed for classification but necessary for segmentation & detection + """ + keys = [f"{prefix}/{x}" for x in self.loss_names] + if loss_items is None: + return keys + loss_items = [round(float(loss_items), 5)] + return dict(zip(keys, loss_items)) + + def plot_metrics(self): + """Plots metrics from a CSV file.""" + plot_results(file=self.csv, classify=True, on_plot=self.on_plot) # save results.png + + def final_eval(self): + """Evaluate trained model and save validation results.""" + for f in self.last, self.best: + if f.exists(): + strip_optimizer(f) # strip optimizers + if f is self.best: + LOGGER.info(f"\nValidating {f}...") + self.validator.args.data = self.args.data + self.validator.args.plots = self.args.plots + self.metrics = self.validator(model=f) + self.metrics.pop("fitness", None) + self.run_callbacks("on_fit_epoch_end") + LOGGER.info(f"Results saved to {colorstr('bold', self.save_dir)}") + + def plot_training_samples(self, batch, ni): + """Plots training samples with their annotations.""" + plot_images( + images=batch["img"], + batch_idx=torch.arange(len(batch["img"])), + cls=batch["cls"].view(-1), # warning: use .view(), not .squeeze() for Classify models + fname=self.save_dir / f"train_batch{ni}.jpg", + on_plot=self.on_plot, + ) diff --git a/ultralytics/models/yolo/classify/val.py b/ultralytics/models/yolo/classify/val.py new file mode 100644 index 0000000..de3cff2 --- /dev/null +++ b/ultralytics/models/yolo/classify/val.py @@ -0,0 +1,113 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import torch + +from ultralytics.data import ClassificationDataset, build_dataloader +from ultralytics.engine.validator import BaseValidator +from ultralytics.utils import LOGGER +from ultralytics.utils.metrics import ClassifyMetrics, ConfusionMatrix +from ultralytics.utils.plotting import plot_images + + +class ClassificationValidator(BaseValidator): + """ + A class extending the BaseValidator class for validation based on a classification model. + + Notes: + - Torchvision classification models can also be passed to the 'model' argument, i.e. model='resnet18'. + + Example: + ```python + from ultralytics.models.yolo.classify import ClassificationValidator + + args = dict(model='yolov8n-cls.pt', data='imagenet10') + validator = ClassificationValidator(args=args) + validator() + ``` + """ + + def __init__(self, dataloader=None, save_dir=None, pbar=None, args=None, _callbacks=None): + """Initializes ClassificationValidator instance with args, dataloader, save_dir, and progress bar.""" + super().__init__(dataloader, save_dir, pbar, args, _callbacks) + self.targets = None + self.pred = None + self.args.task = "classify" + self.metrics = ClassifyMetrics() + + def get_desc(self): + """Returns a formatted string summarizing classification metrics.""" + return ("%22s" + "%11s" * 2) % ("classes", "top1_acc", "top5_acc") + + def init_metrics(self, model): + """Initialize confusion matrix, class names, and top-1 and top-5 accuracy.""" + self.names = model.names + self.nc = len(model.names) + self.confusion_matrix = ConfusionMatrix(nc=self.nc, conf=self.args.conf, task="classify") + self.pred = [] + self.targets = [] + + def preprocess(self, batch): + """Preprocesses input batch and returns it.""" + batch["img"] = batch["img"].to(self.device, non_blocking=True) + batch["img"] = batch["img"].half() if self.args.half else batch["img"].float() + batch["cls"] = batch["cls"].to(self.device) + return batch + + def update_metrics(self, preds, batch): + """Updates running metrics with model predictions and batch targets.""" + n5 = min(len(self.names), 5) + self.pred.append(preds.argsort(1, descending=True)[:, :n5]) + self.targets.append(batch["cls"]) + + def finalize_metrics(self, *args, **kwargs): + """Finalizes metrics of the model such as confusion_matrix and speed.""" + self.confusion_matrix.process_cls_preds(self.pred, self.targets) + if self.args.plots: + for normalize in True, False: + self.confusion_matrix.plot( + save_dir=self.save_dir, names=self.names.values(), normalize=normalize, on_plot=self.on_plot + ) + self.metrics.speed = self.speed + self.metrics.confusion_matrix = self.confusion_matrix + self.metrics.save_dir = self.save_dir + + def get_stats(self): + """Returns a dictionary of metrics obtained by processing targets and predictions.""" + self.metrics.process(self.targets, self.pred) + return self.metrics.results_dict + + def build_dataset(self, img_path): + """Creates and returns a ClassificationDataset instance using given image path and preprocessing parameters.""" + return ClassificationDataset(root=img_path, args=self.args, augment=False, prefix=self.args.split) + + def get_dataloader(self, dataset_path, batch_size): + """Builds and returns a data loader for classification tasks with given parameters.""" + dataset = self.build_dataset(dataset_path) + return build_dataloader(dataset, batch_size, self.args.workers, rank=-1) + + def print_results(self): + """Prints evaluation metrics for YOLO object detection model.""" + pf = "%22s" + "%11.3g" * len(self.metrics.keys) # print format + LOGGER.info(pf % ("all", self.metrics.top1, self.metrics.top5)) + + def plot_val_samples(self, batch, ni): + """Plot validation image samples.""" + plot_images( + images=batch["img"], + batch_idx=torch.arange(len(batch["img"])), + cls=batch["cls"].view(-1), # warning: use .view(), not .squeeze() for Classify models + fname=self.save_dir / f"val_batch{ni}_labels.jpg", + names=self.names, + on_plot=self.on_plot, + ) + + def plot_predictions(self, batch, preds, ni): + """Plots predicted bounding boxes on input images and saves the result.""" + plot_images( + batch["img"], + batch_idx=torch.arange(len(batch["img"])), + cls=torch.argmax(preds, dim=1), + fname=self.save_dir / f"val_batch{ni}_pred.jpg", + names=self.names, + on_plot=self.on_plot, + ) # pred diff --git a/ultralytics/models/yolo/detect/__init__.py b/ultralytics/models/yolo/detect/__init__.py new file mode 100644 index 0000000..5f3e62c --- /dev/null +++ b/ultralytics/models/yolo/detect/__init__.py @@ -0,0 +1,7 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from .predict import DetectionPredictor +from .train import DetectionTrainer +from .val import DetectionValidator + +__all__ = "DetectionPredictor", "DetectionTrainer", "DetectionValidator" diff --git a/ultralytics/models/yolo/detect/predict.py b/ultralytics/models/yolo/detect/predict.py new file mode 100644 index 0000000..3a0c628 --- /dev/null +++ b/ultralytics/models/yolo/detect/predict.py @@ -0,0 +1,43 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from ultralytics.engine.predictor import BasePredictor +from ultralytics.engine.results import Results +from ultralytics.utils import ops + + +class DetectionPredictor(BasePredictor): + """ + A class extending the BasePredictor class for prediction based on a detection model. + + Example: + ```python + from ultralytics.utils import ASSETS + from ultralytics.models.yolo.detect import DetectionPredictor + + args = dict(model='yolov8n.pt', source=ASSETS) + predictor = DetectionPredictor(overrides=args) + predictor.predict_cli() + ``` + """ + + def postprocess(self, preds, img, orig_imgs): + """Post-processes predictions and returns a list of Results objects.""" + preds = ops.non_max_suppression( + preds, + self.args.conf, + self.args.iou, + agnostic=self.args.agnostic_nms, + max_det=self.args.max_det, + classes=self.args.classes, + ) + + if not isinstance(orig_imgs, list): # input images are a torch.Tensor, not a list + orig_imgs = ops.convert_torch2numpy_batch(orig_imgs) + + results = [] + for i, pred in enumerate(preds): + orig_img = orig_imgs[i] + pred[:, :4] = ops.scale_boxes(img.shape[2:], pred[:, :4], orig_img.shape) + img_path = self.batch[0][i] + results.append(Results(orig_img, path=img_path, names=self.model.names, boxes=pred)) + return results diff --git a/ultralytics/models/yolo/detect/train.py b/ultralytics/models/yolo/detect/train.py new file mode 100644 index 0000000..65b7eff --- /dev/null +++ b/ultralytics/models/yolo/detect/train.py @@ -0,0 +1,143 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import math +import random +from copy import copy + +import numpy as np +import torch.nn as nn + +from ultralytics.data import build_dataloader, build_yolo_dataset +from ultralytics.engine.trainer import BaseTrainer +from ultralytics.models import yolo +from ultralytics.nn.tasks import DetectionModel +from ultralytics.utils import LOGGER, RANK +from ultralytics.utils.plotting import plot_images, plot_labels, plot_results +from ultralytics.utils.torch_utils import de_parallel, torch_distributed_zero_first + + +class DetectionTrainer(BaseTrainer): + """ + A class extending the BaseTrainer class for training based on a detection model. + + Example: + ```python + from ultralytics.models.yolo.detect import DetectionTrainer + + args = dict(model='yolov8n.pt', data='coco8.yaml', epochs=3) + trainer = DetectionTrainer(overrides=args) + trainer.train() + ``` + """ + + def build_dataset(self, img_path, mode="train", batch=None): + """ + Build YOLO Dataset. + + Args: + img_path (str): Path to the folder containing images. + mode (str): `train` mode or `val` mode, users are able to customize different augmentations for each mode. + batch (int, optional): Size of batches, this is for `rect`. Defaults to None. + """ + gs = max(int(de_parallel(self.model).stride.max() if self.model else 0), 32) + return build_yolo_dataset(self.args, img_path, batch, self.data, mode=mode, rect=mode == "val", stride=gs) + + def get_dataloader(self, dataset_path, batch_size=16, rank=0, mode="train"): + """Construct and return dataloader.""" + assert mode in {"train", "val"}, f"Mode must be 'train' or 'val', not {mode}." + with torch_distributed_zero_first(rank): # init dataset *.cache only once if DDP + dataset = self.build_dataset(dataset_path, mode, batch_size) + shuffle = mode == "train" + if getattr(dataset, "rect", False) and shuffle: + LOGGER.warning("WARNING ⚠️ 'rect=True' is incompatible with DataLoader shuffle, setting shuffle=False") + shuffle = False + workers = self.args.workers if mode == "train" else self.args.workers * 2 + return build_dataloader(dataset, batch_size, workers, shuffle, rank) # return dataloader + + def preprocess_batch(self, batch): + """Preprocesses a batch of images by scaling and converting to float.""" + batch["img"] = batch["img"].to(self.device, non_blocking=True).float() / 255 + if self.args.multi_scale: + imgs = batch["img"] + sz = ( + random.randrange(self.args.imgsz * 0.5, self.args.imgsz * 1.5 + self.stride) + // self.stride + * self.stride + ) # size + sf = sz / max(imgs.shape[2:]) # scale factor + if sf != 1: + ns = [ + math.ceil(x * sf / self.stride) * self.stride for x in imgs.shape[2:] + ] # new shape (stretched to gs-multiple) + imgs = nn.functional.interpolate(imgs, size=ns, mode="bilinear", align_corners=False) + batch["img"] = imgs + return batch + + def set_model_attributes(self): + """Nl = de_parallel(self.model).model[-1].nl # number of detection layers (to scale hyps).""" + # self.args.box *= 3 / nl # scale to layers + # self.args.cls *= self.data["nc"] / 80 * 3 / nl # scale to classes and layers + # self.args.cls *= (self.args.imgsz / 640) ** 2 * 3 / nl # scale to image size and layers + self.model.nc = self.data["nc"] # attach number of classes to model + self.model.names = self.data["names"] # attach class names to model + self.model.args = self.args # attach hyperparameters to model + # TODO: self.model.class_weights = labels_to_class_weights(dataset.labels, nc).to(device) * nc + + def get_model(self, cfg=None, weights=None, verbose=True): + """Return a YOLO detection model.""" + model = DetectionModel(cfg, nc=self.data["nc"], verbose=verbose and RANK == -1) + if weights: + model.load(weights) + return model + + def get_validator(self): + """Returns a DetectionValidator for YOLO model validation.""" + self.loss_names = "box_loss", "cls_loss", "dfl_loss" + return yolo.detect.DetectionValidator( + self.test_loader, save_dir=self.save_dir, args=copy(self.args), _callbacks=self.callbacks + ) + + def label_loss_items(self, loss_items=None, prefix="train"): + """ + Returns a loss dict with labelled training loss items tensor. + + Not needed for classification but necessary for segmentation & detection + """ + keys = [f"{prefix}/{x}" for x in self.loss_names] + if loss_items is not None: + loss_items = [round(float(x), 5) for x in loss_items] # convert tensors to 5 decimal place floats + return dict(zip(keys, loss_items)) + else: + return keys + + def progress_string(self): + """Returns a formatted string of training progress with epoch, GPU memory, loss, instances and size.""" + return ("\n" + "%11s" * (4 + len(self.loss_names))) % ( + "Epoch", + "GPU_mem", + *self.loss_names, + "Instances", + "Size", + ) + + def plot_training_samples(self, batch, ni): + """Plots training samples with their annotations.""" + plot_images( + images=batch["img"], + batch_idx=batch["batch_idx"], + cls=batch["cls"].squeeze(-1), + bboxes=batch["bboxes"], + paths=batch["im_file"], + fname=self.save_dir / f"train_batch{ni}.jpg", + on_plot=self.on_plot, + ) + + def plot_metrics(self): + """Plots metrics from a CSV file.""" + plot_results(file=self.csv, on_plot=self.on_plot) # save results.png + + def plot_training_labels(self): + """Create a labeled training plot of the YOLO model.""" + boxes = np.concatenate([lb["bboxes"] for lb in self.train_loader.dataset.labels], 0) + cls = np.concatenate([lb["cls"] for lb in self.train_loader.dataset.labels], 0) + plot_labels(boxes, cls.squeeze(), names=self.data["names"], save_dir=self.save_dir, on_plot=self.on_plot) diff --git a/ultralytics/models/yolo/detect/val.py b/ultralytics/models/yolo/detect/val.py new file mode 100644 index 0000000..28dd7b8 --- /dev/null +++ b/ultralytics/models/yolo/detect/val.py @@ -0,0 +1,318 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import os +from pathlib import Path + +import numpy as np +import torch + +from ultralytics.data import build_dataloader, build_yolo_dataset, converter +from ultralytics.engine.validator import BaseValidator +from ultralytics.utils import LOGGER, ops +from ultralytics.utils.checks import check_requirements +from ultralytics.utils.metrics import ConfusionMatrix, DetMetrics, box_iou +from ultralytics.utils.plotting import output_to_target, plot_images + + +class DetectionValidator(BaseValidator): + """ + A class extending the BaseValidator class for validation based on a detection model. + + Example: + ```python + from ultralytics.models.yolo.detect import DetectionValidator + + args = dict(model='yolov8n.pt', data='coco8.yaml') + validator = DetectionValidator(args=args) + validator() + ``` + """ + + def __init__(self, dataloader=None, save_dir=None, pbar=None, args=None, _callbacks=None): + """Initialize detection model with necessary variables and settings.""" + super().__init__(dataloader, save_dir, pbar, args, _callbacks) + self.nt_per_class = None + self.is_coco = False + self.is_lvis = False + self.class_map = None + self.args.task = "detect" + self.metrics = DetMetrics(save_dir=self.save_dir, on_plot=self.on_plot) + self.iouv = torch.linspace(0.5, 0.95, 10) # IoU vector for mAP@0.5:0.95 + self.niou = self.iouv.numel() + self.lb = [] # for autolabelling + + def preprocess(self, batch): + """Preprocesses batch of images for YOLO training.""" + batch["img"] = batch["img"].to(self.device, non_blocking=True) + batch["img"] = (batch["img"].half() if self.args.half else batch["img"].float()) / 255 + for k in ["batch_idx", "cls", "bboxes"]: + batch[k] = batch[k].to(self.device) + + if self.args.save_hybrid: + height, width = batch["img"].shape[2:] + nb = len(batch["img"]) + bboxes = batch["bboxes"] * torch.tensor((width, height, width, height), device=self.device) + self.lb = ( + [ + torch.cat([batch["cls"][batch["batch_idx"] == i], bboxes[batch["batch_idx"] == i]], dim=-1) + for i in range(nb) + ] + if self.args.save_hybrid + else [] + ) # for autolabelling + + return batch + + def init_metrics(self, model): + """Initialize evaluation metrics for YOLO.""" + val = self.data.get(self.args.split, "") # validation path + self.is_coco = isinstance(val, str) and "coco" in val and val.endswith(f"{os.sep}val2017.txt") # is COCO + self.is_lvis = isinstance(val, str) and "lvis" in val and not self.is_coco # is LVIS + self.class_map = converter.coco80_to_coco91_class() if self.is_coco else list(range(len(model.names))) + self.args.save_json |= (self.is_coco or self.is_lvis) and not self.training # run on final val if training COCO + self.names = model.names + self.nc = len(model.names) + self.metrics.names = self.names + self.metrics.plot = self.args.plots + self.confusion_matrix = ConfusionMatrix(nc=self.nc, conf=self.args.conf) + self.seen = 0 + self.jdict = [] + self.stats = dict(tp=[], conf=[], pred_cls=[], target_cls=[]) + + def get_desc(self): + """Return a formatted string summarizing class metrics of YOLO model.""" + return ("%22s" + "%11s" * 6) % ("Class", "Images", "Instances", "Box(P", "R", "mAP50", "mAP50-95)") + + def postprocess(self, preds): + """Apply Non-maximum suppression to prediction outputs.""" + return ops.non_max_suppression( + preds, + self.args.conf, + self.args.iou, + labels=self.lb, + multi_label=True, + agnostic=self.args.single_cls, + max_det=self.args.max_det, + ) + + def _prepare_batch(self, si, batch): + """Prepares a batch of images and annotations for validation.""" + idx = batch["batch_idx"] == si + cls = batch["cls"][idx].squeeze(-1) + bbox = batch["bboxes"][idx] + ori_shape = batch["ori_shape"][si] + imgsz = batch["img"].shape[2:] + ratio_pad = batch["ratio_pad"][si] + if len(cls): + bbox = ops.xywh2xyxy(bbox) * torch.tensor(imgsz, device=self.device)[[1, 0, 1, 0]] # target boxes + ops.scale_boxes(imgsz, bbox, ori_shape, ratio_pad=ratio_pad) # native-space labels + return {"cls": cls, "bbox": bbox, "ori_shape": ori_shape, "imgsz": imgsz, "ratio_pad": ratio_pad} + + def _prepare_pred(self, pred, pbatch): + """Prepares a batch of images and annotations for validation.""" + predn = pred.clone() + ops.scale_boxes( + pbatch["imgsz"], predn[:, :4], pbatch["ori_shape"], ratio_pad=pbatch["ratio_pad"] + ) # native-space pred + return predn + + def update_metrics(self, preds, batch): + """Metrics.""" + for si, pred in enumerate(preds): + self.seen += 1 + npr = len(pred) + stat = dict( + conf=torch.zeros(0, device=self.device), + pred_cls=torch.zeros(0, device=self.device), + tp=torch.zeros(npr, self.niou, dtype=torch.bool, device=self.device), + ) + pbatch = self._prepare_batch(si, batch) + cls, bbox = pbatch.pop("cls"), pbatch.pop("bbox") + nl = len(cls) + stat["target_cls"] = cls + if npr == 0: + if nl: + for k in self.stats.keys(): + self.stats[k].append(stat[k]) + if self.args.plots: + self.confusion_matrix.process_batch(detections=None, gt_bboxes=bbox, gt_cls=cls) + continue + + # Predictions + if self.args.single_cls: + pred[:, 5] = 0 + predn = self._prepare_pred(pred, pbatch) + stat["conf"] = predn[:, 4] + stat["pred_cls"] = predn[:, 5] + + # Evaluate + if nl: + stat["tp"] = self._process_batch(predn, bbox, cls) + if self.args.plots: + self.confusion_matrix.process_batch(predn, bbox, cls) + for k in self.stats.keys(): + self.stats[k].append(stat[k]) + + # Save + if self.args.save_json: + self.pred_to_json(predn, batch["im_file"][si]) + if self.args.save_txt: + file = self.save_dir / "labels" / f'{Path(batch["im_file"][si]).stem}.txt' + self.save_one_txt(predn, self.args.save_conf, pbatch["ori_shape"], file) + + def finalize_metrics(self, *args, **kwargs): + """Set final values for metrics speed and confusion matrix.""" + self.metrics.speed = self.speed + self.metrics.confusion_matrix = self.confusion_matrix + + def get_stats(self): + """Returns metrics statistics and results dictionary.""" + stats = {k: torch.cat(v, 0).cpu().numpy() for k, v in self.stats.items()} # to numpy + if len(stats) and stats["tp"].any(): + self.metrics.process(**stats) + self.nt_per_class = np.bincount( + stats["target_cls"].astype(int), minlength=self.nc + ) # number of targets per class + return self.metrics.results_dict + + def print_results(self): + """Prints training/validation set metrics per class.""" + pf = "%22s" + "%11i" * 2 + "%11.3g" * len(self.metrics.keys) # print format + LOGGER.info(pf % ("all", self.seen, self.nt_per_class.sum(), *self.metrics.mean_results())) + if self.nt_per_class.sum() == 0: + LOGGER.warning(f"WARNING ⚠️ no labels found in {self.args.task} set, can not compute metrics without labels") + + # Print results per class + if self.args.verbose and not self.training and self.nc > 1 and len(self.stats): + for i, c in enumerate(self.metrics.ap_class_index): + LOGGER.info(pf % (self.names[c], self.seen, self.nt_per_class[c], *self.metrics.class_result(i))) + + if self.args.plots: + for normalize in True, False: + self.confusion_matrix.plot( + save_dir=self.save_dir, names=self.names.values(), normalize=normalize, on_plot=self.on_plot + ) + + def _process_batch(self, detections, gt_bboxes, gt_cls): + """ + Return correct prediction matrix. + + Args: + detections (torch.Tensor): Tensor of shape [N, 6] representing detections. + Each detection is of the format: x1, y1, x2, y2, conf, class. + labels (torch.Tensor): Tensor of shape [M, 5] representing labels. + Each label is of the format: class, x1, y1, x2, y2. + + Returns: + (torch.Tensor): Correct prediction matrix of shape [N, 10] for 10 IoU levels. + """ + iou = box_iou(gt_bboxes, detections[:, :4]) + return self.match_predictions(detections[:, 5], gt_cls, iou) + + def build_dataset(self, img_path, mode="val", batch=None): + """ + Build YOLO Dataset. + + Args: + img_path (str): Path to the folder containing images. + mode (str): `train` mode or `val` mode, users are able to customize different augmentations for each mode. + batch (int, optional): Size of batches, this is for `rect`. Defaults to None. + """ + return build_yolo_dataset(self.args, img_path, batch, self.data, mode=mode, stride=self.stride) + + def get_dataloader(self, dataset_path, batch_size): + """Construct and return dataloader.""" + dataset = self.build_dataset(dataset_path, batch=batch_size, mode="val") + return build_dataloader(dataset, batch_size, self.args.workers, shuffle=False, rank=-1) # return dataloader + + def plot_val_samples(self, batch, ni): + """Plot validation image samples.""" + plot_images( + batch["img"], + batch["batch_idx"], + batch["cls"].squeeze(-1), + batch["bboxes"], + paths=batch["im_file"], + fname=self.save_dir / f"val_batch{ni}_labels.jpg", + names=self.names, + on_plot=self.on_plot, + ) + + def plot_predictions(self, batch, preds, ni): + """Plots predicted bounding boxes on input images and saves the result.""" + plot_images( + batch["img"], + *output_to_target(preds, max_det=self.args.max_det), + paths=batch["im_file"], + fname=self.save_dir / f"val_batch{ni}_pred.jpg", + names=self.names, + on_plot=self.on_plot, + ) # pred + + def save_one_txt(self, predn, save_conf, shape, file): + """Save YOLO detections to a txt file in normalized coordinates in a specific format.""" + gn = torch.tensor(shape)[[1, 0, 1, 0]] # normalization gain whwh + for *xyxy, conf, cls in predn.tolist(): + xywh = (ops.xyxy2xywh(torch.tensor(xyxy).view(1, 4)) / gn).view(-1).tolist() # normalized xywh + line = (cls, *xywh, conf) if save_conf else (cls, *xywh) # label format + with open(file, "a") as f: + f.write(("%g " * len(line)).rstrip() % line + "\n") + + def pred_to_json(self, predn, filename): + """Serialize YOLO predictions to COCO json format.""" + stem = Path(filename).stem + image_id = int(stem) if stem.isnumeric() else stem + box = ops.xyxy2xywh(predn[:, :4]) # xywh + box[:, :2] -= box[:, 2:] / 2 # xy center to top-left corner + for p, b in zip(predn.tolist(), box.tolist()): + self.jdict.append( + { + "image_id": image_id, + "category_id": self.class_map[int(p[5])] + + (1 if self.is_lvis else 0), # index starts from 1 if it's lvis + "bbox": [round(x, 3) for x in b], + "score": round(p[4], 5), + } + ) + + def eval_json(self, stats): + """Evaluates YOLO output in JSON format and returns performance statistics.""" + if self.args.save_json and (self.is_coco or self.is_lvis) and len(self.jdict): + pred_json = self.save_dir / "predictions.json" # predictions + anno_json = ( + self.data["path"] + / "annotations" + / ("instances_val2017.json" if self.is_coco else f"lvis_v1_{self.args.split}.json") + ) # annotations + pkg = "pycocotools" if self.is_coco else "lvis" + LOGGER.info(f"\nEvaluating {pkg} mAP using {pred_json} and {anno_json}...") + try: # https://github.com/cocodataset/cocoapi/blob/master/PythonAPI/pycocoEvalDemo.ipynb + for x in pred_json, anno_json: + assert x.is_file(), f"{x} file not found" + check_requirements("pycocotools>=2.0.6" if self.is_coco else "lvis>=0.5.3") + if self.is_coco: + from pycocotools.coco import COCO # noqa + from pycocotools.cocoeval import COCOeval # noqa + + anno = COCO(str(anno_json)) # init annotations api + pred = anno.loadRes(str(pred_json)) # init predictions api (must pass string, not Path) + eval = COCOeval(anno, pred, "bbox") + else: + from lvis import LVIS, LVISEval + + anno = LVIS(str(anno_json)) # init annotations api + pred = anno._load_json(str(pred_json)) # init predictions api (must pass string, not Path) + eval = LVISEval(anno, pred, "bbox") + eval.params.imgIds = [int(Path(x).stem) for x in self.dataloader.dataset.im_files] # images to eval + eval.evaluate() + eval.accumulate() + eval.summarize() + if self.is_lvis: + eval.print_results() # explicitly call print_results + # update mAP50-95 and mAP50 + stats[self.metrics.keys[-1]], stats[self.metrics.keys[-2]] = ( + eval.stats[:2] if self.is_coco else [eval.results["AP50"], eval.results["AP"]] + ) + except Exception as e: + LOGGER.warning(f"{pkg} unable to run: {e}") + return stats diff --git a/ultralytics/models/yolo/model.py b/ultralytics/models/yolo/model.py new file mode 100644 index 0000000..0b49d67 --- /dev/null +++ b/ultralytics/models/yolo/model.py @@ -0,0 +1,107 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from pathlib import Path + +from ultralytics.engine.model import Model +from ultralytics.models import yolo +from ultralytics.nn.tasks import ClassificationModel, DetectionModel, OBBModel, PoseModel, SegmentationModel, WorldModel +from ultralytics.utils import ROOT, yaml_load + + +class YOLO(Model): + """YOLO (You Only Look Once) object detection model.""" + + def __init__(self, model="yolov8n.pt", task=None, verbose=False): + """Initialize YOLO model, switching to YOLOWorld if model filename contains '-world'.""" + path = Path(model) + if "-world" in path.stem and path.suffix in {".pt", ".yaml", ".yml"}: # if YOLOWorld PyTorch model + new_instance = YOLOWorld(path) + self.__class__ = type(new_instance) + self.__dict__ = new_instance.__dict__ + else: + # Continue with default YOLO initialization + super().__init__(model=model, task=task, verbose=verbose) + + @property + def task_map(self): + """Map head to model, trainer, validator, and predictor classes.""" + return { + "classify": { + "model": ClassificationModel, + "trainer": yolo.classify.ClassificationTrainer, + "validator": yolo.classify.ClassificationValidator, + "predictor": yolo.classify.ClassificationPredictor, + }, + "detect": { + "model": DetectionModel, + "trainer": yolo.detect.DetectionTrainer, + "validator": yolo.detect.DetectionValidator, + "predictor": yolo.detect.DetectionPredictor, + }, + "segment": { + "model": SegmentationModel, + "trainer": yolo.segment.SegmentationTrainer, + "validator": yolo.segment.SegmentationValidator, + "predictor": yolo.segment.SegmentationPredictor, + }, + "pose": { + "model": PoseModel, + "trainer": yolo.pose.PoseTrainer, + "validator": yolo.pose.PoseValidator, + "predictor": yolo.pose.PosePredictor, + }, + "obb": { + "model": OBBModel, + "trainer": yolo.obb.OBBTrainer, + "validator": yolo.obb.OBBValidator, + "predictor": yolo.obb.OBBPredictor, + }, + } + + +class YOLOWorld(Model): + """YOLO-World object detection model.""" + + def __init__(self, model="yolov8s-world.pt") -> None: + """ + Initializes the YOLOv8-World model with the given pre-trained model file. Supports *.pt and *.yaml formats. + + Args: + model (str | Path): Path to the pre-trained model. Defaults to 'yolov8s-world.pt'. + """ + super().__init__(model=model, task="detect") + + # Assign default COCO class names when there are no custom names + if not hasattr(self.model, "names"): + self.model.names = yaml_load(ROOT / "cfg/datasets/coco8.yaml").get("names") + + @property + def task_map(self): + """Map head to model, validator, and predictor classes.""" + return { + "detect": { + "model": WorldModel, + "validator": yolo.detect.DetectionValidator, + "predictor": yolo.detect.DetectionPredictor, + "trainer": yolo.world.WorldTrainer, + } + } + + def set_classes(self, classes): + """ + Set classes. + + Args: + classes (List(str)): A list of categories i.e ["person"]. + """ + self.model.set_classes(classes) + # Remove background if it's given + background = " " + if background in classes: + classes.remove(background) + self.model.names = classes + + # Reset method class names + # self.predictor = None # reset predictor otherwise old names remain + if self.predictor: + self.predictor.model.names = classes diff --git a/ultralytics/models/yolo/obb/__init__.py b/ultralytics/models/yolo/obb/__init__.py new file mode 100644 index 0000000..f60349a --- /dev/null +++ b/ultralytics/models/yolo/obb/__init__.py @@ -0,0 +1,7 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from .predict import OBBPredictor +from .train import OBBTrainer +from .val import OBBValidator + +__all__ = "OBBPredictor", "OBBTrainer", "OBBValidator" diff --git a/ultralytics/models/yolo/obb/predict.py b/ultralytics/models/yolo/obb/predict.py new file mode 100644 index 0000000..bb8d4d3 --- /dev/null +++ b/ultralytics/models/yolo/obb/predict.py @@ -0,0 +1,53 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import torch + +from ultralytics.engine.results import Results +from ultralytics.models.yolo.detect.predict import DetectionPredictor +from ultralytics.utils import DEFAULT_CFG, ops + + +class OBBPredictor(DetectionPredictor): + """ + A class extending the DetectionPredictor class for prediction based on an Oriented Bounding Box (OBB) model. + + Example: + ```python + from ultralytics.utils import ASSETS + from ultralytics.models.yolo.obb import OBBPredictor + + args = dict(model='yolov8n-obb.pt', source=ASSETS) + predictor = OBBPredictor(overrides=args) + predictor.predict_cli() + ``` + """ + + def __init__(self, cfg=DEFAULT_CFG, overrides=None, _callbacks=None): + """Initializes OBBPredictor with optional model and data configuration overrides.""" + super().__init__(cfg, overrides, _callbacks) + self.args.task = "obb" + + def postprocess(self, preds, img, orig_imgs): + """Post-processes predictions and returns a list of Results objects.""" + preds = ops.non_max_suppression( + preds, + self.args.conf, + self.args.iou, + agnostic=self.args.agnostic_nms, + max_det=self.args.max_det, + nc=len(self.model.names), + classes=self.args.classes, + rotated=True, + ) + + if not isinstance(orig_imgs, list): # input images are a torch.Tensor, not a list + orig_imgs = ops.convert_torch2numpy_batch(orig_imgs) + + results = [] + for pred, orig_img, img_path in zip(preds, orig_imgs, self.batch[0]): + rboxes = ops.regularize_rboxes(torch.cat([pred[:, :4], pred[:, -1:]], dim=-1)) + rboxes[:, :4] = ops.scale_boxes(img.shape[2:], rboxes[:, :4], orig_img.shape, xywh=True) + # xywh, r, conf, cls + obb = torch.cat([rboxes, pred[:, 4:6]], dim=-1) + results.append(Results(orig_img, path=img_path, names=self.model.names, obb=obb)) + return results diff --git a/ultralytics/models/yolo/obb/train.py b/ultralytics/models/yolo/obb/train.py new file mode 100644 index 0000000..40a35a9 --- /dev/null +++ b/ultralytics/models/yolo/obb/train.py @@ -0,0 +1,42 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from copy import copy + +from ultralytics.models import yolo +from ultralytics.nn.tasks import OBBModel +from ultralytics.utils import DEFAULT_CFG, RANK + + +class OBBTrainer(yolo.detect.DetectionTrainer): + """ + A class extending the DetectionTrainer class for training based on an Oriented Bounding Box (OBB) model. + + Example: + ```python + from ultralytics.models.yolo.obb import OBBTrainer + + args = dict(model='yolov8n-obb.pt', data='dota8.yaml', epochs=3) + trainer = OBBTrainer(overrides=args) + trainer.train() + ``` + """ + + def __init__(self, cfg=DEFAULT_CFG, overrides=None, _callbacks=None): + """Initialize a OBBTrainer object with given arguments.""" + if overrides is None: + overrides = {} + overrides["task"] = "obb" + super().__init__(cfg, overrides, _callbacks) + + def get_model(self, cfg=None, weights=None, verbose=True): + """Return OBBModel initialized with specified config and weights.""" + model = OBBModel(cfg, ch=3, nc=self.data["nc"], verbose=verbose and RANK == -1) + if weights: + model.load(weights) + + return model + + def get_validator(self): + """Return an instance of OBBValidator for validation of YOLO model.""" + self.loss_names = "box_loss", "cls_loss", "dfl_loss" + return yolo.obb.OBBValidator(self.test_loader, save_dir=self.save_dir, args=copy(self.args)) diff --git a/ultralytics/models/yolo/obb/val.py b/ultralytics/models/yolo/obb/val.py new file mode 100644 index 0000000..08c056c --- /dev/null +++ b/ultralytics/models/yolo/obb/val.py @@ -0,0 +1,185 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from pathlib import Path + +import torch + +from ultralytics.models.yolo.detect import DetectionValidator +from ultralytics.utils import LOGGER, ops +from ultralytics.utils.metrics import OBBMetrics, batch_probiou +from ultralytics.utils.plotting import output_to_rotated_target, plot_images + + +class OBBValidator(DetectionValidator): + """ + A class extending the DetectionValidator class for validation based on an Oriented Bounding Box (OBB) model. + + Example: + ```python + from ultralytics.models.yolo.obb import OBBValidator + + args = dict(model='yolov8n-obb.pt', data='dota8.yaml') + validator = OBBValidator(args=args) + validator(model=args['model']) + ``` + """ + + def __init__(self, dataloader=None, save_dir=None, pbar=None, args=None, _callbacks=None): + """Initialize OBBValidator and set task to 'obb', metrics to OBBMetrics.""" + super().__init__(dataloader, save_dir, pbar, args, _callbacks) + self.args.task = "obb" + self.metrics = OBBMetrics(save_dir=self.save_dir, plot=True, on_plot=self.on_plot) + + def init_metrics(self, model): + """Initialize evaluation metrics for YOLO.""" + super().init_metrics(model) + val = self.data.get(self.args.split, "") # validation path + self.is_dota = isinstance(val, str) and "DOTA" in val # is COCO + + def postprocess(self, preds): + """Apply Non-maximum suppression to prediction outputs.""" + return ops.non_max_suppression( + preds, + self.args.conf, + self.args.iou, + labels=self.lb, + nc=self.nc, + multi_label=True, + agnostic=self.args.single_cls, + max_det=self.args.max_det, + rotated=True, + ) + + def _process_batch(self, detections, gt_bboxes, gt_cls): + """ + Return correct prediction matrix. + + Args: + detections (torch.Tensor): Tensor of shape [N, 7] representing detections. + Each detection is of the format: x1, y1, x2, y2, conf, class, angle. + gt_bboxes (torch.Tensor): Tensor of shape [M, 5] representing rotated boxes. + Each box is of the format: x1, y1, x2, y2, angle. + labels (torch.Tensor): Tensor of shape [M] representing labels. + + Returns: + (torch.Tensor): Correct prediction matrix of shape [N, 10] for 10 IoU levels. + """ + iou = batch_probiou(gt_bboxes, torch.cat([detections[:, :4], detections[:, -1:]], dim=-1)) + return self.match_predictions(detections[:, 5], gt_cls, iou) + + def _prepare_batch(self, si, batch): + """Prepares and returns a batch for OBB validation.""" + idx = batch["batch_idx"] == si + cls = batch["cls"][idx].squeeze(-1) + bbox = batch["bboxes"][idx] + ori_shape = batch["ori_shape"][si] + imgsz = batch["img"].shape[2:] + ratio_pad = batch["ratio_pad"][si] + if len(cls): + bbox[..., :4].mul_(torch.tensor(imgsz, device=self.device)[[1, 0, 1, 0]]) # target boxes + ops.scale_boxes(imgsz, bbox, ori_shape, ratio_pad=ratio_pad, xywh=True) # native-space labels + return {"cls": cls, "bbox": bbox, "ori_shape": ori_shape, "imgsz": imgsz, "ratio_pad": ratio_pad} + + def _prepare_pred(self, pred, pbatch): + """Prepares and returns a batch for OBB validation with scaled and padded bounding boxes.""" + predn = pred.clone() + ops.scale_boxes( + pbatch["imgsz"], predn[:, :4], pbatch["ori_shape"], ratio_pad=pbatch["ratio_pad"], xywh=True + ) # native-space pred + return predn + + def plot_predictions(self, batch, preds, ni): + """Plots predicted bounding boxes on input images and saves the result.""" + plot_images( + batch["img"], + *output_to_rotated_target(preds, max_det=self.args.max_det), + paths=batch["im_file"], + fname=self.save_dir / f"val_batch{ni}_pred.jpg", + names=self.names, + on_plot=self.on_plot, + ) # pred + + def pred_to_json(self, predn, filename): + """Serialize YOLO predictions to COCO json format.""" + stem = Path(filename).stem + image_id = int(stem) if stem.isnumeric() else stem + rbox = torch.cat([predn[:, :4], predn[:, -1:]], dim=-1) + poly = ops.xywhr2xyxyxyxy(rbox).view(-1, 8) + for i, (r, b) in enumerate(zip(rbox.tolist(), poly.tolist())): + self.jdict.append( + { + "image_id": image_id, + "category_id": self.class_map[int(predn[i, 5].item())], + "score": round(predn[i, 4].item(), 5), + "rbox": [round(x, 3) for x in r], + "poly": [round(x, 3) for x in b], + } + ) + + def save_one_txt(self, predn, save_conf, shape, file): + """Save YOLO detections to a txt file in normalized coordinates in a specific format.""" + gn = torch.tensor(shape)[[1, 0]] # normalization gain whwh + for *xywh, conf, cls, angle in predn.tolist(): + xywha = torch.tensor([*xywh, angle]).view(1, 5) + xyxyxyxy = (ops.xywhr2xyxyxyxy(xywha) / gn).view(-1).tolist() # normalized xywh + line = (cls, *xyxyxyxy, conf) if save_conf else (cls, *xyxyxyxy) # label format + with open(file, "a") as f: + f.write(("%g " * len(line)).rstrip() % line + "\n") + + def eval_json(self, stats): + """Evaluates YOLO output in JSON format and returns performance statistics.""" + if self.args.save_json and self.is_dota and len(self.jdict): + import json + import re + from collections import defaultdict + + pred_json = self.save_dir / "predictions.json" # predictions + pred_txt = self.save_dir / "predictions_txt" # predictions + pred_txt.mkdir(parents=True, exist_ok=True) + data = json.load(open(pred_json)) + # Save split results + LOGGER.info(f"Saving predictions with DOTA format to {pred_txt}...") + for d in data: + image_id = d["image_id"] + score = d["score"] + classname = self.names[d["category_id"]].replace(" ", "-") + p = d["poly"] + + with open(f'{pred_txt / f"Task1_{classname}"}.txt', "a") as f: + f.writelines(f"{image_id} {score} {p[0]} {p[1]} {p[2]} {p[3]} {p[4]} {p[5]} {p[6]} {p[7]}\n") + # Save merged results, this could result slightly lower map than using official merging script, + # because of the probiou calculation. + pred_merged_txt = self.save_dir / "predictions_merged_txt" # predictions + pred_merged_txt.mkdir(parents=True, exist_ok=True) + merged_results = defaultdict(list) + LOGGER.info(f"Saving merged predictions with DOTA format to {pred_merged_txt}...") + for d in data: + image_id = d["image_id"].split("__")[0] + pattern = re.compile(r"\d+___\d+") + x, y = (int(c) for c in re.findall(pattern, d["image_id"])[0].split("___")) + bbox, score, cls = d["rbox"], d["score"], d["category_id"] + bbox[0] += x + bbox[1] += y + bbox.extend([score, cls]) + merged_results[image_id].append(bbox) + for image_id, bbox in merged_results.items(): + bbox = torch.tensor(bbox) + max_wh = torch.max(bbox[:, :2]).item() * 2 + c = bbox[:, 6:7] * max_wh # classes + scores = bbox[:, 5] # scores + b = bbox[:, :5].clone() + b[:, :2] += c + # 0.3 could get results close to the ones from official merging script, even slightly better. + i = ops.nms_rotated(b, scores, 0.3) + bbox = bbox[i] + + b = ops.xywhr2xyxyxyxy(bbox[:, :5]).view(-1, 8) + for x in torch.cat([b, bbox[:, 5:7]], dim=-1).tolist(): + classname = self.names[int(x[-1])].replace(" ", "-") + p = [round(i, 3) for i in x[:-2]] # poly + score = round(x[-2], 3) + + with open(f'{pred_merged_txt / f"Task1_{classname}"}.txt', "a") as f: + f.writelines(f"{image_id} {score} {p[0]} {p[1]} {p[2]} {p[3]} {p[4]} {p[5]} {p[6]} {p[7]}\n") + + return stats diff --git a/ultralytics/models/yolo/pose/__init__.py b/ultralytics/models/yolo/pose/__init__.py new file mode 100644 index 0000000..d566943 --- /dev/null +++ b/ultralytics/models/yolo/pose/__init__.py @@ -0,0 +1,7 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from .predict import PosePredictor +from .train import PoseTrainer +from .val import PoseValidator + +__all__ = "PoseTrainer", "PoseValidator", "PosePredictor" diff --git a/ultralytics/models/yolo/pose/predict.py b/ultralytics/models/yolo/pose/predict.py new file mode 100644 index 0000000..7c55709 --- /dev/null +++ b/ultralytics/models/yolo/pose/predict.py @@ -0,0 +1,58 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from ultralytics.engine.results import Results +from ultralytics.models.yolo.detect.predict import DetectionPredictor +from ultralytics.utils import DEFAULT_CFG, LOGGER, ops + + +class PosePredictor(DetectionPredictor): + """ + A class extending the DetectionPredictor class for prediction based on a pose model. + + Example: + ```python + from ultralytics.utils import ASSETS + from ultralytics.models.yolo.pose import PosePredictor + + args = dict(model='yolov8n-pose.pt', source=ASSETS) + predictor = PosePredictor(overrides=args) + predictor.predict_cli() + ``` + """ + + def __init__(self, cfg=DEFAULT_CFG, overrides=None, _callbacks=None): + """Initializes PosePredictor, sets task to 'pose' and logs a warning for using 'mps' as device.""" + super().__init__(cfg, overrides, _callbacks) + self.args.task = "pose" + if isinstance(self.args.device, str) and self.args.device.lower() == "mps": + LOGGER.warning( + "WARNING ⚠️ Apple MPS known Pose bug. Recommend 'device=cpu' for Pose models. " + "See https://github.com/ultralytics/ultralytics/issues/4031." + ) + + def postprocess(self, preds, img, orig_imgs): + """Return detection results for a given input image or list of images.""" + preds = ops.non_max_suppression( + preds, + self.args.conf, + self.args.iou, + agnostic=self.args.agnostic_nms, + max_det=self.args.max_det, + classes=self.args.classes, + nc=len(self.model.names), + ) + + if not isinstance(orig_imgs, list): # input images are a torch.Tensor, not a list + orig_imgs = ops.convert_torch2numpy_batch(orig_imgs) + + results = [] + for i, pred in enumerate(preds): + orig_img = orig_imgs[i] + pred[:, :4] = ops.scale_boxes(img.shape[2:], pred[:, :4], orig_img.shape).round() + pred_kpts = pred[:, 6:].view(len(pred), *self.model.kpt_shape) if len(pred) else pred[:, 6:] + pred_kpts = ops.scale_coords(img.shape[2:], pred_kpts, orig_img.shape) + img_path = self.batch[0][i] + results.append( + Results(orig_img, path=img_path, names=self.model.names, boxes=pred[:, :6], keypoints=pred_kpts) + ) + return results diff --git a/ultralytics/models/yolo/pose/train.py b/ultralytics/models/yolo/pose/train.py new file mode 100644 index 0000000..f5229e5 --- /dev/null +++ b/ultralytics/models/yolo/pose/train.py @@ -0,0 +1,79 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from copy import copy + +from ultralytics.models import yolo +from ultralytics.nn.tasks import PoseModel +from ultralytics.utils import DEFAULT_CFG, LOGGER +from ultralytics.utils.plotting import plot_images, plot_results + + +class PoseTrainer(yolo.detect.DetectionTrainer): + """ + A class extending the DetectionTrainer class for training based on a pose model. + + Example: + ```python + from ultralytics.models.yolo.pose import PoseTrainer + + args = dict(model='yolov8n-pose.pt', data='coco8-pose.yaml', epochs=3) + trainer = PoseTrainer(overrides=args) + trainer.train() + ``` + """ + + def __init__(self, cfg=DEFAULT_CFG, overrides=None, _callbacks=None): + """Initialize a PoseTrainer object with specified configurations and overrides.""" + if overrides is None: + overrides = {} + overrides["task"] = "pose" + super().__init__(cfg, overrides, _callbacks) + + if isinstance(self.args.device, str) and self.args.device.lower() == "mps": + LOGGER.warning( + "WARNING ⚠️ Apple MPS known Pose bug. Recommend 'device=cpu' for Pose models. " + "See https://github.com/ultralytics/ultralytics/issues/4031." + ) + + def get_model(self, cfg=None, weights=None, verbose=True): + """Get pose estimation model with specified configuration and weights.""" + model = PoseModel(cfg, ch=3, nc=self.data["nc"], data_kpt_shape=self.data["kpt_shape"], verbose=verbose) + if weights: + model.load(weights) + + return model + + def set_model_attributes(self): + """Sets keypoints shape attribute of PoseModel.""" + super().set_model_attributes() + self.model.kpt_shape = self.data["kpt_shape"] + + def get_validator(self): + """Returns an instance of the PoseValidator class for validation.""" + self.loss_names = "box_loss", "pose_loss", "kobj_loss", "cls_loss", "dfl_loss" + return yolo.pose.PoseValidator( + self.test_loader, save_dir=self.save_dir, args=copy(self.args), _callbacks=self.callbacks + ) + + def plot_training_samples(self, batch, ni): + """Plot a batch of training samples with annotated class labels, bounding boxes, and keypoints.""" + images = batch["img"] + kpts = batch["keypoints"] + cls = batch["cls"].squeeze(-1) + bboxes = batch["bboxes"] + paths = batch["im_file"] + batch_idx = batch["batch_idx"] + plot_images( + images, + batch_idx, + cls, + bboxes, + kpts=kpts, + paths=paths, + fname=self.save_dir / f"train_batch{ni}.jpg", + on_plot=self.on_plot, + ) + + def plot_metrics(self): + """Plots training/val metrics.""" + plot_results(file=self.csv, pose=True, on_plot=self.on_plot) # save results.png diff --git a/ultralytics/models/yolo/pose/val.py b/ultralytics/models/yolo/pose/val.py new file mode 100644 index 0000000..8405686 --- /dev/null +++ b/ultralytics/models/yolo/pose/val.py @@ -0,0 +1,248 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from pathlib import Path + +import numpy as np +import torch + +from ultralytics.models.yolo.detect import DetectionValidator +from ultralytics.utils import LOGGER, ops +from ultralytics.utils.checks import check_requirements +from ultralytics.utils.metrics import OKS_SIGMA, PoseMetrics, box_iou, kpt_iou +from ultralytics.utils.plotting import output_to_target, plot_images + + +class PoseValidator(DetectionValidator): + """ + A class extending the DetectionValidator class for validation based on a pose model. + + Example: + ```python + from ultralytics.models.yolo.pose import PoseValidator + + args = dict(model='yolov8n-pose.pt', data='coco8-pose.yaml') + validator = PoseValidator(args=args) + validator() + ``` + """ + + def __init__(self, dataloader=None, save_dir=None, pbar=None, args=None, _callbacks=None): + """Initialize a 'PoseValidator' object with custom parameters and assigned attributes.""" + super().__init__(dataloader, save_dir, pbar, args, _callbacks) + self.sigma = None + self.kpt_shape = None + self.args.task = "pose" + self.metrics = PoseMetrics(save_dir=self.save_dir, on_plot=self.on_plot) + if isinstance(self.args.device, str) and self.args.device.lower() == "mps": + LOGGER.warning( + "WARNING ⚠️ Apple MPS known Pose bug. Recommend 'device=cpu' for Pose models. " + "See https://github.com/ultralytics/ultralytics/issues/4031." + ) + + def preprocess(self, batch): + """Preprocesses the batch by converting the 'keypoints' data into a float and moving it to the device.""" + batch = super().preprocess(batch) + batch["keypoints"] = batch["keypoints"].to(self.device).float() + return batch + + def get_desc(self): + """Returns description of evaluation metrics in string format.""" + return ("%22s" + "%11s" * 10) % ( + "Class", + "Images", + "Instances", + "Box(P", + "R", + "mAP50", + "mAP50-95)", + "Pose(P", + "R", + "mAP50", + "mAP50-95)", + ) + + def postprocess(self, preds): + """Apply non-maximum suppression and return detections with high confidence scores.""" + return ops.non_max_suppression( + preds, + self.args.conf, + self.args.iou, + labels=self.lb, + multi_label=True, + agnostic=self.args.single_cls, + max_det=self.args.max_det, + nc=self.nc, + ) + + def init_metrics(self, model): + """Initiate pose estimation metrics for YOLO model.""" + super().init_metrics(model) + self.kpt_shape = self.data["kpt_shape"] + is_pose = self.kpt_shape == [17, 3] + nkpt = self.kpt_shape[0] + self.sigma = OKS_SIGMA if is_pose else np.ones(nkpt) / nkpt + self.stats = dict(tp_p=[], tp=[], conf=[], pred_cls=[], target_cls=[]) + + def _prepare_batch(self, si, batch): + """Prepares a batch for processing by converting keypoints to float and moving to device.""" + pbatch = super()._prepare_batch(si, batch) + kpts = batch["keypoints"][batch["batch_idx"] == si] + h, w = pbatch["imgsz"] + kpts = kpts.clone() + kpts[..., 0] *= w + kpts[..., 1] *= h + kpts = ops.scale_coords(pbatch["imgsz"], kpts, pbatch["ori_shape"], ratio_pad=pbatch["ratio_pad"]) + pbatch["kpts"] = kpts + return pbatch + + def _prepare_pred(self, pred, pbatch): + """Prepares and scales keypoints in a batch for pose processing.""" + predn = super()._prepare_pred(pred, pbatch) + nk = pbatch["kpts"].shape[1] + pred_kpts = predn[:, 6:].view(len(predn), nk, -1) + ops.scale_coords(pbatch["imgsz"], pred_kpts, pbatch["ori_shape"], ratio_pad=pbatch["ratio_pad"]) + return predn, pred_kpts + + def update_metrics(self, preds, batch): + """Metrics.""" + for si, pred in enumerate(preds): + self.seen += 1 + npr = len(pred) + stat = dict( + conf=torch.zeros(0, device=self.device), + pred_cls=torch.zeros(0, device=self.device), + tp=torch.zeros(npr, self.niou, dtype=torch.bool, device=self.device), + tp_p=torch.zeros(npr, self.niou, dtype=torch.bool, device=self.device), + ) + pbatch = self._prepare_batch(si, batch) + cls, bbox = pbatch.pop("cls"), pbatch.pop("bbox") + nl = len(cls) + stat["target_cls"] = cls + if npr == 0: + if nl: + for k in self.stats.keys(): + self.stats[k].append(stat[k]) + if self.args.plots: + self.confusion_matrix.process_batch(detections=None, gt_bboxes=bbox, gt_cls=cls) + continue + + # Predictions + if self.args.single_cls: + pred[:, 5] = 0 + predn, pred_kpts = self._prepare_pred(pred, pbatch) + stat["conf"] = predn[:, 4] + stat["pred_cls"] = predn[:, 5] + + # Evaluate + if nl: + stat["tp"] = self._process_batch(predn, bbox, cls) + stat["tp_p"] = self._process_batch(predn, bbox, cls, pred_kpts, pbatch["kpts"]) + if self.args.plots: + self.confusion_matrix.process_batch(predn, bbox, cls) + + for k in self.stats.keys(): + self.stats[k].append(stat[k]) + + # Save + if self.args.save_json: + self.pred_to_json(predn, batch["im_file"][si]) + # if self.args.save_txt: + # save_one_txt(predn, save_conf, shape, file=save_dir / 'labels' / f'{path.stem}.txt') + + def _process_batch(self, detections, gt_bboxes, gt_cls, pred_kpts=None, gt_kpts=None): + """ + Return correct prediction matrix. + + Args: + detections (torch.Tensor): Tensor of shape [N, 6] representing detections. + Each detection is of the format: x1, y1, x2, y2, conf, class. + labels (torch.Tensor): Tensor of shape [M, 5] representing labels. + Each label is of the format: class, x1, y1, x2, y2. + pred_kpts (torch.Tensor, optional): Tensor of shape [N, 51] representing predicted keypoints. + 51 corresponds to 17 keypoints each with 3 values. + gt_kpts (torch.Tensor, optional): Tensor of shape [N, 51] representing ground truth keypoints. + + Returns: + torch.Tensor: Correct prediction matrix of shape [N, 10] for 10 IoU levels. + """ + if pred_kpts is not None and gt_kpts is not None: + # `0.53` is from https://github.com/jin-s13/xtcocoapi/blob/master/xtcocotools/cocoeval.py#L384 + area = ops.xyxy2xywh(gt_bboxes)[:, 2:].prod(1) * 0.53 + iou = kpt_iou(gt_kpts, pred_kpts, sigma=self.sigma, area=area) + else: # boxes + iou = box_iou(gt_bboxes, detections[:, :4]) + + return self.match_predictions(detections[:, 5], gt_cls, iou) + + def plot_val_samples(self, batch, ni): + """Plots and saves validation set samples with predicted bounding boxes and keypoints.""" + plot_images( + batch["img"], + batch["batch_idx"], + batch["cls"].squeeze(-1), + batch["bboxes"], + kpts=batch["keypoints"], + paths=batch["im_file"], + fname=self.save_dir / f"val_batch{ni}_labels.jpg", + names=self.names, + on_plot=self.on_plot, + ) + + def plot_predictions(self, batch, preds, ni): + """Plots predictions for YOLO model.""" + pred_kpts = torch.cat([p[:, 6:].view(-1, *self.kpt_shape) for p in preds], 0) + plot_images( + batch["img"], + *output_to_target(preds, max_det=self.args.max_det), + kpts=pred_kpts, + paths=batch["im_file"], + fname=self.save_dir / f"val_batch{ni}_pred.jpg", + names=self.names, + on_plot=self.on_plot, + ) # pred + + def pred_to_json(self, predn, filename): + """Converts YOLO predictions to COCO JSON format.""" + stem = Path(filename).stem + image_id = int(stem) if stem.isnumeric() else stem + box = ops.xyxy2xywh(predn[:, :4]) # xywh + box[:, :2] -= box[:, 2:] / 2 # xy center to top-left corner + for p, b in zip(predn.tolist(), box.tolist()): + self.jdict.append( + { + "image_id": image_id, + "category_id": self.class_map[int(p[5])], + "bbox": [round(x, 3) for x in b], + "keypoints": p[6:], + "score": round(p[4], 5), + } + ) + + def eval_json(self, stats): + """Evaluates object detection model using COCO JSON format.""" + if self.args.save_json and self.is_coco and len(self.jdict): + anno_json = self.data["path"] / "annotations/person_keypoints_val2017.json" # annotations + pred_json = self.save_dir / "predictions.json" # predictions + LOGGER.info(f"\nEvaluating pycocotools mAP using {pred_json} and {anno_json}...") + try: # https://github.com/cocodataset/cocoapi/blob/master/PythonAPI/pycocoEvalDemo.ipynb + check_requirements("pycocotools>=2.0.6") + from pycocotools.coco import COCO # noqa + from pycocotools.cocoeval import COCOeval # noqa + + for x in anno_json, pred_json: + assert x.is_file(), f"{x} file not found" + anno = COCO(str(anno_json)) # init annotations api + pred = anno.loadRes(str(pred_json)) # init predictions api (must pass string, not Path) + for i, eval in enumerate([COCOeval(anno, pred, "bbox"), COCOeval(anno, pred, "keypoints")]): + if self.is_coco: + eval.params.imgIds = [int(Path(x).stem) for x in self.dataloader.dataset.im_files] # im to eval + eval.evaluate() + eval.accumulate() + eval.summarize() + idx = i * 4 + 2 + stats[self.metrics.keys[idx + 1]], stats[self.metrics.keys[idx]] = eval.stats[ + :2 + ] # update mAP50-95 and mAP50 + except Exception as e: + LOGGER.warning(f"pycocotools unable to run: {e}") + return stats diff --git a/ultralytics/models/yolo/segment/__init__.py b/ultralytics/models/yolo/segment/__init__.py new file mode 100644 index 0000000..ec1ac79 --- /dev/null +++ b/ultralytics/models/yolo/segment/__init__.py @@ -0,0 +1,7 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from .predict import SegmentationPredictor +from .train import SegmentationTrainer +from .val import SegmentationValidator + +__all__ = "SegmentationPredictor", "SegmentationTrainer", "SegmentationValidator" diff --git a/ultralytics/models/yolo/segment/predict.py b/ultralytics/models/yolo/segment/predict.py new file mode 100644 index 0000000..9d7015f --- /dev/null +++ b/ultralytics/models/yolo/segment/predict.py @@ -0,0 +1,57 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from ultralytics.engine.results import Results +from ultralytics.models.yolo.detect.predict import DetectionPredictor +from ultralytics.utils import DEFAULT_CFG, ops + + +class SegmentationPredictor(DetectionPredictor): + """ + A class extending the DetectionPredictor class for prediction based on a segmentation model. + + Example: + ```python + from ultralytics.utils import ASSETS + from ultralytics.models.yolo.segment import SegmentationPredictor + + args = dict(model='yolov8n-seg.pt', source=ASSETS) + predictor = SegmentationPredictor(overrides=args) + predictor.predict_cli() + ``` + """ + + def __init__(self, cfg=DEFAULT_CFG, overrides=None, _callbacks=None): + """Initializes the SegmentationPredictor with the provided configuration, overrides, and callbacks.""" + super().__init__(cfg, overrides, _callbacks) + self.args.task = "segment" + + def postprocess(self, preds, img, orig_imgs): + """Applies non-max suppression and processes detections for each image in an input batch.""" + p = ops.non_max_suppression( + preds[0], + self.args.conf, + self.args.iou, + agnostic=self.args.agnostic_nms, + max_det=self.args.max_det, + nc=len(self.model.names), + classes=self.args.classes, + ) + + if not isinstance(orig_imgs, list): # input images are a torch.Tensor, not a list + orig_imgs = ops.convert_torch2numpy_batch(orig_imgs) + + results = [] + proto = preds[1][-1] if isinstance(preds[1], tuple) else preds[1] # tuple if PyTorch model or array if exported + for i, pred in enumerate(p): + orig_img = orig_imgs[i] + img_path = self.batch[0][i] + if not len(pred): # save empty boxes + masks = None + elif self.args.retina_masks: + pred[:, :4] = ops.scale_boxes(img.shape[2:], pred[:, :4], orig_img.shape) + masks = ops.process_mask_native(proto[i], pred[:, 6:], pred[:, :4], orig_img.shape[:2]) # HWC + else: + masks = ops.process_mask(proto[i], pred[:, 6:], pred[:, :4], img.shape[2:], upsample=True) # HWC + pred[:, :4] = ops.scale_boxes(img.shape[2:], pred[:, :4], orig_img.shape) + results.append(Results(orig_img, path=img_path, names=self.model.names, boxes=pred[:, :6], masks=masks)) + return results diff --git a/ultralytics/models/yolo/segment/train.py b/ultralytics/models/yolo/segment/train.py new file mode 100644 index 0000000..126baf2 --- /dev/null +++ b/ultralytics/models/yolo/segment/train.py @@ -0,0 +1,62 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from copy import copy + +from ultralytics.models import yolo +from ultralytics.nn.tasks import SegmentationModel +from ultralytics.utils import DEFAULT_CFG, RANK +from ultralytics.utils.plotting import plot_images, plot_results + + +class SegmentationTrainer(yolo.detect.DetectionTrainer): + """ + A class extending the DetectionTrainer class for training based on a segmentation model. + + Example: + ```python + from ultralytics.models.yolo.segment import SegmentationTrainer + + args = dict(model='yolov8n-seg.pt', data='coco8-seg.yaml', epochs=3) + trainer = SegmentationTrainer(overrides=args) + trainer.train() + ``` + """ + + def __init__(self, cfg=DEFAULT_CFG, overrides=None, _callbacks=None): + """Initialize a SegmentationTrainer object with given arguments.""" + if overrides is None: + overrides = {} + overrides["task"] = "segment" + super().__init__(cfg, overrides, _callbacks) + + def get_model(self, cfg=None, weights=None, verbose=True): + """Return SegmentationModel initialized with specified config and weights.""" + model = SegmentationModel(cfg, ch=3, nc=self.data["nc"], verbose=verbose and RANK == -1) + if weights: + model.load(weights) + + return model + + def get_validator(self): + """Return an instance of SegmentationValidator for validation of YOLO model.""" + self.loss_names = "box_loss", "seg_loss", "cls_loss", "dfl_loss" + return yolo.segment.SegmentationValidator( + self.test_loader, save_dir=self.save_dir, args=copy(self.args), _callbacks=self.callbacks + ) + + def plot_training_samples(self, batch, ni): + """Creates a plot of training sample images with labels and box coordinates.""" + plot_images( + batch["img"], + batch["batch_idx"], + batch["cls"].squeeze(-1), + batch["bboxes"], + masks=batch["masks"], + paths=batch["im_file"], + fname=self.save_dir / f"train_batch{ni}.jpg", + on_plot=self.on_plot, + ) + + def plot_metrics(self): + """Plots training/val metrics.""" + plot_results(file=self.csv, segment=True, on_plot=self.on_plot) # save results.png diff --git a/ultralytics/models/yolo/segment/val.py b/ultralytics/models/yolo/segment/val.py new file mode 100644 index 0000000..94757c4 --- /dev/null +++ b/ultralytics/models/yolo/segment/val.py @@ -0,0 +1,277 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from multiprocessing.pool import ThreadPool +from pathlib import Path + +import numpy as np +import torch +import torch.nn.functional as F + +from ultralytics.models.yolo.detect import DetectionValidator +from ultralytics.utils import LOGGER, NUM_THREADS, ops +from ultralytics.utils.checks import check_requirements +from ultralytics.utils.metrics import SegmentMetrics, box_iou, mask_iou +from ultralytics.utils.plotting import output_to_target, plot_images + + +class SegmentationValidator(DetectionValidator): + """ + A class extending the DetectionValidator class for validation based on a segmentation model. + + Example: + ```python + from ultralytics.models.yolo.segment import SegmentationValidator + + args = dict(model='yolov8n-seg.pt', data='coco8-seg.yaml') + validator = SegmentationValidator(args=args) + validator() + ``` + """ + + def __init__(self, dataloader=None, save_dir=None, pbar=None, args=None, _callbacks=None): + """Initialize SegmentationValidator and set task to 'segment', metrics to SegmentMetrics.""" + super().__init__(dataloader, save_dir, pbar, args, _callbacks) + self.plot_masks = None + self.process = None + self.args.task = "segment" + self.metrics = SegmentMetrics(save_dir=self.save_dir, on_plot=self.on_plot) + + def preprocess(self, batch): + """Preprocesses batch by converting masks to float and sending to device.""" + batch = super().preprocess(batch) + batch["masks"] = batch["masks"].to(self.device).float() + return batch + + def init_metrics(self, model): + """Initialize metrics and select mask processing function based on save_json flag.""" + super().init_metrics(model) + self.plot_masks = [] + if self.args.save_json: + check_requirements("pycocotools>=2.0.6") + self.process = ops.process_mask_upsample # more accurate + else: + self.process = ops.process_mask # faster + self.stats = dict(tp_m=[], tp=[], conf=[], pred_cls=[], target_cls=[]) + + def get_desc(self): + """Return a formatted description of evaluation metrics.""" + return ("%22s" + "%11s" * 10) % ( + "Class", + "Images", + "Instances", + "Box(P", + "R", + "mAP50", + "mAP50-95)", + "Mask(P", + "R", + "mAP50", + "mAP50-95)", + ) + + def postprocess(self, preds): + """Post-processes YOLO predictions and returns output detections with proto.""" + p = ops.non_max_suppression( + preds[0], + self.args.conf, + self.args.iou, + labels=self.lb, + multi_label=True, + agnostic=self.args.single_cls, + max_det=self.args.max_det, + nc=self.nc, + ) + proto = preds[1][-1] if len(preds[1]) == 3 else preds[1] # second output is len 3 if pt, but only 1 if exported + return p, proto + + def _prepare_batch(self, si, batch): + """Prepares a batch for training or inference by processing images and targets.""" + prepared_batch = super()._prepare_batch(si, batch) + midx = [si] if self.args.overlap_mask else batch["batch_idx"] == si + prepared_batch["masks"] = batch["masks"][midx] + return prepared_batch + + def _prepare_pred(self, pred, pbatch, proto): + """Prepares a batch for training or inference by processing images and targets.""" + predn = super()._prepare_pred(pred, pbatch) + pred_masks = self.process(proto, pred[:, 6:], pred[:, :4], shape=pbatch["imgsz"]) + return predn, pred_masks + + def update_metrics(self, preds, batch): + """Metrics.""" + for si, (pred, proto) in enumerate(zip(preds[0], preds[1])): + self.seen += 1 + npr = len(pred) + stat = dict( + conf=torch.zeros(0, device=self.device), + pred_cls=torch.zeros(0, device=self.device), + tp=torch.zeros(npr, self.niou, dtype=torch.bool, device=self.device), + tp_m=torch.zeros(npr, self.niou, dtype=torch.bool, device=self.device), + ) + pbatch = self._prepare_batch(si, batch) + cls, bbox = pbatch.pop("cls"), pbatch.pop("bbox") + nl = len(cls) + stat["target_cls"] = cls + if npr == 0: + if nl: + for k in self.stats.keys(): + self.stats[k].append(stat[k]) + if self.args.plots: + self.confusion_matrix.process_batch(detections=None, gt_bboxes=bbox, gt_cls=cls) + continue + + # Masks + gt_masks = pbatch.pop("masks") + # Predictions + if self.args.single_cls: + pred[:, 5] = 0 + predn, pred_masks = self._prepare_pred(pred, pbatch, proto) + stat["conf"] = predn[:, 4] + stat["pred_cls"] = predn[:, 5] + + # Evaluate + if nl: + stat["tp"] = self._process_batch(predn, bbox, cls) + stat["tp_m"] = self._process_batch( + predn, bbox, cls, pred_masks, gt_masks, self.args.overlap_mask, masks=True + ) + if self.args.plots: + self.confusion_matrix.process_batch(predn, bbox, cls) + + for k in self.stats.keys(): + self.stats[k].append(stat[k]) + + pred_masks = torch.as_tensor(pred_masks, dtype=torch.uint8) + if self.args.plots and self.batch_i < 3: + self.plot_masks.append(pred_masks[:15].cpu()) # filter top 15 to plot + + # Save + if self.args.save_json: + pred_masks = ops.scale_image( + pred_masks.permute(1, 2, 0).contiguous().cpu().numpy(), + pbatch["ori_shape"], + ratio_pad=batch["ratio_pad"][si], + ) + self.pred_to_json(predn, batch["im_file"][si], pred_masks) + # if self.args.save_txt: + # save_one_txt(predn, save_conf, shape, file=save_dir / 'labels' / f'{path.stem}.txt') + + def finalize_metrics(self, *args, **kwargs): + """Sets speed and confusion matrix for evaluation metrics.""" + self.metrics.speed = self.speed + self.metrics.confusion_matrix = self.confusion_matrix + + def _process_batch(self, detections, gt_bboxes, gt_cls, pred_masks=None, gt_masks=None, overlap=False, masks=False): + """ + Return correct prediction matrix. + + Args: + detections (array[N, 6]), x1, y1, x2, y2, conf, class + labels (array[M, 5]), class, x1, y1, x2, y2 + + Returns: + correct (array[N, 10]), for 10 IoU levels + """ + if masks: + if overlap: + nl = len(gt_cls) + index = torch.arange(nl, device=gt_masks.device).view(nl, 1, 1) + 1 + gt_masks = gt_masks.repeat(nl, 1, 1) # shape(1,640,640) -> (n,640,640) + gt_masks = torch.where(gt_masks == index, 1.0, 0.0) + if gt_masks.shape[1:] != pred_masks.shape[1:]: + gt_masks = F.interpolate(gt_masks[None], pred_masks.shape[1:], mode="bilinear", align_corners=False)[0] + gt_masks = gt_masks.gt_(0.5) + iou = mask_iou(gt_masks.view(gt_masks.shape[0], -1), pred_masks.view(pred_masks.shape[0], -1)) + else: # boxes + iou = box_iou(gt_bboxes, detections[:, :4]) + + return self.match_predictions(detections[:, 5], gt_cls, iou) + + def plot_val_samples(self, batch, ni): + """Plots validation samples with bounding box labels.""" + plot_images( + batch["img"], + batch["batch_idx"], + batch["cls"].squeeze(-1), + batch["bboxes"], + masks=batch["masks"], + paths=batch["im_file"], + fname=self.save_dir / f"val_batch{ni}_labels.jpg", + names=self.names, + on_plot=self.on_plot, + ) + + def plot_predictions(self, batch, preds, ni): + """Plots batch predictions with masks and bounding boxes.""" + plot_images( + batch["img"], + *output_to_target(preds[0], max_det=15), # not set to self.args.max_det due to slow plotting speed + torch.cat(self.plot_masks, dim=0) if len(self.plot_masks) else self.plot_masks, + paths=batch["im_file"], + fname=self.save_dir / f"val_batch{ni}_pred.jpg", + names=self.names, + on_plot=self.on_plot, + ) # pred + self.plot_masks.clear() + + def pred_to_json(self, predn, filename, pred_masks): + """ + Save one JSON result. + + Examples: + >>> result = {"image_id": 42, "category_id": 18, "bbox": [258.15, 41.29, 348.26, 243.78], "score": 0.236} + """ + from pycocotools.mask import encode # noqa + + def single_encode(x): + """Encode predicted masks as RLE and append results to jdict.""" + rle = encode(np.asarray(x[:, :, None], order="F", dtype="uint8"))[0] + rle["counts"] = rle["counts"].decode("utf-8") + return rle + + stem = Path(filename).stem + image_id = int(stem) if stem.isnumeric() else stem + box = ops.xyxy2xywh(predn[:, :4]) # xywh + box[:, :2] -= box[:, 2:] / 2 # xy center to top-left corner + pred_masks = np.transpose(pred_masks, (2, 0, 1)) + with ThreadPool(NUM_THREADS) as pool: + rles = pool.map(single_encode, pred_masks) + for i, (p, b) in enumerate(zip(predn.tolist(), box.tolist())): + self.jdict.append( + { + "image_id": image_id, + "category_id": self.class_map[int(p[5])], + "bbox": [round(x, 3) for x in b], + "score": round(p[4], 5), + "segmentation": rles[i], + } + ) + + def eval_json(self, stats): + """Return COCO-style object detection evaluation metrics.""" + if self.args.save_json and self.is_coco and len(self.jdict): + anno_json = self.data["path"] / "annotations/instances_val2017.json" # annotations + pred_json = self.save_dir / "predictions.json" # predictions + LOGGER.info(f"\nEvaluating pycocotools mAP using {pred_json} and {anno_json}...") + try: # https://github.com/cocodataset/cocoapi/blob/master/PythonAPI/pycocoEvalDemo.ipynb + check_requirements("pycocotools>=2.0.6") + from pycocotools.coco import COCO # noqa + from pycocotools.cocoeval import COCOeval # noqa + + for x in anno_json, pred_json: + assert x.is_file(), f"{x} file not found" + anno = COCO(str(anno_json)) # init annotations api + pred = anno.loadRes(str(pred_json)) # init predictions api (must pass string, not Path) + for i, eval in enumerate([COCOeval(anno, pred, "bbox"), COCOeval(anno, pred, "segm")]): + if self.is_coco: + eval.params.imgIds = [int(Path(x).stem) for x in self.dataloader.dataset.im_files] # im to eval + eval.evaluate() + eval.accumulate() + eval.summarize() + idx = i * 4 + 2 + stats[self.metrics.keys[idx + 1]], stats[self.metrics.keys[idx]] = eval.stats[ + :2 + ] # update mAP50-95 and mAP50 + except Exception as e: + LOGGER.warning(f"pycocotools unable to run: {e}") + return stats diff --git a/ultralytics/models/yolo/world/__init__.py b/ultralytics/models/yolo/world/__init__.py new file mode 100644 index 0000000..1d40199 --- /dev/null +++ b/ultralytics/models/yolo/world/__init__.py @@ -0,0 +1,5 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from .train import WorldTrainer + +__all__ = ["WorldTrainer"] diff --git a/ultralytics/models/yolo/world/train.py b/ultralytics/models/yolo/world/train.py new file mode 100644 index 0000000..12d9b43 --- /dev/null +++ b/ultralytics/models/yolo/world/train.py @@ -0,0 +1,92 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import itertools + +from ultralytics.data import build_yolo_dataset +from ultralytics.models import yolo +from ultralytics.nn.tasks import WorldModel +from ultralytics.utils import DEFAULT_CFG, RANK, checks +from ultralytics.utils.torch_utils import de_parallel + + +def on_pretrain_routine_end(trainer): + """Callback.""" + if RANK in {-1, 0}: + # NOTE: for evaluation + names = [name.split("/")[0] for name in list(trainer.test_loader.dataset.data["names"].values())] + de_parallel(trainer.ema.ema).set_classes(names, cache_clip_model=False) + device = next(trainer.model.parameters()).device + trainer.text_model, _ = trainer.clip.load("ViT-B/32", device=device) + for p in trainer.text_model.parameters(): + p.requires_grad_(False) + + +class WorldTrainer(yolo.detect.DetectionTrainer): + """ + A class to fine-tune a world model on a close-set dataset. + + Example: + ```python + from ultralytics.models.yolo.world import WorldModel + + args = dict(model='yolov8s-world.pt', data='coco8.yaml', epochs=3) + trainer = WorldTrainer(overrides=args) + trainer.train() + ``` + """ + + def __init__(self, cfg=DEFAULT_CFG, overrides=None, _callbacks=None): + """Initialize a WorldTrainer object with given arguments.""" + if overrides is None: + overrides = {} + super().__init__(cfg, overrides, _callbacks) + + # Import and assign clip + try: + import clip + except ImportError: + checks.check_requirements("git+https://github.com/ultralytics/CLIP.git") + import clip + self.clip = clip + + def get_model(self, cfg=None, weights=None, verbose=True): + """Return WorldModel initialized with specified config and weights.""" + # NOTE: This `nc` here is the max number of different text samples in one image, rather than the actual `nc`. + # NOTE: Following the official config, nc hard-coded to 80 for now. + model = WorldModel( + cfg["yaml_file"] if isinstance(cfg, dict) else cfg, + ch=3, + nc=min(self.data["nc"], 80), + verbose=verbose and RANK == -1, + ) + if weights: + model.load(weights) + self.add_callback("on_pretrain_routine_end", on_pretrain_routine_end) + + return model + + def build_dataset(self, img_path, mode="train", batch=None): + """ + Build YOLO Dataset. + + Args: + img_path (str): Path to the folder containing images. + mode (str): `train` mode or `val` mode, users are able to customize different augmentations for each mode. + batch (int, optional): Size of batches, this is for `rect`. Defaults to None. + """ + gs = max(int(de_parallel(self.model).stride.max() if self.model else 0), 32) + return build_yolo_dataset( + self.args, img_path, batch, self.data, mode=mode, rect=mode == "val", stride=gs, multi_modal=mode == "train" + ) + + def preprocess_batch(self, batch): + """Preprocesses a batch of images for YOLOWorld training, adjusting formatting and dimensions as needed.""" + batch = super().preprocess_batch(batch) + + # NOTE: add text features + texts = list(itertools.chain(*batch["texts"])) + text_token = self.clip.tokenize(texts).to(batch["img"].device) + txt_feats = self.text_model.encode_text(text_token).to(dtype=batch["img"].dtype) # torch.float32 + txt_feats = txt_feats / txt_feats.norm(p=2, dim=-1, keepdim=True) + batch["txt_feats"] = txt_feats.reshape(len(batch["texts"]), -1, txt_feats.shape[-1]) + return batch diff --git a/ultralytics/models/yolo/world/train_world.py b/ultralytics/models/yolo/world/train_world.py new file mode 100644 index 0000000..d6836ca --- /dev/null +++ b/ultralytics/models/yolo/world/train_world.py @@ -0,0 +1,108 @@ +from ultralytics.data import YOLOConcatDataset, build_grounding, build_yolo_dataset +from ultralytics.data.utils import check_det_dataset +from ultralytics.models.yolo.world import WorldTrainer +from ultralytics.utils import DEFAULT_CFG +from ultralytics.utils.torch_utils import de_parallel + + +class WorldTrainerFromScratch(WorldTrainer): + """ + A class extending the WorldTrainer class for training a world model from scratch on open-set dataset. + + Example: + ```python + from ultralytics.models.yolo.world.train_world import WorldTrainerFromScratch + from ultralytics import YOLOWorld + + data = dict( + train=dict( + yolo_data=["Objects365.yaml"], + grounding_data=[ + dict( + img_path="../datasets/flickr30k/images", + json_file="../datasets/flickr30k/final_flickr_separateGT_train.json", + ), + dict( + img_path="../datasets/GQA/images", + json_file="../datasets/GQA/final_mixed_train_no_coco.json", + ), + ], + ), + val=dict(yolo_data=["lvis.yaml"]), + ) + + model = YOLOWorld("yolov8s-worldv2.yaml") + model.train(data=data, trainer=WorldTrainerFromScratch) + ``` + """ + + def __init__(self, cfg=DEFAULT_CFG, overrides=None, _callbacks=None): + """Initialize a WorldTrainer object with given arguments.""" + if overrides is None: + overrides = {} + super().__init__(cfg, overrides, _callbacks) + + def build_dataset(self, img_path, mode="train", batch=None): + """ + Build YOLO Dataset. + + Args: + img_path (List[str] | str): Path to the folder containing images. + mode (str): `train` mode or `val` mode, users are able to customize different augmentations for each mode. + batch (int, optional): Size of batches, this is for `rect`. Defaults to None. + """ + gs = max(int(de_parallel(self.model).stride.max() if self.model else 0), 32) + if mode == "train": + dataset = [ + build_yolo_dataset(self.args, im_path, batch, self.data, stride=gs, multi_modal=True) + if isinstance(im_path, str) + else build_grounding(self.args, im_path["img_path"], im_path["json_file"], batch, stride=gs) + for im_path in img_path + ] + return YOLOConcatDataset(dataset) if len(dataset) > 1 else dataset[0] + else: + return build_yolo_dataset(self.args, img_path, batch, self.data, mode=mode, rect=mode == "val", stride=gs) + + def get_dataset(self): + """ + Get train, val path from data dict if it exists. + + Returns None if data format is not recognized. + """ + final_data = dict() + data_yaml = self.args.data + assert data_yaml.get("train", False) # object365.yaml + assert data_yaml.get("val", False) # lvis.yaml + data = {k: [check_det_dataset(d) for d in v.get("yolo_data", [])] for k, v in data_yaml.items()} + assert len(data["val"]) == 1, f"Only support validating on 1 dataset for now, but got {len(data['val'])}." + val_split = "minival" if "lvis" in data["val"][0]["val"] else "val" + for d in data["val"]: + if d.get("minival") is None: # for lvis dataset + continue + d["minival"] = str(d["path"] / d["minival"]) + for s in ["train", "val"]: + final_data[s] = [d["train" if s == "train" else val_split] for d in data[s]] + # save grounding data if there's one + grounding_data = data_yaml[s].get("grounding_data") + if grounding_data is None: + continue + grounding_data = [grounding_data] if not isinstance(grounding_data, list) else grounding_data + for g in grounding_data: + assert isinstance(g, dict), f"Grounding data should be provided in dict format, but got {type(g)}" + final_data[s] += grounding_data + # NOTE: to make training work properly, set `nc` and `names` + final_data["nc"] = data["val"][0]["nc"] + final_data["names"] = data["val"][0]["names"] + self.data = final_data + return final_data["train"], final_data["val"][0] + + def plot_training_labels(self): + """DO NOT plot labels.""" + pass + + def final_eval(self): + """Performs final evaluation and validation for object detection YOLO-World model.""" + val = self.args.data["val"]["yolo_data"][0] + self.validator.args.data = val + self.validator.args.split = "minival" if isinstance(val, str) and "lvis" in val else "val" + return super().final_eval() diff --git a/ultralytics/nn/__init__.py b/ultralytics/nn/__init__.py new file mode 100644 index 0000000..6905d34 --- /dev/null +++ b/ultralytics/nn/__init__.py @@ -0,0 +1,29 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from .tasks import ( + BaseModel, + ClassificationModel, + DetectionModel, + SegmentationModel, + attempt_load_one_weight, + attempt_load_weights, + guess_model_scale, + guess_model_task, + parse_model, + torch_safe_load, + yaml_model_load, +) + +__all__ = ( + "attempt_load_one_weight", + "attempt_load_weights", + "parse_model", + "yaml_model_load", + "guess_model_task", + "guess_model_scale", + "torch_safe_load", + "DetectionModel", + "SegmentationModel", + "ClassificationModel", + "BaseModel", +) diff --git a/ultralytics/nn/autobackend.py b/ultralytics/nn/autobackend.py new file mode 100644 index 0000000..788c725 --- /dev/null +++ b/ultralytics/nn/autobackend.py @@ -0,0 +1,653 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import ast +import contextlib +import json +import platform +import zipfile +from collections import OrderedDict, namedtuple +from pathlib import Path + +import cv2 +import numpy as np +import torch +import torch.nn as nn +from PIL import Image + +from ultralytics.utils import ARM64, LINUX, LOGGER, ROOT, yaml_load +from ultralytics.utils.checks import check_requirements, check_suffix, check_version, check_yaml +from ultralytics.utils.downloads import attempt_download_asset, is_url + + +def check_class_names(names): + """ + Check class names. + + Map imagenet class codes to human-readable names if required. Convert lists to dicts. + """ + if isinstance(names, list): # names is a list + names = dict(enumerate(names)) # convert to dict + if isinstance(names, dict): + # Convert 1) string keys to int, i.e. '0' to 0, and non-string values to strings, i.e. True to 'True' + names = {int(k): str(v) for k, v in names.items()} + n = len(names) + if max(names.keys()) >= n: + raise KeyError( + f"{n}-class dataset requires class indices 0-{n - 1}, but you have invalid class indices " + f"{min(names.keys())}-{max(names.keys())} defined in your dataset YAML." + ) + if isinstance(names[0], str) and names[0].startswith("n0"): # imagenet class codes, i.e. 'n01440764' + names_map = yaml_load(ROOT / "cfg/datasets/ImageNet.yaml")["map"] # human-readable names + names = {k: names_map[v] for k, v in names.items()} + return names + + +def default_class_names(data=None): + """Applies default class names to an input YAML file or returns numerical class names.""" + if data: + with contextlib.suppress(Exception): + return yaml_load(check_yaml(data))["names"] + return {i: f"class{i}" for i in range(999)} # return default if above errors + + +class AutoBackend(nn.Module): + """ + Handles dynamic backend selection for running inference using Ultralytics YOLO models. + + The AutoBackend class is designed to provide an abstraction layer for various inference engines. It supports a wide + range of formats, each with specific naming conventions as outlined below: + + Supported Formats and Naming Conventions: + | Format | File Suffix | + |-----------------------|------------------| + | PyTorch | *.pt | + | TorchScript | *.torchscript | + | ONNX Runtime | *.onnx | + | ONNX OpenCV DNN | *.onnx (dnn=True)| + | OpenVINO | *openvino_model/ | + | CoreML | *.mlpackage | + | TensorRT | *.engine | + | TensorFlow SavedModel | *_saved_model | + | TensorFlow GraphDef | *.pb | + | TensorFlow Lite | *.tflite | + | TensorFlow Edge TPU | *_edgetpu.tflite | + | PaddlePaddle | *_paddle_model | + | NCNN | *_ncnn_model | + + This class offers dynamic backend switching capabilities based on the input model format, making it easier to deploy + models across various platforms. + """ + + @torch.no_grad() + def __init__( + self, + weights="yolov8n.pt", + device=torch.device("cpu"), + dnn=False, + data=None, + fp16=False, + batch=1, + fuse=True, + verbose=True, + ): + """ + Initialize the AutoBackend for inference. + + Args: + weights (str): Path to the model weights file. Defaults to 'yolov8n.pt'. + device (torch.device): Device to run the model on. Defaults to CPU. + dnn (bool): Use OpenCV DNN module for ONNX inference. Defaults to False. + data (str | Path | optional): Path to the additional data.yaml file containing class names. Optional. + fp16 (bool): Enable half-precision inference. Supported only on specific backends. Defaults to False. + batch (int): Batch-size to assume for inference. + fuse (bool): Fuse Conv2D + BatchNorm layers for optimization. Defaults to True. + verbose (bool): Enable verbose logging. Defaults to True. + """ + super().__init__() + w = str(weights[0] if isinstance(weights, list) else weights) + nn_module = isinstance(weights, torch.nn.Module) + ( + pt, + jit, + onnx, + xml, + engine, + coreml, + saved_model, + pb, + tflite, + edgetpu, + tfjs, + paddle, + ncnn, + triton, + ) = self._model_type(w) + fp16 &= pt or jit or onnx or xml or engine or nn_module or triton # FP16 + nhwc = coreml or saved_model or pb or tflite or edgetpu # BHWC formats (vs torch BCWH) + stride = 32 # default stride + model, metadata = None, None + + # Set device + cuda = torch.cuda.is_available() and device.type != "cpu" # use CUDA + if cuda and not any([nn_module, pt, jit, engine, onnx]): # GPU dataloader formats + device = torch.device("cpu") + cuda = False + + # Download if not local + if not (pt or triton or nn_module): + w = attempt_download_asset(w) + + # In-memory PyTorch model + if nn_module: + model = weights.to(device) + if fuse: + model = model.fuse(verbose=verbose) + if hasattr(model, "kpt_shape"): + kpt_shape = model.kpt_shape # pose-only + stride = max(int(model.stride.max()), 32) # model stride + names = model.module.names if hasattr(model, "module") else model.names # get class names + model.half() if fp16 else model.float() + self.model = model # explicitly assign for to(), cpu(), cuda(), half() + pt = True + + # PyTorch + elif pt: + from ultralytics.nn.tasks import attempt_load_weights + + model = attempt_load_weights( + weights if isinstance(weights, list) else w, device=device, inplace=True, fuse=fuse + ) + if hasattr(model, "kpt_shape"): + kpt_shape = model.kpt_shape # pose-only + stride = max(int(model.stride.max()), 32) # model stride + names = model.module.names if hasattr(model, "module") else model.names # get class names + model.half() if fp16 else model.float() + self.model = model # explicitly assign for to(), cpu(), cuda(), half() + + # TorchScript + elif jit: + LOGGER.info(f"Loading {w} for TorchScript inference...") + extra_files = {"config.txt": ""} # model metadata + model = torch.jit.load(w, _extra_files=extra_files, map_location=device) + model.half() if fp16 else model.float() + if extra_files["config.txt"]: # load metadata dict + metadata = json.loads(extra_files["config.txt"], object_hook=lambda x: dict(x.items())) + + # ONNX OpenCV DNN + elif dnn: + LOGGER.info(f"Loading {w} for ONNX OpenCV DNN inference...") + # check_requirements("opencv-python>=4.5.4") + net = cv2.dnn.readNetFromONNX(w) + + # ONNX Runtime + elif onnx: + LOGGER.info(f"Loading {w} for ONNX Runtime inference...") + check_requirements(("onnx", "onnxruntime-gpu" if cuda else "onnxruntime")) + import onnxruntime + + providers = ["CUDAExecutionProvider", "CPUExecutionProvider"] if cuda else ["CPUExecutionProvider"] + session = onnxruntime.InferenceSession(w, providers=providers) + output_names = [x.name for x in session.get_outputs()] + metadata = session.get_modelmeta().custom_metadata_map + + # OpenVINO + elif xml: + LOGGER.info(f"Loading {w} for OpenVINO inference...") + check_requirements("openvino>=2024.0.0") + import openvino as ov + + core = ov.Core() + w = Path(w) + if not w.is_file(): # if not *.xml + w = next(w.glob("*.xml")) # get *.xml file from *_openvino_model dir + ov_model = core.read_model(model=str(w), weights=w.with_suffix(".bin")) + if ov_model.get_parameters()[0].get_layout().empty: + ov_model.get_parameters()[0].set_layout(ov.Layout("NCHW")) + + # OpenVINO inference modes are 'LATENCY', 'THROUGHPUT' (not recommended), or 'CUMULATIVE_THROUGHPUT' + inference_mode = "CUMULATIVE_THROUGHPUT" if batch > 1 else "LATENCY" + LOGGER.info(f"Using OpenVINO {inference_mode} mode for batch={batch} inference...") + ov_compiled_model = core.compile_model( + ov_model, + device_name="AUTO", # AUTO selects best available device, do not modify + config={"PERFORMANCE_HINT": inference_mode}, + ) + input_name = ov_compiled_model.input().get_any_name() + metadata = w.parent / "metadata.yaml" + + # TensorRT + elif engine: + LOGGER.info(f"Loading {w} for TensorRT inference...") + try: + import tensorrt as trt # noqa https://developer.nvidia.com/nvidia-tensorrt-download + except ImportError: + if LINUX: + check_requirements("nvidia-tensorrt", cmds="-U --index-url https://pypi.ngc.nvidia.com") + import tensorrt as trt # noqa + check_version(trt.__version__, "7.0.0", hard=True) # require tensorrt>=7.0.0 + if device.type == "cpu": + device = torch.device("cuda:0") + Binding = namedtuple("Binding", ("name", "dtype", "shape", "data", "ptr")) + logger = trt.Logger(trt.Logger.INFO) + # Read file + with open(w, "rb") as f, trt.Runtime(logger) as runtime: + meta_len = int.from_bytes(f.read(4), byteorder="little") # read metadata length + metadata = json.loads(f.read(meta_len).decode("utf-8")) # read metadata + model = runtime.deserialize_cuda_engine(f.read()) # read engine + + # Model context + try: + context = model.create_execution_context() + except Exception as e: # model is None + LOGGER.error(f"ERROR: TensorRT model exported with a different version than {trt.__version__}\n") + raise e + + bindings = OrderedDict() + output_names = [] + fp16 = False # default updated below + dynamic = False + is_trt10 = not hasattr(model, "num_bindings") + num = range(model.num_io_tensors) if is_trt10 else range(model.num_bindings) + for i in num: + if is_trt10: + name = model.get_tensor_name(i) + dtype = trt.nptype(model.get_tensor_dtype(name)) + is_input = model.get_tensor_mode(name) == trt.TensorIOMode.INPUT + if is_input: + if -1 in tuple(model.get_tensor_shape(name)): + dynamic = True + context.set_input_shape(name, tuple(model.get_tensor_profile_shape(name, 0)[1])) + if dtype == np.float16: + fp16 = True + else: + output_names.append(name) + shape = tuple(context.get_tensor_shape(name)) + else: # TensorRT < 10.0 + name = model.get_binding_name(i) + dtype = trt.nptype(model.get_binding_dtype(i)) + is_input = model.binding_is_input(i) + if model.binding_is_input(i): + if -1 in tuple(model.get_binding_shape(i)): # dynamic + dynamic = True + context.set_binding_shape(i, tuple(model.get_profile_shape(0, i)[1])) + if dtype == np.float16: + fp16 = True + else: + output_names.append(name) + shape = tuple(context.get_binding_shape(i)) + im = torch.from_numpy(np.empty(shape, dtype=dtype)).to(device) + bindings[name] = Binding(name, dtype, shape, im, int(im.data_ptr())) + binding_addrs = OrderedDict((n, d.ptr) for n, d in bindings.items()) + batch_size = bindings["images"].shape[0] # if dynamic, this is instead max batch size + + # CoreML + elif coreml: + LOGGER.info(f"Loading {w} for CoreML inference...") + import coremltools as ct + + model = ct.models.MLModel(w) + metadata = dict(model.user_defined_metadata) + + # TF SavedModel + elif saved_model: + LOGGER.info(f"Loading {w} for TensorFlow SavedModel inference...") + import tensorflow as tf + + keras = False # assume TF1 saved_model + model = tf.keras.models.load_model(w) if keras else tf.saved_model.load(w) + metadata = Path(w) / "metadata.yaml" + + # TF GraphDef + elif pb: # https://www.tensorflow.org/guide/migrate#a_graphpb_or_graphpbtxt + LOGGER.info(f"Loading {w} for TensorFlow GraphDef inference...") + import tensorflow as tf + + from ultralytics.engine.exporter import gd_outputs + + def wrap_frozen_graph(gd, inputs, outputs): + """Wrap frozen graphs for deployment.""" + x = tf.compat.v1.wrap_function(lambda: tf.compat.v1.import_graph_def(gd, name=""), []) # wrapped + ge = x.graph.as_graph_element + return x.prune(tf.nest.map_structure(ge, inputs), tf.nest.map_structure(ge, outputs)) + + gd = tf.Graph().as_graph_def() # TF GraphDef + with open(w, "rb") as f: + gd.ParseFromString(f.read()) + frozen_func = wrap_frozen_graph(gd, inputs="x:0", outputs=gd_outputs(gd)) + + # TFLite or TFLite Edge TPU + elif tflite or edgetpu: # https://www.tensorflow.org/lite/guide/python#install_tensorflow_lite_for_python + try: # https://coral.ai/docs/edgetpu/tflite-python/#update-existing-tf-lite-code-for-the-edge-tpu + from tflite_runtime.interpreter import Interpreter, load_delegate + except ImportError: + import tensorflow as tf + + Interpreter, load_delegate = tf.lite.Interpreter, tf.lite.experimental.load_delegate + if edgetpu: # TF Edge TPU https://coral.ai/software/#edgetpu-runtime + LOGGER.info(f"Loading {w} for TensorFlow Lite Edge TPU inference...") + delegate = {"Linux": "libedgetpu.so.1", "Darwin": "libedgetpu.1.dylib", "Windows": "edgetpu.dll"}[ + platform.system() + ] + interpreter = Interpreter(model_path=w, experimental_delegates=[load_delegate(delegate)]) + else: # TFLite + LOGGER.info(f"Loading {w} for TensorFlow Lite inference...") + interpreter = Interpreter(model_path=w) # load TFLite model + interpreter.allocate_tensors() # allocate + input_details = interpreter.get_input_details() # inputs + output_details = interpreter.get_output_details() # outputs + # Load metadata + with contextlib.suppress(zipfile.BadZipFile): + with zipfile.ZipFile(w, "r") as model: + meta_file = model.namelist()[0] + metadata = ast.literal_eval(model.read(meta_file).decode("utf-8")) + + # TF.js + elif tfjs: + raise NotImplementedError("YOLOv8 TF.js inference is not currently supported.") + + # PaddlePaddle + elif paddle: + LOGGER.info(f"Loading {w} for PaddlePaddle inference...") + check_requirements("paddlepaddle-gpu" if cuda else "paddlepaddle") + import paddle.inference as pdi # noqa + + w = Path(w) + if not w.is_file(): # if not *.pdmodel + w = next(w.rglob("*.pdmodel")) # get *.pdmodel file from *_paddle_model dir + config = pdi.Config(str(w), str(w.with_suffix(".pdiparams"))) + if cuda: + config.enable_use_gpu(memory_pool_init_size_mb=2048, device_id=0) + predictor = pdi.create_predictor(config) + input_handle = predictor.get_input_handle(predictor.get_input_names()[0]) + output_names = predictor.get_output_names() + metadata = w.parents[1] / "metadata.yaml" + + # NCNN + elif ncnn: + LOGGER.info(f"Loading {w} for NCNN inference...") + check_requirements("git+https://github.com/Tencent/ncnn.git" if ARM64 else "ncnn") # requires NCNN + import ncnn as pyncnn + + net = pyncnn.Net() + net.opt.use_vulkan_compute = cuda + w = Path(w) + if not w.is_file(): # if not *.param + w = next(w.glob("*.param")) # get *.param file from *_ncnn_model dir + net.load_param(str(w)) + net.load_model(str(w.with_suffix(".bin"))) + metadata = w.parent / "metadata.yaml" + + # NVIDIA Triton Inference Server + elif triton: + check_requirements("tritonclient[all]") + from ultralytics.utils.triton import TritonRemoteModel + + model = TritonRemoteModel(w) + + # Any other format (unsupported) + else: + from ultralytics.engine.exporter import export_formats + + raise TypeError( + f"model='{w}' is not a supported model format. " + f"See https://docs.ultralytics.com/modes/predict for help.\n\n{export_formats()}" + ) + + # Load external metadata YAML + if isinstance(metadata, (str, Path)) and Path(metadata).exists(): + metadata = yaml_load(metadata) + if metadata: + for k, v in metadata.items(): + if k in {"stride", "batch"}: + metadata[k] = int(v) + elif k in {"imgsz", "names", "kpt_shape"} and isinstance(v, str): + metadata[k] = eval(v) + stride = metadata["stride"] + task = metadata["task"] + batch = metadata["batch"] + imgsz = metadata["imgsz"] + names = metadata["names"] + kpt_shape = metadata.get("kpt_shape") + elif not (pt or triton or nn_module): + LOGGER.warning(f"WARNING ⚠️ Metadata not found for 'model={weights}'") + + # Check names + if "names" not in locals(): # names missing + names = default_class_names(data) + names = check_class_names(names) + + # Disable gradients + if pt: + for p in model.parameters(): + p.requires_grad = False + + self.__dict__.update(locals()) # assign all variables to self + + def forward(self, im, augment=False, visualize=False, embed=None): + """ + Runs inference on the YOLOv8 MultiBackend model. + + Args: + im (torch.Tensor): The image tensor to perform inference on. + augment (bool): whether to perform data augmentation during inference, defaults to False + visualize (bool): whether to visualize the output predictions, defaults to False + embed (list, optional): A list of feature vectors/embeddings to return. + + Returns: + (tuple): Tuple containing the raw output tensor, and processed output for visualization (if visualize=True) + """ + b, ch, h, w = im.shape # batch, channel, height, width + if self.fp16 and im.dtype != torch.float16: + im = im.half() # to FP16 + if self.nhwc: + im = im.permute(0, 2, 3, 1) # torch BCHW to numpy BHWC shape(1,320,192,3) + + # PyTorch + if self.pt or self.nn_module: + y = self.model(im, augment=augment, visualize=visualize, embed=embed) + + # TorchScript + elif self.jit: + y = self.model(im) + + # ONNX OpenCV DNN + elif self.dnn: + im = im.cpu().numpy() # torch to numpy + self.net.setInput(im) + y = self.net.forward() + + # ONNX Runtime + elif self.onnx: + im = im.cpu().numpy() # torch to numpy + y = self.session.run(self.output_names, {self.session.get_inputs()[0].name: im}) + + # OpenVINO + elif self.xml: + im = im.cpu().numpy() # FP32 + + if self.inference_mode in {"THROUGHPUT", "CUMULATIVE_THROUGHPUT"}: # optimized for larger batch-sizes + n = im.shape[0] # number of images in batch + results = [None] * n # preallocate list with None to match the number of images + + def callback(request, userdata): + """Places result in preallocated list using userdata index.""" + results[userdata] = request.results + + # Create AsyncInferQueue, set the callback and start asynchronous inference for each input image + async_queue = self.ov.runtime.AsyncInferQueue(self.ov_compiled_model) + async_queue.set_callback(callback) + for i in range(n): + # Start async inference with userdata=i to specify the position in results list + async_queue.start_async(inputs={self.input_name: im[i : i + 1]}, userdata=i) # keep image as BCHW + async_queue.wait_all() # wait for all inference requests to complete + y = np.concatenate([list(r.values())[0] for r in results]) + + else: # inference_mode = "LATENCY", optimized for fastest first result at batch-size 1 + y = list(self.ov_compiled_model(im).values()) + + # TensorRT + elif self.engine: + if self.dynamic or im.shape != self.bindings["images"].shape: + if self.is_trt10: + self.context.set_input_shape("images", im.shape) + self.bindings["images"] = self.bindings["images"]._replace(shape=im.shape) + for name in self.output_names: + self.bindings[name].data.resize_(tuple(self.context.get_tensor_shape(name))) + else: + i = self.model.get_binding_index("images") + self.context.set_binding_shape(i, im.shape) + self.bindings["images"] = self.bindings["images"]._replace(shape=im.shape) + for name in self.output_names: + i = self.model.get_binding_index(name) + self.bindings[name].data.resize_(tuple(self.context.get_binding_shape(i))) + + s = self.bindings["images"].shape + assert im.shape == s, f"input size {im.shape} {'>' if self.dynamic else 'not equal to'} max model size {s}" + self.binding_addrs["images"] = int(im.data_ptr()) + self.context.execute_v2(list(self.binding_addrs.values())) + y = [self.bindings[x].data for x in sorted(self.output_names)] + + # CoreML + elif self.coreml: + im = im[0].cpu().numpy() + im_pil = Image.fromarray((im * 255).astype("uint8")) + # im = im.resize((192, 320), Image.BILINEAR) + y = self.model.predict({"image": im_pil}) # coordinates are xywh normalized + if "confidence" in y: + raise TypeError( + "Ultralytics only supports inference of non-pipelined CoreML models exported with " + f"'nms=False', but 'model={w}' has an NMS pipeline created by an 'nms=True' export." + ) + # TODO: CoreML NMS inference handling + # from ultralytics.utils.ops import xywh2xyxy + # box = xywh2xyxy(y['coordinates'] * [[w, h, w, h]]) # xyxy pixels + # conf, cls = y['confidence'].max(1), y['confidence'].argmax(1).astype(np.float32) + # y = np.concatenate((box, conf.reshape(-1, 1), cls.reshape(-1, 1)), 1) + elif len(y) == 1: # classification model + y = list(y.values()) + elif len(y) == 2: # segmentation model + y = list(reversed(y.values())) # reversed for segmentation models (pred, proto) + + # PaddlePaddle + elif self.paddle: + im = im.cpu().numpy().astype(np.float32) + self.input_handle.copy_from_cpu(im) + self.predictor.run() + y = [self.predictor.get_output_handle(x).copy_to_cpu() for x in self.output_names] + + # NCNN + elif self.ncnn: + mat_in = self.pyncnn.Mat(im[0].cpu().numpy()) + with self.net.create_extractor() as ex: + ex.input(self.net.input_names()[0], mat_in) + # WARNING: 'output_names' sorted as a temporary fix for https://github.com/pnnx/pnnx/issues/130 + y = [np.array(ex.extract(x)[1])[None] for x in sorted(self.net.output_names())] + + # NVIDIA Triton Inference Server + elif self.triton: + im = im.cpu().numpy() # torch to numpy + y = self.model(im) + + # TensorFlow (SavedModel, GraphDef, Lite, Edge TPU) + else: + im = im.cpu().numpy() + if self.saved_model: # SavedModel + y = self.model(im, training=False) if self.keras else self.model(im) + if not isinstance(y, list): + y = [y] + elif self.pb: # GraphDef + y = self.frozen_func(x=self.tf.constant(im)) + if len(y) == 2 and len(self.names) == 999: # segments and names not defined + ip, ib = (0, 1) if len(y[0].shape) == 4 else (1, 0) # index of protos, boxes + nc = y[ib].shape[1] - y[ip].shape[3] - 4 # y = (1, 160, 160, 32), (1, 116, 8400) + self.names = {i: f"class{i}" for i in range(nc)} + else: # Lite or Edge TPU + details = self.input_details[0] + is_int = details["dtype"] in {np.int8, np.int16} # is TFLite quantized int8 or int16 model + if is_int: + scale, zero_point = details["quantization"] + im = (im / scale + zero_point).astype(details["dtype"]) # de-scale + self.interpreter.set_tensor(details["index"], im) + self.interpreter.invoke() + y = [] + for output in self.output_details: + x = self.interpreter.get_tensor(output["index"]) + if is_int: + scale, zero_point = output["quantization"] + x = (x.astype(np.float32) - zero_point) * scale # re-scale + if x.ndim == 3: # if task is not classification, excluding masks (ndim=4) as well + # Denormalize xywh by image size. See https://github.com/ultralytics/ultralytics/pull/1695 + # xywh are normalized in TFLite/EdgeTPU to mitigate quantization error of integer models + x[:, [0, 2]] *= w + x[:, [1, 3]] *= h + y.append(x) + # TF segment fixes: export is reversed vs ONNX export and protos are transposed + if len(y) == 2: # segment with (det, proto) output order reversed + if len(y[1].shape) != 4: + y = list(reversed(y)) # should be y = (1, 116, 8400), (1, 160, 160, 32) + y[1] = np.transpose(y[1], (0, 3, 1, 2)) # should be y = (1, 116, 8400), (1, 32, 160, 160) + y = [x if isinstance(x, np.ndarray) else x.numpy() for x in y] + + # for x in y: + # print(type(x), len(x)) if isinstance(x, (list, tuple)) else print(type(x), x.shape) # debug shapes + if isinstance(y, (list, tuple)): + return self.from_numpy(y[0]) if len(y) == 1 else [self.from_numpy(x) for x in y] + else: + return self.from_numpy(y) + + def from_numpy(self, x): + """ + Convert a numpy array to a tensor. + + Args: + x (np.ndarray): The array to be converted. + + Returns: + (torch.Tensor): The converted tensor + """ + return torch.tensor(x).to(self.device) if isinstance(x, np.ndarray) else x + + def warmup(self, imgsz=(1, 3, 640, 640)): + """ + Warm up the model by running one forward pass with a dummy input. + + Args: + imgsz (tuple): The shape of the dummy input tensor in the format (batch_size, channels, height, width) + """ + warmup_types = self.pt, self.jit, self.onnx, self.engine, self.saved_model, self.pb, self.triton, self.nn_module + if any(warmup_types) and (self.device.type != "cpu" or self.triton): + im = torch.empty(*imgsz, dtype=torch.half if self.fp16 else torch.float, device=self.device) # input + for _ in range(2 if self.jit else 1): + self.forward(im) # warmup + + @staticmethod + def _model_type(p="path/to/model.pt"): + """ + This function takes a path to a model file and returns the model type. Possibles types are pt, jit, onnx, xml, + engine, coreml, saved_model, pb, tflite, edgetpu, tfjs, ncnn or paddle. + + Args: + p: path to the model file. Defaults to path/to/model.pt + + Examples: + >>> model = AutoBackend(weights="path/to/model.onnx") + >>> model_type = model._model_type() # returns "onnx" + """ + from ultralytics.engine.exporter import export_formats + + sf = list(export_formats().Suffix) # export suffixes + if not is_url(p) and not isinstance(p, str): + check_suffix(p, sf) # checks + name = Path(p).name + types = [s in name for s in sf] + types[5] |= name.endswith(".mlmodel") # retain support for older Apple CoreML *.mlmodel formats + types[8] &= not types[9] # tflite &= not edgetpu + if any(types): + triton = False + else: + from urllib.parse import urlsplit + + url = urlsplit(p) + triton = bool(url.netloc) and bool(url.path) and url.scheme in {"http", "grpc"} + + return types + [triton] diff --git a/ultralytics/nn/modules/__init__.py b/ultralytics/nn/modules/__init__.py new file mode 100644 index 0000000..5104417 --- /dev/null +++ b/ultralytics/nn/modules/__init__.py @@ -0,0 +1,138 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +""" +Ultralytics modules. + +Example: + Visualize a module with Netron. + ```python + from ultralytics.nn.modules import * + import torch + import os + + x = torch.ones(1, 128, 40, 40) + m = Conv(128, 128) + f = f'{m._get_name()}.onnx' + torch.onnx.export(m, x, f) + os.system(f'onnxsim {f} {f} && open {f}') + ``` +""" + +from .block import ( + C1, + C2, + C3, + C3TR, + DFL, + SPP, + SPPELAN, + SPPF, + ADown, + BNContrastiveHead, + Bottleneck, + BottleneckCSP, + C2f, + C2fAttn, + C3Ghost, + C3x, + CBFuse, + CBLinear, + ContrastiveHead, + GhostBottleneck, + HGBlock, + HGStem, + ImagePoolingAttn, + Proto, + RepC3, + RepNCSPELAN4, + ResNetLayer, + Silence, +) +from .conv import ( + CBAM, + ChannelAttention, + Concat, + Conv, + Conv2, + ConvTranspose, + DWConv, + DWConvTranspose2d, + Focus, + GhostConv, + LightConv, + RepConv, + SpatialAttention, +) +from .head import OBB, Classify, Detect, Pose, RTDETRDecoder, Segment, WorldDetect +from .transformer import ( + AIFI, + MLP, + DeformableTransformerDecoder, + DeformableTransformerDecoderLayer, + LayerNorm2d, + MLPBlock, + MSDeformAttn, + TransformerBlock, + TransformerEncoderLayer, + TransformerLayer, +) + +__all__ = ( + "Conv", + "Conv2", + "LightConv", + "RepConv", + "DWConv", + "DWConvTranspose2d", + "ConvTranspose", + "Focus", + "GhostConv", + "ChannelAttention", + "SpatialAttention", + "CBAM", + "Concat", + "TransformerLayer", + "TransformerBlock", + "MLPBlock", + "LayerNorm2d", + "DFL", + "HGBlock", + "HGStem", + "SPP", + "SPPF", + "C1", + "C2", + "C3", + "C2f", + "C2fAttn", + "C3x", + "C3TR", + "C3Ghost", + "GhostBottleneck", + "Bottleneck", + "BottleneckCSP", + "Proto", + "Detect", + "Segment", + "Pose", + "Classify", + "TransformerEncoderLayer", + "RepC3", + "RTDETRDecoder", + "AIFI", + "DeformableTransformerDecoder", + "DeformableTransformerDecoderLayer", + "MSDeformAttn", + "MLP", + "ResNetLayer", + "OBB", + "WorldDetect", + "ImagePoolingAttn", + "ContrastiveHead", + "BNContrastiveHead", + "RepNCSPELAN4", + "ADown", + "SPPELAN", + "CBFuse", + "CBLinear", + "Silence", +) diff --git a/ultralytics/nn/modules/block.py b/ultralytics/nn/modules/block.py new file mode 100644 index 0000000..a19e83b --- /dev/null +++ b/ultralytics/nn/modules/block.py @@ -0,0 +1,686 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +"""Block modules.""" + +import torch +import torch.nn as nn +import torch.nn.functional as F + +from .conv import Conv, DWConv, GhostConv, LightConv, RepConv, autopad +from .transformer import TransformerBlock + +__all__ = ( + "DFL", + "HGBlock", + "HGStem", + "SPP", + "SPPF", + "C1", + "C2", + "C3", + "C2f", + "C2fAttn", + "ImagePoolingAttn", + "ContrastiveHead", + "BNContrastiveHead", + "C3x", + "C3TR", + "C3Ghost", + "GhostBottleneck", + "Bottleneck", + "BottleneckCSP", + "Proto", + "RepC3", + "ResNetLayer", + "RepNCSPELAN4", + "ADown", + "SPPELAN", + "CBFuse", + "CBLinear", + "Silence", +) + + +class DFL(nn.Module): + """ + Integral module of Distribution Focal Loss (DFL). + + Proposed in Generalized Focal Loss https://ieeexplore.ieee.org/document/9792391 + """ + + def __init__(self, c1=16): + """Initialize a convolutional layer with a given number of input channels.""" + super().__init__() + self.conv = nn.Conv2d(c1, 1, 1, bias=False).requires_grad_(False) + x = torch.arange(c1, dtype=torch.float) + self.conv.weight.data[:] = nn.Parameter(x.view(1, c1, 1, 1)) + self.c1 = c1 + + def forward(self, x): + """Applies a transformer layer on input tensor 'x' and returns a tensor.""" + b, _, a = x.shape # batch, channels, anchors + return self.conv(x.view(b, 4, self.c1, a).transpose(2, 1).softmax(1)).view(b, 4, a) + # return self.conv(x.view(b, self.c1, 4, a).softmax(1)).view(b, 4, a) + + +class Proto(nn.Module): + """YOLOv8 mask Proto module for segmentation models.""" + + def __init__(self, c1, c_=256, c2=32): + """ + Initializes the YOLOv8 mask Proto module with specified number of protos and masks. + + Input arguments are ch_in, number of protos, number of masks. + """ + super().__init__() + self.cv1 = Conv(c1, c_, k=3) + self.upsample = nn.ConvTranspose2d(c_, c_, 2, 2, 0, bias=True) # nn.Upsample(scale_factor=2, mode='nearest') + self.cv2 = Conv(c_, c_, k=3) + self.cv3 = Conv(c_, c2) + + def forward(self, x): + """Performs a forward pass through layers using an upsampled input image.""" + return self.cv3(self.cv2(self.upsample(self.cv1(x)))) + + +class HGStem(nn.Module): + """ + StemBlock of PPHGNetV2 with 5 convolutions and one maxpool2d. + + https://github.com/PaddlePaddle/PaddleDetection/blob/develop/ppdet/modeling/backbones/hgnet_v2.py + """ + + def __init__(self, c1, cm, c2): + """Initialize the SPP layer with input/output channels and specified kernel sizes for max pooling.""" + super().__init__() + self.stem1 = Conv(c1, cm, 3, 2, act=nn.ReLU()) + self.stem2a = Conv(cm, cm // 2, 2, 1, 0, act=nn.ReLU()) + self.stem2b = Conv(cm // 2, cm, 2, 1, 0, act=nn.ReLU()) + self.stem3 = Conv(cm * 2, cm, 3, 2, act=nn.ReLU()) + self.stem4 = Conv(cm, c2, 1, 1, act=nn.ReLU()) + self.pool = nn.MaxPool2d(kernel_size=2, stride=1, padding=0, ceil_mode=True) + + def forward(self, x): + """Forward pass of a PPHGNetV2 backbone layer.""" + x = self.stem1(x) + x = F.pad(x, [0, 1, 0, 1]) + x2 = self.stem2a(x) + x2 = F.pad(x2, [0, 1, 0, 1]) + x2 = self.stem2b(x2) + x1 = self.pool(x) + x = torch.cat([x1, x2], dim=1) + x = self.stem3(x) + x = self.stem4(x) + return x + + +class HGBlock(nn.Module): + """ + HG_Block of PPHGNetV2 with 2 convolutions and LightConv. + + https://github.com/PaddlePaddle/PaddleDetection/blob/develop/ppdet/modeling/backbones/hgnet_v2.py + """ + + def __init__(self, c1, cm, c2, k=3, n=6, lightconv=False, shortcut=False, act=nn.ReLU()): + """Initializes a CSP Bottleneck with 1 convolution using specified input and output channels.""" + super().__init__() + block = LightConv if lightconv else Conv + self.m = nn.ModuleList(block(c1 if i == 0 else cm, cm, k=k, act=act) for i in range(n)) + self.sc = Conv(c1 + n * cm, c2 // 2, 1, 1, act=act) # squeeze conv + self.ec = Conv(c2 // 2, c2, 1, 1, act=act) # excitation conv + self.add = shortcut and c1 == c2 + + def forward(self, x): + """Forward pass of a PPHGNetV2 backbone layer.""" + y = [x] + y.extend(m(y[-1]) for m in self.m) + y = self.ec(self.sc(torch.cat(y, 1))) + return y + x if self.add else y + + +class SPP(nn.Module): + """Spatial Pyramid Pooling (SPP) layer https://arxiv.org/abs/1406.4729.""" + + def __init__(self, c1, c2, k=(5, 9, 13)): + """Initialize the SPP layer with input/output channels and pooling kernel sizes.""" + super().__init__() + c_ = c1 // 2 # hidden channels + self.cv1 = Conv(c1, c_, 1, 1) + self.cv2 = Conv(c_ * (len(k) + 1), c2, 1, 1) + self.m = nn.ModuleList([nn.MaxPool2d(kernel_size=x, stride=1, padding=x // 2) for x in k]) + + def forward(self, x): + """Forward pass of the SPP layer, performing spatial pyramid pooling.""" + x = self.cv1(x) + return self.cv2(torch.cat([x] + [m(x) for m in self.m], 1)) + + +class SPPF(nn.Module): + """Spatial Pyramid Pooling - Fast (SPPF) layer for YOLOv5 by Glenn Jocher.""" + + def __init__(self, c1, c2, k=5): + """ + Initializes the SPPF layer with given input/output channels and kernel size. + + This module is equivalent to SPP(k=(5, 9, 13)). + """ + super().__init__() + c_ = c1 // 2 # hidden channels + self.cv1 = Conv(c1, c_, 1, 1) + self.cv2 = Conv(c_ * 4, c2, 1, 1) + self.m = nn.MaxPool2d(kernel_size=k, stride=1, padding=k // 2) + + def forward(self, x): + """Forward pass through Ghost Convolution block.""" + y = [self.cv1(x)] + y.extend(self.m(y[-1]) for _ in range(3)) + return self.cv2(torch.cat(y, 1)) + + +class C1(nn.Module): + """CSP Bottleneck with 1 convolution.""" + + def __init__(self, c1, c2, n=1): + """Initializes the CSP Bottleneck with configurations for 1 convolution with arguments ch_in, ch_out, number.""" + super().__init__() + self.cv1 = Conv(c1, c2, 1, 1) + self.m = nn.Sequential(*(Conv(c2, c2, 3) for _ in range(n))) + + def forward(self, x): + """Applies cross-convolutions to input in the C3 module.""" + y = self.cv1(x) + return self.m(y) + y + + +class C2(nn.Module): + """CSP Bottleneck with 2 convolutions.""" + + def __init__(self, c1, c2, n=1, shortcut=True, g=1, e=0.5): + """Initializes the CSP Bottleneck with 2 convolutions module with arguments ch_in, ch_out, number, shortcut, + groups, expansion. + """ + super().__init__() + self.c = int(c2 * e) # hidden channels + self.cv1 = Conv(c1, 2 * self.c, 1, 1) + self.cv2 = Conv(2 * self.c, c2, 1) # optional act=FReLU(c2) + # self.attention = ChannelAttention(2 * self.c) # or SpatialAttention() + self.m = nn.Sequential(*(Bottleneck(self.c, self.c, shortcut, g, k=((3, 3), (3, 3)), e=1.0) for _ in range(n))) + + def forward(self, x): + """Forward pass through the CSP bottleneck with 2 convolutions.""" + a, b = self.cv1(x).chunk(2, 1) + return self.cv2(torch.cat((self.m(a), b), 1)) + + +class C2f(nn.Module): + """Faster Implementation of CSP Bottleneck with 2 convolutions.""" + + def __init__(self, c1, c2, n=1, shortcut=False, g=1, e=0.5): + """Initialize CSP bottleneck layer with two convolutions with arguments ch_in, ch_out, number, shortcut, groups, + expansion. + """ + super().__init__() + self.c = int(c2 * e) # hidden channels + self.cv1 = Conv(c1, 2 * self.c, 1, 1) + self.cv2 = Conv((2 + n) * self.c, c2, 1) # optional act=FReLU(c2) + self.m = nn.ModuleList(Bottleneck(self.c, self.c, shortcut, g, k=((3, 3), (3, 3)), e=1.0) for _ in range(n)) + + def forward(self, x): + """Forward pass through C2f layer.""" + y = list(self.cv1(x).chunk(2, 1)) + y.extend(m(y[-1]) for m in self.m) + return self.cv2(torch.cat(y, 1)) + + def forward_split(self, x): + """Forward pass using split() instead of chunk().""" + y = list(self.cv1(x).split((self.c, self.c), 1)) + y.extend(m(y[-1]) for m in self.m) + return self.cv2(torch.cat(y, 1)) + + +class C3(nn.Module): + """CSP Bottleneck with 3 convolutions.""" + + def __init__(self, c1, c2, n=1, shortcut=True, g=1, e=0.5): + """Initialize the CSP Bottleneck with given channels, number, shortcut, groups, and expansion values.""" + super().__init__() + c_ = int(c2 * e) # hidden channels + self.cv1 = Conv(c1, c_, 1, 1) + self.cv2 = Conv(c1, c_, 1, 1) + self.cv3 = Conv(2 * c_, c2, 1) # optional act=FReLU(c2) + self.m = nn.Sequential(*(Bottleneck(c_, c_, shortcut, g, k=((1, 1), (3, 3)), e=1.0) for _ in range(n))) + + def forward(self, x): + """Forward pass through the CSP bottleneck with 2 convolutions.""" + return self.cv3(torch.cat((self.m(self.cv1(x)), self.cv2(x)), 1)) + + +class C3x(C3): + """C3 module with cross-convolutions.""" + + def __init__(self, c1, c2, n=1, shortcut=True, g=1, e=0.5): + """Initialize C3TR instance and set default parameters.""" + super().__init__(c1, c2, n, shortcut, g, e) + self.c_ = int(c2 * e) + self.m = nn.Sequential(*(Bottleneck(self.c_, self.c_, shortcut, g, k=((1, 3), (3, 1)), e=1) for _ in range(n))) + + +class RepC3(nn.Module): + """Rep C3.""" + + def __init__(self, c1, c2, n=3, e=1.0): + """Initialize CSP Bottleneck with a single convolution using input channels, output channels, and number.""" + super().__init__() + c_ = int(c2 * e) # hidden channels + self.cv1 = Conv(c1, c2, 1, 1) + self.cv2 = Conv(c1, c2, 1, 1) + self.m = nn.Sequential(*[RepConv(c_, c_) for _ in range(n)]) + self.cv3 = Conv(c_, c2, 1, 1) if c_ != c2 else nn.Identity() + + def forward(self, x): + """Forward pass of RT-DETR neck layer.""" + return self.cv3(self.m(self.cv1(x)) + self.cv2(x)) + + +class C3TR(C3): + """C3 module with TransformerBlock().""" + + def __init__(self, c1, c2, n=1, shortcut=True, g=1, e=0.5): + """Initialize C3Ghost module with GhostBottleneck().""" + super().__init__(c1, c2, n, shortcut, g, e) + c_ = int(c2 * e) + self.m = TransformerBlock(c_, c_, 4, n) + + +class C3Ghost(C3): + """C3 module with GhostBottleneck().""" + + def __init__(self, c1, c2, n=1, shortcut=True, g=1, e=0.5): + """Initialize 'SPP' module with various pooling sizes for spatial pyramid pooling.""" + super().__init__(c1, c2, n, shortcut, g, e) + c_ = int(c2 * e) # hidden channels + self.m = nn.Sequential(*(GhostBottleneck(c_, c_) for _ in range(n))) + + +class GhostBottleneck(nn.Module): + """Ghost Bottleneck https://github.com/huawei-noah/ghostnet.""" + + def __init__(self, c1, c2, k=3, s=1): + """Initializes GhostBottleneck module with arguments ch_in, ch_out, kernel, stride.""" + super().__init__() + c_ = c2 // 2 + self.conv = nn.Sequential( + GhostConv(c1, c_, 1, 1), # pw + DWConv(c_, c_, k, s, act=False) if s == 2 else nn.Identity(), # dw + GhostConv(c_, c2, 1, 1, act=False), # pw-linear + ) + self.shortcut = ( + nn.Sequential(DWConv(c1, c1, k, s, act=False), Conv(c1, c2, 1, 1, act=False)) if s == 2 else nn.Identity() + ) + + def forward(self, x): + """Applies skip connection and concatenation to input tensor.""" + return self.conv(x) + self.shortcut(x) + + +class Bottleneck(nn.Module): + """Standard bottleneck.""" + + def __init__(self, c1, c2, shortcut=True, g=1, k=(3, 3), e=0.5): + """Initializes a bottleneck module with given input/output channels, shortcut option, group, kernels, and + expansion. + """ + super().__init__() + c_ = int(c2 * e) # hidden channels + self.cv1 = Conv(c1, c_, k[0], 1) + self.cv2 = Conv(c_, c2, k[1], 1, g=g) + self.add = shortcut and c1 == c2 + + def forward(self, x): + """'forward()' applies the YOLO FPN to input data.""" + return x + self.cv2(self.cv1(x)) if self.add else self.cv2(self.cv1(x)) + + +class BottleneckCSP(nn.Module): + """CSP Bottleneck https://github.com/WongKinYiu/CrossStagePartialNetworks.""" + + def __init__(self, c1, c2, n=1, shortcut=True, g=1, e=0.5): + """Initializes the CSP Bottleneck given arguments for ch_in, ch_out, number, shortcut, groups, expansion.""" + super().__init__() + c_ = int(c2 * e) # hidden channels + self.cv1 = Conv(c1, c_, 1, 1) + self.cv2 = nn.Conv2d(c1, c_, 1, 1, bias=False) + self.cv3 = nn.Conv2d(c_, c_, 1, 1, bias=False) + self.cv4 = Conv(2 * c_, c2, 1, 1) + self.bn = nn.BatchNorm2d(2 * c_) # applied to cat(cv2, cv3) + self.act = nn.SiLU() + self.m = nn.Sequential(*(Bottleneck(c_, c_, shortcut, g, e=1.0) for _ in range(n))) + + def forward(self, x): + """Applies a CSP bottleneck with 3 convolutions.""" + y1 = self.cv3(self.m(self.cv1(x))) + y2 = self.cv2(x) + return self.cv4(self.act(self.bn(torch.cat((y1, y2), 1)))) + + +class ResNetBlock(nn.Module): + """ResNet block with standard convolution layers.""" + + def __init__(self, c1, c2, s=1, e=4): + """Initialize convolution with given parameters.""" + super().__init__() + c3 = e * c2 + self.cv1 = Conv(c1, c2, k=1, s=1, act=True) + self.cv2 = Conv(c2, c2, k=3, s=s, p=1, act=True) + self.cv3 = Conv(c2, c3, k=1, act=False) + self.shortcut = nn.Sequential(Conv(c1, c3, k=1, s=s, act=False)) if s != 1 or c1 != c3 else nn.Identity() + + def forward(self, x): + """Forward pass through the ResNet block.""" + return F.relu(self.cv3(self.cv2(self.cv1(x))) + self.shortcut(x)) + + +class ResNetLayer(nn.Module): + """ResNet layer with multiple ResNet blocks.""" + + def __init__(self, c1, c2, s=1, is_first=False, n=1, e=4): + """Initializes the ResNetLayer given arguments.""" + super().__init__() + self.is_first = is_first + + if self.is_first: + self.layer = nn.Sequential( + Conv(c1, c2, k=7, s=2, p=3, act=True), nn.MaxPool2d(kernel_size=3, stride=2, padding=1) + ) + else: + blocks = [ResNetBlock(c1, c2, s, e=e)] + blocks.extend([ResNetBlock(e * c2, c2, 1, e=e) for _ in range(n - 1)]) + self.layer = nn.Sequential(*blocks) + + def forward(self, x): + """Forward pass through the ResNet layer.""" + return self.layer(x) + + +class MaxSigmoidAttnBlock(nn.Module): + """Max Sigmoid attention block.""" + + def __init__(self, c1, c2, nh=1, ec=128, gc=512, scale=False): + """Initializes MaxSigmoidAttnBlock with specified arguments.""" + super().__init__() + self.nh = nh + self.hc = c2 // nh + self.ec = Conv(c1, ec, k=1, act=False) if c1 != ec else None + self.gl = nn.Linear(gc, ec) + self.bias = nn.Parameter(torch.zeros(nh)) + self.proj_conv = Conv(c1, c2, k=3, s=1, act=False) + self.scale = nn.Parameter(torch.ones(1, nh, 1, 1)) if scale else 1.0 + + def forward(self, x, guide): + """Forward process.""" + bs, _, h, w = x.shape + + guide = self.gl(guide) + guide = guide.view(bs, -1, self.nh, self.hc) + embed = self.ec(x) if self.ec is not None else x + embed = embed.view(bs, self.nh, self.hc, h, w) + + aw = torch.einsum("bmchw,bnmc->bmhwn", embed, guide) + aw = aw.max(dim=-1)[0] + aw = aw / (self.hc**0.5) + aw = aw + self.bias[None, :, None, None] + aw = aw.sigmoid() * self.scale + + x = self.proj_conv(x) + x = x.view(bs, self.nh, -1, h, w) + x = x * aw.unsqueeze(2) + return x.view(bs, -1, h, w) + + +class C2fAttn(nn.Module): + """C2f module with an additional attn module.""" + + def __init__(self, c1, c2, n=1, ec=128, nh=1, gc=512, shortcut=False, g=1, e=0.5): + """Initialize CSP bottleneck layer with two convolutions with arguments ch_in, ch_out, number, shortcut, groups, + expansion. + """ + super().__init__() + self.c = int(c2 * e) # hidden channels + self.cv1 = Conv(c1, 2 * self.c, 1, 1) + self.cv2 = Conv((3 + n) * self.c, c2, 1) # optional act=FReLU(c2) + self.m = nn.ModuleList(Bottleneck(self.c, self.c, shortcut, g, k=((3, 3), (3, 3)), e=1.0) for _ in range(n)) + self.attn = MaxSigmoidAttnBlock(self.c, self.c, gc=gc, ec=ec, nh=nh) + + def forward(self, x, guide): + """Forward pass through C2f layer.""" + y = list(self.cv1(x).chunk(2, 1)) + y.extend(m(y[-1]) for m in self.m) + y.append(self.attn(y[-1], guide)) + return self.cv2(torch.cat(y, 1)) + + def forward_split(self, x, guide): + """Forward pass using split() instead of chunk().""" + y = list(self.cv1(x).split((self.c, self.c), 1)) + y.extend(m(y[-1]) for m in self.m) + y.append(self.attn(y[-1], guide)) + return self.cv2(torch.cat(y, 1)) + + +class ImagePoolingAttn(nn.Module): + """ImagePoolingAttn: Enhance the text embeddings with image-aware information.""" + + def __init__(self, ec=256, ch=(), ct=512, nh=8, k=3, scale=False): + """Initializes ImagePoolingAttn with specified arguments.""" + super().__init__() + + nf = len(ch) + self.query = nn.Sequential(nn.LayerNorm(ct), nn.Linear(ct, ec)) + self.key = nn.Sequential(nn.LayerNorm(ec), nn.Linear(ec, ec)) + self.value = nn.Sequential(nn.LayerNorm(ec), nn.Linear(ec, ec)) + self.proj = nn.Linear(ec, ct) + self.scale = nn.Parameter(torch.tensor([0.0]), requires_grad=True) if scale else 1.0 + self.projections = nn.ModuleList([nn.Conv2d(in_channels, ec, kernel_size=1) for in_channels in ch]) + self.im_pools = nn.ModuleList([nn.AdaptiveMaxPool2d((k, k)) for _ in range(nf)]) + self.ec = ec + self.nh = nh + self.nf = nf + self.hc = ec // nh + self.k = k + + def forward(self, x, text): + """Executes attention mechanism on input tensor x and guide tensor.""" + bs = x[0].shape[0] + assert len(x) == self.nf + num_patches = self.k**2 + x = [pool(proj(x)).view(bs, -1, num_patches) for (x, proj, pool) in zip(x, self.projections, self.im_pools)] + x = torch.cat(x, dim=-1).transpose(1, 2) + q = self.query(text) + k = self.key(x) + v = self.value(x) + + # q = q.reshape(1, text.shape[1], self.nh, self.hc).repeat(bs, 1, 1, 1) + q = q.reshape(bs, -1, self.nh, self.hc) + k = k.reshape(bs, -1, self.nh, self.hc) + v = v.reshape(bs, -1, self.nh, self.hc) + + aw = torch.einsum("bnmc,bkmc->bmnk", q, k) + aw = aw / (self.hc**0.5) + aw = F.softmax(aw, dim=-1) + + x = torch.einsum("bmnk,bkmc->bnmc", aw, v) + x = self.proj(x.reshape(bs, -1, self.ec)) + return x * self.scale + text + + +class ContrastiveHead(nn.Module): + """Contrastive Head for YOLO-World compute the region-text scores according to the similarity between image and text + features. + """ + + def __init__(self): + """Initializes ContrastiveHead with specified region-text similarity parameters.""" + super().__init__() + # NOTE: use -10.0 to keep the init cls loss consistency with other losses + self.bias = nn.Parameter(torch.tensor([-10.0])) + self.logit_scale = nn.Parameter(torch.ones([]) * torch.tensor(1 / 0.07).log()) + + def forward(self, x, w): + """Forward function of contrastive learning.""" + x = F.normalize(x, dim=1, p=2) + w = F.normalize(w, dim=-1, p=2) + x = torch.einsum("bchw,bkc->bkhw", x, w) + return x * self.logit_scale.exp() + self.bias + + +class BNContrastiveHead(nn.Module): + """ + Batch Norm Contrastive Head for YOLO-World using batch norm instead of l2-normalization. + + Args: + embed_dims (int): Embed dimensions of text and image features. + """ + + def __init__(self, embed_dims: int): + """Initialize ContrastiveHead with region-text similarity parameters.""" + super().__init__() + self.norm = nn.BatchNorm2d(embed_dims) + # NOTE: use -10.0 to keep the init cls loss consistency with other losses + self.bias = nn.Parameter(torch.tensor([-10.0])) + # use -1.0 is more stable + self.logit_scale = nn.Parameter(-1.0 * torch.ones([])) + + def forward(self, x, w): + """Forward function of contrastive learning.""" + x = self.norm(x) + w = F.normalize(w, dim=-1, p=2) + x = torch.einsum("bchw,bkc->bkhw", x, w) + return x * self.logit_scale.exp() + self.bias + + +class RepBottleneck(Bottleneck): + """Rep bottleneck.""" + + def __init__(self, c1, c2, shortcut=True, g=1, k=(3, 3), e=0.5): + """Initializes a RepBottleneck module with customizable in/out channels, shortcut option, groups and expansion + ratio. + """ + super().__init__(c1, c2, shortcut, g, k, e) + c_ = int(c2 * e) # hidden channels + self.cv1 = RepConv(c1, c_, k[0], 1) + + +class RepCSP(C3): + """Rep CSP Bottleneck with 3 convolutions.""" + + def __init__(self, c1, c2, n=1, shortcut=True, g=1, e=0.5): + """Initializes RepCSP layer with given channels, repetitions, shortcut, groups and expansion ratio.""" + super().__init__(c1, c2, n, shortcut, g, e) + c_ = int(c2 * e) # hidden channels + self.m = nn.Sequential(*(RepBottleneck(c_, c_, shortcut, g, e=1.0) for _ in range(n))) + + +class RepNCSPELAN4(nn.Module): + """CSP-ELAN.""" + + def __init__(self, c1, c2, c3, c4, n=1): + """Initializes CSP-ELAN layer with specified channel sizes, repetitions, and convolutions.""" + super().__init__() + self.c = c3 // 2 + self.cv1 = Conv(c1, c3, 1, 1) + self.cv2 = nn.Sequential(RepCSP(c3 // 2, c4, n), Conv(c4, c4, 3, 1)) + self.cv3 = nn.Sequential(RepCSP(c4, c4, n), Conv(c4, c4, 3, 1)) + self.cv4 = Conv(c3 + (2 * c4), c2, 1, 1) + + def forward(self, x): + """Forward pass through RepNCSPELAN4 layer.""" + y = list(self.cv1(x).chunk(2, 1)) + y.extend((m(y[-1])) for m in [self.cv2, self.cv3]) + return self.cv4(torch.cat(y, 1)) + + def forward_split(self, x): + """Forward pass using split() instead of chunk().""" + y = list(self.cv1(x).split((self.c, self.c), 1)) + y.extend(m(y[-1]) for m in [self.cv2, self.cv3]) + return self.cv4(torch.cat(y, 1)) + + +class ADown(nn.Module): + """ADown.""" + + def __init__(self, c1, c2): + """Initializes ADown module with convolution layers to downsample input from channels c1 to c2.""" + super().__init__() + self.c = c2 // 2 + self.cv1 = Conv(c1 // 2, self.c, 3, 2, 1) + self.cv2 = Conv(c1 // 2, self.c, 1, 1, 0) + + def forward(self, x): + """Forward pass through ADown layer.""" + x = torch.nn.functional.avg_pool2d(x, 2, 1, 0, False, True) + x1, x2 = x.chunk(2, 1) + x1 = self.cv1(x1) + x2 = torch.nn.functional.max_pool2d(x2, 3, 2, 1) + x2 = self.cv2(x2) + return torch.cat((x1, x2), 1) + + +class SPPELAN(nn.Module): + """SPP-ELAN.""" + + def __init__(self, c1, c2, c3, k=5): + """Initializes SPP-ELAN block with convolution and max pooling layers for spatial pyramid pooling.""" + super().__init__() + self.c = c3 + self.cv1 = Conv(c1, c3, 1, 1) + self.cv2 = nn.MaxPool2d(kernel_size=k, stride=1, padding=k // 2) + self.cv3 = nn.MaxPool2d(kernel_size=k, stride=1, padding=k // 2) + self.cv4 = nn.MaxPool2d(kernel_size=k, stride=1, padding=k // 2) + self.cv5 = Conv(4 * c3, c2, 1, 1) + + def forward(self, x): + """Forward pass through SPPELAN layer.""" + y = [self.cv1(x)] + y.extend(m(y[-1]) for m in [self.cv2, self.cv3, self.cv4]) + return self.cv5(torch.cat(y, 1)) + + +class Silence(nn.Module): + """Silence.""" + + def __init__(self): + """Initializes the Silence module.""" + super(Silence, self).__init__() + + def forward(self, x): + """Forward pass through Silence layer.""" + return x + + +class CBLinear(nn.Module): + """CBLinear.""" + + def __init__(self, c1, c2s, k=1, s=1, p=None, g=1): + """Initializes the CBLinear module, passing inputs unchanged.""" + super(CBLinear, self).__init__() + self.c2s = c2s + self.conv = nn.Conv2d(c1, sum(c2s), k, s, autopad(k, p), groups=g, bias=True) + + def forward(self, x): + """Forward pass through CBLinear layer.""" + outs = self.conv(x).split(self.c2s, dim=1) + return outs + + +class CBFuse(nn.Module): + """CBFuse.""" + + def __init__(self, idx): + """Initializes CBFuse module with layer index for selective feature fusion.""" + super(CBFuse, self).__init__() + self.idx = idx + + def forward(self, xs): + """Forward pass through CBFuse layer.""" + target_size = xs[-1].shape[2:] + res = [F.interpolate(x[self.idx[i]], size=target_size, mode="nearest") for i, x in enumerate(xs[:-1])] + out = torch.sum(torch.stack(res + xs[-1:]), dim=0) + return out diff --git a/ultralytics/nn/modules/conv.py b/ultralytics/nn/modules/conv.py new file mode 100644 index 0000000..6b51813 --- /dev/null +++ b/ultralytics/nn/modules/conv.py @@ -0,0 +1,333 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +"""Convolution modules.""" + +import math + +import numpy as np +import torch +import torch.nn as nn + +__all__ = ( + "Conv", + "Conv2", + "LightConv", + "DWConv", + "DWConvTranspose2d", + "ConvTranspose", + "Focus", + "GhostConv", + "ChannelAttention", + "SpatialAttention", + "CBAM", + "Concat", + "RepConv", +) + + +def autopad(k, p=None, d=1): # kernel, padding, dilation + """Pad to 'same' shape outputs.""" + if d > 1: + k = d * (k - 1) + 1 if isinstance(k, int) else [d * (x - 1) + 1 for x in k] # actual kernel-size + if p is None: + p = k // 2 if isinstance(k, int) else [x // 2 for x in k] # auto-pad + return p + + +class Conv(nn.Module): + """Standard convolution with args(ch_in, ch_out, kernel, stride, padding, groups, dilation, activation).""" + + default_act = nn.SiLU() # default activation + + def __init__(self, c1, c2, k=1, s=1, p=None, g=1, d=1, act=True): + """Initialize Conv layer with given arguments including activation.""" + super().__init__() + self.conv = nn.Conv2d(c1, c2, k, s, autopad(k, p, d), groups=g, dilation=d, bias=False) + self.bn = nn.BatchNorm2d(c2) + self.act = self.default_act if act is True else act if isinstance(act, nn.Module) else nn.Identity() + + def forward(self, x): + """Apply convolution, batch normalization and activation to input tensor.""" + return self.act(self.bn(self.conv(x))) + + def forward_fuse(self, x): + """Perform transposed convolution of 2D data.""" + return self.act(self.conv(x)) + + +class Conv2(Conv): + """Simplified RepConv module with Conv fusing.""" + + def __init__(self, c1, c2, k=3, s=1, p=None, g=1, d=1, act=True): + """Initialize Conv layer with given arguments including activation.""" + super().__init__(c1, c2, k, s, p, g=g, d=d, act=act) + self.cv2 = nn.Conv2d(c1, c2, 1, s, autopad(1, p, d), groups=g, dilation=d, bias=False) # add 1x1 conv + + def forward(self, x): + """Apply convolution, batch normalization and activation to input tensor.""" + return self.act(self.bn(self.conv(x) + self.cv2(x))) + + def forward_fuse(self, x): + """Apply fused convolution, batch normalization and activation to input tensor.""" + return self.act(self.bn(self.conv(x))) + + def fuse_convs(self): + """Fuse parallel convolutions.""" + w = torch.zeros_like(self.conv.weight.data) + i = [x // 2 for x in w.shape[2:]] + w[:, :, i[0] : i[0] + 1, i[1] : i[1] + 1] = self.cv2.weight.data.clone() + self.conv.weight.data += w + self.__delattr__("cv2") + self.forward = self.forward_fuse + + +class LightConv(nn.Module): + """ + Light convolution with args(ch_in, ch_out, kernel). + + https://github.com/PaddlePaddle/PaddleDetection/blob/develop/ppdet/modeling/backbones/hgnet_v2.py + """ + + def __init__(self, c1, c2, k=1, act=nn.ReLU()): + """Initialize Conv layer with given arguments including activation.""" + super().__init__() + self.conv1 = Conv(c1, c2, 1, act=False) + self.conv2 = DWConv(c2, c2, k, act=act) + + def forward(self, x): + """Apply 2 convolutions to input tensor.""" + return self.conv2(self.conv1(x)) + + +class DWConv(Conv): + """Depth-wise convolution.""" + + def __init__(self, c1, c2, k=1, s=1, d=1, act=True): # ch_in, ch_out, kernel, stride, dilation, activation + """Initialize Depth-wise convolution with given parameters.""" + super().__init__(c1, c2, k, s, g=math.gcd(c1, c2), d=d, act=act) + + +class DWConvTranspose2d(nn.ConvTranspose2d): + """Depth-wise transpose convolution.""" + + def __init__(self, c1, c2, k=1, s=1, p1=0, p2=0): # ch_in, ch_out, kernel, stride, padding, padding_out + """Initialize DWConvTranspose2d class with given parameters.""" + super().__init__(c1, c2, k, s, p1, p2, groups=math.gcd(c1, c2)) + + +class ConvTranspose(nn.Module): + """Convolution transpose 2d layer.""" + + default_act = nn.SiLU() # default activation + + def __init__(self, c1, c2, k=2, s=2, p=0, bn=True, act=True): + """Initialize ConvTranspose2d layer with batch normalization and activation function.""" + super().__init__() + self.conv_transpose = nn.ConvTranspose2d(c1, c2, k, s, p, bias=not bn) + self.bn = nn.BatchNorm2d(c2) if bn else nn.Identity() + self.act = self.default_act if act is True else act if isinstance(act, nn.Module) else nn.Identity() + + def forward(self, x): + """Applies transposed convolutions, batch normalization and activation to input.""" + return self.act(self.bn(self.conv_transpose(x))) + + def forward_fuse(self, x): + """Applies activation and convolution transpose operation to input.""" + return self.act(self.conv_transpose(x)) + + +class Focus(nn.Module): + """Focus wh information into c-space.""" + + def __init__(self, c1, c2, k=1, s=1, p=None, g=1, act=True): + """Initializes Focus object with user defined channel, convolution, padding, group and activation values.""" + super().__init__() + self.conv = Conv(c1 * 4, c2, k, s, p, g, act=act) + # self.contract = Contract(gain=2) + + def forward(self, x): + """ + Applies convolution to concatenated tensor and returns the output. + + Input shape is (b,c,w,h) and output shape is (b,4c,w/2,h/2). + """ + return self.conv(torch.cat((x[..., ::2, ::2], x[..., 1::2, ::2], x[..., ::2, 1::2], x[..., 1::2, 1::2]), 1)) + # return self.conv(self.contract(x)) + + +class GhostConv(nn.Module): + """Ghost Convolution https://github.com/huawei-noah/ghostnet.""" + + def __init__(self, c1, c2, k=1, s=1, g=1, act=True): + """Initializes the GhostConv object with input channels, output channels, kernel size, stride, groups and + activation. + """ + super().__init__() + c_ = c2 // 2 # hidden channels + self.cv1 = Conv(c1, c_, k, s, None, g, act=act) + self.cv2 = Conv(c_, c_, 5, 1, None, c_, act=act) + + def forward(self, x): + """Forward propagation through a Ghost Bottleneck layer with skip connection.""" + y = self.cv1(x) + return torch.cat((y, self.cv2(y)), 1) + + +class RepConv(nn.Module): + """ + RepConv is a basic rep-style block, including training and deploy status. + + This module is used in RT-DETR. + Based on https://github.com/DingXiaoH/RepVGG/blob/main/repvgg.py + """ + + default_act = nn.SiLU() # default activation + + def __init__(self, c1, c2, k=3, s=1, p=1, g=1, d=1, act=True, bn=False, deploy=False): + """Initializes Light Convolution layer with inputs, outputs & optional activation function.""" + super().__init__() + assert k == 3 and p == 1 + self.g = g + self.c1 = c1 + self.c2 = c2 + self.act = self.default_act if act is True else act if isinstance(act, nn.Module) else nn.Identity() + + self.bn = nn.BatchNorm2d(num_features=c1) if bn and c2 == c1 and s == 1 else None + self.conv1 = Conv(c1, c2, k, s, p=p, g=g, act=False) + self.conv2 = Conv(c1, c2, 1, s, p=(p - k // 2), g=g, act=False) + + def forward_fuse(self, x): + """Forward process.""" + return self.act(self.conv(x)) + + def forward(self, x): + """Forward process.""" + id_out = 0 if self.bn is None else self.bn(x) + return self.act(self.conv1(x) + self.conv2(x) + id_out) + + def get_equivalent_kernel_bias(self): + """Returns equivalent kernel and bias by adding 3x3 kernel, 1x1 kernel and identity kernel with their biases.""" + kernel3x3, bias3x3 = self._fuse_bn_tensor(self.conv1) + kernel1x1, bias1x1 = self._fuse_bn_tensor(self.conv2) + kernelid, biasid = self._fuse_bn_tensor(self.bn) + return kernel3x3 + self._pad_1x1_to_3x3_tensor(kernel1x1) + kernelid, bias3x3 + bias1x1 + biasid + + def _pad_1x1_to_3x3_tensor(self, kernel1x1): + """Pads a 1x1 tensor to a 3x3 tensor.""" + if kernel1x1 is None: + return 0 + else: + return torch.nn.functional.pad(kernel1x1, [1, 1, 1, 1]) + + def _fuse_bn_tensor(self, branch): + """Generates appropriate kernels and biases for convolution by fusing branches of the neural network.""" + if branch is None: + return 0, 0 + if isinstance(branch, Conv): + kernel = branch.conv.weight + running_mean = branch.bn.running_mean + running_var = branch.bn.running_var + gamma = branch.bn.weight + beta = branch.bn.bias + eps = branch.bn.eps + elif isinstance(branch, nn.BatchNorm2d): + if not hasattr(self, "id_tensor"): + input_dim = self.c1 // self.g + kernel_value = np.zeros((self.c1, input_dim, 3, 3), dtype=np.float32) + for i in range(self.c1): + kernel_value[i, i % input_dim, 1, 1] = 1 + self.id_tensor = torch.from_numpy(kernel_value).to(branch.weight.device) + kernel = self.id_tensor + running_mean = branch.running_mean + running_var = branch.running_var + gamma = branch.weight + beta = branch.bias + eps = branch.eps + std = (running_var + eps).sqrt() + t = (gamma / std).reshape(-1, 1, 1, 1) + return kernel * t, beta - running_mean * gamma / std + + def fuse_convs(self): + """Combines two convolution layers into a single layer and removes unused attributes from the class.""" + if hasattr(self, "conv"): + return + kernel, bias = self.get_equivalent_kernel_bias() + self.conv = nn.Conv2d( + in_channels=self.conv1.conv.in_channels, + out_channels=self.conv1.conv.out_channels, + kernel_size=self.conv1.conv.kernel_size, + stride=self.conv1.conv.stride, + padding=self.conv1.conv.padding, + dilation=self.conv1.conv.dilation, + groups=self.conv1.conv.groups, + bias=True, + ).requires_grad_(False) + self.conv.weight.data = kernel + self.conv.bias.data = bias + for para in self.parameters(): + para.detach_() + self.__delattr__("conv1") + self.__delattr__("conv2") + if hasattr(self, "nm"): + self.__delattr__("nm") + if hasattr(self, "bn"): + self.__delattr__("bn") + if hasattr(self, "id_tensor"): + self.__delattr__("id_tensor") + + +class ChannelAttention(nn.Module): + """Channel-attention module https://github.com/open-mmlab/mmdetection/tree/v3.0.0rc1/configs/rtmdet.""" + + def __init__(self, channels: int) -> None: + """Initializes the class and sets the basic configurations and instance variables required.""" + super().__init__() + self.pool = nn.AdaptiveAvgPool2d(1) + self.fc = nn.Conv2d(channels, channels, 1, 1, 0, bias=True) + self.act = nn.Sigmoid() + + def forward(self, x: torch.Tensor) -> torch.Tensor: + """Applies forward pass using activation on convolutions of the input, optionally using batch normalization.""" + return x * self.act(self.fc(self.pool(x))) + + +class SpatialAttention(nn.Module): + """Spatial-attention module.""" + + def __init__(self, kernel_size=7): + """Initialize Spatial-attention module with kernel size argument.""" + super().__init__() + assert kernel_size in {3, 7}, "kernel size must be 3 or 7" + padding = 3 if kernel_size == 7 else 1 + self.cv1 = nn.Conv2d(2, 1, kernel_size, padding=padding, bias=False) + self.act = nn.Sigmoid() + + def forward(self, x): + """Apply channel and spatial attention on input for feature recalibration.""" + return x * self.act(self.cv1(torch.cat([torch.mean(x, 1, keepdim=True), torch.max(x, 1, keepdim=True)[0]], 1))) + + +class CBAM(nn.Module): + """Convolutional Block Attention Module.""" + + def __init__(self, c1, kernel_size=7): + """Initialize CBAM with given input channel (c1) and kernel size.""" + super().__init__() + self.channel_attention = ChannelAttention(c1) + self.spatial_attention = SpatialAttention(kernel_size) + + def forward(self, x): + """Applies the forward pass through C1 module.""" + return self.spatial_attention(self.channel_attention(x)) + + +class Concat(nn.Module): + """Concatenate a list of tensors along dimension.""" + + def __init__(self, dimension=1): + """Concatenates a list of tensors along a specified dimension.""" + super().__init__() + self.d = dimension + + def forward(self, x): + """Forward pass for the YOLOv8 mask Proto module.""" + return torch.cat(x, self.d) diff --git a/ultralytics/nn/modules/head.py b/ultralytics/nn/modules/head.py new file mode 100644 index 0000000..87c6417 --- /dev/null +++ b/ultralytics/nn/modules/head.py @@ -0,0 +1,492 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +"""Model head modules.""" + +import math + +import torch +import torch.nn as nn +from torch.nn.init import constant_, xavier_uniform_ + +from ultralytics.utils.tal import TORCH_1_10, dist2bbox, dist2rbox, make_anchors + +from .block import DFL, BNContrastiveHead, ContrastiveHead, Proto +from .conv import Conv +from .transformer import MLP, DeformableTransformerDecoder, DeformableTransformerDecoderLayer +from .utils import bias_init_with_prob, linear_init + +__all__ = "Detect", "Segment", "Pose", "Classify", "OBB", "RTDETRDecoder" + + +class Detect(nn.Module): + """YOLOv8 Detect head for detection models.""" + + dynamic = False # force grid reconstruction + export = False # export mode + shape = None + anchors = torch.empty(0) # init + strides = torch.empty(0) # init + + def __init__(self, nc=80, ch=()): + """Initializes the YOLOv8 detection layer with specified number of classes and channels.""" + super().__init__() + self.nc = nc # number of classes + self.nl = len(ch) # number of detection layers + self.reg_max = 16 # DFL channels (ch[0] // 16 to scale 4/8/12/16/20 for n/s/m/l/x) + self.no = nc + self.reg_max * 4 # number of outputs per anchor + self.stride = torch.zeros(self.nl) # strides computed during build + c2, c3 = max((16, ch[0] // 4, self.reg_max * 4)), max(ch[0], min(self.nc, 100)) # channels + self.cv2 = nn.ModuleList( + nn.Sequential(Conv(x, c2, 3), Conv(c2, c2, 3), nn.Conv2d(c2, 4 * self.reg_max, 1)) for x in ch + ) + self.cv3 = nn.ModuleList(nn.Sequential(Conv(x, c3, 3), Conv(c3, c3, 3), nn.Conv2d(c3, self.nc, 1)) for x in ch) + self.dfl = DFL(self.reg_max) if self.reg_max > 1 else nn.Identity() + + def forward(self, x): + """Concatenates and returns predicted bounding boxes and class probabilities.""" + for i in range(self.nl): + x[i] = torch.cat((self.cv2[i](x[i]), self.cv3[i](x[i])), 1) + if self.training: # Training path + return x + + # Inference path + shape = x[0].shape # BCHW + x_cat = torch.cat([xi.view(shape[0], self.no, -1) for xi in x], 2) + if self.dynamic or self.shape != shape: + self.anchors, self.strides = (x.transpose(0, 1) for x in make_anchors(x, self.stride, 0.5)) + self.shape = shape + + if self.export and self.format in {"saved_model", "pb", "tflite", "edgetpu", "tfjs"}: # avoid TF FlexSplitV ops + box = x_cat[:, : self.reg_max * 4] + cls = x_cat[:, self.reg_max * 4 :] + else: + box, cls = x_cat.split((self.reg_max * 4, self.nc), 1) + + if self.export and self.format in {"tflite", "edgetpu"}: + # Precompute normalization factor to increase numerical stability + # See https://github.com/ultralytics/ultralytics/issues/7371 + grid_h = shape[2] + grid_w = shape[3] + grid_size = torch.tensor([grid_w, grid_h, grid_w, grid_h], device=box.device).reshape(1, 4, 1) + norm = self.strides / (self.stride[0] * grid_size) + dbox = self.decode_bboxes(self.dfl(box) * norm, self.anchors.unsqueeze(0) * norm[:, :2]) + else: + dbox = self.decode_bboxes(self.dfl(box), self.anchors.unsqueeze(0)) * self.strides + + y = torch.cat((dbox, cls.sigmoid()), 1) + return y if self.export else (y, x) + + def bias_init(self): + """Initialize Detect() biases, WARNING: requires stride availability.""" + m = self # self.model[-1] # Detect() module + # cf = torch.bincount(torch.tensor(np.concatenate(dataset.labels, 0)[:, 0]).long(), minlength=nc) + 1 + # ncf = math.log(0.6 / (m.nc - 0.999999)) if cf is None else torch.log(cf / cf.sum()) # nominal class frequency + for a, b, s in zip(m.cv2, m.cv3, m.stride): # from + a[-1].bias.data[:] = 1.0 # box + b[-1].bias.data[: m.nc] = math.log(5 / m.nc / (640 / s) ** 2) # cls (.01 objects, 80 classes, 640 img) + + def decode_bboxes(self, bboxes, anchors): + """Decode bounding boxes.""" + return dist2bbox(bboxes, anchors, xywh=True, dim=1) + + +class Segment(Detect): + """YOLOv8 Segment head for segmentation models.""" + + def __init__(self, nc=80, nm=32, npr=256, ch=()): + """Initialize the YOLO model attributes such as the number of masks, prototypes, and the convolution layers.""" + super().__init__(nc, ch) + self.nm = nm # number of masks + self.npr = npr # number of protos + self.proto = Proto(ch[0], self.npr, self.nm) # protos + self.detect = Detect.forward + + c4 = max(ch[0] // 4, self.nm) + self.cv4 = nn.ModuleList(nn.Sequential(Conv(x, c4, 3), Conv(c4, c4, 3), nn.Conv2d(c4, self.nm, 1)) for x in ch) + + def forward(self, x): + """Return model outputs and mask coefficients if training, otherwise return outputs and mask coefficients.""" + p = self.proto(x[0]) # mask protos + bs = p.shape[0] # batch size + + mc = torch.cat([self.cv4[i](x[i]).view(bs, self.nm, -1) for i in range(self.nl)], 2) # mask coefficients + x = self.detect(self, x) + if self.training: + return x, mc, p + return (torch.cat([x, mc], 1), p) if self.export else (torch.cat([x[0], mc], 1), (x[1], mc, p)) + + +class OBB(Detect): + """YOLOv8 OBB detection head for detection with rotation models.""" + + def __init__(self, nc=80, ne=1, ch=()): + """Initialize OBB with number of classes `nc` and layer channels `ch`.""" + super().__init__(nc, ch) + self.ne = ne # number of extra parameters + self.detect = Detect.forward + + c4 = max(ch[0] // 4, self.ne) + self.cv4 = nn.ModuleList(nn.Sequential(Conv(x, c4, 3), Conv(c4, c4, 3), nn.Conv2d(c4, self.ne, 1)) for x in ch) + + def forward(self, x): + """Concatenates and returns predicted bounding boxes and class probabilities.""" + bs = x[0].shape[0] # batch size + angle = torch.cat([self.cv4[i](x[i]).view(bs, self.ne, -1) for i in range(self.nl)], 2) # OBB theta logits + # NOTE: set `angle` as an attribute so that `decode_bboxes` could use it. + angle = (angle.sigmoid() - 0.25) * math.pi # [-pi/4, 3pi/4] + # angle = angle.sigmoid() * math.pi / 2 # [0, pi/2] + if not self.training: + self.angle = angle + x = self.detect(self, x) + if self.training: + return x, angle + return torch.cat([x, angle], 1) if self.export else (torch.cat([x[0], angle], 1), (x[1], angle)) + + def decode_bboxes(self, bboxes, anchors): + """Decode rotated bounding boxes.""" + return dist2rbox(bboxes, self.angle, anchors, dim=1) + + +class Pose(Detect): + """YOLOv8 Pose head for keypoints models.""" + + def __init__(self, nc=80, kpt_shape=(17, 3), ch=()): + """Initialize YOLO network with default parameters and Convolutional Layers.""" + super().__init__(nc, ch) + self.kpt_shape = kpt_shape # number of keypoints, number of dims (2 for x,y or 3 for x,y,visible) + self.nk = kpt_shape[0] * kpt_shape[1] # number of keypoints total + self.detect = Detect.forward + + c4 = max(ch[0] // 4, self.nk) + self.cv4 = nn.ModuleList(nn.Sequential(Conv(x, c4, 3), Conv(c4, c4, 3), nn.Conv2d(c4, self.nk, 1)) for x in ch) + + def forward(self, x): + """Perform forward pass through YOLO model and return predictions.""" + bs = x[0].shape[0] # batch size + kpt = torch.cat([self.cv4[i](x[i]).view(bs, self.nk, -1) for i in range(self.nl)], -1) # (bs, 17*3, h*w) + x = self.detect(self, x) + if self.training: + return x, kpt + pred_kpt = self.kpts_decode(bs, kpt) + return torch.cat([x, pred_kpt], 1) if self.export else (torch.cat([x[0], pred_kpt], 1), (x[1], kpt)) + + def kpts_decode(self, bs, kpts): + """Decodes keypoints.""" + ndim = self.kpt_shape[1] + if self.export: # required for TFLite export to avoid 'PLACEHOLDER_FOR_GREATER_OP_CODES' bug + y = kpts.view(bs, *self.kpt_shape, -1) + a = (y[:, :, :2] * 2.0 + (self.anchors - 0.5)) * self.strides + if ndim == 3: + a = torch.cat((a, y[:, :, 2:3].sigmoid()), 2) + return a.view(bs, self.nk, -1) + else: + y = kpts.clone() + if ndim == 3: + y[:, 2::3] = y[:, 2::3].sigmoid() # sigmoid (WARNING: inplace .sigmoid_() Apple MPS bug) + y[:, 0::ndim] = (y[:, 0::ndim] * 2.0 + (self.anchors[0] - 0.5)) * self.strides + y[:, 1::ndim] = (y[:, 1::ndim] * 2.0 + (self.anchors[1] - 0.5)) * self.strides + return y + + +class Classify(nn.Module): + """YOLOv8 classification head, i.e. x(b,c1,20,20) to x(b,c2).""" + + def __init__(self, c1, c2, k=1, s=1, p=None, g=1): + """Initializes YOLOv8 classification head with specified input and output channels, kernel size, stride, + padding, and groups. + """ + super().__init__() + c_ = 1280 # efficientnet_b0 size + self.conv = Conv(c1, c_, k, s, p, g) + self.pool = nn.AdaptiveAvgPool2d(1) # to x(b,c_,1,1) + self.drop = nn.Dropout(p=0.0, inplace=True) + self.linear = nn.Linear(c_, c2) # to x(b,c2) + + def forward(self, x): + """Performs a forward pass of the YOLO model on input image data.""" + if isinstance(x, list): + x = torch.cat(x, 1) + x = self.linear(self.drop(self.pool(self.conv(x)).flatten(1))) + return x if self.training else x.softmax(1) + + +class WorldDetect(Detect): + def __init__(self, nc=80, embed=512, with_bn=False, ch=()): + """Initialize YOLOv8 detection layer with nc classes and layer channels ch.""" + super().__init__(nc, ch) + c3 = max(ch[0], min(self.nc, 100)) + self.cv3 = nn.ModuleList(nn.Sequential(Conv(x, c3, 3), Conv(c3, c3, 3), nn.Conv2d(c3, embed, 1)) for x in ch) + self.cv4 = nn.ModuleList(BNContrastiveHead(embed) if with_bn else ContrastiveHead() for _ in ch) + + def forward(self, x, text): + """Concatenates and returns predicted bounding boxes and class probabilities.""" + for i in range(self.nl): + x[i] = torch.cat((self.cv2[i](x[i]), self.cv4[i](self.cv3[i](x[i]), text)), 1) + if self.training: + return x + + # Inference path + shape = x[0].shape # BCHW + x_cat = torch.cat([xi.view(shape[0], self.nc + self.reg_max * 4, -1) for xi in x], 2) + if self.dynamic or self.shape != shape: + self.anchors, self.strides = (x.transpose(0, 1) for x in make_anchors(x, self.stride, 0.5)) + self.shape = shape + + if self.export and self.format in {"saved_model", "pb", "tflite", "edgetpu", "tfjs"}: # avoid TF FlexSplitV ops + box = x_cat[:, : self.reg_max * 4] + cls = x_cat[:, self.reg_max * 4 :] + else: + box, cls = x_cat.split((self.reg_max * 4, self.nc), 1) + + if self.export and self.format in {"tflite", "edgetpu"}: + # Precompute normalization factor to increase numerical stability + # See https://github.com/ultralytics/ultralytics/issues/7371 + grid_h = shape[2] + grid_w = shape[3] + grid_size = torch.tensor([grid_w, grid_h, grid_w, grid_h], device=box.device).reshape(1, 4, 1) + norm = self.strides / (self.stride[0] * grid_size) + dbox = self.decode_bboxes(self.dfl(box) * norm, self.anchors.unsqueeze(0) * norm[:, :2]) + else: + dbox = self.decode_bboxes(self.dfl(box), self.anchors.unsqueeze(0)) * self.strides + + y = torch.cat((dbox, cls.sigmoid()), 1) + return y if self.export else (y, x) + + def bias_init(self): + """Initialize Detect() biases, WARNING: requires stride availability.""" + m = self # self.model[-1] # Detect() module + # cf = torch.bincount(torch.tensor(np.concatenate(dataset.labels, 0)[:, 0]).long(), minlength=nc) + 1 + # ncf = math.log(0.6 / (m.nc - 0.999999)) if cf is None else torch.log(cf / cf.sum()) # nominal class frequency + for a, b, s in zip(m.cv2, m.cv3, m.stride): # from + a[-1].bias.data[:] = 1.0 # box + # b[-1].bias.data[:] = math.log(5 / m.nc / (640 / s) ** 2) # cls (.01 objects, 80 classes, 640 img) + + +class RTDETRDecoder(nn.Module): + """ + Real-Time Deformable Transformer Decoder (RTDETRDecoder) module for object detection. + + This decoder module utilizes Transformer architecture along with deformable convolutions to predict bounding boxes + and class labels for objects in an image. It integrates features from multiple layers and runs through a series of + Transformer decoder layers to output the final predictions. + """ + + export = False # export mode + + def __init__( + self, + nc=80, + ch=(512, 1024, 2048), + hd=256, # hidden dim + nq=300, # num queries + ndp=4, # num decoder points + nh=8, # num head + ndl=6, # num decoder layers + d_ffn=1024, # dim of feedforward + dropout=0.0, + act=nn.ReLU(), + eval_idx=-1, + # Training args + nd=100, # num denoising + label_noise_ratio=0.5, + box_noise_scale=1.0, + learnt_init_query=False, + ): + """ + Initializes the RTDETRDecoder module with the given parameters. + + Args: + nc (int): Number of classes. Default is 80. + ch (tuple): Channels in the backbone feature maps. Default is (512, 1024, 2048). + hd (int): Dimension of hidden layers. Default is 256. + nq (int): Number of query points. Default is 300. + ndp (int): Number of decoder points. Default is 4. + nh (int): Number of heads in multi-head attention. Default is 8. + ndl (int): Number of decoder layers. Default is 6. + d_ffn (int): Dimension of the feed-forward networks. Default is 1024. + dropout (float): Dropout rate. Default is 0. + act (nn.Module): Activation function. Default is nn.ReLU. + eval_idx (int): Evaluation index. Default is -1. + nd (int): Number of denoising. Default is 100. + label_noise_ratio (float): Label noise ratio. Default is 0.5. + box_noise_scale (float): Box noise scale. Default is 1.0. + learnt_init_query (bool): Whether to learn initial query embeddings. Default is False. + """ + super().__init__() + self.hidden_dim = hd + self.nhead = nh + self.nl = len(ch) # num level + self.nc = nc + self.num_queries = nq + self.num_decoder_layers = ndl + + # Backbone feature projection + self.input_proj = nn.ModuleList(nn.Sequential(nn.Conv2d(x, hd, 1, bias=False), nn.BatchNorm2d(hd)) for x in ch) + # NOTE: simplified version but it's not consistent with .pt weights. + # self.input_proj = nn.ModuleList(Conv(x, hd, act=False) for x in ch) + + # Transformer module + decoder_layer = DeformableTransformerDecoderLayer(hd, nh, d_ffn, dropout, act, self.nl, ndp) + self.decoder = DeformableTransformerDecoder(hd, decoder_layer, ndl, eval_idx) + + # Denoising part + self.denoising_class_embed = nn.Embedding(nc, hd) + self.num_denoising = nd + self.label_noise_ratio = label_noise_ratio + self.box_noise_scale = box_noise_scale + + # Decoder embedding + self.learnt_init_query = learnt_init_query + if learnt_init_query: + self.tgt_embed = nn.Embedding(nq, hd) + self.query_pos_head = MLP(4, 2 * hd, hd, num_layers=2) + + # Encoder head + self.enc_output = nn.Sequential(nn.Linear(hd, hd), nn.LayerNorm(hd)) + self.enc_score_head = nn.Linear(hd, nc) + self.enc_bbox_head = MLP(hd, hd, 4, num_layers=3) + + # Decoder head + self.dec_score_head = nn.ModuleList([nn.Linear(hd, nc) for _ in range(ndl)]) + self.dec_bbox_head = nn.ModuleList([MLP(hd, hd, 4, num_layers=3) for _ in range(ndl)]) + + self._reset_parameters() + + def forward(self, x, batch=None): + """Runs the forward pass of the module, returning bounding box and classification scores for the input.""" + from ultralytics.models.utils.ops import get_cdn_group + + # Input projection and embedding + feats, shapes = self._get_encoder_input(x) + + # Prepare denoising training + dn_embed, dn_bbox, attn_mask, dn_meta = get_cdn_group( + batch, + self.nc, + self.num_queries, + self.denoising_class_embed.weight, + self.num_denoising, + self.label_noise_ratio, + self.box_noise_scale, + self.training, + ) + + embed, refer_bbox, enc_bboxes, enc_scores = self._get_decoder_input(feats, shapes, dn_embed, dn_bbox) + + # Decoder + dec_bboxes, dec_scores = self.decoder( + embed, + refer_bbox, + feats, + shapes, + self.dec_bbox_head, + self.dec_score_head, + self.query_pos_head, + attn_mask=attn_mask, + ) + x = dec_bboxes, dec_scores, enc_bboxes, enc_scores, dn_meta + if self.training: + return x + # (bs, 300, 4+nc) + y = torch.cat((dec_bboxes.squeeze(0), dec_scores.squeeze(0).sigmoid()), -1) + return y if self.export else (y, x) + + def _generate_anchors(self, shapes, grid_size=0.05, dtype=torch.float32, device="cpu", eps=1e-2): + """Generates anchor bounding boxes for given shapes with specific grid size and validates them.""" + anchors = [] + for i, (h, w) in enumerate(shapes): + sy = torch.arange(end=h, dtype=dtype, device=device) + sx = torch.arange(end=w, dtype=dtype, device=device) + grid_y, grid_x = torch.meshgrid(sy, sx, indexing="ij") if TORCH_1_10 else torch.meshgrid(sy, sx) + grid_xy = torch.stack([grid_x, grid_y], -1) # (h, w, 2) + + valid_WH = torch.tensor([w, h], dtype=dtype, device=device) + grid_xy = (grid_xy.unsqueeze(0) + 0.5) / valid_WH # (1, h, w, 2) + wh = torch.ones_like(grid_xy, dtype=dtype, device=device) * grid_size * (2.0**i) + anchors.append(torch.cat([grid_xy, wh], -1).view(-1, h * w, 4)) # (1, h*w, 4) + + anchors = torch.cat(anchors, 1) # (1, h*w*nl, 4) + valid_mask = ((anchors > eps) & (anchors < 1 - eps)).all(-1, keepdim=True) # 1, h*w*nl, 1 + anchors = torch.log(anchors / (1 - anchors)) + anchors = anchors.masked_fill(~valid_mask, float("inf")) + return anchors, valid_mask + + def _get_encoder_input(self, x): + """Processes and returns encoder inputs by getting projection features from input and concatenating them.""" + # Get projection features + x = [self.input_proj[i](feat) for i, feat in enumerate(x)] + # Get encoder inputs + feats = [] + shapes = [] + for feat in x: + h, w = feat.shape[2:] + # [b, c, h, w] -> [b, h*w, c] + feats.append(feat.flatten(2).permute(0, 2, 1)) + # [nl, 2] + shapes.append([h, w]) + + # [b, h*w, c] + feats = torch.cat(feats, 1) + return feats, shapes + + def _get_decoder_input(self, feats, shapes, dn_embed=None, dn_bbox=None): + """Generates and prepares the input required for the decoder from the provided features and shapes.""" + bs = feats.shape[0] + # Prepare input for decoder + anchors, valid_mask = self._generate_anchors(shapes, dtype=feats.dtype, device=feats.device) + features = self.enc_output(valid_mask * feats) # bs, h*w, 256 + + enc_outputs_scores = self.enc_score_head(features) # (bs, h*w, nc) + + # Query selection + # (bs, num_queries) + topk_ind = torch.topk(enc_outputs_scores.max(-1).values, self.num_queries, dim=1).indices.view(-1) + # (bs, num_queries) + batch_ind = torch.arange(end=bs, dtype=topk_ind.dtype).unsqueeze(-1).repeat(1, self.num_queries).view(-1) + + # (bs, num_queries, 256) + top_k_features = features[batch_ind, topk_ind].view(bs, self.num_queries, -1) + # (bs, num_queries, 4) + top_k_anchors = anchors[:, topk_ind].view(bs, self.num_queries, -1) + + # Dynamic anchors + static content + refer_bbox = self.enc_bbox_head(top_k_features) + top_k_anchors + + enc_bboxes = refer_bbox.sigmoid() + if dn_bbox is not None: + refer_bbox = torch.cat([dn_bbox, refer_bbox], 1) + enc_scores = enc_outputs_scores[batch_ind, topk_ind].view(bs, self.num_queries, -1) + + embeddings = self.tgt_embed.weight.unsqueeze(0).repeat(bs, 1, 1) if self.learnt_init_query else top_k_features + if self.training: + refer_bbox = refer_bbox.detach() + if not self.learnt_init_query: + embeddings = embeddings.detach() + if dn_embed is not None: + embeddings = torch.cat([dn_embed, embeddings], 1) + + return embeddings, refer_bbox, enc_bboxes, enc_scores + + # TODO + def _reset_parameters(self): + """Initializes or resets the parameters of the model's various components with predefined weights and biases.""" + # Class and bbox head init + bias_cls = bias_init_with_prob(0.01) / 80 * self.nc + # NOTE: the weight initialization in `linear_init` would cause NaN when training with custom datasets. + # linear_init(self.enc_score_head) + constant_(self.enc_score_head.bias, bias_cls) + constant_(self.enc_bbox_head.layers[-1].weight, 0.0) + constant_(self.enc_bbox_head.layers[-1].bias, 0.0) + for cls_, reg_ in zip(self.dec_score_head, self.dec_bbox_head): + # linear_init(cls_) + constant_(cls_.bias, bias_cls) + constant_(reg_.layers[-1].weight, 0.0) + constant_(reg_.layers[-1].bias, 0.0) + + linear_init(self.enc_output[0]) + xavier_uniform_(self.enc_output[0].weight) + if self.learnt_init_query: + xavier_uniform_(self.tgt_embed.weight) + xavier_uniform_(self.query_pos_head.layers[0].weight) + xavier_uniform_(self.query_pos_head.layers[1].weight) + for layer in self.input_proj: + xavier_uniform_(layer[0].weight) diff --git a/ultralytics/nn/modules/transformer.py b/ultralytics/nn/modules/transformer.py new file mode 100644 index 0000000..062c609 --- /dev/null +++ b/ultralytics/nn/modules/transformer.py @@ -0,0 +1,426 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +"""Transformer modules.""" + +import math + +import torch +import torch.nn as nn +import torch.nn.functional as F +from torch.nn.init import constant_, xavier_uniform_ + +from .conv import Conv +from .utils import _get_clones, inverse_sigmoid, multi_scale_deformable_attn_pytorch + +__all__ = ( + "TransformerEncoderLayer", + "TransformerLayer", + "TransformerBlock", + "MLPBlock", + "LayerNorm2d", + "AIFI", + "DeformableTransformerDecoder", + "DeformableTransformerDecoderLayer", + "MSDeformAttn", + "MLP", +) + + +class TransformerEncoderLayer(nn.Module): + """Defines a single layer of the transformer encoder.""" + + def __init__(self, c1, cm=2048, num_heads=8, dropout=0.0, act=nn.GELU(), normalize_before=False): + """Initialize the TransformerEncoderLayer with specified parameters.""" + super().__init__() + from ...utils.torch_utils import TORCH_1_9 + + if not TORCH_1_9: + raise ModuleNotFoundError( + "TransformerEncoderLayer() requires torch>=1.9 to use nn.MultiheadAttention(batch_first=True)." + ) + self.ma = nn.MultiheadAttention(c1, num_heads, dropout=dropout, batch_first=True) + # Implementation of Feedforward model + self.fc1 = nn.Linear(c1, cm) + self.fc2 = nn.Linear(cm, c1) + + self.norm1 = nn.LayerNorm(c1) + self.norm2 = nn.LayerNorm(c1) + self.dropout = nn.Dropout(dropout) + self.dropout1 = nn.Dropout(dropout) + self.dropout2 = nn.Dropout(dropout) + + self.act = act + self.normalize_before = normalize_before + + @staticmethod + def with_pos_embed(tensor, pos=None): + """Add position embeddings to the tensor if provided.""" + return tensor if pos is None else tensor + pos + + def forward_post(self, src, src_mask=None, src_key_padding_mask=None, pos=None): + """Performs forward pass with post-normalization.""" + q = k = self.with_pos_embed(src, pos) + src2 = self.ma(q, k, value=src, attn_mask=src_mask, key_padding_mask=src_key_padding_mask)[0] + src = src + self.dropout1(src2) + src = self.norm1(src) + src2 = self.fc2(self.dropout(self.act(self.fc1(src)))) + src = src + self.dropout2(src2) + return self.norm2(src) + + def forward_pre(self, src, src_mask=None, src_key_padding_mask=None, pos=None): + """Performs forward pass with pre-normalization.""" + src2 = self.norm1(src) + q = k = self.with_pos_embed(src2, pos) + src2 = self.ma(q, k, value=src2, attn_mask=src_mask, key_padding_mask=src_key_padding_mask)[0] + src = src + self.dropout1(src2) + src2 = self.norm2(src) + src2 = self.fc2(self.dropout(self.act(self.fc1(src2)))) + return src + self.dropout2(src2) + + def forward(self, src, src_mask=None, src_key_padding_mask=None, pos=None): + """Forward propagates the input through the encoder module.""" + if self.normalize_before: + return self.forward_pre(src, src_mask, src_key_padding_mask, pos) + return self.forward_post(src, src_mask, src_key_padding_mask, pos) + + +class AIFI(TransformerEncoderLayer): + """Defines the AIFI transformer layer.""" + + def __init__(self, c1, cm=2048, num_heads=8, dropout=0, act=nn.GELU(), normalize_before=False): + """Initialize the AIFI instance with specified parameters.""" + super().__init__(c1, cm, num_heads, dropout, act, normalize_before) + + def forward(self, x): + """Forward pass for the AIFI transformer layer.""" + c, h, w = x.shape[1:] + pos_embed = self.build_2d_sincos_position_embedding(w, h, c) + # Flatten [B, C, H, W] to [B, HxW, C] + x = super().forward(x.flatten(2).permute(0, 2, 1), pos=pos_embed.to(device=x.device, dtype=x.dtype)) + return x.permute(0, 2, 1).view([-1, c, h, w]).contiguous() + + @staticmethod + def build_2d_sincos_position_embedding(w, h, embed_dim=256, temperature=10000.0): + """Builds 2D sine-cosine position embedding.""" + assert embed_dim % 4 == 0, "Embed dimension must be divisible by 4 for 2D sin-cos position embedding" + grid_w = torch.arange(w, dtype=torch.float32) + grid_h = torch.arange(h, dtype=torch.float32) + grid_w, grid_h = torch.meshgrid(grid_w, grid_h, indexing="ij") + pos_dim = embed_dim // 4 + omega = torch.arange(pos_dim, dtype=torch.float32) / pos_dim + omega = 1.0 / (temperature**omega) + + out_w = grid_w.flatten()[..., None] @ omega[None] + out_h = grid_h.flatten()[..., None] @ omega[None] + + return torch.cat([torch.sin(out_w), torch.cos(out_w), torch.sin(out_h), torch.cos(out_h)], 1)[None] + + +class TransformerLayer(nn.Module): + """Transformer layer https://arxiv.org/abs/2010.11929 (LayerNorm layers removed for better performance).""" + + def __init__(self, c, num_heads): + """Initializes a self-attention mechanism using linear transformations and multi-head attention.""" + super().__init__() + self.q = nn.Linear(c, c, bias=False) + self.k = nn.Linear(c, c, bias=False) + self.v = nn.Linear(c, c, bias=False) + self.ma = nn.MultiheadAttention(embed_dim=c, num_heads=num_heads) + self.fc1 = nn.Linear(c, c, bias=False) + self.fc2 = nn.Linear(c, c, bias=False) + + def forward(self, x): + """Apply a transformer block to the input x and return the output.""" + x = self.ma(self.q(x), self.k(x), self.v(x))[0] + x + return self.fc2(self.fc1(x)) + x + + +class TransformerBlock(nn.Module): + """Vision Transformer https://arxiv.org/abs/2010.11929.""" + + def __init__(self, c1, c2, num_heads, num_layers): + """Initialize a Transformer module with position embedding and specified number of heads and layers.""" + super().__init__() + self.conv = None + if c1 != c2: + self.conv = Conv(c1, c2) + self.linear = nn.Linear(c2, c2) # learnable position embedding + self.tr = nn.Sequential(*(TransformerLayer(c2, num_heads) for _ in range(num_layers))) + self.c2 = c2 + + def forward(self, x): + """Forward propagates the input through the bottleneck module.""" + if self.conv is not None: + x = self.conv(x) + b, _, w, h = x.shape + p = x.flatten(2).permute(2, 0, 1) + return self.tr(p + self.linear(p)).permute(1, 2, 0).reshape(b, self.c2, w, h) + + +class MLPBlock(nn.Module): + """Implements a single block of a multi-layer perceptron.""" + + def __init__(self, embedding_dim, mlp_dim, act=nn.GELU): + """Initialize the MLPBlock with specified embedding dimension, MLP dimension, and activation function.""" + super().__init__() + self.lin1 = nn.Linear(embedding_dim, mlp_dim) + self.lin2 = nn.Linear(mlp_dim, embedding_dim) + self.act = act() + + def forward(self, x: torch.Tensor) -> torch.Tensor: + """Forward pass for the MLPBlock.""" + return self.lin2(self.act(self.lin1(x))) + + +class MLP(nn.Module): + """Implements a simple multi-layer perceptron (also called FFN).""" + + def __init__(self, input_dim, hidden_dim, output_dim, num_layers): + """Initialize the MLP with specified input, hidden, output dimensions and number of layers.""" + super().__init__() + self.num_layers = num_layers + h = [hidden_dim] * (num_layers - 1) + self.layers = nn.ModuleList(nn.Linear(n, k) for n, k in zip([input_dim] + h, h + [output_dim])) + + def forward(self, x): + """Forward pass for the entire MLP.""" + for i, layer in enumerate(self.layers): + x = F.relu(layer(x)) if i < self.num_layers - 1 else layer(x) + return x + + +class LayerNorm2d(nn.Module): + """ + 2D Layer Normalization module inspired by Detectron2 and ConvNeXt implementations. + + Original implementations in + https://github.com/facebookresearch/detectron2/blob/main/detectron2/layers/batch_norm.py + and + https://github.com/facebookresearch/ConvNeXt/blob/main/models/convnext.py. + """ + + def __init__(self, num_channels, eps=1e-6): + """Initialize LayerNorm2d with the given parameters.""" + super().__init__() + self.weight = nn.Parameter(torch.ones(num_channels)) + self.bias = nn.Parameter(torch.zeros(num_channels)) + self.eps = eps + + def forward(self, x): + """Perform forward pass for 2D layer normalization.""" + u = x.mean(1, keepdim=True) + s = (x - u).pow(2).mean(1, keepdim=True) + x = (x - u) / torch.sqrt(s + self.eps) + return self.weight[:, None, None] * x + self.bias[:, None, None] + + +class MSDeformAttn(nn.Module): + """ + Multiscale Deformable Attention Module based on Deformable-DETR and PaddleDetection implementations. + + https://github.com/fundamentalvision/Deformable-DETR/blob/main/models/ops/modules/ms_deform_attn.py + """ + + def __init__(self, d_model=256, n_levels=4, n_heads=8, n_points=4): + """Initialize MSDeformAttn with the given parameters.""" + super().__init__() + if d_model % n_heads != 0: + raise ValueError(f"d_model must be divisible by n_heads, but got {d_model} and {n_heads}") + _d_per_head = d_model // n_heads + # Better to set _d_per_head to a power of 2 which is more efficient in a CUDA implementation + assert _d_per_head * n_heads == d_model, "`d_model` must be divisible by `n_heads`" + + self.im2col_step = 64 + + self.d_model = d_model + self.n_levels = n_levels + self.n_heads = n_heads + self.n_points = n_points + + self.sampling_offsets = nn.Linear(d_model, n_heads * n_levels * n_points * 2) + self.attention_weights = nn.Linear(d_model, n_heads * n_levels * n_points) + self.value_proj = nn.Linear(d_model, d_model) + self.output_proj = nn.Linear(d_model, d_model) + + self._reset_parameters() + + def _reset_parameters(self): + """Reset module parameters.""" + constant_(self.sampling_offsets.weight.data, 0.0) + thetas = torch.arange(self.n_heads, dtype=torch.float32) * (2.0 * math.pi / self.n_heads) + grid_init = torch.stack([thetas.cos(), thetas.sin()], -1) + grid_init = ( + (grid_init / grid_init.abs().max(-1, keepdim=True)[0]) + .view(self.n_heads, 1, 1, 2) + .repeat(1, self.n_levels, self.n_points, 1) + ) + for i in range(self.n_points): + grid_init[:, :, i, :] *= i + 1 + with torch.no_grad(): + self.sampling_offsets.bias = nn.Parameter(grid_init.view(-1)) + constant_(self.attention_weights.weight.data, 0.0) + constant_(self.attention_weights.bias.data, 0.0) + xavier_uniform_(self.value_proj.weight.data) + constant_(self.value_proj.bias.data, 0.0) + xavier_uniform_(self.output_proj.weight.data) + constant_(self.output_proj.bias.data, 0.0) + + def forward(self, query, refer_bbox, value, value_shapes, value_mask=None): + """ + Perform forward pass for multiscale deformable attention. + + https://github.com/PaddlePaddle/PaddleDetection/blob/develop/ppdet/modeling/transformers/deformable_transformer.py + + Args: + query (torch.Tensor): [bs, query_length, C] + refer_bbox (torch.Tensor): [bs, query_length, n_levels, 2], range in [0, 1], top-left (0,0), + bottom-right (1, 1), including padding area + value (torch.Tensor): [bs, value_length, C] + value_shapes (List): [n_levels, 2], [(H_0, W_0), (H_1, W_1), ..., (H_{L-1}, W_{L-1})] + value_mask (Tensor): [bs, value_length], True for non-padding elements, False for padding elements + + Returns: + output (Tensor): [bs, Length_{query}, C] + """ + bs, len_q = query.shape[:2] + len_v = value.shape[1] + assert sum(s[0] * s[1] for s in value_shapes) == len_v + + value = self.value_proj(value) + if value_mask is not None: + value = value.masked_fill(value_mask[..., None], float(0)) + value = value.view(bs, len_v, self.n_heads, self.d_model // self.n_heads) + sampling_offsets = self.sampling_offsets(query).view(bs, len_q, self.n_heads, self.n_levels, self.n_points, 2) + attention_weights = self.attention_weights(query).view(bs, len_q, self.n_heads, self.n_levels * self.n_points) + attention_weights = F.softmax(attention_weights, -1).view(bs, len_q, self.n_heads, self.n_levels, self.n_points) + # N, Len_q, n_heads, n_levels, n_points, 2 + num_points = refer_bbox.shape[-1] + if num_points == 2: + offset_normalizer = torch.as_tensor(value_shapes, dtype=query.dtype, device=query.device).flip(-1) + add = sampling_offsets / offset_normalizer[None, None, None, :, None, :] + sampling_locations = refer_bbox[:, :, None, :, None, :] + add + elif num_points == 4: + add = sampling_offsets / self.n_points * refer_bbox[:, :, None, :, None, 2:] * 0.5 + sampling_locations = refer_bbox[:, :, None, :, None, :2] + add + else: + raise ValueError(f"Last dim of reference_points must be 2 or 4, but got {num_points}.") + output = multi_scale_deformable_attn_pytorch(value, value_shapes, sampling_locations, attention_weights) + return self.output_proj(output) + + +class DeformableTransformerDecoderLayer(nn.Module): + """ + Deformable Transformer Decoder Layer inspired by PaddleDetection and Deformable-DETR implementations. + + https://github.com/PaddlePaddle/PaddleDetection/blob/develop/ppdet/modeling/transformers/deformable_transformer.py + https://github.com/fundamentalvision/Deformable-DETR/blob/main/models/deformable_transformer.py + """ + + def __init__(self, d_model=256, n_heads=8, d_ffn=1024, dropout=0.0, act=nn.ReLU(), n_levels=4, n_points=4): + """Initialize the DeformableTransformerDecoderLayer with the given parameters.""" + super().__init__() + + # Self attention + self.self_attn = nn.MultiheadAttention(d_model, n_heads, dropout=dropout) + self.dropout1 = nn.Dropout(dropout) + self.norm1 = nn.LayerNorm(d_model) + + # Cross attention + self.cross_attn = MSDeformAttn(d_model, n_levels, n_heads, n_points) + self.dropout2 = nn.Dropout(dropout) + self.norm2 = nn.LayerNorm(d_model) + + # FFN + self.linear1 = nn.Linear(d_model, d_ffn) + self.act = act + self.dropout3 = nn.Dropout(dropout) + self.linear2 = nn.Linear(d_ffn, d_model) + self.dropout4 = nn.Dropout(dropout) + self.norm3 = nn.LayerNorm(d_model) + + @staticmethod + def with_pos_embed(tensor, pos): + """Add positional embeddings to the input tensor, if provided.""" + return tensor if pos is None else tensor + pos + + def forward_ffn(self, tgt): + """Perform forward pass through the Feed-Forward Network part of the layer.""" + tgt2 = self.linear2(self.dropout3(self.act(self.linear1(tgt)))) + tgt = tgt + self.dropout4(tgt2) + return self.norm3(tgt) + + def forward(self, embed, refer_bbox, feats, shapes, padding_mask=None, attn_mask=None, query_pos=None): + """Perform the forward pass through the entire decoder layer.""" + + # Self attention + q = k = self.with_pos_embed(embed, query_pos) + tgt = self.self_attn(q.transpose(0, 1), k.transpose(0, 1), embed.transpose(0, 1), attn_mask=attn_mask)[ + 0 + ].transpose(0, 1) + embed = embed + self.dropout1(tgt) + embed = self.norm1(embed) + + # Cross attention + tgt = self.cross_attn( + self.with_pos_embed(embed, query_pos), refer_bbox.unsqueeze(2), feats, shapes, padding_mask + ) + embed = embed + self.dropout2(tgt) + embed = self.norm2(embed) + + # FFN + return self.forward_ffn(embed) + + +class DeformableTransformerDecoder(nn.Module): + """ + Implementation of Deformable Transformer Decoder based on PaddleDetection. + + https://github.com/PaddlePaddle/PaddleDetection/blob/develop/ppdet/modeling/transformers/deformable_transformer.py + """ + + def __init__(self, hidden_dim, decoder_layer, num_layers, eval_idx=-1): + """Initialize the DeformableTransformerDecoder with the given parameters.""" + super().__init__() + self.layers = _get_clones(decoder_layer, num_layers) + self.num_layers = num_layers + self.hidden_dim = hidden_dim + self.eval_idx = eval_idx if eval_idx >= 0 else num_layers + eval_idx + + def forward( + self, + embed, # decoder embeddings + refer_bbox, # anchor + feats, # image features + shapes, # feature shapes + bbox_head, + score_head, + pos_mlp, + attn_mask=None, + padding_mask=None, + ): + """Perform the forward pass through the entire decoder.""" + output = embed + dec_bboxes = [] + dec_cls = [] + last_refined_bbox = None + refer_bbox = refer_bbox.sigmoid() + for i, layer in enumerate(self.layers): + output = layer(output, refer_bbox, feats, shapes, padding_mask, attn_mask, pos_mlp(refer_bbox)) + + bbox = bbox_head[i](output) + refined_bbox = torch.sigmoid(bbox + inverse_sigmoid(refer_bbox)) + + if self.training: + dec_cls.append(score_head[i](output)) + if i == 0: + dec_bboxes.append(refined_bbox) + else: + dec_bboxes.append(torch.sigmoid(bbox + inverse_sigmoid(last_refined_bbox))) + elif i == self.eval_idx: + dec_cls.append(score_head[i](output)) + dec_bboxes.append(refined_bbox) + break + + last_refined_bbox = refined_bbox + refer_bbox = refined_bbox.detach() if self.training else refined_bbox + + return torch.stack(dec_bboxes), torch.stack(dec_cls) diff --git a/ultralytics/nn/modules/utils.py b/ultralytics/nn/modules/utils.py new file mode 100644 index 0000000..1512967 --- /dev/null +++ b/ultralytics/nn/modules/utils.py @@ -0,0 +1,85 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +"""Module utils.""" + +import copy +import math + +import numpy as np +import torch +import torch.nn as nn +import torch.nn.functional as F +from torch.nn.init import uniform_ + +__all__ = "multi_scale_deformable_attn_pytorch", "inverse_sigmoid" + + +def _get_clones(module, n): + """Create a list of cloned modules from the given module.""" + return nn.ModuleList([copy.deepcopy(module) for _ in range(n)]) + + +def bias_init_with_prob(prior_prob=0.01): + """Initialize conv/fc bias value according to a given probability value.""" + return float(-np.log((1 - prior_prob) / prior_prob)) # return bias_init + + +def linear_init(module): + """Initialize the weights and biases of a linear module.""" + bound = 1 / math.sqrt(module.weight.shape[0]) + uniform_(module.weight, -bound, bound) + if hasattr(module, "bias") and module.bias is not None: + uniform_(module.bias, -bound, bound) + + +def inverse_sigmoid(x, eps=1e-5): + """Calculate the inverse sigmoid function for a tensor.""" + x = x.clamp(min=0, max=1) + x1 = x.clamp(min=eps) + x2 = (1 - x).clamp(min=eps) + return torch.log(x1 / x2) + + +def multi_scale_deformable_attn_pytorch( + value: torch.Tensor, + value_spatial_shapes: torch.Tensor, + sampling_locations: torch.Tensor, + attention_weights: torch.Tensor, +) -> torch.Tensor: + """ + Multiscale deformable attention. + + https://github.com/IDEA-Research/detrex/blob/main/detrex/layers/multi_scale_deform_attn.py + """ + + bs, _, num_heads, embed_dims = value.shape + _, num_queries, num_heads, num_levels, num_points, _ = sampling_locations.shape + value_list = value.split([H_ * W_ for H_, W_ in value_spatial_shapes], dim=1) + sampling_grids = 2 * sampling_locations - 1 + sampling_value_list = [] + for level, (H_, W_) in enumerate(value_spatial_shapes): + # bs, H_*W_, num_heads, embed_dims -> + # bs, H_*W_, num_heads*embed_dims -> + # bs, num_heads*embed_dims, H_*W_ -> + # bs*num_heads, embed_dims, H_, W_ + value_l_ = value_list[level].flatten(2).transpose(1, 2).reshape(bs * num_heads, embed_dims, H_, W_) + # bs, num_queries, num_heads, num_points, 2 -> + # bs, num_heads, num_queries, num_points, 2 -> + # bs*num_heads, num_queries, num_points, 2 + sampling_grid_l_ = sampling_grids[:, :, :, level].transpose(1, 2).flatten(0, 1) + # bs*num_heads, embed_dims, num_queries, num_points + sampling_value_l_ = F.grid_sample( + value_l_, sampling_grid_l_, mode="bilinear", padding_mode="zeros", align_corners=False + ) + sampling_value_list.append(sampling_value_l_) + # (bs, num_queries, num_heads, num_levels, num_points) -> + # (bs, num_heads, num_queries, num_levels, num_points) -> + # (bs, num_heads, 1, num_queries, num_levels*num_points) + attention_weights = attention_weights.transpose(1, 2).reshape( + bs * num_heads, 1, num_queries, num_levels * num_points + ) + output = ( + (torch.stack(sampling_value_list, dim=-2).flatten(-2) * attention_weights) + .sum(-1) + .view(bs, num_heads * embed_dims, num_queries) + ) + return output.transpose(1, 2).contiguous() diff --git a/ultralytics/nn/tasks.py b/ultralytics/nn/tasks.py new file mode 100644 index 0000000..cf3816f --- /dev/null +++ b/ultralytics/nn/tasks.py @@ -0,0 +1,1055 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import contextlib +from copy import deepcopy +from pathlib import Path + +import torch +import torch.nn as nn + +from ultralytics.nn.modules import ( + AIFI, + C1, + C2, + C3, + C3TR, + OBB, + SPP, + SPPELAN, + SPPF, + ADown, + Bottleneck, + BottleneckCSP, + C2f, + C2fAttn, + C3Ghost, + C3x, + CBFuse, + CBLinear, + Classify, + Concat, + Conv, + Conv2, + ConvTranspose, + Detect, + DWConv, + DWConvTranspose2d, + Focus, + GhostBottleneck, + GhostConv, + HGBlock, + HGStem, + ImagePoolingAttn, + Pose, + RepC3, + RepConv, + RepNCSPELAN4, + ResNetLayer, + RTDETRDecoder, + Segment, + Silence, + WorldDetect, +) +from ultralytics.utils import DEFAULT_CFG_DICT, DEFAULT_CFG_KEYS, LOGGER, colorstr, emojis, yaml_load +from ultralytics.utils.checks import check_requirements, check_suffix, check_yaml +from ultralytics.utils.loss import v8ClassificationLoss, v8DetectionLoss, v8OBBLoss, v8PoseLoss, v8SegmentationLoss +from ultralytics.utils.plotting import feature_visualization +from ultralytics.utils.torch_utils import ( + fuse_conv_and_bn, + fuse_deconv_and_bn, + initialize_weights, + intersect_dicts, + make_divisible, + model_info, + scale_img, + time_sync, +) + +try: + import thop +except ImportError: + thop = None + + +class BaseModel(nn.Module): + """The BaseModel class serves as a base class for all the models in the Ultralytics YOLO family.""" + + def forward(self, x, *args, **kwargs): + """ + Forward pass of the model on a single scale. Wrapper for `_forward_once` method. + + Args: + x (torch.Tensor | dict): The input image tensor or a dict including image tensor and gt labels. + + Returns: + (torch.Tensor): The output of the network. + """ + if isinstance(x, dict): # for cases of training and validating while training. + return self.loss(x, *args, **kwargs) + return self.predict(x, *args, **kwargs) + + def predict(self, x, profile=False, visualize=False, augment=False, embed=None): + """ + Perform a forward pass through the network. + + Args: + x (torch.Tensor): The input tensor to the model. + profile (bool): Print the computation time of each layer if True, defaults to False. + visualize (bool): Save the feature maps of the model if True, defaults to False. + augment (bool): Augment image during prediction, defaults to False. + embed (list, optional): A list of feature vectors/embeddings to return. + + Returns: + (torch.Tensor): The last output of the model. + """ + if augment: + return self._predict_augment(x) + return self._predict_once(x, profile, visualize, embed) + + def _predict_once(self, x, profile=False, visualize=False, embed=None): + """ + Perform a forward pass through the network. + + Args: + x (torch.Tensor): The input tensor to the model. + profile (bool): Print the computation time of each layer if True, defaults to False. + visualize (bool): Save the feature maps of the model if True, defaults to False. + embed (list, optional): A list of feature vectors/embeddings to return. + + Returns: + (torch.Tensor): The last output of the model. + """ + y, dt, embeddings = [], [], [] # outputs + for m in self.model: + if m.f != -1: # if not from previous layer + x = y[m.f] if isinstance(m.f, int) else [x if j == -1 else y[j] for j in m.f] # from earlier layers + if profile: + self._profile_one_layer(m, x, dt) + x = m(x) # run + y.append(x if m.i in self.save else None) # save output + if visualize: + feature_visualization(x, m.type, m.i, save_dir=visualize) + if embed and m.i in embed: + embeddings.append(nn.functional.adaptive_avg_pool2d(x, (1, 1)).squeeze(-1).squeeze(-1)) # flatten + if m.i == max(embed): + return torch.unbind(torch.cat(embeddings, 1), dim=0) + return x + + def _predict_augment(self, x): + """Perform augmentations on input image x and return augmented inference.""" + LOGGER.warning( + f"WARNING ⚠️ {self.__class__.__name__} does not support augmented inference yet. " + f"Reverting to single-scale inference instead." + ) + return self._predict_once(x) + + def _profile_one_layer(self, m, x, dt): + """ + Profile the computation time and FLOPs of a single layer of the model on a given input. Appends the results to + the provided list. + + Args: + m (nn.Module): The layer to be profiled. + x (torch.Tensor): The input data to the layer. + dt (list): A list to store the computation time of the layer. + + Returns: + None + """ + c = m == self.model[-1] and isinstance(x, list) # is final layer list, copy input as inplace fix + flops = thop.profile(m, inputs=[x.copy() if c else x], verbose=False)[0] / 1e9 * 2 if thop else 0 # FLOPs + t = time_sync() + for _ in range(10): + m(x.copy() if c else x) + dt.append((time_sync() - t) * 100) + if m == self.model[0]: + LOGGER.info(f"{'time (ms)':>10s} {'GFLOPs':>10s} {'params':>10s} module") + LOGGER.info(f"{dt[-1]:10.2f} {flops:10.2f} {m.np:10.0f} {m.type}") + if c: + LOGGER.info(f"{sum(dt):10.2f} {'-':>10s} {'-':>10s} Total") + + def fuse(self, verbose=True): + """ + Fuse the `Conv2d()` and `BatchNorm2d()` layers of the model into a single layer, in order to improve the + computation efficiency. + + Returns: + (nn.Module): The fused model is returned. + """ + if not self.is_fused(): + for m in self.model.modules(): + if isinstance(m, (Conv, Conv2, DWConv)) and hasattr(m, "bn"): + if isinstance(m, Conv2): + m.fuse_convs() + m.conv = fuse_conv_and_bn(m.conv, m.bn) # update conv + delattr(m, "bn") # remove batchnorm + m.forward = m.forward_fuse # update forward + if isinstance(m, ConvTranspose) and hasattr(m, "bn"): + m.conv_transpose = fuse_deconv_and_bn(m.conv_transpose, m.bn) + delattr(m, "bn") # remove batchnorm + m.forward = m.forward_fuse # update forward + if isinstance(m, RepConv): + m.fuse_convs() + m.forward = m.forward_fuse # update forward + self.info(verbose=verbose) + + return self + + def is_fused(self, thresh=10): + """ + Check if the model has less than a certain threshold of BatchNorm layers. + + Args: + thresh (int, optional): The threshold number of BatchNorm layers. Default is 10. + + Returns: + (bool): True if the number of BatchNorm layers in the model is less than the threshold, False otherwise. + """ + bn = tuple(v for k, v in nn.__dict__.items() if "Norm" in k) # normalization layers, i.e. BatchNorm2d() + return sum(isinstance(v, bn) for v in self.modules()) < thresh # True if < 'thresh' BatchNorm layers in model + + def info(self, detailed=False, verbose=True, imgsz=640): + """ + Prints model information. + + Args: + detailed (bool): if True, prints out detailed information about the model. Defaults to False + verbose (bool): if True, prints out the model information. Defaults to False + imgsz (int): the size of the image that the model will be trained on. Defaults to 640 + """ + return model_info(self, detailed=detailed, verbose=verbose, imgsz=imgsz) + + def _apply(self, fn): + """ + Applies a function to all the tensors in the model that are not parameters or registered buffers. + + Args: + fn (function): the function to apply to the model + + Returns: + (BaseModel): An updated BaseModel object. + """ + self = super()._apply(fn) + m = self.model[-1] # Detect() + if isinstance(m, Detect): # includes all Detect subclasses like Segment, Pose, OBB, WorldDetect + m.stride = fn(m.stride) + m.anchors = fn(m.anchors) + m.strides = fn(m.strides) + return self + + def load(self, weights, verbose=True): + """ + Load the weights into the model. + + Args: + weights (dict | torch.nn.Module): The pre-trained weights to be loaded. + verbose (bool, optional): Whether to log the transfer progress. Defaults to True. + """ + model = weights["model"] if isinstance(weights, dict) else weights # torchvision models are not dicts + csd = model.float().state_dict() # checkpoint state_dict as FP32 + csd = intersect_dicts(csd, self.state_dict()) # intersect + self.load_state_dict(csd, strict=False) # load + if verbose: + LOGGER.info(f"Transferred {len(csd)}/{len(self.model.state_dict())} items from pretrained weights") + + def loss(self, batch, preds=None): + """ + Compute loss. + + Args: + batch (dict): Batch to compute loss on + preds (torch.Tensor | List[torch.Tensor]): Predictions. + """ + if not hasattr(self, "criterion"): + self.criterion = self.init_criterion() + + preds = self.forward(batch["img"]) if preds is None else preds + return self.criterion(preds, batch) + + def init_criterion(self): + """Initialize the loss criterion for the BaseModel.""" + raise NotImplementedError("compute_loss() needs to be implemented by task heads") + + +class DetectionModel(BaseModel): + """YOLOv8 detection model.""" + + def __init__(self, cfg="yolov8n.yaml", ch=3, nc=None, verbose=True): # model, input channels, number of classes + """Initialize the YOLOv8 detection model with the given config and parameters.""" + super().__init__() + self.yaml = cfg if isinstance(cfg, dict) else yaml_model_load(cfg) # cfg dict + + # Define model + ch = self.yaml["ch"] = self.yaml.get("ch", ch) # input channels + if nc and nc != self.yaml["nc"]: + LOGGER.info(f"Overriding model.yaml nc={self.yaml['nc']} with nc={nc}") + self.yaml["nc"] = nc # override YAML value + self.model, self.save = parse_model(deepcopy(self.yaml), ch=ch, verbose=verbose) # model, savelist + self.names = {i: f"{i}" for i in range(self.yaml["nc"])} # default names dict + self.inplace = self.yaml.get("inplace", True) + + # Build strides + m = self.model[-1] # Detect() + if isinstance(m, Detect): # includes all Detect subclasses like Segment, Pose, OBB, WorldDetect + s = 256 # 2x min stride + m.inplace = self.inplace + forward = lambda x: self.forward(x)[0] if isinstance(m, (Segment, Pose, OBB)) else self.forward(x) + m.stride = torch.tensor([s / x.shape[-2] for x in forward(torch.zeros(1, ch, s, s))]) # forward + self.stride = m.stride + m.bias_init() # only run once + else: + self.stride = torch.Tensor([32]) # default stride for i.e. RTDETR + + # Init weights, biases + initialize_weights(self) + if verbose: + self.info() + LOGGER.info("") + + def _predict_augment(self, x): + """Perform augmentations on input image x and return augmented inference and train outputs.""" + img_size = x.shape[-2:] # height, width + s = [1, 0.83, 0.67] # scales + f = [None, 3, None] # flips (2-ud, 3-lr) + y = [] # outputs + for si, fi in zip(s, f): + xi = scale_img(x.flip(fi) if fi else x, si, gs=int(self.stride.max())) + yi = super().predict(xi)[0] # forward + yi = self._descale_pred(yi, fi, si, img_size) + y.append(yi) + y = self._clip_augmented(y) # clip augmented tails + return torch.cat(y, -1), None # augmented inference, train + + @staticmethod + def _descale_pred(p, flips, scale, img_size, dim=1): + """De-scale predictions following augmented inference (inverse operation).""" + p[:, :4] /= scale # de-scale + x, y, wh, cls = p.split((1, 1, 2, p.shape[dim] - 4), dim) + if flips == 2: + y = img_size[0] - y # de-flip ud + elif flips == 3: + x = img_size[1] - x # de-flip lr + return torch.cat((x, y, wh, cls), dim) + + def _clip_augmented(self, y): + """Clip YOLO augmented inference tails.""" + nl = self.model[-1].nl # number of detection layers (P3-P5) + g = sum(4**x for x in range(nl)) # grid points + e = 1 # exclude layer count + i = (y[0].shape[-1] // g) * sum(4**x for x in range(e)) # indices + y[0] = y[0][..., :-i] # large + i = (y[-1].shape[-1] // g) * sum(4 ** (nl - 1 - x) for x in range(e)) # indices + y[-1] = y[-1][..., i:] # small + return y + + def init_criterion(self): + """Initialize the loss criterion for the DetectionModel.""" + return v8DetectionLoss(self) + + +class OBBModel(DetectionModel): + """YOLOv8 Oriented Bounding Box (OBB) model.""" + + def __init__(self, cfg="yolov8n-obb.yaml", ch=3, nc=None, verbose=True): + """Initialize YOLOv8 OBB model with given config and parameters.""" + super().__init__(cfg=cfg, ch=ch, nc=nc, verbose=verbose) + + def init_criterion(self): + """Initialize the loss criterion for the model.""" + return v8OBBLoss(self) + + +class SegmentationModel(DetectionModel): + """YOLOv8 segmentation model.""" + + def __init__(self, cfg="yolov8n-seg.yaml", ch=3, nc=None, verbose=True): + """Initialize YOLOv8 segmentation model with given config and parameters.""" + super().__init__(cfg=cfg, ch=ch, nc=nc, verbose=verbose) + + def init_criterion(self): + """Initialize the loss criterion for the SegmentationModel.""" + return v8SegmentationLoss(self) + + +class PoseModel(DetectionModel): + """YOLOv8 pose model.""" + + def __init__(self, cfg="yolov8n-pose.yaml", ch=3, nc=None, data_kpt_shape=(None, None), verbose=True): + """Initialize YOLOv8 Pose model.""" + if not isinstance(cfg, dict): + cfg = yaml_model_load(cfg) # load model YAML + if any(data_kpt_shape) and list(data_kpt_shape) != list(cfg["kpt_shape"]): + LOGGER.info(f"Overriding model.yaml kpt_shape={cfg['kpt_shape']} with kpt_shape={data_kpt_shape}") + cfg["kpt_shape"] = data_kpt_shape + super().__init__(cfg=cfg, ch=ch, nc=nc, verbose=verbose) + + def init_criterion(self): + """Initialize the loss criterion for the PoseModel.""" + return v8PoseLoss(self) + + +class ClassificationModel(BaseModel): + """YOLOv8 classification model.""" + + def __init__(self, cfg="yolov8n-cls.yaml", ch=3, nc=None, verbose=True): + """Init ClassificationModel with YAML, channels, number of classes, verbose flag.""" + super().__init__() + self._from_yaml(cfg, ch, nc, verbose) + + def _from_yaml(self, cfg, ch, nc, verbose): + """Set YOLOv8 model configurations and define the model architecture.""" + self.yaml = cfg if isinstance(cfg, dict) else yaml_model_load(cfg) # cfg dict + + # Define model + ch = self.yaml["ch"] = self.yaml.get("ch", ch) # input channels + if nc and nc != self.yaml["nc"]: + LOGGER.info(f"Overriding model.yaml nc={self.yaml['nc']} with nc={nc}") + self.yaml["nc"] = nc # override YAML value + elif not nc and not self.yaml.get("nc", None): + raise ValueError("nc not specified. Must specify nc in model.yaml or function arguments.") + self.model, self.save = parse_model(deepcopy(self.yaml), ch=ch, verbose=verbose) # model, savelist + self.stride = torch.Tensor([1]) # no stride constraints + self.names = {i: f"{i}" for i in range(self.yaml["nc"])} # default names dict + self.info() + + @staticmethod + def reshape_outputs(model, nc): + """Update a TorchVision classification model to class count 'n' if required.""" + name, m = list((model.model if hasattr(model, "model") else model).named_children())[-1] # last module + if isinstance(m, Classify): # YOLO Classify() head + if m.linear.out_features != nc: + m.linear = nn.Linear(m.linear.in_features, nc) + elif isinstance(m, nn.Linear): # ResNet, EfficientNet + if m.out_features != nc: + setattr(model, name, nn.Linear(m.in_features, nc)) + elif isinstance(m, nn.Sequential): + types = [type(x) for x in m] + if nn.Linear in types: + i = types.index(nn.Linear) # nn.Linear index + if m[i].out_features != nc: + m[i] = nn.Linear(m[i].in_features, nc) + elif nn.Conv2d in types: + i = types.index(nn.Conv2d) # nn.Conv2d index + if m[i].out_channels != nc: + m[i] = nn.Conv2d(m[i].in_channels, nc, m[i].kernel_size, m[i].stride, bias=m[i].bias is not None) + + def init_criterion(self): + """Initialize the loss criterion for the ClassificationModel.""" + return v8ClassificationLoss() + + +class RTDETRDetectionModel(DetectionModel): + """ + RTDETR (Real-time DEtection and Tracking using Transformers) Detection Model class. + + This class is responsible for constructing the RTDETR architecture, defining loss functions, and facilitating both + the training and inference processes. RTDETR is an object detection and tracking model that extends from the + DetectionModel base class. + + Attributes: + cfg (str): The configuration file path or preset string. Default is 'rtdetr-l.yaml'. + ch (int): Number of input channels. Default is 3 (RGB). + nc (int, optional): Number of classes for object detection. Default is None. + verbose (bool): Specifies if summary statistics are shown during initialization. Default is True. + + Methods: + init_criterion: Initializes the criterion used for loss calculation. + loss: Computes and returns the loss during training. + predict: Performs a forward pass through the network and returns the output. + """ + + def __init__(self, cfg="rtdetr-l.yaml", ch=3, nc=None, verbose=True): + """ + Initialize the RTDETRDetectionModel. + + Args: + cfg (str): Configuration file name or path. + ch (int): Number of input channels. + nc (int, optional): Number of classes. Defaults to None. + verbose (bool, optional): Print additional information during initialization. Defaults to True. + """ + super().__init__(cfg=cfg, ch=ch, nc=nc, verbose=verbose) + + def init_criterion(self): + """Initialize the loss criterion for the RTDETRDetectionModel.""" + from ultralytics.models.utils.loss import RTDETRDetectionLoss + + return RTDETRDetectionLoss(nc=self.nc, use_vfl=True) + + def loss(self, batch, preds=None): + """ + Compute the loss for the given batch of data. + + Args: + batch (dict): Dictionary containing image and label data. + preds (torch.Tensor, optional): Precomputed model predictions. Defaults to None. + + Returns: + (tuple): A tuple containing the total loss and main three losses in a tensor. + """ + if not hasattr(self, "criterion"): + self.criterion = self.init_criterion() + + img = batch["img"] + # NOTE: preprocess gt_bbox and gt_labels to list. + bs = len(img) + batch_idx = batch["batch_idx"] + gt_groups = [(batch_idx == i).sum().item() for i in range(bs)] + targets = { + "cls": batch["cls"].to(img.device, dtype=torch.long).view(-1), + "bboxes": batch["bboxes"].to(device=img.device), + "batch_idx": batch_idx.to(img.device, dtype=torch.long).view(-1), + "gt_groups": gt_groups, + } + + preds = self.predict(img, batch=targets) if preds is None else preds + dec_bboxes, dec_scores, enc_bboxes, enc_scores, dn_meta = preds if self.training else preds[1] + if dn_meta is None: + dn_bboxes, dn_scores = None, None + else: + dn_bboxes, dec_bboxes = torch.split(dec_bboxes, dn_meta["dn_num_split"], dim=2) + dn_scores, dec_scores = torch.split(dec_scores, dn_meta["dn_num_split"], dim=2) + + dec_bboxes = torch.cat([enc_bboxes.unsqueeze(0), dec_bboxes]) # (7, bs, 300, 4) + dec_scores = torch.cat([enc_scores.unsqueeze(0), dec_scores]) + + loss = self.criterion( + (dec_bboxes, dec_scores), targets, dn_bboxes=dn_bboxes, dn_scores=dn_scores, dn_meta=dn_meta + ) + # NOTE: There are like 12 losses in RTDETR, backward with all losses but only show the main three losses. + return sum(loss.values()), torch.as_tensor( + [loss[k].detach() for k in ["loss_giou", "loss_class", "loss_bbox"]], device=img.device + ) + + def predict(self, x, profile=False, visualize=False, batch=None, augment=False, embed=None): + """ + Perform a forward pass through the model. + + Args: + x (torch.Tensor): The input tensor. + profile (bool, optional): If True, profile the computation time for each layer. Defaults to False. + visualize (bool, optional): If True, save feature maps for visualization. Defaults to False. + batch (dict, optional): Ground truth data for evaluation. Defaults to None. + augment (bool, optional): If True, perform data augmentation during inference. Defaults to False. + embed (list, optional): A list of feature vectors/embeddings to return. + + Returns: + (torch.Tensor): Model's output tensor. + """ + y, dt, embeddings = [], [], [] # outputs + for m in self.model[:-1]: # except the head part + if m.f != -1: # if not from previous layer + x = y[m.f] if isinstance(m.f, int) else [x if j == -1 else y[j] for j in m.f] # from earlier layers + if profile: + self._profile_one_layer(m, x, dt) + x = m(x) # run + y.append(x if m.i in self.save else None) # save output + if visualize: + feature_visualization(x, m.type, m.i, save_dir=visualize) + if embed and m.i in embed: + embeddings.append(nn.functional.adaptive_avg_pool2d(x, (1, 1)).squeeze(-1).squeeze(-1)) # flatten + if m.i == max(embed): + return torch.unbind(torch.cat(embeddings, 1), dim=0) + head = self.model[-1] + x = head([y[j] for j in head.f], batch) # head inference + return x + + +class WorldModel(DetectionModel): + """YOLOv8 World Model.""" + + def __init__(self, cfg="yolov8s-world.yaml", ch=3, nc=None, verbose=True): + """Initialize YOLOv8 world model with given config and parameters.""" + self.txt_feats = torch.randn(1, nc or 80, 512) # features placeholder + self.clip_model = None # CLIP model placeholder + super().__init__(cfg=cfg, ch=ch, nc=nc, verbose=verbose) + + def set_classes(self, text, batch=80, cache_clip_model=True): + """Set classes in advance so that model could do offline-inference without clip model.""" + try: + import clip + except ImportError: + check_requirements("git+https://github.com/ultralytics/CLIP.git") + import clip + + if ( + not getattr(self, "clip_model", None) and cache_clip_model + ): # for backwards compatibility of models lacking clip_model attribute + self.clip_model = clip.load("ViT-B/32")[0] + model = self.clip_model if cache_clip_model else clip.load("ViT-B/32")[0] + device = next(model.parameters()).device + text_token = clip.tokenize(text).to(device) + txt_feats = [model.encode_text(token).detach() for token in text_token.split(batch)] + txt_feats = txt_feats[0] if len(txt_feats) == 1 else torch.cat(txt_feats, dim=0) + txt_feats = txt_feats / txt_feats.norm(p=2, dim=-1, keepdim=True) + self.txt_feats = txt_feats.reshape(-1, len(text), txt_feats.shape[-1]) + self.model[-1].nc = len(text) + + def predict(self, x, profile=False, visualize=False, txt_feats=None, augment=False, embed=None): + """ + Perform a forward pass through the model. + + Args: + x (torch.Tensor): The input tensor. + profile (bool, optional): If True, profile the computation time for each layer. Defaults to False. + visualize (bool, optional): If True, save feature maps for visualization. Defaults to False. + txt_feats (torch.Tensor): The text features, use it if it's given. Defaults to None. + augment (bool, optional): If True, perform data augmentation during inference. Defaults to False. + embed (list, optional): A list of feature vectors/embeddings to return. + + Returns: + (torch.Tensor): Model's output tensor. + """ + txt_feats = (self.txt_feats if txt_feats is None else txt_feats).to(device=x.device, dtype=x.dtype) + if len(txt_feats) != len(x): + txt_feats = txt_feats.repeat(len(x), 1, 1) + ori_txt_feats = txt_feats.clone() + y, dt, embeddings = [], [], [] # outputs + for m in self.model: # except the head part + if m.f != -1: # if not from previous layer + x = y[m.f] if isinstance(m.f, int) else [x if j == -1 else y[j] for j in m.f] # from earlier layers + if profile: + self._profile_one_layer(m, x, dt) + if isinstance(m, C2fAttn): + x = m(x, txt_feats) + elif isinstance(m, WorldDetect): + x = m(x, ori_txt_feats) + elif isinstance(m, ImagePoolingAttn): + txt_feats = m(x, txt_feats) + else: + x = m(x) # run + + y.append(x if m.i in self.save else None) # save output + if visualize: + feature_visualization(x, m.type, m.i, save_dir=visualize) + if embed and m.i in embed: + embeddings.append(nn.functional.adaptive_avg_pool2d(x, (1, 1)).squeeze(-1).squeeze(-1)) # flatten + if m.i == max(embed): + return torch.unbind(torch.cat(embeddings, 1), dim=0) + return x + + def loss(self, batch, preds=None): + """ + Compute loss. + + Args: + batch (dict): Batch to compute loss on. + preds (torch.Tensor | List[torch.Tensor]): Predictions. + """ + if not hasattr(self, "criterion"): + self.criterion = self.init_criterion() + + if preds is None: + preds = self.forward(batch["img"], txt_feats=batch["txt_feats"]) + return self.criterion(preds, batch) + + +class Ensemble(nn.ModuleList): + """Ensemble of models.""" + + def __init__(self): + """Initialize an ensemble of models.""" + super().__init__() + + def forward(self, x, augment=False, profile=False, visualize=False): + """Function generates the YOLO network's final layer.""" + y = [module(x, augment, profile, visualize)[0] for module in self] + # y = torch.stack(y).max(0)[0] # max ensemble + # y = torch.stack(y).mean(0) # mean ensemble + y = torch.cat(y, 2) # nms ensemble, y shape(B, HW, C) + return y, None # inference, train output + + +# Functions ------------------------------------------------------------------------------------------------------------ + + +@contextlib.contextmanager +def temporary_modules(modules=None): + """ + Context manager for temporarily adding or modifying modules in Python's module cache (`sys.modules`). + + This function can be used to change the module paths during runtime. It's useful when refactoring code, + where you've moved a module from one location to another, but you still want to support the old import + paths for backwards compatibility. + + Args: + modules (dict, optional): A dictionary mapping old module paths to new module paths. + + Example: + ```python + with temporary_modules({'old.module.path': 'new.module.path'}): + import old.module.path # this will now import new.module.path + ``` + + Note: + The changes are only in effect inside the context manager and are undone once the context manager exits. + Be aware that directly manipulating `sys.modules` can lead to unpredictable results, especially in larger + applications or libraries. Use this function with caution. + """ + if not modules: + modules = {} + + import importlib + import sys + + try: + # Set modules in sys.modules under their old name + for old, new in modules.items(): + sys.modules[old] = importlib.import_module(new) + + yield + finally: + # Remove the temporary module paths + for old in modules: + if old in sys.modules: + del sys.modules[old] + + +def torch_safe_load(weight): + """ + This function attempts to load a PyTorch model with the torch.load() function. If a ModuleNotFoundError is raised, + it catches the error, logs a warning message, and attempts to install the missing module via the + check_requirements() function. After installation, the function again attempts to load the model using torch.load(). + + Args: + weight (str): The file path of the PyTorch model. + + Returns: + (dict): The loaded PyTorch model. + """ + from ultralytics.utils.downloads import attempt_download_asset + + check_suffix(file=weight, suffix=".pt") + file = attempt_download_asset(weight) # search online if missing locally + try: + with temporary_modules( + { + "ultralytics.yolo.utils": "ultralytics.utils", + "ultralytics.yolo.v8": "ultralytics.models.yolo", + "ultralytics.yolo.data": "ultralytics.data", + } + ): # for legacy 8.0 Classify and Pose models + ckpt = torch.load(file, map_location="cpu") + + except ModuleNotFoundError as e: # e.name is missing module name + if e.name == "models": + raise TypeError( + emojis( + f"ERROR ❌️ {weight} appears to be an Ultralytics YOLOv5 model originally trained " + f"with https://github.com/ultralytics/yolov5.\nThis model is NOT forwards compatible with " + f"YOLOv8 at https://github.com/ultralytics/ultralytics." + f"\nRecommend fixes are to train a new model using the latest 'ultralytics' package or to " + f"run a command with an official YOLOv8 model, i.e. 'yolo predict model=yolov8n.pt'" + ) + ) from e + LOGGER.warning( + f"WARNING ⚠️ {weight} appears to require '{e.name}', which is not in ultralytics requirements." + f"\nAutoInstall will run now for '{e.name}' but this feature will be removed in the future." + f"\nRecommend fixes are to train a new model using the latest 'ultralytics' package or to " + f"run a command with an official YOLOv8 model, i.e. 'yolo predict model=yolov8n.pt'" + ) + check_requirements(e.name) # install missing module + ckpt = torch.load(file, map_location="cpu") + + if not isinstance(ckpt, dict): + # File is likely a YOLO instance saved with i.e. torch.save(model, "saved_model.pt") + LOGGER.warning( + f"WARNING ⚠️ The file '{weight}' appears to be improperly saved or formatted. " + f"For optimal results, use model.save('filename.pt') to correctly save YOLO models." + ) + ckpt = {"model": ckpt.model} + + return ckpt, file # load + + +def attempt_load_weights(weights, device=None, inplace=True, fuse=False): + """Loads an ensemble of models weights=[a,b,c] or a single model weights=[a] or weights=a.""" + + ensemble = Ensemble() + for w in weights if isinstance(weights, list) else [weights]: + ckpt, w = torch_safe_load(w) # load ckpt + args = {**DEFAULT_CFG_DICT, **ckpt["train_args"]} if "train_args" in ckpt else None # combined args + model = (ckpt.get("ema") or ckpt["model"]).to(device).float() # FP32 model + + # Model compatibility updates + model.args = args # attach args to model + model.pt_path = w # attach *.pt file path to model + model.task = guess_model_task(model) + if not hasattr(model, "stride"): + model.stride = torch.tensor([32.0]) + + # Append + ensemble.append(model.fuse().eval() if fuse and hasattr(model, "fuse") else model.eval()) # model in eval mode + + # Module updates + for m in ensemble.modules(): + if hasattr(m, "inplace"): + m.inplace = inplace + elif isinstance(m, nn.Upsample) and not hasattr(m, "recompute_scale_factor"): + m.recompute_scale_factor = None # torch 1.11.0 compatibility + + # Return model + if len(ensemble) == 1: + return ensemble[-1] + + # Return ensemble + LOGGER.info(f"Ensemble created with {weights}\n") + for k in "names", "nc", "yaml": + setattr(ensemble, k, getattr(ensemble[0], k)) + ensemble.stride = ensemble[int(torch.argmax(torch.tensor([m.stride.max() for m in ensemble])))].stride + assert all(ensemble[0].nc == m.nc for m in ensemble), f"Models differ in class counts {[m.nc for m in ensemble]}" + return ensemble + + +def attempt_load_one_weight(weight, device=None, inplace=True, fuse=False): + """Loads a single model weights.""" + ckpt, weight = torch_safe_load(weight) # load ckpt + args = {**DEFAULT_CFG_DICT, **(ckpt.get("train_args", {}))} # combine model and default args, preferring model args + model = (ckpt.get("ema") or ckpt["model"]).to(device).float() # FP32 model + + # Model compatibility updates + model.args = {k: v for k, v in args.items() if k in DEFAULT_CFG_KEYS} # attach args to model + model.pt_path = weight # attach *.pt file path to model + model.task = guess_model_task(model) + if not hasattr(model, "stride"): + model.stride = torch.tensor([32.0]) + + model = model.fuse().eval() if fuse and hasattr(model, "fuse") else model.eval() # model in eval mode + + # Module updates + for m in model.modules(): + if hasattr(m, "inplace"): + m.inplace = inplace + elif isinstance(m, nn.Upsample) and not hasattr(m, "recompute_scale_factor"): + m.recompute_scale_factor = None # torch 1.11.0 compatibility + + # Return model and ckpt + return model, ckpt + + +def parse_model(d, ch, verbose=True): # model_dict, input_channels(3) + """Parse a YOLO model.yaml dictionary into a PyTorch model.""" + import ast + + # Args + max_channels = float("inf") + nc, act, scales = (d.get(x) for x in ("nc", "activation", "scales")) + depth, width, kpt_shape = (d.get(x, 1.0) for x in ("depth_multiple", "width_multiple", "kpt_shape")) + if scales: + scale = d.get("scale") + if not scale: + scale = tuple(scales.keys())[0] + LOGGER.warning(f"WARNING ⚠️ no model scale passed. Assuming scale='{scale}'.") + depth, width, max_channels = scales[scale] + + if act: + Conv.default_act = eval(act) # redefine default activation, i.e. Conv.default_act = nn.SiLU() + if verbose: + LOGGER.info(f"{colorstr('activation:')} {act}") # print + + if verbose: + LOGGER.info(f"\n{'':>3}{'from':>20}{'n':>3}{'params':>10} {'module':<45}{'arguments':<30}") + ch = [ch] + layers, save, c2 = [], [], ch[-1] # layers, savelist, ch out + for i, (f, n, m, args) in enumerate(d["backbone"] + d["head"]): # from, number, module, args + m = getattr(torch.nn, m[3:]) if "nn." in m else globals()[m] # get module + for j, a in enumerate(args): + if isinstance(a, str): + with contextlib.suppress(ValueError): + args[j] = locals()[a] if a in locals() else ast.literal_eval(a) + + n = n_ = max(round(n * depth), 1) if n > 1 else n # depth gain + if m in { + Classify, + Conv, + ConvTranspose, + GhostConv, + Bottleneck, + GhostBottleneck, + SPP, + SPPF, + DWConv, + Focus, + BottleneckCSP, + C1, + C2, + C2f, + RepNCSPELAN4, + ADown, + SPPELAN, + C2fAttn, + C3, + C3TR, + C3Ghost, + nn.ConvTranspose2d, + DWConvTranspose2d, + C3x, + RepC3, + }: + c1, c2 = ch[f], args[0] + if c2 != nc: # if c2 not equal to number of classes (i.e. for Classify() output) + c2 = make_divisible(min(c2, max_channels) * width, 8) + if m is C2fAttn: + args[1] = make_divisible(min(args[1], max_channels // 2) * width, 8) # embed channels + args[2] = int( + max(round(min(args[2], max_channels // 2 // 32)) * width, 1) if args[2] > 1 else args[2] + ) # num heads + + args = [c1, c2, *args[1:]] + if m in {BottleneckCSP, C1, C2, C2f, C2fAttn, C3, C3TR, C3Ghost, C3x, RepC3}: + args.insert(2, n) # number of repeats + n = 1 + elif m is AIFI: + args = [ch[f], *args] + elif m in {HGStem, HGBlock}: + c1, cm, c2 = ch[f], args[0], args[1] + args = [c1, cm, c2, *args[2:]] + if m is HGBlock: + args.insert(4, n) # number of repeats + n = 1 + elif m is ResNetLayer: + c2 = args[1] if args[3] else args[1] * 4 + elif m is nn.BatchNorm2d: + args = [ch[f]] + elif m is Concat: + c2 = sum(ch[x] for x in f) + elif m in {Detect, WorldDetect, Segment, Pose, OBB, ImagePoolingAttn}: + args.append([ch[x] for x in f]) + if m is Segment: + args[2] = make_divisible(min(args[2], max_channels) * width, 8) + elif m is RTDETRDecoder: # special case, channels arg must be passed in index 1 + args.insert(1, [ch[x] for x in f]) + elif m is CBLinear: + c2 = args[0] + c1 = ch[f] + args = [c1, c2, *args[1:]] + elif m is CBFuse: + c2 = ch[f[-1]] + else: + c2 = ch[f] + + m_ = nn.Sequential(*(m(*args) for _ in range(n))) if n > 1 else m(*args) # module + t = str(m)[8:-2].replace("__main__.", "") # module type + m.np = sum(x.numel() for x in m_.parameters()) # number params + m_.i, m_.f, m_.type = i, f, t # attach index, 'from' index, type + if verbose: + LOGGER.info(f"{i:>3}{str(f):>20}{n_:>3}{m.np:10.0f} {t:<45}{str(args):<30}") # print + save.extend(x % i for x in ([f] if isinstance(f, int) else f) if x != -1) # append to savelist + layers.append(m_) + if i == 0: + ch = [] + ch.append(c2) + return nn.Sequential(*layers), sorted(save) + + +def yaml_model_load(path): + """Load a YOLOv8 model from a YAML file.""" + import re + + path = Path(path) + if path.stem in (f"yolov{d}{x}6" for x in "nsmlx" for d in (5, 8)): + new_stem = re.sub(r"(\d+)([nslmx])6(.+)?$", r"\1\2-p6\3", path.stem) + LOGGER.warning(f"WARNING ⚠️ Ultralytics YOLO P6 models now use -p6 suffix. Renaming {path.stem} to {new_stem}.") + path = path.with_name(new_stem + path.suffix) + + unified_path = re.sub(r"(\d+)([nslmx])(.+)?$", r"\1\3", str(path)) # i.e. yolov8x.yaml -> yolov8.yaml + yaml_file = check_yaml(unified_path, hard=False) or check_yaml(path) + d = yaml_load(yaml_file) # model dict + d["scale"] = guess_model_scale(path) + d["yaml_file"] = str(path) + return d + + +def guess_model_scale(model_path): + """ + Takes a path to a YOLO model's YAML file as input and extracts the size character of the model's scale. The function + uses regular expression matching to find the pattern of the model scale in the YAML file name, which is denoted by + n, s, m, l, or x. The function returns the size character of the model scale as a string. + + Args: + model_path (str | Path): The path to the YOLO model's YAML file. + + Returns: + (str): The size character of the model's scale, which can be n, s, m, l, or x. + """ + with contextlib.suppress(AttributeError): + import re + + return re.search(r"yolov\d+([nslmx])", Path(model_path).stem).group(1) # n, s, m, l, or x + return "" + + +def guess_model_task(model): + """ + Guess the task of a PyTorch model from its architecture or configuration. + + Args: + model (nn.Module | dict): PyTorch model or model configuration in YAML format. + + Returns: + (str): Task of the model ('detect', 'segment', 'classify', 'pose'). + + Raises: + SyntaxError: If the task of the model could not be determined. + """ + + def cfg2task(cfg): + """Guess from YAML dictionary.""" + m = cfg["head"][-1][-2].lower() # output module name + if m in {"classify", "classifier", "cls", "fc"}: + return "classify" + if m == "detect": + return "detect" + if m == "segment": + return "segment" + if m == "pose": + return "pose" + if m == "obb": + return "obb" + + # Guess from model cfg + if isinstance(model, dict): + with contextlib.suppress(Exception): + return cfg2task(model) + + # Guess from PyTorch model + if isinstance(model, nn.Module): # PyTorch model + for x in "model.args", "model.model.args", "model.model.model.args": + with contextlib.suppress(Exception): + return eval(x)["task"] + for x in "model.yaml", "model.model.yaml", "model.model.model.yaml": + with contextlib.suppress(Exception): + return cfg2task(eval(x)) + + for m in model.modules(): + if isinstance(m, Segment): + return "segment" + elif isinstance(m, Classify): + return "classify" + elif isinstance(m, Pose): + return "pose" + elif isinstance(m, OBB): + return "obb" + elif isinstance(m, (Detect, WorldDetect)): + return "detect" + + # Guess from model filename + if isinstance(model, (str, Path)): + model = Path(model) + if "-seg" in model.stem or "segment" in model.parts: + return "segment" + elif "-cls" in model.stem or "classify" in model.parts: + return "classify" + elif "-pose" in model.stem or "pose" in model.parts: + return "pose" + elif "-obb" in model.stem or "obb" in model.parts: + return "obb" + elif "detect" in model.parts: + return "detect" + + # Unable to determine task from model + LOGGER.warning( + "WARNING ⚠️ Unable to automatically guess model task, assuming 'task=detect'. " + "Explicitly define task for your model, i.e. 'task=detect', 'segment', 'classify','pose' or 'obb'." + ) + return "detect" # assume detect diff --git a/ultralytics/solutions/__init__.py b/ultralytics/solutions/__init__.py new file mode 100644 index 0000000..9e68dc1 --- /dev/null +++ b/ultralytics/solutions/__init__.py @@ -0,0 +1 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license diff --git a/ultralytics/solutions/ai_gym.py b/ultralytics/solutions/ai_gym.py new file mode 100644 index 0000000..495250e --- /dev/null +++ b/ultralytics/solutions/ai_gym.py @@ -0,0 +1,150 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import cv2 + +from ultralytics.utils.checks import check_imshow +from ultralytics.utils.plotting import Annotator + + +class AIGym: + """A class to manage the gym steps of people in a real-time video stream based on their poses.""" + + def __init__(self): + """Initializes the AIGym with default values for Visual and Image parameters.""" + + # Image and line thickness + self.im0 = None + self.tf = None + + # Keypoints and count information + self.keypoints = None + self.poseup_angle = None + self.posedown_angle = None + self.threshold = 0.001 + + # Store stage, count and angle information + self.angle = None + self.count = None + self.stage = None + self.pose_type = "pushup" + self.kpts_to_check = None + + # Visual Information + self.view_img = False + self.annotator = None + + # Check if environment support imshow + self.env_check = check_imshow(warn=True) + + def set_args( + self, + kpts_to_check, + line_thickness=2, + view_img=False, + pose_up_angle=145.0, + pose_down_angle=90.0, + pose_type="pullup", + ): + """ + Configures the AIGym line_thickness, save image and view image parameters. + + Args: + kpts_to_check (list): 3 keypoints for counting + line_thickness (int): Line thickness for bounding boxes. + view_img (bool): display the im0 + pose_up_angle (float): Angle to set pose position up + pose_down_angle (float): Angle to set pose position down + pose_type (str): "pushup", "pullup" or "abworkout" + """ + self.kpts_to_check = kpts_to_check + self.tf = line_thickness + self.view_img = view_img + self.poseup_angle = pose_up_angle + self.posedown_angle = pose_down_angle + self.pose_type = pose_type + + def start_counting(self, im0, results, frame_count): + """ + Function used to count the gym steps. + + Args: + im0 (ndarray): Current frame from the video stream. + results (list): Pose estimation data + frame_count (int): store current frame count + """ + self.im0 = im0 + if frame_count == 1: + self.count = [0] * len(results[0]) + self.angle = [0] * len(results[0]) + self.stage = ["-" for _ in results[0]] + self.keypoints = results[0].keypoints.data + self.annotator = Annotator(im0, line_width=2) + + for ind, k in enumerate(reversed(self.keypoints)): + if self.pose_type in {"pushup", "pullup"}: + self.angle[ind] = self.annotator.estimate_pose_angle( + k[int(self.kpts_to_check[0])].cpu(), + k[int(self.kpts_to_check[1])].cpu(), + k[int(self.kpts_to_check[2])].cpu(), + ) + self.im0 = self.annotator.draw_specific_points(k, self.kpts_to_check, shape=(640, 640), radius=10) + + if self.pose_type == "abworkout": + self.angle[ind] = self.annotator.estimate_pose_angle( + k[int(self.kpts_to_check[0])].cpu(), + k[int(self.kpts_to_check[1])].cpu(), + k[int(self.kpts_to_check[2])].cpu(), + ) + self.im0 = self.annotator.draw_specific_points(k, self.kpts_to_check, shape=(640, 640), radius=10) + if self.angle[ind] > self.poseup_angle: + self.stage[ind] = "down" + if self.angle[ind] < self.posedown_angle and self.stage[ind] == "down": + self.stage[ind] = "up" + self.count[ind] += 1 + self.annotator.plot_angle_and_count_and_stage( + angle_text=self.angle[ind], + count_text=self.count[ind], + stage_text=self.stage[ind], + center_kpt=k[int(self.kpts_to_check[1])], + line_thickness=self.tf, + ) + + if self.pose_type == "pushup": + if self.angle[ind] > self.poseup_angle: + self.stage[ind] = "up" + if self.angle[ind] < self.posedown_angle and self.stage[ind] == "up": + self.stage[ind] = "down" + self.count[ind] += 1 + self.annotator.plot_angle_and_count_and_stage( + angle_text=self.angle[ind], + count_text=self.count[ind], + stage_text=self.stage[ind], + center_kpt=k[int(self.kpts_to_check[1])], + line_thickness=self.tf, + ) + if self.pose_type == "pullup": + if self.angle[ind] > self.poseup_angle: + self.stage[ind] = "down" + if self.angle[ind] < self.posedown_angle and self.stage[ind] == "down": + self.stage[ind] = "up" + self.count[ind] += 1 + self.annotator.plot_angle_and_count_and_stage( + angle_text=self.angle[ind], + count_text=self.count[ind], + stage_text=self.stage[ind], + center_kpt=k[int(self.kpts_to_check[1])], + line_thickness=self.tf, + ) + + self.annotator.kpts(k, shape=(640, 640), radius=1, kpt_line=True) + + if self.env_check and self.view_img: + cv2.imshow("Ultralytics YOLOv8 AI GYM", self.im0) + if cv2.waitKey(1) & 0xFF == ord("q"): + return + + return self.im0 + + +if __name__ == "__main__": + AIGym() diff --git a/ultralytics/solutions/distance_calculation.py b/ultralytics/solutions/distance_calculation.py new file mode 100644 index 0000000..f09209e --- /dev/null +++ b/ultralytics/solutions/distance_calculation.py @@ -0,0 +1,181 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import math + +import cv2 + +from ultralytics.utils.checks import check_imshow +from ultralytics.utils.plotting import Annotator, colors + + +class DistanceCalculation: + """A class to calculate distance between two objects in real-time video stream based on their tracks.""" + + def __init__(self): + """Initializes the distance calculation class with default values for Visual, Image, track and distance + parameters. + """ + + # Visual & im0 information + self.im0 = None + self.annotator = None + self.view_img = False + self.line_color = (255, 255, 0) + self.centroid_color = (255, 0, 255) + + # Predict/track information + self.clss = None + self.names = None + self.boxes = None + self.line_thickness = 2 + self.trk_ids = None + + # Distance calculation information + self.centroids = [] + self.pixel_per_meter = 10 + + # Mouse event + self.left_mouse_count = 0 + self.selected_boxes = {} + + # Check if environment support imshow + self.env_check = check_imshow(warn=True) + + def set_args( + self, + names, + pixels_per_meter=10, + view_img=False, + line_thickness=2, + line_color=(255, 255, 0), + centroid_color=(255, 0, 255), + ): + """ + Configures the distance calculation and display parameters. + + Args: + names (dict): object detection classes names + pixels_per_meter (int): Number of pixels in meter + view_img (bool): Flag indicating frame display + line_thickness (int): Line thickness for bounding boxes. + line_color (RGB): color of centroids line + centroid_color (RGB): colors of bbox centroids + """ + self.names = names + self.pixel_per_meter = pixels_per_meter + self.view_img = view_img + self.line_thickness = line_thickness + self.line_color = line_color + self.centroid_color = centroid_color + + def mouse_event_for_distance(self, event, x, y, flags, param): + """ + This function is designed to move region with mouse events in a real-time video stream. + + Args: + event (int): The type of mouse event (e.g., cv2.EVENT_MOUSEMOVE, cv2.EVENT_LBUTTONDOWN, etc.). + x (int): The x-coordinate of the mouse pointer. + y (int): The y-coordinate of the mouse pointer. + flags (int): Any flags associated with the event (e.g., cv2.EVENT_FLAG_CTRLKEY, + cv2.EVENT_FLAG_SHIFTKEY, etc.). + param (dict): Additional parameters you may want to pass to the function. + """ + global selected_boxes + global left_mouse_count + if event == cv2.EVENT_LBUTTONDOWN: + self.left_mouse_count += 1 + if self.left_mouse_count <= 2: + for box, track_id in zip(self.boxes, self.trk_ids): + if box[0] < x < box[2] and box[1] < y < box[3] and track_id not in self.selected_boxes: + self.selected_boxes[track_id] = [] + self.selected_boxes[track_id] = box + + if event == cv2.EVENT_RBUTTONDOWN: + self.selected_boxes = {} + self.left_mouse_count = 0 + + def extract_tracks(self, tracks): + """ + Extracts results from the provided data. + + Args: + tracks (list): List of tracks obtained from the object tracking process. + """ + self.boxes = tracks[0].boxes.xyxy.cpu() + self.clss = tracks[0].boxes.cls.cpu().tolist() + self.trk_ids = tracks[0].boxes.id.int().cpu().tolist() + + def calculate_centroid(self, box): + """ + Calculate the centroid of bounding box. + + Args: + box (list): Bounding box data + """ + return int((box[0] + box[2]) // 2), int((box[1] + box[3]) // 2) + + def calculate_distance(self, centroid1, centroid2): + """ + Calculate distance between two centroids. + + Args: + centroid1 (point): First bounding box data + centroid2 (point): Second bounding box data + """ + pixel_distance = math.sqrt((centroid1[0] - centroid2[0]) ** 2 + (centroid1[1] - centroid2[1]) ** 2) + return pixel_distance / self.pixel_per_meter, (pixel_distance / self.pixel_per_meter) * 1000 + + def start_process(self, im0, tracks): + """ + Calculate distance between two bounding boxes based on tracking data. + + Args: + im0 (nd array): Image + tracks (list): List of tracks obtained from the object tracking process. + """ + self.im0 = im0 + if tracks[0].boxes.id is None: + if self.view_img: + self.display_frames() + return + self.extract_tracks(tracks) + + self.annotator = Annotator(self.im0, line_width=2) + + for box, cls, track_id in zip(self.boxes, self.clss, self.trk_ids): + self.annotator.box_label(box, color=colors(int(cls), True), label=self.names[int(cls)]) + + if len(self.selected_boxes) == 2: + for trk_id, _ in self.selected_boxes.items(): + if trk_id == track_id: + self.selected_boxes[track_id] = box + + if len(self.selected_boxes) == 2: + for trk_id, box in self.selected_boxes.items(): + centroid = self.calculate_centroid(self.selected_boxes[trk_id]) + self.centroids.append(centroid) + + distance_m, distance_mm = self.calculate_distance(self.centroids[0], self.centroids[1]) + self.annotator.plot_distance_and_line( + distance_m, distance_mm, self.centroids, self.line_color, self.centroid_color + ) + + self.centroids = [] + + if self.view_img and self.env_check: + self.display_frames() + + return im0 + + def display_frames(self): + """Display frame.""" + cv2.namedWindow("Ultralytics Distance Estimation") + cv2.setMouseCallback("Ultralytics Distance Estimation", self.mouse_event_for_distance) + cv2.imshow("Ultralytics Distance Estimation", self.im0) + + if cv2.waitKey(1) & 0xFF == ord("q"): + return + + +if __name__ == "__main__": + DistanceCalculation() diff --git a/ultralytics/solutions/heatmap.py b/ultralytics/solutions/heatmap.py new file mode 100644 index 0000000..1c71eb7 --- /dev/null +++ b/ultralytics/solutions/heatmap.py @@ -0,0 +1,306 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from collections import defaultdict + +import cv2 +import numpy as np + +from ultralytics.utils.checks import check_imshow, check_requirements +from ultralytics.utils.plotting import Annotator + +check_requirements("shapely>=2.0.0") + +from shapely.geometry import LineString, Point, Polygon + + +class Heatmap: + """A class to draw heatmaps in real-time video stream based on their tracks.""" + + def __init__(self): + """Initializes the heatmap class with default values for Visual, Image, track, count and heatmap parameters.""" + + # Visual information + self.annotator = None + self.view_img = False + self.shape = "circle" + + self.names = None # Classes names + + # Image information + self.imw = None + self.imh = None + self.im0 = None + self.tf = 2 + self.view_in_counts = True + self.view_out_counts = True + + # Heatmap colormap and heatmap np array + self.colormap = None + self.heatmap = None + self.heatmap_alpha = 0.5 + + # Predict/track information + self.boxes = None + self.track_ids = None + self.clss = None + self.track_history = defaultdict(list) + + # Region & Line Information + self.count_reg_pts = None + self.counting_region = None + self.line_dist_thresh = 15 + self.region_thickness = 5 + self.region_color = (255, 0, 255) + + # Object Counting Information + self.in_counts = 0 + self.out_counts = 0 + self.count_ids = [] + self.class_wise_count = {} + self.count_txt_color = (0, 0, 0) + self.count_bg_color = (255, 255, 255) + self.cls_txtdisplay_gap = 50 + + # Decay factor + self.decay_factor = 0.99 + + # Check if environment support imshow + self.env_check = check_imshow(warn=True) + + def set_args( + self, + imw, + imh, + classes_names=None, + colormap=cv2.COLORMAP_JET, + heatmap_alpha=0.5, + view_img=False, + view_in_counts=True, + view_out_counts=True, + count_reg_pts=None, + count_txt_color=(0, 0, 0), + count_bg_color=(255, 255, 255), + count_reg_color=(255, 0, 255), + region_thickness=5, + line_dist_thresh=15, + line_thickness=2, + decay_factor=0.99, + shape="circle", + ): + """ + Configures the heatmap colormap, width, height and display parameters. + + Args: + colormap (cv2.COLORMAP): The colormap to be set. + imw (int): The width of the frame. + imh (int): The height of the frame. + classes_names (dict): Classes names + line_thickness (int): Line thickness for bounding boxes. + heatmap_alpha (float): alpha value for heatmap display + view_img (bool): Flag indicating frame display + view_in_counts (bool): Flag to control whether to display the incounts on video stream. + view_out_counts (bool): Flag to control whether to display the outcounts on video stream. + count_reg_pts (list): Object counting region points + count_txt_color (RGB color): count text color value + count_bg_color (RGB color): count highlighter line color + count_reg_color (RGB color): Color of object counting region + region_thickness (int): Object counting Region thickness + line_dist_thresh (int): Euclidean Distance threshold for line counter + decay_factor (float): value for removing heatmap area after object passed + shape (str): Heatmap shape, rect or circle shape supported + """ + self.tf = line_thickness + self.names = classes_names + self.imw = imw + self.imh = imh + self.heatmap_alpha = heatmap_alpha + self.view_img = view_img + self.view_in_counts = view_in_counts + self.view_out_counts = view_out_counts + self.colormap = colormap + + # Region and line selection + if count_reg_pts is not None: + if len(count_reg_pts) == 2: + print("Line Counter Initiated.") + self.count_reg_pts = count_reg_pts + self.counting_region = LineString(self.count_reg_pts) + elif len(count_reg_pts) >= 3: + print("Polygon Counter Initiated.") + self.count_reg_pts = count_reg_pts + self.counting_region = Polygon(self.count_reg_pts) + else: + print("Invalid Region points provided, region_points must be 2 for lines or >= 3 for polygons.") + print("Using Line Counter Now") + self.counting_region = LineString(self.count_reg_pts) + + # Heatmap new frame + self.heatmap = np.zeros((int(self.imh), int(self.imw)), dtype=np.float32) + + self.count_txt_color = count_txt_color + self.count_bg_color = count_bg_color + self.region_color = count_reg_color + self.region_thickness = region_thickness + self.decay_factor = decay_factor + self.line_dist_thresh = line_dist_thresh + self.shape = shape + + # shape of heatmap, if not selected + if self.shape not in {"circle", "rect"}: + print("Unknown shape value provided, 'circle' & 'rect' supported") + print("Using Circular shape now") + self.shape = "circle" + + def extract_results(self, tracks): + """ + Extracts results from the provided data. + + Args: + tracks (list): List of tracks obtained from the object tracking process. + """ + self.boxes = tracks[0].boxes.xyxy.cpu() + self.clss = tracks[0].boxes.cls.cpu().tolist() + self.track_ids = tracks[0].boxes.id.int().cpu().tolist() + + def generate_heatmap(self, im0, tracks): + """ + Generate heatmap based on tracking data. + + Args: + im0 (nd array): Image + tracks (list): List of tracks obtained from the object tracking process. + """ + self.im0 = im0 + if tracks[0].boxes.id is None: + self.heatmap = np.zeros((int(self.imh), int(self.imw)), dtype=np.float32) + if self.view_img and self.env_check: + self.display_frames() + return im0 + self.heatmap *= self.decay_factor # decay factor + self.extract_results(tracks) + self.annotator = Annotator(self.im0, self.tf, None) + + if self.count_reg_pts is not None: + # Draw counting region + if self.view_in_counts or self.view_out_counts: + self.annotator.draw_region( + reg_pts=self.count_reg_pts, color=self.region_color, thickness=self.region_thickness + ) + + for box, cls, track_id in zip(self.boxes, self.clss, self.track_ids): + # Store class info + if self.names[cls] not in self.class_wise_count: + if len(self.names[cls]) > 5: + self.names[cls] = self.names[cls][:5] + self.class_wise_count[self.names[cls]] = {"in": 0, "out": 0} + + if self.shape == "circle": + center = (int((box[0] + box[2]) // 2), int((box[1] + box[3]) // 2)) + radius = min(int(box[2]) - int(box[0]), int(box[3]) - int(box[1])) // 2 + + y, x = np.ogrid[0 : self.heatmap.shape[0], 0 : self.heatmap.shape[1]] + mask = (x - center[0]) ** 2 + (y - center[1]) ** 2 <= radius**2 + + self.heatmap[int(box[1]) : int(box[3]), int(box[0]) : int(box[2])] += ( + 2 * mask[int(box[1]) : int(box[3]), int(box[0]) : int(box[2])] + ) + + else: + self.heatmap[int(box[1]) : int(box[3]), int(box[0]) : int(box[2])] += 2 + + # Store tracking hist + track_line = self.track_history[track_id] + track_line.append((float((box[0] + box[2]) / 2), float((box[1] + box[3]) / 2))) + if len(track_line) > 30: + track_line.pop(0) + + prev_position = self.track_history[track_id][-2] if len(self.track_history[track_id]) > 1 else None + + # Count objects in any polygon + if len(self.count_reg_pts) >= 3: + is_inside = self.counting_region.contains(Point(track_line[-1])) + + if prev_position is not None and is_inside and track_id not in self.count_ids: + self.count_ids.append(track_id) + + if (box[0] - prev_position[0]) * (self.counting_region.centroid.x - prev_position[0]) > 0: + self.in_counts += 1 + self.class_wise_count[self.names[cls]]["in"] += 1 + else: + self.out_counts += 1 + self.class_wise_count[self.names[cls]]["out"] += 1 + + # Count objects using line + elif len(self.count_reg_pts) == 2: + if prev_position is not None and track_id not in self.count_ids: + distance = Point(track_line[-1]).distance(self.counting_region) + if distance < self.line_dist_thresh and track_id not in self.count_ids: + self.count_ids.append(track_id) + + if (box[0] - prev_position[0]) * (self.counting_region.centroid.x - prev_position[0]) > 0: + self.in_counts += 1 + self.class_wise_count[self.names[cls]]["in"] += 1 + else: + self.out_counts += 1 + self.class_wise_count[self.names[cls]]["out"] += 1 + + else: + for box, cls in zip(self.boxes, self.clss): + if self.shape == "circle": + center = (int((box[0] + box[2]) // 2), int((box[1] + box[3]) // 2)) + radius = min(int(box[2]) - int(box[0]), int(box[3]) - int(box[1])) // 2 + + y, x = np.ogrid[0 : self.heatmap.shape[0], 0 : self.heatmap.shape[1]] + mask = (x - center[0]) ** 2 + (y - center[1]) ** 2 <= radius**2 + + self.heatmap[int(box[1]) : int(box[3]), int(box[0]) : int(box[2])] += ( + 2 * mask[int(box[1]) : int(box[3]), int(box[0]) : int(box[2])] + ) + + else: + self.heatmap[int(box[1]) : int(box[3]), int(box[0]) : int(box[2])] += 2 + + # Normalize, apply colormap to heatmap and combine with original image + heatmap_normalized = cv2.normalize(self.heatmap, None, 0, 255, cv2.NORM_MINMAX) + heatmap_colored = cv2.applyColorMap(heatmap_normalized.astype(np.uint8), self.colormap) + + label = "Ultralytics Analytics \t" + + for key, value in self.class_wise_count.items(): + if value["in"] != 0 or value["out"] != 0: + if not self.view_in_counts and not self.view_out_counts: + label = None + elif not self.view_in_counts: + label += f"{str.capitalize(key)}: IN {value['in']} \t" + elif not self.view_out_counts: + label += f"{str.capitalize(key)}: OUT {value['out']} \t" + else: + label += f"{str.capitalize(key)}: IN {value['in']} OUT {value['out']} \t" + + label = label.rstrip() + label = label.split("\t") + + if self.count_reg_pts is not None and label is not None: + self.annotator.display_counts( + counts=label, + count_txt_color=self.count_txt_color, + count_bg_color=self.count_bg_color, + ) + + self.im0 = cv2.addWeighted(self.im0, 1 - self.heatmap_alpha, heatmap_colored, self.heatmap_alpha, 0) + + if self.env_check and self.view_img: + self.display_frames() + + return self.im0 + + def display_frames(self): + """Display frame.""" + cv2.imshow("Ultralytics Heatmap", self.im0) + + if cv2.waitKey(1) & 0xFF == ord("q"): + return + + +if __name__ == "__main__": + Heatmap() diff --git a/ultralytics/solutions/object_counter.py b/ultralytics/solutions/object_counter.py new file mode 100644 index 0000000..e7174b0 --- /dev/null +++ b/ultralytics/solutions/object_counter.py @@ -0,0 +1,283 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from collections import defaultdict + +import cv2 + +from ultralytics.utils.checks import check_imshow, check_requirements +from ultralytics.utils.plotting import Annotator, colors + +check_requirements("shapely>=2.0.0") + +from shapely.geometry import LineString, Point, Polygon + + +class ObjectCounter: + """A class to manage the counting of objects in a real-time video stream based on their tracks.""" + + def __init__(self): + """Initializes the Counter with default values for various tracking and counting parameters.""" + + # Mouse events + self.is_drawing = False + self.selected_point = None + + # Region & Line Information + self.reg_pts = [(20, 400), (1260, 400)] + self.line_dist_thresh = 15 + self.counting_region = None + self.region_color = (255, 0, 255) + self.region_thickness = 5 + + # Image and annotation Information + self.im0 = None + self.tf = None + self.view_img = False + self.view_in_counts = True + self.view_out_counts = True + + self.names = None # Classes names + self.annotator = None # Annotator + self.window_name = "Ultralytics YOLOv8 Object Counter" + + # Object counting Information + self.in_counts = 0 + self.out_counts = 0 + self.count_ids = [] + self.class_wise_count = {} + self.count_txt_thickness = 0 + self.count_txt_color = (255, 255, 255) + self.count_bg_color = (255, 255, 255) + self.cls_txtdisplay_gap = 50 + self.fontsize = 0.6 + + # Tracks info + self.track_history = defaultdict(list) + self.track_thickness = 2 + self.draw_tracks = False + self.track_color = None + + # Check if environment support imshow + self.env_check = check_imshow(warn=True) + + def set_args( + self, + classes_names, + reg_pts, + count_reg_color=(255, 0, 255), + count_txt_color=(0, 0, 0), + count_bg_color=(255, 255, 255), + line_thickness=2, + track_thickness=2, + view_img=False, + view_in_counts=True, + view_out_counts=True, + draw_tracks=False, + track_color=None, + region_thickness=5, + line_dist_thresh=15, + cls_txtdisplay_gap=50, + ): + """ + Configures the Counter's image, bounding box line thickness, and counting region points. + + Args: + line_thickness (int): Line thickness for bounding boxes. + view_img (bool): Flag to control whether to display the video stream. + view_in_counts (bool): Flag to control whether to display the incounts on video stream. + view_out_counts (bool): Flag to control whether to display the outcounts on video stream. + reg_pts (list): Initial list of points defining the counting region. + classes_names (dict): Classes names + track_thickness (int): Track thickness + draw_tracks (Bool): draw tracks + count_txt_color (RGB color): count text color value + count_bg_color (RGB color): count highlighter line color + count_reg_color (RGB color): Color of object counting region + track_color (RGB color): color for tracks + region_thickness (int): Object counting Region thickness + line_dist_thresh (int): Euclidean Distance threshold for line counter + cls_txtdisplay_gap (int): Display gap between each class count + """ + self.tf = line_thickness + self.view_img = view_img + self.view_in_counts = view_in_counts + self.view_out_counts = view_out_counts + self.track_thickness = track_thickness + self.draw_tracks = draw_tracks + + # Region and line selection + if len(reg_pts) == 2: + print("Line Counter Initiated.") + self.reg_pts = reg_pts + self.counting_region = LineString(self.reg_pts) + elif len(reg_pts) >= 3: + print("Polygon Counter Initiated.") + self.reg_pts = reg_pts + self.counting_region = Polygon(self.reg_pts) + else: + print("Invalid Region points provided, region_points must be 2 for lines or >= 3 for polygons.") + print("Using Line Counter Now") + self.counting_region = LineString(self.reg_pts) + + self.names = classes_names + self.track_color = track_color + self.count_txt_color = count_txt_color + self.count_bg_color = count_bg_color + self.region_color = count_reg_color + self.region_thickness = region_thickness + self.line_dist_thresh = line_dist_thresh + self.cls_txtdisplay_gap = cls_txtdisplay_gap + + def mouse_event_for_region(self, event, x, y, flags, params): + """ + This function is designed to move region with mouse events in a real-time video stream. + + Args: + event (int): The type of mouse event (e.g., cv2.EVENT_MOUSEMOVE, cv2.EVENT_LBUTTONDOWN, etc.). + x (int): The x-coordinate of the mouse pointer. + y (int): The y-coordinate of the mouse pointer. + flags (int): Any flags associated with the event (e.g., cv2.EVENT_FLAG_CTRLKEY, + cv2.EVENT_FLAG_SHIFTKEY, etc.). + params (dict): Additional parameters you may want to pass to the function. + """ + if event == cv2.EVENT_LBUTTONDOWN: + for i, point in enumerate(self.reg_pts): + if ( + isinstance(point, (tuple, list)) + and len(point) >= 2 + and (abs(x - point[0]) < 10 and abs(y - point[1]) < 10) + ): + self.selected_point = i + self.is_drawing = True + break + + elif event == cv2.EVENT_MOUSEMOVE: + if self.is_drawing and self.selected_point is not None: + self.reg_pts[self.selected_point] = (x, y) + self.counting_region = Polygon(self.reg_pts) + + elif event == cv2.EVENT_LBUTTONUP: + self.is_drawing = False + self.selected_point = None + + def extract_and_process_tracks(self, tracks): + """Extracts and processes tracks for object counting in a video stream.""" + + # Annotator Init and region drawing + self.annotator = Annotator(self.im0, self.tf, self.names) + + # Draw region or line + self.annotator.draw_region(reg_pts=self.reg_pts, color=self.region_color, thickness=self.region_thickness) + + if tracks[0].boxes.id is not None: + boxes = tracks[0].boxes.xyxy.cpu() + clss = tracks[0].boxes.cls.cpu().tolist() + track_ids = tracks[0].boxes.id.int().cpu().tolist() + + # Extract tracks + for box, track_id, cls in zip(boxes, track_ids, clss): + # Draw bounding box + self.annotator.box_label(box, label=f"{self.names[cls]}#{track_id}", color=colors(int(track_id), True)) + + # Store class info + if self.names[cls] not in self.class_wise_count: + if len(self.names[cls]) > 5: + self.names[cls] = self.names[cls][:5] + self.class_wise_count[self.names[cls]] = {"in": 0, "out": 0} + + # Draw Tracks + track_line = self.track_history[track_id] + track_line.append((float((box[0] + box[2]) / 2), float((box[1] + box[3]) / 2))) + if len(track_line) > 30: + track_line.pop(0) + + # Draw track trails + if self.draw_tracks: + self.annotator.draw_centroid_and_tracks( + track_line, + color=self.track_color if self.track_color else colors(int(track_id), True), + track_thickness=self.track_thickness, + ) + + prev_position = self.track_history[track_id][-2] if len(self.track_history[track_id]) > 1 else None + + # Count objects in any polygon + if len(self.reg_pts) >= 3: + is_inside = self.counting_region.contains(Point(track_line[-1])) + + if prev_position is not None and is_inside and track_id not in self.count_ids: + self.count_ids.append(track_id) + + if (box[0] - prev_position[0]) * (self.counting_region.centroid.x - prev_position[0]) > 0: + self.in_counts += 1 + self.class_wise_count[self.names[cls]]["in"] += 1 + else: + self.out_counts += 1 + self.class_wise_count[self.names[cls]]["out"] += 1 + + # Count objects using line + elif len(self.reg_pts) == 2: + if prev_position is not None and track_id not in self.count_ids: + distance = Point(track_line[-1]).distance(self.counting_region) + if distance < self.line_dist_thresh and track_id not in self.count_ids: + self.count_ids.append(track_id) + + if (box[0] - prev_position[0]) * (self.counting_region.centroid.x - prev_position[0]) > 0: + self.in_counts += 1 + self.class_wise_count[self.names[cls]]["in"] += 1 + else: + self.out_counts += 1 + self.class_wise_count[self.names[cls]]["out"] += 1 + + label = "Ultralytics Analytics \t" + + for key, value in self.class_wise_count.items(): + if value["in"] != 0 or value["out"] != 0: + if not self.view_in_counts and not self.view_out_counts: + label = None + elif not self.view_in_counts: + label += f"{str.capitalize(key)}: IN {value['in']} \t" + elif not self.view_out_counts: + label += f"{str.capitalize(key)}: OUT {value['out']} \t" + else: + label += f"{str.capitalize(key)}: IN {value['in']} OUT {value['out']} \t" + + label = label.rstrip() + label = label.split("\t") + + if label is not None: + self.annotator.display_counts( + counts=label, + count_txt_color=self.count_txt_color, + count_bg_color=self.count_bg_color, + ) + + def display_frames(self): + """Display frame.""" + if self.env_check: + cv2.namedWindow(self.window_name) + if len(self.reg_pts) == 4: # only add mouse event If user drawn region + cv2.setMouseCallback(self.window_name, self.mouse_event_for_region, {"region_points": self.reg_pts}) + cv2.imshow(self.window_name, self.im0) + # Break Window + if cv2.waitKey(1) & 0xFF == ord("q"): + return + + def start_counting(self, im0, tracks): + """ + Main function to start the object counting process. + + Args: + im0 (ndarray): Current frame from the video stream. + tracks (list): List of tracks obtained from the object tracking process. + """ + self.im0 = im0 # store image + self.extract_and_process_tracks(tracks) # draw region even if no objects + + if self.view_img: + self.display_frames() + return self.im0 + + +if __name__ == "__main__": + ObjectCounter() diff --git a/ultralytics/solutions/queue_management.py b/ultralytics/solutions/queue_management.py new file mode 100644 index 0000000..ca8db49 --- /dev/null +++ b/ultralytics/solutions/queue_management.py @@ -0,0 +1,187 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from collections import defaultdict + +import cv2 + +from ultralytics.utils.checks import check_imshow, check_requirements +from ultralytics.utils.plotting import Annotator, colors + +check_requirements("shapely>=2.0.0") + +from shapely.geometry import Point, Polygon + + +class QueueManager: + """A class to manage the queue management in real-time video stream based on their tracks.""" + + def __init__(self): + """Initializes the queue manager with default values for various tracking and counting parameters.""" + + # Mouse events + self.is_drawing = False + self.selected_point = None + + # Region & Line Information + self.reg_pts = [(20, 60), (20, 680), (1120, 680), (1120, 60)] + self.counting_region = None + self.region_color = (255, 0, 255) + self.region_thickness = 5 + + # Image and annotation Information + self.im0 = None + self.tf = None + self.view_img = False + self.view_queue_counts = True + self.fontsize = 0.6 + + self.names = None # Classes names + self.annotator = None # Annotator + self.window_name = "Ultralytics YOLOv8 Queue Manager" + + # Object counting Information + self.counts = 0 + self.count_txt_color = (255, 255, 255) + + # Tracks info + self.track_history = defaultdict(list) + self.track_thickness = 2 + self.draw_tracks = False + self.track_color = None + + # Check if environment support imshow + self.env_check = check_imshow(warn=True) + + def set_args( + self, + classes_names, + reg_pts, + line_thickness=2, + track_thickness=2, + view_img=False, + region_color=(255, 0, 255), + view_queue_counts=True, + draw_tracks=False, + count_txt_color=(255, 255, 255), + track_color=None, + region_thickness=5, + fontsize=0.7, + ): + """ + Configures the Counter's image, bounding box line thickness, and counting region points. + + Args: + line_thickness (int): Line thickness for bounding boxes. + view_img (bool): Flag to control whether to display the video stream. + view_queue_counts (bool): Flag to control whether to display the counts on video stream. + reg_pts (list): Initial list of points defining the counting region. + classes_names (dict): Classes names + region_color (RGB color): Color of queue region + track_thickness (int): Track thickness + draw_tracks (Bool): draw tracks + count_txt_color (RGB color): count text color value + track_color (RGB color): color for tracks + region_thickness (int): Object counting Region thickness + fontsize (float): Text display font size + """ + self.tf = line_thickness + self.view_img = view_img + self.view_queue_counts = view_queue_counts + self.track_thickness = track_thickness + self.draw_tracks = draw_tracks + self.region_color = region_color + + if len(reg_pts) >= 3: + print("Queue region initiated...") + self.reg_pts = reg_pts + self.counting_region = Polygon(self.reg_pts) + else: + print("Invalid region points provided...") + print("Using default region now....") + self.counting_region = Polygon(self.reg_pts) + + self.names = classes_names + self.track_color = track_color + self.count_txt_color = count_txt_color + self.region_thickness = region_thickness + self.fontsize = fontsize + + def extract_and_process_tracks(self, tracks): + """Extracts and processes tracks for queue management in a video stream.""" + + # Annotator Init and queue region drawing + self.annotator = Annotator(self.im0, self.tf, self.names) + + if tracks[0].boxes.id is not None: + boxes = tracks[0].boxes.xyxy.cpu() + clss = tracks[0].boxes.cls.cpu().tolist() + track_ids = tracks[0].boxes.id.int().cpu().tolist() + + # Extract tracks + for box, track_id, cls in zip(boxes, track_ids, clss): + # Draw bounding box + self.annotator.box_label(box, label=f"{self.names[cls]}#{track_id}", color=colors(int(track_id), True)) + + # Draw Tracks + track_line = self.track_history[track_id] + track_line.append((float((box[0] + box[2]) / 2), float((box[1] + box[3]) / 2))) + if len(track_line) > 30: + track_line.pop(0) + + # Draw track trails + if self.draw_tracks: + self.annotator.draw_centroid_and_tracks( + track_line, + color=self.track_color if self.track_color else colors(int(track_id), True), + track_thickness=self.track_thickness, + ) + + prev_position = self.track_history[track_id][-2] if len(self.track_history[track_id]) > 1 else None + + if len(self.reg_pts) >= 3: + is_inside = self.counting_region.contains(Point(track_line[-1])) + if prev_position is not None and is_inside: + self.counts += 1 + + label = "Queue Counts : " + str(self.counts) + + if label is not None: + self.annotator.queue_counts_display( + label, + points=self.reg_pts, + region_color=self.region_color, + txt_color=self.count_txt_color, + fontsize=self.fontsize, + ) + + self.counts = 0 + self.display_frames() + + def display_frames(self): + """Display frame.""" + if self.env_check: + self.annotator.draw_region(reg_pts=self.reg_pts, thickness=self.region_thickness, color=self.region_color) + cv2.namedWindow(self.window_name) + cv2.imshow(self.window_name, self.im0) + # Break Window + if cv2.waitKey(1) & 0xFF == ord("q"): + return + + def process_queue(self, im0, tracks): + """ + Main function to start the queue management process. + + Args: + im0 (ndarray): Current frame from the video stream. + tracks (list): List of tracks obtained from the object tracking process. + """ + self.im0 = im0 # store image + self.extract_and_process_tracks(tracks) # draw region even if no objects + + if self.view_img: + self.display_frames() + return self.im0 + + +if __name__ == "__main__": + QueueManager() diff --git a/ultralytics/solutions/speed_estimation.py b/ultralytics/solutions/speed_estimation.py new file mode 100644 index 0000000..f3f1795 --- /dev/null +++ b/ultralytics/solutions/speed_estimation.py @@ -0,0 +1,198 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from collections import defaultdict +from time import time + +import cv2 +import numpy as np + +from ultralytics.utils.checks import check_imshow +from ultralytics.utils.plotting import Annotator, colors + + +class SpeedEstimator: + """A class to estimation speed of objects in real-time video stream based on their tracks.""" + + def __init__(self): + """Initializes the speed-estimator class with default values for Visual, Image, track and speed parameters.""" + + # Visual & im0 information + self.im0 = None + self.annotator = None + self.view_img = False + + # Region information + self.reg_pts = [(20, 400), (1260, 400)] + self.region_thickness = 3 + + # Predict/track information + self.clss = None + self.names = None + self.boxes = None + self.trk_ids = None + self.trk_pts = None + self.line_thickness = 2 + self.trk_history = defaultdict(list) + + # Speed estimator information + self.current_time = 0 + self.dist_data = {} + self.trk_idslist = [] + self.spdl_dist_thresh = 10 + self.trk_previous_times = {} + self.trk_previous_points = {} + + # Check if environment support imshow + self.env_check = check_imshow(warn=True) + + def set_args( + self, + reg_pts, + names, + view_img=False, + line_thickness=2, + region_thickness=5, + spdl_dist_thresh=10, + ): + """ + Configures the speed estimation and display parameters. + + Args: + reg_pts (list): Initial list of points defining the speed calculation region. + names (dict): object detection classes names + view_img (bool): Flag indicating frame display + line_thickness (int): Line thickness for bounding boxes. + region_thickness (int): Speed estimation region thickness + spdl_dist_thresh (int): Euclidean distance threshold for speed line + """ + if reg_pts is None: + print("Region points not provided, using default values") + else: + self.reg_pts = reg_pts + self.names = names + self.view_img = view_img + self.line_thickness = line_thickness + self.region_thickness = region_thickness + self.spdl_dist_thresh = spdl_dist_thresh + + def extract_tracks(self, tracks): + """ + Extracts results from the provided data. + + Args: + tracks (list): List of tracks obtained from the object tracking process. + """ + self.boxes = tracks[0].boxes.xyxy.cpu() + self.clss = tracks[0].boxes.cls.cpu().tolist() + self.trk_ids = tracks[0].boxes.id.int().cpu().tolist() + + def store_track_info(self, track_id, box): + """ + Store track data. + + Args: + track_id (int): object track id. + box (list): object bounding box data + """ + track = self.trk_history[track_id] + bbox_center = (float((box[0] + box[2]) / 2), float((box[1] + box[3]) / 2)) + track.append(bbox_center) + + if len(track) > 30: + track.pop(0) + + self.trk_pts = np.hstack(track).astype(np.int32).reshape((-1, 1, 2)) + return track + + def plot_box_and_track(self, track_id, box, cls, track): + """ + Plot track and bounding box. + + Args: + track_id (int): object track id. + box (list): object bounding box data + cls (str): object class name + track (list): tracking history for tracks path drawing + """ + speed_label = f"{int(self.dist_data[track_id])}km/ph" if track_id in self.dist_data else self.names[int(cls)] + bbox_color = colors(int(track_id)) if track_id in self.dist_data else (255, 0, 255) + + self.annotator.box_label(box, speed_label, bbox_color) + + cv2.polylines(self.im0, [self.trk_pts], isClosed=False, color=(0, 255, 0), thickness=1) + cv2.circle(self.im0, (int(track[-1][0]), int(track[-1][1])), 5, bbox_color, -1) + + def calculate_speed(self, trk_id, track): + """ + Calculation of object speed. + + Args: + trk_id (int): object track id. + track (list): tracking history for tracks path drawing + """ + + if not self.reg_pts[0][0] < track[-1][0] < self.reg_pts[1][0]: + return + if self.reg_pts[1][1] - self.spdl_dist_thresh < track[-1][1] < self.reg_pts[1][1] + self.spdl_dist_thresh: + direction = "known" + + elif self.reg_pts[0][1] - self.spdl_dist_thresh < track[-1][1] < self.reg_pts[0][1] + self.spdl_dist_thresh: + direction = "known" + + else: + direction = "unknown" + + if self.trk_previous_times[trk_id] != 0 and direction != "unknown" and trk_id not in self.trk_idslist: + self.trk_idslist.append(trk_id) + + time_difference = time() - self.trk_previous_times[trk_id] + if time_difference > 0: + dist_difference = np.abs(track[-1][1] - self.trk_previous_points[trk_id][1]) + speed = dist_difference / time_difference + self.dist_data[trk_id] = speed + + self.trk_previous_times[trk_id] = time() + self.trk_previous_points[trk_id] = track[-1] + + def estimate_speed(self, im0, tracks, region_color=(255, 0, 0)): + """ + Calculate object based on tracking data. + + Args: + im0 (nd array): Image + tracks (list): List of tracks obtained from the object tracking process. + region_color (tuple): Color to use when drawing regions. + """ + self.im0 = im0 + if tracks[0].boxes.id is None: + if self.view_img and self.env_check: + self.display_frames() + return im0 + self.extract_tracks(tracks) + + self.annotator = Annotator(self.im0, line_width=2) + self.annotator.draw_region(reg_pts=self.reg_pts, color=region_color, thickness=self.region_thickness) + + for box, trk_id, cls in zip(self.boxes, self.trk_ids, self.clss): + track = self.store_track_info(trk_id, box) + + if trk_id not in self.trk_previous_times: + self.trk_previous_times[trk_id] = 0 + + self.plot_box_and_track(trk_id, box, cls, track) + self.calculate_speed(trk_id, track) + + if self.view_img and self.env_check: + self.display_frames() + + return im0 + + def display_frames(self): + """Display frame.""" + cv2.imshow("Ultralytics Speed Estimation", self.im0) + if cv2.waitKey(1) & 0xFF == ord("q"): + return + + +if __name__ == "__main__": + SpeedEstimator() diff --git a/ultralytics/trackers/README.md b/ultralytics/trackers/README.md new file mode 100644 index 0000000..2cab3c0 --- /dev/null +++ b/ultralytics/trackers/README.md @@ -0,0 +1,321 @@ +# Multi-Object Tracking with Ultralytics YOLO + +YOLOv8 trackers visualization + +Object tracking in the realm of video analytics is a critical task that not only identifies the location and class of objects within the frame but also maintains a unique ID for each detected object as the video progresses. The applications are limitless—ranging from surveillance and security to real-time sports analytics. + +## Why Choose Ultralytics YOLO for Object Tracking? + +The output from Ultralytics trackers is consistent with standard object detection but has the added value of object IDs. This makes it easy to track objects in video streams and perform subsequent analytics. Here's why you should consider using Ultralytics YOLO for your object tracking needs: + +- **Efficiency:** Process video streams in real-time without compromising accuracy. +- **Flexibility:** Supports multiple tracking algorithms and configurations. +- **Ease of Use:** Simple Python API and CLI options for quick integration and deployment. +- **Customizability:** Easy to use with custom trained YOLO models, allowing integration into domain-specific applications. + +**Video Tutorial:** [Object Detection and Tracking with Ultralytics YOLOv8](https://www.youtube.com/embed/hHyHmOtmEgs?si=VNZtXmm45Nb9s-N-). + +## Features at a Glance + +Ultralytics YOLO extends its object detection features to provide robust and versatile object tracking: + +- **Real-Time Tracking:** Seamlessly track objects in high-frame-rate videos. +- **Multiple Tracker Support:** Choose from a variety of established tracking algorithms. +- **Customizable Tracker Configurations:** Tailor the tracking algorithm to meet specific requirements by adjusting various parameters. + +## Available Trackers + +Ultralytics YOLO supports the following tracking algorithms. They can be enabled by passing the relevant YAML configuration file such as `tracker=tracker_type.yaml`: + +- [BoT-SORT](https://github.com/NirAharon/BoT-SORT) - Use `botsort.yaml` to enable this tracker. +- [ByteTrack](https://github.com/ifzhang/ByteTrack) - Use `bytetrack.yaml` to enable this tracker. + +The default tracker is BoT-SORT. + +## Tracking + +To run the tracker on video streams, use a trained Detect, Segment or Pose model such as YOLOv8n, YOLOv8n-seg and YOLOv8n-pose. + +#### Python + +```python +from ultralytics import YOLO + +# Load an official or custom model +model = YOLO("yolov8n.pt") # Load an official Detect model +model = YOLO("yolov8n-seg.pt") # Load an official Segment model +model = YOLO("yolov8n-pose.pt") # Load an official Pose model +model = YOLO("path/to/best.pt") # Load a custom trained model + +# Perform tracking with the model +results = model.track( + source="https://youtu.be/LNwODJXcvt4", show=True +) # Tracking with default tracker +results = model.track( + source="https://youtu.be/LNwODJXcvt4", show=True, tracker="bytetrack.yaml" +) # Tracking with ByteTrack tracker +``` + +#### CLI + +```bash +# Perform tracking with various models using the command line interface +yolo track model=yolov8n.pt source="https://youtu.be/LNwODJXcvt4" # Official Detect model +yolo track model=yolov8n-seg.pt source="https://youtu.be/LNwODJXcvt4" # Official Segment model +yolo track model=yolov8n-pose.pt source="https://youtu.be/LNwODJXcvt4" # Official Pose model +yolo track model=path/to/best.pt source="https://youtu.be/LNwODJXcvt4" # Custom trained model + +# Track using ByteTrack tracker +yolo track model=path/to/best.pt tracker="bytetrack.yaml" +``` + +As can be seen in the above usage, tracking is available for all Detect, Segment and Pose models run on videos or streaming sources. + +## Configuration + +### Tracking Arguments + +Tracking configuration shares properties with Predict mode, such as `conf`, `iou`, and `show`. For further configurations, refer to the [Predict](https://docs.ultralytics.com/modes/predict/) model page. + +#### Python + +```python +from ultralytics import YOLO + +# Configure the tracking parameters and run the tracker +model = YOLO("yolov8n.pt") +results = model.track( + source="https://youtu.be/LNwODJXcvt4", conf=0.3, iou=0.5, show=True +) +``` + +#### CLI + +```bash +# Configure tracking parameters and run the tracker using the command line interface +yolo track model=yolov8n.pt source="https://youtu.be/LNwODJXcvt4" conf=0.3, iou=0.5 show +``` + +### Tracker Selection + +Ultralytics also allows you to use a modified tracker configuration file. To do this, simply make a copy of a tracker config file (for example, `custom_tracker.yaml`) from [ultralytics/cfg/trackers](https://github.com/ultralytics/ultralytics/tree/main/ultralytics/cfg/trackers) and modify any configurations (except the `tracker_type`) as per your needs. + +#### Python + +```python +from ultralytics import YOLO + +# Load the model and run the tracker with a custom configuration file +model = YOLO("yolov8n.pt") +results = model.track( + source="https://youtu.be/LNwODJXcvt4", tracker="custom_tracker.yaml" +) +``` + +#### CLI + +```bash +# Load the model and run the tracker with a custom configuration file using the command line interface +yolo track model=yolov8n.pt source="https://youtu.be/LNwODJXcvt4" tracker='custom_tracker.yaml' +``` + +For a comprehensive list of tracking arguments, refer to the [ultralytics/cfg/trackers](https://github.com/ultralytics/ultralytics/tree/main/ultralytics/cfg/trackers) page. + +## Python Examples + +### Persisting Tracks Loop + +Here is a Python script using OpenCV (`cv2`) and YOLOv8 to run object tracking on video frames. This script still assumes you have already installed the necessary packages (`opencv-python` and `ultralytics`). The `persist=True` argument tells the tracker than the current image or frame is the next in a sequence and to expect tracks from the previous image in the current image. + +#### Python + +```python +import cv2 +from ultralytics import YOLO + +# Load the YOLOv8 model +model = YOLO("yolov8n.pt") + +# Open the video file +video_path = "path/to/video.mp4" +cap = cv2.VideoCapture(video_path) + +# Loop through the video frames +while cap.isOpened(): + # Read a frame from the video + success, frame = cap.read() + + if success: + # Run YOLOv8 tracking on the frame, persisting tracks between frames + results = model.track(frame, persist=True) + + # Visualize the results on the frame + annotated_frame = results[0].plot() + + # Display the annotated frame + cv2.imshow("YOLOv8 Tracking", annotated_frame) + + # Break the loop if 'q' is pressed + if cv2.waitKey(1) & 0xFF == ord("q"): + break + else: + # Break the loop if the end of the video is reached + break + +# Release the video capture object and close the display window +cap.release() +cv2.destroyAllWindows() +``` + +Please note the change from `model(frame)` to `model.track(frame)`, which enables object tracking instead of simple detection. This modified script will run the tracker on each frame of the video, visualize the results, and display them in a window. The loop can be exited by pressing 'q'. + +### Plotting Tracks Over Time + +Visualizing object tracks over consecutive frames can provide valuable insights into the movement patterns and behavior of detected objects within a video. With Ultralytics YOLOv8, plotting these tracks is a seamless and efficient process. + +In the following example, we demonstrate how to utilize YOLOv8's tracking capabilities to plot the movement of detected objects across multiple video frames. This script involves opening a video file, reading it frame by frame, and utilizing the YOLO model to identify and track various objects. By retaining the center points of the detected bounding boxes and connecting them, we can draw lines that represent the paths followed by the tracked objects. + +#### Python + +```python +from collections import defaultdict + +import cv2 +import numpy as np + +from ultralytics import YOLO + +# Load the YOLOv8 model +model = YOLO("yolov8n.pt") + +# Open the video file +video_path = "path/to/video.mp4" +cap = cv2.VideoCapture(video_path) + +# Store the track history +track_history = defaultdict(lambda: []) + +# Loop through the video frames +while cap.isOpened(): + # Read a frame from the video + success, frame = cap.read() + + if success: + # Run YOLOv8 tracking on the frame, persisting tracks between frames + results = model.track(frame, persist=True) + + # Get the boxes and track IDs + boxes = results[0].boxes.xywh.cpu() + track_ids = results[0].boxes.id.int().cpu().tolist() + + # Visualize the results on the frame + annotated_frame = results[0].plot() + + # Plot the tracks + for box, track_id in zip(boxes, track_ids): + x, y, w, h = box + track = track_history[track_id] + track.append((float(x), float(y))) # x, y center point + if len(track) > 30: # retain 90 tracks for 90 frames + track.pop(0) + + # Draw the tracking lines + points = np.hstack(track).astype(np.int32).reshape((-1, 1, 2)) + cv2.polylines( + annotated_frame, + [points], + isClosed=False, + color=(230, 230, 230), + thickness=10, + ) + + # Display the annotated frame + cv2.imshow("YOLOv8 Tracking", annotated_frame) + + # Break the loop if 'q' is pressed + if cv2.waitKey(1) & 0xFF == ord("q"): + break + else: + # Break the loop if the end of the video is reached + break + +# Release the video capture object and close the display window +cap.release() +cv2.destroyAllWindows() +``` + +### Multithreaded Tracking + +Multithreaded tracking provides the capability to run object tracking on multiple video streams simultaneously. This is particularly useful when handling multiple video inputs, such as from multiple surveillance cameras, where concurrent processing can greatly enhance efficiency and performance. + +In the provided Python script, we make use of Python's `threading` module to run multiple instances of the tracker concurrently. Each thread is responsible for running the tracker on one video file, and all the threads run simultaneously in the background. + +To ensure that each thread receives the correct parameters (the video file and the model to use), we define a function `run_tracker_in_thread` that accepts these parameters and contains the main tracking loop. This function reads the video frame by frame, runs the tracker, and displays the results. + +Two different models are used in this example: `yolov8n.pt` and `yolov8n-seg.pt`, each tracking objects in a different video file. The video files are specified in `video_file1` and `video_file2`. + +The `daemon=True` parameter in `threading.Thread` means that these threads will be closed as soon as the main program finishes. We then start the threads with `start()` and use `join()` to make the main thread wait until both tracker threads have finished. + +Finally, after all threads have completed their task, the windows displaying the results are closed using `cv2.destroyAllWindows()`. + +#### Python + +```python +import threading + +import cv2 +from ultralytics import YOLO + + +def run_tracker_in_thread(filename, model): + video = cv2.VideoCapture(filename) + frames = int(video.get(cv2.CAP_PROP_FRAME_COUNT)) + for _ in range(frames): + ret, frame = video.read() + if ret: + results = model.track(source=frame, persist=True) + res_plotted = results[0].plot() + cv2.imshow("p", res_plotted) + if cv2.waitKey(1) == ord("q"): + break + + +# Load the models +model1 = YOLO("yolov8n.pt") +model2 = YOLO("yolov8n-seg.pt") + +# Define the video files for the trackers +video_file1 = "path/to/video1.mp4" +video_file2 = "path/to/video2.mp4" + +# Create the tracker threads +tracker_thread1 = threading.Thread( + target=run_tracker_in_thread, args=(video_file1, model1), daemon=True +) +tracker_thread2 = threading.Thread( + target=run_tracker_in_thread, args=(video_file2, model2), daemon=True +) + +# Start the tracker threads +tracker_thread1.start() +tracker_thread2.start() + +# Wait for the tracker threads to finish +tracker_thread1.join() +tracker_thread2.join() + +# Clean up and close windows +cv2.destroyAllWindows() +``` + +This example can easily be extended to handle more video files and models by creating more threads and applying the same methodology. + +## Contribute New Trackers + +Are you proficient in multi-object tracking and have successfully implemented or adapted a tracking algorithm with Ultralytics YOLO? We invite you to contribute to our Trackers section in [ultralytics/cfg/trackers](https://github.com/ultralytics/ultralytics/tree/main/ultralytics/cfg/trackers)! Your real-world applications and solutions could be invaluable for users working on tracking tasks. + +By contributing to this section, you help expand the scope of tracking solutions available within the Ultralytics YOLO framework, adding another layer of functionality and utility for the community. + +To initiate your contribution, please refer to our [Contributing Guide](https://docs.ultralytics.com/help/contributing) for comprehensive instructions on submitting a Pull Request (PR) 🛠️. We are excited to see what you bring to the table! + +Together, let's enhance the tracking capabilities of the Ultralytics YOLO ecosystem 🙏! diff --git a/ultralytics/trackers/__init__.py b/ultralytics/trackers/__init__.py new file mode 100644 index 0000000..bf51b8d --- /dev/null +++ b/ultralytics/trackers/__init__.py @@ -0,0 +1,7 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from .bot_sort import BOTSORT +from .byte_tracker import BYTETracker +from .track import register_tracker + +__all__ = "register_tracker", "BOTSORT", "BYTETracker" # allow simpler import diff --git a/ultralytics/trackers/basetrack.py b/ultralytics/trackers/basetrack.py new file mode 100644 index 0000000..c900cac --- /dev/null +++ b/ultralytics/trackers/basetrack.py @@ -0,0 +1,105 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +"""This module defines the base classes and structures for object tracking in YOLO.""" + +from collections import OrderedDict + +import numpy as np + + +class TrackState: + """ + Enumeration class representing the possible states of an object being tracked. + + Attributes: + New (int): State when the object is newly detected. + Tracked (int): State when the object is successfully tracked in subsequent frames. + Lost (int): State when the object is no longer tracked. + Removed (int): State when the object is removed from tracking. + """ + + New = 0 + Tracked = 1 + Lost = 2 + Removed = 3 + + +class BaseTrack: + """ + Base class for object tracking, providing foundational attributes and methods. + + Attributes: + _count (int): Class-level counter for unique track IDs. + track_id (int): Unique identifier for the track. + is_activated (bool): Flag indicating whether the track is currently active. + state (TrackState): Current state of the track. + history (OrderedDict): Ordered history of the track's states. + features (list): List of features extracted from the object for tracking. + curr_feature (any): The current feature of the object being tracked. + score (float): The confidence score of the tracking. + start_frame (int): The frame number where tracking started. + frame_id (int): The most recent frame ID processed by the track. + time_since_update (int): Frames passed since the last update. + location (tuple): The location of the object in the context of multi-camera tracking. + + Methods: + end_frame: Returns the ID of the last frame where the object was tracked. + next_id: Increments and returns the next global track ID. + activate: Abstract method to activate the track. + predict: Abstract method to predict the next state of the track. + update: Abstract method to update the track with new data. + mark_lost: Marks the track as lost. + mark_removed: Marks the track as removed. + reset_id: Resets the global track ID counter. + """ + + _count = 0 + + def __init__(self): + """Initializes a new track with unique ID and foundational tracking attributes.""" + self.track_id = 0 + self.is_activated = False + self.state = TrackState.New + self.history = OrderedDict() + self.features = [] + self.curr_feature = None + self.score = 0 + self.start_frame = 0 + self.frame_id = 0 + self.time_since_update = 0 + self.location = (np.inf, np.inf) + + @property + def end_frame(self): + """Return the last frame ID of the track.""" + return self.frame_id + + @staticmethod + def next_id(): + """Increment and return the global track ID counter.""" + BaseTrack._count += 1 + return BaseTrack._count + + def activate(self, *args): + """Abstract method to activate the track with provided arguments.""" + raise NotImplementedError + + def predict(self): + """Abstract method to predict the next state of the track.""" + raise NotImplementedError + + def update(self, *args, **kwargs): + """Abstract method to update the track with new observations.""" + raise NotImplementedError + + def mark_lost(self): + """Mark the track as lost.""" + self.state = TrackState.Lost + + def mark_removed(self): + """Mark the track as removed.""" + self.state = TrackState.Removed + + @staticmethod + def reset_id(): + """Reset the global track ID counter.""" + BaseTrack._count = 0 diff --git a/ultralytics/trackers/bot_sort.py b/ultralytics/trackers/bot_sort.py new file mode 100644 index 0000000..31d5e1b --- /dev/null +++ b/ultralytics/trackers/bot_sort.py @@ -0,0 +1,200 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from collections import deque + +import numpy as np + +from .basetrack import TrackState +from .byte_tracker import BYTETracker, STrack +from .utils import matching +from .utils.gmc import GMC +from .utils.kalman_filter import KalmanFilterXYWH + + +class BOTrack(STrack): + """ + An extended version of the STrack class for YOLOv8, adding object tracking features. + + Attributes: + shared_kalman (KalmanFilterXYWH): A shared Kalman filter for all instances of BOTrack. + smooth_feat (np.ndarray): Smoothed feature vector. + curr_feat (np.ndarray): Current feature vector. + features (deque): A deque to store feature vectors with a maximum length defined by `feat_history`. + alpha (float): Smoothing factor for the exponential moving average of features. + mean (np.ndarray): The mean state of the Kalman filter. + covariance (np.ndarray): The covariance matrix of the Kalman filter. + + Methods: + update_features(feat): Update features vector and smooth it using exponential moving average. + predict(): Predicts the mean and covariance using Kalman filter. + re_activate(new_track, frame_id, new_id): Reactivates a track with updated features and optionally new ID. + update(new_track, frame_id): Update the YOLOv8 instance with new track and frame ID. + tlwh: Property that gets the current position in tlwh format `(top left x, top left y, width, height)`. + multi_predict(stracks): Predicts the mean and covariance of multiple object tracks using shared Kalman filter. + convert_coords(tlwh): Converts tlwh bounding box coordinates to xywh format. + tlwh_to_xywh(tlwh): Convert bounding box to xywh format `(center x, center y, width, height)`. + + Usage: + bo_track = BOTrack(tlwh, score, cls, feat) + bo_track.predict() + bo_track.update(new_track, frame_id) + """ + + shared_kalman = KalmanFilterXYWH() + + def __init__(self, tlwh, score, cls, feat=None, feat_history=50): + """Initialize YOLOv8 object with temporal parameters, such as feature history, alpha and current features.""" + super().__init__(tlwh, score, cls) + + self.smooth_feat = None + self.curr_feat = None + if feat is not None: + self.update_features(feat) + self.features = deque([], maxlen=feat_history) + self.alpha = 0.9 + + def update_features(self, feat): + """Update features vector and smooth it using exponential moving average.""" + feat /= np.linalg.norm(feat) + self.curr_feat = feat + if self.smooth_feat is None: + self.smooth_feat = feat + else: + self.smooth_feat = self.alpha * self.smooth_feat + (1 - self.alpha) * feat + self.features.append(feat) + self.smooth_feat /= np.linalg.norm(self.smooth_feat) + + def predict(self): + """Predicts the mean and covariance using Kalman filter.""" + mean_state = self.mean.copy() + if self.state != TrackState.Tracked: + mean_state[6] = 0 + mean_state[7] = 0 + + self.mean, self.covariance = self.kalman_filter.predict(mean_state, self.covariance) + + def re_activate(self, new_track, frame_id, new_id=False): + """Reactivates a track with updated features and optionally assigns a new ID.""" + if new_track.curr_feat is not None: + self.update_features(new_track.curr_feat) + super().re_activate(new_track, frame_id, new_id) + + def update(self, new_track, frame_id): + """Update the YOLOv8 instance with new track and frame ID.""" + if new_track.curr_feat is not None: + self.update_features(new_track.curr_feat) + super().update(new_track, frame_id) + + @property + def tlwh(self): + """Get current position in bounding box format `(top left x, top left y, width, height)`.""" + if self.mean is None: + return self._tlwh.copy() + ret = self.mean[:4].copy() + ret[:2] -= ret[2:] / 2 + return ret + + @staticmethod + def multi_predict(stracks): + """Predicts the mean and covariance of multiple object tracks using shared Kalman filter.""" + if len(stracks) <= 0: + return + multi_mean = np.asarray([st.mean.copy() for st in stracks]) + multi_covariance = np.asarray([st.covariance for st in stracks]) + for i, st in enumerate(stracks): + if st.state != TrackState.Tracked: + multi_mean[i][6] = 0 + multi_mean[i][7] = 0 + multi_mean, multi_covariance = BOTrack.shared_kalman.multi_predict(multi_mean, multi_covariance) + for i, (mean, cov) in enumerate(zip(multi_mean, multi_covariance)): + stracks[i].mean = mean + stracks[i].covariance = cov + + def convert_coords(self, tlwh): + """Converts Top-Left-Width-Height bounding box coordinates to X-Y-Width-Height format.""" + return self.tlwh_to_xywh(tlwh) + + @staticmethod + def tlwh_to_xywh(tlwh): + """Convert bounding box to format `(center x, center y, width, height)`.""" + ret = np.asarray(tlwh).copy() + ret[:2] += ret[2:] / 2 + return ret + + +class BOTSORT(BYTETracker): + """ + An extended version of the BYTETracker class for YOLOv8, designed for object tracking with ReID and GMC algorithm. + + Attributes: + proximity_thresh (float): Threshold for spatial proximity (IoU) between tracks and detections. + appearance_thresh (float): Threshold for appearance similarity (ReID embeddings) between tracks and detections. + encoder (object): Object to handle ReID embeddings, set to None if ReID is not enabled. + gmc (GMC): An instance of the GMC algorithm for data association. + args (object): Parsed command-line arguments containing tracking parameters. + + Methods: + get_kalmanfilter(): Returns an instance of KalmanFilterXYWH for object tracking. + init_track(dets, scores, cls, img): Initialize track with detections, scores, and classes. + get_dists(tracks, detections): Get distances between tracks and detections using IoU and (optionally) ReID. + multi_predict(tracks): Predict and track multiple objects with YOLOv8 model. + + Usage: + bot_sort = BOTSORT(args, frame_rate) + bot_sort.init_track(dets, scores, cls, img) + bot_sort.multi_predict(tracks) + + Note: + The class is designed to work with the YOLOv8 object detection model and supports ReID only if enabled via args. + """ + + def __init__(self, args, frame_rate=30): + """Initialize YOLOv8 object with ReID module and GMC algorithm.""" + super().__init__(args, frame_rate) + # ReID module + self.proximity_thresh = args.proximity_thresh + self.appearance_thresh = args.appearance_thresh + + if args.with_reid: + # Haven't supported BoT-SORT(reid) yet + self.encoder = None + self.gmc = GMC(method=args.gmc_method) + + def get_kalmanfilter(self): + """Returns an instance of KalmanFilterXYWH for object tracking.""" + return KalmanFilterXYWH() + + def init_track(self, dets, scores, cls, img=None): + """Initialize track with detections, scores, and classes.""" + if len(dets) == 0: + return [] + if self.args.with_reid and self.encoder is not None: + features_keep = self.encoder.inference(img, dets) + return [BOTrack(xyxy, s, c, f) for (xyxy, s, c, f) in zip(dets, scores, cls, features_keep)] # detections + else: + return [BOTrack(xyxy, s, c) for (xyxy, s, c) in zip(dets, scores, cls)] # detections + + def get_dists(self, tracks, detections): + """Get distances between tracks and detections using IoU and (optionally) ReID embeddings.""" + dists = matching.iou_distance(tracks, detections) + dists_mask = dists > self.proximity_thresh + + # TODO: mot20 + # if not self.args.mot20: + dists = matching.fuse_score(dists, detections) + + if self.args.with_reid and self.encoder is not None: + emb_dists = matching.embedding_distance(tracks, detections) / 2.0 + emb_dists[emb_dists > self.appearance_thresh] = 1.0 + emb_dists[dists_mask] = 1.0 + dists = np.minimum(dists, emb_dists) + return dists + + def multi_predict(self, tracks): + """Predict and track multiple objects with YOLOv8 model.""" + BOTrack.multi_predict(tracks) + + def reset(self): + """Reset tracker.""" + super().reset() + self.gmc.reset_params() diff --git a/ultralytics/trackers/byte_tracker.py b/ultralytics/trackers/byte_tracker.py new file mode 100644 index 0000000..61d788b --- /dev/null +++ b/ultralytics/trackers/byte_tracker.py @@ -0,0 +1,444 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import numpy as np + +from ..utils import LOGGER +from ..utils.ops import xywh2ltwh +from .basetrack import BaseTrack, TrackState +from .utils import matching +from .utils.kalman_filter import KalmanFilterXYAH + + +class STrack(BaseTrack): + """ + Single object tracking representation that uses Kalman filtering for state estimation. + + This class is responsible for storing all the information regarding individual tracklets and performs state updates + and predictions based on Kalman filter. + + Attributes: + shared_kalman (KalmanFilterXYAH): Shared Kalman filter that is used across all STrack instances for prediction. + _tlwh (np.ndarray): Private attribute to store top-left corner coordinates and width and height of bounding box. + kalman_filter (KalmanFilterXYAH): Instance of Kalman filter used for this particular object track. + mean (np.ndarray): Mean state estimate vector. + covariance (np.ndarray): Covariance of state estimate. + is_activated (bool): Boolean flag indicating if the track has been activated. + score (float): Confidence score of the track. + tracklet_len (int): Length of the tracklet. + cls (any): Class label for the object. + idx (int): Index or identifier for the object. + frame_id (int): Current frame ID. + start_frame (int): Frame where the object was first detected. + + Methods: + predict(): Predict the next state of the object using Kalman filter. + multi_predict(stracks): Predict the next states for multiple tracks. + multi_gmc(stracks, H): Update multiple track states using a homography matrix. + activate(kalman_filter, frame_id): Activate a new tracklet. + re_activate(new_track, frame_id, new_id): Reactivate a previously lost tracklet. + update(new_track, frame_id): Update the state of a matched track. + convert_coords(tlwh): Convert bounding box to x-y-aspect-height format. + tlwh_to_xyah(tlwh): Convert tlwh bounding box to xyah format. + """ + + shared_kalman = KalmanFilterXYAH() + + def __init__(self, xywh, score, cls): + """Initialize new STrack instance.""" + super().__init__() + # xywh+idx or xywha+idx + assert len(xywh) in {5, 6}, f"expected 5 or 6 values but got {len(xywh)}" + self._tlwh = np.asarray(xywh2ltwh(xywh[:4]), dtype=np.float32) + self.kalman_filter = None + self.mean, self.covariance = None, None + self.is_activated = False + + self.score = score + self.tracklet_len = 0 + self.cls = cls + self.idx = xywh[-1] + self.angle = xywh[4] if len(xywh) == 6 else None + + def predict(self): + """Predicts mean and covariance using Kalman filter.""" + mean_state = self.mean.copy() + if self.state != TrackState.Tracked: + mean_state[7] = 0 + self.mean, self.covariance = self.kalman_filter.predict(mean_state, self.covariance) + + @staticmethod + def multi_predict(stracks): + """Perform multi-object predictive tracking using Kalman filter for given stracks.""" + if len(stracks) <= 0: + return + multi_mean = np.asarray([st.mean.copy() for st in stracks]) + multi_covariance = np.asarray([st.covariance for st in stracks]) + for i, st in enumerate(stracks): + if st.state != TrackState.Tracked: + multi_mean[i][7] = 0 + multi_mean, multi_covariance = STrack.shared_kalman.multi_predict(multi_mean, multi_covariance) + for i, (mean, cov) in enumerate(zip(multi_mean, multi_covariance)): + stracks[i].mean = mean + stracks[i].covariance = cov + + @staticmethod + def multi_gmc(stracks, H=np.eye(2, 3)): + """Update state tracks positions and covariances using a homography matrix.""" + if len(stracks) > 0: + multi_mean = np.asarray([st.mean.copy() for st in stracks]) + multi_covariance = np.asarray([st.covariance for st in stracks]) + + R = H[:2, :2] + R8x8 = np.kron(np.eye(4, dtype=float), R) + t = H[:2, 2] + + for i, (mean, cov) in enumerate(zip(multi_mean, multi_covariance)): + mean = R8x8.dot(mean) + mean[:2] += t + cov = R8x8.dot(cov).dot(R8x8.transpose()) + + stracks[i].mean = mean + stracks[i].covariance = cov + + def activate(self, kalman_filter, frame_id): + """Start a new tracklet.""" + self.kalman_filter = kalman_filter + self.track_id = self.next_id() + self.mean, self.covariance = self.kalman_filter.initiate(self.convert_coords(self._tlwh)) + + self.tracklet_len = 0 + self.state = TrackState.Tracked + if frame_id == 1: + self.is_activated = True + self.frame_id = frame_id + self.start_frame = frame_id + + def re_activate(self, new_track, frame_id, new_id=False): + """Reactivates a previously lost track with a new detection.""" + self.mean, self.covariance = self.kalman_filter.update( + self.mean, self.covariance, self.convert_coords(new_track.tlwh) + ) + self.tracklet_len = 0 + self.state = TrackState.Tracked + self.is_activated = True + self.frame_id = frame_id + if new_id: + self.track_id = self.next_id() + self.score = new_track.score + self.cls = new_track.cls + self.angle = new_track.angle + self.idx = new_track.idx + + def update(self, new_track, frame_id): + """ + Update the state of a matched track. + + Args: + new_track (STrack): The new track containing updated information. + frame_id (int): The ID of the current frame. + """ + self.frame_id = frame_id + self.tracklet_len += 1 + + new_tlwh = new_track.tlwh + self.mean, self.covariance = self.kalman_filter.update( + self.mean, self.covariance, self.convert_coords(new_tlwh) + ) + self.state = TrackState.Tracked + self.is_activated = True + + self.score = new_track.score + self.cls = new_track.cls + self.angle = new_track.angle + self.idx = new_track.idx + + def convert_coords(self, tlwh): + """Convert a bounding box's top-left-width-height format to its x-y-aspect-height equivalent.""" + return self.tlwh_to_xyah(tlwh) + + @property + def tlwh(self): + """Get current position in bounding box format (top left x, top left y, width, height).""" + if self.mean is None: + return self._tlwh.copy() + ret = self.mean[:4].copy() + ret[2] *= ret[3] + ret[:2] -= ret[2:] / 2 + return ret + + @property + def xyxy(self): + """Convert bounding box to format (min x, min y, max x, max y), i.e., (top left, bottom right).""" + ret = self.tlwh.copy() + ret[2:] += ret[:2] + return ret + + @staticmethod + def tlwh_to_xyah(tlwh): + """Convert bounding box to format (center x, center y, aspect ratio, height), where the aspect ratio is width / + height. + """ + ret = np.asarray(tlwh).copy() + ret[:2] += ret[2:] / 2 + ret[2] /= ret[3] + return ret + + @property + def xywh(self): + """Get current position in bounding box format (center x, center y, width, height).""" + ret = np.asarray(self.tlwh).copy() + ret[:2] += ret[2:] / 2 + return ret + + @property + def xywha(self): + """Get current position in bounding box format (center x, center y, width, height, angle).""" + if self.angle is None: + LOGGER.warning("WARNING ⚠️ `angle` attr not found, returning `xywh` instead.") + return self.xywh + return np.concatenate([self.xywh, self.angle[None]]) + + @property + def result(self): + """Get current tracking results.""" + coords = self.xyxy if self.angle is None else self.xywha + return coords.tolist() + [self.track_id, self.score, self.cls, self.idx] + + def __repr__(self): + """Return a string representation of the BYTETracker object with start and end frames and track ID.""" + return f"OT_{self.track_id}_({self.start_frame}-{self.end_frame})" + + +class BYTETracker: + """ + BYTETracker: A tracking algorithm built on top of YOLOv8 for object detection and tracking. + + The class is responsible for initializing, updating, and managing the tracks for detected objects in a video + sequence. It maintains the state of tracked, lost, and removed tracks over frames, utilizes Kalman filtering for + predicting the new object locations, and performs data association. + + Attributes: + tracked_stracks (list[STrack]): List of successfully activated tracks. + lost_stracks (list[STrack]): List of lost tracks. + removed_stracks (list[STrack]): List of removed tracks. + frame_id (int): The current frame ID. + args (namespace): Command-line arguments. + max_time_lost (int): The maximum frames for a track to be considered as 'lost'. + kalman_filter (object): Kalman Filter object. + + Methods: + update(results, img=None): Updates object tracker with new detections. + get_kalmanfilter(): Returns a Kalman filter object for tracking bounding boxes. + init_track(dets, scores, cls, img=None): Initialize object tracking with detections. + get_dists(tracks, detections): Calculates the distance between tracks and detections. + multi_predict(tracks): Predicts the location of tracks. + reset_id(): Resets the ID counter of STrack. + joint_stracks(tlista, tlistb): Combines two lists of stracks. + sub_stracks(tlista, tlistb): Filters out the stracks present in the second list from the first list. + remove_duplicate_stracks(stracksa, stracksb): Removes duplicate stracks based on IoU. + """ + + def __init__(self, args, frame_rate=30): + """Initialize a YOLOv8 object to track objects with given arguments and frame rate.""" + self.tracked_stracks = [] # type: list[STrack] + self.lost_stracks = [] # type: list[STrack] + self.removed_stracks = [] # type: list[STrack] + + self.frame_id = 0 + self.args = args + self.max_time_lost = int(frame_rate / 30.0 * args.track_buffer) + self.kalman_filter = self.get_kalmanfilter() + self.reset_id() + + def update(self, results, img=None): + """Updates object tracker with new detections and returns tracked object bounding boxes.""" + self.frame_id += 1 + activated_stracks = [] + refind_stracks = [] + lost_stracks = [] + removed_stracks = [] + + scores = results.conf + bboxes = results.xywhr if hasattr(results, "xywhr") else results.xywh + # Add index + bboxes = np.concatenate([bboxes, np.arange(len(bboxes)).reshape(-1, 1)], axis=-1) + cls = results.cls + + remain_inds = scores > self.args.track_high_thresh + inds_low = scores > self.args.track_low_thresh + inds_high = scores < self.args.track_high_thresh + + inds_second = np.logical_and(inds_low, inds_high) + dets_second = bboxes[inds_second] + dets = bboxes[remain_inds] + scores_keep = scores[remain_inds] + scores_second = scores[inds_second] + cls_keep = cls[remain_inds] + cls_second = cls[inds_second] + + detections = self.init_track(dets, scores_keep, cls_keep, img) + # Add newly detected tracklets to tracked_stracks + unconfirmed = [] + tracked_stracks = [] # type: list[STrack] + for track in self.tracked_stracks: + if not track.is_activated: + unconfirmed.append(track) + else: + tracked_stracks.append(track) + # Step 2: First association, with high score detection boxes + strack_pool = self.joint_stracks(tracked_stracks, self.lost_stracks) + # Predict the current location with KF + self.multi_predict(strack_pool) + if hasattr(self, "gmc") and img is not None: + warp = self.gmc.apply(img, dets) + STrack.multi_gmc(strack_pool, warp) + STrack.multi_gmc(unconfirmed, warp) + + dists = self.get_dists(strack_pool, detections) + matches, u_track, u_detection = matching.linear_assignment(dists, thresh=self.args.match_thresh) + + for itracked, idet in matches: + track = strack_pool[itracked] + det = detections[idet] + if track.state == TrackState.Tracked: + track.update(det, self.frame_id) + activated_stracks.append(track) + else: + track.re_activate(det, self.frame_id, new_id=False) + refind_stracks.append(track) + # Step 3: Second association, with low score detection boxes association the untrack to the low score detections + detections_second = self.init_track(dets_second, scores_second, cls_second, img) + r_tracked_stracks = [strack_pool[i] for i in u_track if strack_pool[i].state == TrackState.Tracked] + # TODO + dists = matching.iou_distance(r_tracked_stracks, detections_second) + matches, u_track, u_detection_second = matching.linear_assignment(dists, thresh=0.5) + for itracked, idet in matches: + track = r_tracked_stracks[itracked] + det = detections_second[idet] + if track.state == TrackState.Tracked: + track.update(det, self.frame_id) + activated_stracks.append(track) + else: + track.re_activate(det, self.frame_id, new_id=False) + refind_stracks.append(track) + + for it in u_track: + track = r_tracked_stracks[it] + if track.state != TrackState.Lost: + track.mark_lost() + lost_stracks.append(track) + # Deal with unconfirmed tracks, usually tracks with only one beginning frame + detections = [detections[i] for i in u_detection] + dists = self.get_dists(unconfirmed, detections) + matches, u_unconfirmed, u_detection = matching.linear_assignment(dists, thresh=0.7) + for itracked, idet in matches: + unconfirmed[itracked].update(detections[idet], self.frame_id) + activated_stracks.append(unconfirmed[itracked]) + for it in u_unconfirmed: + track = unconfirmed[it] + track.mark_removed() + removed_stracks.append(track) + # Step 4: Init new stracks + for inew in u_detection: + track = detections[inew] + if track.score < self.args.new_track_thresh: + continue + track.activate(self.kalman_filter, self.frame_id) + activated_stracks.append(track) + # Step 5: Update state + for track in self.lost_stracks: + if self.frame_id - track.end_frame > self.max_time_lost: + track.mark_removed() + removed_stracks.append(track) + + self.tracked_stracks = [t for t in self.tracked_stracks if t.state == TrackState.Tracked] + self.tracked_stracks = self.joint_stracks(self.tracked_stracks, activated_stracks) + self.tracked_stracks = self.joint_stracks(self.tracked_stracks, refind_stracks) + self.lost_stracks = self.sub_stracks(self.lost_stracks, self.tracked_stracks) + self.lost_stracks.extend(lost_stracks) + self.lost_stracks = self.sub_stracks(self.lost_stracks, self.removed_stracks) + self.tracked_stracks, self.lost_stracks = self.remove_duplicate_stracks(self.tracked_stracks, self.lost_stracks) + self.removed_stracks.extend(removed_stracks) + if len(self.removed_stracks) > 1000: + self.removed_stracks = self.removed_stracks[-999:] # clip remove stracks to 1000 maximum + + return np.asarray([x.result for x in self.tracked_stracks if x.is_activated], dtype=np.float32) + + def get_kalmanfilter(self): + """Returns a Kalman filter object for tracking bounding boxes.""" + return KalmanFilterXYAH() + + def init_track(self, dets, scores, cls, img=None): + """Initialize object tracking with detections and scores using STrack algorithm.""" + return [STrack(xyxy, s, c) for (xyxy, s, c) in zip(dets, scores, cls)] if len(dets) else [] # detections + + def get_dists(self, tracks, detections): + """Calculates the distance between tracks and detections using IoU and fuses scores.""" + dists = matching.iou_distance(tracks, detections) + # TODO: mot20 + # if not self.args.mot20: + dists = matching.fuse_score(dists, detections) + return dists + + def multi_predict(self, tracks): + """Returns the predicted tracks using the YOLOv8 network.""" + STrack.multi_predict(tracks) + + @staticmethod + def reset_id(): + """Resets the ID counter of STrack.""" + STrack.reset_id() + + def reset(self): + """Reset tracker.""" + self.tracked_stracks = [] # type: list[STrack] + self.lost_stracks = [] # type: list[STrack] + self.removed_stracks = [] # type: list[STrack] + self.frame_id = 0 + self.kalman_filter = self.get_kalmanfilter() + self.reset_id() + + @staticmethod + def joint_stracks(tlista, tlistb): + """Combine two lists of stracks into a single one.""" + exists = {} + res = [] + for t in tlista: + exists[t.track_id] = 1 + res.append(t) + for t in tlistb: + tid = t.track_id + if not exists.get(tid, 0): + exists[tid] = 1 + res.append(t) + return res + + @staticmethod + def sub_stracks(tlista, tlistb): + """DEPRECATED CODE in https://github.com/ultralytics/ultralytics/pull/1890/ + stracks = {t.track_id: t for t in tlista} + for t in tlistb: + tid = t.track_id + if stracks.get(tid, 0): + del stracks[tid] + return list(stracks.values()) + """ + track_ids_b = {t.track_id for t in tlistb} + return [t for t in tlista if t.track_id not in track_ids_b] + + @staticmethod + def remove_duplicate_stracks(stracksa, stracksb): + """Remove duplicate stracks with non-maximum IoU distance.""" + pdist = matching.iou_distance(stracksa, stracksb) + pairs = np.where(pdist < 0.15) + dupa, dupb = [], [] + for p, q in zip(*pairs): + timep = stracksa[p].frame_id - stracksa[p].start_frame + timeq = stracksb[q].frame_id - stracksb[q].start_frame + if timep > timeq: + dupb.append(q) + else: + dupa.append(p) + resa = [t for i, t in enumerate(stracksa) if i not in dupa] + resb = [t for i, t in enumerate(stracksb) if i not in dupb] + return resa, resb diff --git a/ultralytics/trackers/track.py b/ultralytics/trackers/track.py new file mode 100644 index 0000000..de25671 --- /dev/null +++ b/ultralytics/trackers/track.py @@ -0,0 +1,90 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from functools import partial +from pathlib import Path + +import torch + +from ultralytics.utils import IterableSimpleNamespace, yaml_load +from ultralytics.utils.checks import check_yaml + +from .bot_sort import BOTSORT +from .byte_tracker import BYTETracker + +# A mapping of tracker types to corresponding tracker classes +TRACKER_MAP = {"bytetrack": BYTETracker, "botsort": BOTSORT} + + +def on_predict_start(predictor: object, persist: bool = False) -> None: + """ + Initialize trackers for object tracking during prediction. + + Args: + predictor (object): The predictor object to initialize trackers for. + persist (bool, optional): Whether to persist the trackers if they already exist. Defaults to False. + + Raises: + AssertionError: If the tracker_type is not 'bytetrack' or 'botsort'. + """ + if hasattr(predictor, "trackers") and persist: + return + + tracker = check_yaml(predictor.args.tracker) + cfg = IterableSimpleNamespace(**yaml_load(tracker)) + + if cfg.tracker_type not in {"bytetrack", "botsort"}: + raise AssertionError(f"Only 'bytetrack' and 'botsort' are supported for now, but got '{cfg.tracker_type}'") + + trackers = [] + for _ in range(predictor.dataset.bs): + tracker = TRACKER_MAP[cfg.tracker_type](args=cfg, frame_rate=30) + trackers.append(tracker) + if predictor.dataset.mode != "stream": # only need one tracker for other modes. + break + predictor.trackers = trackers + predictor.vid_path = [None] * predictor.dataset.bs # for determining when to reset tracker on new video + + +def on_predict_postprocess_end(predictor: object, persist: bool = False) -> None: + """ + Postprocess detected boxes and update with object tracking. + + Args: + predictor (object): The predictor object containing the predictions. + persist (bool, optional): Whether to persist the trackers if they already exist. Defaults to False. + """ + path, im0s = predictor.batch[:2] + + is_obb = predictor.args.task == "obb" + is_stream = predictor.dataset.mode == "stream" + for i in range(len(im0s)): + tracker = predictor.trackers[i if is_stream else 0] + vid_path = predictor.save_dir / Path(path[i]).name + if not persist and predictor.vid_path[i if is_stream else 0] != vid_path: + tracker.reset() + predictor.vid_path[i if is_stream else 0] = vid_path + + det = (predictor.results[i].obb if is_obb else predictor.results[i].boxes).cpu().numpy() + if len(det) == 0: + continue + tracks = tracker.update(det, im0s[i]) + if len(tracks) == 0: + continue + idx = tracks[:, -1].astype(int) + predictor.results[i] = predictor.results[i][idx] + + update_args = dict() + update_args["obb" if is_obb else "boxes"] = torch.as_tensor(tracks[:, :-1]) + predictor.results[i].update(**update_args) + + +def register_tracker(model: object, persist: bool) -> None: + """ + Register tracking callbacks to the model for object tracking during prediction. + + Args: + model (object): The model object to register tracking callbacks for. + persist (bool): Whether to persist the trackers if they already exist. + """ + model.add_callback("on_predict_start", partial(on_predict_start, persist=persist)) + model.add_callback("on_predict_postprocess_end", partial(on_predict_postprocess_end, persist=persist)) diff --git a/ultralytics/trackers/utils/__init__.py b/ultralytics/trackers/utils/__init__.py new file mode 100644 index 0000000..9e68dc1 --- /dev/null +++ b/ultralytics/trackers/utils/__init__.py @@ -0,0 +1 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license diff --git a/ultralytics/trackers/utils/gmc.py b/ultralytics/trackers/utils/gmc.py new file mode 100644 index 0000000..052bf94 --- /dev/null +++ b/ultralytics/trackers/utils/gmc.py @@ -0,0 +1,363 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import copy + +import cv2 +import numpy as np + +from ultralytics.utils import LOGGER + + +class GMC: + """ + Generalized Motion Compensation (GMC) class for tracking and object detection in video frames. + + This class provides methods for tracking and detecting objects based on several tracking algorithms including ORB, + SIFT, ECC, and Sparse Optical Flow. It also supports downscaling of frames for computational efficiency. + + Attributes: + method (str): The method used for tracking. Options include 'orb', 'sift', 'ecc', 'sparseOptFlow', 'none'. + downscale (int): Factor by which to downscale the frames for processing. + prevFrame (np.ndarray): Stores the previous frame for tracking. + prevKeyPoints (list): Stores the keypoints from the previous frame. + prevDescriptors (np.ndarray): Stores the descriptors from the previous frame. + initializedFirstFrame (bool): Flag to indicate if the first frame has been processed. + + Methods: + __init__(self, method='sparseOptFlow', downscale=2): Initializes a GMC object with the specified method + and downscale factor. + apply(self, raw_frame, detections=None): Applies the chosen method to a raw frame and optionally uses + provided detections. + applyEcc(self, raw_frame, detections=None): Applies the ECC algorithm to a raw frame. + applyFeatures(self, raw_frame, detections=None): Applies feature-based methods like ORB or SIFT to a raw frame. + applySparseOptFlow(self, raw_frame, detections=None): Applies the Sparse Optical Flow method to a raw frame. + """ + + def __init__(self, method: str = "sparseOptFlow", downscale: int = 2) -> None: + """ + Initialize a video tracker with specified parameters. + + Args: + method (str): The method used for tracking. Options include 'orb', 'sift', 'ecc', 'sparseOptFlow', 'none'. + downscale (int): Downscale factor for processing frames. + """ + super().__init__() + + self.method = method + self.downscale = max(1, int(downscale)) + + if self.method == "orb": + self.detector = cv2.FastFeatureDetector_create(20) + self.extractor = cv2.ORB_create() + self.matcher = cv2.BFMatcher(cv2.NORM_HAMMING) + + elif self.method == "sift": + self.detector = cv2.SIFT_create(nOctaveLayers=3, contrastThreshold=0.02, edgeThreshold=20) + self.extractor = cv2.SIFT_create(nOctaveLayers=3, contrastThreshold=0.02, edgeThreshold=20) + self.matcher = cv2.BFMatcher(cv2.NORM_L2) + + elif self.method == "ecc": + number_of_iterations = 5000 + termination_eps = 1e-6 + self.warp_mode = cv2.MOTION_EUCLIDEAN + self.criteria = (cv2.TERM_CRITERIA_EPS | cv2.TERM_CRITERIA_COUNT, number_of_iterations, termination_eps) + + elif self.method == "sparseOptFlow": + self.feature_params = dict( + maxCorners=1000, qualityLevel=0.01, minDistance=1, blockSize=3, useHarrisDetector=False, k=0.04 + ) + + elif self.method in {"none", "None", None}: + self.method = None + else: + raise ValueError(f"Error: Unknown GMC method:{method}") + + self.prevFrame = None + self.prevKeyPoints = None + self.prevDescriptors = None + self.initializedFirstFrame = False + + def apply(self, raw_frame: np.array, detections: list = None) -> np.array: + """ + Apply object detection on a raw frame using specified method. + + Args: + raw_frame (np.ndarray): The raw frame to be processed. + detections (list): List of detections to be used in the processing. + + Returns: + (np.ndarray): Processed frame. + + Examples: + >>> gmc = GMC() + >>> gmc.apply(np.array([[1, 2, 3], [4, 5, 6]])) + array([[1, 2, 3], + [4, 5, 6]]) + """ + if self.method in {"orb", "sift"}: + return self.applyFeatures(raw_frame, detections) + elif self.method == "ecc": + return self.applyEcc(raw_frame) + elif self.method == "sparseOptFlow": + return self.applySparseOptFlow(raw_frame) + else: + return np.eye(2, 3) + + def applyEcc(self, raw_frame: np.array) -> np.array: + """ + Apply ECC algorithm to a raw frame. + + Args: + raw_frame (np.ndarray): The raw frame to be processed. + + Returns: + (np.ndarray): Processed frame. + + Examples: + >>> gmc = GMC() + >>> gmc.applyEcc(np.array([[1, 2, 3], [4, 5, 6]])) + array([[1, 2, 3], + [4, 5, 6]]) + """ + height, width, _ = raw_frame.shape + frame = cv2.cvtColor(raw_frame, cv2.COLOR_BGR2GRAY) + H = np.eye(2, 3, dtype=np.float32) + + # Downscale image + if self.downscale > 1.0: + frame = cv2.GaussianBlur(frame, (3, 3), 1.5) + frame = cv2.resize(frame, (width // self.downscale, height // self.downscale)) + width = width // self.downscale + height = height // self.downscale + + # Handle first frame + if not self.initializedFirstFrame: + # Initialize data + self.prevFrame = frame.copy() + + # Initialization done + self.initializedFirstFrame = True + + return H + + # Run the ECC algorithm. The results are stored in warp_matrix. + # (cc, H) = cv2.findTransformECC(self.prevFrame, frame, H, self.warp_mode, self.criteria) + try: + (_, H) = cv2.findTransformECC(self.prevFrame, frame, H, self.warp_mode, self.criteria, None, 1) + except Exception as e: + LOGGER.warning(f"WARNING: find transform failed. Set warp as identity {e}") + + return H + + def applyFeatures(self, raw_frame: np.array, detections: list = None) -> np.array: + """ + Apply feature-based methods like ORB or SIFT to a raw frame. + + Args: + raw_frame (np.ndarray): The raw frame to be processed. + detections (list): List of detections to be used in the processing. + + Returns: + (np.ndarray): Processed frame. + + Examples: + >>> gmc = GMC() + >>> gmc.applyFeatures(np.array([[1, 2, 3], [4, 5, 6]])) + array([[1, 2, 3], + [4, 5, 6]]) + """ + height, width, _ = raw_frame.shape + frame = cv2.cvtColor(raw_frame, cv2.COLOR_BGR2GRAY) + H = np.eye(2, 3) + + # Downscale image + if self.downscale > 1.0: + frame = cv2.resize(frame, (width // self.downscale, height // self.downscale)) + width = width // self.downscale + height = height // self.downscale + + # Find the keypoints + mask = np.zeros_like(frame) + mask[int(0.02 * height) : int(0.98 * height), int(0.02 * width) : int(0.98 * width)] = 255 + if detections is not None: + for det in detections: + tlbr = (det[:4] / self.downscale).astype(np.int_) + mask[tlbr[1] : tlbr[3], tlbr[0] : tlbr[2]] = 0 + + keypoints = self.detector.detect(frame, mask) + + # Compute the descriptors + keypoints, descriptors = self.extractor.compute(frame, keypoints) + + # Handle first frame + if not self.initializedFirstFrame: + # Initialize data + self.prevFrame = frame.copy() + self.prevKeyPoints = copy.copy(keypoints) + self.prevDescriptors = copy.copy(descriptors) + + # Initialization done + self.initializedFirstFrame = True + + return H + + # Match descriptors + knnMatches = self.matcher.knnMatch(self.prevDescriptors, descriptors, 2) + + # Filter matches based on smallest spatial distance + matches = [] + spatialDistances = [] + + maxSpatialDistance = 0.25 * np.array([width, height]) + + # Handle empty matches case + if len(knnMatches) == 0: + # Store to next iteration + self.prevFrame = frame.copy() + self.prevKeyPoints = copy.copy(keypoints) + self.prevDescriptors = copy.copy(descriptors) + + return H + + for m, n in knnMatches: + if m.distance < 0.9 * n.distance: + prevKeyPointLocation = self.prevKeyPoints[m.queryIdx].pt + currKeyPointLocation = keypoints[m.trainIdx].pt + + spatialDistance = ( + prevKeyPointLocation[0] - currKeyPointLocation[0], + prevKeyPointLocation[1] - currKeyPointLocation[1], + ) + + if (np.abs(spatialDistance[0]) < maxSpatialDistance[0]) and ( + np.abs(spatialDistance[1]) < maxSpatialDistance[1] + ): + spatialDistances.append(spatialDistance) + matches.append(m) + + meanSpatialDistances = np.mean(spatialDistances, 0) + stdSpatialDistances = np.std(spatialDistances, 0) + + inliers = (spatialDistances - meanSpatialDistances) < 2.5 * stdSpatialDistances + + goodMatches = [] + prevPoints = [] + currPoints = [] + for i in range(len(matches)): + if inliers[i, 0] and inliers[i, 1]: + goodMatches.append(matches[i]) + prevPoints.append(self.prevKeyPoints[matches[i].queryIdx].pt) + currPoints.append(keypoints[matches[i].trainIdx].pt) + + prevPoints = np.array(prevPoints) + currPoints = np.array(currPoints) + + # Draw the keypoint matches on the output image + # if False: + # import matplotlib.pyplot as plt + # matches_img = np.hstack((self.prevFrame, frame)) + # matches_img = cv2.cvtColor(matches_img, cv2.COLOR_GRAY2BGR) + # W = self.prevFrame.shape[1] + # for m in goodMatches: + # prev_pt = np.array(self.prevKeyPoints[m.queryIdx].pt, dtype=np.int_) + # curr_pt = np.array(keypoints[m.trainIdx].pt, dtype=np.int_) + # curr_pt[0] += W + # color = np.random.randint(0, 255, 3) + # color = (int(color[0]), int(color[1]), int(color[2])) + # + # matches_img = cv2.line(matches_img, prev_pt, curr_pt, tuple(color), 1, cv2.LINE_AA) + # matches_img = cv2.circle(matches_img, prev_pt, 2, tuple(color), -1) + # matches_img = cv2.circle(matches_img, curr_pt, 2, tuple(color), -1) + # + # plt.figure() + # plt.imshow(matches_img) + # plt.show() + + # Find rigid matrix + if prevPoints.shape[0] > 4: + H, inliers = cv2.estimateAffinePartial2D(prevPoints, currPoints, cv2.RANSAC) + + # Handle downscale + if self.downscale > 1.0: + H[0, 2] *= self.downscale + H[1, 2] *= self.downscale + else: + LOGGER.warning("WARNING: not enough matching points") + + # Store to next iteration + self.prevFrame = frame.copy() + self.prevKeyPoints = copy.copy(keypoints) + self.prevDescriptors = copy.copy(descriptors) + + return H + + def applySparseOptFlow(self, raw_frame: np.array) -> np.array: + """ + Apply Sparse Optical Flow method to a raw frame. + + Args: + raw_frame (np.ndarray): The raw frame to be processed. + + Returns: + (np.ndarray): Processed frame. + + Examples: + >>> gmc = GMC() + >>> gmc.applySparseOptFlow(np.array([[1, 2, 3], [4, 5, 6]])) + array([[1, 2, 3], + [4, 5, 6]]) + """ + height, width, _ = raw_frame.shape + frame = cv2.cvtColor(raw_frame, cv2.COLOR_BGR2GRAY) + H = np.eye(2, 3) + + # Downscale image + if self.downscale > 1.0: + frame = cv2.resize(frame, (width // self.downscale, height // self.downscale)) + + # Find the keypoints + keypoints = cv2.goodFeaturesToTrack(frame, mask=None, **self.feature_params) + + # Handle first frame + if not self.initializedFirstFrame or self.prevKeyPoints is None: + self.prevFrame = frame.copy() + self.prevKeyPoints = copy.copy(keypoints) + self.initializedFirstFrame = True + return H + + # Find correspondences + matchedKeypoints, status, _ = cv2.calcOpticalFlowPyrLK(self.prevFrame, frame, self.prevKeyPoints, None) + + # Leave good correspondences only + prevPoints = [] + currPoints = [] + + for i in range(len(status)): + if status[i]: + prevPoints.append(self.prevKeyPoints[i]) + currPoints.append(matchedKeypoints[i]) + + prevPoints = np.array(prevPoints) + currPoints = np.array(currPoints) + + # Find rigid matrix + if (prevPoints.shape[0] > 4) and (prevPoints.shape[0] == prevPoints.shape[0]): + H, _ = cv2.estimateAffinePartial2D(prevPoints, currPoints, cv2.RANSAC) + + if self.downscale > 1.0: + H[0, 2] *= self.downscale + H[1, 2] *= self.downscale + else: + LOGGER.warning("WARNING: not enough matching points") + + self.prevFrame = frame.copy() + self.prevKeyPoints = copy.copy(keypoints) + + return H + + def reset_params(self) -> None: + """Reset parameters.""" + self.prevFrame = None + self.prevKeyPoints = None + self.prevDescriptors = None + self.initializedFirstFrame = False diff --git a/ultralytics/trackers/utils/kalman_filter.py b/ultralytics/trackers/utils/kalman_filter.py new file mode 100644 index 0000000..36e280f --- /dev/null +++ b/ultralytics/trackers/utils/kalman_filter.py @@ -0,0 +1,360 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import numpy as np +import scipy.linalg + + +class KalmanFilterXYAH: + """ + For bytetrack. A simple Kalman filter for tracking bounding boxes in image space. + + The 8-dimensional state space (x, y, a, h, vx, vy, va, vh) contains the bounding box center position (x, y), aspect + ratio a, height h, and their respective velocities. + + Object motion follows a constant velocity model. The bounding box location (x, y, a, h) is taken as direct + observation of the state space (linear observation model). + """ + + def __init__(self): + """Initialize Kalman filter model matrices with motion and observation uncertainty weights.""" + ndim, dt = 4, 1.0 + + # Create Kalman filter model matrices + self._motion_mat = np.eye(2 * ndim, 2 * ndim) + for i in range(ndim): + self._motion_mat[i, ndim + i] = dt + self._update_mat = np.eye(ndim, 2 * ndim) + + # Motion and observation uncertainty are chosen relative to the current state estimate. These weights control + # the amount of uncertainty in the model. + self._std_weight_position = 1.0 / 20 + self._std_weight_velocity = 1.0 / 160 + + def initiate(self, measurement: np.ndarray) -> tuple: + """ + Create track from unassociated measurement. + + Args: + measurement (ndarray): Bounding box coordinates (x, y, a, h) with center position (x, y), aspect ratio a, + and height h. + + Returns: + (tuple[ndarray, ndarray]): Returns the mean vector (8 dimensional) and covariance matrix (8x8 dimensional) + of the new track. Unobserved velocities are initialized to 0 mean. + """ + mean_pos = measurement + mean_vel = np.zeros_like(mean_pos) + mean = np.r_[mean_pos, mean_vel] + + std = [ + 2 * self._std_weight_position * measurement[3], + 2 * self._std_weight_position * measurement[3], + 1e-2, + 2 * self._std_weight_position * measurement[3], + 10 * self._std_weight_velocity * measurement[3], + 10 * self._std_weight_velocity * measurement[3], + 1e-5, + 10 * self._std_weight_velocity * measurement[3], + ] + covariance = np.diag(np.square(std)) + return mean, covariance + + def predict(self, mean: np.ndarray, covariance: np.ndarray) -> tuple: + """ + Run Kalman filter prediction step. + + Args: + mean (ndarray): The 8 dimensional mean vector of the object state at the previous time step. + covariance (ndarray): The 8x8 dimensional covariance matrix of the object state at the previous time step. + + Returns: + (tuple[ndarray, ndarray]): Returns the mean vector and covariance matrix of the predicted state. Unobserved + velocities are initialized to 0 mean. + """ + std_pos = [ + self._std_weight_position * mean[3], + self._std_weight_position * mean[3], + 1e-2, + self._std_weight_position * mean[3], + ] + std_vel = [ + self._std_weight_velocity * mean[3], + self._std_weight_velocity * mean[3], + 1e-5, + self._std_weight_velocity * mean[3], + ] + motion_cov = np.diag(np.square(np.r_[std_pos, std_vel])) + + mean = np.dot(mean, self._motion_mat.T) + covariance = np.linalg.multi_dot((self._motion_mat, covariance, self._motion_mat.T)) + motion_cov + + return mean, covariance + + def project(self, mean: np.ndarray, covariance: np.ndarray) -> tuple: + """ + Project state distribution to measurement space. + + Args: + mean (ndarray): The state's mean vector (8 dimensional array). + covariance (ndarray): The state's covariance matrix (8x8 dimensional). + + Returns: + (tuple[ndarray, ndarray]): Returns the projected mean and covariance matrix of the given state estimate. + """ + std = [ + self._std_weight_position * mean[3], + self._std_weight_position * mean[3], + 1e-1, + self._std_weight_position * mean[3], + ] + innovation_cov = np.diag(np.square(std)) + + mean = np.dot(self._update_mat, mean) + covariance = np.linalg.multi_dot((self._update_mat, covariance, self._update_mat.T)) + return mean, covariance + innovation_cov + + def multi_predict(self, mean: np.ndarray, covariance: np.ndarray) -> tuple: + """ + Run Kalman filter prediction step (Vectorized version). + + Args: + mean (ndarray): The Nx8 dimensional mean matrix of the object states at the previous time step. + covariance (ndarray): The Nx8x8 covariance matrix of the object states at the previous time step. + + Returns: + (tuple[ndarray, ndarray]): Returns the mean vector and covariance matrix of the predicted state. Unobserved + velocities are initialized to 0 mean. + """ + std_pos = [ + self._std_weight_position * mean[:, 3], + self._std_weight_position * mean[:, 3], + 1e-2 * np.ones_like(mean[:, 3]), + self._std_weight_position * mean[:, 3], + ] + std_vel = [ + self._std_weight_velocity * mean[:, 3], + self._std_weight_velocity * mean[:, 3], + 1e-5 * np.ones_like(mean[:, 3]), + self._std_weight_velocity * mean[:, 3], + ] + sqr = np.square(np.r_[std_pos, std_vel]).T + + motion_cov = [np.diag(sqr[i]) for i in range(len(mean))] + motion_cov = np.asarray(motion_cov) + + mean = np.dot(mean, self._motion_mat.T) + left = np.dot(self._motion_mat, covariance).transpose((1, 0, 2)) + covariance = np.dot(left, self._motion_mat.T) + motion_cov + + return mean, covariance + + def update(self, mean: np.ndarray, covariance: np.ndarray, measurement: np.ndarray) -> tuple: + """ + Run Kalman filter correction step. + + Args: + mean (ndarray): The predicted state's mean vector (8 dimensional). + covariance (ndarray): The state's covariance matrix (8x8 dimensional). + measurement (ndarray): The 4 dimensional measurement vector (x, y, a, h), where (x, y) is the center + position, a the aspect ratio, and h the height of the bounding box. + + Returns: + (tuple[ndarray, ndarray]): Returns the measurement-corrected state distribution. + """ + projected_mean, projected_cov = self.project(mean, covariance) + + chol_factor, lower = scipy.linalg.cho_factor(projected_cov, lower=True, check_finite=False) + kalman_gain = scipy.linalg.cho_solve( + (chol_factor, lower), np.dot(covariance, self._update_mat.T).T, check_finite=False + ).T + innovation = measurement - projected_mean + + new_mean = mean + np.dot(innovation, kalman_gain.T) + new_covariance = covariance - np.linalg.multi_dot((kalman_gain, projected_cov, kalman_gain.T)) + return new_mean, new_covariance + + def gating_distance( + self, + mean: np.ndarray, + covariance: np.ndarray, + measurements: np.ndarray, + only_position: bool = False, + metric: str = "maha", + ) -> np.ndarray: + """ + Compute gating distance between state distribution and measurements. A suitable distance threshold can be + obtained from `chi2inv95`. If `only_position` is False, the chi-square distribution has 4 degrees of freedom, + otherwise 2. + + Args: + mean (ndarray): Mean vector over the state distribution (8 dimensional). + covariance (ndarray): Covariance of the state distribution (8x8 dimensional). + measurements (ndarray): An Nx4 matrix of N measurements, each in format (x, y, a, h) where (x, y) + is the bounding box center position, a the aspect ratio, and h the height. + only_position (bool, optional): If True, distance computation is done with respect to the bounding box + center position only. Defaults to False. + metric (str, optional): The metric to use for calculating the distance. Options are 'gaussian' for the + squared Euclidean distance and 'maha' for the squared Mahalanobis distance. Defaults to 'maha'. + + Returns: + (np.ndarray): Returns an array of length N, where the i-th element contains the squared distance between + (mean, covariance) and `measurements[i]`. + """ + mean, covariance = self.project(mean, covariance) + if only_position: + mean, covariance = mean[:2], covariance[:2, :2] + measurements = measurements[:, :2] + + d = measurements - mean + if metric == "gaussian": + return np.sum(d * d, axis=1) + elif metric == "maha": + cholesky_factor = np.linalg.cholesky(covariance) + z = scipy.linalg.solve_triangular(cholesky_factor, d.T, lower=True, check_finite=False, overwrite_b=True) + return np.sum(z * z, axis=0) # square maha + else: + raise ValueError("Invalid distance metric") + + +class KalmanFilterXYWH(KalmanFilterXYAH): + """ + For BoT-SORT. A simple Kalman filter for tracking bounding boxes in image space. + + The 8-dimensional state space (x, y, w, h, vx, vy, vw, vh) contains the bounding box center position (x, y), width + w, height h, and their respective velocities. + + Object motion follows a constant velocity model. The bounding box location (x, y, w, h) is taken as direct + observation of the state space (linear observation model). + """ + + def initiate(self, measurement: np.ndarray) -> tuple: + """ + Create track from unassociated measurement. + + Args: + measurement (ndarray): Bounding box coordinates (x, y, w, h) with center position (x, y), width, and height. + + Returns: + (tuple[ndarray, ndarray]): Returns the mean vector (8 dimensional) and covariance matrix (8x8 dimensional) + of the new track. Unobserved velocities are initialized to 0 mean. + """ + mean_pos = measurement + mean_vel = np.zeros_like(mean_pos) + mean = np.r_[mean_pos, mean_vel] + + std = [ + 2 * self._std_weight_position * measurement[2], + 2 * self._std_weight_position * measurement[3], + 2 * self._std_weight_position * measurement[2], + 2 * self._std_weight_position * measurement[3], + 10 * self._std_weight_velocity * measurement[2], + 10 * self._std_weight_velocity * measurement[3], + 10 * self._std_weight_velocity * measurement[2], + 10 * self._std_weight_velocity * measurement[3], + ] + covariance = np.diag(np.square(std)) + return mean, covariance + + def predict(self, mean, covariance) -> tuple: + """ + Run Kalman filter prediction step. + + Args: + mean (ndarray): The 8 dimensional mean vector of the object state at the previous time step. + covariance (ndarray): The 8x8 dimensional covariance matrix of the object state at the previous time step. + + Returns: + (tuple[ndarray, ndarray]): Returns the mean vector and covariance matrix of the predicted state. Unobserved + velocities are initialized to 0 mean. + """ + std_pos = [ + self._std_weight_position * mean[2], + self._std_weight_position * mean[3], + self._std_weight_position * mean[2], + self._std_weight_position * mean[3], + ] + std_vel = [ + self._std_weight_velocity * mean[2], + self._std_weight_velocity * mean[3], + self._std_weight_velocity * mean[2], + self._std_weight_velocity * mean[3], + ] + motion_cov = np.diag(np.square(np.r_[std_pos, std_vel])) + + mean = np.dot(mean, self._motion_mat.T) + covariance = np.linalg.multi_dot((self._motion_mat, covariance, self._motion_mat.T)) + motion_cov + + return mean, covariance + + def project(self, mean, covariance) -> tuple: + """ + Project state distribution to measurement space. + + Args: + mean (ndarray): The state's mean vector (8 dimensional array). + covariance (ndarray): The state's covariance matrix (8x8 dimensional). + + Returns: + (tuple[ndarray, ndarray]): Returns the projected mean and covariance matrix of the given state estimate. + """ + std = [ + self._std_weight_position * mean[2], + self._std_weight_position * mean[3], + self._std_weight_position * mean[2], + self._std_weight_position * mean[3], + ] + innovation_cov = np.diag(np.square(std)) + + mean = np.dot(self._update_mat, mean) + covariance = np.linalg.multi_dot((self._update_mat, covariance, self._update_mat.T)) + return mean, covariance + innovation_cov + + def multi_predict(self, mean, covariance) -> tuple: + """ + Run Kalman filter prediction step (Vectorized version). + + Args: + mean (ndarray): The Nx8 dimensional mean matrix of the object states at the previous time step. + covariance (ndarray): The Nx8x8 covariance matrix of the object states at the previous time step. + + Returns: + (tuple[ndarray, ndarray]): Returns the mean vector and covariance matrix of the predicted state. Unobserved + velocities are initialized to 0 mean. + """ + std_pos = [ + self._std_weight_position * mean[:, 2], + self._std_weight_position * mean[:, 3], + self._std_weight_position * mean[:, 2], + self._std_weight_position * mean[:, 3], + ] + std_vel = [ + self._std_weight_velocity * mean[:, 2], + self._std_weight_velocity * mean[:, 3], + self._std_weight_velocity * mean[:, 2], + self._std_weight_velocity * mean[:, 3], + ] + sqr = np.square(np.r_[std_pos, std_vel]).T + + motion_cov = [np.diag(sqr[i]) for i in range(len(mean))] + motion_cov = np.asarray(motion_cov) + + mean = np.dot(mean, self._motion_mat.T) + left = np.dot(self._motion_mat, covariance).transpose((1, 0, 2)) + covariance = np.dot(left, self._motion_mat.T) + motion_cov + + return mean, covariance + + def update(self, mean, covariance, measurement) -> tuple: + """ + Run Kalman filter correction step. + + Args: + mean (ndarray): The predicted state's mean vector (8 dimensional). + covariance (ndarray): The state's covariance matrix (8x8 dimensional). + measurement (ndarray): The 4 dimensional measurement vector (x, y, w, h), where (x, y) is the center + position, w the width, and h the height of the bounding box. + + Returns: + (tuple[ndarray, ndarray]): Returns the measurement-corrected state distribution. + """ + return super().update(mean, covariance, measurement) diff --git a/ultralytics/trackers/utils/matching.py b/ultralytics/trackers/utils/matching.py new file mode 100644 index 0000000..070e148 --- /dev/null +++ b/ultralytics/trackers/utils/matching.py @@ -0,0 +1,138 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import numpy as np +import scipy +from scipy.spatial.distance import cdist + +from ultralytics.utils.metrics import batch_probiou, bbox_ioa + +try: + import lap # for linear_assignment + + assert lap.__version__ # verify package is not directory +except (ImportError, AssertionError, AttributeError): + from ultralytics.utils.checks import check_requirements + + check_requirements("lapx>=0.5.8") # update to lap package from https://github.com/rathaROG/lapx + import lap + + +def linear_assignment(cost_matrix: np.ndarray, thresh: float, use_lap: bool = True) -> tuple: + """ + Perform linear assignment using scipy or lap.lapjv. + + Args: + cost_matrix (np.ndarray): The matrix containing cost values for assignments. + thresh (float): Threshold for considering an assignment valid. + use_lap (bool, optional): Whether to use lap.lapjv. Defaults to True. + + Returns: + Tuple with: + - matched indices + - unmatched indices from 'a' + - unmatched indices from 'b' + """ + + if cost_matrix.size == 0: + return np.empty((0, 2), dtype=int), tuple(range(cost_matrix.shape[0])), tuple(range(cost_matrix.shape[1])) + + if use_lap: + # Use lap.lapjv + # https://github.com/gatagat/lap + _, x, y = lap.lapjv(cost_matrix, extend_cost=True, cost_limit=thresh) + matches = [[ix, mx] for ix, mx in enumerate(x) if mx >= 0] + unmatched_a = np.where(x < 0)[0] + unmatched_b = np.where(y < 0)[0] + else: + # Use scipy.optimize.linear_sum_assignment + # https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.linear_sum_assignment.html + x, y = scipy.optimize.linear_sum_assignment(cost_matrix) # row x, col y + matches = np.asarray([[x[i], y[i]] for i in range(len(x)) if cost_matrix[x[i], y[i]] <= thresh]) + if len(matches) == 0: + unmatched_a = list(np.arange(cost_matrix.shape[0])) + unmatched_b = list(np.arange(cost_matrix.shape[1])) + else: + unmatched_a = list(set(np.arange(cost_matrix.shape[0])) - set(matches[:, 0])) + unmatched_b = list(set(np.arange(cost_matrix.shape[1])) - set(matches[:, 1])) + + return matches, unmatched_a, unmatched_b + + +def iou_distance(atracks: list, btracks: list) -> np.ndarray: + """ + Compute cost based on Intersection over Union (IoU) between tracks. + + Args: + atracks (list[STrack] | list[np.ndarray]): List of tracks 'a' or bounding boxes. + btracks (list[STrack] | list[np.ndarray]): List of tracks 'b' or bounding boxes. + + Returns: + (np.ndarray): Cost matrix computed based on IoU. + """ + + if atracks and isinstance(atracks[0], np.ndarray) or btracks and isinstance(btracks[0], np.ndarray): + atlbrs = atracks + btlbrs = btracks + else: + atlbrs = [track.xywha if track.angle is not None else track.xyxy for track in atracks] + btlbrs = [track.xywha if track.angle is not None else track.xyxy for track in btracks] + + ious = np.zeros((len(atlbrs), len(btlbrs)), dtype=np.float32) + if len(atlbrs) and len(btlbrs): + if len(atlbrs[0]) == 5 and len(btlbrs[0]) == 5: + ious = batch_probiou( + np.ascontiguousarray(atlbrs, dtype=np.float32), + np.ascontiguousarray(btlbrs, dtype=np.float32), + ).numpy() + else: + ious = bbox_ioa( + np.ascontiguousarray(atlbrs, dtype=np.float32), + np.ascontiguousarray(btlbrs, dtype=np.float32), + iou=True, + ) + return 1 - ious # cost matrix + + +def embedding_distance(tracks: list, detections: list, metric: str = "cosine") -> np.ndarray: + """ + Compute distance between tracks and detections based on embeddings. + + Args: + tracks (list[STrack]): List of tracks. + detections (list[BaseTrack]): List of detections. + metric (str, optional): Metric for distance computation. Defaults to 'cosine'. + + Returns: + (np.ndarray): Cost matrix computed based on embeddings. + """ + + cost_matrix = np.zeros((len(tracks), len(detections)), dtype=np.float32) + if cost_matrix.size == 0: + return cost_matrix + det_features = np.asarray([track.curr_feat for track in detections], dtype=np.float32) + # for i, track in enumerate(tracks): + # cost_matrix[i, :] = np.maximum(0.0, cdist(track.smooth_feat.reshape(1,-1), det_features, metric)) + track_features = np.asarray([track.smooth_feat for track in tracks], dtype=np.float32) + cost_matrix = np.maximum(0.0, cdist(track_features, det_features, metric)) # Normalized features + return cost_matrix + + +def fuse_score(cost_matrix: np.ndarray, detections: list) -> np.ndarray: + """ + Fuses cost matrix with detection scores to produce a single similarity matrix. + + Args: + cost_matrix (np.ndarray): The matrix containing cost values for assignments. + detections (list[BaseTrack]): List of detections with scores. + + Returns: + (np.ndarray): Fused similarity matrix. + """ + + if cost_matrix.size == 0: + return cost_matrix + iou_sim = 1 - cost_matrix + det_scores = np.array([det.score for det in detections]) + det_scores = np.expand_dims(det_scores, axis=0).repeat(cost_matrix.shape[0], axis=0) + fuse_sim = iou_sim * det_scores + return 1 - fuse_sim # fuse_cost diff --git a/ultralytics/utils/__init__.py b/ultralytics/utils/__init__.py new file mode 100644 index 0000000..ab0dcaf --- /dev/null +++ b/ultralytics/utils/__init__.py @@ -0,0 +1,1095 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import contextlib +import importlib.metadata +import inspect +import logging.config +import os +import platform +import re +import subprocess +import sys +import threading +import time +import urllib +import uuid +from pathlib import Path +from types import SimpleNamespace +from typing import Union + +import cv2 +import matplotlib.pyplot as plt +import numpy as np +import torch +import yaml +from tqdm import tqdm as tqdm_original + +from ultralytics import __version__ + +# PyTorch Multi-GPU DDP Constants +RANK = int(os.getenv("RANK", -1)) +LOCAL_RANK = int(os.getenv("LOCAL_RANK", -1)) # https://pytorch.org/docs/stable/elastic/run.html + +# Other Constants +ARGV = sys.argv or ["", ""] # sometimes sys.argv = [] +FILE = Path(__file__).resolve() +ROOT = FILE.parents[1] # YOLO +ASSETS = ROOT / "assets" # default images +DEFAULT_CFG_PATH = ROOT / "cfg/default.yaml" +NUM_THREADS = min(8, max(1, os.cpu_count() - 1)) # number of YOLOv5 multiprocessing threads +AUTOINSTALL = str(os.getenv("YOLO_AUTOINSTALL", True)).lower() == "true" # global auto-install mode +VERBOSE = str(os.getenv("YOLO_VERBOSE", True)).lower() == "true" # global verbose mode +TQDM_BAR_FORMAT = "{l_bar}{bar:10}{r_bar}" if VERBOSE else None # tqdm bar format +LOGGING_NAME = "ultralytics" +MACOS, LINUX, WINDOWS = (platform.system() == x for x in ["Darwin", "Linux", "Windows"]) # environment booleans +ARM64 = platform.machine() in {"arm64", "aarch64"} # ARM64 booleans +PYTHON_VERSION = platform.python_version() +TORCHVISION_VERSION = importlib.metadata.version("torchvision") # faster than importing torchvision +HELP_MSG = """ + Usage examples for running YOLOv8: + + 1. Install the ultralytics package: + + pip install ultralytics + + 2. Use the Python SDK: + + from ultralytics import YOLO + + # Load a model + model = YOLO('yolov8n.yaml') # build a new model from scratch + model = YOLO("yolov8n.pt") # load a pretrained model (recommended for training) + + # Use the model + results = model.train(data="coco128.yaml", epochs=3) # train the model + results = model.val() # evaluate model performance on the validation set + results = model('https://ultralytics.com/images/bus.jpg') # predict on an image + success = model.export(format='onnx') # export the model to ONNX format + + 3. Use the command line interface (CLI): + + YOLOv8 'yolo' CLI commands use the following syntax: + + yolo TASK MODE ARGS + + Where TASK (optional) is one of [detect, segment, classify] + MODE (required) is one of [train, val, predict, export] + ARGS (optional) are any number of custom 'arg=value' pairs like 'imgsz=320' that override defaults. + See all ARGS at https://docs.ultralytics.com/usage/cfg or with 'yolo cfg' + + - Train a detection model for 10 epochs with an initial learning_rate of 0.01 + yolo detect train data=coco128.yaml model=yolov8n.pt epochs=10 lr0=0.01 + + - Predict a YouTube video using a pretrained segmentation model at image size 320: + yolo segment predict model=yolov8n-seg.pt source='https://youtu.be/LNwODJXcvt4' imgsz=320 + + - Val a pretrained detection model at batch-size 1 and image size 640: + yolo detect val model=yolov8n.pt data=coco128.yaml batch=1 imgsz=640 + + - Export a YOLOv8n classification model to ONNX format at image size 224 by 128 (no TASK required) + yolo export model=yolov8n-cls.pt format=onnx imgsz=224,128 + + - Run special commands: + yolo help + yolo checks + yolo version + yolo settings + yolo copy-cfg + yolo cfg + + Docs: https://docs.ultralytics.com + Community: https://community.ultralytics.com + GitHub: https://github.com/ultralytics/ultralytics + """ + +# Settings +torch.set_printoptions(linewidth=320, precision=4, profile="default") +np.set_printoptions(linewidth=320, formatter={"float_kind": "{:11.5g}".format}) # format short g, %precision=5 +# cv2.setNumThreads(0) # prevent OpenCV from multithreading (incompatible with PyTorch DataLoader) +os.environ["NUMEXPR_MAX_THREADS"] = str(NUM_THREADS) # NumExpr max threads +os.environ["CUBLAS_WORKSPACE_CONFIG"] = ":4096:8" # for deterministic training +os.environ["TF_CPP_MIN_LOG_LEVEL"] = "2" # suppress verbose TF compiler warnings in Colab + + +class TQDM(tqdm_original): + """ + Custom Ultralytics tqdm class with different default arguments. + + Args: + *args (list): Positional arguments passed to original tqdm. + **kwargs (any): Keyword arguments, with custom defaults applied. + """ + + def __init__(self, *args, **kwargs): + """ + Initialize custom Ultralytics tqdm class with different default arguments. + + Note these can still be overridden when calling TQDM. + """ + kwargs["disable"] = not VERBOSE or kwargs.get("disable", False) # logical 'and' with default value if passed + kwargs.setdefault("bar_format", TQDM_BAR_FORMAT) # override default value if passed + super().__init__(*args, **kwargs) + + +class SimpleClass: + """Ultralytics SimpleClass is a base class providing helpful string representation, error reporting, and attribute + access methods for easier debugging and usage. + """ + + def __str__(self): + """Return a human-readable string representation of the object.""" + attr = [] + for a in dir(self): + v = getattr(self, a) + if not callable(v) and not a.startswith("_"): + if isinstance(v, SimpleClass): + # Display only the module and class name for subclasses + s = f"{a}: {v.__module__}.{v.__class__.__name__} object" + else: + s = f"{a}: {repr(v)}" + attr.append(s) + return f"{self.__module__}.{self.__class__.__name__} object with attributes:\n\n" + "\n".join(attr) + + def __repr__(self): + """Return a machine-readable string representation of the object.""" + return self.__str__() + + def __getattr__(self, attr): + """Custom attribute access error message with helpful information.""" + name = self.__class__.__name__ + raise AttributeError(f"'{name}' object has no attribute '{attr}'. See valid attributes below.\n{self.__doc__}") + + +class IterableSimpleNamespace(SimpleNamespace): + """Ultralytics IterableSimpleNamespace is an extension class of SimpleNamespace that adds iterable functionality and + enables usage with dict() and for loops. + """ + + def __iter__(self): + """Return an iterator of key-value pairs from the namespace's attributes.""" + return iter(vars(self).items()) + + def __str__(self): + """Return a human-readable string representation of the object.""" + return "\n".join(f"{k}={v}" for k, v in vars(self).items()) + + def __getattr__(self, attr): + """Custom attribute access error message with helpful information.""" + name = self.__class__.__name__ + raise AttributeError( + f""" + '{name}' object has no attribute '{attr}'. This may be caused by a modified or out of date ultralytics + 'default.yaml' file.\nPlease update your code with 'pip install -U ultralytics' and if necessary replace + {DEFAULT_CFG_PATH} with the latest version from + https://github.com/ultralytics/ultralytics/blob/main/ultralytics/cfg/default.yaml + """ + ) + + def get(self, key, default=None): + """Return the value of the specified key if it exists; otherwise, return the default value.""" + return getattr(self, key, default) + + +def plt_settings(rcparams=None, backend="Agg"): + """ + Decorator to temporarily set rc parameters and the backend for a plotting function. + + Example: + decorator: @plt_settings({"font.size": 12}) + context manager: with plt_settings({"font.size": 12}): + + Args: + rcparams (dict): Dictionary of rc parameters to set. + backend (str, optional): Name of the backend to use. Defaults to 'Agg'. + + Returns: + (Callable): Decorated function with temporarily set rc parameters and backend. This decorator can be + applied to any function that needs to have specific matplotlib rc parameters and backend for its execution. + """ + + if rcparams is None: + rcparams = {"font.size": 11} + + def decorator(func): + """Decorator to apply temporary rc parameters and backend to a function.""" + + def wrapper(*args, **kwargs): + """Sets rc parameters and backend, calls the original function, and restores the settings.""" + original_backend = plt.get_backend() + if backend.lower() != original_backend.lower(): + plt.close("all") # auto-close()ing of figures upon backend switching is deprecated since 3.8 + plt.switch_backend(backend) + + with plt.rc_context(rcparams): + result = func(*args, **kwargs) + + if backend != original_backend: + plt.close("all") + plt.switch_backend(original_backend) + return result + + return wrapper + + return decorator + + +def set_logging(name="LOGGING_NAME", verbose=True): + """Sets up logging for the given name with UTF-8 encoding support, ensuring compatibility across different + environments. + """ + level = logging.INFO if verbose and RANK in {-1, 0} else logging.ERROR # rank in world for Multi-GPU trainings + + # Configure the console (stdout) encoding to UTF-8, with checks for compatibility + formatter = logging.Formatter("%(message)s") # Default formatter + if WINDOWS and hasattr(sys.stdout, "encoding") and sys.stdout.encoding != "utf-8": + + class CustomFormatter(logging.Formatter): + def format(self, record): + """Sets up logging with UTF-8 encoding and configurable verbosity.""" + return emojis(super().format(record)) + + try: + # Attempt to reconfigure stdout to use UTF-8 encoding if possible + if hasattr(sys.stdout, "reconfigure"): + sys.stdout.reconfigure(encoding="utf-8") + # For environments where reconfigure is not available, wrap stdout in a TextIOWrapper + elif hasattr(sys.stdout, "buffer"): + import io + + sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8") + else: + formatter = CustomFormatter("%(message)s") + except Exception as e: + print(f"Creating custom formatter for non UTF-8 environments due to {e}") + formatter = CustomFormatter("%(message)s") + + # Create and configure the StreamHandler with the appropriate formatter and level + stream_handler = logging.StreamHandler(sys.stdout) + stream_handler.setFormatter(formatter) + stream_handler.setLevel(level) + + # Set up the logger + logger = logging.getLogger(name) + logger.setLevel(level) + logger.addHandler(stream_handler) + logger.propagate = False + return logger + + +# Set logger +LOGGER = set_logging(LOGGING_NAME, verbose=VERBOSE) # define globally (used in train.py, val.py, predict.py, etc.) +for logger in "sentry_sdk", "urllib3.connectionpool": + logging.getLogger(logger).setLevel(logging.CRITICAL + 1) + + +def emojis(string=""): + """Return platform-dependent emoji-safe version of string.""" + return string.encode().decode("ascii", "ignore") if WINDOWS else string + + +class ThreadingLocked: + """ + A decorator class for ensuring thread-safe execution of a function or method. This class can be used as a decorator + to make sure that if the decorated function is called from multiple threads, only one thread at a time will be able + to execute the function. + + Attributes: + lock (threading.Lock): A lock object used to manage access to the decorated function. + + Example: + ```python + from ultralytics.utils import ThreadingLocked + + @ThreadingLocked() + def my_function(): + # Your code here + pass + ``` + """ + + def __init__(self): + """Initializes the decorator class for thread-safe execution of a function or method.""" + self.lock = threading.Lock() + + def __call__(self, f): + """Run thread-safe execution of function or method.""" + from functools import wraps + + @wraps(f) + def decorated(*args, **kwargs): + """Applies thread-safety to the decorated function or method.""" + with self.lock: + return f(*args, **kwargs) + + return decorated + + +def yaml_save(file="data.yaml", data=None, header=""): + """ + Save YAML data to a file. + + Args: + file (str, optional): File name. Default is 'data.yaml'. + data (dict): Data to save in YAML format. + header (str, optional): YAML header to add. + + Returns: + (None): Data is saved to the specified file. + """ + if data is None: + data = {} + file = Path(file) + if not file.parent.exists(): + # Create parent directories if they don't exist + file.parent.mkdir(parents=True, exist_ok=True) + + # Convert Path objects to strings + valid_types = int, float, str, bool, list, tuple, dict, type(None) + for k, v in data.items(): + if not isinstance(v, valid_types): + data[k] = str(v) + + # Dump data to file in YAML format + with open(file, "w", errors="ignore", encoding="utf-8") as f: + if header: + f.write(header) + yaml.safe_dump(data, f, sort_keys=False, allow_unicode=True) + + +def yaml_load(file="data.yaml", append_filename=False): + """ + Load YAML data from a file. + + Args: + file (str, optional): File name. Default is 'data.yaml'. + append_filename (bool): Add the YAML filename to the YAML dictionary. Default is False. + + Returns: + (dict): YAML data and file name. + """ + assert Path(file).suffix in {".yaml", ".yml"}, f"Attempting to load non-YAML file {file} with yaml_load()" + with open(file, errors="ignore", encoding="utf-8") as f: + s = f.read() # string + + # Remove special characters + if not s.isprintable(): + s = re.sub(r"[^\x09\x0A\x0D\x20-\x7E\x85\xA0-\uD7FF\uE000-\uFFFD\U00010000-\U0010ffff]+", "", s) + + # Add YAML filename to dict and return + data = yaml.safe_load(s) or {} # always return a dict (yaml.safe_load() may return None for empty files) + if append_filename: + data["yaml_file"] = str(file) + return data + + +def yaml_print(yaml_file: Union[str, Path, dict]) -> None: + """ + Pretty prints a YAML file or a YAML-formatted dictionary. + + Args: + yaml_file: The file path of the YAML file or a YAML-formatted dictionary. + + Returns: + (None) + """ + yaml_dict = yaml_load(yaml_file) if isinstance(yaml_file, (str, Path)) else yaml_file + dump = yaml.dump(yaml_dict, sort_keys=False, allow_unicode=True) + LOGGER.info(f"Printing '{colorstr('bold', 'black', yaml_file)}'\n\n{dump}") + + +# Default configuration +DEFAULT_CFG_DICT = yaml_load(DEFAULT_CFG_PATH) +for k, v in DEFAULT_CFG_DICT.items(): + if isinstance(v, str) and v.lower() == "none": + DEFAULT_CFG_DICT[k] = None +DEFAULT_CFG_KEYS = DEFAULT_CFG_DICT.keys() +DEFAULT_CFG = IterableSimpleNamespace(**DEFAULT_CFG_DICT) + + +def read_device_model() -> str: + """ + Reads the device model information from the system and caches it for quick access. Used by is_jetson() and + is_raspberrypi(). + + Returns: + (str): Model file contents if read successfully or empty string otherwise. + """ + with contextlib.suppress(Exception): + with open("/proc/device-tree/model") as f: + return f.read() + return "" + + +def is_ubuntu() -> bool: + """ + Check if the OS is Ubuntu. + + Returns: + (bool): True if OS is Ubuntu, False otherwise. + """ + with contextlib.suppress(FileNotFoundError): + with open("/etc/os-release") as f: + return "ID=ubuntu" in f.read() + return False + + +def is_colab(): + """ + Check if the current script is running inside a Google Colab notebook. + + Returns: + (bool): True if running inside a Colab notebook, False otherwise. + """ + return "COLAB_RELEASE_TAG" in os.environ or "COLAB_BACKEND_VERSION" in os.environ + + +def is_kaggle(): + """ + Check if the current script is running inside a Kaggle kernel. + + Returns: + (bool): True if running inside a Kaggle kernel, False otherwise. + """ + return os.environ.get("PWD") == "/kaggle/working" and os.environ.get("KAGGLE_URL_BASE") == "https://www.kaggle.com" + + +def is_jupyter(): + """ + Check if the current script is running inside a Jupyter Notebook. Verified on Colab, Jupyterlab, Kaggle, Paperspace. + + Returns: + (bool): True if running inside a Jupyter Notebook, False otherwise. + """ + with contextlib.suppress(Exception): + from IPython import get_ipython + + return get_ipython() is not None + return False + + +def is_docker() -> bool: + """ + Determine if the script is running inside a Docker container. + + Returns: + (bool): True if the script is running inside a Docker container, False otherwise. + """ + with contextlib.suppress(Exception): + with open("/proc/self/cgroup") as f: + return "docker" in f.read() + return False + + +def is_raspberrypi() -> bool: + """ + Determines if the Python environment is running on a Raspberry Pi by checking the device model information. + + Returns: + (bool): True if running on a Raspberry Pi, False otherwise. + """ + return "Raspberry Pi" in PROC_DEVICE_MODEL + + +def is_jetson() -> bool: + """ + Determines if the Python environment is running on a Jetson Nano or Jetson Orin device by checking the device model + information. + + Returns: + (bool): True if running on a Jetson Nano or Jetson Orin, False otherwise. + """ + return "NVIDIA" in PROC_DEVICE_MODEL # i.e. "NVIDIA Jetson Nano" or "NVIDIA Orin NX" + + +def is_online() -> bool: + """ + Check internet connectivity by attempting to connect to a known online host. + + Returns: + (bool): True if connection is successful, False otherwise. + """ + with contextlib.suppress(Exception): + assert str(os.getenv("YOLO_OFFLINE", "")).lower() != "true" # check if ENV var YOLO_OFFLINE="True" + import socket + + for dns in ("1.1.1.1", "8.8.8.8"): # check Cloudflare and Google DNS + socket.create_connection(address=(dns, 80), timeout=1.0).close() + return True + return False + + +def is_pip_package(filepath: str = __name__) -> bool: + """ + Determines if the file at the given filepath is part of a pip package. + + Args: + filepath (str): The filepath to check. + + Returns: + (bool): True if the file is part of a pip package, False otherwise. + """ + import importlib.util + + # Get the spec for the module + spec = importlib.util.find_spec(filepath) + + # Return whether the spec is not None and the origin is not None (indicating it is a package) + return spec is not None and spec.origin is not None + + +def is_dir_writeable(dir_path: Union[str, Path]) -> bool: + """ + Check if a directory is writeable. + + Args: + dir_path (str | Path): The path to the directory. + + Returns: + (bool): True if the directory is writeable, False otherwise. + """ + return os.access(str(dir_path), os.W_OK) + + +def is_pytest_running(): + """ + Determines whether pytest is currently running or not. + + Returns: + (bool): True if pytest is running, False otherwise. + """ + return ("PYTEST_CURRENT_TEST" in os.environ) or ("pytest" in sys.modules) or ("pytest" in Path(ARGV[0]).stem) + + +def is_github_action_running() -> bool: + """ + Determine if the current environment is a GitHub Actions runner. + + Returns: + (bool): True if the current environment is a GitHub Actions runner, False otherwise. + """ + return "GITHUB_ACTIONS" in os.environ and "GITHUB_WORKFLOW" in os.environ and "RUNNER_OS" in os.environ + + +def get_git_dir(): + """ + Determines whether the current file is part of a git repository and if so, returns the repository root directory. If + the current file is not part of a git repository, returns None. + + Returns: + (Path | None): Git root directory if found or None if not found. + """ + for d in Path(__file__).parents: + if (d / ".git").is_dir(): + return d + + +def is_git_dir(): + """ + Determines whether the current file is part of a git repository. If the current file is not part of a git + repository, returns None. + + Returns: + (bool): True if current file is part of a git repository. + """ + return GIT_DIR is not None + + +def get_git_origin_url(): + """ + Retrieves the origin URL of a git repository. + + Returns: + (str | None): The origin URL of the git repository or None if not git directory. + """ + if IS_GIT_DIR: + with contextlib.suppress(subprocess.CalledProcessError): + origin = subprocess.check_output(["git", "config", "--get", "remote.origin.url"]) + return origin.decode().strip() + + +def get_git_branch(): + """ + Returns the current git branch name. If not in a git repository, returns None. + + Returns: + (str | None): The current git branch name or None if not a git directory. + """ + if IS_GIT_DIR: + with contextlib.suppress(subprocess.CalledProcessError): + origin = subprocess.check_output(["git", "rev-parse", "--abbrev-ref", "HEAD"]) + return origin.decode().strip() + + +def get_default_args(func): + """ + Returns a dictionary of default arguments for a function. + + Args: + func (callable): The function to inspect. + + Returns: + (dict): A dictionary where each key is a parameter name, and each value is the default value of that parameter. + """ + signature = inspect.signature(func) + return {k: v.default for k, v in signature.parameters.items() if v.default is not inspect.Parameter.empty} + + +def get_ubuntu_version(): + """ + Retrieve the Ubuntu version if the OS is Ubuntu. + + Returns: + (str): Ubuntu version or None if not an Ubuntu OS. + """ + if is_ubuntu(): + with contextlib.suppress(FileNotFoundError, AttributeError): + with open("/etc/os-release") as f: + return re.search(r'VERSION_ID="(\d+\.\d+)"', f.read())[1] + + +def get_user_config_dir(sub_dir="Ultralytics"): + """ + Return the appropriate config directory based on the environment operating system. + + Args: + sub_dir (str): The name of the subdirectory to create. + + Returns: + (Path): The path to the user config directory. + """ + if WINDOWS: + path = Path.home() / "AppData" / "Roaming" / sub_dir + elif MACOS: # macOS + path = Path.home() / "Library" / "Application Support" / sub_dir + elif LINUX: + path = Path.home() / ".config" / sub_dir + else: + raise ValueError(f"Unsupported operating system: {platform.system()}") + + # GCP and AWS lambda fix, only /tmp is writeable + if not is_dir_writeable(path.parent): + LOGGER.warning( + f"WARNING ⚠️ user config directory '{path}' is not writeable, defaulting to '/tmp' or CWD." + "Alternatively you can define a YOLO_CONFIG_DIR environment variable for this path." + ) + path = Path("/tmp") / sub_dir if is_dir_writeable("/tmp") else Path().cwd() / sub_dir + + # Create the subdirectory if it does not exist + path.mkdir(parents=True, exist_ok=True) + + return path + + +# Define constants (required below) +PROC_DEVICE_MODEL = read_device_model() # is_jetson() and is_raspberrypi() depend on this constant +ONLINE = is_online() +IS_COLAB = is_colab() +IS_DOCKER = is_docker() +IS_JETSON = is_jetson() +IS_JUPYTER = is_jupyter() +IS_KAGGLE = is_kaggle() +IS_PIP_PACKAGE = is_pip_package() +IS_RASPBERRYPI = is_raspberrypi() +GIT_DIR = get_git_dir() +IS_GIT_DIR = is_git_dir() +USER_CONFIG_DIR = Path(os.getenv("YOLO_CONFIG_DIR") or get_user_config_dir()) # Ultralytics settings dir +SETTINGS_YAML = USER_CONFIG_DIR / "settings.yaml" + + +def colorstr(*input): + """ + Colors a string based on the provided color and style arguments. Utilizes ANSI escape codes. + See https://en.wikipedia.org/wiki/ANSI_escape_code for more details. + + This function can be called in two ways: + - colorstr('color', 'style', 'your string') + - colorstr('your string') + + In the second form, 'blue' and 'bold' will be applied by default. + + Args: + *input (str): A sequence of strings where the first n-1 strings are color and style arguments, + and the last string is the one to be colored. + + Supported Colors and Styles: + Basic Colors: 'black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white' + Bright Colors: 'bright_black', 'bright_red', 'bright_green', 'bright_yellow', + 'bright_blue', 'bright_magenta', 'bright_cyan', 'bright_white' + Misc: 'end', 'bold', 'underline' + + Returns: + (str): The input string wrapped with ANSI escape codes for the specified color and style. + + Examples: + >>> colorstr("blue", "bold", "hello world") + >>> "\033[34m\033[1mhello world\033[0m" + """ + *args, string = input if len(input) > 1 else ("blue", "bold", input[0]) # color arguments, string + colors = { + "black": "\033[30m", # basic colors + "red": "\033[31m", + "green": "\033[32m", + "yellow": "\033[33m", + "blue": "\033[34m", + "magenta": "\033[35m", + "cyan": "\033[36m", + "white": "\033[37m", + "bright_black": "\033[90m", # bright colors + "bright_red": "\033[91m", + "bright_green": "\033[92m", + "bright_yellow": "\033[93m", + "bright_blue": "\033[94m", + "bright_magenta": "\033[95m", + "bright_cyan": "\033[96m", + "bright_white": "\033[97m", + "end": "\033[0m", # misc + "bold": "\033[1m", + "underline": "\033[4m", + } + return "".join(colors[x] for x in args) + f"{string}" + colors["end"] + + +def remove_colorstr(input_string): + """ + Removes ANSI escape codes from a string, effectively un-coloring it. + + Args: + input_string (str): The string to remove color and style from. + + Returns: + (str): A new string with all ANSI escape codes removed. + + Examples: + >>> remove_colorstr(colorstr('blue', 'bold', 'hello world')) + >>> 'hello world' + """ + ansi_escape = re.compile(r"\x1B\[[0-9;]*[A-Za-z]") + return ansi_escape.sub("", input_string) + + +class TryExcept(contextlib.ContextDecorator): + """ + Ultralytics TryExcept class. Use as @TryExcept() decorator or 'with TryExcept():' context manager. + + Examples: + As a decorator: + >>> @TryExcept(msg="Error occurred in func", verbose=True) + >>> def func(): + >>> # Function logic here + >>> pass + + As a context manager: + >>> with TryExcept(msg="Error occurred in block", verbose=True): + >>> # Code block here + >>> pass + """ + + def __init__(self, msg="", verbose=True): + """Initialize TryExcept class with optional message and verbosity settings.""" + self.msg = msg + self.verbose = verbose + + def __enter__(self): + """Executes when entering TryExcept context, initializes instance.""" + pass + + def __exit__(self, exc_type, value, traceback): + """Defines behavior when exiting a 'with' block, prints error message if necessary.""" + if self.verbose and value: + print(emojis(f"{self.msg}{': ' if self.msg else ''}{value}")) + return True + + +class Retry(contextlib.ContextDecorator): + """ + Retry class for function execution with exponential backoff. + + Can be used as a decorator or a context manager to retry a function or block of code on exceptions, up to a + specified number of times with an exponentially increasing delay between retries. + + Examples: + Example usage as a decorator: + >>> @Retry(times=3, delay=2) + >>> def test_func(): + >>> # Replace with function logic that may raise exceptions + >>> return True + + Example usage as a context manager: + >>> with Retry(times=3, delay=2): + >>> # Replace with code block that may raise exceptions + >>> pass + """ + + def __init__(self, times=3, delay=2): + """Initialize Retry class with specified number of retries and delay.""" + self.times = times + self.delay = delay + self._attempts = 0 + + def __call__(self, func): + """Decorator implementation for Retry with exponential backoff.""" + + def wrapped_func(*args, **kwargs): + """Applies retries to the decorated function or method.""" + self._attempts = 0 + while self._attempts < self.times: + try: + return func(*args, **kwargs) + except Exception as e: + self._attempts += 1 + print(f"Retry {self._attempts}/{self.times} failed: {e}") + if self._attempts >= self.times: + raise e + time.sleep(self.delay * (2**self._attempts)) # exponential backoff delay + + return wrapped_func + + def __enter__(self): + """Enter the runtime context related to this object.""" + self._attempts = 0 + + def __exit__(self, exc_type, exc_value, traceback): + """Exit the runtime context related to this object with exponential backoff.""" + if exc_type is not None: + self._attempts += 1 + if self._attempts < self.times: + print(f"Retry {self._attempts}/{self.times} failed: {exc_value}") + time.sleep(self.delay * (2**self._attempts)) # exponential backoff delay + return True # Suppresses the exception and retries + return False # Re-raises the exception if retries are exhausted + + +def threaded(func): + """ + Multi-threads a target function by default and returns the thread or function result. + + Use as @threaded decorator. The function runs in a separate thread unless 'threaded=False' is passed. + """ + + def wrapper(*args, **kwargs): + """Multi-threads a given function based on 'threaded' kwarg and returns the thread or function result.""" + if kwargs.pop("threaded", True): # run in thread + thread = threading.Thread(target=func, args=args, kwargs=kwargs, daemon=True) + thread.start() + return thread + else: + return func(*args, **kwargs) + + return wrapper + + +def set_sentry(): + """ + Initialize the Sentry SDK for error tracking and reporting. Only used if sentry_sdk package is installed and + sync=True in settings. Run 'yolo settings' to see and update settings YAML file. + + Conditions required to send errors (ALL conditions must be met or no errors will be reported): + - sentry_sdk package is installed + - sync=True in YOLO settings + - pytest is not running + - running in a pip package installation + - running in a non-git directory + - running with rank -1 or 0 + - online environment + - CLI used to run package (checked with 'yolo' as the name of the main CLI command) + + The function also configures Sentry SDK to ignore KeyboardInterrupt and FileNotFoundError + exceptions and to exclude events with 'out of memory' in their exception message. + + Additionally, the function sets custom tags and user information for Sentry events. + """ + + def before_send(event, hint): + """ + Modify the event before sending it to Sentry based on specific exception types and messages. + + Args: + event (dict): The event dictionary containing information about the error. + hint (dict): A dictionary containing additional information about the error. + + Returns: + dict: The modified event or None if the event should not be sent to Sentry. + """ + if "exc_info" in hint: + exc_type, exc_value, tb = hint["exc_info"] + if exc_type in {KeyboardInterrupt, FileNotFoundError} or "out of memory" in str(exc_value): + return None # do not send event + + event["tags"] = { + "sys_argv": ARGV[0], + "sys_argv_name": Path(ARGV[0]).name, + "install": "git" if IS_GIT_DIR else "pip" if IS_PIP_PACKAGE else "other", + "os": ENVIRONMENT, + } + return event + + if ( + SETTINGS["sync"] + and RANK in {-1, 0} + and Path(ARGV[0]).name == "yolo" + and not TESTS_RUNNING + and ONLINE + and IS_PIP_PACKAGE + and not IS_GIT_DIR + ): + # If sentry_sdk package is not installed then return and do not use Sentry + try: + import sentry_sdk # noqa + except ImportError: + return + + sentry_sdk.init( + dsn="https://5ff1556b71594bfea135ff0203a0d290@o4504521589325824.ingest.sentry.io/4504521592406016", + debug=False, + traces_sample_rate=1.0, + release=__version__, + environment="production", # 'dev' or 'production' + before_send=before_send, + ignore_errors=[KeyboardInterrupt, FileNotFoundError], + ) + sentry_sdk.set_user({"id": SETTINGS["uuid"]}) # SHA-256 anonymized UUID hash + + +class SettingsManager(dict): + """ + Manages Ultralytics settings stored in a YAML file. + + Args: + file (str | Path): Path to the Ultralytics settings YAML file. Default is USER_CONFIG_DIR / 'settings.yaml'. + version (str): Settings version. In case of local version mismatch, new default settings will be saved. + """ + + def __init__(self, file=SETTINGS_YAML, version="0.0.4"): + """Initialize the SettingsManager with default settings, load and validate current settings from the YAML + file. + """ + import copy + import hashlib + + from ultralytics.utils.checks import check_version + from ultralytics.utils.torch_utils import torch_distributed_zero_first + + root = GIT_DIR or Path() + datasets_root = (root.parent if GIT_DIR and is_dir_writeable(root.parent) else root).resolve() + + self.file = Path(file) + self.version = version + self.defaults = { + "settings_version": version, + "datasets_dir": str(datasets_root / "datasets"), + "weights_dir": str(root / "weights"), + "runs_dir": str(root / "runs"), + "uuid": hashlib.sha256(str(uuid.getnode()).encode()).hexdigest(), + "sync": True, + "api_key": "", + "openai_api_key": "", + "clearml": True, # integrations + "comet": True, + "dvc": True, + "hub": True, + "mlflow": True, + "neptune": True, + "raytune": True, + "tensorboard": True, + "wandb": True, + } + + super().__init__(copy.deepcopy(self.defaults)) + + with torch_distributed_zero_first(RANK): + if not self.file.exists(): + self.save() + + self.load() + correct_keys = self.keys() == self.defaults.keys() + correct_types = all(type(a) is type(b) for a, b in zip(self.values(), self.defaults.values())) + correct_version = check_version(self["settings_version"], self.version) + help_msg = ( + f"\nView settings with 'yolo settings' or at '{self.file}'" + "\nUpdate settings with 'yolo settings key=value', i.e. 'yolo settings runs_dir=path/to/dir'. " + "For help see https://docs.ultralytics.com/quickstart/#ultralytics-settings." + ) + if not (correct_keys and correct_types and correct_version): + LOGGER.warning( + "WARNING ⚠️ Ultralytics settings reset to default values. This may be due to a possible problem " + f"with your settings or a recent ultralytics package update. {help_msg}" + ) + self.reset() + + if self.get("datasets_dir") == self.get("runs_dir"): + LOGGER.warning( + f"WARNING ⚠️ Ultralytics setting 'datasets_dir: {self.get('datasets_dir')}' " + f"must be different than 'runs_dir: {self.get('runs_dir')}'. " + f"Please change one to avoid possible issues during training. {help_msg}" + ) + + def load(self): + """Loads settings from the YAML file.""" + super().update(yaml_load(self.file)) + + def save(self): + """Saves the current settings to the YAML file.""" + yaml_save(self.file, dict(self)) + + def update(self, *args, **kwargs): + """Updates a setting value in the current settings.""" + super().update(*args, **kwargs) + self.save() + + def reset(self): + """Resets the settings to default and saves them.""" + self.clear() + self.update(self.defaults) + self.save() + + +def deprecation_warn(arg, new_arg, version=None): + """Issue a deprecation warning when a deprecated argument is used, suggesting an updated argument.""" + if not version: + version = float(__version__[:3]) + 0.2 # deprecate after 2nd major release + LOGGER.warning( + f"WARNING ⚠️ '{arg}' is deprecated and will be removed in 'ultralytics {version}' in the future. " + f"Please use '{new_arg}' instead." + ) + + +def clean_url(url): + """Strip auth from URL, i.e. https://url.com/file.txt?auth -> https://url.com/file.txt.""" + url = Path(url).as_posix().replace(":/", "://") # Pathlib turns :// -> :/, as_posix() for Windows + return urllib.parse.unquote(url).split("?")[0] # '%2F' to '/', split https://url.com/file.txt?auth + + +def url2file(url): + """Convert URL to filename, i.e. https://url.com/file.txt?auth -> file.txt.""" + return Path(clean_url(url)).name + + +# Run below code on utils init ------------------------------------------------------------------------------------ + +# Check first-install steps +PREFIX = colorstr("Ultralytics: ") +SETTINGS = SettingsManager() # initialize settings +DATASETS_DIR = Path(SETTINGS["datasets_dir"]) # global datasets directory +WEIGHTS_DIR = Path(SETTINGS["weights_dir"]) # global weights directory +RUNS_DIR = Path(SETTINGS["runs_dir"]) # global runs directory +ENVIRONMENT = ( + "Colab" + if IS_COLAB + else "Kaggle" + if IS_KAGGLE + else "Jupyter" + if IS_JUPYTER + else "Docker" + if IS_DOCKER + else platform.system() +) +TESTS_RUNNING = is_pytest_running() or is_github_action_running() +set_sentry() + +# Apply monkey patches +from .patches import imread, imshow, imwrite, torch_save + +torch.save = torch_save +if WINDOWS: + # Apply cv2 patches for non-ASCII and non-UTF characters in image paths + cv2.imread, cv2.imwrite, cv2.imshow = imread, imwrite, imshow diff --git a/ultralytics/utils/autobatch.py b/ultralytics/utils/autobatch.py new file mode 100644 index 0000000..daea14e --- /dev/null +++ b/ultralytics/utils/autobatch.py @@ -0,0 +1,88 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +"""Functions for estimating the best YOLO batch size to use a fraction of the available CUDA memory in PyTorch.""" + +from copy import deepcopy + +import numpy as np +import torch + +from ultralytics.utils import DEFAULT_CFG, LOGGER, colorstr +from ultralytics.utils.torch_utils import profile + + +def check_train_batch_size(model, imgsz=640, amp=True): + """ + Check YOLO training batch size using the autobatch() function. + + Args: + model (torch.nn.Module): YOLO model to check batch size for. + imgsz (int): Image size used for training. + amp (bool): If True, use automatic mixed precision (AMP) for training. + + Returns: + (int): Optimal batch size computed using the autobatch() function. + """ + + with torch.cuda.amp.autocast(amp): + return autobatch(deepcopy(model).train(), imgsz) # compute optimal batch size + + +def autobatch(model, imgsz=640, fraction=0.60, batch_size=DEFAULT_CFG.batch): + """ + Automatically estimate the best YOLO batch size to use a fraction of the available CUDA memory. + + Args: + model (torch.nn.module): YOLO model to compute batch size for. + imgsz (int, optional): The image size used as input for the YOLO model. Defaults to 640. + fraction (float, optional): The fraction of available CUDA memory to use. Defaults to 0.60. + batch_size (int, optional): The default batch size to use if an error is detected. Defaults to 16. + + Returns: + (int): The optimal batch size. + """ + + # Check device + prefix = colorstr("AutoBatch: ") + LOGGER.info(f"{prefix}Computing optimal batch size for imgsz={imgsz}") + device = next(model.parameters()).device # get model device + if device.type == "cpu": + LOGGER.info(f"{prefix}CUDA not detected, using default CPU batch-size {batch_size}") + return batch_size + if torch.backends.cudnn.benchmark: + LOGGER.info(f"{prefix} ⚠️ Requires torch.backends.cudnn.benchmark=False, using default batch-size {batch_size}") + return batch_size + + # Inspect CUDA memory + gb = 1 << 30 # bytes to GiB (1024 ** 3) + d = str(device).upper() # 'CUDA:0' + properties = torch.cuda.get_device_properties(device) # device properties + t = properties.total_memory / gb # GiB total + r = torch.cuda.memory_reserved(device) / gb # GiB reserved + a = torch.cuda.memory_allocated(device) / gb # GiB allocated + f = t - (r + a) # GiB free + LOGGER.info(f"{prefix}{d} ({properties.name}) {t:.2f}G total, {r:.2f}G reserved, {a:.2f}G allocated, {f:.2f}G free") + + # Profile batch sizes + batch_sizes = [1, 2, 4, 8, 16] + try: + img = [torch.empty(b, 3, imgsz, imgsz) for b in batch_sizes] + results = profile(img, model, n=3, device=device) + + # Fit a solution + y = [x[2] for x in results if x] # memory [2] + p = np.polyfit(batch_sizes[: len(y)], y, deg=1) # first degree polynomial fit + b = int((f * fraction - p[1]) / p[0]) # y intercept (optimal batch size) + if None in results: # some sizes failed + i = results.index(None) # first fail index + if b >= batch_sizes[i]: # y intercept above failure point + b = batch_sizes[max(i - 1, 0)] # select prior safe point + if b < 1 or b > 1024: # b outside of safe range + b = batch_size + LOGGER.info(f"{prefix}WARNING ⚠️ CUDA anomaly detected, using default batch-size {batch_size}.") + + fraction = (np.polyval(p, b) + r + a) / t # actual fraction predicted + LOGGER.info(f"{prefix}Using batch-size {b} for {d} {t * fraction:.2f}G/{t:.2f}G ({fraction * 100:.0f}%) ✅") + return b + except Exception as e: + LOGGER.warning(f"{prefix}WARNING ⚠️ error detected: {e}, using default batch-size {batch_size}.") + return batch_size diff --git a/ultralytics/utils/benchmarks.py b/ultralytics/utils/benchmarks.py new file mode 100644 index 0000000..af16913 --- /dev/null +++ b/ultralytics/utils/benchmarks.py @@ -0,0 +1,401 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +""" +Benchmark a YOLO model formats for speed and accuracy. + +Usage: + from ultralytics.utils.benchmarks import ProfileModels, benchmark + ProfileModels(['yolov8n.yaml', 'yolov8s.yaml']).profile() + benchmark(model='yolov8n.pt', imgsz=160) + +Format | `format=argument` | Model +--- | --- | --- +PyTorch | - | yolov8n.pt +TorchScript | `torchscript` | yolov8n.torchscript +ONNX | `onnx` | yolov8n.onnx +OpenVINO | `openvino` | yolov8n_openvino_model/ +TensorRT | `engine` | yolov8n.engine +CoreML | `coreml` | yolov8n.mlpackage +TensorFlow SavedModel | `saved_model` | yolov8n_saved_model/ +TensorFlow GraphDef | `pb` | yolov8n.pb +TensorFlow Lite | `tflite` | yolov8n.tflite +TensorFlow Edge TPU | `edgetpu` | yolov8n_edgetpu.tflite +TensorFlow.js | `tfjs` | yolov8n_web_model/ +PaddlePaddle | `paddle` | yolov8n_paddle_model/ +NCNN | `ncnn` | yolov8n_ncnn_model/ +""" + +import glob +import platform +import time +from pathlib import Path + +import numpy as np +import torch.cuda + +from ultralytics import YOLO, YOLOWorld +from ultralytics.cfg import TASK2DATA, TASK2METRIC +from ultralytics.engine.exporter import export_formats +from ultralytics.utils import ASSETS, LINUX, LOGGER, MACOS, TQDM, WEIGHTS_DIR +from ultralytics.utils.checks import IS_PYTHON_3_12, check_requirements, check_yolo +from ultralytics.utils.files import file_size +from ultralytics.utils.torch_utils import select_device + + +def benchmark( + model=WEIGHTS_DIR / "yolov8n.pt", data=None, imgsz=160, half=False, int8=False, device="cpu", verbose=False +): + """ + Benchmark a YOLO model across different formats for speed and accuracy. + + Args: + model (str | Path | optional): Path to the model file or directory. Default is + Path(SETTINGS['weights_dir']) / 'yolov8n.pt'. + data (str, optional): Dataset to evaluate on, inherited from TASK2DATA if not passed. Default is None. + imgsz (int, optional): Image size for the benchmark. Default is 160. + half (bool, optional): Use half-precision for the model if True. Default is False. + int8 (bool, optional): Use int8-precision for the model if True. Default is False. + device (str, optional): Device to run the benchmark on, either 'cpu' or 'cuda'. Default is 'cpu'. + verbose (bool | float | optional): If True or a float, assert benchmarks pass with given metric. + Default is False. + + Returns: + df (pandas.DataFrame): A pandas DataFrame with benchmark results for each format, including file size, + metric, and inference time. + + Example: + ```python + from ultralytics.utils.benchmarks import benchmark + + benchmark(model='yolov8n.pt', imgsz=640) + ``` + """ + import pandas as pd # scope for faster 'import ultralytics' + + pd.options.display.max_columns = 10 + pd.options.display.width = 120 + device = select_device(device, verbose=False) + if isinstance(model, (str, Path)): + model = YOLO(model) + + y = [] + t0 = time.time() + for i, (name, format, suffix, cpu, gpu) in export_formats().iterrows(): # index, (name, format, suffix, CPU, GPU) + emoji, filename = "❌", None # export defaults + try: + # Checks + if i == 9: # Edge TPU + assert LINUX, "Edge TPU export only supported on Linux" + elif i == 7: # TF GraphDef + assert model.task != "obb", "TensorFlow GraphDef not supported for OBB task" + elif i in {5, 10}: # CoreML and TF.js + assert MACOS or LINUX, "export only supported on macOS and Linux" + if i in {3, 5}: # CoreML and OpenVINO + assert not IS_PYTHON_3_12, "CoreML and OpenVINO not supported on Python 3.12" + if i in {6, 7, 8, 9, 10}: # All TF formats + assert not isinstance(model, YOLOWorld), "YOLOWorldv2 TensorFlow exports not supported by onnx2tf yet" + if i in {11}: # Paddle + assert not isinstance(model, YOLOWorld), "YOLOWorldv2 Paddle exports not supported yet" + if i in {12}: # NCNN + assert not isinstance(model, YOLOWorld), "YOLOWorldv2 NCNN exports not supported yet" + if "cpu" in device.type: + assert cpu, "inference not supported on CPU" + if "cuda" in device.type: + assert gpu, "inference not supported on GPU" + + # Export + if format == "-": + filename = model.ckpt_path or model.cfg + exported_model = model # PyTorch format + else: + filename = model.export(imgsz=imgsz, format=format, half=half, int8=int8, device=device, verbose=False) + exported_model = YOLO(filename, task=model.task) + assert suffix in str(filename), "export failed" + emoji = "❎" # indicates export succeeded + + # Predict + assert model.task != "pose" or i != 7, "GraphDef Pose inference is not supported" + assert i not in {9, 10}, "inference not supported" # Edge TPU and TF.js are unsupported + assert i != 5 or platform.system() == "Darwin", "inference only supported on macOS>=10.13" # CoreML + exported_model.predict(ASSETS / "bus.jpg", imgsz=imgsz, device=device, half=half) + + # Validate + data = data or TASK2DATA[model.task] # task to dataset, i.e. coco8.yaml for task=detect + key = TASK2METRIC[model.task] # task to metric, i.e. metrics/mAP50-95(B) for task=detect + results = exported_model.val( + data=data, batch=1, imgsz=imgsz, plots=False, device=device, half=half, int8=int8, verbose=False + ) + metric, speed = results.results_dict[key], results.speed["inference"] + y.append([name, "✅", round(file_size(filename), 1), round(metric, 4), round(speed, 2)]) + except Exception as e: + if verbose: + assert type(e) is AssertionError, f"Benchmark failure for {name}: {e}" + LOGGER.warning(f"ERROR ❌️ Benchmark failure for {name}: {e}") + y.append([name, emoji, round(file_size(filename), 1), None, None]) # mAP, t_inference + + # Print results + check_yolo(device=device) # print system info + df = pd.DataFrame(y, columns=["Format", "Status❔", "Size (MB)", key, "Inference time (ms/im)"]) + + name = Path(model.ckpt_path).name + s = f"\nBenchmarks complete for {name} on {data} at imgsz={imgsz} ({time.time() - t0:.2f}s)\n{df}\n" + LOGGER.info(s) + with open("benchmarks.log", "a", errors="ignore", encoding="utf-8") as f: + f.write(s) + + if verbose and isinstance(verbose, float): + metrics = df[key].array # values to compare to floor + floor = verbose # minimum metric floor to pass, i.e. = 0.29 mAP for YOLOv5n + assert all(x > floor for x in metrics if pd.notna(x)), f"Benchmark failure: metric(s) < floor {floor}" + + return df + + +class ProfileModels: + """ + ProfileModels class for profiling different models on ONNX and TensorRT. + + This class profiles the performance of different models, returning results such as model speed and FLOPs. + + Attributes: + paths (list): Paths of the models to profile. + num_timed_runs (int): Number of timed runs for the profiling. Default is 100. + num_warmup_runs (int): Number of warmup runs before profiling. Default is 10. + min_time (float): Minimum number of seconds to profile for. Default is 60. + imgsz (int): Image size used in the models. Default is 640. + + Methods: + profile(): Profiles the models and prints the result. + + Example: + ```python + from ultralytics.utils.benchmarks import ProfileModels + + ProfileModels(['yolov8n.yaml', 'yolov8s.yaml'], imgsz=640).profile() + ``` + """ + + def __init__( + self, + paths: list, + num_timed_runs=100, + num_warmup_runs=10, + min_time=60, + imgsz=640, + half=True, + trt=True, + device=None, + ): + """ + Initialize the ProfileModels class for profiling models. + + Args: + paths (list): List of paths of the models to be profiled. + num_timed_runs (int, optional): Number of timed runs for the profiling. Default is 100. + num_warmup_runs (int, optional): Number of warmup runs before the actual profiling starts. Default is 10. + min_time (float, optional): Minimum time in seconds for profiling a model. Default is 60. + imgsz (int, optional): Size of the image used during profiling. Default is 640. + half (bool, optional): Flag to indicate whether to use half-precision floating point for profiling. + trt (bool, optional): Flag to indicate whether to profile using TensorRT. Default is True. + device (torch.device, optional): Device used for profiling. If None, it is determined automatically. + """ + self.paths = paths + self.num_timed_runs = num_timed_runs + self.num_warmup_runs = num_warmup_runs + self.min_time = min_time + self.imgsz = imgsz + self.half = half + self.trt = trt # run TensorRT profiling + self.device = device or torch.device(0 if torch.cuda.is_available() else "cpu") + + def profile(self): + """Logs the benchmarking results of a model, checks metrics against floor and returns the results.""" + files = self.get_files() + + if not files: + print("No matching *.pt or *.onnx files found.") + return + + table_rows = [] + output = [] + for file in files: + engine_file = file.with_suffix(".engine") + if file.suffix in {".pt", ".yaml", ".yml"}: + model = YOLO(str(file)) + model.fuse() # to report correct params and GFLOPs in model.info() + model_info = model.info() + if self.trt and self.device.type != "cpu" and not engine_file.is_file(): + engine_file = model.export( + format="engine", half=self.half, imgsz=self.imgsz, device=self.device, verbose=False + ) + onnx_file = model.export( + format="onnx", half=self.half, imgsz=self.imgsz, simplify=True, device=self.device, verbose=False + ) + elif file.suffix == ".onnx": + model_info = self.get_onnx_model_info(file) + onnx_file = file + else: + continue + + t_engine = self.profile_tensorrt_model(str(engine_file)) + t_onnx = self.profile_onnx_model(str(onnx_file)) + table_rows.append(self.generate_table_row(file.stem, t_onnx, t_engine, model_info)) + output.append(self.generate_results_dict(file.stem, t_onnx, t_engine, model_info)) + + self.print_table(table_rows) + return output + + def get_files(self): + """Returns a list of paths for all relevant model files given by the user.""" + files = [] + for path in self.paths: + path = Path(path) + if path.is_dir(): + extensions = ["*.pt", "*.onnx", "*.yaml"] + files.extend([file for ext in extensions for file in glob.glob(str(path / ext))]) + elif path.suffix in {".pt", ".yaml", ".yml"}: # add non-existing + files.append(str(path)) + else: + files.extend(glob.glob(str(path))) + + print(f"Profiling: {sorted(files)}") + return [Path(file) for file in sorted(files)] + + def get_onnx_model_info(self, onnx_file: str): + """Retrieves the information including number of layers, parameters, gradients and FLOPs for an ONNX model + file. + """ + return 0.0, 0.0, 0.0, 0.0 # return (num_layers, num_params, num_gradients, num_flops) + + @staticmethod + def iterative_sigma_clipping(data, sigma=2, max_iters=3): + """Applies an iterative sigma clipping algorithm to the given data times number of iterations.""" + data = np.array(data) + for _ in range(max_iters): + mean, std = np.mean(data), np.std(data) + clipped_data = data[(data > mean - sigma * std) & (data < mean + sigma * std)] + if len(clipped_data) == len(data): + break + data = clipped_data + return data + + def profile_tensorrt_model(self, engine_file: str, eps: float = 1e-3): + """Profiles the TensorRT model, measuring average run time and standard deviation among runs.""" + if not self.trt or not Path(engine_file).is_file(): + return 0.0, 0.0 + + # Model and input + model = YOLO(engine_file) + input_data = np.random.rand(self.imgsz, self.imgsz, 3).astype(np.float32) # must be FP32 + + # Warmup runs + elapsed = 0.0 + for _ in range(3): + start_time = time.time() + for _ in range(self.num_warmup_runs): + model(input_data, imgsz=self.imgsz, verbose=False) + elapsed = time.time() - start_time + + # Compute number of runs as higher of min_time or num_timed_runs + num_runs = max(round(self.min_time / (elapsed + eps) * self.num_warmup_runs), self.num_timed_runs * 50) + + # Timed runs + run_times = [] + for _ in TQDM(range(num_runs), desc=engine_file): + results = model(input_data, imgsz=self.imgsz, verbose=False) + run_times.append(results[0].speed["inference"]) # Convert to milliseconds + + run_times = self.iterative_sigma_clipping(np.array(run_times), sigma=2, max_iters=3) # sigma clipping + return np.mean(run_times), np.std(run_times) + + def profile_onnx_model(self, onnx_file: str, eps: float = 1e-3): + """Profiles an ONNX model by executing it multiple times and returns the mean and standard deviation of run + times. + """ + check_requirements("onnxruntime") + import onnxruntime as ort + + # Session with either 'TensorrtExecutionProvider', 'CUDAExecutionProvider', 'CPUExecutionProvider' + sess_options = ort.SessionOptions() + sess_options.graph_optimization_level = ort.GraphOptimizationLevel.ORT_ENABLE_ALL + sess_options.intra_op_num_threads = 8 # Limit the number of threads + sess = ort.InferenceSession(onnx_file, sess_options, providers=["CPUExecutionProvider"]) + + input_tensor = sess.get_inputs()[0] + input_type = input_tensor.type + + # Mapping ONNX datatype to numpy datatype + if "float16" in input_type: + input_dtype = np.float16 + elif "float" in input_type: + input_dtype = np.float32 + elif "double" in input_type: + input_dtype = np.float64 + elif "int64" in input_type: + input_dtype = np.int64 + elif "int32" in input_type: + input_dtype = np.int32 + else: + raise ValueError(f"Unsupported ONNX datatype {input_type}") + + input_data = np.random.rand(*input_tensor.shape).astype(input_dtype) + input_name = input_tensor.name + output_name = sess.get_outputs()[0].name + + # Warmup runs + elapsed = 0.0 + for _ in range(3): + start_time = time.time() + for _ in range(self.num_warmup_runs): + sess.run([output_name], {input_name: input_data}) + elapsed = time.time() - start_time + + # Compute number of runs as higher of min_time or num_timed_runs + num_runs = max(round(self.min_time / (elapsed + eps) * self.num_warmup_runs), self.num_timed_runs) + + # Timed runs + run_times = [] + for _ in TQDM(range(num_runs), desc=onnx_file): + start_time = time.time() + sess.run([output_name], {input_name: input_data}) + run_times.append((time.time() - start_time) * 1000) # Convert to milliseconds + + run_times = self.iterative_sigma_clipping(np.array(run_times), sigma=2, max_iters=5) # sigma clipping + return np.mean(run_times), np.std(run_times) + + def generate_table_row(self, model_name, t_onnx, t_engine, model_info): + """Generates a formatted string for a table row that includes model performance and metric details.""" + layers, params, gradients, flops = model_info + return ( + f"| {model_name:18s} | {self.imgsz} | - | {t_onnx[0]:.2f} ± {t_onnx[1]:.2f} ms | {t_engine[0]:.2f} ± " + f"{t_engine[1]:.2f} ms | {params / 1e6:.1f} | {flops:.1f} |" + ) + + @staticmethod + def generate_results_dict(model_name, t_onnx, t_engine, model_info): + """Generates a dictionary of model details including name, parameters, GFLOPS and speed metrics.""" + layers, params, gradients, flops = model_info + return { + "model/name": model_name, + "model/parameters": params, + "model/GFLOPs": round(flops, 3), + "model/speed_ONNX(ms)": round(t_onnx[0], 3), + "model/speed_TensorRT(ms)": round(t_engine[0], 3), + } + + @staticmethod + def print_table(table_rows): + """Formats and prints a comparison table for different models with given statistics and performance data.""" + gpu = torch.cuda.get_device_name(0) if torch.cuda.is_available() else "GPU" + header = ( + f"| Model | size
(pixels) | mAPval
50-95 | Speed
CPU ONNX
(ms) | " + f"Speed
{gpu} TensorRT
(ms) | params
(M) | FLOPs
(B) |" + ) + separator = ( + "|-------------|---------------------|--------------------|------------------------------|" + "-----------------------------------|------------------|-----------------|" + ) + + print(f"\n\n{header}") + print(separator) + for row in table_rows: + print(row) diff --git a/ultralytics/utils/callbacks/__init__.py b/ultralytics/utils/callbacks/__init__.py new file mode 100644 index 0000000..116babe --- /dev/null +++ b/ultralytics/utils/callbacks/__init__.py @@ -0,0 +1,5 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from .base import add_integration_callbacks, default_callbacks, get_default_callbacks + +__all__ = "add_integration_callbacks", "default_callbacks", "get_default_callbacks" diff --git a/ultralytics/utils/callbacks/base.py b/ultralytics/utils/callbacks/base.py new file mode 100644 index 0000000..e1e9b42 --- /dev/null +++ b/ultralytics/utils/callbacks/base.py @@ -0,0 +1,218 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +"""Base callbacks.""" + +from collections import defaultdict +from copy import deepcopy + +# Trainer callbacks ---------------------------------------------------------------------------------------------------- + + +def on_pretrain_routine_start(trainer): + """Called before the pretraining routine starts.""" + pass + + +def on_pretrain_routine_end(trainer): + """Called after the pretraining routine ends.""" + pass + + +def on_train_start(trainer): + """Called when the training starts.""" + pass + + +def on_train_epoch_start(trainer): + """Called at the start of each training epoch.""" + pass + + +def on_train_batch_start(trainer): + """Called at the start of each training batch.""" + pass + + +def optimizer_step(trainer): + """Called when the optimizer takes a step.""" + pass + + +def on_before_zero_grad(trainer): + """Called before the gradients are set to zero.""" + pass + + +def on_train_batch_end(trainer): + """Called at the end of each training batch.""" + pass + + +def on_train_epoch_end(trainer): + """Called at the end of each training epoch.""" + pass + + +def on_fit_epoch_end(trainer): + """Called at the end of each fit epoch (train + val).""" + pass + + +def on_model_save(trainer): + """Called when the model is saved.""" + pass + + +def on_train_end(trainer): + """Called when the training ends.""" + pass + + +def on_params_update(trainer): + """Called when the model parameters are updated.""" + pass + + +def teardown(trainer): + """Called during the teardown of the training process.""" + pass + + +# Validator callbacks -------------------------------------------------------------------------------------------------- + + +def on_val_start(validator): + """Called when the validation starts.""" + pass + + +def on_val_batch_start(validator): + """Called at the start of each validation batch.""" + pass + + +def on_val_batch_end(validator): + """Called at the end of each validation batch.""" + pass + + +def on_val_end(validator): + """Called when the validation ends.""" + pass + + +# Predictor callbacks -------------------------------------------------------------------------------------------------- + + +def on_predict_start(predictor): + """Called when the prediction starts.""" + pass + + +def on_predict_batch_start(predictor): + """Called at the start of each prediction batch.""" + pass + + +def on_predict_batch_end(predictor): + """Called at the end of each prediction batch.""" + pass + + +def on_predict_postprocess_end(predictor): + """Called after the post-processing of the prediction ends.""" + pass + + +def on_predict_end(predictor): + """Called when the prediction ends.""" + pass + + +# Exporter callbacks --------------------------------------------------------------------------------------------------- + + +def on_export_start(exporter): + """Called when the model export starts.""" + pass + + +def on_export_end(exporter): + """Called when the model export ends.""" + pass + + +default_callbacks = { + # Run in trainer + "on_pretrain_routine_start": [on_pretrain_routine_start], + "on_pretrain_routine_end": [on_pretrain_routine_end], + "on_train_start": [on_train_start], + "on_train_epoch_start": [on_train_epoch_start], + "on_train_batch_start": [on_train_batch_start], + "optimizer_step": [optimizer_step], + "on_before_zero_grad": [on_before_zero_grad], + "on_train_batch_end": [on_train_batch_end], + "on_train_epoch_end": [on_train_epoch_end], + "on_fit_epoch_end": [on_fit_epoch_end], # fit = train + val + "on_model_save": [on_model_save], + "on_train_end": [on_train_end], + "on_params_update": [on_params_update], + "teardown": [teardown], + # Run in validator + "on_val_start": [on_val_start], + "on_val_batch_start": [on_val_batch_start], + "on_val_batch_end": [on_val_batch_end], + "on_val_end": [on_val_end], + # Run in predictor + "on_predict_start": [on_predict_start], + "on_predict_batch_start": [on_predict_batch_start], + "on_predict_postprocess_end": [on_predict_postprocess_end], + "on_predict_batch_end": [on_predict_batch_end], + "on_predict_end": [on_predict_end], + # Run in exporter + "on_export_start": [on_export_start], + "on_export_end": [on_export_end], +} + + +def get_default_callbacks(): + """ + Return a copy of the default_callbacks dictionary with lists as default values. + + Returns: + (defaultdict): A defaultdict with keys from default_callbacks and empty lists as default values. + """ + return defaultdict(list, deepcopy(default_callbacks)) + + +def add_integration_callbacks(instance): + """ + Add integration callbacks from various sources to the instance's callbacks. + + Args: + instance (Trainer, Predictor, Validator, Exporter): An object with a 'callbacks' attribute that is a dictionary + of callback lists. + """ + + # Load HUB callbacks + from .hub import callbacks as hub_cb + + callbacks_list = [hub_cb] + + # Load training callbacks + if "Trainer" in instance.__class__.__name__: + from .clearml import callbacks as clear_cb + from .comet import callbacks as comet_cb + from .dvc import callbacks as dvc_cb + from .mlflow import callbacks as mlflow_cb + from .neptune import callbacks as neptune_cb + from .raytune import callbacks as tune_cb + from .tensorboard import callbacks as tb_cb + from .wb import callbacks as wb_cb + + callbacks_list.extend([clear_cb, comet_cb, dvc_cb, mlflow_cb, neptune_cb, tune_cb, tb_cb, wb_cb]) + + # Add the callbacks to the callbacks dictionary + for callbacks in callbacks_list: + for k, v in callbacks.items(): + if v not in instance.callbacks[k]: + instance.callbacks[k].append(v) diff --git a/ultralytics/utils/callbacks/clearml.py b/ultralytics/utils/callbacks/clearml.py new file mode 100644 index 0000000..e076e55 --- /dev/null +++ b/ultralytics/utils/callbacks/clearml.py @@ -0,0 +1,153 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from ultralytics.utils import LOGGER, SETTINGS, TESTS_RUNNING + +try: + assert not TESTS_RUNNING # do not log pytest + assert SETTINGS["clearml"] is True # verify integration is enabled + import clearml + from clearml import Task + + assert hasattr(clearml, "__version__") # verify package is not directory + +except (ImportError, AssertionError): + clearml = None + + +def _log_debug_samples(files, title="Debug Samples") -> None: + """ + Log files (images) as debug samples in the ClearML task. + + Args: + files (list): A list of file paths in PosixPath format. + title (str): A title that groups together images with the same values. + """ + import re + + if task := Task.current_task(): + for f in files: + if f.exists(): + it = re.search(r"_batch(\d+)", f.name) + iteration = int(it.groups()[0]) if it else 0 + task.get_logger().report_image( + title=title, series=f.name.replace(it.group(), ""), local_path=str(f), iteration=iteration + ) + + +def _log_plot(title, plot_path) -> None: + """ + Log an image as a plot in the plot section of ClearML. + + Args: + title (str): The title of the plot. + plot_path (str): The path to the saved image file. + """ + import matplotlib.image as mpimg + import matplotlib.pyplot as plt + + img = mpimg.imread(plot_path) + fig = plt.figure() + ax = fig.add_axes([0, 0, 1, 1], frameon=False, aspect="auto", xticks=[], yticks=[]) # no ticks + ax.imshow(img) + + Task.current_task().get_logger().report_matplotlib_figure( + title=title, series="", figure=fig, report_interactive=False + ) + + +def on_pretrain_routine_start(trainer): + """Runs at start of pretraining routine; initializes and connects/ logs task to ClearML.""" + try: + if task := Task.current_task(): + # WARNING: make sure the automatic pytorch and matplotlib bindings are disabled! + # We are logging these plots and model files manually in the integration + from clearml.binding.frameworks.pytorch_bind import PatchPyTorchModelIO + from clearml.binding.matplotlib_bind import PatchedMatplotlib + + PatchPyTorchModelIO.update_current_task(None) + PatchedMatplotlib.update_current_task(None) + else: + task = Task.init( + project_name=trainer.args.project or "YOLOv8", + task_name=trainer.args.name, + tags=["YOLOv8"], + output_uri=True, + reuse_last_task_id=False, + auto_connect_frameworks={"pytorch": False, "matplotlib": False}, + ) + LOGGER.warning( + "ClearML Initialized a new task. If you want to run remotely, " + "please add clearml-init and connect your arguments before initializing YOLO." + ) + task.connect(vars(trainer.args), name="General") + except Exception as e: + LOGGER.warning(f"WARNING ⚠️ ClearML installed but not initialized correctly, not logging this run. {e}") + + +def on_train_epoch_end(trainer): + """Logs debug samples for the first epoch of YOLO training and report current training progress.""" + if task := Task.current_task(): + # Log debug samples + if trainer.epoch == 1: + _log_debug_samples(sorted(trainer.save_dir.glob("train_batch*.jpg")), "Mosaic") + # Report the current training progress + for k, v in trainer.label_loss_items(trainer.tloss, prefix="train").items(): + task.get_logger().report_scalar("train", k, v, iteration=trainer.epoch) + for k, v in trainer.lr.items(): + task.get_logger().report_scalar("lr", k, v, iteration=trainer.epoch) + + +def on_fit_epoch_end(trainer): + """Reports model information to logger at the end of an epoch.""" + if task := Task.current_task(): + # You should have access to the validation bboxes under jdict + task.get_logger().report_scalar( + title="Epoch Time", series="Epoch Time", value=trainer.epoch_time, iteration=trainer.epoch + ) + for k, v in trainer.metrics.items(): + task.get_logger().report_scalar("val", k, v, iteration=trainer.epoch) + if trainer.epoch == 0: + from ultralytics.utils.torch_utils import model_info_for_loggers + + for k, v in model_info_for_loggers(trainer).items(): + task.get_logger().report_single_value(k, v) + + +def on_val_end(validator): + """Logs validation results including labels and predictions.""" + if Task.current_task(): + # Log val_labels and val_pred + _log_debug_samples(sorted(validator.save_dir.glob("val*.jpg")), "Validation") + + +def on_train_end(trainer): + """Logs final model and its name on training completion.""" + if task := Task.current_task(): + # Log final results, CM matrix + PR plots + files = [ + "results.png", + "confusion_matrix.png", + "confusion_matrix_normalized.png", + *(f"{x}_curve.png" for x in ("F1", "PR", "P", "R")), + ] + files = [(trainer.save_dir / f) for f in files if (trainer.save_dir / f).exists()] # filter + for f in files: + _log_plot(title=f.stem, plot_path=f) + # Report final metrics + for k, v in trainer.validator.metrics.results_dict.items(): + task.get_logger().report_single_value(k, v) + # Log the final model + task.update_output_model(model_path=str(trainer.best), model_name=trainer.args.name, auto_delete_file=False) + + +callbacks = ( + { + "on_pretrain_routine_start": on_pretrain_routine_start, + "on_train_epoch_end": on_train_epoch_end, + "on_fit_epoch_end": on_fit_epoch_end, + "on_val_end": on_val_end, + "on_train_end": on_train_end, + } + if clearml + else {} +) diff --git a/ultralytics/utils/callbacks/comet.py b/ultralytics/utils/callbacks/comet.py new file mode 100644 index 0000000..518860c --- /dev/null +++ b/ultralytics/utils/callbacks/comet.py @@ -0,0 +1,375 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from ultralytics.utils import LOGGER, RANK, SETTINGS, TESTS_RUNNING, ops + +try: + assert not TESTS_RUNNING # do not log pytest + assert SETTINGS["comet"] is True # verify integration is enabled + import comet_ml + + assert hasattr(comet_ml, "__version__") # verify package is not directory + + import os + from pathlib import Path + + # Ensures certain logging functions only run for supported tasks + COMET_SUPPORTED_TASKS = ["detect"] + + # Names of plots created by YOLOv8 that are logged to Comet + EVALUATION_PLOT_NAMES = "F1_curve", "P_curve", "R_curve", "PR_curve", "confusion_matrix" + LABEL_PLOT_NAMES = "labels", "labels_correlogram" + + _comet_image_prediction_count = 0 + +except (ImportError, AssertionError): + comet_ml = None + + +def _get_comet_mode(): + """Returns the mode of comet set in the environment variables, defaults to 'online' if not set.""" + return os.getenv("COMET_MODE", "online") + + +def _get_comet_model_name(): + """Returns the model name for Comet from the environment variable 'COMET_MODEL_NAME' or defaults to 'YOLOv8'.""" + return os.getenv("COMET_MODEL_NAME", "YOLOv8") + + +def _get_eval_batch_logging_interval(): + """Get the evaluation batch logging interval from environment variable or use default value 1.""" + return int(os.getenv("COMET_EVAL_BATCH_LOGGING_INTERVAL", 1)) + + +def _get_max_image_predictions_to_log(): + """Get the maximum number of image predictions to log from the environment variables.""" + return int(os.getenv("COMET_MAX_IMAGE_PREDICTIONS", 100)) + + +def _scale_confidence_score(score): + """Scales the given confidence score by a factor specified in an environment variable.""" + scale = float(os.getenv("COMET_MAX_CONFIDENCE_SCORE", 100.0)) + return score * scale + + +def _should_log_confusion_matrix(): + """Determines if the confusion matrix should be logged based on the environment variable settings.""" + return os.getenv("COMET_EVAL_LOG_CONFUSION_MATRIX", "false").lower() == "true" + + +def _should_log_image_predictions(): + """Determines whether to log image predictions based on a specified environment variable.""" + return os.getenv("COMET_EVAL_LOG_IMAGE_PREDICTIONS", "true").lower() == "true" + + +def _get_experiment_type(mode, project_name): + """Return an experiment based on mode and project name.""" + if mode == "offline": + return comet_ml.OfflineExperiment(project_name=project_name) + + return comet_ml.Experiment(project_name=project_name) + + +def _create_experiment(args): + """Ensures that the experiment object is only created in a single process during distributed training.""" + if RANK not in {-1, 0}: + return + try: + comet_mode = _get_comet_mode() + _project_name = os.getenv("COMET_PROJECT_NAME", args.project) + experiment = _get_experiment_type(comet_mode, _project_name) + experiment.log_parameters(vars(args)) + experiment.log_others( + { + "eval_batch_logging_interval": _get_eval_batch_logging_interval(), + "log_confusion_matrix_on_eval": _should_log_confusion_matrix(), + "log_image_predictions": _should_log_image_predictions(), + "max_image_predictions": _get_max_image_predictions_to_log(), + } + ) + experiment.log_other("Created from", "yolov8") + + except Exception as e: + LOGGER.warning(f"WARNING ⚠️ Comet installed but not initialized correctly, not logging this run. {e}") + + +def _fetch_trainer_metadata(trainer): + """Returns metadata for YOLO training including epoch and asset saving status.""" + curr_epoch = trainer.epoch + 1 + + train_num_steps_per_epoch = len(trainer.train_loader.dataset) // trainer.batch_size + curr_step = curr_epoch * train_num_steps_per_epoch + final_epoch = curr_epoch == trainer.epochs + + save = trainer.args.save + save_period = trainer.args.save_period + save_interval = curr_epoch % save_period == 0 + save_assets = save and save_period > 0 and save_interval and not final_epoch + + return dict(curr_epoch=curr_epoch, curr_step=curr_step, save_assets=save_assets, final_epoch=final_epoch) + + +def _scale_bounding_box_to_original_image_shape(box, resized_image_shape, original_image_shape, ratio_pad): + """ + YOLOv8 resizes images during training and the label values are normalized based on this resized shape. + + This function rescales the bounding box labels to the original image shape. + """ + + resized_image_height, resized_image_width = resized_image_shape + + # Convert normalized xywh format predictions to xyxy in resized scale format + box = ops.xywhn2xyxy(box, h=resized_image_height, w=resized_image_width) + # Scale box predictions from resized image scale back to original image scale + box = ops.scale_boxes(resized_image_shape, box, original_image_shape, ratio_pad) + # Convert bounding box format from xyxy to xywh for Comet logging + box = ops.xyxy2xywh(box) + # Adjust xy center to correspond top-left corner + box[:2] -= box[2:] / 2 + box = box.tolist() + + return box + + +def _format_ground_truth_annotations_for_detection(img_idx, image_path, batch, class_name_map=None): + """Format ground truth annotations for detection.""" + indices = batch["batch_idx"] == img_idx + bboxes = batch["bboxes"][indices] + if len(bboxes) == 0: + LOGGER.debug(f"COMET WARNING: Image: {image_path} has no bounding boxes labels") + return None + + cls_labels = batch["cls"][indices].squeeze(1).tolist() + if class_name_map: + cls_labels = [str(class_name_map[label]) for label in cls_labels] + + original_image_shape = batch["ori_shape"][img_idx] + resized_image_shape = batch["resized_shape"][img_idx] + ratio_pad = batch["ratio_pad"][img_idx] + + data = [] + for box, label in zip(bboxes, cls_labels): + box = _scale_bounding_box_to_original_image_shape(box, resized_image_shape, original_image_shape, ratio_pad) + data.append( + { + "boxes": [box], + "label": f"gt_{label}", + "score": _scale_confidence_score(1.0), + } + ) + + return {"name": "ground_truth", "data": data} + + +def _format_prediction_annotations_for_detection(image_path, metadata, class_label_map=None): + """Format YOLO predictions for object detection visualization.""" + stem = image_path.stem + image_id = int(stem) if stem.isnumeric() else stem + + predictions = metadata.get(image_id) + if not predictions: + LOGGER.debug(f"COMET WARNING: Image: {image_path} has no bounding boxes predictions") + return None + + data = [] + for prediction in predictions: + boxes = prediction["bbox"] + score = _scale_confidence_score(prediction["score"]) + cls_label = prediction["category_id"] + if class_label_map: + cls_label = str(class_label_map[cls_label]) + + data.append({"boxes": [boxes], "label": cls_label, "score": score}) + + return {"name": "prediction", "data": data} + + +def _fetch_annotations(img_idx, image_path, batch, prediction_metadata_map, class_label_map): + """Join the ground truth and prediction annotations if they exist.""" + ground_truth_annotations = _format_ground_truth_annotations_for_detection( + img_idx, image_path, batch, class_label_map + ) + prediction_annotations = _format_prediction_annotations_for_detection( + image_path, prediction_metadata_map, class_label_map + ) + + annotations = [ + annotation for annotation in [ground_truth_annotations, prediction_annotations] if annotation is not None + ] + return [annotations] if annotations else None + + +def _create_prediction_metadata_map(model_predictions): + """Create metadata map for model predictions by groupings them based on image ID.""" + pred_metadata_map = {} + for prediction in model_predictions: + pred_metadata_map.setdefault(prediction["image_id"], []) + pred_metadata_map[prediction["image_id"]].append(prediction) + + return pred_metadata_map + + +def _log_confusion_matrix(experiment, trainer, curr_step, curr_epoch): + """Log the confusion matrix to Comet experiment.""" + conf_mat = trainer.validator.confusion_matrix.matrix + names = list(trainer.data["names"].values()) + ["background"] + experiment.log_confusion_matrix( + matrix=conf_mat, labels=names, max_categories=len(names), epoch=curr_epoch, step=curr_step + ) + + +def _log_images(experiment, image_paths, curr_step, annotations=None): + """Logs images to the experiment with optional annotations.""" + if annotations: + for image_path, annotation in zip(image_paths, annotations): + experiment.log_image(image_path, name=image_path.stem, step=curr_step, annotations=annotation) + + else: + for image_path in image_paths: + experiment.log_image(image_path, name=image_path.stem, step=curr_step) + + +def _log_image_predictions(experiment, validator, curr_step): + """Logs predicted boxes for a single image during training.""" + global _comet_image_prediction_count + + task = validator.args.task + if task not in COMET_SUPPORTED_TASKS: + return + + jdict = validator.jdict + if not jdict: + return + + predictions_metadata_map = _create_prediction_metadata_map(jdict) + dataloader = validator.dataloader + class_label_map = validator.names + + batch_logging_interval = _get_eval_batch_logging_interval() + max_image_predictions = _get_max_image_predictions_to_log() + + for batch_idx, batch in enumerate(dataloader): + if (batch_idx + 1) % batch_logging_interval != 0: + continue + + image_paths = batch["im_file"] + for img_idx, image_path in enumerate(image_paths): + if _comet_image_prediction_count >= max_image_predictions: + return + + image_path = Path(image_path) + annotations = _fetch_annotations( + img_idx, + image_path, + batch, + predictions_metadata_map, + class_label_map, + ) + _log_images( + experiment, + [image_path], + curr_step, + annotations=annotations, + ) + _comet_image_prediction_count += 1 + + +def _log_plots(experiment, trainer): + """Logs evaluation plots and label plots for the experiment.""" + plot_filenames = [trainer.save_dir / f"{plots}.png" for plots in EVALUATION_PLOT_NAMES] + _log_images(experiment, plot_filenames, None) + + label_plot_filenames = [trainer.save_dir / f"{labels}.jpg" for labels in LABEL_PLOT_NAMES] + _log_images(experiment, label_plot_filenames, None) + + +def _log_model(experiment, trainer): + """Log the best-trained model to Comet.ml.""" + model_name = _get_comet_model_name() + experiment.log_model(model_name, file_or_folder=str(trainer.best), file_name="best.pt", overwrite=True) + + +def on_pretrain_routine_start(trainer): + """Creates or resumes a CometML experiment at the start of a YOLO pre-training routine.""" + experiment = comet_ml.get_global_experiment() + is_alive = getattr(experiment, "alive", False) + if not experiment or not is_alive: + _create_experiment(trainer.args) + + +def on_train_epoch_end(trainer): + """Log metrics and save batch images at the end of training epochs.""" + experiment = comet_ml.get_global_experiment() + if not experiment: + return + + metadata = _fetch_trainer_metadata(trainer) + curr_epoch = metadata["curr_epoch"] + curr_step = metadata["curr_step"] + + experiment.log_metrics(trainer.label_loss_items(trainer.tloss, prefix="train"), step=curr_step, epoch=curr_epoch) + + if curr_epoch == 1: + _log_images(experiment, trainer.save_dir.glob("train_batch*.jpg"), curr_step) + + +def on_fit_epoch_end(trainer): + """Logs model assets at the end of each epoch.""" + experiment = comet_ml.get_global_experiment() + if not experiment: + return + + metadata = _fetch_trainer_metadata(trainer) + curr_epoch = metadata["curr_epoch"] + curr_step = metadata["curr_step"] + save_assets = metadata["save_assets"] + + experiment.log_metrics(trainer.metrics, step=curr_step, epoch=curr_epoch) + experiment.log_metrics(trainer.lr, step=curr_step, epoch=curr_epoch) + if curr_epoch == 1: + from ultralytics.utils.torch_utils import model_info_for_loggers + + experiment.log_metrics(model_info_for_loggers(trainer), step=curr_step, epoch=curr_epoch) + + if not save_assets: + return + + _log_model(experiment, trainer) + if _should_log_confusion_matrix(): + _log_confusion_matrix(experiment, trainer, curr_step, curr_epoch) + if _should_log_image_predictions(): + _log_image_predictions(experiment, trainer.validator, curr_step) + + +def on_train_end(trainer): + """Perform operations at the end of training.""" + experiment = comet_ml.get_global_experiment() + if not experiment: + return + + metadata = _fetch_trainer_metadata(trainer) + curr_epoch = metadata["curr_epoch"] + curr_step = metadata["curr_step"] + plots = trainer.args.plots + + _log_model(experiment, trainer) + if plots: + _log_plots(experiment, trainer) + + _log_confusion_matrix(experiment, trainer, curr_step, curr_epoch) + _log_image_predictions(experiment, trainer.validator, curr_step) + experiment.end() + + global _comet_image_prediction_count + _comet_image_prediction_count = 0 + + +callbacks = ( + { + "on_pretrain_routine_start": on_pretrain_routine_start, + "on_train_epoch_end": on_train_epoch_end, + "on_fit_epoch_end": on_fit_epoch_end, + "on_train_end": on_train_end, + } + if comet_ml + else {} +) diff --git a/ultralytics/utils/callbacks/dvc.py b/ultralytics/utils/callbacks/dvc.py new file mode 100644 index 0000000..ab51dc5 --- /dev/null +++ b/ultralytics/utils/callbacks/dvc.py @@ -0,0 +1,145 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from ultralytics.utils import LOGGER, SETTINGS, TESTS_RUNNING, checks + +try: + assert not TESTS_RUNNING # do not log pytest + assert SETTINGS["dvc"] is True # verify integration is enabled + import dvclive + + assert checks.check_version("dvclive", "2.11.0", verbose=True) + + import os + import re + from pathlib import Path + + # DVCLive logger instance + live = None + _processed_plots = {} + + # `on_fit_epoch_end` is called on final validation (probably need to be fixed) for now this is the way we + # distinguish final evaluation of the best model vs last epoch validation + _training_epoch = False + +except (ImportError, AssertionError, TypeError): + dvclive = None + + +def _log_images(path, prefix=""): + """Logs images at specified path with an optional prefix using DVCLive.""" + if live: + name = path.name + + # Group images by batch to enable sliders in UI + if m := re.search(r"_batch(\d+)", name): + ni = m[1] + new_stem = re.sub(r"_batch(\d+)", "_batch", path.stem) + name = (Path(new_stem) / ni).with_suffix(path.suffix) + + live.log_image(os.path.join(prefix, name), path) + + +def _log_plots(plots, prefix=""): + """Logs plot images for training progress if they have not been previously processed.""" + for name, params in plots.items(): + timestamp = params["timestamp"] + if _processed_plots.get(name) != timestamp: + _log_images(name, prefix) + _processed_plots[name] = timestamp + + +def _log_confusion_matrix(validator): + """Logs the confusion matrix for the given validator using DVCLive.""" + targets = [] + preds = [] + matrix = validator.confusion_matrix.matrix + names = list(validator.names.values()) + if validator.confusion_matrix.task == "detect": + names += ["background"] + + for ti, pred in enumerate(matrix.T.astype(int)): + for pi, num in enumerate(pred): + targets.extend([names[ti]] * num) + preds.extend([names[pi]] * num) + + live.log_sklearn_plot("confusion_matrix", targets, preds, name="cf.json", normalized=True) + + +def on_pretrain_routine_start(trainer): + """Initializes DVCLive logger for training metadata during pre-training routine.""" + try: + global live + live = dvclive.Live(save_dvc_exp=True, cache_images=True) + LOGGER.info("DVCLive is detected and auto logging is enabled (run 'yolo settings dvc=False' to disable).") + except Exception as e: + LOGGER.warning(f"WARNING ⚠️ DVCLive installed but not initialized correctly, not logging this run. {e}") + + +def on_pretrain_routine_end(trainer): + """Logs plots related to the training process at the end of the pretraining routine.""" + _log_plots(trainer.plots, "train") + + +def on_train_start(trainer): + """Logs the training parameters if DVCLive logging is active.""" + if live: + live.log_params(trainer.args) + + +def on_train_epoch_start(trainer): + """Sets the global variable _training_epoch value to True at the start of training each epoch.""" + global _training_epoch + _training_epoch = True + + +def on_fit_epoch_end(trainer): + """Logs training metrics and model info, and advances to next step on the end of each fit epoch.""" + global _training_epoch + if live and _training_epoch: + all_metrics = {**trainer.label_loss_items(trainer.tloss, prefix="train"), **trainer.metrics, **trainer.lr} + for metric, value in all_metrics.items(): + live.log_metric(metric, value) + + if trainer.epoch == 0: + from ultralytics.utils.torch_utils import model_info_for_loggers + + for metric, value in model_info_for_loggers(trainer).items(): + live.log_metric(metric, value, plot=False) + + _log_plots(trainer.plots, "train") + _log_plots(trainer.validator.plots, "val") + + live.next_step() + _training_epoch = False + + +def on_train_end(trainer): + """Logs the best metrics, plots, and confusion matrix at the end of training if DVCLive is active.""" + if live: + # At the end log the best metrics. It runs validator on the best model internally. + all_metrics = {**trainer.label_loss_items(trainer.tloss, prefix="train"), **trainer.metrics, **trainer.lr} + for metric, value in all_metrics.items(): + live.log_metric(metric, value, plot=False) + + _log_plots(trainer.plots, "val") + _log_plots(trainer.validator.plots, "val") + _log_confusion_matrix(trainer.validator) + + if trainer.best.exists(): + live.log_artifact(trainer.best, copy=True, type="model") + + live.end() + + +callbacks = ( + { + "on_pretrain_routine_start": on_pretrain_routine_start, + "on_pretrain_routine_end": on_pretrain_routine_end, + "on_train_start": on_train_start, + "on_train_epoch_start": on_train_epoch_start, + "on_fit_epoch_end": on_fit_epoch_end, + "on_train_end": on_train_end, + } + if dvclive + else {} +) diff --git a/ultralytics/utils/callbacks/hub.py b/ultralytics/utils/callbacks/hub.py new file mode 100644 index 0000000..99fe98b --- /dev/null +++ b/ultralytics/utils/callbacks/hub.py @@ -0,0 +1,105 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import json +from time import time + +from ultralytics.hub.utils import HUB_WEB_ROOT, PREFIX, events +from ultralytics.utils import LOGGER, SETTINGS + + +def on_pretrain_routine_end(trainer): + """Logs info before starting timer for upload rate limit.""" + session = getattr(trainer, "hub_session", None) + if session: + # Start timer for upload rate limit + session.timers = {"metrics": time(), "ckpt": time()} # start timer on session.rate_limit + + +def on_fit_epoch_end(trainer): + """Uploads training progress metrics at the end of each epoch.""" + session = getattr(trainer, "hub_session", None) + if session: + # Upload metrics after val end + all_plots = { + **trainer.label_loss_items(trainer.tloss, prefix="train"), + **trainer.metrics, + } + if trainer.epoch == 0: + from ultralytics.utils.torch_utils import model_info_for_loggers + + all_plots = {**all_plots, **model_info_for_loggers(trainer)} + + session.metrics_queue[trainer.epoch] = json.dumps(all_plots) + + # If any metrics fail to upload, add them to the queue to attempt uploading again. + if session.metrics_upload_failed_queue: + session.metrics_queue.update(session.metrics_upload_failed_queue) + + if time() - session.timers["metrics"] > session.rate_limits["metrics"]: + session.upload_metrics() + session.timers["metrics"] = time() # reset timer + session.metrics_queue = {} # reset queue + + +def on_model_save(trainer): + """Saves checkpoints to Ultralytics HUB with rate limiting.""" + session = getattr(trainer, "hub_session", None) + if session: + # Upload checkpoints with rate limiting + is_best = trainer.best_fitness == trainer.fitness + if time() - session.timers["ckpt"] > session.rate_limits["ckpt"]: + LOGGER.info(f"{PREFIX}Uploading checkpoint {HUB_WEB_ROOT}/models/{session.model.id}") + session.upload_model(trainer.epoch, trainer.last, is_best) + session.timers["ckpt"] = time() # reset timer + + +def on_train_end(trainer): + """Upload final model and metrics to Ultralytics HUB at the end of training.""" + session = getattr(trainer, "hub_session", None) + if session: + # Upload final model and metrics with exponential standoff + LOGGER.info(f"{PREFIX}Syncing final model...") + session.upload_model( + trainer.epoch, + trainer.best, + map=trainer.metrics.get("metrics/mAP50-95(B)", 0), + final=True, + ) + session.alive = False # stop heartbeats + LOGGER.info(f"{PREFIX}Done ✅\n" f"{PREFIX}View model at {session.model_url} 🚀") + + +def on_train_start(trainer): + """Run events on train start.""" + events(trainer.args) + + +def on_val_start(validator): + """Runs events on validation start.""" + events(validator.args) + + +def on_predict_start(predictor): + """Run events on predict start.""" + events(predictor.args) + + +def on_export_start(exporter): + """Run events on export start.""" + events(exporter.args) + + +callbacks = ( + { + "on_pretrain_routine_end": on_pretrain_routine_end, + "on_fit_epoch_end": on_fit_epoch_end, + "on_model_save": on_model_save, + "on_train_end": on_train_end, + "on_train_start": on_train_start, + "on_val_start": on_val_start, + "on_predict_start": on_predict_start, + "on_export_start": on_export_start, + } + if SETTINGS["hub"] is True + else {} +) # verify enabled diff --git a/ultralytics/utils/callbacks/mlflow.py b/ultralytics/utils/callbacks/mlflow.py new file mode 100644 index 0000000..249c876 --- /dev/null +++ b/ultralytics/utils/callbacks/mlflow.py @@ -0,0 +1,133 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +""" +MLflow Logging for Ultralytics YOLO. + +This module enables MLflow logging for Ultralytics YOLO. It logs metrics, parameters, and model artifacts. +For setting up, a tracking URI should be specified. The logging can be customized using environment variables. + +Commands: + 1. To set a project name: + `export MLFLOW_EXPERIMENT_NAME=` or use the project= argument + + 2. To set a run name: + `export MLFLOW_RUN=` or use the name= argument + + 3. To start a local MLflow server: + mlflow server --backend-store-uri runs/mlflow + It will by default start a local server at http://127.0.0.1:5000. + To specify a different URI, set the MLFLOW_TRACKING_URI environment variable. + + 4. To kill all running MLflow server instances: + ps aux | grep 'mlflow' | grep -v 'grep' | awk '{print $2}' | xargs kill -9 +""" + +from ultralytics.utils import LOGGER, RUNS_DIR, SETTINGS, TESTS_RUNNING, colorstr + +try: + import os + + assert not TESTS_RUNNING or "test_mlflow" in os.environ.get("PYTEST_CURRENT_TEST", "") # do not log pytest + assert SETTINGS["mlflow"] is True # verify integration is enabled + import mlflow + + assert hasattr(mlflow, "__version__") # verify package is not directory + from pathlib import Path + + PREFIX = colorstr("MLflow: ") + SANITIZE = lambda x: {k.replace("(", "").replace(")", ""): float(v) for k, v in x.items()} + +except (ImportError, AssertionError): + mlflow = None + + +def on_pretrain_routine_end(trainer): + """ + Log training parameters to MLflow at the end of the pretraining routine. + + This function sets up MLflow logging based on environment variables and trainer arguments. It sets the tracking URI, + experiment name, and run name, then starts the MLflow run if not already active. It finally logs the parameters + from the trainer. + + Args: + trainer (ultralytics.engine.trainer.BaseTrainer): The training object with arguments and parameters to log. + + Global: + mlflow: The imported mlflow module to use for logging. + + Environment Variables: + MLFLOW_TRACKING_URI: The URI for MLflow tracking. If not set, defaults to 'runs/mlflow'. + MLFLOW_EXPERIMENT_NAME: The name of the MLflow experiment. If not set, defaults to trainer.args.project. + MLFLOW_RUN: The name of the MLflow run. If not set, defaults to trainer.args.name. + MLFLOW_KEEP_RUN_ACTIVE: Boolean indicating whether to keep the MLflow run active after the end of training. + """ + global mlflow + + uri = os.environ.get("MLFLOW_TRACKING_URI") or str(RUNS_DIR / "mlflow") + LOGGER.debug(f"{PREFIX} tracking uri: {uri}") + mlflow.set_tracking_uri(uri) + + # Set experiment and run names + experiment_name = os.environ.get("MLFLOW_EXPERIMENT_NAME") or trainer.args.project or "/Shared/YOLOv8" + run_name = os.environ.get("MLFLOW_RUN") or trainer.args.name + mlflow.set_experiment(experiment_name) + + mlflow.autolog() + try: + active_run = mlflow.active_run() or mlflow.start_run(run_name=run_name) + LOGGER.info(f"{PREFIX}logging run_id({active_run.info.run_id}) to {uri}") + if Path(uri).is_dir(): + LOGGER.info(f"{PREFIX}view at http://127.0.0.1:5000 with 'mlflow server --backend-store-uri {uri}'") + LOGGER.info(f"{PREFIX}disable with 'yolo settings mlflow=False'") + mlflow.log_params(dict(trainer.args)) + except Exception as e: + LOGGER.warning(f"{PREFIX}WARNING ⚠️ Failed to initialize: {e}\n" f"{PREFIX}WARNING ⚠️ Not tracking this run") + + +def on_train_epoch_end(trainer): + """Log training metrics at the end of each train epoch to MLflow.""" + if mlflow: + mlflow.log_metrics( + metrics={ + **SANITIZE(trainer.lr), + **SANITIZE(trainer.label_loss_items(trainer.tloss, prefix="train")), + }, + step=trainer.epoch, + ) + + +def on_fit_epoch_end(trainer): + """Log training metrics at the end of each fit epoch to MLflow.""" + if mlflow: + mlflow.log_metrics(metrics=SANITIZE(trainer.metrics), step=trainer.epoch) + + +def on_train_end(trainer): + """Log model artifacts at the end of the training.""" + if mlflow: + mlflow.log_artifact(str(trainer.best.parent)) # log save_dir/weights directory with best.pt and last.pt + for f in trainer.save_dir.glob("*"): # log all other files in save_dir + if f.suffix in {".png", ".jpg", ".csv", ".pt", ".yaml"}: + mlflow.log_artifact(str(f)) + keep_run_active = os.environ.get("MLFLOW_KEEP_RUN_ACTIVE", "False").lower() == "true" + if keep_run_active: + LOGGER.info(f"{PREFIX}mlflow run still alive, remember to close it using mlflow.end_run()") + else: + mlflow.end_run() + LOGGER.debug(f"{PREFIX}mlflow run ended") + + LOGGER.info( + f"{PREFIX}results logged to {mlflow.get_tracking_uri()}\n" + f"{PREFIX}disable with 'yolo settings mlflow=False'" + ) + + +callbacks = ( + { + "on_pretrain_routine_end": on_pretrain_routine_end, + "on_train_epoch_end": on_train_epoch_end, + "on_fit_epoch_end": on_fit_epoch_end, + "on_train_end": on_train_end, + } + if mlflow + else {} +) diff --git a/ultralytics/utils/callbacks/neptune.py b/ultralytics/utils/callbacks/neptune.py new file mode 100644 index 0000000..6be8a82 --- /dev/null +++ b/ultralytics/utils/callbacks/neptune.py @@ -0,0 +1,112 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from ultralytics.utils import LOGGER, SETTINGS, TESTS_RUNNING + +try: + assert not TESTS_RUNNING # do not log pytest + assert SETTINGS["neptune"] is True # verify integration is enabled + import neptune + from neptune.types import File + + assert hasattr(neptune, "__version__") + + run = None # NeptuneAI experiment logger instance + +except (ImportError, AssertionError): + neptune = None + + +def _log_scalars(scalars, step=0): + """Log scalars to the NeptuneAI experiment logger.""" + if run: + for k, v in scalars.items(): + run[k].append(value=v, step=step) + + +def _log_images(imgs_dict, group=""): + """Log scalars to the NeptuneAI experiment logger.""" + if run: + for k, v in imgs_dict.items(): + run[f"{group}/{k}"].upload(File(v)) + + +def _log_plot(title, plot_path): + """ + Log plots to the NeptuneAI experiment logger. + + Args: + title (str): Title of the plot. + plot_path (PosixPath | str): Path to the saved image file. + """ + import matplotlib.image as mpimg + import matplotlib.pyplot as plt + + img = mpimg.imread(plot_path) + fig = plt.figure() + ax = fig.add_axes([0, 0, 1, 1], frameon=False, aspect="auto", xticks=[], yticks=[]) # no ticks + ax.imshow(img) + run[f"Plots/{title}"].upload(fig) + + +def on_pretrain_routine_start(trainer): + """Callback function called before the training routine starts.""" + try: + global run + run = neptune.init_run(project=trainer.args.project or "YOLOv8", name=trainer.args.name, tags=["YOLOv8"]) + run["Configuration/Hyperparameters"] = {k: "" if v is None else v for k, v in vars(trainer.args).items()} + except Exception as e: + LOGGER.warning(f"WARNING ⚠️ NeptuneAI installed but not initialized correctly, not logging this run. {e}") + + +def on_train_epoch_end(trainer): + """Callback function called at end of each training epoch.""" + _log_scalars(trainer.label_loss_items(trainer.tloss, prefix="train"), trainer.epoch + 1) + _log_scalars(trainer.lr, trainer.epoch + 1) + if trainer.epoch == 1: + _log_images({f.stem: str(f) for f in trainer.save_dir.glob("train_batch*.jpg")}, "Mosaic") + + +def on_fit_epoch_end(trainer): + """Callback function called at end of each fit (train+val) epoch.""" + if run and trainer.epoch == 0: + from ultralytics.utils.torch_utils import model_info_for_loggers + + run["Configuration/Model"] = model_info_for_loggers(trainer) + _log_scalars(trainer.metrics, trainer.epoch + 1) + + +def on_val_end(validator): + """Callback function called at end of each validation.""" + if run: + # Log val_labels and val_pred + _log_images({f.stem: str(f) for f in validator.save_dir.glob("val*.jpg")}, "Validation") + + +def on_train_end(trainer): + """Callback function called at end of training.""" + if run: + # Log final results, CM matrix + PR plots + files = [ + "results.png", + "confusion_matrix.png", + "confusion_matrix_normalized.png", + *(f"{x}_curve.png" for x in ("F1", "PR", "P", "R")), + ] + files = [(trainer.save_dir / f) for f in files if (trainer.save_dir / f).exists()] # filter + for f in files: + _log_plot(title=f.stem, plot_path=f) + # Log the final model + run[f"weights/{trainer.args.name or trainer.args.task}/{trainer.best.name}"].upload(File(str(trainer.best))) + + +callbacks = ( + { + "on_pretrain_routine_start": on_pretrain_routine_start, + "on_train_epoch_end": on_train_epoch_end, + "on_fit_epoch_end": on_fit_epoch_end, + "on_val_end": on_val_end, + "on_train_end": on_train_end, + } + if neptune + else {} +) diff --git a/ultralytics/utils/callbacks/raytune.py b/ultralytics/utils/callbacks/raytune.py new file mode 100644 index 0000000..1a368db --- /dev/null +++ b/ultralytics/utils/callbacks/raytune.py @@ -0,0 +1,29 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from ultralytics.utils import SETTINGS + +try: + assert SETTINGS["raytune"] is True # verify integration is enabled + import ray + from ray import tune + from ray.air import session + +except (ImportError, AssertionError): + tune = None + + +def on_fit_epoch_end(trainer): + """Sends training metrics to Ray Tune at end of each epoch.""" + if ray.train._internal.session._get_session(): # replacement for deprecated ray.tune.is_session_enabled() + metrics = trainer.metrics + metrics["epoch"] = trainer.epoch + session.report(metrics) + + +callbacks = ( + { + "on_fit_epoch_end": on_fit_epoch_end, + } + if tune + else {} +) diff --git a/ultralytics/utils/callbacks/tensorboard.py b/ultralytics/utils/callbacks/tensorboard.py new file mode 100644 index 0000000..b8a9825 --- /dev/null +++ b/ultralytics/utils/callbacks/tensorboard.py @@ -0,0 +1,107 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +import contextlib + +from ultralytics.utils import LOGGER, SETTINGS, TESTS_RUNNING, colorstr + +try: + # WARNING: do not move SummaryWriter import due to protobuf bug https://github.com/ultralytics/ultralytics/pull/4674 + from torch.utils.tensorboard import SummaryWriter + + assert not TESTS_RUNNING # do not log pytest + assert SETTINGS["tensorboard"] is True # verify integration is enabled + WRITER = None # TensorBoard SummaryWriter instance + PREFIX = colorstr("TensorBoard: ") + + # Imports below only required if TensorBoard enabled + import warnings + from copy import deepcopy + + from ultralytics.utils.torch_utils import de_parallel, torch + +except (ImportError, AssertionError, TypeError, AttributeError): + # TypeError for handling 'Descriptors cannot not be created directly.' protobuf errors in Windows + # AttributeError: module 'tensorflow' has no attribute 'io' if 'tensorflow' not installed + SummaryWriter = None + + +def _log_scalars(scalars, step=0): + """Logs scalar values to TensorBoard.""" + if WRITER: + for k, v in scalars.items(): + WRITER.add_scalar(k, v, step) + + +def _log_tensorboard_graph(trainer): + """Log model graph to TensorBoard.""" + + # Input image + imgsz = trainer.args.imgsz + imgsz = (imgsz, imgsz) if isinstance(imgsz, int) else imgsz + p = next(trainer.model.parameters()) # for device, type + im = torch.zeros((1, 3, *imgsz), device=p.device, dtype=p.dtype) # input image (must be zeros, not empty) + + with warnings.catch_warnings(): + warnings.simplefilter("ignore", category=UserWarning) # suppress jit trace warning + warnings.simplefilter("ignore", category=torch.jit.TracerWarning) # suppress jit trace warning + + # Try simple method first (YOLO) + with contextlib.suppress(Exception): + trainer.model.eval() # place in .eval() mode to avoid BatchNorm statistics changes + WRITER.add_graph(torch.jit.trace(de_parallel(trainer.model), im, strict=False), []) + LOGGER.info(f"{PREFIX}model graph visualization added ✅") + return + + # Fallback to TorchScript export steps (RTDETR) + try: + model = deepcopy(de_parallel(trainer.model)) + model.eval() + model = model.fuse(verbose=False) + for m in model.modules(): + if hasattr(m, "export"): # Detect, RTDETRDecoder (Segment and Pose use Detect base class) + m.export = True + m.format = "torchscript" + model(im) # dry run + WRITER.add_graph(torch.jit.trace(model, im, strict=False), []) + LOGGER.info(f"{PREFIX}model graph visualization added ✅") + except Exception as e: + LOGGER.warning(f"{PREFIX}WARNING ⚠️ TensorBoard graph visualization failure {e}") + + +def on_pretrain_routine_start(trainer): + """Initialize TensorBoard logging with SummaryWriter.""" + if SummaryWriter: + try: + global WRITER + WRITER = SummaryWriter(str(trainer.save_dir)) + LOGGER.info(f"{PREFIX}Start with 'tensorboard --logdir {trainer.save_dir}', view at http://localhost:6006/") + except Exception as e: + LOGGER.warning(f"{PREFIX}WARNING ⚠️ TensorBoard not initialized correctly, not logging this run. {e}") + + +def on_train_start(trainer): + """Log TensorBoard graph.""" + if WRITER: + _log_tensorboard_graph(trainer) + + +def on_train_epoch_end(trainer): + """Logs scalar statistics at the end of a training epoch.""" + _log_scalars(trainer.label_loss_items(trainer.tloss, prefix="train"), trainer.epoch + 1) + _log_scalars(trainer.lr, trainer.epoch + 1) + + +def on_fit_epoch_end(trainer): + """Logs epoch metrics at end of training epoch.""" + _log_scalars(trainer.metrics, trainer.epoch + 1) + + +callbacks = ( + { + "on_pretrain_routine_start": on_pretrain_routine_start, + "on_train_start": on_train_start, + "on_fit_epoch_end": on_fit_epoch_end, + "on_train_epoch_end": on_train_epoch_end, + } + if SummaryWriter + else {} +) diff --git a/ultralytics/utils/callbacks/wb.py b/ultralytics/utils/callbacks/wb.py new file mode 100644 index 0000000..796d509 --- /dev/null +++ b/ultralytics/utils/callbacks/wb.py @@ -0,0 +1,163 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from ultralytics.utils import SETTINGS, TESTS_RUNNING +from ultralytics.utils.torch_utils import model_info_for_loggers + +try: + assert not TESTS_RUNNING # do not log pytest + assert SETTINGS["wandb"] is True # verify integration is enabled + import wandb as wb + + assert hasattr(wb, "__version__") # verify package is not directory + _processed_plots = {} + +except (ImportError, AssertionError): + wb = None + + +def _custom_table(x, y, classes, title="Precision Recall Curve", x_title="Recall", y_title="Precision"): + """ + Create and log a custom metric visualization to wandb.plot.pr_curve. + + This function crafts a custom metric visualization that mimics the behavior of wandb's default precision-recall + curve while allowing for enhanced customization. The visual metric is useful for monitoring model performance across + different classes. + + Args: + x (List): Values for the x-axis; expected to have length N. + y (List): Corresponding values for the y-axis; also expected to have length N. + classes (List): Labels identifying the class of each point; length N. + title (str, optional): Title for the plot; defaults to 'Precision Recall Curve'. + x_title (str, optional): Label for the x-axis; defaults to 'Recall'. + y_title (str, optional): Label for the y-axis; defaults to 'Precision'. + + Returns: + (wandb.Object): A wandb object suitable for logging, showcasing the crafted metric visualization. + """ + import pandas # scope for faster 'import ultralytics' + + df = pandas.DataFrame({"class": classes, "y": y, "x": x}).round(3) + fields = {"x": "x", "y": "y", "class": "class"} + string_fields = {"title": title, "x-axis-title": x_title, "y-axis-title": y_title} + return wb.plot_table( + "wandb/area-under-curve/v0", wb.Table(dataframe=df), fields=fields, string_fields=string_fields + ) + + +def _plot_curve( + x, + y, + names=None, + id="precision-recall", + title="Precision Recall Curve", + x_title="Recall", + y_title="Precision", + num_x=100, + only_mean=False, +): + """ + Log a metric curve visualization. + + This function generates a metric curve based on input data and logs the visualization to wandb. + The curve can represent aggregated data (mean) or individual class data, depending on the 'only_mean' flag. + + Args: + x (np.ndarray): Data points for the x-axis with length N. + y (np.ndarray): Corresponding data points for the y-axis with shape CxN, where C is the number of classes. + names (list, optional): Names of the classes corresponding to the y-axis data; length C. Defaults to []. + id (str, optional): Unique identifier for the logged data in wandb. Defaults to 'precision-recall'. + title (str, optional): Title for the visualization plot. Defaults to 'Precision Recall Curve'. + x_title (str, optional): Label for the x-axis. Defaults to 'Recall'. + y_title (str, optional): Label for the y-axis. Defaults to 'Precision'. + num_x (int, optional): Number of interpolated data points for visualization. Defaults to 100. + only_mean (bool, optional): Flag to indicate if only the mean curve should be plotted. Defaults to True. + + Note: + The function leverages the '_custom_table' function to generate the actual visualization. + """ + import numpy as np + + # Create new x + if names is None: + names = [] + x_new = np.linspace(x[0], x[-1], num_x).round(5) + + # Create arrays for logging + x_log = x_new.tolist() + y_log = np.interp(x_new, x, np.mean(y, axis=0)).round(3).tolist() + + if only_mean: + table = wb.Table(data=list(zip(x_log, y_log)), columns=[x_title, y_title]) + wb.run.log({title: wb.plot.line(table, x_title, y_title, title=title)}) + else: + classes = ["mean"] * len(x_log) + for i, yi in enumerate(y): + x_log.extend(x_new) # add new x + y_log.extend(np.interp(x_new, x, yi)) # interpolate y to new x + classes.extend([names[i]] * len(x_new)) # add class names + wb.log({id: _custom_table(x_log, y_log, classes, title, x_title, y_title)}, commit=False) + + +def _log_plots(plots, step): + """Logs plots from the input dictionary if they haven't been logged already at the specified step.""" + for name, params in plots.items(): + timestamp = params["timestamp"] + if _processed_plots.get(name) != timestamp: + wb.run.log({name.stem: wb.Image(str(name))}, step=step) + _processed_plots[name] = timestamp + + +def on_pretrain_routine_start(trainer): + """Initiate and start project if module is present.""" + wb.run or wb.init(project=trainer.args.project or "YOLOv8", name=trainer.args.name, config=vars(trainer.args)) + + +def on_fit_epoch_end(trainer): + """Logs training metrics and model information at the end of an epoch.""" + wb.run.log(trainer.metrics, step=trainer.epoch + 1) + _log_plots(trainer.plots, step=trainer.epoch + 1) + _log_plots(trainer.validator.plots, step=trainer.epoch + 1) + if trainer.epoch == 0: + wb.run.log(model_info_for_loggers(trainer), step=trainer.epoch + 1) + + +def on_train_epoch_end(trainer): + """Log metrics and save images at the end of each training epoch.""" + wb.run.log(trainer.label_loss_items(trainer.tloss, prefix="train"), step=trainer.epoch + 1) + wb.run.log(trainer.lr, step=trainer.epoch + 1) + if trainer.epoch == 1: + _log_plots(trainer.plots, step=trainer.epoch + 1) + + +def on_train_end(trainer): + """Save the best model as an artifact at end of training.""" + _log_plots(trainer.validator.plots, step=trainer.epoch + 1) + _log_plots(trainer.plots, step=trainer.epoch + 1) + art = wb.Artifact(type="model", name=f"run_{wb.run.id}_model") + if trainer.best.exists(): + art.add_file(trainer.best) + wb.run.log_artifact(art, aliases=["best"]) + for curve_name, curve_values in zip(trainer.validator.metrics.curves, trainer.validator.metrics.curves_results): + x, y, x_title, y_title = curve_values + _plot_curve( + x, + y, + names=list(trainer.validator.metrics.names.values()), + id=f"curves/{curve_name}", + title=curve_name, + x_title=x_title, + y_title=y_title, + ) + wb.run.finish() # required or run continues on dashboard + + +callbacks = ( + { + "on_pretrain_routine_start": on_pretrain_routine_start, + "on_train_epoch_end": on_train_epoch_end, + "on_fit_epoch_end": on_fit_epoch_end, + "on_train_end": on_train_end, + } + if wb + else {} +) diff --git a/ultralytics/utils/checks.py b/ultralytics/utils/checks.py new file mode 100644 index 0000000..85c60f9 --- /dev/null +++ b/ultralytics/utils/checks.py @@ -0,0 +1,736 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import contextlib +import glob +import inspect +import math +import os +import platform +import re +import shutil +import subprocess +import time +from importlib import metadata +from pathlib import Path +from typing import Optional + +import cv2 +import numpy as np +import requests +import torch + +from ultralytics.utils import ( + ASSETS, + AUTOINSTALL, + IS_COLAB, + IS_DOCKER, + IS_JUPYTER, + IS_KAGGLE, + IS_PIP_PACKAGE, + LINUX, + LOGGER, + ONLINE, + PYTHON_VERSION, + ROOT, + TORCHVISION_VERSION, + USER_CONFIG_DIR, + Retry, + SimpleNamespace, + ThreadingLocked, + TryExcept, + clean_url, + colorstr, + downloads, + emojis, + is_github_action_running, + url2file, +) + + +def parse_requirements(file_path=ROOT.parent / "requirements.txt", package=""): + """ + Parse a requirements.txt file, ignoring lines that start with '#' and any text after '#'. + + Args: + file_path (Path): Path to the requirements.txt file. + package (str, optional): Python package to use instead of requirements.txt file, i.e. package='ultralytics'. + + Returns: + (List[Dict[str, str]]): List of parsed requirements as dictionaries with `name` and `specifier` keys. + + Example: + ```python + from ultralytics.utils.checks import parse_requirements + + parse_requirements(package='ultralytics') + ``` + """ + + if package: + requires = [x for x in metadata.distribution(package).requires if "extra == " not in x] + else: + requires = Path(file_path).read_text().splitlines() + + requirements = [] + for line in requires: + line = line.strip() + if line and not line.startswith("#"): + line = line.split("#")[0].strip() # ignore inline comments + match = re.match(r"([a-zA-Z0-9-_]+)\s*([<>!=~]+.*)?", line) + if match: + requirements.append(SimpleNamespace(name=match[1], specifier=match[2].strip() if match[2] else "")) + + return requirements + + +def parse_version(version="0.0.0") -> tuple: + """ + Convert a version string to a tuple of integers, ignoring any extra non-numeric string attached to the version. This + function replaces deprecated 'pkg_resources.parse_version(v)'. + + Args: + version (str): Version string, i.e. '2.0.1+cpu' + + Returns: + (tuple): Tuple of integers representing the numeric part of the version and the extra string, i.e. (2, 0, 1) + """ + try: + return tuple(map(int, re.findall(r"\d+", version)[:3])) # '2.0.1+cpu' -> (2, 0, 1) + except Exception as e: + LOGGER.warning(f"WARNING ⚠️ failure for parse_version({version}), returning (0, 0, 0): {e}") + return 0, 0, 0 + + +def is_ascii(s) -> bool: + """ + Check if a string is composed of only ASCII characters. + + Args: + s (str): String to be checked. + + Returns: + (bool): True if the string is composed only of ASCII characters, False otherwise. + """ + # Convert list, tuple, None, etc. to string + s = str(s) + + # Check if the string is composed of only ASCII characters + return all(ord(c) < 128 for c in s) + + +def check_imgsz(imgsz, stride=32, min_dim=1, max_dim=2, floor=0): + """ + Verify image size is a multiple of the given stride in each dimension. If the image size is not a multiple of the + stride, update it to the nearest multiple of the stride that is greater than or equal to the given floor value. + + Args: + imgsz (int | cList[int]): Image size. + stride (int): Stride value. + min_dim (int): Minimum number of dimensions. + max_dim (int): Maximum number of dimensions. + floor (int): Minimum allowed value for image size. + + Returns: + (List[int]): Updated image size. + """ + # Convert stride to integer if it is a tensor + stride = int(stride.max() if isinstance(stride, torch.Tensor) else stride) + + # Convert image size to list if it is an integer + if isinstance(imgsz, int): + imgsz = [imgsz] + elif isinstance(imgsz, (list, tuple)): + imgsz = list(imgsz) + elif isinstance(imgsz, str): # i.e. '640' or '[640,640]' + imgsz = [int(imgsz)] if imgsz.isnumeric() else eval(imgsz) + else: + raise TypeError( + f"'imgsz={imgsz}' is of invalid type {type(imgsz).__name__}. " + f"Valid imgsz types are int i.e. 'imgsz=640' or list i.e. 'imgsz=[640,640]'" + ) + + # Apply max_dim + if len(imgsz) > max_dim: + msg = ( + "'train' and 'val' imgsz must be an integer, while 'predict' and 'export' imgsz may be a [h, w] list " + "or an integer, i.e. 'yolo export imgsz=640,480' or 'yolo export imgsz=640'" + ) + if max_dim != 1: + raise ValueError(f"imgsz={imgsz} is not a valid image size. {msg}") + LOGGER.warning(f"WARNING ⚠️ updating to 'imgsz={max(imgsz)}'. {msg}") + imgsz = [max(imgsz)] + # Make image size a multiple of the stride + sz = [max(math.ceil(x / stride) * stride, floor) for x in imgsz] + + # Print warning message if image size was updated + if sz != imgsz: + LOGGER.warning(f"WARNING ⚠️ imgsz={imgsz} must be multiple of max stride {stride}, updating to {sz}") + + # Add missing dimensions if necessary + sz = [sz[0], sz[0]] if min_dim == 2 and len(sz) == 1 else sz[0] if min_dim == 1 and len(sz) == 1 else sz + + return sz + + +def check_version( + current: str = "0.0.0", + required: str = "0.0.0", + name: str = "version", + hard: bool = False, + verbose: bool = False, + msg: str = "", +) -> bool: + """ + Check current version against the required version or range. + + Args: + current (str): Current version or package name to get version from. + required (str): Required version or range (in pip-style format). + name (str, optional): Name to be used in warning message. + hard (bool, optional): If True, raise an AssertionError if the requirement is not met. + verbose (bool, optional): If True, print warning message if requirement is not met. + msg (str, optional): Extra message to display if verbose. + + Returns: + (bool): True if requirement is met, False otherwise. + + Example: + ```python + # Check if current version is exactly 22.04 + check_version(current='22.04', required='==22.04') + + # Check if current version is greater than or equal to 22.04 + check_version(current='22.10', required='22.04') # assumes '>=' inequality if none passed + + # Check if current version is less than or equal to 22.04 + check_version(current='22.04', required='<=22.04') + + # Check if current version is between 20.04 (inclusive) and 22.04 (exclusive) + check_version(current='21.10', required='>20.04,<22.04') + ``` + """ + if not current: # if current is '' or None + LOGGER.warning(f"WARNING ⚠️ invalid check_version({current}, {required}) requested, please check values.") + return True + elif not current[0].isdigit(): # current is package name rather than version string, i.e. current='ultralytics' + try: + name = current # assigned package name to 'name' arg + current = metadata.version(current) # get version string from package name + except metadata.PackageNotFoundError as e: + if hard: + raise ModuleNotFoundError(emojis(f"WARNING ⚠️ {current} package is required but not installed")) from e + else: + return False + + if not required: # if required is '' or None + return True + + op = "" + version = "" + result = True + c = parse_version(current) # '1.2.3' -> (1, 2, 3) + for r in required.strip(",").split(","): + op, version = re.match(r"([^0-9]*)([\d.]+)", r).groups() # split '>=22.04' -> ('>=', '22.04') + v = parse_version(version) # '1.2.3' -> (1, 2, 3) + if op == "==" and c != v: + result = False + elif op == "!=" and c == v: + result = False + elif op in {">=", ""} and not (c >= v): # if no constraint passed assume '>=required' + result = False + elif op == "<=" and not (c <= v): + result = False + elif op == ">" and not (c > v): + result = False + elif op == "<" and not (c < v): + result = False + if not result: + warning = f"WARNING ⚠️ {name}{op}{version} is required, but {name}=={current} is currently installed {msg}" + if hard: + raise ModuleNotFoundError(emojis(warning)) # assert version requirements met + if verbose: + LOGGER.warning(warning) + return result + + +def check_latest_pypi_version(package_name="vsensebox-ultralytics"): + """ + Returns the latest version of a PyPI package without downloading or installing it. + + Parameters: + package_name (str): The name of the package to find the latest version for. + + Returns: + (str): The latest version of the package. + """ + if package_name == 'vsensebox-ultralytics': + with contextlib.suppress(Exception): + requests.packages.urllib3.disable_warnings() # Disable the InsecureRequestWarning + response = requests.get(f'https://pypi.org/pypi/{package_name}/json', timeout=3) + if response.status_code == 200: + return response.json()['info']['version'] + else: + LOGGER.info( + f'This is custom vsensebox-ultralytics for VsenseBox 😃 ' + f"🌐 Check for the update here: https://github.com/rathaumons/ultralytics-for-vsensebox") + return None + + +def check_pip_update_available(): + """ + Checks if a new version of the ultralytics package is available on PyPI. + + Returns: + (bool): True if an update is available, False otherwise. + """ + if ONLINE and IS_PIP_PACKAGE: + with contextlib.suppress(Exception): + from ultralytics import __version__ + + latest = check_latest_pypi_version() + if check_version(__version__, f"<{latest}"): # check if current version is < latest version + LOGGER.info( + f"New https://pypi.org/project/vsensebox-ultralytics/{latest} available 😃 " + f"Update with 'pip install -U vsensebox-ultralytics'" + ) + return True + return False + + +@ThreadingLocked() +def check_font(font="Arial.ttf"): + """ + Find font locally or download to user's configuration directory if it does not already exist. + + Args: + font (str): Path or name of font. + + Returns: + file (Path): Resolved font file path. + """ + from matplotlib import font_manager + + # Check USER_CONFIG_DIR + name = Path(font).name + file = USER_CONFIG_DIR / name + if file.exists(): + return file + + # Check system fonts + matches = [s for s in font_manager.findSystemFonts() if font in s] + if any(matches): + return matches[0] + + # Download to USER_CONFIG_DIR if missing + url = f"https://ultralytics.com/assets/{name}" + if downloads.is_url(url, check=True): + downloads.safe_download(url=url, file=file) + return file + + +def check_python(minimum: str = "3.8.0") -> bool: + """ + Check current python version against the required minimum version. + + Args: + minimum (str): Required minimum version of python. + + Returns: + (bool): Whether the installed Python version meets the minimum constraints. + """ + return check_version(PYTHON_VERSION, minimum, name="Python ", hard=True) + + +@TryExcept() +def check_requirements(requirements=ROOT.parent / "requirements.txt", exclude=(), install=True, cmds=""): + """ + Check if installed dependencies meet YOLOv8 requirements and attempt to auto-update if needed. + + Args: + requirements (Union[Path, str, List[str]]): Path to a requirements.txt file, a single package requirement as a + string, or a list of package requirements as strings. + exclude (Tuple[str]): Tuple of package names to exclude from checking. + install (bool): If True, attempt to auto-update packages that don't meet requirements. + cmds (str): Additional commands to pass to the pip install command when auto-updating. + + Example: + ```python + from ultralytics.utils.checks import check_requirements + + # Check a requirements.txt file + check_requirements('path/to/requirements.txt') + + # Check a single package + check_requirements('ultralytics>=8.0.0') + + # Check multiple packages + check_requirements(['numpy', 'ultralytics>=8.0.0']) + ``` + """ + + prefix = colorstr("red", "bold", "requirements:") + check_python() # check python version + check_torchvision() # check torch-torchvision compatibility + if isinstance(requirements, Path): # requirements.txt file + file = requirements.resolve() + assert file.exists(), f"{prefix} {file} not found, check failed." + requirements = [f"{x.name}{x.specifier}" for x in parse_requirements(file) if x.name not in exclude] + elif isinstance(requirements, str): + requirements = [requirements] + + pkgs = [] + for r in requirements: + r_stripped = r.split("/")[-1].replace(".git", "") # replace git+https://org/repo.git -> 'repo' + match = re.match(r"([a-zA-Z0-9-_]+)([<>!=~]+.*)?", r_stripped) + name, required = match[1], match[2].strip() if match[2] else "" + try: + assert check_version(metadata.version(name), required) # exception if requirements not met + except (AssertionError, metadata.PackageNotFoundError): + pkgs.append(r) + + s = " ".join(f'"{x}"' for x in pkgs) # console string + if s: + if install and AUTOINSTALL: # check environment variable + n = len(pkgs) # number of packages updates + LOGGER.info(f"{prefix} Ultralytics requirement{'s' * (n > 1)} {pkgs} not found, attempting AutoUpdate...") + try: + t = time.time() + assert ONLINE, "AutoUpdate skipped (offline)" + with Retry(times=2, delay=1): # run up to 2 times with 1-second retry delay + LOGGER.info(subprocess.check_output(f"pip install --no-cache {s} {cmds}", shell=True).decode()) + dt = time.time() - t + LOGGER.info( + f"{prefix} AutoUpdate success ✅ {dt:.1f}s, installed {n} package{'s' * (n > 1)}: {pkgs}\n" + f"{prefix} ⚠️ {colorstr('bold', 'Restart runtime or rerun command for updates to take effect')}\n" + ) + except Exception as e: + LOGGER.warning(f"{prefix} ❌ {e}") + return False + else: + return False + + return True + + +def check_torchvision(): + """ + Checks the installed versions of PyTorch and Torchvision to ensure they're compatible. + + This function checks the installed versions of PyTorch and Torchvision, and warns if they're incompatible according + to the provided compatibility table based on: + https://github.com/pytorch/vision#installation. + + The compatibility table is a dictionary where the keys are PyTorch versions and the values are lists of compatible + Torchvision versions. + """ + + # Compatibility table + compatibility_table = {"2.0": ["0.15"], "1.13": ["0.14"], "1.12": ["0.13"]} + + # Extract only the major and minor versions + v_torch = ".".join(torch.__version__.split("+")[0].split(".")[:2]) + v_torchvision = ".".join(TORCHVISION_VERSION.split("+")[0].split(".")[:2]) + + if v_torch in compatibility_table: + compatible_versions = compatibility_table[v_torch] + if all(v_torchvision != v for v in compatible_versions): + print( + f"WARNING ⚠️ torchvision=={v_torchvision} is incompatible with torch=={v_torch}.\n" + f"Run 'pip install torchvision=={compatible_versions[0]}' to fix torchvision or " + "'pip install -U torch torchvision' to update both.\n" + "For a full compatibility table see https://github.com/pytorch/vision#installation" + ) + + +def check_suffix(file="yolov8n.pt", suffix=".pt", msg=""): + """Check file(s) for acceptable suffix.""" + if file and suffix: + if isinstance(suffix, str): + suffix = (suffix,) + for f in file if isinstance(file, (list, tuple)) else [file]: + s = Path(f).suffix.lower().strip() # file suffix + if len(s): + assert s in suffix, f"{msg}{f} acceptable suffix is {suffix}, not {s}" + + +def check_yolov5u_filename(file: str, verbose: bool = True): + """Replace legacy YOLOv5 filenames with updated YOLOv5u filenames.""" + if "yolov3" in file or "yolov5" in file: + if "u.yaml" in file: + file = file.replace("u.yaml", ".yaml") # i.e. yolov5nu.yaml -> yolov5n.yaml + elif ".pt" in file and "u" not in file: + original_file = file + file = re.sub(r"(.*yolov5([nsmlx]))\.pt", "\\1u.pt", file) # i.e. yolov5n.pt -> yolov5nu.pt + file = re.sub(r"(.*yolov5([nsmlx])6)\.pt", "\\1u.pt", file) # i.e. yolov5n6.pt -> yolov5n6u.pt + file = re.sub(r"(.*yolov3(|-tiny|-spp))\.pt", "\\1u.pt", file) # i.e. yolov3-spp.pt -> yolov3-sppu.pt + if file != original_file and verbose: + LOGGER.info( + f"PRO TIP 💡 Replace 'model={original_file}' with new 'model={file}'.\nYOLOv5 'u' models are " + f"trained with https://github.com/ultralytics/ultralytics and feature improved performance vs " + f"standard YOLOv5 models trained with https://github.com/ultralytics/yolov5.\n" + ) + return file + + +def check_model_file_from_stem(model="yolov8n"): + """Return a model filename from a valid model stem.""" + if model and not Path(model).suffix and Path(model).stem in downloads.GITHUB_ASSETS_STEMS: + return Path(model).with_suffix(".pt") # add suffix, i.e. yolov8n -> yolov8n.pt + else: + return model + + +def check_file(file, suffix="", download=True, hard=True): + """Search/download file (if necessary) and return path.""" + check_suffix(file, suffix) # optional + file = str(file).strip() # convert to string and strip spaces + file = check_yolov5u_filename(file) # yolov5n -> yolov5nu + if ( + not file + or ("://" not in file and Path(file).exists()) # '://' check required in Windows Python<3.10 + or file.lower().startswith("grpc://") + ): # file exists or gRPC Triton images + return file + elif download and file.lower().startswith(("https://", "http://", "rtsp://", "rtmp://", "tcp://")): # download + url = file # warning: Pathlib turns :// -> :/ + file = url2file(file) # '%2F' to '/', split https://url.com/file.txt?auth + if Path(file).exists(): + LOGGER.info(f"Found {clean_url(url)} locally at {file}") # file already exists + else: + downloads.safe_download(url=url, file=file, unzip=False) + return file + else: # search + files = glob.glob(str(ROOT / "**" / file), recursive=True) or glob.glob(str(ROOT.parent / file)) # find file + if not files and hard: + raise FileNotFoundError(f"'{file}' does not exist") + elif len(files) > 1 and hard: + raise FileNotFoundError(f"Multiple files match '{file}', specify exact path: {files}") + return files[0] if len(files) else [] # return file + + +def check_yaml(file, suffix=(".yaml", ".yml"), hard=True): + """Search/download YAML file (if necessary) and return path, checking suffix.""" + return check_file(file, suffix, hard=hard) + + +def check_is_path_safe(basedir, path): + """ + Check if the resolved path is under the intended directory to prevent path traversal. + + Args: + basedir (Path | str): The intended directory. + path (Path | str): The path to check. + + Returns: + (bool): True if the path is safe, False otherwise. + """ + base_dir_resolved = Path(basedir).resolve() + path_resolved = Path(path).resolve() + + return path_resolved.is_file() and path_resolved.parts[: len(base_dir_resolved.parts)] == base_dir_resolved.parts + + +def check_imshow(warn=False): + """Check if environment supports image displays.""" + try: + if LINUX: + assert "DISPLAY" in os.environ and not IS_DOCKER and not IS_COLAB and not IS_KAGGLE + cv2.imshow("test", np.zeros((8, 8, 3), dtype=np.uint8)) # show a small 8-pixel image + cv2.waitKey(1) + cv2.destroyAllWindows() + cv2.waitKey(1) + return True + except Exception as e: + if warn: + LOGGER.warning(f"WARNING ⚠️ Environment does not support cv2.imshow() or PIL Image.show()\n{e}") + return False + + +def check_yolo(verbose=True, device=""): + """Return a human-readable YOLO software and hardware summary.""" + import psutil + + from ultralytics.utils.torch_utils import select_device + + if IS_JUPYTER: + if check_requirements("wandb", install=False): + os.system("pip uninstall -y wandb") # uninstall wandb: unwanted account creation prompt with infinite hang + if IS_COLAB: + shutil.rmtree("sample_data", ignore_errors=True) # remove colab /sample_data directory + + if verbose: + # System info + gib = 1 << 30 # bytes per GiB + ram = psutil.virtual_memory().total + total, used, free = shutil.disk_usage("/") + s = f"({os.cpu_count()} CPUs, {ram / gib:.1f} GB RAM, {(total - free) / gib:.1f}/{total / gib:.1f} GB disk)" + with contextlib.suppress(Exception): # clear display if ipython is installed + from IPython import display + + display.clear_output() + else: + s = "" + + select_device(device=device, newline=False) + LOGGER.info(f"Setup complete ✅ {s}") + + +def collect_system_info(): + """Collect and print relevant system information including OS, Python, RAM, CPU, and CUDA.""" + + import psutil + + from ultralytics.utils import ENVIRONMENT, IS_GIT_DIR + from ultralytics.utils.torch_utils import get_cpu_info + + ram_info = psutil.virtual_memory().total / (1024**3) # Convert bytes to GB + check_yolo() + LOGGER.info( + f"\n{'OS':<20}{platform.platform()}\n" + f"{'Environment':<20}{ENVIRONMENT}\n" + f"{'Python':<20}{PYTHON_VERSION}\n" + f"{'Install':<20}{'git' if IS_GIT_DIR else 'pip' if IS_PIP_PACKAGE else 'other'}\n" + f"{'RAM':<20}{ram_info:.2f} GB\n" + f"{'CPU':<20}{get_cpu_info()}\n" + f"{'CUDA':<20}{torch.version.cuda if torch and torch.cuda.is_available() else None}\n" + ) + + for r in parse_requirements(package="ultralytics"): + try: + current = metadata.version(r.name) + is_met = "✅ " if check_version(current, str(r.specifier), hard=True) else "❌ " + except metadata.PackageNotFoundError: + current = "(not installed)" + is_met = "❌ " + LOGGER.info(f"{r.name:<20}{is_met}{current}{r.specifier}") + + if is_github_action_running(): + LOGGER.info( + f"\nRUNNER_OS: {os.getenv('RUNNER_OS')}\n" + f"GITHUB_EVENT_NAME: {os.getenv('GITHUB_EVENT_NAME')}\n" + f"GITHUB_WORKFLOW: {os.getenv('GITHUB_WORKFLOW')}\n" + f"GITHUB_ACTOR: {os.getenv('GITHUB_ACTOR')}\n" + f"GITHUB_REPOSITORY: {os.getenv('GITHUB_REPOSITORY')}\n" + f"GITHUB_REPOSITORY_OWNER: {os.getenv('GITHUB_REPOSITORY_OWNER')}\n" + ) + + +def check_amp(model): + """ + This function checks the PyTorch Automatic Mixed Precision (AMP) functionality of a YOLOv8 model. If the checks + fail, it means there are anomalies with AMP on the system that may cause NaN losses or zero-mAP results, so AMP will + be disabled during training. + + Args: + model (nn.Module): A YOLOv8 model instance. + + Example: + ```python + from ultralytics import YOLO + from ultralytics.utils.checks import check_amp + + model = YOLO('yolov8n.pt').model.cuda() + check_amp(model) + ``` + + Returns: + (bool): Returns True if the AMP functionality works correctly with YOLOv8 model, else False. + """ + device = next(model.parameters()).device # get model device + if device.type in {"cpu", "mps"}: + return False # AMP only used on CUDA devices + + def amp_allclose(m, im): + """All close FP32 vs AMP results.""" + a = m(im, device=device, verbose=False)[0].boxes.data # FP32 inference + with torch.cuda.amp.autocast(True): + b = m(im, device=device, verbose=False)[0].boxes.data # AMP inference + del m + return a.shape == b.shape and torch.allclose(a, b.float(), atol=0.5) # close to 0.5 absolute tolerance + + im = ASSETS / "bus.jpg" # image to check + prefix = colorstr("AMP: ") + LOGGER.info(f"{prefix}running Automatic Mixed Precision (AMP) checks with YOLOv8n...") + warning_msg = "Setting 'amp=True'. If you experience zero-mAP or NaN losses you can disable AMP with amp=False." + try: + from ultralytics import YOLO + + assert amp_allclose(YOLO("yolov8n.pt"), im) + LOGGER.info(f"{prefix}checks passed ✅") + except ConnectionError: + LOGGER.warning(f"{prefix}checks skipped ⚠️, offline and unable to download YOLOv8n. {warning_msg}") + except (AttributeError, ModuleNotFoundError): + LOGGER.warning( + f"{prefix}checks skipped ⚠️. " + f"Unable to load YOLOv8n due to possible Ultralytics package modifications. {warning_msg}" + ) + except AssertionError: + LOGGER.warning( + f"{prefix}checks failed ❌. Anomalies were detected with AMP on your system that may lead to " + f"NaN losses or zero-mAP results, so AMP will be disabled during training." + ) + return False + return True + + +def git_describe(path=ROOT): # path must be a directory + """Return human-readable git description, i.e. v5.0-5-g3e25f1e https://git-scm.com/docs/git-describe.""" + with contextlib.suppress(Exception): + return subprocess.check_output(f"git -C {path} describe --tags --long --always", shell=True).decode()[:-1] + return "" + + +def print_args(args: Optional[dict] = None, show_file=True, show_func=False): + """Print function arguments (optional args dict).""" + + def strip_auth(v): + """Clean longer Ultralytics HUB URLs by stripping potential authentication information.""" + return clean_url(v) if (isinstance(v, str) and v.startswith("http") and len(v) > 100) else v + + x = inspect.currentframe().f_back # previous frame + file, _, func, _, _ = inspect.getframeinfo(x) + if args is None: # get args automatically + args, _, _, frm = inspect.getargvalues(x) + args = {k: v for k, v in frm.items() if k in args} + try: + file = Path(file).resolve().relative_to(ROOT).with_suffix("") + except ValueError: + file = Path(file).stem + s = (f"{file}: " if show_file else "") + (f"{func}: " if show_func else "") + LOGGER.info(colorstr(s) + ", ".join(f"{k}={strip_auth(v)}" for k, v in args.items())) + + +def cuda_device_count() -> int: + """ + Get the number of NVIDIA GPUs available in the environment. + + Returns: + (int): The number of NVIDIA GPUs available. + """ + try: + # Run the nvidia-smi command and capture its output + output = subprocess.check_output( + ["nvidia-smi", "--query-gpu=count", "--format=csv,noheader,nounits"], encoding="utf-8" + ) + + # Take the first line and strip any leading/trailing white space + first_line = output.strip().split("\n")[0] + + return int(first_line) + except (subprocess.CalledProcessError, FileNotFoundError, ValueError): + # If the command fails, nvidia-smi is not found, or output is not an integer, assume no GPUs are available + return 0 + + +def cuda_is_available() -> bool: + """ + Check if CUDA is available in the environment. + + Returns: + (bool): True if one or more NVIDIA GPUs are available, False otherwise. + """ + return cuda_device_count() > 0 + + +# Define constants +IS_PYTHON_3_12 = PYTHON_VERSION.startswith("3.12") diff --git a/ultralytics/utils/dist.py b/ultralytics/utils/dist.py new file mode 100644 index 0000000..b669e52 --- /dev/null +++ b/ultralytics/utils/dist.py @@ -0,0 +1,71 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import os +import shutil +import socket +import sys +import tempfile + +from . import USER_CONFIG_DIR +from .torch_utils import TORCH_1_9 + + +def find_free_network_port() -> int: + """ + Finds a free port on localhost. + + It is useful in single-node training when we don't want to connect to a real main node but have to set the + `MASTER_PORT` environment variable. + """ + with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s: + s.bind(("127.0.0.1", 0)) + return s.getsockname()[1] # port + + +def generate_ddp_file(trainer): + """Generates a DDP file and returns its file name.""" + module, name = f"{trainer.__class__.__module__}.{trainer.__class__.__name__}".rsplit(".", 1) + + content = f""" +# Ultralytics Multi-GPU training temp file (should be automatically deleted after use) +overrides = {vars(trainer.args)} + +if __name__ == "__main__": + from {module} import {name} + from ultralytics.utils import DEFAULT_CFG_DICT + + cfg = DEFAULT_CFG_DICT.copy() + cfg.update(save_dir='') # handle the extra key 'save_dir' + trainer = {name}(cfg=cfg, overrides=overrides) + results = trainer.train() +""" + (USER_CONFIG_DIR / "DDP").mkdir(exist_ok=True) + with tempfile.NamedTemporaryFile( + prefix="_temp_", + suffix=f"{id(trainer)}.py", + mode="w+", + encoding="utf-8", + dir=USER_CONFIG_DIR / "DDP", + delete=False, + ) as file: + file.write(content) + return file.name + + +def generate_ddp_command(world_size, trainer): + """Generates and returns command for distributed training.""" + import __main__ # noqa local import to avoid https://github.com/Lightning-AI/lightning/issues/15218 + + if not trainer.resume: + shutil.rmtree(trainer.save_dir) # remove the save_dir + file = generate_ddp_file(trainer) + dist_cmd = "torch.distributed.run" if TORCH_1_9 else "torch.distributed.launch" + port = find_free_network_port() + cmd = [sys.executable, "-m", dist_cmd, "--nproc_per_node", f"{world_size}", "--master_port", f"{port}", file] + return cmd, file + + +def ddp_cleanup(trainer, file): + """Delete temp file if created.""" + if f"{id(trainer)}.py" in file: # if temp_file suffix in file + os.remove(file) diff --git a/ultralytics/utils/downloads.py b/ultralytics/utils/downloads.py new file mode 100644 index 0000000..f24bd3b --- /dev/null +++ b/ultralytics/utils/downloads.py @@ -0,0 +1,500 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import contextlib +import re +import shutil +import subprocess +from itertools import repeat +from multiprocessing.pool import ThreadPool +from pathlib import Path +from urllib import parse, request + +import requests +import torch + +from ultralytics.utils import LOGGER, TQDM, checks, clean_url, emojis, is_online, url2file + +# Define Ultralytics GitHub assets maintained at https://github.com/ultralytics/assets +GITHUB_ASSETS_REPO = "ultralytics/assets" +GITHUB_ASSETS_NAMES = ( + [f"yolov8{k}{suffix}.pt" for k in "nsmlx" for suffix in ("", "-cls", "-seg", "-pose", "-obb")] + + [f"yolov5{k}{resolution}u.pt" for k in "nsmlx" for resolution in ("", "6")] + + [f"yolov3{k}u.pt" for k in ("", "-spp", "-tiny")] + + [f"yolov8{k}-world.pt" for k in "smlx"] + + [f"yolov8{k}-worldv2.pt" for k in "smlx"] + + [f"yolov9{k}.pt" for k in "ce"] + + [f"yolo_nas_{k}.pt" for k in "sml"] + + [f"sam_{k}.pt" for k in "bl"] + + [f"FastSAM-{k}.pt" for k in "sx"] + + [f"rtdetr-{k}.pt" for k in "lx"] + + ["mobile_sam.pt"] + + ["calibration_image_sample_data_20x128x128x3_float32.npy.zip"] +) +GITHUB_ASSETS_STEMS = [Path(k).stem for k in GITHUB_ASSETS_NAMES] + + +def is_url(url, check=False): + """ + Validates if the given string is a URL and optionally checks if the URL exists online. + + Args: + url (str): The string to be validated as a URL. + check (bool, optional): If True, performs an additional check to see if the URL exists online. + Defaults to True. + + Returns: + (bool): Returns True for a valid URL. If 'check' is True, also returns True if the URL exists online. + Returns False otherwise. + + Example: + ```python + valid = is_url("https://www.example.com") + ``` + """ + with contextlib.suppress(Exception): + url = str(url) + result = parse.urlparse(url) + assert all([result.scheme, result.netloc]) # check if is url + if check: + with request.urlopen(url) as response: + return response.getcode() == 200 # check if exists online + return True + return False + + +def delete_dsstore(path, files_to_delete=(".DS_Store", "__MACOSX")): + """ + Deletes all ".DS_store" files under a specified directory. + + Args: + path (str, optional): The directory path where the ".DS_store" files should be deleted. + files_to_delete (tuple): The files to be deleted. + + Example: + ```python + from ultralytics.utils.downloads import delete_dsstore + + delete_dsstore('path/to/dir') + ``` + + Note: + ".DS_store" files are created by the Apple operating system and contain metadata about folders and files. They + are hidden system files and can cause issues when transferring files between different operating systems. + """ + for file in files_to_delete: + matches = list(Path(path).rglob(file)) + LOGGER.info(f"Deleting {file} files: {matches}") + for f in matches: + f.unlink() + + +def zip_directory(directory, compress=True, exclude=(".DS_Store", "__MACOSX"), progress=True): + """ + Zips the contents of a directory, excluding files containing strings in the exclude list. The resulting zip file is + named after the directory and placed alongside it. + + Args: + directory (str | Path): The path to the directory to be zipped. + compress (bool): Whether to compress the files while zipping. Default is True. + exclude (tuple, optional): A tuple of filename strings to be excluded. Defaults to ('.DS_Store', '__MACOSX'). + progress (bool, optional): Whether to display a progress bar. Defaults to True. + + Returns: + (Path): The path to the resulting zip file. + + Example: + ```python + from ultralytics.utils.downloads import zip_directory + + file = zip_directory('path/to/dir') + ``` + """ + from zipfile import ZIP_DEFLATED, ZIP_STORED, ZipFile + + delete_dsstore(directory) + directory = Path(directory) + if not directory.is_dir(): + raise FileNotFoundError(f"Directory '{directory}' does not exist.") + + # Unzip with progress bar + files_to_zip = [f for f in directory.rglob("*") if f.is_file() and all(x not in f.name for x in exclude)] + zip_file = directory.with_suffix(".zip") + compression = ZIP_DEFLATED if compress else ZIP_STORED + with ZipFile(zip_file, "w", compression) as f: + for file in TQDM(files_to_zip, desc=f"Zipping {directory} to {zip_file}...", unit="file", disable=not progress): + f.write(file, file.relative_to(directory)) + + return zip_file # return path to zip file + + +def unzip_file(file, path=None, exclude=(".DS_Store", "__MACOSX"), exist_ok=False, progress=True): + """ + Unzips a *.zip file to the specified path, excluding files containing strings in the exclude list. + + If the zipfile does not contain a single top-level directory, the function will create a new + directory with the same name as the zipfile (without the extension) to extract its contents. + If a path is not provided, the function will use the parent directory of the zipfile as the default path. + + Args: + file (str): The path to the zipfile to be extracted. + path (str, optional): The path to extract the zipfile to. Defaults to None. + exclude (tuple, optional): A tuple of filename strings to be excluded. Defaults to ('.DS_Store', '__MACOSX'). + exist_ok (bool, optional): Whether to overwrite existing contents if they exist. Defaults to False. + progress (bool, optional): Whether to display a progress bar. Defaults to True. + + Raises: + BadZipFile: If the provided file does not exist or is not a valid zipfile. + + Returns: + (Path): The path to the directory where the zipfile was extracted. + + Example: + ```python + from ultralytics.utils.downloads import unzip_file + + dir = unzip_file('path/to/file.zip') + ``` + """ + from zipfile import BadZipFile, ZipFile, is_zipfile + + if not (Path(file).exists() and is_zipfile(file)): + raise BadZipFile(f"File '{file}' does not exist or is a bad zip file.") + if path is None: + path = Path(file).parent # default path + + # Unzip the file contents + with ZipFile(file) as zipObj: + files = [f for f in zipObj.namelist() if all(x not in f for x in exclude)] + top_level_dirs = {Path(f).parts[0] for f in files} + + if len(top_level_dirs) > 1 or (len(files) > 1 and not files[0].endswith("/")): + # Zip has multiple files at top level + path = extract_path = Path(path) / Path(file).stem # i.e. ../datasets/coco8 + else: + # Zip has 1 top-level directory + extract_path = path # i.e. ../datasets + path = Path(path) / list(top_level_dirs)[0] # i.e. ../datasets/coco8 + + # Check if destination directory already exists and contains files + if path.exists() and any(path.iterdir()) and not exist_ok: + # If it exists and is not empty, return the path without unzipping + LOGGER.warning(f"WARNING ⚠️ Skipping {file} unzip as destination directory {path} is not empty.") + return path + + for f in TQDM(files, desc=f"Unzipping {file} to {Path(path).resolve()}...", unit="file", disable=not progress): + # Ensure the file is within the extract_path to avoid path traversal security vulnerability + if ".." in Path(f).parts: + LOGGER.warning(f"Potentially insecure file path: {f}, skipping extraction.") + continue + zipObj.extract(f, extract_path) + + return path # return unzip dir + + +def check_disk_space(url="https://ultralytics.com/assets/coco128.zip", path=Path.cwd(), sf=1.5, hard=True): + """ + Check if there is sufficient disk space to download and store a file. + + Args: + url (str, optional): The URL to the file. Defaults to 'https://ultralytics.com/assets/coco128.zip'. + path (str | Path, optional): The path or drive to check the available free space on. + sf (float, optional): Safety factor, the multiplier for the required free space. Defaults to 2.0. + hard (bool, optional): Whether to throw an error or not on insufficient disk space. Defaults to True. + + Returns: + (bool): True if there is sufficient disk space, False otherwise. + """ + try: + r = requests.head(url) # response + assert r.status_code < 400, f"URL error for {url}: {r.status_code} {r.reason}" # check response + except Exception: + return True # requests issue, default to True + + # Check file size + gib = 1 << 30 # bytes per GiB + data = int(r.headers.get("Content-Length", 0)) / gib # file size (GB) + total, used, free = (x / gib for x in shutil.disk_usage(path)) # bytes + + if data * sf < free: + return True # sufficient space + + # Insufficient space + text = ( + f"WARNING ⚠️ Insufficient free disk space {free:.1f} GB < {data * sf:.3f} GB required, " + f"Please free {data * sf - free:.1f} GB additional disk space and try again." + ) + if hard: + raise MemoryError(text) + LOGGER.warning(text) + return False + + +def get_google_drive_file_info(link): + """ + Retrieves the direct download link and filename for a shareable Google Drive file link. + + Args: + link (str): The shareable link of the Google Drive file. + + Returns: + (str): Direct download URL for the Google Drive file. + (str): Original filename of the Google Drive file. If filename extraction fails, returns None. + + Example: + ```python + from ultralytics.utils.downloads import get_google_drive_file_info + + link = "https://drive.google.com/file/d/1cqT-cJgANNrhIHCrEufUYhQ4RqiWG_lJ/view?usp=drive_link" + url, filename = get_google_drive_file_info(link) + ``` + """ + file_id = link.split("/d/")[1].split("/view")[0] + drive_url = f"https://drive.google.com/uc?export=download&id={file_id}" + filename = None + + # Start session + with requests.Session() as session: + response = session.get(drive_url, stream=True) + if "quota exceeded" in str(response.content.lower()): + raise ConnectionError( + emojis( + f"❌ Google Drive file download quota exceeded. " + f"Please try again later or download this file manually at {link}." + ) + ) + for k, v in response.cookies.items(): + if k.startswith("download_warning"): + drive_url += f"&confirm={v}" # v is token + cd = response.headers.get("content-disposition") + if cd: + filename = re.findall('filename="(.+)"', cd)[0] + return drive_url, filename + + +def safe_download( + url, + file=None, + dir=None, + unzip=True, + delete=False, + curl=False, + retry=3, + min_bytes=1e0, + exist_ok=False, + progress=True, +): + """ + Downloads files from a URL, with options for retrying, unzipping, and deleting the downloaded file. + + Args: + url (str): The URL of the file to be downloaded. + file (str, optional): The filename of the downloaded file. + If not provided, the file will be saved with the same name as the URL. + dir (str, optional): The directory to save the downloaded file. + If not provided, the file will be saved in the current working directory. + unzip (bool, optional): Whether to unzip the downloaded file. Default: True. + delete (bool, optional): Whether to delete the downloaded file after unzipping. Default: False. + curl (bool, optional): Whether to use curl command line tool for downloading. Default: False. + retry (int, optional): The number of times to retry the download in case of failure. Default: 3. + min_bytes (float, optional): The minimum number of bytes that the downloaded file should have, to be considered + a successful download. Default: 1E0. + exist_ok (bool, optional): Whether to overwrite existing contents during unzipping. Defaults to False. + progress (bool, optional): Whether to display a progress bar during the download. Default: True. + + Example: + ```python + from ultralytics.utils.downloads import safe_download + + link = "https://ultralytics.com/assets/bus.jpg" + path = safe_download(link) + ``` + """ + gdrive = url.startswith("https://drive.google.com/") # check if the URL is a Google Drive link + if gdrive: + url, file = get_google_drive_file_info(url) + + f = Path(dir or ".") / (file or url2file(url)) # URL converted to filename + if "://" not in str(url) and Path(url).is_file(): # URL exists ('://' check required in Windows Python<3.10) + f = Path(url) # filename + elif not f.is_file(): # URL and file do not exist + desc = f"Downloading {url if gdrive else clean_url(url)} to '{f}'" + LOGGER.info(f"{desc}...") + f.parent.mkdir(parents=True, exist_ok=True) # make directory if missing + check_disk_space(url, path=f.parent) + for i in range(retry + 1): + try: + if curl or i > 0: # curl download with retry, continue + s = "sS" * (not progress) # silent + r = subprocess.run(["curl", "-#", f"-{s}L", url, "-o", f, "--retry", "3", "-C", "-"]).returncode + assert r == 0, f"Curl return value {r}" + else: # urllib download + method = "torch" + if method == "torch": + torch.hub.download_url_to_file(url, f, progress=progress) + else: + with request.urlopen(url) as response, TQDM( + total=int(response.getheader("Content-Length", 0)), + desc=desc, + disable=not progress, + unit="B", + unit_scale=True, + unit_divisor=1024, + ) as pbar: + with open(f, "wb") as f_opened: + for data in response: + f_opened.write(data) + pbar.update(len(data)) + + if f.exists(): + if f.stat().st_size > min_bytes: + break # success + f.unlink() # remove partial downloads + except Exception as e: + if i == 0 and not is_online(): + raise ConnectionError(emojis(f"❌ Download failure for {url}. Environment is not online.")) from e + elif i >= retry: + raise ConnectionError(emojis(f"❌ Download failure for {url}. Retry limit reached.")) from e + LOGGER.warning(f"⚠️ Download failure, retrying {i + 1}/{retry} {url}...") + + if unzip and f.exists() and f.suffix in {"", ".zip", ".tar", ".gz"}: + from zipfile import is_zipfile + + unzip_dir = (dir or f.parent).resolve() # unzip to dir if provided else unzip in place + if is_zipfile(f): + unzip_dir = unzip_file(file=f, path=unzip_dir, exist_ok=exist_ok, progress=progress) # unzip + elif f.suffix in {".tar", ".gz"}: + LOGGER.info(f"Unzipping {f} to {unzip_dir}...") + subprocess.run(["tar", "xf" if f.suffix == ".tar" else "xfz", f, "--directory", unzip_dir], check=True) + if delete: + f.unlink() # remove zip + return unzip_dir + + +def get_github_assets(repo="ultralytics/assets", version="latest", retry=False): + """ + Retrieve the specified version's tag and assets from a GitHub repository. If the version is not specified, the + function fetches the latest release assets. + + Args: + repo (str, optional): The GitHub repository in the format 'owner/repo'. Defaults to 'ultralytics/assets'. + version (str, optional): The release version to fetch assets from. Defaults to 'latest'. + retry (bool, optional): Flag to retry the request in case of a failure. Defaults to False. + + Returns: + (tuple): A tuple containing the release tag and a list of asset names. + + Example: + ```python + tag, assets = get_github_assets(repo='ultralytics/assets', version='latest') + ``` + """ + + if version != "latest": + version = f"tags/{version}" # i.e. tags/v6.2 + url = f"https://api.github.com/repos/{repo}/releases/{version}" + r = requests.get(url) # github api + if r.status_code != 200 and r.reason != "rate limit exceeded" and retry: # failed and not 403 rate limit exceeded + r = requests.get(url) # try again + if r.status_code != 200: + LOGGER.warning(f"⚠️ GitHub assets check failure for {url}: {r.status_code} {r.reason}") + return "", [] + data = r.json() + return data["tag_name"], [x["name"] for x in data["assets"]] # tag, assets i.e. ['yolov8n.pt', 'yolov8s.pt', ...] + + +def attempt_download_asset(file, repo="ultralytics/assets", release="v8.1.0", **kwargs): + """ + Attempt to download a file from GitHub release assets if it is not found locally. The function checks for the file + locally first, then tries to download it from the specified GitHub repository release. + + Args: + file (str | Path): The filename or file path to be downloaded. + repo (str, optional): The GitHub repository in the format 'owner/repo'. Defaults to 'ultralytics/assets'. + release (str, optional): The specific release version to be downloaded. Defaults to 'v8.1.0'. + **kwargs (any): Additional keyword arguments for the download process. + + Returns: + (str): The path to the downloaded file. + + Example: + ```python + file_path = attempt_download_asset('yolov5s.pt', repo='ultralytics/assets', release='latest') + ``` + """ + from ultralytics.utils import SETTINGS # scoped for circular import + + # YOLOv3/5u updates + file = str(file) + file = checks.check_yolov5u_filename(file) + file = Path(file.strip().replace("'", "")) + if file.exists(): + return str(file) + elif (SETTINGS["weights_dir"] / file).exists(): + return str(SETTINGS["weights_dir"] / file) + else: + # URL specified + name = Path(parse.unquote(str(file))).name # decode '%2F' to '/' etc. + download_url = f"https://github.com/{repo}/releases/download" + if str(file).startswith(("http:/", "https:/")): # download + url = str(file).replace(":/", "://") # Pathlib turns :// -> :/ + file = url2file(name) # parse authentication https://url.com/file.txt?auth... + if Path(file).is_file(): + LOGGER.info(f"Found {clean_url(url)} locally at {file}") # file already exists + else: + safe_download(url=url, file=file, min_bytes=1e5, **kwargs) + + elif repo == GITHUB_ASSETS_REPO and name in GITHUB_ASSETS_NAMES: + safe_download(url=f"{download_url}/{release}/{name}", file=file, min_bytes=1e5, **kwargs) + + else: + tag, assets = get_github_assets(repo, release) + if not assets: + tag, assets = get_github_assets(repo) # latest release + if name in assets: + safe_download(url=f"{download_url}/{tag}/{name}", file=file, min_bytes=1e5, **kwargs) + + return str(file) + + +def download(url, dir=Path.cwd(), unzip=True, delete=False, curl=False, threads=1, retry=3, exist_ok=False): + """ + Downloads files from specified URLs to a given directory. Supports concurrent downloads if multiple threads are + specified. + + Args: + url (str | list): The URL or list of URLs of the files to be downloaded. + dir (Path, optional): The directory where the files will be saved. Defaults to the current working directory. + unzip (bool, optional): Flag to unzip the files after downloading. Defaults to True. + delete (bool, optional): Flag to delete the zip files after extraction. Defaults to False. + curl (bool, optional): Flag to use curl for downloading. Defaults to False. + threads (int, optional): Number of threads to use for concurrent downloads. Defaults to 1. + retry (int, optional): Number of retries in case of download failure. Defaults to 3. + exist_ok (bool, optional): Whether to overwrite existing contents during unzipping. Defaults to False. + + Example: + ```python + download('https://ultralytics.com/assets/example.zip', dir='path/to/dir', unzip=True) + ``` + """ + dir = Path(dir) + dir.mkdir(parents=True, exist_ok=True) # make directory + if threads > 1: + with ThreadPool(threads) as pool: + pool.map( + lambda x: safe_download( + url=x[0], + dir=x[1], + unzip=unzip, + delete=delete, + curl=curl, + retry=retry, + exist_ok=exist_ok, + progress=threads <= 1, + ), + zip(url, repeat(dir)), + ) + pool.close() + pool.join() + else: + for u in [url] if isinstance(url, (str, Path)) else url: + safe_download(url=u, dir=dir, unzip=unzip, delete=delete, curl=curl, retry=retry, exist_ok=exist_ok) diff --git a/ultralytics/utils/errors.py b/ultralytics/utils/errors.py new file mode 100644 index 0000000..86aee1d --- /dev/null +++ b/ultralytics/utils/errors.py @@ -0,0 +1,22 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from ultralytics.utils import emojis + + +class HUBModelError(Exception): + """ + Custom exception class for handling errors related to model fetching in Ultralytics YOLO. + + This exception is raised when a requested model is not found or cannot be retrieved. + The message is also processed to include emojis for better user experience. + + Attributes: + message (str): The error message displayed when the exception is raised. + + Note: + The message is automatically processed through the 'emojis' function from the 'ultralytics.utils' package. + """ + + def __init__(self, message="Model not found. Please check model URL and try again."): + """Create an exception for when a model is not found.""" + super().__init__(emojis(message)) diff --git a/ultralytics/utils/files.py b/ultralytics/utils/files.py new file mode 100644 index 0000000..719caca --- /dev/null +++ b/ultralytics/utils/files.py @@ -0,0 +1,188 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import contextlib +import glob +import os +import shutil +import tempfile +from contextlib import contextmanager +from datetime import datetime +from pathlib import Path + + +class WorkingDirectory(contextlib.ContextDecorator): + """Usage: @WorkingDirectory(dir) decorator or 'with WorkingDirectory(dir):' context manager.""" + + def __init__(self, new_dir): + """Sets the working directory to 'new_dir' upon instantiation.""" + self.dir = new_dir # new dir + self.cwd = Path.cwd().resolve() # current dir + + def __enter__(self): + """Changes the current directory to the specified directory.""" + os.chdir(self.dir) + + def __exit__(self, exc_type, exc_val, exc_tb): # noqa + """Restore the current working directory on context exit.""" + os.chdir(self.cwd) + + +@contextmanager +def spaces_in_path(path): + """ + Context manager to handle paths with spaces in their names. If a path contains spaces, it replaces them with + underscores, copies the file/directory to the new path, executes the context code block, then copies the + file/directory back to its original location. + + Args: + path (str | Path): The original path. + + Yields: + (Path): Temporary path with spaces replaced by underscores if spaces were present, otherwise the original path. + + Example: + ```python + with ultralytics.utils.files import spaces_in_path + + with spaces_in_path('/path/with spaces') as new_path: + # Your code here + ``` + """ + + # If path has spaces, replace them with underscores + if " " in str(path): + string = isinstance(path, str) # input type + path = Path(path) + + # Create a temporary directory and construct the new path + with tempfile.TemporaryDirectory() as tmp_dir: + tmp_path = Path(tmp_dir) / path.name.replace(" ", "_") + + # Copy file/directory + if path.is_dir(): + # tmp_path.mkdir(parents=True, exist_ok=True) + shutil.copytree(path, tmp_path) + elif path.is_file(): + tmp_path.parent.mkdir(parents=True, exist_ok=True) + shutil.copy2(path, tmp_path) + + try: + # Yield the temporary path + yield str(tmp_path) if string else tmp_path + + finally: + # Copy file/directory back + if tmp_path.is_dir(): + shutil.copytree(tmp_path, path, dirs_exist_ok=True) + elif tmp_path.is_file(): + shutil.copy2(tmp_path, path) # Copy back the file + + else: + # If there are no spaces, just yield the original path + yield path + + +def increment_path(path, exist_ok=False, sep="", mkdir=False): + """ + Increments a file or directory path, i.e. runs/exp --> runs/exp{sep}2, runs/exp{sep}3, ... etc. + + If the path exists and exist_ok is not set to True, the path will be incremented by appending a number and sep to + the end of the path. If the path is a file, the file extension will be preserved. If the path is a directory, the + number will be appended directly to the end of the path. If mkdir is set to True, the path will be created as a + directory if it does not already exist. + + Args: + path (str, pathlib.Path): Path to increment. + exist_ok (bool, optional): If True, the path will not be incremented and returned as-is. Defaults to False. + sep (str, optional): Separator to use between the path and the incrementation number. Defaults to ''. + mkdir (bool, optional): Create a directory if it does not exist. Defaults to False. + + Returns: + (pathlib.Path): Incremented path. + """ + path = Path(path) # os-agnostic + if path.exists() and not exist_ok: + path, suffix = (path.with_suffix(""), path.suffix) if path.is_file() else (path, "") + + # Method 1 + for n in range(2, 9999): + p = f"{path}{sep}{n}{suffix}" # increment path + if not os.path.exists(p): + break + path = Path(p) + + if mkdir: + path.mkdir(parents=True, exist_ok=True) # make directory + + return path + + +def file_age(path=__file__): + """Return days since last file update.""" + dt = datetime.now() - datetime.fromtimestamp(Path(path).stat().st_mtime) # delta + return dt.days # + dt.seconds / 86400 # fractional days + + +def file_date(path=__file__): + """Return human-readable file modification date, i.e. '2021-3-26'.""" + t = datetime.fromtimestamp(Path(path).stat().st_mtime) + return f"{t.year}-{t.month}-{t.day}" + + +def file_size(path): + """Return file/dir size (MB).""" + if isinstance(path, (str, Path)): + mb = 1 << 20 # bytes to MiB (1024 ** 2) + path = Path(path) + if path.is_file(): + return path.stat().st_size / mb + elif path.is_dir(): + return sum(f.stat().st_size for f in path.glob("**/*") if f.is_file()) / mb + return 0.0 + + +def get_latest_run(search_dir="."): + """Return path to most recent 'last.pt' in /runs (i.e. to --resume from).""" + last_list = glob.glob(f"{search_dir}/**/last*.pt", recursive=True) + return max(last_list, key=os.path.getctime) if last_list else "" + + +def update_models(model_names=("yolov8n.pt",), source_dir=Path("."), update_names=False): + """ + Updates and re-saves specified YOLO models in an 'updated_models' subdirectory. + + Args: + model_names (tuple, optional): Model filenames to update, defaults to ("yolov8n.pt"). + source_dir (Path, optional): Directory containing models and target subdirectory, defaults to current directory. + update_names (bool, optional): Update model names from a data YAML. + + Example: + ```python + from ultralytics.utils.files import update_models + + model_names = (f"rtdetr-{size}.pt" for size in "lx") + update_models(model_names) + ``` + """ + from ultralytics import YOLO + from ultralytics.nn.autobackend import default_class_names + + target_dir = source_dir / "updated_models" + target_dir.mkdir(parents=True, exist_ok=True) # Ensure target directory exists + + for model_name in model_names: + model_path = source_dir / model_name + print(f"Loading model from {model_path}") + + # Load model + model = YOLO(model_path) + model.half() + if update_names: # update model names from a dataset YAML + model.model.names = default_class_names("coco8.yaml") + + # Define new save path + save_path = target_dir / model_name + + # Save model using model.save() + print(f"Re-saving {model_name} model to {save_path}") + model.save(save_path, use_dill=False) diff --git a/ultralytics/utils/instance.py b/ultralytics/utils/instance.py new file mode 100644 index 0000000..4e9ef2c --- /dev/null +++ b/ultralytics/utils/instance.py @@ -0,0 +1,407 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from collections import abc +from itertools import repeat +from numbers import Number +from typing import List + +import numpy as np + +from .ops import ltwh2xywh, ltwh2xyxy, xywh2ltwh, xywh2xyxy, xyxy2ltwh, xyxy2xywh + + +def _ntuple(n): + """From PyTorch internals.""" + + def parse(x): + """Parse bounding boxes format between XYWH and LTWH.""" + return x if isinstance(x, abc.Iterable) else tuple(repeat(x, n)) + + return parse + + +to_2tuple = _ntuple(2) +to_4tuple = _ntuple(4) + +# `xyxy` means left top and right bottom +# `xywh` means center x, center y and width, height(YOLO format) +# `ltwh` means left top and width, height(COCO format) +_formats = ["xyxy", "xywh", "ltwh"] + +__all__ = ("Bboxes",) # tuple or list + + +class Bboxes: + """ + A class for handling bounding boxes. + + The class supports various bounding box formats like 'xyxy', 'xywh', and 'ltwh'. + Bounding box data should be provided in numpy arrays. + + Attributes: + bboxes (numpy.ndarray): The bounding boxes stored in a 2D numpy array. + format (str): The format of the bounding boxes ('xyxy', 'xywh', or 'ltwh'). + + Note: + This class does not handle normalization or denormalization of bounding boxes. + """ + + def __init__(self, bboxes, format="xyxy") -> None: + """Initializes the Bboxes class with bounding box data in a specified format.""" + assert format in _formats, f"Invalid bounding box format: {format}, format must be one of {_formats}" + bboxes = bboxes[None, :] if bboxes.ndim == 1 else bboxes + assert bboxes.ndim == 2 + assert bboxes.shape[1] == 4 + self.bboxes = bboxes + self.format = format + # self.normalized = normalized + + def convert(self, format): + """Converts bounding box format from one type to another.""" + assert format in _formats, f"Invalid bounding box format: {format}, format must be one of {_formats}" + if self.format == format: + return + elif self.format == "xyxy": + func = xyxy2xywh if format == "xywh" else xyxy2ltwh + elif self.format == "xywh": + func = xywh2xyxy if format == "xyxy" else xywh2ltwh + else: + func = ltwh2xyxy if format == "xyxy" else ltwh2xywh + self.bboxes = func(self.bboxes) + self.format = format + + def areas(self): + """Return box areas.""" + self.convert("xyxy") + return (self.bboxes[:, 2] - self.bboxes[:, 0]) * (self.bboxes[:, 3] - self.bboxes[:, 1]) + + # def denormalize(self, w, h): + # if not self.normalized: + # return + # assert (self.bboxes <= 1.0).all() + # self.bboxes[:, 0::2] *= w + # self.bboxes[:, 1::2] *= h + # self.normalized = False + # + # def normalize(self, w, h): + # if self.normalized: + # return + # assert (self.bboxes > 1.0).any() + # self.bboxes[:, 0::2] /= w + # self.bboxes[:, 1::2] /= h + # self.normalized = True + + def mul(self, scale): + """ + Args: + scale (tuple | list | int): the scale for four coords. + """ + if isinstance(scale, Number): + scale = to_4tuple(scale) + assert isinstance(scale, (tuple, list)) + assert len(scale) == 4 + self.bboxes[:, 0] *= scale[0] + self.bboxes[:, 1] *= scale[1] + self.bboxes[:, 2] *= scale[2] + self.bboxes[:, 3] *= scale[3] + + def add(self, offset): + """ + Args: + offset (tuple | list | int): the offset for four coords. + """ + if isinstance(offset, Number): + offset = to_4tuple(offset) + assert isinstance(offset, (tuple, list)) + assert len(offset) == 4 + self.bboxes[:, 0] += offset[0] + self.bboxes[:, 1] += offset[1] + self.bboxes[:, 2] += offset[2] + self.bboxes[:, 3] += offset[3] + + def __len__(self): + """Return the number of boxes.""" + return len(self.bboxes) + + @classmethod + def concatenate(cls, boxes_list: List["Bboxes"], axis=0) -> "Bboxes": + """ + Concatenate a list of Bboxes objects into a single Bboxes object. + + Args: + boxes_list (List[Bboxes]): A list of Bboxes objects to concatenate. + axis (int, optional): The axis along which to concatenate the bounding boxes. + Defaults to 0. + + Returns: + Bboxes: A new Bboxes object containing the concatenated bounding boxes. + + Note: + The input should be a list or tuple of Bboxes objects. + """ + assert isinstance(boxes_list, (list, tuple)) + if not boxes_list: + return cls(np.empty(0)) + assert all(isinstance(box, Bboxes) for box in boxes_list) + + if len(boxes_list) == 1: + return boxes_list[0] + return cls(np.concatenate([b.bboxes for b in boxes_list], axis=axis)) + + def __getitem__(self, index) -> "Bboxes": + """ + Retrieve a specific bounding box or a set of bounding boxes using indexing. + + Args: + index (int, slice, or np.ndarray): The index, slice, or boolean array to select + the desired bounding boxes. + + Returns: + Bboxes: A new Bboxes object containing the selected bounding boxes. + + Raises: + AssertionError: If the indexed bounding boxes do not form a 2-dimensional matrix. + + Note: + When using boolean indexing, make sure to provide a boolean array with the same + length as the number of bounding boxes. + """ + if isinstance(index, int): + return Bboxes(self.bboxes[index].view(1, -1)) + b = self.bboxes[index] + assert b.ndim == 2, f"Indexing on Bboxes with {index} failed to return a matrix!" + return Bboxes(b) + + +class Instances: + """ + Container for bounding boxes, segments, and keypoints of detected objects in an image. + + Attributes: + _bboxes (Bboxes): Internal object for handling bounding box operations. + keypoints (ndarray): keypoints(x, y, visible) with shape [N, 17, 3]. Default is None. + normalized (bool): Flag indicating whether the bounding box coordinates are normalized. + segments (ndarray): Segments array with shape [N, 1000, 2] after resampling. + + Args: + bboxes (ndarray): An array of bounding boxes with shape [N, 4]. + segments (list | ndarray, optional): A list or array of object segments. Default is None. + keypoints (ndarray, optional): An array of keypoints with shape [N, 17, 3]. Default is None. + bbox_format (str, optional): The format of bounding boxes ('xywh' or 'xyxy'). Default is 'xywh'. + normalized (bool, optional): Whether the bounding box coordinates are normalized. Default is True. + + Examples: + ```python + # Create an Instances object + instances = Instances( + bboxes=np.array([[10, 10, 30, 30], [20, 20, 40, 40]]), + segments=[np.array([[5, 5], [10, 10]]), np.array([[15, 15], [20, 20]])], + keypoints=np.array([[[5, 5, 1], [10, 10, 1]], [[15, 15, 1], [20, 20, 1]]]) + ) + ``` + + Note: + The bounding box format is either 'xywh' or 'xyxy', and is determined by the `bbox_format` argument. + This class does not perform input validation, and it assumes the inputs are well-formed. + """ + + def __init__(self, bboxes, segments=None, keypoints=None, bbox_format="xywh", normalized=True) -> None: + """ + Args: + bboxes (ndarray): bboxes with shape [N, 4]. + segments (list | ndarray): segments. + keypoints (ndarray): keypoints(x, y, visible) with shape [N, 17, 3]. + """ + self._bboxes = Bboxes(bboxes=bboxes, format=bbox_format) + self.keypoints = keypoints + self.normalized = normalized + self.segments = segments + + def convert_bbox(self, format): + """Convert bounding box format.""" + self._bboxes.convert(format=format) + + @property + def bbox_areas(self): + """Calculate the area of bounding boxes.""" + return self._bboxes.areas() + + def scale(self, scale_w, scale_h, bbox_only=False): + """This might be similar with denormalize func but without normalized sign.""" + self._bboxes.mul(scale=(scale_w, scale_h, scale_w, scale_h)) + if bbox_only: + return + self.segments[..., 0] *= scale_w + self.segments[..., 1] *= scale_h + if self.keypoints is not None: + self.keypoints[..., 0] *= scale_w + self.keypoints[..., 1] *= scale_h + + def denormalize(self, w, h): + """Denormalizes boxes, segments, and keypoints from normalized coordinates.""" + if not self.normalized: + return + self._bboxes.mul(scale=(w, h, w, h)) + self.segments[..., 0] *= w + self.segments[..., 1] *= h + if self.keypoints is not None: + self.keypoints[..., 0] *= w + self.keypoints[..., 1] *= h + self.normalized = False + + def normalize(self, w, h): + """Normalize bounding boxes, segments, and keypoints to image dimensions.""" + if self.normalized: + return + self._bboxes.mul(scale=(1 / w, 1 / h, 1 / w, 1 / h)) + self.segments[..., 0] /= w + self.segments[..., 1] /= h + if self.keypoints is not None: + self.keypoints[..., 0] /= w + self.keypoints[..., 1] /= h + self.normalized = True + + def add_padding(self, padw, padh): + """Handle rect and mosaic situation.""" + assert not self.normalized, "you should add padding with absolute coordinates." + self._bboxes.add(offset=(padw, padh, padw, padh)) + self.segments[..., 0] += padw + self.segments[..., 1] += padh + if self.keypoints is not None: + self.keypoints[..., 0] += padw + self.keypoints[..., 1] += padh + + def __getitem__(self, index) -> "Instances": + """ + Retrieve a specific instance or a set of instances using indexing. + + Args: + index (int, slice, or np.ndarray): The index, slice, or boolean array to select + the desired instances. + + Returns: + Instances: A new Instances object containing the selected bounding boxes, + segments, and keypoints if present. + + Note: + When using boolean indexing, make sure to provide a boolean array with the same + length as the number of instances. + """ + segments = self.segments[index] if len(self.segments) else self.segments + keypoints = self.keypoints[index] if self.keypoints is not None else None + bboxes = self.bboxes[index] + bbox_format = self._bboxes.format + return Instances( + bboxes=bboxes, + segments=segments, + keypoints=keypoints, + bbox_format=bbox_format, + normalized=self.normalized, + ) + + def flipud(self, h): + """Flips the coordinates of bounding boxes, segments, and keypoints vertically.""" + if self._bboxes.format == "xyxy": + y1 = self.bboxes[:, 1].copy() + y2 = self.bboxes[:, 3].copy() + self.bboxes[:, 1] = h - y2 + self.bboxes[:, 3] = h - y1 + else: + self.bboxes[:, 1] = h - self.bboxes[:, 1] + self.segments[..., 1] = h - self.segments[..., 1] + if self.keypoints is not None: + self.keypoints[..., 1] = h - self.keypoints[..., 1] + + def fliplr(self, w): + """Reverses the order of the bounding boxes and segments horizontally.""" + if self._bboxes.format == "xyxy": + x1 = self.bboxes[:, 0].copy() + x2 = self.bboxes[:, 2].copy() + self.bboxes[:, 0] = w - x2 + self.bboxes[:, 2] = w - x1 + else: + self.bboxes[:, 0] = w - self.bboxes[:, 0] + self.segments[..., 0] = w - self.segments[..., 0] + if self.keypoints is not None: + self.keypoints[..., 0] = w - self.keypoints[..., 0] + + def clip(self, w, h): + """Clips bounding boxes, segments, and keypoints values to stay within image boundaries.""" + ori_format = self._bboxes.format + self.convert_bbox(format="xyxy") + self.bboxes[:, [0, 2]] = self.bboxes[:, [0, 2]].clip(0, w) + self.bboxes[:, [1, 3]] = self.bboxes[:, [1, 3]].clip(0, h) + if ori_format != "xyxy": + self.convert_bbox(format=ori_format) + self.segments[..., 0] = self.segments[..., 0].clip(0, w) + self.segments[..., 1] = self.segments[..., 1].clip(0, h) + if self.keypoints is not None: + self.keypoints[..., 0] = self.keypoints[..., 0].clip(0, w) + self.keypoints[..., 1] = self.keypoints[..., 1].clip(0, h) + + def remove_zero_area_boxes(self): + """ + Remove zero-area boxes, i.e. after clipping some boxes may have zero width or height. + + This removes them. + """ + good = self.bbox_areas > 0 + if not all(good): + self._bboxes = self._bboxes[good] + if len(self.segments): + self.segments = self.segments[good] + if self.keypoints is not None: + self.keypoints = self.keypoints[good] + return good + + def update(self, bboxes, segments=None, keypoints=None): + """Updates instance variables.""" + self._bboxes = Bboxes(bboxes, format=self._bboxes.format) + if segments is not None: + self.segments = segments + if keypoints is not None: + self.keypoints = keypoints + + def __len__(self): + """Return the length of the instance list.""" + return len(self.bboxes) + + @classmethod + def concatenate(cls, instances_list: List["Instances"], axis=0) -> "Instances": + """ + Concatenates a list of Instances objects into a single Instances object. + + Args: + instances_list (List[Instances]): A list of Instances objects to concatenate. + axis (int, optional): The axis along which the arrays will be concatenated. Defaults to 0. + + Returns: + Instances: A new Instances object containing the concatenated bounding boxes, + segments, and keypoints if present. + + Note: + The `Instances` objects in the list should have the same properties, such as + the format of the bounding boxes, whether keypoints are present, and if the + coordinates are normalized. + """ + assert isinstance(instances_list, (list, tuple)) + if not instances_list: + return cls(np.empty(0)) + assert all(isinstance(instance, Instances) for instance in instances_list) + + if len(instances_list) == 1: + return instances_list[0] + + use_keypoint = instances_list[0].keypoints is not None + bbox_format = instances_list[0]._bboxes.format + normalized = instances_list[0].normalized + + cat_boxes = np.concatenate([ins.bboxes for ins in instances_list], axis=axis) + cat_segments = np.concatenate([b.segments for b in instances_list], axis=axis) + cat_keypoints = np.concatenate([b.keypoints for b in instances_list], axis=axis) if use_keypoint else None + return cls(cat_boxes, cat_segments, cat_keypoints, bbox_format, normalized) + + @property + def bboxes(self): + """Return bounding boxes.""" + return self._bboxes.bboxes diff --git a/ultralytics/utils/loss.py b/ultralytics/utils/loss.py new file mode 100644 index 0000000..ee4df19 --- /dev/null +++ b/ultralytics/utils/loss.py @@ -0,0 +1,716 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import torch +import torch.nn as nn +import torch.nn.functional as F + +from ultralytics.utils.metrics import OKS_SIGMA +from ultralytics.utils.ops import crop_mask, xywh2xyxy, xyxy2xywh +from ultralytics.utils.tal import RotatedTaskAlignedAssigner, TaskAlignedAssigner, dist2bbox, dist2rbox, make_anchors + +from .metrics import bbox_iou, probiou +from .tal import bbox2dist + + +class VarifocalLoss(nn.Module): + """ + Varifocal loss by Zhang et al. + + https://arxiv.org/abs/2008.13367. + """ + + def __init__(self): + """Initialize the VarifocalLoss class.""" + super().__init__() + + @staticmethod + def forward(pred_score, gt_score, label, alpha=0.75, gamma=2.0): + """Computes varfocal loss.""" + weight = alpha * pred_score.sigmoid().pow(gamma) * (1 - label) + gt_score * label + with torch.cuda.amp.autocast(enabled=False): + loss = ( + (F.binary_cross_entropy_with_logits(pred_score.float(), gt_score.float(), reduction="none") * weight) + .mean(1) + .sum() + ) + return loss + + +class FocalLoss(nn.Module): + """Wraps focal loss around existing loss_fcn(), i.e. criteria = FocalLoss(nn.BCEWithLogitsLoss(), gamma=1.5).""" + + def __init__(self): + """Initializer for FocalLoss class with no parameters.""" + super().__init__() + + @staticmethod + def forward(pred, label, gamma=1.5, alpha=0.25): + """Calculates and updates confusion matrix for object detection/classification tasks.""" + loss = F.binary_cross_entropy_with_logits(pred, label, reduction="none") + # p_t = torch.exp(-loss) + # loss *= self.alpha * (1.000001 - p_t) ** self.gamma # non-zero power for gradient stability + + # TF implementation https://github.com/tensorflow/addons/blob/v0.7.1/tensorflow_addons/losses/focal_loss.py + pred_prob = pred.sigmoid() # prob from logits + p_t = label * pred_prob + (1 - label) * (1 - pred_prob) + modulating_factor = (1.0 - p_t) ** gamma + loss *= modulating_factor + if alpha > 0: + alpha_factor = label * alpha + (1 - label) * (1 - alpha) + loss *= alpha_factor + return loss.mean(1).sum() + + +class BboxLoss(nn.Module): + """Criterion class for computing training losses during training.""" + + def __init__(self, reg_max, use_dfl=False): + """Initialize the BboxLoss module with regularization maximum and DFL settings.""" + super().__init__() + self.reg_max = reg_max + self.use_dfl = use_dfl + + def forward(self, pred_dist, pred_bboxes, anchor_points, target_bboxes, target_scores, target_scores_sum, fg_mask): + """IoU loss.""" + weight = target_scores.sum(-1)[fg_mask].unsqueeze(-1) + iou = bbox_iou(pred_bboxes[fg_mask], target_bboxes[fg_mask], xywh=False, CIoU=True) + loss_iou = ((1.0 - iou) * weight).sum() / target_scores_sum + + # DFL loss + if self.use_dfl: + target_ltrb = bbox2dist(anchor_points, target_bboxes, self.reg_max) + loss_dfl = self._df_loss(pred_dist[fg_mask].view(-1, self.reg_max + 1), target_ltrb[fg_mask]) * weight + loss_dfl = loss_dfl.sum() / target_scores_sum + else: + loss_dfl = torch.tensor(0.0).to(pred_dist.device) + + return loss_iou, loss_dfl + + @staticmethod + def _df_loss(pred_dist, target): + """ + Return sum of left and right DFL losses. + + Distribution Focal Loss (DFL) proposed in Generalized Focal Loss + https://ieeexplore.ieee.org/document/9792391 + """ + tl = target.long() # target left + tr = tl + 1 # target right + wl = tr - target # weight left + wr = 1 - wl # weight right + return ( + F.cross_entropy(pred_dist, tl.view(-1), reduction="none").view(tl.shape) * wl + + F.cross_entropy(pred_dist, tr.view(-1), reduction="none").view(tl.shape) * wr + ).mean(-1, keepdim=True) + + +class RotatedBboxLoss(BboxLoss): + """Criterion class for computing training losses during training.""" + + def __init__(self, reg_max, use_dfl=False): + """Initialize the BboxLoss module with regularization maximum and DFL settings.""" + super().__init__(reg_max, use_dfl) + + def forward(self, pred_dist, pred_bboxes, anchor_points, target_bboxes, target_scores, target_scores_sum, fg_mask): + """IoU loss.""" + weight = target_scores.sum(-1)[fg_mask].unsqueeze(-1) + iou = probiou(pred_bboxes[fg_mask], target_bboxes[fg_mask]) + loss_iou = ((1.0 - iou) * weight).sum() / target_scores_sum + + # DFL loss + if self.use_dfl: + target_ltrb = bbox2dist(anchor_points, xywh2xyxy(target_bboxes[..., :4]), self.reg_max) + loss_dfl = self._df_loss(pred_dist[fg_mask].view(-1, self.reg_max + 1), target_ltrb[fg_mask]) * weight + loss_dfl = loss_dfl.sum() / target_scores_sum + else: + loss_dfl = torch.tensor(0.0).to(pred_dist.device) + + return loss_iou, loss_dfl + + +class KeypointLoss(nn.Module): + """Criterion class for computing training losses.""" + + def __init__(self, sigmas) -> None: + """Initialize the KeypointLoss class.""" + super().__init__() + self.sigmas = sigmas + + def forward(self, pred_kpts, gt_kpts, kpt_mask, area): + """Calculates keypoint loss factor and Euclidean distance loss for predicted and actual keypoints.""" + d = (pred_kpts[..., 0] - gt_kpts[..., 0]).pow(2) + (pred_kpts[..., 1] - gt_kpts[..., 1]).pow(2) + kpt_loss_factor = kpt_mask.shape[1] / (torch.sum(kpt_mask != 0, dim=1) + 1e-9) + # e = d / (2 * (area * self.sigmas) ** 2 + 1e-9) # from formula + e = d / ((2 * self.sigmas).pow(2) * (area + 1e-9) * 2) # from cocoeval + return (kpt_loss_factor.view(-1, 1) * ((1 - torch.exp(-e)) * kpt_mask)).mean() + + +class v8DetectionLoss: + """Criterion class for computing training losses.""" + + def __init__(self, model): # model must be de-paralleled + """Initializes v8DetectionLoss with the model, defining model-related properties and BCE loss function.""" + device = next(model.parameters()).device # get model device + h = model.args # hyperparameters + + m = model.model[-1] # Detect() module + self.bce = nn.BCEWithLogitsLoss(reduction="none") + self.hyp = h + self.stride = m.stride # model strides + self.nc = m.nc # number of classes + self.no = m.nc + m.reg_max * 4 + self.reg_max = m.reg_max + self.device = device + + self.use_dfl = m.reg_max > 1 + + self.assigner = TaskAlignedAssigner(topk=10, num_classes=self.nc, alpha=0.5, beta=6.0) + self.bbox_loss = BboxLoss(m.reg_max - 1, use_dfl=self.use_dfl).to(device) + self.proj = torch.arange(m.reg_max, dtype=torch.float, device=device) + + def preprocess(self, targets, batch_size, scale_tensor): + """Preprocesses the target counts and matches with the input batch size to output a tensor.""" + if targets.shape[0] == 0: + out = torch.zeros(batch_size, 0, 5, device=self.device) + else: + i = targets[:, 0] # image index + _, counts = i.unique(return_counts=True) + counts = counts.to(dtype=torch.int32) + out = torch.zeros(batch_size, counts.max(), 5, device=self.device) + for j in range(batch_size): + matches = i == j + n = matches.sum() + if n: + out[j, :n] = targets[matches, 1:] + out[..., 1:5] = xywh2xyxy(out[..., 1:5].mul_(scale_tensor)) + return out + + def bbox_decode(self, anchor_points, pred_dist): + """Decode predicted object bounding box coordinates from anchor points and distribution.""" + if self.use_dfl: + b, a, c = pred_dist.shape # batch, anchors, channels + pred_dist = pred_dist.view(b, a, 4, c // 4).softmax(3).matmul(self.proj.type(pred_dist.dtype)) + # pred_dist = pred_dist.view(b, a, c // 4, 4).transpose(2,3).softmax(3).matmul(self.proj.type(pred_dist.dtype)) + # pred_dist = (pred_dist.view(b, a, c // 4, 4).softmax(2) * self.proj.type(pred_dist.dtype).view(1, 1, -1, 1)).sum(2) + return dist2bbox(pred_dist, anchor_points, xywh=False) + + def __call__(self, preds, batch): + """Calculate the sum of the loss for box, cls and dfl multiplied by batch size.""" + loss = torch.zeros(3, device=self.device) # box, cls, dfl + feats = preds[1] if isinstance(preds, tuple) else preds + pred_distri, pred_scores = torch.cat([xi.view(feats[0].shape[0], self.no, -1) for xi in feats], 2).split( + (self.reg_max * 4, self.nc), 1 + ) + + pred_scores = pred_scores.permute(0, 2, 1).contiguous() + pred_distri = pred_distri.permute(0, 2, 1).contiguous() + + dtype = pred_scores.dtype + batch_size = pred_scores.shape[0] + imgsz = torch.tensor(feats[0].shape[2:], device=self.device, dtype=dtype) * self.stride[0] # image size (h,w) + anchor_points, stride_tensor = make_anchors(feats, self.stride, 0.5) + + # Targets + targets = torch.cat((batch["batch_idx"].view(-1, 1), batch["cls"].view(-1, 1), batch["bboxes"]), 1) + targets = self.preprocess(targets.to(self.device), batch_size, scale_tensor=imgsz[[1, 0, 1, 0]]) + gt_labels, gt_bboxes = targets.split((1, 4), 2) # cls, xyxy + mask_gt = gt_bboxes.sum(2, keepdim=True).gt_(0) + + # Pboxes + pred_bboxes = self.bbox_decode(anchor_points, pred_distri) # xyxy, (b, h*w, 4) + + _, target_bboxes, target_scores, fg_mask, _ = self.assigner( + pred_scores.detach().sigmoid(), + (pred_bboxes.detach() * stride_tensor).type(gt_bboxes.dtype), + anchor_points * stride_tensor, + gt_labels, + gt_bboxes, + mask_gt, + ) + + target_scores_sum = max(target_scores.sum(), 1) + + # Cls loss + # loss[1] = self.varifocal_loss(pred_scores, target_scores, target_labels) / target_scores_sum # VFL way + loss[1] = self.bce(pred_scores, target_scores.to(dtype)).sum() / target_scores_sum # BCE + + # Bbox loss + if fg_mask.sum(): + target_bboxes /= stride_tensor + loss[0], loss[2] = self.bbox_loss( + pred_distri, pred_bboxes, anchor_points, target_bboxes, target_scores, target_scores_sum, fg_mask + ) + + loss[0] *= self.hyp.box # box gain + loss[1] *= self.hyp.cls # cls gain + loss[2] *= self.hyp.dfl # dfl gain + + return loss.sum() * batch_size, loss.detach() # loss(box, cls, dfl) + + +class v8SegmentationLoss(v8DetectionLoss): + """Criterion class for computing training losses.""" + + def __init__(self, model): # model must be de-paralleled + """Initializes the v8SegmentationLoss class, taking a de-paralleled model as argument.""" + super().__init__(model) + self.overlap = model.args.overlap_mask + + def __call__(self, preds, batch): + """Calculate and return the loss for the YOLO model.""" + loss = torch.zeros(4, device=self.device) # box, cls, dfl + feats, pred_masks, proto = preds if len(preds) == 3 else preds[1] + batch_size, _, mask_h, mask_w = proto.shape # batch size, number of masks, mask height, mask width + pred_distri, pred_scores = torch.cat([xi.view(feats[0].shape[0], self.no, -1) for xi in feats], 2).split( + (self.reg_max * 4, self.nc), 1 + ) + + # B, grids, .. + pred_scores = pred_scores.permute(0, 2, 1).contiguous() + pred_distri = pred_distri.permute(0, 2, 1).contiguous() + pred_masks = pred_masks.permute(0, 2, 1).contiguous() + + dtype = pred_scores.dtype + imgsz = torch.tensor(feats[0].shape[2:], device=self.device, dtype=dtype) * self.stride[0] # image size (h,w) + anchor_points, stride_tensor = make_anchors(feats, self.stride, 0.5) + + # Targets + try: + batch_idx = batch["batch_idx"].view(-1, 1) + targets = torch.cat((batch_idx, batch["cls"].view(-1, 1), batch["bboxes"]), 1) + targets = self.preprocess(targets.to(self.device), batch_size, scale_tensor=imgsz[[1, 0, 1, 0]]) + gt_labels, gt_bboxes = targets.split((1, 4), 2) # cls, xyxy + mask_gt = gt_bboxes.sum(2, keepdim=True).gt_(0) + except RuntimeError as e: + raise TypeError( + "ERROR ❌ segment dataset incorrectly formatted or not a segment dataset.\n" + "This error can occur when incorrectly training a 'segment' model on a 'detect' dataset, " + "i.e. 'yolo train model=yolov8n-seg.pt data=coco8.yaml'.\nVerify your dataset is a " + "correctly formatted 'segment' dataset using 'data=coco8-seg.yaml' " + "as an example.\nSee https://docs.ultralytics.com/datasets/segment/ for help." + ) from e + + # Pboxes + pred_bboxes = self.bbox_decode(anchor_points, pred_distri) # xyxy, (b, h*w, 4) + + _, target_bboxes, target_scores, fg_mask, target_gt_idx = self.assigner( + pred_scores.detach().sigmoid(), + (pred_bboxes.detach() * stride_tensor).type(gt_bboxes.dtype), + anchor_points * stride_tensor, + gt_labels, + gt_bboxes, + mask_gt, + ) + + target_scores_sum = max(target_scores.sum(), 1) + + # Cls loss + # loss[1] = self.varifocal_loss(pred_scores, target_scores, target_labels) / target_scores_sum # VFL way + loss[2] = self.bce(pred_scores, target_scores.to(dtype)).sum() / target_scores_sum # BCE + + if fg_mask.sum(): + # Bbox loss + loss[0], loss[3] = self.bbox_loss( + pred_distri, + pred_bboxes, + anchor_points, + target_bboxes / stride_tensor, + target_scores, + target_scores_sum, + fg_mask, + ) + # Masks loss + masks = batch["masks"].to(self.device).float() + if tuple(masks.shape[-2:]) != (mask_h, mask_w): # downsample + masks = F.interpolate(masks[None], (mask_h, mask_w), mode="nearest")[0] + + loss[1] = self.calculate_segmentation_loss( + fg_mask, masks, target_gt_idx, target_bboxes, batch_idx, proto, pred_masks, imgsz, self.overlap + ) + + # WARNING: lines below prevent Multi-GPU DDP 'unused gradient' PyTorch errors, do not remove + else: + loss[1] += (proto * 0).sum() + (pred_masks * 0).sum() # inf sums may lead to nan loss + + loss[0] *= self.hyp.box # box gain + loss[1] *= self.hyp.box # seg gain + loss[2] *= self.hyp.cls # cls gain + loss[3] *= self.hyp.dfl # dfl gain + + return loss.sum() * batch_size, loss.detach() # loss(box, cls, dfl) + + @staticmethod + def single_mask_loss( + gt_mask: torch.Tensor, pred: torch.Tensor, proto: torch.Tensor, xyxy: torch.Tensor, area: torch.Tensor + ) -> torch.Tensor: + """ + Compute the instance segmentation loss for a single image. + + Args: + gt_mask (torch.Tensor): Ground truth mask of shape (n, H, W), where n is the number of objects. + pred (torch.Tensor): Predicted mask coefficients of shape (n, 32). + proto (torch.Tensor): Prototype masks of shape (32, H, W). + xyxy (torch.Tensor): Ground truth bounding boxes in xyxy format, normalized to [0, 1], of shape (n, 4). + area (torch.Tensor): Area of each ground truth bounding box of shape (n,). + + Returns: + (torch.Tensor): The calculated mask loss for a single image. + + Notes: + The function uses the equation pred_mask = torch.einsum('in,nhw->ihw', pred, proto) to produce the + predicted masks from the prototype masks and predicted mask coefficients. + """ + pred_mask = torch.einsum("in,nhw->ihw", pred, proto) # (n, 32) @ (32, 80, 80) -> (n, 80, 80) + loss = F.binary_cross_entropy_with_logits(pred_mask, gt_mask, reduction="none") + return (crop_mask(loss, xyxy).mean(dim=(1, 2)) / area).sum() + + def calculate_segmentation_loss( + self, + fg_mask: torch.Tensor, + masks: torch.Tensor, + target_gt_idx: torch.Tensor, + target_bboxes: torch.Tensor, + batch_idx: torch.Tensor, + proto: torch.Tensor, + pred_masks: torch.Tensor, + imgsz: torch.Tensor, + overlap: bool, + ) -> torch.Tensor: + """ + Calculate the loss for instance segmentation. + + Args: + fg_mask (torch.Tensor): A binary tensor of shape (BS, N_anchors) indicating which anchors are positive. + masks (torch.Tensor): Ground truth masks of shape (BS, H, W) if `overlap` is False, otherwise (BS, ?, H, W). + target_gt_idx (torch.Tensor): Indexes of ground truth objects for each anchor of shape (BS, N_anchors). + target_bboxes (torch.Tensor): Ground truth bounding boxes for each anchor of shape (BS, N_anchors, 4). + batch_idx (torch.Tensor): Batch indices of shape (N_labels_in_batch, 1). + proto (torch.Tensor): Prototype masks of shape (BS, 32, H, W). + pred_masks (torch.Tensor): Predicted masks for each anchor of shape (BS, N_anchors, 32). + imgsz (torch.Tensor): Size of the input image as a tensor of shape (2), i.e., (H, W). + overlap (bool): Whether the masks in `masks` tensor overlap. + + Returns: + (torch.Tensor): The calculated loss for instance segmentation. + + Notes: + The batch loss can be computed for improved speed at higher memory usage. + For example, pred_mask can be computed as follows: + pred_mask = torch.einsum('in,nhw->ihw', pred, proto) # (i, 32) @ (32, 160, 160) -> (i, 160, 160) + """ + _, _, mask_h, mask_w = proto.shape + loss = 0 + + # Normalize to 0-1 + target_bboxes_normalized = target_bboxes / imgsz[[1, 0, 1, 0]] + + # Areas of target bboxes + marea = xyxy2xywh(target_bboxes_normalized)[..., 2:].prod(2) + + # Normalize to mask size + mxyxy = target_bboxes_normalized * torch.tensor([mask_w, mask_h, mask_w, mask_h], device=proto.device) + + for i, single_i in enumerate(zip(fg_mask, target_gt_idx, pred_masks, proto, mxyxy, marea, masks)): + fg_mask_i, target_gt_idx_i, pred_masks_i, proto_i, mxyxy_i, marea_i, masks_i = single_i + if fg_mask_i.any(): + mask_idx = target_gt_idx_i[fg_mask_i] + if overlap: + gt_mask = masks_i == (mask_idx + 1).view(-1, 1, 1) + gt_mask = gt_mask.float() + else: + gt_mask = masks[batch_idx.view(-1) == i][mask_idx] + + loss += self.single_mask_loss( + gt_mask, pred_masks_i[fg_mask_i], proto_i, mxyxy_i[fg_mask_i], marea_i[fg_mask_i] + ) + + # WARNING: lines below prevents Multi-GPU DDP 'unused gradient' PyTorch errors, do not remove + else: + loss += (proto * 0).sum() + (pred_masks * 0).sum() # inf sums may lead to nan loss + + return loss / fg_mask.sum() + + +class v8PoseLoss(v8DetectionLoss): + """Criterion class for computing training losses.""" + + def __init__(self, model): # model must be de-paralleled + """Initializes v8PoseLoss with model, sets keypoint variables and declares a keypoint loss instance.""" + super().__init__(model) + self.kpt_shape = model.model[-1].kpt_shape + self.bce_pose = nn.BCEWithLogitsLoss() + is_pose = self.kpt_shape == [17, 3] + nkpt = self.kpt_shape[0] # number of keypoints + sigmas = torch.from_numpy(OKS_SIGMA).to(self.device) if is_pose else torch.ones(nkpt, device=self.device) / nkpt + self.keypoint_loss = KeypointLoss(sigmas=sigmas) + + def __call__(self, preds, batch): + """Calculate the total loss and detach it.""" + loss = torch.zeros(5, device=self.device) # box, cls, dfl, kpt_location, kpt_visibility + feats, pred_kpts = preds if isinstance(preds[0], list) else preds[1] + pred_distri, pred_scores = torch.cat([xi.view(feats[0].shape[0], self.no, -1) for xi in feats], 2).split( + (self.reg_max * 4, self.nc), 1 + ) + + # B, grids, .. + pred_scores = pred_scores.permute(0, 2, 1).contiguous() + pred_distri = pred_distri.permute(0, 2, 1).contiguous() + pred_kpts = pred_kpts.permute(0, 2, 1).contiguous() + + dtype = pred_scores.dtype + imgsz = torch.tensor(feats[0].shape[2:], device=self.device, dtype=dtype) * self.stride[0] # image size (h,w) + anchor_points, stride_tensor = make_anchors(feats, self.stride, 0.5) + + # Targets + batch_size = pred_scores.shape[0] + batch_idx = batch["batch_idx"].view(-1, 1) + targets = torch.cat((batch_idx, batch["cls"].view(-1, 1), batch["bboxes"]), 1) + targets = self.preprocess(targets.to(self.device), batch_size, scale_tensor=imgsz[[1, 0, 1, 0]]) + gt_labels, gt_bboxes = targets.split((1, 4), 2) # cls, xyxy + mask_gt = gt_bboxes.sum(2, keepdim=True).gt_(0) + + # Pboxes + pred_bboxes = self.bbox_decode(anchor_points, pred_distri) # xyxy, (b, h*w, 4) + pred_kpts = self.kpts_decode(anchor_points, pred_kpts.view(batch_size, -1, *self.kpt_shape)) # (b, h*w, 17, 3) + + _, target_bboxes, target_scores, fg_mask, target_gt_idx = self.assigner( + pred_scores.detach().sigmoid(), + (pred_bboxes.detach() * stride_tensor).type(gt_bboxes.dtype), + anchor_points * stride_tensor, + gt_labels, + gt_bboxes, + mask_gt, + ) + + target_scores_sum = max(target_scores.sum(), 1) + + # Cls loss + # loss[1] = self.varifocal_loss(pred_scores, target_scores, target_labels) / target_scores_sum # VFL way + loss[3] = self.bce(pred_scores, target_scores.to(dtype)).sum() / target_scores_sum # BCE + + # Bbox loss + if fg_mask.sum(): + target_bboxes /= stride_tensor + loss[0], loss[4] = self.bbox_loss( + pred_distri, pred_bboxes, anchor_points, target_bboxes, target_scores, target_scores_sum, fg_mask + ) + keypoints = batch["keypoints"].to(self.device).float().clone() + keypoints[..., 0] *= imgsz[1] + keypoints[..., 1] *= imgsz[0] + + loss[1], loss[2] = self.calculate_keypoints_loss( + fg_mask, target_gt_idx, keypoints, batch_idx, stride_tensor, target_bboxes, pred_kpts + ) + + loss[0] *= self.hyp.box # box gain + loss[1] *= self.hyp.pose # pose gain + loss[2] *= self.hyp.kobj # kobj gain + loss[3] *= self.hyp.cls # cls gain + loss[4] *= self.hyp.dfl # dfl gain + + return loss.sum() * batch_size, loss.detach() # loss(box, cls, dfl) + + @staticmethod + def kpts_decode(anchor_points, pred_kpts): + """Decodes predicted keypoints to image coordinates.""" + y = pred_kpts.clone() + y[..., :2] *= 2.0 + y[..., 0] += anchor_points[:, [0]] - 0.5 + y[..., 1] += anchor_points[:, [1]] - 0.5 + return y + + def calculate_keypoints_loss( + self, masks, target_gt_idx, keypoints, batch_idx, stride_tensor, target_bboxes, pred_kpts + ): + """ + Calculate the keypoints loss for the model. + + This function calculates the keypoints loss and keypoints object loss for a given batch. The keypoints loss is + based on the difference between the predicted keypoints and ground truth keypoints. The keypoints object loss is + a binary classification loss that classifies whether a keypoint is present or not. + + Args: + masks (torch.Tensor): Binary mask tensor indicating object presence, shape (BS, N_anchors). + target_gt_idx (torch.Tensor): Index tensor mapping anchors to ground truth objects, shape (BS, N_anchors). + keypoints (torch.Tensor): Ground truth keypoints, shape (N_kpts_in_batch, N_kpts_per_object, kpts_dim). + batch_idx (torch.Tensor): Batch index tensor for keypoints, shape (N_kpts_in_batch, 1). + stride_tensor (torch.Tensor): Stride tensor for anchors, shape (N_anchors, 1). + target_bboxes (torch.Tensor): Ground truth boxes in (x1, y1, x2, y2) format, shape (BS, N_anchors, 4). + pred_kpts (torch.Tensor): Predicted keypoints, shape (BS, N_anchors, N_kpts_per_object, kpts_dim). + + Returns: + (tuple): Returns a tuple containing: + - kpts_loss (torch.Tensor): The keypoints loss. + - kpts_obj_loss (torch.Tensor): The keypoints object loss. + """ + batch_idx = batch_idx.flatten() + batch_size = len(masks) + + # Find the maximum number of keypoints in a single image + max_kpts = torch.unique(batch_idx, return_counts=True)[1].max() + + # Create a tensor to hold batched keypoints + batched_keypoints = torch.zeros( + (batch_size, max_kpts, keypoints.shape[1], keypoints.shape[2]), device=keypoints.device + ) + + # TODO: any idea how to vectorize this? + # Fill batched_keypoints with keypoints based on batch_idx + for i in range(batch_size): + keypoints_i = keypoints[batch_idx == i] + batched_keypoints[i, : keypoints_i.shape[0]] = keypoints_i + + # Expand dimensions of target_gt_idx to match the shape of batched_keypoints + target_gt_idx_expanded = target_gt_idx.unsqueeze(-1).unsqueeze(-1) + + # Use target_gt_idx_expanded to select keypoints from batched_keypoints + selected_keypoints = batched_keypoints.gather( + 1, target_gt_idx_expanded.expand(-1, -1, keypoints.shape[1], keypoints.shape[2]) + ) + + # Divide coordinates by stride + selected_keypoints /= stride_tensor.view(1, -1, 1, 1) + + kpts_loss = 0 + kpts_obj_loss = 0 + + if masks.any(): + gt_kpt = selected_keypoints[masks] + area = xyxy2xywh(target_bboxes[masks])[:, 2:].prod(1, keepdim=True) + pred_kpt = pred_kpts[masks] + kpt_mask = gt_kpt[..., 2] != 0 if gt_kpt.shape[-1] == 3 else torch.full_like(gt_kpt[..., 0], True) + kpts_loss = self.keypoint_loss(pred_kpt, gt_kpt, kpt_mask, area) # pose loss + + if pred_kpt.shape[-1] == 3: + kpts_obj_loss = self.bce_pose(pred_kpt[..., 2], kpt_mask.float()) # keypoint obj loss + + return kpts_loss, kpts_obj_loss + + +class v8ClassificationLoss: + """Criterion class for computing training losses.""" + + def __call__(self, preds, batch): + """Compute the classification loss between predictions and true labels.""" + loss = torch.nn.functional.cross_entropy(preds, batch["cls"], reduction="mean") + loss_items = loss.detach() + return loss, loss_items + + +class v8OBBLoss(v8DetectionLoss): + def __init__(self, model): + """ + Initializes v8OBBLoss with model, assigner, and rotated bbox loss. + + Note model must be de-paralleled. + """ + super().__init__(model) + self.assigner = RotatedTaskAlignedAssigner(topk=10, num_classes=self.nc, alpha=0.5, beta=6.0) + self.bbox_loss = RotatedBboxLoss(self.reg_max - 1, use_dfl=self.use_dfl).to(self.device) + + def preprocess(self, targets, batch_size, scale_tensor): + """Preprocesses the target counts and matches with the input batch size to output a tensor.""" + if targets.shape[0] == 0: + out = torch.zeros(batch_size, 0, 6, device=self.device) + else: + i = targets[:, 0] # image index + _, counts = i.unique(return_counts=True) + counts = counts.to(dtype=torch.int32) + out = torch.zeros(batch_size, counts.max(), 6, device=self.device) + for j in range(batch_size): + matches = i == j + n = matches.sum() + if n: + bboxes = targets[matches, 2:] + bboxes[..., :4].mul_(scale_tensor) + out[j, :n] = torch.cat([targets[matches, 1:2], bboxes], dim=-1) + return out + + def __call__(self, preds, batch): + """Calculate and return the loss for the YOLO model.""" + loss = torch.zeros(3, device=self.device) # box, cls, dfl + feats, pred_angle = preds if isinstance(preds[0], list) else preds[1] + batch_size = pred_angle.shape[0] # batch size, number of masks, mask height, mask width + pred_distri, pred_scores = torch.cat([xi.view(feats[0].shape[0], self.no, -1) for xi in feats], 2).split( + (self.reg_max * 4, self.nc), 1 + ) + + # b, grids, .. + pred_scores = pred_scores.permute(0, 2, 1).contiguous() + pred_distri = pred_distri.permute(0, 2, 1).contiguous() + pred_angle = pred_angle.permute(0, 2, 1).contiguous() + + dtype = pred_scores.dtype + imgsz = torch.tensor(feats[0].shape[2:], device=self.device, dtype=dtype) * self.stride[0] # image size (h,w) + anchor_points, stride_tensor = make_anchors(feats, self.stride, 0.5) + + # targets + try: + batch_idx = batch["batch_idx"].view(-1, 1) + targets = torch.cat((batch_idx, batch["cls"].view(-1, 1), batch["bboxes"].view(-1, 5)), 1) + rw, rh = targets[:, 4] * imgsz[0].item(), targets[:, 5] * imgsz[1].item() + targets = targets[(rw >= 2) & (rh >= 2)] # filter rboxes of tiny size to stabilize training + targets = self.preprocess(targets.to(self.device), batch_size, scale_tensor=imgsz[[1, 0, 1, 0]]) + gt_labels, gt_bboxes = targets.split((1, 5), 2) # cls, xywhr + mask_gt = gt_bboxes.sum(2, keepdim=True).gt_(0) + except RuntimeError as e: + raise TypeError( + "ERROR ❌ OBB dataset incorrectly formatted or not a OBB dataset.\n" + "This error can occur when incorrectly training a 'OBB' model on a 'detect' dataset, " + "i.e. 'yolo train model=yolov8n-obb.pt data=dota8.yaml'.\nVerify your dataset is a " + "correctly formatted 'OBB' dataset using 'data=dota8.yaml' " + "as an example.\nSee https://docs.ultralytics.com/datasets/obb/ for help." + ) from e + + # Pboxes + pred_bboxes = self.bbox_decode(anchor_points, pred_distri, pred_angle) # xyxy, (b, h*w, 4) + + bboxes_for_assigner = pred_bboxes.clone().detach() + # Only the first four elements need to be scaled + bboxes_for_assigner[..., :4] *= stride_tensor + _, target_bboxes, target_scores, fg_mask, _ = self.assigner( + pred_scores.detach().sigmoid(), + bboxes_for_assigner.type(gt_bboxes.dtype), + anchor_points * stride_tensor, + gt_labels, + gt_bboxes, + mask_gt, + ) + + target_scores_sum = max(target_scores.sum(), 1) + + # Cls loss + # loss[1] = self.varifocal_loss(pred_scores, target_scores, target_labels) / target_scores_sum # VFL way + loss[1] = self.bce(pred_scores, target_scores.to(dtype)).sum() / target_scores_sum # BCE + + # Bbox loss + if fg_mask.sum(): + target_bboxes[..., :4] /= stride_tensor + loss[0], loss[2] = self.bbox_loss( + pred_distri, pred_bboxes, anchor_points, target_bboxes, target_scores, target_scores_sum, fg_mask + ) + else: + loss[0] += (pred_angle * 0).sum() + + loss[0] *= self.hyp.box # box gain + loss[1] *= self.hyp.cls # cls gain + loss[2] *= self.hyp.dfl # dfl gain + + return loss.sum() * batch_size, loss.detach() # loss(box, cls, dfl) + + def bbox_decode(self, anchor_points, pred_dist, pred_angle): + """ + Decode predicted object bounding box coordinates from anchor points and distribution. + + Args: + anchor_points (torch.Tensor): Anchor points, (h*w, 2). + pred_dist (torch.Tensor): Predicted rotated distance, (bs, h*w, 4). + pred_angle (torch.Tensor): Predicted angle, (bs, h*w, 1). + + Returns: + (torch.Tensor): Predicted rotated bounding boxes with angles, (bs, h*w, 5). + """ + if self.use_dfl: + b, a, c = pred_dist.shape # batch, anchors, channels + pred_dist = pred_dist.view(b, a, 4, c // 4).softmax(3).matmul(self.proj.type(pred_dist.dtype)) + return torch.cat((dist2rbox(pred_dist, pred_angle, anchor_points), pred_angle), dim=-1) diff --git a/ultralytics/utils/metrics.py b/ultralytics/utils/metrics.py new file mode 100644 index 0000000..cdb4868 --- /dev/null +++ b/ultralytics/utils/metrics.py @@ -0,0 +1,1289 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +"""Model validation metrics.""" + +import math +import warnings +from pathlib import Path + +import matplotlib.pyplot as plt +import numpy as np +import torch + +from ultralytics.utils import LOGGER, SimpleClass, TryExcept, plt_settings + +OKS_SIGMA = ( + np.array([0.26, 0.25, 0.25, 0.35, 0.35, 0.79, 0.79, 0.72, 0.72, 0.62, 0.62, 1.07, 1.07, 0.87, 0.87, 0.89, 0.89]) + / 10.0 +) + + +def bbox_ioa(box1, box2, iou=False, eps=1e-7): + """ + Calculate the intersection over box2 area given box1 and box2. Boxes are in x1y1x2y2 format. + + Args: + box1 (np.ndarray): A numpy array of shape (n, 4) representing n bounding boxes. + box2 (np.ndarray): A numpy array of shape (m, 4) representing m bounding boxes. + iou (bool): Calculate the standard IoU if True else return inter_area/box2_area. + eps (float, optional): A small value to avoid division by zero. Defaults to 1e-7. + + Returns: + (np.ndarray): A numpy array of shape (n, m) representing the intersection over box2 area. + """ + + # Get the coordinates of bounding boxes + b1_x1, b1_y1, b1_x2, b1_y2 = box1.T + b2_x1, b2_y1, b2_x2, b2_y2 = box2.T + + # Intersection area + inter_area = (np.minimum(b1_x2[:, None], b2_x2) - np.maximum(b1_x1[:, None], b2_x1)).clip(0) * ( + np.minimum(b1_y2[:, None], b2_y2) - np.maximum(b1_y1[:, None], b2_y1) + ).clip(0) + + # Box2 area + area = (b2_x2 - b2_x1) * (b2_y2 - b2_y1) + if iou: + box1_area = (b1_x2 - b1_x1) * (b1_y2 - b1_y1) + area = area + box1_area[:, None] - inter_area + + # Intersection over box2 area + return inter_area / (area + eps) + + +def box_iou(box1, box2, eps=1e-7): + """ + Calculate intersection-over-union (IoU) of boxes. Both sets of boxes are expected to be in (x1, y1, x2, y2) format. + Based on https://github.com/pytorch/vision/blob/master/torchvision/ops/boxes.py + + Args: + box1 (torch.Tensor): A tensor of shape (N, 4) representing N bounding boxes. + box2 (torch.Tensor): A tensor of shape (M, 4) representing M bounding boxes. + eps (float, optional): A small value to avoid division by zero. Defaults to 1e-7. + + Returns: + (torch.Tensor): An NxM tensor containing the pairwise IoU values for every element in box1 and box2. + """ + + # inter(N,M) = (rb(N,M,2) - lt(N,M,2)).clamp(0).prod(2) + (a1, a2), (b1, b2) = box1.unsqueeze(1).chunk(2, 2), box2.unsqueeze(0).chunk(2, 2) + inter = (torch.min(a2, b2) - torch.max(a1, b1)).clamp_(0).prod(2) + + # IoU = inter / (area1 + area2 - inter) + return inter / ((a2 - a1).prod(2) + (b2 - b1).prod(2) - inter + eps) + + +def bbox_iou(box1, box2, xywh=True, GIoU=False, DIoU=False, CIoU=False, eps=1e-7): + """ + Calculate Intersection over Union (IoU) of box1(1, 4) to box2(n, 4). + + Args: + box1 (torch.Tensor): A tensor representing a single bounding box with shape (1, 4). + box2 (torch.Tensor): A tensor representing n bounding boxes with shape (n, 4). + xywh (bool, optional): If True, input boxes are in (x, y, w, h) format. If False, input boxes are in + (x1, y1, x2, y2) format. Defaults to True. + GIoU (bool, optional): If True, calculate Generalized IoU. Defaults to False. + DIoU (bool, optional): If True, calculate Distance IoU. Defaults to False. + CIoU (bool, optional): If True, calculate Complete IoU. Defaults to False. + eps (float, optional): A small value to avoid division by zero. Defaults to 1e-7. + + Returns: + (torch.Tensor): IoU, GIoU, DIoU, or CIoU values depending on the specified flags. + """ + + # Get the coordinates of bounding boxes + if xywh: # transform from xywh to xyxy + (x1, y1, w1, h1), (x2, y2, w2, h2) = box1.chunk(4, -1), box2.chunk(4, -1) + w1_, h1_, w2_, h2_ = w1 / 2, h1 / 2, w2 / 2, h2 / 2 + b1_x1, b1_x2, b1_y1, b1_y2 = x1 - w1_, x1 + w1_, y1 - h1_, y1 + h1_ + b2_x1, b2_x2, b2_y1, b2_y2 = x2 - w2_, x2 + w2_, y2 - h2_, y2 + h2_ + else: # x1, y1, x2, y2 = box1 + b1_x1, b1_y1, b1_x2, b1_y2 = box1.chunk(4, -1) + b2_x1, b2_y1, b2_x2, b2_y2 = box2.chunk(4, -1) + w1, h1 = b1_x2 - b1_x1, b1_y2 - b1_y1 + eps + w2, h2 = b2_x2 - b2_x1, b2_y2 - b2_y1 + eps + + # Intersection area + inter = (b1_x2.minimum(b2_x2) - b1_x1.maximum(b2_x1)).clamp_(0) * ( + b1_y2.minimum(b2_y2) - b1_y1.maximum(b2_y1) + ).clamp_(0) + + # Union Area + union = w1 * h1 + w2 * h2 - inter + eps + + # IoU + iou = inter / union + if CIoU or DIoU or GIoU: + cw = b1_x2.maximum(b2_x2) - b1_x1.minimum(b2_x1) # convex (smallest enclosing box) width + ch = b1_y2.maximum(b2_y2) - b1_y1.minimum(b2_y1) # convex height + if CIoU or DIoU: # Distance or Complete IoU https://arxiv.org/abs/1911.08287v1 + c2 = cw.pow(2) + ch.pow(2) + eps # convex diagonal squared + rho2 = ( + (b2_x1 + b2_x2 - b1_x1 - b1_x2).pow(2) + (b2_y1 + b2_y2 - b1_y1 - b1_y2).pow(2) + ) / 4 # center dist**2 + if CIoU: # https://github.com/Zzh-tju/DIoU-SSD-pytorch/blob/master/utils/box/box_utils.py#L47 + v = (4 / math.pi**2) * ((w2 / h2).atan() - (w1 / h1).atan()).pow(2) + with torch.no_grad(): + alpha = v / (v - iou + (1 + eps)) + return iou - (rho2 / c2 + v * alpha) # CIoU + return iou - rho2 / c2 # DIoU + c_area = cw * ch + eps # convex area + return iou - (c_area - union) / c_area # GIoU https://arxiv.org/pdf/1902.09630.pdf + return iou # IoU + + +def mask_iou(mask1, mask2, eps=1e-7): + """ + Calculate masks IoU. + + Args: + mask1 (torch.Tensor): A tensor of shape (N, n) where N is the number of ground truth objects and n is the + product of image width and height. + mask2 (torch.Tensor): A tensor of shape (M, n) where M is the number of predicted objects and n is the + product of image width and height. + eps (float, optional): A small value to avoid division by zero. Defaults to 1e-7. + + Returns: + (torch.Tensor): A tensor of shape (N, M) representing masks IoU. + """ + intersection = torch.matmul(mask1, mask2.T).clamp_(0) + union = (mask1.sum(1)[:, None] + mask2.sum(1)[None]) - intersection # (area1 + area2) - intersection + return intersection / (union + eps) + + +def kpt_iou(kpt1, kpt2, area, sigma, eps=1e-7): + """ + Calculate Object Keypoint Similarity (OKS). + + Args: + kpt1 (torch.Tensor): A tensor of shape (N, 17, 3) representing ground truth keypoints. + kpt2 (torch.Tensor): A tensor of shape (M, 17, 3) representing predicted keypoints. + area (torch.Tensor): A tensor of shape (N,) representing areas from ground truth. + sigma (list): A list containing 17 values representing keypoint scales. + eps (float, optional): A small value to avoid division by zero. Defaults to 1e-7. + + Returns: + (torch.Tensor): A tensor of shape (N, M) representing keypoint similarities. + """ + d = (kpt1[:, None, :, 0] - kpt2[..., 0]).pow(2) + (kpt1[:, None, :, 1] - kpt2[..., 1]).pow(2) # (N, M, 17) + sigma = torch.tensor(sigma, device=kpt1.device, dtype=kpt1.dtype) # (17, ) + kpt_mask = kpt1[..., 2] != 0 # (N, 17) + e = d / ((2 * sigma).pow(2) * (area[:, None, None] + eps) * 2) # from cocoeval + # e = d / ((area[None, :, None] + eps) * sigma) ** 2 / 2 # from formula + return ((-e).exp() * kpt_mask[:, None]).sum(-1) / (kpt_mask.sum(-1)[:, None] + eps) + + +def _get_covariance_matrix(boxes): + """ + Generating covariance matrix from obbs. + + Args: + boxes (torch.Tensor): A tensor of shape (N, 5) representing rotated bounding boxes, with xywhr format. + + Returns: + (torch.Tensor): Covariance metrixs corresponding to original rotated bounding boxes. + """ + # Gaussian bounding boxes, ignore the center points (the first two columns) because they are not needed here. + gbbs = torch.cat((boxes[:, 2:4].pow(2) / 12, boxes[:, 4:]), dim=-1) + a, b, c = gbbs.split(1, dim=-1) + cos = c.cos() + sin = c.sin() + cos2 = cos.pow(2) + sin2 = sin.pow(2) + return a * cos2 + b * sin2, a * sin2 + b * cos2, (a - b) * cos * sin + + +def probiou(obb1, obb2, CIoU=False, eps=1e-7): + """ + Calculate the prob IoU between oriented bounding boxes, https://arxiv.org/pdf/2106.06072v1.pdf. + + Args: + obb1 (torch.Tensor): A tensor of shape (N, 5) representing ground truth obbs, with xywhr format. + obb2 (torch.Tensor): A tensor of shape (N, 5) representing predicted obbs, with xywhr format. + eps (float, optional): A small value to avoid division by zero. Defaults to 1e-7. + + Returns: + (torch.Tensor): A tensor of shape (N, ) representing obb similarities. + """ + x1, y1 = obb1[..., :2].split(1, dim=-1) + x2, y2 = obb2[..., :2].split(1, dim=-1) + a1, b1, c1 = _get_covariance_matrix(obb1) + a2, b2, c2 = _get_covariance_matrix(obb2) + + t1 = ( + ((a1 + a2) * (y1 - y2).pow(2) + (b1 + b2) * (x1 - x2).pow(2)) / ((a1 + a2) * (b1 + b2) - (c1 + c2).pow(2) + eps) + ) * 0.25 + t2 = (((c1 + c2) * (x2 - x1) * (y1 - y2)) / ((a1 + a2) * (b1 + b2) - (c1 + c2).pow(2) + eps)) * 0.5 + t3 = ( + ((a1 + a2) * (b1 + b2) - (c1 + c2).pow(2)) + / (4 * ((a1 * b1 - c1.pow(2)).clamp_(0) * (a2 * b2 - c2.pow(2)).clamp_(0)).sqrt() + eps) + + eps + ).log() * 0.5 + bd = (t1 + t2 + t3).clamp(eps, 100.0) + hd = (1.0 - (-bd).exp() + eps).sqrt() + iou = 1 - hd + if CIoU: # only include the wh aspect ratio part + w1, h1 = obb1[..., 2:4].split(1, dim=-1) + w2, h2 = obb2[..., 2:4].split(1, dim=-1) + v = (4 / math.pi**2) * ((w2 / h2).atan() - (w1 / h1).atan()).pow(2) + with torch.no_grad(): + alpha = v / (v - iou + (1 + eps)) + return iou - v * alpha # CIoU + return iou + + +def batch_probiou(obb1, obb2, eps=1e-7): + """ + Calculate the prob IoU between oriented bounding boxes, https://arxiv.org/pdf/2106.06072v1.pdf. + + Args: + obb1 (torch.Tensor | np.ndarray): A tensor of shape (N, 5) representing ground truth obbs, with xywhr format. + obb2 (torch.Tensor | np.ndarray): A tensor of shape (M, 5) representing predicted obbs, with xywhr format. + eps (float, optional): A small value to avoid division by zero. Defaults to 1e-7. + + Returns: + (torch.Tensor): A tensor of shape (N, M) representing obb similarities. + """ + obb1 = torch.from_numpy(obb1) if isinstance(obb1, np.ndarray) else obb1 + obb2 = torch.from_numpy(obb2) if isinstance(obb2, np.ndarray) else obb2 + + x1, y1 = obb1[..., :2].split(1, dim=-1) + x2, y2 = (x.squeeze(-1)[None] for x in obb2[..., :2].split(1, dim=-1)) + a1, b1, c1 = _get_covariance_matrix(obb1) + a2, b2, c2 = (x.squeeze(-1)[None] for x in _get_covariance_matrix(obb2)) + + t1 = ( + ((a1 + a2) * (y1 - y2).pow(2) + (b1 + b2) * (x1 - x2).pow(2)) / ((a1 + a2) * (b1 + b2) - (c1 + c2).pow(2) + eps) + ) * 0.25 + t2 = (((c1 + c2) * (x2 - x1) * (y1 - y2)) / ((a1 + a2) * (b1 + b2) - (c1 + c2).pow(2) + eps)) * 0.5 + t3 = ( + ((a1 + a2) * (b1 + b2) - (c1 + c2).pow(2)) + / (4 * ((a1 * b1 - c1.pow(2)).clamp_(0) * (a2 * b2 - c2.pow(2)).clamp_(0)).sqrt() + eps) + + eps + ).log() * 0.5 + bd = (t1 + t2 + t3).clamp(eps, 100.0) + hd = (1.0 - (-bd).exp() + eps).sqrt() + return 1 - hd + + +def smooth_BCE(eps=0.1): + """ + Computes smoothed positive and negative Binary Cross-Entropy targets. + + This function calculates positive and negative label smoothing BCE targets based on a given epsilon value. + For implementation details, refer to https://github.com/ultralytics/yolov3/issues/238#issuecomment-598028441. + + Args: + eps (float, optional): The epsilon value for label smoothing. Defaults to 0.1. + + Returns: + (tuple): A tuple containing the positive and negative label smoothing BCE targets. + """ + return 1.0 - 0.5 * eps, 0.5 * eps + + +class ConfusionMatrix: + """ + A class for calculating and updating a confusion matrix for object detection and classification tasks. + + Attributes: + task (str): The type of task, either 'detect' or 'classify'. + matrix (np.ndarray): The confusion matrix, with dimensions depending on the task. + nc (int): The number of classes. + conf (float): The confidence threshold for detections. + iou_thres (float): The Intersection over Union threshold. + """ + + def __init__(self, nc, conf=0.25, iou_thres=0.45, task="detect"): + """Initialize attributes for the YOLO model.""" + self.task = task + self.matrix = np.zeros((nc + 1, nc + 1)) if self.task == "detect" else np.zeros((nc, nc)) + self.nc = nc # number of classes + self.conf = 0.25 if conf in {None, 0.001} else conf # apply 0.25 if default val conf is passed + self.iou_thres = iou_thres + + def process_cls_preds(self, preds, targets): + """ + Update confusion matrix for classification task. + + Args: + preds (Array[N, min(nc,5)]): Predicted class labels. + targets (Array[N, 1]): Ground truth class labels. + """ + preds, targets = torch.cat(preds)[:, 0], torch.cat(targets) + for p, t in zip(preds.cpu().numpy(), targets.cpu().numpy()): + self.matrix[p][t] += 1 + + def process_batch(self, detections, gt_bboxes, gt_cls): + """ + Update confusion matrix for object detection task. + + Args: + detections (Array[N, 6] | Array[N, 7]): Detected bounding boxes and their associated information. + Each row should contain (x1, y1, x2, y2, conf, class) + or with an additional element `angle` when it's obb. + gt_bboxes (Array[M, 4]| Array[N, 5]): Ground truth bounding boxes with xyxy/xyxyr format. + gt_cls (Array[M]): The class labels. + """ + if gt_cls.shape[0] == 0: # Check if labels is empty + if detections is not None: + detections = detections[detections[:, 4] > self.conf] + detection_classes = detections[:, 5].int() + for dc in detection_classes: + self.matrix[dc, self.nc] += 1 # false positives + return + if detections is None: + gt_classes = gt_cls.int() + for gc in gt_classes: + self.matrix[self.nc, gc] += 1 # background FN + return + + detections = detections[detections[:, 4] > self.conf] + gt_classes = gt_cls.int() + detection_classes = detections[:, 5].int() + is_obb = detections.shape[1] == 7 and gt_bboxes.shape[1] == 5 # with additional `angle` dimension + iou = ( + batch_probiou(gt_bboxes, torch.cat([detections[:, :4], detections[:, -1:]], dim=-1)) + if is_obb + else box_iou(gt_bboxes, detections[:, :4]) + ) + + x = torch.where(iou > self.iou_thres) + if x[0].shape[0]: + matches = torch.cat((torch.stack(x, 1), iou[x[0], x[1]][:, None]), 1).cpu().numpy() + if x[0].shape[0] > 1: + matches = matches[matches[:, 2].argsort()[::-1]] + matches = matches[np.unique(matches[:, 1], return_index=True)[1]] + matches = matches[matches[:, 2].argsort()[::-1]] + matches = matches[np.unique(matches[:, 0], return_index=True)[1]] + else: + matches = np.zeros((0, 3)) + + n = matches.shape[0] > 0 + m0, m1, _ = matches.transpose().astype(int) + for i, gc in enumerate(gt_classes): + j = m0 == i + if n and sum(j) == 1: + self.matrix[detection_classes[m1[j]], gc] += 1 # correct + else: + self.matrix[self.nc, gc] += 1 # true background + + if n: + for i, dc in enumerate(detection_classes): + if not any(m1 == i): + self.matrix[dc, self.nc] += 1 # predicted background + + def matrix(self): + """Returns the confusion matrix.""" + return self.matrix + + def tp_fp(self): + """Returns true positives and false positives.""" + tp = self.matrix.diagonal() # true positives + fp = self.matrix.sum(1) - tp # false positives + # fn = self.matrix.sum(0) - tp # false negatives (missed detections) + return (tp[:-1], fp[:-1]) if self.task == "detect" else (tp, fp) # remove background class if task=detect + + @TryExcept("WARNING ⚠️ ConfusionMatrix plot failure") + @plt_settings() + def plot(self, normalize=True, save_dir="", names=(), on_plot=None): + """ + Plot the confusion matrix using seaborn and save it to a file. + + Args: + normalize (bool): Whether to normalize the confusion matrix. + save_dir (str): Directory where the plot will be saved. + names (tuple): Names of classes, used as labels on the plot. + on_plot (func): An optional callback to pass plots path and data when they are rendered. + """ + import seaborn # scope for faster 'import ultralytics' + + array = self.matrix / ((self.matrix.sum(0).reshape(1, -1) + 1e-9) if normalize else 1) # normalize columns + array[array < 0.005] = np.nan # don't annotate (would appear as 0.00) + + fig, ax = plt.subplots(1, 1, figsize=(12, 9), tight_layout=True) + nc, nn = self.nc, len(names) # number of classes, names + seaborn.set_theme(font_scale=1.0 if nc < 50 else 0.8) # for label size + labels = (0 < nn < 99) and (nn == nc) # apply names to ticklabels + ticklabels = (list(names) + ["background"]) if labels else "auto" + with warnings.catch_warnings(): + warnings.simplefilter("ignore") # suppress empty matrix RuntimeWarning: All-NaN slice encountered + seaborn.heatmap( + array, + ax=ax, + annot=nc < 30, + annot_kws={"size": 8}, + cmap="Blues", + fmt=".2f" if normalize else ".0f", + square=True, + vmin=0.0, + xticklabels=ticklabels, + yticklabels=ticklabels, + ).set_facecolor((1, 1, 1)) + title = "Confusion Matrix" + " Normalized" * normalize + ax.set_xlabel("True") + ax.set_ylabel("Predicted") + ax.set_title(title) + plot_fname = Path(save_dir) / f'{title.lower().replace(" ", "_")}.png' + fig.savefig(plot_fname, dpi=250) + plt.close(fig) + if on_plot: + on_plot(plot_fname) + + def print(self): + """Print the confusion matrix to the console.""" + for i in range(self.nc + 1): + LOGGER.info(" ".join(map(str, self.matrix[i]))) + + +def smooth(y, f=0.05): + """Box filter of fraction f.""" + nf = round(len(y) * f * 2) // 2 + 1 # number of filter elements (must be odd) + p = np.ones(nf // 2) # ones padding + yp = np.concatenate((p * y[0], y, p * y[-1]), 0) # y padded + return np.convolve(yp, np.ones(nf) / nf, mode="valid") # y-smoothed + + +@plt_settings() +def plot_pr_curve(px, py, ap, save_dir=Path("pr_curve.png"), names=(), on_plot=None): + """Plots a precision-recall curve.""" + fig, ax = plt.subplots(1, 1, figsize=(9, 6), tight_layout=True) + py = np.stack(py, axis=1) + + if 0 < len(names) < 21: # display per-class legend if < 21 classes + for i, y in enumerate(py.T): + ax.plot(px, y, linewidth=1, label=f"{names[i]} {ap[i, 0]:.3f}") # plot(recall, precision) + else: + ax.plot(px, py, linewidth=1, color="grey") # plot(recall, precision) + + ax.plot(px, py.mean(1), linewidth=3, color="blue", label="all classes %.3f mAP@0.5" % ap[:, 0].mean()) + ax.set_xlabel("Recall") + ax.set_ylabel("Precision") + ax.set_xlim(0, 1) + ax.set_ylim(0, 1) + ax.legend(bbox_to_anchor=(1.04, 1), loc="upper left") + ax.set_title("Precision-Recall Curve") + fig.savefig(save_dir, dpi=250) + plt.close(fig) + if on_plot: + on_plot(save_dir) + + +@plt_settings() +def plot_mc_curve(px, py, save_dir=Path("mc_curve.png"), names=(), xlabel="Confidence", ylabel="Metric", on_plot=None): + """Plots a metric-confidence curve.""" + fig, ax = plt.subplots(1, 1, figsize=(9, 6), tight_layout=True) + + if 0 < len(names) < 21: # display per-class legend if < 21 classes + for i, y in enumerate(py): + ax.plot(px, y, linewidth=1, label=f"{names[i]}") # plot(confidence, metric) + else: + ax.plot(px, py.T, linewidth=1, color="grey") # plot(confidence, metric) + + y = smooth(py.mean(0), 0.05) + ax.plot(px, y, linewidth=3, color="blue", label=f"all classes {y.max():.2f} at {px[y.argmax()]:.3f}") + ax.set_xlabel(xlabel) + ax.set_ylabel(ylabel) + ax.set_xlim(0, 1) + ax.set_ylim(0, 1) + ax.legend(bbox_to_anchor=(1.04, 1), loc="upper left") + ax.set_title(f"{ylabel}-Confidence Curve") + fig.savefig(save_dir, dpi=250) + plt.close(fig) + if on_plot: + on_plot(save_dir) + + +def compute_ap(recall, precision): + """ + Compute the average precision (AP) given the recall and precision curves. + + Args: + recall (list): The recall curve. + precision (list): The precision curve. + + Returns: + (float): Average precision. + (np.ndarray): Precision envelope curve. + (np.ndarray): Modified recall curve with sentinel values added at the beginning and end. + """ + + # Append sentinel values to beginning and end + mrec = np.concatenate(([0.0], recall, [1.0])) + mpre = np.concatenate(([1.0], precision, [0.0])) + + # Compute the precision envelope + mpre = np.flip(np.maximum.accumulate(np.flip(mpre))) + + # Integrate area under curve + method = "interp" # methods: 'continuous', 'interp' + if method == "interp": + x = np.linspace(0, 1, 101) # 101-point interp (COCO) + ap = np.trapz(np.interp(x, mrec, mpre), x) # integrate + else: # 'continuous' + i = np.where(mrec[1:] != mrec[:-1])[0] # points where x-axis (recall) changes + ap = np.sum((mrec[i + 1] - mrec[i]) * mpre[i + 1]) # area under curve + + return ap, mpre, mrec + + +def ap_per_class( + tp, conf, pred_cls, target_cls, plot=False, on_plot=None, save_dir=Path(), names=(), eps=1e-16, prefix="" +): + """ + Computes the average precision per class for object detection evaluation. + + Args: + tp (np.ndarray): Binary array indicating whether the detection is correct (True) or not (False). + conf (np.ndarray): Array of confidence scores of the detections. + pred_cls (np.ndarray): Array of predicted classes of the detections. + target_cls (np.ndarray): Array of true classes of the detections. + plot (bool, optional): Whether to plot PR curves or not. Defaults to False. + on_plot (func, optional): A callback to pass plots path and data when they are rendered. Defaults to None. + save_dir (Path, optional): Directory to save the PR curves. Defaults to an empty path. + names (tuple, optional): Tuple of class names to plot PR curves. Defaults to an empty tuple. + eps (float, optional): A small value to avoid division by zero. Defaults to 1e-16. + prefix (str, optional): A prefix string for saving the plot files. Defaults to an empty string. + + Returns: + (tuple): A tuple of six arrays and one array of unique classes, where: + tp (np.ndarray): True positive counts at threshold given by max F1 metric for each class.Shape: (nc,). + fp (np.ndarray): False positive counts at threshold given by max F1 metric for each class. Shape: (nc,). + p (np.ndarray): Precision values at threshold given by max F1 metric for each class. Shape: (nc,). + r (np.ndarray): Recall values at threshold given by max F1 metric for each class. Shape: (nc,). + f1 (np.ndarray): F1-score values at threshold given by max F1 metric for each class. Shape: (nc,). + ap (np.ndarray): Average precision for each class at different IoU thresholds. Shape: (nc, 10). + unique_classes (np.ndarray): An array of unique classes that have data. Shape: (nc,). + p_curve (np.ndarray): Precision curves for each class. Shape: (nc, 1000). + r_curve (np.ndarray): Recall curves for each class. Shape: (nc, 1000). + f1_curve (np.ndarray): F1-score curves for each class. Shape: (nc, 1000). + x (np.ndarray): X-axis values for the curves. Shape: (1000,). + prec_values: Precision values at mAP@0.5 for each class. Shape: (nc, 1000). + """ + + # Sort by objectness + i = np.argsort(-conf) + tp, conf, pred_cls = tp[i], conf[i], pred_cls[i] + + # Find unique classes + unique_classes, nt = np.unique(target_cls, return_counts=True) + nc = unique_classes.shape[0] # number of classes, number of detections + + # Create Precision-Recall curve and compute AP for each class + x, prec_values = np.linspace(0, 1, 1000), [] + + # Average precision, precision and recall curves + ap, p_curve, r_curve = np.zeros((nc, tp.shape[1])), np.zeros((nc, 1000)), np.zeros((nc, 1000)) + for ci, c in enumerate(unique_classes): + i = pred_cls == c + n_l = nt[ci] # number of labels + n_p = i.sum() # number of predictions + if n_p == 0 or n_l == 0: + continue + + # Accumulate FPs and TPs + fpc = (1 - tp[i]).cumsum(0) + tpc = tp[i].cumsum(0) + + # Recall + recall = tpc / (n_l + eps) # recall curve + r_curve[ci] = np.interp(-x, -conf[i], recall[:, 0], left=0) # negative x, xp because xp decreases + + # Precision + precision = tpc / (tpc + fpc) # precision curve + p_curve[ci] = np.interp(-x, -conf[i], precision[:, 0], left=1) # p at pr_score + + # AP from recall-precision curve + for j in range(tp.shape[1]): + ap[ci, j], mpre, mrec = compute_ap(recall[:, j], precision[:, j]) + if plot and j == 0: + prec_values.append(np.interp(x, mrec, mpre)) # precision at mAP@0.5 + + prec_values = np.array(prec_values) # (nc, 1000) + + # Compute F1 (harmonic mean of precision and recall) + f1_curve = 2 * p_curve * r_curve / (p_curve + r_curve + eps) + names = [v for k, v in names.items() if k in unique_classes] # list: only classes that have data + names = dict(enumerate(names)) # to dict + if plot: + plot_pr_curve(x, prec_values, ap, save_dir / f"{prefix}PR_curve.png", names, on_plot=on_plot) + plot_mc_curve(x, f1_curve, save_dir / f"{prefix}F1_curve.png", names, ylabel="F1", on_plot=on_plot) + plot_mc_curve(x, p_curve, save_dir / f"{prefix}P_curve.png", names, ylabel="Precision", on_plot=on_plot) + plot_mc_curve(x, r_curve, save_dir / f"{prefix}R_curve.png", names, ylabel="Recall", on_plot=on_plot) + + i = smooth(f1_curve.mean(0), 0.1).argmax() # max F1 index + p, r, f1 = p_curve[:, i], r_curve[:, i], f1_curve[:, i] # max-F1 precision, recall, F1 values + tp = (r * nt).round() # true positives + fp = (tp / (p + eps) - tp).round() # false positives + return tp, fp, p, r, f1, ap, unique_classes.astype(int), p_curve, r_curve, f1_curve, x, prec_values + + +class Metric(SimpleClass): + """ + Class for computing evaluation metrics for YOLOv8 model. + + Attributes: + p (list): Precision for each class. Shape: (nc,). + r (list): Recall for each class. Shape: (nc,). + f1 (list): F1 score for each class. Shape: (nc,). + all_ap (list): AP scores for all classes and all IoU thresholds. Shape: (nc, 10). + ap_class_index (list): Index of class for each AP score. Shape: (nc,). + nc (int): Number of classes. + + Methods: + ap50(): AP at IoU threshold of 0.5 for all classes. Returns: List of AP scores. Shape: (nc,) or []. + ap(): AP at IoU thresholds from 0.5 to 0.95 for all classes. Returns: List of AP scores. Shape: (nc,) or []. + mp(): Mean precision of all classes. Returns: Float. + mr(): Mean recall of all classes. Returns: Float. + map50(): Mean AP at IoU threshold of 0.5 for all classes. Returns: Float. + map75(): Mean AP at IoU threshold of 0.75 for all classes. Returns: Float. + map(): Mean AP at IoU thresholds from 0.5 to 0.95 for all classes. Returns: Float. + mean_results(): Mean of results, returns mp, mr, map50, map. + class_result(i): Class-aware result, returns p[i], r[i], ap50[i], ap[i]. + maps(): mAP of each class. Returns: Array of mAP scores, shape: (nc,). + fitness(): Model fitness as a weighted combination of metrics. Returns: Float. + update(results): Update metric attributes with new evaluation results. + """ + + def __init__(self) -> None: + """Initializes a Metric instance for computing evaluation metrics for the YOLOv8 model.""" + self.p = [] # (nc, ) + self.r = [] # (nc, ) + self.f1 = [] # (nc, ) + self.all_ap = [] # (nc, 10) + self.ap_class_index = [] # (nc, ) + self.nc = 0 + + @property + def ap50(self): + """ + Returns the Average Precision (AP) at an IoU threshold of 0.5 for all classes. + + Returns: + (np.ndarray, list): Array of shape (nc,) with AP50 values per class, or an empty list if not available. + """ + return self.all_ap[:, 0] if len(self.all_ap) else [] + + @property + def ap(self): + """ + Returns the Average Precision (AP) at an IoU threshold of 0.5-0.95 for all classes. + + Returns: + (np.ndarray, list): Array of shape (nc,) with AP50-95 values per class, or an empty list if not available. + """ + return self.all_ap.mean(1) if len(self.all_ap) else [] + + @property + def mp(self): + """ + Returns the Mean Precision of all classes. + + Returns: + (float): The mean precision of all classes. + """ + return self.p.mean() if len(self.p) else 0.0 + + @property + def mr(self): + """ + Returns the Mean Recall of all classes. + + Returns: + (float): The mean recall of all classes. + """ + return self.r.mean() if len(self.r) else 0.0 + + @property + def map50(self): + """ + Returns the mean Average Precision (mAP) at an IoU threshold of 0.5. + + Returns: + (float): The mAP at an IoU threshold of 0.5. + """ + return self.all_ap[:, 0].mean() if len(self.all_ap) else 0.0 + + @property + def map75(self): + """ + Returns the mean Average Precision (mAP) at an IoU threshold of 0.75. + + Returns: + (float): The mAP at an IoU threshold of 0.75. + """ + return self.all_ap[:, 5].mean() if len(self.all_ap) else 0.0 + + @property + def map(self): + """ + Returns the mean Average Precision (mAP) over IoU thresholds of 0.5 - 0.95 in steps of 0.05. + + Returns: + (float): The mAP over IoU thresholds of 0.5 - 0.95 in steps of 0.05. + """ + return self.all_ap.mean() if len(self.all_ap) else 0.0 + + def mean_results(self): + """Mean of results, return mp, mr, map50, map.""" + return [self.mp, self.mr, self.map50, self.map] + + def class_result(self, i): + """Class-aware result, return p[i], r[i], ap50[i], ap[i].""" + return self.p[i], self.r[i], self.ap50[i], self.ap[i] + + @property + def maps(self): + """MAP of each class.""" + maps = np.zeros(self.nc) + self.map + for i, c in enumerate(self.ap_class_index): + maps[c] = self.ap[i] + return maps + + def fitness(self): + """Model fitness as a weighted combination of metrics.""" + w = [0.0, 0.0, 0.1, 0.9] # weights for [P, R, mAP@0.5, mAP@0.5:0.95] + return (np.array(self.mean_results()) * w).sum() + + def update(self, results): + """ + Updates the evaluation metrics of the model with a new set of results. + + Args: + results (tuple): A tuple containing the following evaluation metrics: + - p (list): Precision for each class. Shape: (nc,). + - r (list): Recall for each class. Shape: (nc,). + - f1 (list): F1 score for each class. Shape: (nc,). + - all_ap (list): AP scores for all classes and all IoU thresholds. Shape: (nc, 10). + - ap_class_index (list): Index of class for each AP score. Shape: (nc,). + + Side Effects: + Updates the class attributes `self.p`, `self.r`, `self.f1`, `self.all_ap`, and `self.ap_class_index` based + on the values provided in the `results` tuple. + """ + ( + self.p, + self.r, + self.f1, + self.all_ap, + self.ap_class_index, + self.p_curve, + self.r_curve, + self.f1_curve, + self.px, + self.prec_values, + ) = results + + @property + def curves(self): + """Returns a list of curves for accessing specific metrics curves.""" + return [] + + @property + def curves_results(self): + """Returns a list of curves for accessing specific metrics curves.""" + return [ + [self.px, self.prec_values, "Recall", "Precision"], + [self.px, self.f1_curve, "Confidence", "F1"], + [self.px, self.p_curve, "Confidence", "Precision"], + [self.px, self.r_curve, "Confidence", "Recall"], + ] + + +class DetMetrics(SimpleClass): + """ + This class is a utility class for computing detection metrics such as precision, recall, and mean average precision + (mAP) of an object detection model. + + Args: + save_dir (Path): A path to the directory where the output plots will be saved. Defaults to current directory. + plot (bool): A flag that indicates whether to plot precision-recall curves for each class. Defaults to False. + on_plot (func): An optional callback to pass plots path and data when they are rendered. Defaults to None. + names (tuple of str): A tuple of strings that represents the names of the classes. Defaults to an empty tuple. + + Attributes: + save_dir (Path): A path to the directory where the output plots will be saved. + plot (bool): A flag that indicates whether to plot the precision-recall curves for each class. + on_plot (func): An optional callback to pass plots path and data when they are rendered. + names (tuple of str): A tuple of strings that represents the names of the classes. + box (Metric): An instance of the Metric class for storing the results of the detection metrics. + speed (dict): A dictionary for storing the execution time of different parts of the detection process. + + Methods: + process(tp, conf, pred_cls, target_cls): Updates the metric results with the latest batch of predictions. + keys: Returns a list of keys for accessing the computed detection metrics. + mean_results: Returns a list of mean values for the computed detection metrics. + class_result(i): Returns a list of values for the computed detection metrics for a specific class. + maps: Returns a dictionary of mean average precision (mAP) values for different IoU thresholds. + fitness: Computes the fitness score based on the computed detection metrics. + ap_class_index: Returns a list of class indices sorted by their average precision (AP) values. + results_dict: Returns a dictionary that maps detection metric keys to their computed values. + curves: TODO + curves_results: TODO + """ + + def __init__(self, save_dir=Path("."), plot=False, on_plot=None, names=()) -> None: + """Initialize a DetMetrics instance with a save directory, plot flag, callback function, and class names.""" + self.save_dir = save_dir + self.plot = plot + self.on_plot = on_plot + self.names = names + self.box = Metric() + self.speed = {"preprocess": 0.0, "inference": 0.0, "loss": 0.0, "postprocess": 0.0} + self.task = "detect" + + def process(self, tp, conf, pred_cls, target_cls): + """Process predicted results for object detection and update metrics.""" + results = ap_per_class( + tp, + conf, + pred_cls, + target_cls, + plot=self.plot, + save_dir=self.save_dir, + names=self.names, + on_plot=self.on_plot, + )[2:] + self.box.nc = len(self.names) + self.box.update(results) + + @property + def keys(self): + """Returns a list of keys for accessing specific metrics.""" + return ["metrics/precision(B)", "metrics/recall(B)", "metrics/mAP50(B)", "metrics/mAP50-95(B)"] + + def mean_results(self): + """Calculate mean of detected objects & return precision, recall, mAP50, and mAP50-95.""" + return self.box.mean_results() + + def class_result(self, i): + """Return the result of evaluating the performance of an object detection model on a specific class.""" + return self.box.class_result(i) + + @property + def maps(self): + """Returns mean Average Precision (mAP) scores per class.""" + return self.box.maps + + @property + def fitness(self): + """Returns the fitness of box object.""" + return self.box.fitness() + + @property + def ap_class_index(self): + """Returns the average precision index per class.""" + return self.box.ap_class_index + + @property + def results_dict(self): + """Returns dictionary of computed performance metrics and statistics.""" + return dict(zip(self.keys + ["fitness"], self.mean_results() + [self.fitness])) + + @property + def curves(self): + """Returns a list of curves for accessing specific metrics curves.""" + return ["Precision-Recall(B)", "F1-Confidence(B)", "Precision-Confidence(B)", "Recall-Confidence(B)"] + + @property + def curves_results(self): + """Returns dictionary of computed performance metrics and statistics.""" + return self.box.curves_results + + +class SegmentMetrics(SimpleClass): + """ + Calculates and aggregates detection and segmentation metrics over a given set of classes. + + Args: + save_dir (Path): Path to the directory where the output plots should be saved. Default is the current directory. + plot (bool): Whether to save the detection and segmentation plots. Default is False. + on_plot (func): An optional callback to pass plots path and data when they are rendered. Defaults to None. + names (list): List of class names. Default is an empty list. + + Attributes: + save_dir (Path): Path to the directory where the output plots should be saved. + plot (bool): Whether to save the detection and segmentation plots. + on_plot (func): An optional callback to pass plots path and data when they are rendered. + names (list): List of class names. + box (Metric): An instance of the Metric class to calculate box detection metrics. + seg (Metric): An instance of the Metric class to calculate mask segmentation metrics. + speed (dict): Dictionary to store the time taken in different phases of inference. + + Methods: + process(tp_m, tp_b, conf, pred_cls, target_cls): Processes metrics over the given set of predictions. + mean_results(): Returns the mean of the detection and segmentation metrics over all the classes. + class_result(i): Returns the detection and segmentation metrics of class `i`. + maps: Returns the mean Average Precision (mAP) scores for IoU thresholds ranging from 0.50 to 0.95. + fitness: Returns the fitness scores, which are a single weighted combination of metrics. + ap_class_index: Returns the list of indices of classes used to compute Average Precision (AP). + results_dict: Returns the dictionary containing all the detection and segmentation metrics and fitness score. + """ + + def __init__(self, save_dir=Path("."), plot=False, on_plot=None, names=()) -> None: + """Initialize a SegmentMetrics instance with a save directory, plot flag, callback function, and class names.""" + self.save_dir = save_dir + self.plot = plot + self.on_plot = on_plot + self.names = names + self.box = Metric() + self.seg = Metric() + self.speed = {"preprocess": 0.0, "inference": 0.0, "loss": 0.0, "postprocess": 0.0} + self.task = "segment" + + def process(self, tp, tp_m, conf, pred_cls, target_cls): + """ + Processes the detection and segmentation metrics over the given set of predictions. + + Args: + tp (list): List of True Positive boxes. + tp_m (list): List of True Positive masks. + conf (list): List of confidence scores. + pred_cls (list): List of predicted classes. + target_cls (list): List of target classes. + """ + + results_mask = ap_per_class( + tp_m, + conf, + pred_cls, + target_cls, + plot=self.plot, + on_plot=self.on_plot, + save_dir=self.save_dir, + names=self.names, + prefix="Mask", + )[2:] + self.seg.nc = len(self.names) + self.seg.update(results_mask) + results_box = ap_per_class( + tp, + conf, + pred_cls, + target_cls, + plot=self.plot, + on_plot=self.on_plot, + save_dir=self.save_dir, + names=self.names, + prefix="Box", + )[2:] + self.box.nc = len(self.names) + self.box.update(results_box) + + @property + def keys(self): + """Returns a list of keys for accessing metrics.""" + return [ + "metrics/precision(B)", + "metrics/recall(B)", + "metrics/mAP50(B)", + "metrics/mAP50-95(B)", + "metrics/precision(M)", + "metrics/recall(M)", + "metrics/mAP50(M)", + "metrics/mAP50-95(M)", + ] + + def mean_results(self): + """Return the mean metrics for bounding box and segmentation results.""" + return self.box.mean_results() + self.seg.mean_results() + + def class_result(self, i): + """Returns classification results for a specified class index.""" + return self.box.class_result(i) + self.seg.class_result(i) + + @property + def maps(self): + """Returns mAP scores for object detection and semantic segmentation models.""" + return self.box.maps + self.seg.maps + + @property + def fitness(self): + """Get the fitness score for both segmentation and bounding box models.""" + return self.seg.fitness() + self.box.fitness() + + @property + def ap_class_index(self): + """Boxes and masks have the same ap_class_index.""" + return self.box.ap_class_index + + @property + def results_dict(self): + """Returns results of object detection model for evaluation.""" + return dict(zip(self.keys + ["fitness"], self.mean_results() + [self.fitness])) + + @property + def curves(self): + """Returns a list of curves for accessing specific metrics curves.""" + return [ + "Precision-Recall(B)", + "F1-Confidence(B)", + "Precision-Confidence(B)", + "Recall-Confidence(B)", + "Precision-Recall(M)", + "F1-Confidence(M)", + "Precision-Confidence(M)", + "Recall-Confidence(M)", + ] + + @property + def curves_results(self): + """Returns dictionary of computed performance metrics and statistics.""" + return self.box.curves_results + self.seg.curves_results + + +class PoseMetrics(SegmentMetrics): + """ + Calculates and aggregates detection and pose metrics over a given set of classes. + + Args: + save_dir (Path): Path to the directory where the output plots should be saved. Default is the current directory. + plot (bool): Whether to save the detection and segmentation plots. Default is False. + on_plot (func): An optional callback to pass plots path and data when they are rendered. Defaults to None. + names (list): List of class names. Default is an empty list. + + Attributes: + save_dir (Path): Path to the directory where the output plots should be saved. + plot (bool): Whether to save the detection and segmentation plots. + on_plot (func): An optional callback to pass plots path and data when they are rendered. + names (list): List of class names. + box (Metric): An instance of the Metric class to calculate box detection metrics. + pose (Metric): An instance of the Metric class to calculate mask segmentation metrics. + speed (dict): Dictionary to store the time taken in different phases of inference. + + Methods: + process(tp_m, tp_b, conf, pred_cls, target_cls): Processes metrics over the given set of predictions. + mean_results(): Returns the mean of the detection and segmentation metrics over all the classes. + class_result(i): Returns the detection and segmentation metrics of class `i`. + maps: Returns the mean Average Precision (mAP) scores for IoU thresholds ranging from 0.50 to 0.95. + fitness: Returns the fitness scores, which are a single weighted combination of metrics. + ap_class_index: Returns the list of indices of classes used to compute Average Precision (AP). + results_dict: Returns the dictionary containing all the detection and segmentation metrics and fitness score. + """ + + def __init__(self, save_dir=Path("."), plot=False, on_plot=None, names=()) -> None: + """Initialize the PoseMetrics class with directory path, class names, and plotting options.""" + super().__init__(save_dir, plot, names) + self.save_dir = save_dir + self.plot = plot + self.on_plot = on_plot + self.names = names + self.box = Metric() + self.pose = Metric() + self.speed = {"preprocess": 0.0, "inference": 0.0, "loss": 0.0, "postprocess": 0.0} + self.task = "pose" + + def process(self, tp, tp_p, conf, pred_cls, target_cls): + """ + Processes the detection and pose metrics over the given set of predictions. + + Args: + tp (list): List of True Positive boxes. + tp_p (list): List of True Positive keypoints. + conf (list): List of confidence scores. + pred_cls (list): List of predicted classes. + target_cls (list): List of target classes. + """ + + results_pose = ap_per_class( + tp_p, + conf, + pred_cls, + target_cls, + plot=self.plot, + on_plot=self.on_plot, + save_dir=self.save_dir, + names=self.names, + prefix="Pose", + )[2:] + self.pose.nc = len(self.names) + self.pose.update(results_pose) + results_box = ap_per_class( + tp, + conf, + pred_cls, + target_cls, + plot=self.plot, + on_plot=self.on_plot, + save_dir=self.save_dir, + names=self.names, + prefix="Box", + )[2:] + self.box.nc = len(self.names) + self.box.update(results_box) + + @property + def keys(self): + """Returns list of evaluation metric keys.""" + return [ + "metrics/precision(B)", + "metrics/recall(B)", + "metrics/mAP50(B)", + "metrics/mAP50-95(B)", + "metrics/precision(P)", + "metrics/recall(P)", + "metrics/mAP50(P)", + "metrics/mAP50-95(P)", + ] + + def mean_results(self): + """Return the mean results of box and pose.""" + return self.box.mean_results() + self.pose.mean_results() + + def class_result(self, i): + """Return the class-wise detection results for a specific class i.""" + return self.box.class_result(i) + self.pose.class_result(i) + + @property + def maps(self): + """Returns the mean average precision (mAP) per class for both box and pose detections.""" + return self.box.maps + self.pose.maps + + @property + def fitness(self): + """Computes classification metrics and speed using the `targets` and `pred` inputs.""" + return self.pose.fitness() + self.box.fitness() + + @property + def curves(self): + """Returns a list of curves for accessing specific metrics curves.""" + return [ + "Precision-Recall(B)", + "F1-Confidence(B)", + "Precision-Confidence(B)", + "Recall-Confidence(B)", + "Precision-Recall(P)", + "F1-Confidence(P)", + "Precision-Confidence(P)", + "Recall-Confidence(P)", + ] + + @property + def curves_results(self): + """Returns dictionary of computed performance metrics and statistics.""" + return self.box.curves_results + self.pose.curves_results + + +class ClassifyMetrics(SimpleClass): + """ + Class for computing classification metrics including top-1 and top-5 accuracy. + + Attributes: + top1 (float): The top-1 accuracy. + top5 (float): The top-5 accuracy. + speed (Dict[str, float]): A dictionary containing the time taken for each step in the pipeline. + + Properties: + fitness (float): The fitness of the model, which is equal to top-5 accuracy. + results_dict (Dict[str, Union[float, str]]): A dictionary containing the classification metrics and fitness. + keys (List[str]): A list of keys for the results_dict. + + Methods: + process(targets, pred): Processes the targets and predictions to compute classification metrics. + """ + + def __init__(self) -> None: + """Initialize a ClassifyMetrics instance.""" + self.top1 = 0 + self.top5 = 0 + self.speed = {"preprocess": 0.0, "inference": 0.0, "loss": 0.0, "postprocess": 0.0} + self.task = "classify" + + def process(self, targets, pred): + """Target classes and predicted classes.""" + pred, targets = torch.cat(pred), torch.cat(targets) + correct = (targets[:, None] == pred).float() + acc = torch.stack((correct[:, 0], correct.max(1).values), dim=1) # (top1, top5) accuracy + self.top1, self.top5 = acc.mean(0).tolist() + + @property + def fitness(self): + """Returns mean of top-1 and top-5 accuracies as fitness score.""" + return (self.top1 + self.top5) / 2 + + @property + def results_dict(self): + """Returns a dictionary with model's performance metrics and fitness score.""" + return dict(zip(self.keys + ["fitness"], [self.top1, self.top5, self.fitness])) + + @property + def keys(self): + """Returns a list of keys for the results_dict property.""" + return ["metrics/accuracy_top1", "metrics/accuracy_top5"] + + @property + def curves(self): + """Returns a list of curves for accessing specific metrics curves.""" + return [] + + @property + def curves_results(self): + """Returns a list of curves for accessing specific metrics curves.""" + return [] + + +class OBBMetrics(SimpleClass): + def __init__(self, save_dir=Path("."), plot=False, on_plot=None, names=()) -> None: + self.save_dir = save_dir + self.plot = plot + self.on_plot = on_plot + self.names = names + self.box = Metric() + self.speed = {"preprocess": 0.0, "inference": 0.0, "loss": 0.0, "postprocess": 0.0} + + def process(self, tp, conf, pred_cls, target_cls): + """Process predicted results for object detection and update metrics.""" + results = ap_per_class( + tp, + conf, + pred_cls, + target_cls, + plot=self.plot, + save_dir=self.save_dir, + names=self.names, + on_plot=self.on_plot, + )[2:] + self.box.nc = len(self.names) + self.box.update(results) + + @property + def keys(self): + """Returns a list of keys for accessing specific metrics.""" + return ["metrics/precision(B)", "metrics/recall(B)", "metrics/mAP50(B)", "metrics/mAP50-95(B)"] + + def mean_results(self): + """Calculate mean of detected objects & return precision, recall, mAP50, and mAP50-95.""" + return self.box.mean_results() + + def class_result(self, i): + """Return the result of evaluating the performance of an object detection model on a specific class.""" + return self.box.class_result(i) + + @property + def maps(self): + """Returns mean Average Precision (mAP) scores per class.""" + return self.box.maps + + @property + def fitness(self): + """Returns the fitness of box object.""" + return self.box.fitness() + + @property + def ap_class_index(self): + """Returns the average precision index per class.""" + return self.box.ap_class_index + + @property + def results_dict(self): + """Returns dictionary of computed performance metrics and statistics.""" + return dict(zip(self.keys + ["fitness"], self.mean_results() + [self.fitness])) + + @property + def curves(self): + """Returns a list of curves for accessing specific metrics curves.""" + return [] + + @property + def curves_results(self): + """Returns a list of curves for accessing specific metrics curves.""" + return [] diff --git a/ultralytics/utils/ops.py b/ultralytics/utils/ops.py new file mode 100644 index 0000000..4bdeb16 --- /dev/null +++ b/ultralytics/utils/ops.py @@ -0,0 +1,849 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import contextlib +import math +import re +import time + +import cv2 +import numpy as np +import torch +import torch.nn.functional as F + +from ultralytics.utils import LOGGER +from ultralytics.utils.metrics import batch_probiou + + +class Profile(contextlib.ContextDecorator): + """ + YOLOv8 Profile class. Use as a decorator with @Profile() or as a context manager with 'with Profile():'. + + Example: + ```python + from ultralytics.utils.ops import Profile + + with Profile(device=device) as dt: + pass # slow operation here + + print(dt) # prints "Elapsed time is 9.5367431640625e-07 s" + ``` + """ + + def __init__(self, t=0.0, device: torch.device = None): + """ + Initialize the Profile class. + + Args: + t (float): Initial time. Defaults to 0.0. + device (torch.device): Devices used for model inference. Defaults to None (cpu). + """ + self.t = t + self.device = device + self.cuda = bool(device and str(device).startswith("cuda")) + + def __enter__(self): + """Start timing.""" + self.start = self.time() + return self + + def __exit__(self, type, value, traceback): # noqa + """Stop timing.""" + self.dt = self.time() - self.start # delta-time + self.t += self.dt # accumulate dt + + def __str__(self): + """Returns a human-readable string representing the accumulated elapsed time in the profiler.""" + return f"Elapsed time is {self.t} s" + + def time(self): + """Get current time.""" + if self.cuda: + torch.cuda.synchronize(self.device) + return time.time() + + +def segment2box(segment, width=640, height=640): + """ + Convert 1 segment label to 1 box label, applying inside-image constraint, i.e. (xy1, xy2, ...) to (xyxy). + + Args: + segment (torch.Tensor): the segment label + width (int): the width of the image. Defaults to 640 + height (int): The height of the image. Defaults to 640 + + Returns: + (np.ndarray): the minimum and maximum x and y values of the segment. + """ + x, y = segment.T # segment xy + inside = (x >= 0) & (y >= 0) & (x <= width) & (y <= height) + x = x[inside] + y = y[inside] + return ( + np.array([x.min(), y.min(), x.max(), y.max()], dtype=segment.dtype) + if any(x) + else np.zeros(4, dtype=segment.dtype) + ) # xyxy + + +def scale_boxes(img1_shape, boxes, img0_shape, ratio_pad=None, padding=True, xywh=False): + """ + Rescales bounding boxes (in the format of xyxy by default) from the shape of the image they were originally + specified in (img1_shape) to the shape of a different image (img0_shape). + + Args: + img1_shape (tuple): The shape of the image that the bounding boxes are for, in the format of (height, width). + boxes (torch.Tensor): the bounding boxes of the objects in the image, in the format of (x1, y1, x2, y2) + img0_shape (tuple): the shape of the target image, in the format of (height, width). + ratio_pad (tuple): a tuple of (ratio, pad) for scaling the boxes. If not provided, the ratio and pad will be + calculated based on the size difference between the two images. + padding (bool): If True, assuming the boxes is based on image augmented by yolo style. If False then do regular + rescaling. + xywh (bool): The box format is xywh or not, default=False. + + Returns: + boxes (torch.Tensor): The scaled bounding boxes, in the format of (x1, y1, x2, y2) + """ + if ratio_pad is None: # calculate from img0_shape + gain = min(img1_shape[0] / img0_shape[0], img1_shape[1] / img0_shape[1]) # gain = old / new + pad = ( + round((img1_shape[1] - img0_shape[1] * gain) / 2 - 0.1), + round((img1_shape[0] - img0_shape[0] * gain) / 2 - 0.1), + ) # wh padding + else: + gain = ratio_pad[0][0] + pad = ratio_pad[1] + + if padding: + boxes[..., 0] -= pad[0] # x padding + boxes[..., 1] -= pad[1] # y padding + if not xywh: + boxes[..., 2] -= pad[0] # x padding + boxes[..., 3] -= pad[1] # y padding + boxes[..., :4] /= gain + return clip_boxes(boxes, img0_shape) + + +def make_divisible(x, divisor): + """ + Returns the nearest number that is divisible by the given divisor. + + Args: + x (int): The number to make divisible. + divisor (int | torch.Tensor): The divisor. + + Returns: + (int): The nearest number divisible by the divisor. + """ + if isinstance(divisor, torch.Tensor): + divisor = int(divisor.max()) # to int + return math.ceil(x / divisor) * divisor + + +def nms_rotated(boxes, scores, threshold=0.45): + """ + NMS for obbs, powered by probiou and fast-nms. + + Args: + boxes (torch.Tensor): (N, 5), xywhr. + scores (torch.Tensor): (N, ). + threshold (float): IoU threshold. + + Returns: + """ + if len(boxes) == 0: + return np.empty((0,), dtype=np.int8) + sorted_idx = torch.argsort(scores, descending=True) + boxes = boxes[sorted_idx] + ious = batch_probiou(boxes, boxes).triu_(diagonal=1) + pick = torch.nonzero(ious.max(dim=0)[0] < threshold).squeeze_(-1) + return sorted_idx[pick] + + +def non_max_suppression( + prediction, + conf_thres=0.25, + iou_thres=0.45, + classes=None, + agnostic=False, + multi_label=False, + labels=(), + max_det=300, + nc=0, # number of classes (optional) + max_time_img=0.05, + max_nms=30000, + max_wh=7680, + in_place=True, + rotated=False, +): + """ + Perform non-maximum suppression (NMS) on a set of boxes, with support for masks and multiple labels per box. + + Args: + prediction (torch.Tensor): A tensor of shape (batch_size, num_classes + 4 + num_masks, num_boxes) + containing the predicted boxes, classes, and masks. The tensor should be in the format + output by a model, such as YOLO. + conf_thres (float): The confidence threshold below which boxes will be filtered out. + Valid values are between 0.0 and 1.0. + iou_thres (float): The IoU threshold below which boxes will be filtered out during NMS. + Valid values are between 0.0 and 1.0. + classes (List[int]): A list of class indices to consider. If None, all classes will be considered. + agnostic (bool): If True, the model is agnostic to the number of classes, and all + classes will be considered as one. + multi_label (bool): If True, each box may have multiple labels. + labels (List[List[Union[int, float, torch.Tensor]]]): A list of lists, where each inner + list contains the apriori labels for a given image. The list should be in the format + output by a dataloader, with each label being a tuple of (class_index, x1, y1, x2, y2). + max_det (int): The maximum number of boxes to keep after NMS. + nc (int, optional): The number of classes output by the model. Any indices after this will be considered masks. + max_time_img (float): The maximum time (seconds) for processing one image. + max_nms (int): The maximum number of boxes into torchvision.ops.nms(). + max_wh (int): The maximum box width and height in pixels. + in_place (bool): If True, the input prediction tensor will be modified in place. + + Returns: + (List[torch.Tensor]): A list of length batch_size, where each element is a tensor of + shape (num_boxes, 6 + num_masks) containing the kept boxes, with columns + (x1, y1, x2, y2, confidence, class, mask1, mask2, ...). + """ + import torchvision # scope for faster 'import ultralytics' + + # Checks + assert 0 <= conf_thres <= 1, f"Invalid Confidence threshold {conf_thres}, valid values are between 0.0 and 1.0" + assert 0 <= iou_thres <= 1, f"Invalid IoU {iou_thres}, valid values are between 0.0 and 1.0" + if isinstance(prediction, (list, tuple)): # YOLOv8 model in validation model, output = (inference_out, loss_out) + prediction = prediction[0] # select only inference output + + bs = prediction.shape[0] # batch size + nc = nc or (prediction.shape[1] - 4) # number of classes + nm = prediction.shape[1] - nc - 4 + mi = 4 + nc # mask start index + xc = prediction[:, 4:mi].amax(1) > conf_thres # candidates + + # Settings + # min_wh = 2 # (pixels) minimum box width and height + time_limit = 2.0 + max_time_img * bs # seconds to quit after + multi_label &= nc > 1 # multiple labels per box (adds 0.5ms/img) + + prediction = prediction.transpose(-1, -2) # shape(1,84,6300) to shape(1,6300,84) + if not rotated: + if in_place: + prediction[..., :4] = xywh2xyxy(prediction[..., :4]) # xywh to xyxy + else: + prediction = torch.cat((xywh2xyxy(prediction[..., :4]), prediction[..., 4:]), dim=-1) # xywh to xyxy + + t = time.time() + output = [torch.zeros((0, 6 + nm), device=prediction.device)] * bs + for xi, x in enumerate(prediction): # image index, image inference + # Apply constraints + # x[((x[:, 2:4] < min_wh) | (x[:, 2:4] > max_wh)).any(1), 4] = 0 # width-height + x = x[xc[xi]] # confidence + + # Cat apriori labels if autolabelling + if labels and len(labels[xi]) and not rotated: + lb = labels[xi] + v = torch.zeros((len(lb), nc + nm + 4), device=x.device) + v[:, :4] = xywh2xyxy(lb[:, 1:5]) # box + v[range(len(lb)), lb[:, 0].long() + 4] = 1.0 # cls + x = torch.cat((x, v), 0) + + # If none remain process next image + if not x.shape[0]: + continue + + # Detections matrix nx6 (xyxy, conf, cls) + box, cls, mask = x.split((4, nc, nm), 1) + + if multi_label: + i, j = torch.where(cls > conf_thres) + x = torch.cat((box[i], x[i, 4 + j, None], j[:, None].float(), mask[i]), 1) + else: # best class only + conf, j = cls.max(1, keepdim=True) + x = torch.cat((box, conf, j.float(), mask), 1)[conf.view(-1) > conf_thres] + + # Filter by class + if classes is not None: + x = x[(x[:, 5:6] == torch.tensor(classes, device=x.device)).any(1)] + + # Check shape + n = x.shape[0] # number of boxes + if not n: # no boxes + continue + if n > max_nms: # excess boxes + x = x[x[:, 4].argsort(descending=True)[:max_nms]] # sort by confidence and remove excess boxes + + # Batched NMS + c = x[:, 5:6] * (0 if agnostic else max_wh) # classes + scores = x[:, 4] # scores + if rotated: + boxes = torch.cat((x[:, :2] + c, x[:, 2:4], x[:, -1:]), dim=-1) # xywhr + i = nms_rotated(boxes, scores, iou_thres) + else: + boxes = x[:, :4] + c # boxes (offset by class) + i = torchvision.ops.nms(boxes, scores, iou_thres) # NMS + i = i[:max_det] # limit detections + + # # Experimental + # merge = False # use merge-NMS + # if merge and (1 < n < 3E3): # Merge NMS (boxes merged using weighted mean) + # # Update boxes as boxes(i,4) = weights(i,n) * boxes(n,4) + # from .metrics import box_iou + # iou = box_iou(boxes[i], boxes) > iou_thres # IoU matrix + # weights = iou * scores[None] # box weights + # x[i, :4] = torch.mm(weights, x[:, :4]).float() / weights.sum(1, keepdim=True) # merged boxes + # redundant = True # require redundant detections + # if redundant: + # i = i[iou.sum(1) > 1] # require redundancy + + output[xi] = x[i] + if (time.time() - t) > time_limit: + LOGGER.warning(f"WARNING ⚠️ NMS time limit {time_limit:.3f}s exceeded") + break # time limit exceeded + + return output + + +def clip_boxes(boxes, shape): + """ + Takes a list of bounding boxes and a shape (height, width) and clips the bounding boxes to the shape. + + Args: + boxes (torch.Tensor): the bounding boxes to clip + shape (tuple): the shape of the image + + Returns: + (torch.Tensor | numpy.ndarray): Clipped boxes + """ + if isinstance(boxes, torch.Tensor): # faster individually (WARNING: inplace .clamp_() Apple MPS bug) + boxes[..., 0] = boxes[..., 0].clamp(0, shape[1]) # x1 + boxes[..., 1] = boxes[..., 1].clamp(0, shape[0]) # y1 + boxes[..., 2] = boxes[..., 2].clamp(0, shape[1]) # x2 + boxes[..., 3] = boxes[..., 3].clamp(0, shape[0]) # y2 + else: # np.array (faster grouped) + boxes[..., [0, 2]] = boxes[..., [0, 2]].clip(0, shape[1]) # x1, x2 + boxes[..., [1, 3]] = boxes[..., [1, 3]].clip(0, shape[0]) # y1, y2 + return boxes + + +def clip_coords(coords, shape): + """ + Clip line coordinates to the image boundaries. + + Args: + coords (torch.Tensor | numpy.ndarray): A list of line coordinates. + shape (tuple): A tuple of integers representing the size of the image in the format (height, width). + + Returns: + (torch.Tensor | numpy.ndarray): Clipped coordinates + """ + if isinstance(coords, torch.Tensor): # faster individually (WARNING: inplace .clamp_() Apple MPS bug) + coords[..., 0] = coords[..., 0].clamp(0, shape[1]) # x + coords[..., 1] = coords[..., 1].clamp(0, shape[0]) # y + else: # np.array (faster grouped) + coords[..., 0] = coords[..., 0].clip(0, shape[1]) # x + coords[..., 1] = coords[..., 1].clip(0, shape[0]) # y + return coords + + +def scale_image(masks, im0_shape, ratio_pad=None): + """ + Takes a mask, and resizes it to the original image size. + + Args: + masks (np.ndarray): resized and padded masks/images, [h, w, num]/[h, w, 3]. + im0_shape (tuple): the original image shape + ratio_pad (tuple): the ratio of the padding to the original image. + + Returns: + masks (torch.Tensor): The masks that are being returned. + """ + # Rescale coordinates (xyxy) from im1_shape to im0_shape + im1_shape = masks.shape + if im1_shape[:2] == im0_shape[:2]: + return masks + if ratio_pad is None: # calculate from im0_shape + gain = min(im1_shape[0] / im0_shape[0], im1_shape[1] / im0_shape[1]) # gain = old / new + pad = (im1_shape[1] - im0_shape[1] * gain) / 2, (im1_shape[0] - im0_shape[0] * gain) / 2 # wh padding + else: + # gain = ratio_pad[0][0] + pad = ratio_pad[1] + top, left = int(pad[1]), int(pad[0]) # y, x + bottom, right = int(im1_shape[0] - pad[1]), int(im1_shape[1] - pad[0]) + + if len(masks.shape) < 2: + raise ValueError(f'"len of masks shape" should be 2 or 3, but got {len(masks.shape)}') + masks = masks[top:bottom, left:right] + masks = cv2.resize(masks, (im0_shape[1], im0_shape[0])) + if len(masks.shape) == 2: + masks = masks[:, :, None] + + return masks + + +def xyxy2xywh(x): + """ + Convert bounding box coordinates from (x1, y1, x2, y2) format to (x, y, width, height) format where (x1, y1) is the + top-left corner and (x2, y2) is the bottom-right corner. + + Args: + x (np.ndarray | torch.Tensor): The input bounding box coordinates in (x1, y1, x2, y2) format. + + Returns: + y (np.ndarray | torch.Tensor): The bounding box coordinates in (x, y, width, height) format. + """ + assert x.shape[-1] == 4, f"input shape last dimension expected 4 but input shape is {x.shape}" + y = torch.empty_like(x) if isinstance(x, torch.Tensor) else np.empty_like(x) # faster than clone/copy + y[..., 0] = (x[..., 0] + x[..., 2]) / 2 # x center + y[..., 1] = (x[..., 1] + x[..., 3]) / 2 # y center + y[..., 2] = x[..., 2] - x[..., 0] # width + y[..., 3] = x[..., 3] - x[..., 1] # height + return y + + +def xywh2xyxy(x): + """ + Convert bounding box coordinates from (x, y, width, height) format to (x1, y1, x2, y2) format where (x1, y1) is the + top-left corner and (x2, y2) is the bottom-right corner. + + Args: + x (np.ndarray | torch.Tensor): The input bounding box coordinates in (x, y, width, height) format. + + Returns: + y (np.ndarray | torch.Tensor): The bounding box coordinates in (x1, y1, x2, y2) format. + """ + assert x.shape[-1] == 4, f"input shape last dimension expected 4 but input shape is {x.shape}" + y = torch.empty_like(x) if isinstance(x, torch.Tensor) else np.empty_like(x) # faster than clone/copy + dw = x[..., 2] / 2 # half-width + dh = x[..., 3] / 2 # half-height + y[..., 0] = x[..., 0] - dw # top left x + y[..., 1] = x[..., 1] - dh # top left y + y[..., 2] = x[..., 0] + dw # bottom right x + y[..., 3] = x[..., 1] + dh # bottom right y + return y + + +def xywhn2xyxy(x, w=640, h=640, padw=0, padh=0): + """ + Convert normalized bounding box coordinates to pixel coordinates. + + Args: + x (np.ndarray | torch.Tensor): The bounding box coordinates. + w (int): Width of the image. Defaults to 640 + h (int): Height of the image. Defaults to 640 + padw (int): Padding width. Defaults to 0 + padh (int): Padding height. Defaults to 0 + Returns: + y (np.ndarray | torch.Tensor): The coordinates of the bounding box in the format [x1, y1, x2, y2] where + x1,y1 is the top-left corner, x2,y2 is the bottom-right corner of the bounding box. + """ + assert x.shape[-1] == 4, f"input shape last dimension expected 4 but input shape is {x.shape}" + y = torch.empty_like(x) if isinstance(x, torch.Tensor) else np.empty_like(x) # faster than clone/copy + y[..., 0] = w * (x[..., 0] - x[..., 2] / 2) + padw # top left x + y[..., 1] = h * (x[..., 1] - x[..., 3] / 2) + padh # top left y + y[..., 2] = w * (x[..., 0] + x[..., 2] / 2) + padw # bottom right x + y[..., 3] = h * (x[..., 1] + x[..., 3] / 2) + padh # bottom right y + return y + + +def xyxy2xywhn(x, w=640, h=640, clip=False, eps=0.0): + """ + Convert bounding box coordinates from (x1, y1, x2, y2) format to (x, y, width, height, normalized) format. x, y, + width and height are normalized to image dimensions. + + Args: + x (np.ndarray | torch.Tensor): The input bounding box coordinates in (x1, y1, x2, y2) format. + w (int): The width of the image. Defaults to 640 + h (int): The height of the image. Defaults to 640 + clip (bool): If True, the boxes will be clipped to the image boundaries. Defaults to False + eps (float): The minimum value of the box's width and height. Defaults to 0.0 + + Returns: + y (np.ndarray | torch.Tensor): The bounding box coordinates in (x, y, width, height, normalized) format + """ + if clip: + x = clip_boxes(x, (h - eps, w - eps)) + assert x.shape[-1] == 4, f"input shape last dimension expected 4 but input shape is {x.shape}" + y = torch.empty_like(x) if isinstance(x, torch.Tensor) else np.empty_like(x) # faster than clone/copy + y[..., 0] = ((x[..., 0] + x[..., 2]) / 2) / w # x center + y[..., 1] = ((x[..., 1] + x[..., 3]) / 2) / h # y center + y[..., 2] = (x[..., 2] - x[..., 0]) / w # width + y[..., 3] = (x[..., 3] - x[..., 1]) / h # height + return y + + +def xywh2ltwh(x): + """ + Convert the bounding box format from [x, y, w, h] to [x1, y1, w, h], where x1, y1 are the top-left coordinates. + + Args: + x (np.ndarray | torch.Tensor): The input tensor with the bounding box coordinates in the xywh format + + Returns: + y (np.ndarray | torch.Tensor): The bounding box coordinates in the xyltwh format + """ + y = x.clone() if isinstance(x, torch.Tensor) else np.copy(x) + y[..., 0] = x[..., 0] - x[..., 2] / 2 # top left x + y[..., 1] = x[..., 1] - x[..., 3] / 2 # top left y + return y + + +def xyxy2ltwh(x): + """ + Convert nx4 bounding boxes from [x1, y1, x2, y2] to [x1, y1, w, h], where xy1=top-left, xy2=bottom-right. + + Args: + x (np.ndarray | torch.Tensor): The input tensor with the bounding boxes coordinates in the xyxy format + + Returns: + y (np.ndarray | torch.Tensor): The bounding box coordinates in the xyltwh format. + """ + y = x.clone() if isinstance(x, torch.Tensor) else np.copy(x) + y[..., 2] = x[..., 2] - x[..., 0] # width + y[..., 3] = x[..., 3] - x[..., 1] # height + return y + + +def ltwh2xywh(x): + """ + Convert nx4 boxes from [x1, y1, w, h] to [x, y, w, h] where xy1=top-left, xy=center. + + Args: + x (torch.Tensor): the input tensor + + Returns: + y (np.ndarray | torch.Tensor): The bounding box coordinates in the xywh format. + """ + y = x.clone() if isinstance(x, torch.Tensor) else np.copy(x) + y[..., 0] = x[..., 0] + x[..., 2] / 2 # center x + y[..., 1] = x[..., 1] + x[..., 3] / 2 # center y + return y + + +def xyxyxyxy2xywhr(corners): + """ + Convert batched Oriented Bounding Boxes (OBB) from [xy1, xy2, xy3, xy4] to [xywh, rotation]. Rotation values are + expected in degrees from 0 to 90. + + Args: + corners (numpy.ndarray | torch.Tensor): Input corners of shape (n, 8). + + Returns: + (numpy.ndarray | torch.Tensor): Converted data in [cx, cy, w, h, rotation] format of shape (n, 5). + """ + is_torch = isinstance(corners, torch.Tensor) + points = corners.cpu().numpy() if is_torch else corners + points = points.reshape(len(corners), -1, 2) + rboxes = [] + for pts in points: + # NOTE: Use cv2.minAreaRect to get accurate xywhr, + # especially some objects are cut off by augmentations in dataloader. + (x, y), (w, h), angle = cv2.minAreaRect(pts) + rboxes.append([x, y, w, h, angle / 180 * np.pi]) + return ( + torch.tensor(rboxes, device=corners.device, dtype=corners.dtype) + if is_torch + else np.asarray(rboxes, dtype=points.dtype) + ) # rboxes + + +def xywhr2xyxyxyxy(rboxes): + """ + Convert batched Oriented Bounding Boxes (OBB) from [xywh, rotation] to [xy1, xy2, xy3, xy4]. Rotation values should + be in degrees from 0 to 90. + + Args: + rboxes (numpy.ndarray | torch.Tensor): Boxes in [cx, cy, w, h, rotation] format of shape (n, 5) or (b, n, 5). + + Returns: + (numpy.ndarray | torch.Tensor): Converted corner points of shape (n, 4, 2) or (b, n, 4, 2). + """ + is_numpy = isinstance(rboxes, np.ndarray) + cos, sin = (np.cos, np.sin) if is_numpy else (torch.cos, torch.sin) + + ctr = rboxes[..., :2] + w, h, angle = (rboxes[..., i : i + 1] for i in range(2, 5)) + cos_value, sin_value = cos(angle), sin(angle) + vec1 = [w / 2 * cos_value, w / 2 * sin_value] + vec2 = [-h / 2 * sin_value, h / 2 * cos_value] + vec1 = np.concatenate(vec1, axis=-1) if is_numpy else torch.cat(vec1, dim=-1) + vec2 = np.concatenate(vec2, axis=-1) if is_numpy else torch.cat(vec2, dim=-1) + pt1 = ctr + vec1 + vec2 + pt2 = ctr + vec1 - vec2 + pt3 = ctr - vec1 - vec2 + pt4 = ctr - vec1 + vec2 + return np.stack([pt1, pt2, pt3, pt4], axis=-2) if is_numpy else torch.stack([pt1, pt2, pt3, pt4], dim=-2) + + +def ltwh2xyxy(x): + """ + It converts the bounding box from [x1, y1, w, h] to [x1, y1, x2, y2] where xy1=top-left, xy2=bottom-right. + + Args: + x (np.ndarray | torch.Tensor): the input image + + Returns: + y (np.ndarray | torch.Tensor): the xyxy coordinates of the bounding boxes. + """ + y = x.clone() if isinstance(x, torch.Tensor) else np.copy(x) + y[..., 2] = x[..., 2] + x[..., 0] # width + y[..., 3] = x[..., 3] + x[..., 1] # height + return y + + +def segments2boxes(segments): + """ + It converts segment labels to box labels, i.e. (cls, xy1, xy2, ...) to (cls, xywh) + + Args: + segments (list): list of segments, each segment is a list of points, each point is a list of x, y coordinates + + Returns: + (np.ndarray): the xywh coordinates of the bounding boxes. + """ + boxes = [] + for s in segments: + x, y = s.T # segment xy + boxes.append([x.min(), y.min(), x.max(), y.max()]) # cls, xyxy + return xyxy2xywh(np.array(boxes)) # cls, xywh + + +def resample_segments(segments, n=1000): + """ + Inputs a list of segments (n,2) and returns a list of segments (n,2) up-sampled to n points each. + + Args: + segments (list): a list of (n,2) arrays, where n is the number of points in the segment. + n (int): number of points to resample the segment to. Defaults to 1000 + + Returns: + segments (list): the resampled segments. + """ + for i, s in enumerate(segments): + s = np.concatenate((s, s[0:1, :]), axis=0) + x = np.linspace(0, len(s) - 1, n) + xp = np.arange(len(s)) + segments[i] = ( + np.concatenate([np.interp(x, xp, s[:, i]) for i in range(2)], dtype=np.float32).reshape(2, -1).T + ) # segment xy + return segments + + +def crop_mask(masks, boxes): + """ + It takes a mask and a bounding box, and returns a mask that is cropped to the bounding box. + + Args: + masks (torch.Tensor): [n, h, w] tensor of masks + boxes (torch.Tensor): [n, 4] tensor of bbox coordinates in relative point form + + Returns: + (torch.Tensor): The masks are being cropped to the bounding box. + """ + _, h, w = masks.shape + x1, y1, x2, y2 = torch.chunk(boxes[:, :, None], 4, 1) # x1 shape(n,1,1) + r = torch.arange(w, device=masks.device, dtype=x1.dtype)[None, None, :] # rows shape(1,1,w) + c = torch.arange(h, device=masks.device, dtype=x1.dtype)[None, :, None] # cols shape(1,h,1) + + return masks * ((r >= x1) * (r < x2) * (c >= y1) * (c < y2)) + + +def process_mask_upsample(protos, masks_in, bboxes, shape): + """ + Takes the output of the mask head, and applies the mask to the bounding boxes. This produces masks of higher quality + but is slower. + + Args: + protos (torch.Tensor): [mask_dim, mask_h, mask_w] + masks_in (torch.Tensor): [n, mask_dim], n is number of masks after nms + bboxes (torch.Tensor): [n, 4], n is number of masks after nms + shape (tuple): the size of the input image (h,w) + + Returns: + (torch.Tensor): The upsampled masks. + """ + c, mh, mw = protos.shape # CHW + masks = (masks_in @ protos.float().view(c, -1)).sigmoid().view(-1, mh, mw) + masks = F.interpolate(masks[None], shape, mode="bilinear", align_corners=False)[0] # CHW + masks = crop_mask(masks, bboxes) # CHW + return masks.gt_(0.5) + + +def process_mask(protos, masks_in, bboxes, shape, upsample=False): + """ + Apply masks to bounding boxes using the output of the mask head. + + Args: + protos (torch.Tensor): A tensor of shape [mask_dim, mask_h, mask_w]. + masks_in (torch.Tensor): A tensor of shape [n, mask_dim], where n is the number of masks after NMS. + bboxes (torch.Tensor): A tensor of shape [n, 4], where n is the number of masks after NMS. + shape (tuple): A tuple of integers representing the size of the input image in the format (h, w). + upsample (bool): A flag to indicate whether to upsample the mask to the original image size. Default is False. + + Returns: + (torch.Tensor): A binary mask tensor of shape [n, h, w], where n is the number of masks after NMS, and h and w + are the height and width of the input image. The mask is applied to the bounding boxes. + """ + + c, mh, mw = protos.shape # CHW + ih, iw = shape + masks = (masks_in @ protos.float().view(c, -1)).sigmoid().view(-1, mh, mw) # CHW + width_ratio = mw / iw + height_ratio = mh / ih + + downsampled_bboxes = bboxes.clone() + downsampled_bboxes[:, 0] *= width_ratio + downsampled_bboxes[:, 2] *= width_ratio + downsampled_bboxes[:, 3] *= height_ratio + downsampled_bboxes[:, 1] *= height_ratio + + masks = crop_mask(masks, downsampled_bboxes) # CHW + if upsample: + masks = F.interpolate(masks[None], shape, mode="bilinear", align_corners=False)[0] # CHW + return masks.gt_(0.5) + + +def process_mask_native(protos, masks_in, bboxes, shape): + """ + It takes the output of the mask head, and crops it after upsampling to the bounding boxes. + + Args: + protos (torch.Tensor): [mask_dim, mask_h, mask_w] + masks_in (torch.Tensor): [n, mask_dim], n is number of masks after nms + bboxes (torch.Tensor): [n, 4], n is number of masks after nms + shape (tuple): the size of the input image (h,w) + + Returns: + masks (torch.Tensor): The returned masks with dimensions [h, w, n] + """ + c, mh, mw = protos.shape # CHW + masks = (masks_in @ protos.float().view(c, -1)).sigmoid().view(-1, mh, mw) + masks = scale_masks(masks[None], shape)[0] # CHW + masks = crop_mask(masks, bboxes) # CHW + return masks.gt_(0.5) + + +def scale_masks(masks, shape, padding=True): + """ + Rescale segment masks to shape. + + Args: + masks (torch.Tensor): (N, C, H, W). + shape (tuple): Height and width. + padding (bool): If True, assuming the boxes is based on image augmented by yolo style. If False then do regular + rescaling. + """ + mh, mw = masks.shape[2:] + gain = min(mh / shape[0], mw / shape[1]) # gain = old / new + pad = [mw - shape[1] * gain, mh - shape[0] * gain] # wh padding + if padding: + pad[0] /= 2 + pad[1] /= 2 + top, left = (int(pad[1]), int(pad[0])) if padding else (0, 0) # y, x + bottom, right = (int(mh - pad[1]), int(mw - pad[0])) + masks = masks[..., top:bottom, left:right] + + masks = F.interpolate(masks, shape, mode="bilinear", align_corners=False) # NCHW + return masks + + +def scale_coords(img1_shape, coords, img0_shape, ratio_pad=None, normalize=False, padding=True): + """ + Rescale segment coordinates (xy) from img1_shape to img0_shape. + + Args: + img1_shape (tuple): The shape of the image that the coords are from. + coords (torch.Tensor): the coords to be scaled of shape n,2. + img0_shape (tuple): the shape of the image that the segmentation is being applied to. + ratio_pad (tuple): the ratio of the image size to the padded image size. + normalize (bool): If True, the coordinates will be normalized to the range [0, 1]. Defaults to False. + padding (bool): If True, assuming the boxes is based on image augmented by yolo style. If False then do regular + rescaling. + + Returns: + coords (torch.Tensor): The scaled coordinates. + """ + if ratio_pad is None: # calculate from img0_shape + gain = min(img1_shape[0] / img0_shape[0], img1_shape[1] / img0_shape[1]) # gain = old / new + pad = (img1_shape[1] - img0_shape[1] * gain) / 2, (img1_shape[0] - img0_shape[0] * gain) / 2 # wh padding + else: + gain = ratio_pad[0][0] + pad = ratio_pad[1] + + if padding: + coords[..., 0] -= pad[0] # x padding + coords[..., 1] -= pad[1] # y padding + coords[..., 0] /= gain + coords[..., 1] /= gain + coords = clip_coords(coords, img0_shape) + if normalize: + coords[..., 0] /= img0_shape[1] # width + coords[..., 1] /= img0_shape[0] # height + return coords + + +def regularize_rboxes(rboxes): + """ + Regularize rotated boxes in range [0, pi/2]. + + Args: + rboxes (torch.Tensor): (N, 5), xywhr. + + Returns: + (torch.Tensor): The regularized boxes. + """ + x, y, w, h, t = rboxes.unbind(dim=-1) + # Swap edge and angle if h >= w + w_ = torch.where(w > h, w, h) + h_ = torch.where(w > h, h, w) + t = torch.where(w > h, t, t + math.pi / 2) % math.pi + return torch.stack([x, y, w_, h_, t], dim=-1) # regularized boxes + + +def masks2segments(masks, strategy="largest"): + """ + It takes a list of masks(n,h,w) and returns a list of segments(n,xy) + + Args: + masks (torch.Tensor): the output of the model, which is a tensor of shape (batch_size, 160, 160) + strategy (str): 'concat' or 'largest'. Defaults to largest + + Returns: + segments (List): list of segment masks + """ + segments = [] + for x in masks.int().cpu().numpy().astype("uint8"): + c = cv2.findContours(x, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)[0] + if c: + if strategy == "concat": # concatenate all segments + c = np.concatenate([x.reshape(-1, 2) for x in c]) + elif strategy == "largest": # select largest segment + c = np.array(c[np.array([len(x) for x in c]).argmax()]).reshape(-1, 2) + else: + c = np.zeros((0, 2)) # no segments found + segments.append(c.astype("float32")) + return segments + + +def convert_torch2numpy_batch(batch: torch.Tensor) -> np.ndarray: + """ + Convert a batch of FP32 torch tensors (0.0-1.0) to a NumPy uint8 array (0-255), changing from BCHW to BHWC layout. + + Args: + batch (torch.Tensor): Input tensor batch of shape (Batch, Channels, Height, Width) and dtype torch.float32. + + Returns: + (np.ndarray): Output NumPy array batch of shape (Batch, Height, Width, Channels) and dtype uint8. + """ + return (batch.permute(0, 2, 3, 1).contiguous() * 255).clamp(0, 255).to(torch.uint8).cpu().numpy() + + +def clean_str(s): + """ + Cleans a string by replacing special characters with underscore _ + + Args: + s (str): a string needing special characters replaced + + Returns: + (str): a string with special characters replaced by an underscore _ + """ + return re.sub(pattern="[|@#!¡·$€%&()=?¿^*;:,¨´><+]", repl="_", string=s) diff --git a/ultralytics/utils/patches.py b/ultralytics/utils/patches.py new file mode 100644 index 0000000..d438407 --- /dev/null +++ b/ultralytics/utils/patches.py @@ -0,0 +1,88 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license +"""Monkey patches to update/extend functionality of existing functions.""" + +import time +from pathlib import Path + +import cv2 +import numpy as np +import torch + +# OpenCV Multilanguage-friendly functions ------------------------------------------------------------------------------ +_imshow = cv2.imshow # copy to avoid recursion errors + + +def imread(filename: str, flags: int = cv2.IMREAD_COLOR): + """ + Read an image from a file. + + Args: + filename (str): Path to the file to read. + flags (int, optional): Flag that can take values of cv2.IMREAD_*. Defaults to cv2.IMREAD_COLOR. + + Returns: + (np.ndarray): The read image. + """ + return cv2.imdecode(np.fromfile(filename, np.uint8), flags) + + +def imwrite(filename: str, img: np.ndarray, params=None): + """ + Write an image to a file. + + Args: + filename (str): Path to the file to write. + img (np.ndarray): Image to write. + params (list of ints, optional): Additional parameters. See OpenCV documentation. + + Returns: + (bool): True if the file was written, False otherwise. + """ + try: + cv2.imencode(Path(filename).suffix, img, params)[1].tofile(filename) + return True + except Exception: + return False + + +def imshow(winname: str, mat: np.ndarray): + """ + Displays an image in the specified window. + + Args: + winname (str): Name of the window. + mat (np.ndarray): Image to be shown. + """ + _imshow(winname.encode("unicode_escape").decode(), mat) + + +# PyTorch functions ---------------------------------------------------------------------------------------------------- +_torch_save = torch.save # copy to avoid recursion errors + + +def torch_save(*args, use_dill=True, **kwargs): + """ + Optionally use dill to serialize lambda functions where pickle does not, adding robustness with 3 retries and + exponential standoff in case of save failure. + + Args: + *args (tuple): Positional arguments to pass to torch.save. + use_dill (bool): Whether to try using dill for serialization if available. Defaults to True. + **kwargs (any): Keyword arguments to pass to torch.save. + """ + try: + assert use_dill + import dill as pickle + except (AssertionError, ImportError): + import pickle + + if "pickle_module" not in kwargs: + kwargs["pickle_module"] = pickle + + for i in range(4): # 3 retries + try: + return _torch_save(*args, **kwargs) + except RuntimeError as e: # unable to save, possibly waiting for device to flush or antivirus scan + if i == 3: + raise e + time.sleep((2**i) / 2) # exponential standoff: 0.5s, 1.0s, 2.0s diff --git a/ultralytics/utils/plotting.py b/ultralytics/utils/plotting.py new file mode 100644 index 0000000..1ffc27c --- /dev/null +++ b/ultralytics/utils/plotting.py @@ -0,0 +1,1120 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import contextlib +import math +import warnings +from pathlib import Path + +import cv2 +import matplotlib.pyplot as plt +import numpy as np +import torch +from PIL import Image, ImageDraw, ImageFont +from PIL import __version__ as pil_version + +from ultralytics.utils import LOGGER, TryExcept, ops, plt_settings, threaded +from ultralytics.utils.checks import check_font, check_version, is_ascii +from ultralytics.utils.files import increment_path + + +class Colors: + """ + Ultralytics default color palette https://ultralytics.com/. + + This class provides methods to work with the Ultralytics color palette, including converting hex color codes to + RGB values. + + Attributes: + palette (list of tuple): List of RGB color values. + n (int): The number of colors in the palette. + pose_palette (np.ndarray): A specific color palette array with dtype np.uint8. + """ + + def __init__(self): + """Initialize colors as hex = matplotlib.colors.TABLEAU_COLORS.values().""" + hexs = ( + "FF3838", + "FF9D97", + "FF701F", + "FFB21D", + "CFD231", + "48F90A", + "92CC17", + "3DDB86", + "1A9334", + "00D4BB", + "2C99A8", + "00C2FF", + "344593", + "6473FF", + "0018EC", + "8438FF", + "520085", + "CB38FF", + "FF95C8", + "FF37C7", + ) + self.palette = [self.hex2rgb(f"#{c}") for c in hexs] + self.n = len(self.palette) + self.pose_palette = np.array( + [ + [255, 128, 0], + [255, 153, 51], + [255, 178, 102], + [230, 230, 0], + [255, 153, 255], + [153, 204, 255], + [255, 102, 255], + [255, 51, 255], + [102, 178, 255], + [51, 153, 255], + [255, 153, 153], + [255, 102, 102], + [255, 51, 51], + [153, 255, 153], + [102, 255, 102], + [51, 255, 51], + [0, 255, 0], + [0, 0, 255], + [255, 0, 0], + [255, 255, 255], + ], + dtype=np.uint8, + ) + + def __call__(self, i, bgr=False): + """Converts hex color codes to RGB values.""" + c = self.palette[int(i) % self.n] + return (c[2], c[1], c[0]) if bgr else c + + @staticmethod + def hex2rgb(h): + """Converts hex color codes to RGB values (i.e. default PIL order).""" + return tuple(int(h[1 + i : 1 + i + 2], 16) for i in (0, 2, 4)) + + +colors = Colors() # create instance for 'from utils.plots import colors' + + +class Annotator: + """ + Ultralytics Annotator for train/val mosaics and JPGs and predictions annotations. + + Attributes: + im (Image.Image or numpy array): The image to annotate. + pil (bool): Whether to use PIL or cv2 for drawing annotations. + font (ImageFont.truetype or ImageFont.load_default): Font used for text annotations. + lw (float): Line width for drawing. + skeleton (List[List[int]]): Skeleton structure for keypoints. + limb_color (List[int]): Color palette for limbs. + kpt_color (List[int]): Color palette for keypoints. + """ + + def __init__(self, im, line_width=None, font_size=None, font="Arial.ttf", pil=False, example="abc"): + """Initialize the Annotator class with image and line width along with color palette for keypoints and limbs.""" + non_ascii = not is_ascii(example) # non-latin labels, i.e. asian, arabic, cyrillic + input_is_pil = isinstance(im, Image.Image) + self.pil = pil or non_ascii or input_is_pil + self.lw = line_width or max(round(sum(im.size if input_is_pil else im.shape) / 2 * 0.003), 2) + if self.pil: # use PIL + self.im = im if input_is_pil else Image.fromarray(im) + self.draw = ImageDraw.Draw(self.im) + try: + font = check_font("Arial.Unicode.ttf" if non_ascii else font) + size = font_size or max(round(sum(self.im.size) / 2 * 0.035), 12) + self.font = ImageFont.truetype(str(font), size) + except Exception: + self.font = ImageFont.load_default() + # Deprecation fix for w, h = getsize(string) -> _, _, w, h = getbox(string) + if check_version(pil_version, "9.2.0"): + self.font.getsize = lambda x: self.font.getbbox(x)[2:4] # text width, height + else: # use cv2 + assert im.data.contiguous, "Image not contiguous. Apply np.ascontiguousarray(im) to Annotator input images." + self.im = im if im.flags.writeable else im.copy() + self.tf = max(self.lw - 1, 1) # font thickness + self.sf = self.lw / 3 # font scale + # Pose + self.skeleton = [ + [16, 14], + [14, 12], + [17, 15], + [15, 13], + [12, 13], + [6, 12], + [7, 13], + [6, 7], + [6, 8], + [7, 9], + [8, 10], + [9, 11], + [2, 3], + [1, 2], + [1, 3], + [2, 4], + [3, 5], + [4, 6], + [5, 7], + ] + + self.limb_color = colors.pose_palette[[9, 9, 9, 9, 7, 7, 7, 0, 0, 0, 0, 0, 16, 16, 16, 16, 16, 16, 16]] + self.kpt_color = colors.pose_palette[[16, 16, 16, 16, 16, 0, 0, 0, 0, 0, 0, 9, 9, 9, 9, 9, 9]] + + def box_label(self, box, label="", color=(128, 128, 128), txt_color=(255, 255, 255), rotated=False): + """Add one xyxy box to image with label.""" + if isinstance(box, torch.Tensor): + box = box.tolist() + if self.pil or not is_ascii(label): + if rotated: + p1 = box[0] + # NOTE: PIL-version polygon needs tuple type. + self.draw.polygon([tuple(b) for b in box], width=self.lw, outline=color) + else: + p1 = (box[0], box[1]) + self.draw.rectangle(box, width=self.lw, outline=color) # box + if label: + w, h = self.font.getsize(label) # text width, height + outside = p1[1] - h >= 0 # label fits outside box + self.draw.rectangle( + (p1[0], p1[1] - h if outside else p1[1], p1[0] + w + 1, p1[1] + 1 if outside else p1[1] + h + 1), + fill=color, + ) + # self.draw.text((box[0], box[1]), label, fill=txt_color, font=self.font, anchor='ls') # for PIL>8.0 + self.draw.text((p1[0], p1[1] - h if outside else p1[1]), label, fill=txt_color, font=self.font) + else: # cv2 + if rotated: + p1 = [int(b) for b in box[0]] + # NOTE: cv2-version polylines needs np.asarray type. + cv2.polylines(self.im, [np.asarray(box, dtype=int)], True, color, self.lw) + else: + p1, p2 = (int(box[0]), int(box[1])), (int(box[2]), int(box[3])) + cv2.rectangle(self.im, p1, p2, color, thickness=self.lw, lineType=cv2.LINE_AA) + if label: + w, h = cv2.getTextSize(label, 0, fontScale=self.sf, thickness=self.tf)[0] # text width, height + outside = p1[1] - h >= 3 + p2 = p1[0] + w, p1[1] - h - 3 if outside else p1[1] + h + 3 + cv2.rectangle(self.im, p1, p2, color, -1, cv2.LINE_AA) # filled + cv2.putText( + self.im, + label, + (p1[0], p1[1] - 2 if outside else p1[1] + h + 2), + 0, + self.sf, + txt_color, + thickness=self.tf, + lineType=cv2.LINE_AA, + ) + + def masks(self, masks, colors, im_gpu, alpha=0.5, retina_masks=False): + """ + Plot masks on image. + + Args: + masks (tensor): Predicted masks on cuda, shape: [n, h, w] + colors (List[List[Int]]): Colors for predicted masks, [[r, g, b] * n] + im_gpu (tensor): Image is in cuda, shape: [3, h, w], range: [0, 1] + alpha (float): Mask transparency: 0.0 fully transparent, 1.0 opaque + retina_masks (bool): Whether to use high resolution masks or not. Defaults to False. + """ + if self.pil: + # Convert to numpy first + self.im = np.asarray(self.im).copy() + if len(masks) == 0: + self.im[:] = im_gpu.permute(1, 2, 0).contiguous().cpu().numpy() * 255 + if im_gpu.device != masks.device: + im_gpu = im_gpu.to(masks.device) + colors = torch.tensor(colors, device=masks.device, dtype=torch.float32) / 255.0 # shape(n,3) + colors = colors[:, None, None] # shape(n,1,1,3) + masks = masks.unsqueeze(3) # shape(n,h,w,1) + masks_color = masks * (colors * alpha) # shape(n,h,w,3) + + inv_alpha_masks = (1 - masks * alpha).cumprod(0) # shape(n,h,w,1) + mcs = masks_color.max(dim=0).values # shape(n,h,w,3) + + im_gpu = im_gpu.flip(dims=[0]) # flip channel + im_gpu = im_gpu.permute(1, 2, 0).contiguous() # shape(h,w,3) + im_gpu = im_gpu * inv_alpha_masks[-1] + mcs + im_mask = im_gpu * 255 + im_mask_np = im_mask.byte().cpu().numpy() + self.im[:] = im_mask_np if retina_masks else ops.scale_image(im_mask_np, self.im.shape) + if self.pil: + # Convert im back to PIL and update draw + self.fromarray(self.im) + + def kpts(self, kpts, shape=(640, 640), radius=5, kpt_line=True, conf_thres=0.25): + """ + Plot keypoints on the image. + + Args: + kpts (tensor): Predicted keypoints with shape [17, 3]. Each keypoint has (x, y, confidence). + shape (tuple): Image shape as a tuple (h, w), where h is the height and w is the width. + radius (int, optional): Radius of the drawn keypoints. Default is 5. + kpt_line (bool, optional): If True, the function will draw lines connecting keypoints + for human pose. Default is True. + + Note: + `kpt_line=True` currently only supports human pose plotting. + """ + if self.pil: + # Convert to numpy first + self.im = np.asarray(self.im).copy() + nkpt, ndim = kpts.shape + is_pose = nkpt == 17 and ndim in {2, 3} + kpt_line &= is_pose # `kpt_line=True` for now only supports human pose plotting + for i, k in enumerate(kpts): + color_k = [int(x) for x in self.kpt_color[i]] if is_pose else colors(i) + x_coord, y_coord = k[0], k[1] + if x_coord % shape[1] != 0 and y_coord % shape[0] != 0: + if len(k) == 3: + conf = k[2] + if conf < conf_thres: + continue + cv2.circle(self.im, (int(x_coord), int(y_coord)), radius, color_k, -1, lineType=cv2.LINE_AA) + + if kpt_line: + ndim = kpts.shape[-1] + for i, sk in enumerate(self.skeleton): + pos1 = (int(kpts[(sk[0] - 1), 0]), int(kpts[(sk[0] - 1), 1])) + pos2 = (int(kpts[(sk[1] - 1), 0]), int(kpts[(sk[1] - 1), 1])) + if ndim == 3: + conf1 = kpts[(sk[0] - 1), 2] + conf2 = kpts[(sk[1] - 1), 2] + if conf1 < conf_thres or conf2 < conf_thres: + continue + if pos1[0] % shape[1] == 0 or pos1[1] % shape[0] == 0 or pos1[0] < 0 or pos1[1] < 0: + continue + if pos2[0] % shape[1] == 0 or pos2[1] % shape[0] == 0 or pos2[0] < 0 or pos2[1] < 0: + continue + cv2.line(self.im, pos1, pos2, [int(x) for x in self.limb_color[i]], thickness=2, lineType=cv2.LINE_AA) + if self.pil: + # Convert im back to PIL and update draw + self.fromarray(self.im) + + def rectangle(self, xy, fill=None, outline=None, width=1): + """Add rectangle to image (PIL-only).""" + self.draw.rectangle(xy, fill, outline, width) + + def text(self, xy, text, txt_color=(255, 255, 255), anchor="top", box_style=False): + """Adds text to an image using PIL or cv2.""" + if anchor == "bottom": # start y from font bottom + w, h = self.font.getsize(text) # text width, height + xy[1] += 1 - h + if self.pil: + if box_style: + w, h = self.font.getsize(text) + self.draw.rectangle((xy[0], xy[1], xy[0] + w + 1, xy[1] + h + 1), fill=txt_color) + # Using `txt_color` for background and draw fg with white color + txt_color = (255, 255, 255) + if "\n" in text: + lines = text.split("\n") + _, h = self.font.getsize(text) + for line in lines: + self.draw.text(xy, line, fill=txt_color, font=self.font) + xy[1] += h + else: + self.draw.text(xy, text, fill=txt_color, font=self.font) + else: + if box_style: + w, h = cv2.getTextSize(text, 0, fontScale=self.sf, thickness=self.tf)[0] # text width, height + outside = xy[1] - h >= 3 + p2 = xy[0] + w, xy[1] - h - 3 if outside else xy[1] + h + 3 + cv2.rectangle(self.im, xy, p2, txt_color, -1, cv2.LINE_AA) # filled + # Using `txt_color` for background and draw fg with white color + txt_color = (255, 255, 255) + cv2.putText(self.im, text, xy, 0, self.sf, txt_color, thickness=self.tf, lineType=cv2.LINE_AA) + + def fromarray(self, im): + """Update self.im from a numpy array.""" + self.im = im if isinstance(im, Image.Image) else Image.fromarray(im) + self.draw = ImageDraw.Draw(self.im) + + def result(self): + """Return annotated image as array.""" + return np.asarray(self.im) + + def show(self, title=None): + """Show the annotated image.""" + Image.fromarray(np.asarray(self.im)[..., ::-1]).show(title) + + def save(self, filename="image.jpg"): + """Save the annotated image to 'filename'.""" + cv2.imwrite(filename, np.asarray(self.im)) + + def get_bbox_dimension(self, bbox=None): + """ + Calculate the area of a bounding box. + + Args: + bbox (tuple): Bounding box coordinates in the format (x_min, y_min, x_max, y_max). + + Returns: + angle (degree): Degree value of angle between three points + """ + x_min, y_min, x_max, y_max = bbox + width = x_max - x_min + height = y_max - y_min + return width, height, width * height + + def draw_region(self, reg_pts=None, color=(0, 255, 0), thickness=5): + """ + Draw region line. + + Args: + reg_pts (list): Region Points (for line 2 points, for region 4 points) + color (tuple): Region Color value + thickness (int): Region area thickness value + """ + cv2.polylines(self.im, [np.array(reg_pts, dtype=np.int32)], isClosed=True, color=color, thickness=thickness) + + def draw_centroid_and_tracks(self, track, color=(255, 0, 255), track_thickness=2): + """ + Draw centroid point and track trails. + + Args: + track (list): object tracking points for trails display + color (tuple): tracks line color + track_thickness (int): track line thickness value + """ + points = np.hstack(track).astype(np.int32).reshape((-1, 1, 2)) + cv2.polylines(self.im, [points], isClosed=False, color=color, thickness=track_thickness) + cv2.circle(self.im, (int(track[-1][0]), int(track[-1][1])), track_thickness * 2, color, -1) + + def queue_counts_display(self, label, points=None, region_color=(255, 255, 255), txt_color=(0, 0, 0), fontsize=0.7): + """ + Displays queue counts on an image centered at the points with customizable font size and colors. + + Args: + label (str): queue counts label + points (tuple): region points for center point calculation to display text + region_color (RGB): queue region color + txt_color (RGB): text display color + fontsize (float): text fontsize + """ + x_values = [point[0] for point in points] + y_values = [point[1] for point in points] + center_x = sum(x_values) // len(points) + center_y = sum(y_values) // len(points) + + text_size = cv2.getTextSize(label, 0, fontScale=fontsize, thickness=self.tf)[0] + text_width = text_size[0] + text_height = text_size[1] + + rect_width = text_width + 20 + rect_height = text_height + 20 + rect_top_left = (center_x - rect_width // 2, center_y - rect_height // 2) + rect_bottom_right = (center_x + rect_width // 2, center_y + rect_height // 2) + cv2.rectangle(self.im, rect_top_left, rect_bottom_right, region_color, -1) + + text_x = center_x - text_width // 2 + text_y = center_y + text_height // 2 + + # Draw text + cv2.putText( + self.im, + label, + (text_x, text_y), + 0, + fontScale=fontsize, + color=txt_color, + thickness=self.tf, + lineType=cv2.LINE_AA, + ) + + def display_counts(self, counts=None, count_bg_color=(0, 0, 0), count_txt_color=(255, 255, 255)): + """ + Display counts on im0 with text background and border. + + Args: + counts (str): objects count data + count_bg_color (RGB Color): counts highlighter color + count_txt_color (RGB Color): counts display color + """ + + tl = self.tf or round(0.002 * (self.im.shape[0] + self.im.shape[1]) / 2) + 1 + tf = max(tl - 1, 1) + + t_sizes = [cv2.getTextSize(str(count), 0, fontScale=self.sf, thickness=self.tf)[0] for count in counts] + + max_text_width = max([size[0] for size in t_sizes]) + max_text_height = max([size[1] for size in t_sizes]) + + text_x = self.im.shape[1] - int(self.im.shape[1] * 0.025 + max_text_width) + text_y = int(self.im.shape[0] * 0.025) + + # Calculate dynamic gap between each count value based on the width of the image + dynamic_gap = max(1, self.im.shape[1] // 100) * tf + + for i, count in enumerate(counts): + text_x_pos = text_x + text_y_pos = text_y + i * dynamic_gap # Adjust vertical position with dynamic gap + + # Draw the border + cv2.rectangle( + self.im, + (text_x_pos - (10 * tf), text_y_pos - (10 * tf)), + (text_x_pos + max_text_width + (10 * tf), text_y_pos + max_text_height + (10 * tf)), + count_bg_color, + -1, + ) + + # Draw the count text + cv2.putText( + self.im, + str(count), + (text_x_pos, text_y_pos + max_text_height), + 0, + fontScale=self.sf, + color=count_txt_color, + thickness=self.tf, + lineType=cv2.LINE_AA, + ) + + text_y_pos += tf * max_text_height + + @staticmethod + def estimate_pose_angle(a, b, c): + """ + Calculate the pose angle for object. + + Args: + a (float) : The value of pose point a + b (float): The value of pose point b + c (float): The value o pose point c + + Returns: + angle (degree): Degree value of angle between three points + """ + a, b, c = np.array(a), np.array(b), np.array(c) + radians = np.arctan2(c[1] - b[1], c[0] - b[0]) - np.arctan2(a[1] - b[1], a[0] - b[0]) + angle = np.abs(radians * 180.0 / np.pi) + if angle > 180.0: + angle = 360 - angle + return angle + + def draw_specific_points(self, keypoints, indices=[2, 5, 7], shape=(640, 640), radius=2, conf_thres=0.25): + """ + Draw specific keypoints for gym steps counting. + + Args: + keypoints (list): list of keypoints data to be plotted + indices (list): keypoints ids list to be plotted + shape (tuple): imgsz for model inference + radius (int): Keypoint radius value + """ + for i, k in enumerate(keypoints): + if i in indices: + x_coord, y_coord = k[0], k[1] + if x_coord % shape[1] != 0 and y_coord % shape[0] != 0: + if len(k) == 3: + conf = k[2] + if conf < conf_thres: + continue + cv2.circle(self.im, (int(x_coord), int(y_coord)), radius, (0, 255, 0), -1, lineType=cv2.LINE_AA) + return self.im + + def plot_angle_and_count_and_stage(self, angle_text, count_text, stage_text, center_kpt, line_thickness=2): + """ + Plot the pose angle, count value and step stage. + + Args: + angle_text (str): angle value for workout monitoring + count_text (str): counts value for workout monitoring + stage_text (str): stage decision for workout monitoring + center_kpt (int): centroid pose index for workout monitoring + line_thickness (int): thickness for text display + """ + angle_text, count_text, stage_text = (f" {angle_text:.2f}", f"Steps : {count_text}", f" {stage_text}") + font_scale = 0.6 + (line_thickness / 10.0) + + # Draw angle + (angle_text_width, angle_text_height), _ = cv2.getTextSize(angle_text, 0, font_scale, line_thickness) + angle_text_position = (int(center_kpt[0]), int(center_kpt[1])) + angle_background_position = (angle_text_position[0], angle_text_position[1] - angle_text_height - 5) + angle_background_size = (angle_text_width + 2 * 5, angle_text_height + 2 * 5 + (line_thickness * 2)) + cv2.rectangle( + self.im, + angle_background_position, + ( + angle_background_position[0] + angle_background_size[0], + angle_background_position[1] + angle_background_size[1], + ), + (255, 255, 255), + -1, + ) + cv2.putText(self.im, angle_text, angle_text_position, 0, font_scale, (0, 0, 0), line_thickness) + + # Draw Counts + (count_text_width, count_text_height), _ = cv2.getTextSize(count_text, 0, font_scale, line_thickness) + count_text_position = (angle_text_position[0], angle_text_position[1] + angle_text_height + 20) + count_background_position = ( + angle_background_position[0], + angle_background_position[1] + angle_background_size[1] + 5, + ) + count_background_size = (count_text_width + 10, count_text_height + 10 + (line_thickness * 2)) + + cv2.rectangle( + self.im, + count_background_position, + ( + count_background_position[0] + count_background_size[0], + count_background_position[1] + count_background_size[1], + ), + (255, 255, 255), + -1, + ) + cv2.putText(self.im, count_text, count_text_position, 0, font_scale, (0, 0, 0), line_thickness) + + # Draw Stage + (stage_text_width, stage_text_height), _ = cv2.getTextSize(stage_text, 0, font_scale, line_thickness) + stage_text_position = (int(center_kpt[0]), int(center_kpt[1]) + angle_text_height + count_text_height + 40) + stage_background_position = (stage_text_position[0], stage_text_position[1] - stage_text_height - 5) + stage_background_size = (stage_text_width + 10, stage_text_height + 10) + + cv2.rectangle( + self.im, + stage_background_position, + ( + stage_background_position[0] + stage_background_size[0], + stage_background_position[1] + stage_background_size[1], + ), + (255, 255, 255), + -1, + ) + cv2.putText(self.im, stage_text, stage_text_position, 0, font_scale, (0, 0, 0), line_thickness) + + def seg_bbox(self, mask, mask_color=(255, 0, 255), det_label=None, track_label=None): + """ + Function for drawing segmented object in bounding box shape. + + Args: + mask (list): masks data list for instance segmentation area plotting + mask_color (tuple): mask foreground color + det_label (str): Detection label text + track_label (str): Tracking label text + """ + cv2.polylines(self.im, [np.int32([mask])], isClosed=True, color=mask_color, thickness=2) + + label = f"Track ID: {track_label}" if track_label else det_label + text_size, _ = cv2.getTextSize(label, 0, 0.7, 1) + + cv2.rectangle( + self.im, + (int(mask[0][0]) - text_size[0] // 2 - 10, int(mask[0][1]) - text_size[1] - 10), + (int(mask[0][0]) + text_size[0] // 2 + 5, int(mask[0][1] + 5)), + mask_color, + -1, + ) + + cv2.putText( + self.im, label, (int(mask[0][0]) - text_size[0] // 2, int(mask[0][1]) - 5), 0, 0.7, (255, 255, 255), 2 + ) + + def plot_distance_and_line(self, distance_m, distance_mm, centroids, line_color, centroid_color): + """ + Plot the distance and line on frame. + + Args: + distance_m (float): Distance between two bbox centroids in meters. + distance_mm (float): Distance between two bbox centroids in millimeters. + centroids (list): Bounding box centroids data. + line_color (RGB): Distance line color. + centroid_color (RGB): Bounding box centroid color. + """ + (text_width_m, text_height_m), _ = cv2.getTextSize(f"Distance M: {distance_m:.2f}m", 0, 0.8, 2) + cv2.rectangle(self.im, (15, 25), (15 + text_width_m + 10, 25 + text_height_m + 20), (255, 255, 255), -1) + cv2.putText( + self.im, + f"Distance M: {distance_m:.2f}m", + (20, 50), + 0, + 0.8, + (0, 0, 0), + 2, + cv2.LINE_AA, + ) + + (text_width_mm, text_height_mm), _ = cv2.getTextSize(f"Distance MM: {distance_mm:.2f}mm", 0, 0.8, 2) + cv2.rectangle(self.im, (15, 75), (15 + text_width_mm + 10, 75 + text_height_mm + 20), (255, 255, 255), -1) + cv2.putText( + self.im, + f"Distance MM: {distance_mm:.2f}mm", + (20, 100), + 0, + 0.8, + (0, 0, 0), + 2, + cv2.LINE_AA, + ) + + cv2.line(self.im, centroids[0], centroids[1], line_color, 3) + cv2.circle(self.im, centroids[0], 6, centroid_color, -1) + cv2.circle(self.im, centroids[1], 6, centroid_color, -1) + + def visioneye(self, box, center_point, color=(235, 219, 11), pin_color=(255, 0, 255), thickness=2, pins_radius=10): + """ + Function for pinpoint human-vision eye mapping and plotting. + + Args: + box (list): Bounding box coordinates + center_point (tuple): center point for vision eye view + color (tuple): object centroid and line color value + pin_color (tuple): visioneye point color value + thickness (int): int value for line thickness + pins_radius (int): visioneye point radius value + """ + center_bbox = int((box[0] + box[2]) / 2), int((box[1] + box[3]) / 2) + cv2.circle(self.im, center_point, pins_radius, pin_color, -1) + cv2.circle(self.im, center_bbox, pins_radius, color, -1) + cv2.line(self.im, center_point, center_bbox, color, thickness) + + +@TryExcept() # known issue https://github.com/ultralytics/yolov5/issues/5395 +@plt_settings() +def plot_labels(boxes, cls, names=(), save_dir=Path(""), on_plot=None): + """Plot training labels including class histograms and box statistics.""" + import pandas # scope for faster 'import ultralytics' + import seaborn # scope for faster 'import ultralytics' + + # Filter matplotlib>=3.7.2 warning and Seaborn use_inf and is_categorical FutureWarnings + warnings.filterwarnings("ignore", category=UserWarning, message="The figure layout has changed to tight") + warnings.filterwarnings("ignore", category=FutureWarning) + + # Plot dataset labels + LOGGER.info(f"Plotting labels to {save_dir / 'labels.jpg'}... ") + nc = int(cls.max() + 1) # number of classes + boxes = boxes[:1000000] # limit to 1M boxes + x = pandas.DataFrame(boxes, columns=["x", "y", "width", "height"]) + + # Seaborn correlogram + seaborn.pairplot(x, corner=True, diag_kind="auto", kind="hist", diag_kws=dict(bins=50), plot_kws=dict(pmax=0.9)) + plt.savefig(save_dir / "labels_correlogram.jpg", dpi=200) + plt.close() + + # Matplotlib labels + ax = plt.subplots(2, 2, figsize=(8, 8), tight_layout=True)[1].ravel() + y = ax[0].hist(cls, bins=np.linspace(0, nc, nc + 1) - 0.5, rwidth=0.8) + for i in range(nc): + y[2].patches[i].set_color([x / 255 for x in colors(i)]) + ax[0].set_ylabel("instances") + if 0 < len(names) < 30: + ax[0].set_xticks(range(len(names))) + ax[0].set_xticklabels(list(names.values()), rotation=90, fontsize=10) + else: + ax[0].set_xlabel("classes") + seaborn.histplot(x, x="x", y="y", ax=ax[2], bins=50, pmax=0.9) + seaborn.histplot(x, x="width", y="height", ax=ax[3], bins=50, pmax=0.9) + + # Rectangles + boxes[:, 0:2] = 0.5 # center + boxes = ops.xywh2xyxy(boxes) * 1000 + img = Image.fromarray(np.ones((1000, 1000, 3), dtype=np.uint8) * 255) + for cls, box in zip(cls[:500], boxes[:500]): + ImageDraw.Draw(img).rectangle(box, width=1, outline=colors(cls)) # plot + ax[1].imshow(img) + ax[1].axis("off") + + for a in [0, 1, 2, 3]: + for s in ["top", "right", "left", "bottom"]: + ax[a].spines[s].set_visible(False) + + fname = save_dir / "labels.jpg" + plt.savefig(fname, dpi=200) + plt.close() + if on_plot: + on_plot(fname) + + +def save_one_box(xyxy, im, file=Path("im.jpg"), gain=1.02, pad=10, square=False, BGR=False, save=True): + """ + Save image crop as {file} with crop size multiple {gain} and {pad} pixels. Save and/or return crop. + + This function takes a bounding box and an image, and then saves a cropped portion of the image according + to the bounding box. Optionally, the crop can be squared, and the function allows for gain and padding + adjustments to the bounding box. + + Args: + xyxy (torch.Tensor or list): A tensor or list representing the bounding box in xyxy format. + im (numpy.ndarray): The input image. + file (Path, optional): The path where the cropped image will be saved. Defaults to 'im.jpg'. + gain (float, optional): A multiplicative factor to increase the size of the bounding box. Defaults to 1.02. + pad (int, optional): The number of pixels to add to the width and height of the bounding box. Defaults to 10. + square (bool, optional): If True, the bounding box will be transformed into a square. Defaults to False. + BGR (bool, optional): If True, the image will be saved in BGR format, otherwise in RGB. Defaults to False. + save (bool, optional): If True, the cropped image will be saved to disk. Defaults to True. + + Returns: + (numpy.ndarray): The cropped image. + + Example: + ```python + from ultralytics.utils.plotting import save_one_box + + xyxy = [50, 50, 150, 150] + im = cv2.imread('image.jpg') + cropped_im = save_one_box(xyxy, im, file='cropped.jpg', square=True) + ``` + """ + + if not isinstance(xyxy, torch.Tensor): # may be list + xyxy = torch.stack(xyxy) + b = ops.xyxy2xywh(xyxy.view(-1, 4)) # boxes + if square: + b[:, 2:] = b[:, 2:].max(1)[0].unsqueeze(1) # attempt rectangle to square + b[:, 2:] = b[:, 2:] * gain + pad # box wh * gain + pad + xyxy = ops.xywh2xyxy(b).long() + xyxy = ops.clip_boxes(xyxy, im.shape) + crop = im[int(xyxy[0, 1]) : int(xyxy[0, 3]), int(xyxy[0, 0]) : int(xyxy[0, 2]), :: (1 if BGR else -1)] + if save: + file.parent.mkdir(parents=True, exist_ok=True) # make directory + f = str(increment_path(file).with_suffix(".jpg")) + # cv2.imwrite(f, crop) # save BGR, https://github.com/ultralytics/yolov5/issues/7007 chroma subsampling issue + Image.fromarray(crop[..., ::-1]).save(f, quality=95, subsampling=0) # save RGB + return crop + + +@threaded +def plot_images( + images, + batch_idx, + cls, + bboxes=np.zeros(0, dtype=np.float32), + confs=None, + masks=np.zeros(0, dtype=np.uint8), + kpts=np.zeros((0, 51), dtype=np.float32), + paths=None, + fname="images.jpg", + names=None, + on_plot=None, + max_subplots=16, + save=True, + conf_thres=0.25, +): + """Plot image grid with labels.""" + if isinstance(images, torch.Tensor): + images = images.cpu().float().numpy() + if isinstance(cls, torch.Tensor): + cls = cls.cpu().numpy() + if isinstance(bboxes, torch.Tensor): + bboxes = bboxes.cpu().numpy() + if isinstance(masks, torch.Tensor): + masks = masks.cpu().numpy().astype(int) + if isinstance(kpts, torch.Tensor): + kpts = kpts.cpu().numpy() + if isinstance(batch_idx, torch.Tensor): + batch_idx = batch_idx.cpu().numpy() + + max_size = 1920 # max image size + bs, _, h, w = images.shape # batch size, _, height, width + bs = min(bs, max_subplots) # limit plot images + ns = np.ceil(bs**0.5) # number of subplots (square) + if np.max(images[0]) <= 1: + images *= 255 # de-normalise (optional) + + # Build Image + mosaic = np.full((int(ns * h), int(ns * w), 3), 255, dtype=np.uint8) # init + for i in range(bs): + x, y = int(w * (i // ns)), int(h * (i % ns)) # block origin + mosaic[y : y + h, x : x + w, :] = images[i].transpose(1, 2, 0) + + # Resize (optional) + scale = max_size / ns / max(h, w) + if scale < 1: + h = math.ceil(scale * h) + w = math.ceil(scale * w) + mosaic = cv2.resize(mosaic, tuple(int(x * ns) for x in (w, h))) + + # Annotate + fs = int((h + w) * ns * 0.01) # font size + annotator = Annotator(mosaic, line_width=round(fs / 10), font_size=fs, pil=True, example=names) + for i in range(bs): + x, y = int(w * (i // ns)), int(h * (i % ns)) # block origin + annotator.rectangle([x, y, x + w, y + h], None, (255, 255, 255), width=2) # borders + if paths: + annotator.text((x + 5, y + 5), text=Path(paths[i]).name[:40], txt_color=(220, 220, 220)) # filenames + if len(cls) > 0: + idx = batch_idx == i + classes = cls[idx].astype("int") + labels = confs is None + + if len(bboxes): + boxes = bboxes[idx] + conf = confs[idx] if confs is not None else None # check for confidence presence (label vs pred) + if len(boxes): + if boxes[:, :4].max() <= 1.1: # if normalized with tolerance 0.1 + boxes[..., [0, 2]] *= w # scale to pixels + boxes[..., [1, 3]] *= h + elif scale < 1: # absolute coords need scale if image scales + boxes[..., :4] *= scale + boxes[..., 0] += x + boxes[..., 1] += y + is_obb = boxes.shape[-1] == 5 # xywhr + boxes = ops.xywhr2xyxyxyxy(boxes) if is_obb else ops.xywh2xyxy(boxes) + for j, box in enumerate(boxes.astype(np.int64).tolist()): + c = classes[j] + color = colors(c) + c = names.get(c, c) if names else c + if labels or conf[j] > conf_thres: + label = f"{c}" if labels else f"{c} {conf[j]:.1f}" + annotator.box_label(box, label, color=color, rotated=is_obb) + + elif len(classes): + for c in classes: + color = colors(c) + c = names.get(c, c) if names else c + annotator.text((x, y), f"{c}", txt_color=color, box_style=True) + + # Plot keypoints + if len(kpts): + kpts_ = kpts[idx].copy() + if len(kpts_): + if kpts_[..., 0].max() <= 1.01 or kpts_[..., 1].max() <= 1.01: # if normalized with tolerance .01 + kpts_[..., 0] *= w # scale to pixels + kpts_[..., 1] *= h + elif scale < 1: # absolute coords need scale if image scales + kpts_ *= scale + kpts_[..., 0] += x + kpts_[..., 1] += y + for j in range(len(kpts_)): + if labels or conf[j] > conf_thres: + annotator.kpts(kpts_[j], conf_thres=conf_thres) + + # Plot masks + if len(masks): + if idx.shape[0] == masks.shape[0]: # overlap_masks=False + image_masks = masks[idx] + else: # overlap_masks=True + image_masks = masks[[i]] # (1, 640, 640) + nl = idx.sum() + index = np.arange(nl).reshape((nl, 1, 1)) + 1 + image_masks = np.repeat(image_masks, nl, axis=0) + image_masks = np.where(image_masks == index, 1.0, 0.0) + + im = np.asarray(annotator.im).copy() + for j in range(len(image_masks)): + if labels or conf[j] > conf_thres: + color = colors(classes[j]) + mh, mw = image_masks[j].shape + if mh != h or mw != w: + mask = image_masks[j].astype(np.uint8) + mask = cv2.resize(mask, (w, h)) + mask = mask.astype(bool) + else: + mask = image_masks[j].astype(bool) + with contextlib.suppress(Exception): + im[y : y + h, x : x + w, :][mask] = ( + im[y : y + h, x : x + w, :][mask] * 0.4 + np.array(color) * 0.6 + ) + annotator.fromarray(im) + if not save: + return np.asarray(annotator.im) + annotator.im.save(fname) # save + if on_plot: + on_plot(fname) + + +@plt_settings() +def plot_results(file="path/to/results.csv", dir="", segment=False, pose=False, classify=False, on_plot=None): + """ + Plot training results from a results CSV file. The function supports various types of data including segmentation, + pose estimation, and classification. Plots are saved as 'results.png' in the directory where the CSV is located. + + Args: + file (str, optional): Path to the CSV file containing the training results. Defaults to 'path/to/results.csv'. + dir (str, optional): Directory where the CSV file is located if 'file' is not provided. Defaults to ''. + segment (bool, optional): Flag to indicate if the data is for segmentation. Defaults to False. + pose (bool, optional): Flag to indicate if the data is for pose estimation. Defaults to False. + classify (bool, optional): Flag to indicate if the data is for classification. Defaults to False. + on_plot (callable, optional): Callback function to be executed after plotting. Takes filename as an argument. + Defaults to None. + + Example: + ```python + from ultralytics.utils.plotting import plot_results + + plot_results('path/to/results.csv', segment=True) + ``` + """ + import pandas as pd # scope for faster 'import ultralytics' + from scipy.ndimage import gaussian_filter1d + + save_dir = Path(file).parent if file else Path(dir) + if classify: + fig, ax = plt.subplots(2, 2, figsize=(6, 6), tight_layout=True) + index = [1, 4, 2, 3] + elif segment: + fig, ax = plt.subplots(2, 8, figsize=(18, 6), tight_layout=True) + index = [1, 2, 3, 4, 5, 6, 9, 10, 13, 14, 15, 16, 7, 8, 11, 12] + elif pose: + fig, ax = plt.subplots(2, 9, figsize=(21, 6), tight_layout=True) + index = [1, 2, 3, 4, 5, 6, 7, 10, 11, 14, 15, 16, 17, 18, 8, 9, 12, 13] + else: + fig, ax = plt.subplots(2, 5, figsize=(12, 6), tight_layout=True) + index = [1, 2, 3, 4, 5, 8, 9, 10, 6, 7] + ax = ax.ravel() + files = list(save_dir.glob("results*.csv")) + assert len(files), f"No results.csv files found in {save_dir.resolve()}, nothing to plot." + for f in files: + try: + data = pd.read_csv(f) + s = [x.strip() for x in data.columns] + x = data.values[:, 0] + for i, j in enumerate(index): + y = data.values[:, j].astype("float") + # y[y == 0] = np.nan # don't show zero values + ax[i].plot(x, y, marker=".", label=f.stem, linewidth=2, markersize=8) # actual results + ax[i].plot(x, gaussian_filter1d(y, sigma=3), ":", label="smooth", linewidth=2) # smoothing line + ax[i].set_title(s[j], fontsize=12) + # if j in {8, 9, 10}: # share train and val loss y axes + # ax[i].get_shared_y_axes().join(ax[i], ax[i - 5]) + except Exception as e: + LOGGER.warning(f"WARNING: Plotting error for {f}: {e}") + ax[1].legend() + fname = save_dir / "results.png" + fig.savefig(fname, dpi=200) + plt.close() + if on_plot: + on_plot(fname) + + +def plt_color_scatter(v, f, bins=20, cmap="viridis", alpha=0.8, edgecolors="none"): + """ + Plots a scatter plot with points colored based on a 2D histogram. + + Args: + v (array-like): Values for the x-axis. + f (array-like): Values for the y-axis. + bins (int, optional): Number of bins for the histogram. Defaults to 20. + cmap (str, optional): Colormap for the scatter plot. Defaults to 'viridis'. + alpha (float, optional): Alpha for the scatter plot. Defaults to 0.8. + edgecolors (str, optional): Edge colors for the scatter plot. Defaults to 'none'. + + Examples: + >>> v = np.random.rand(100) + >>> f = np.random.rand(100) + >>> plt_color_scatter(v, f) + """ + + # Calculate 2D histogram and corresponding colors + hist, xedges, yedges = np.histogram2d(v, f, bins=bins) + colors = [ + hist[ + min(np.digitize(v[i], xedges, right=True) - 1, hist.shape[0] - 1), + min(np.digitize(f[i], yedges, right=True) - 1, hist.shape[1] - 1), + ] + for i in range(len(v)) + ] + + # Scatter plot + plt.scatter(v, f, c=colors, cmap=cmap, alpha=alpha, edgecolors=edgecolors) + + +def plot_tune_results(csv_file="tune_results.csv"): + """ + Plot the evolution results stored in an 'tune_results.csv' file. The function generates a scatter plot for each key + in the CSV, color-coded based on fitness scores. The best-performing configurations are highlighted on the plots. + + Args: + csv_file (str, optional): Path to the CSV file containing the tuning results. Defaults to 'tune_results.csv'. + + Examples: + >>> plot_tune_results('path/to/tune_results.csv') + """ + + import pandas as pd # scope for faster 'import ultralytics' + from scipy.ndimage import gaussian_filter1d + + # Scatter plots for each hyperparameter + csv_file = Path(csv_file) + data = pd.read_csv(csv_file) + num_metrics_columns = 1 + keys = [x.strip() for x in data.columns][num_metrics_columns:] + x = data.values + fitness = x[:, 0] # fitness + j = np.argmax(fitness) # max fitness index + n = math.ceil(len(keys) ** 0.5) # columns and rows in plot + plt.figure(figsize=(10, 10), tight_layout=True) + for i, k in enumerate(keys): + v = x[:, i + num_metrics_columns] + mu = v[j] # best single result + plt.subplot(n, n, i + 1) + plt_color_scatter(v, fitness, cmap="viridis", alpha=0.8, edgecolors="none") + plt.plot(mu, fitness.max(), "k+", markersize=15) + plt.title(f"{k} = {mu:.3g}", fontdict={"size": 9}) # limit to 40 characters + plt.tick_params(axis="both", labelsize=8) # Set axis label size to 8 + if i % n != 0: + plt.yticks([]) + + file = csv_file.with_name("tune_scatter_plots.png") # filename + plt.savefig(file, dpi=200) + plt.close() + LOGGER.info(f"Saved {file}") + + # Fitness vs iteration + x = range(1, len(fitness) + 1) + plt.figure(figsize=(10, 6), tight_layout=True) + plt.plot(x, fitness, marker="o", linestyle="none", label="fitness") + plt.plot(x, gaussian_filter1d(fitness, sigma=3), ":", label="smoothed", linewidth=2) # smoothing line + plt.title("Fitness vs Iteration") + plt.xlabel("Iteration") + plt.ylabel("Fitness") + plt.grid(True) + plt.legend() + + file = csv_file.with_name("tune_fitness.png") # filename + plt.savefig(file, dpi=200) + plt.close() + LOGGER.info(f"Saved {file}") + + +def output_to_target(output, max_det=300): + """Convert model output to target format [batch_id, class_id, x, y, w, h, conf] for plotting.""" + targets = [] + for i, o in enumerate(output): + box, conf, cls = o[:max_det, :6].cpu().split((4, 1, 1), 1) + j = torch.full((conf.shape[0], 1), i) + targets.append(torch.cat((j, cls, ops.xyxy2xywh(box), conf), 1)) + targets = torch.cat(targets, 0).numpy() + return targets[:, 0], targets[:, 1], targets[:, 2:-1], targets[:, -1] + + +def output_to_rotated_target(output, max_det=300): + """Convert model output to target format [batch_id, class_id, x, y, w, h, conf] for plotting.""" + targets = [] + for i, o in enumerate(output): + box, conf, cls, angle = o[:max_det].cpu().split((4, 1, 1, 1), 1) + j = torch.full((conf.shape[0], 1), i) + targets.append(torch.cat((j, cls, box, angle, conf), 1)) + targets = torch.cat(targets, 0).numpy() + return targets[:, 0], targets[:, 1], targets[:, 2:-1], targets[:, -1] + + +def feature_visualization(x, module_type, stage, n=32, save_dir=Path("runs/detect/exp")): + """ + Visualize feature maps of a given model module during inference. + + Args: + x (torch.Tensor): Features to be visualized. + module_type (str): Module type. + stage (int): Module stage within the model. + n (int, optional): Maximum number of feature maps to plot. Defaults to 32. + save_dir (Path, optional): Directory to save results. Defaults to Path('runs/detect/exp'). + """ + for m in ["Detect", "Pose", "Segment"]: + if m in module_type: + return + _, channels, height, width = x.shape # batch, channels, height, width + if height > 1 and width > 1: + f = save_dir / f"stage{stage}_{module_type.split('.')[-1]}_features.png" # filename + + blocks = torch.chunk(x[0].cpu(), channels, dim=0) # select batch index 0, block by channels + n = min(n, channels) # number of plots + _, ax = plt.subplots(math.ceil(n / 8), 8, tight_layout=True) # 8 rows x n/8 cols + ax = ax.ravel() + plt.subplots_adjust(wspace=0.05, hspace=0.05) + for i in range(n): + ax[i].imshow(blocks[i].squeeze()) # cmap='gray' + ax[i].axis("off") + + LOGGER.info(f"Saving {f}... ({n}/{channels})") + plt.savefig(f, dpi=300, bbox_inches="tight") + plt.close() + np.save(str(f.with_suffix(".npy")), x[0].cpu().numpy()) # npy save diff --git a/ultralytics/utils/tal.py b/ultralytics/utils/tal.py new file mode 100644 index 0000000..9cee050 --- /dev/null +++ b/ultralytics/utils/tal.py @@ -0,0 +1,344 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import torch +import torch.nn as nn + +from .checks import check_version +from .metrics import bbox_iou, probiou +from .ops import xywhr2xyxyxyxy + +TORCH_1_10 = check_version(torch.__version__, "1.10.0") + + +class TaskAlignedAssigner(nn.Module): + """ + A task-aligned assigner for object detection. + + This class assigns ground-truth (gt) objects to anchors based on the task-aligned metric, which combines both + classification and localization information. + + Attributes: + topk (int): The number of top candidates to consider. + num_classes (int): The number of object classes. + alpha (float): The alpha parameter for the classification component of the task-aligned metric. + beta (float): The beta parameter for the localization component of the task-aligned metric. + eps (float): A small value to prevent division by zero. + """ + + def __init__(self, topk=13, num_classes=80, alpha=1.0, beta=6.0, eps=1e-9): + """Initialize a TaskAlignedAssigner object with customizable hyperparameters.""" + super().__init__() + self.topk = topk + self.num_classes = num_classes + self.bg_idx = num_classes + self.alpha = alpha + self.beta = beta + self.eps = eps + + @torch.no_grad() + def forward(self, pd_scores, pd_bboxes, anc_points, gt_labels, gt_bboxes, mask_gt): + """ + Compute the task-aligned assignment. Reference code is available at + https://github.com/Nioolek/PPYOLOE_pytorch/blob/master/ppyoloe/assigner/tal_assigner.py. + + Args: + pd_scores (Tensor): shape(bs, num_total_anchors, num_classes) + pd_bboxes (Tensor): shape(bs, num_total_anchors, 4) + anc_points (Tensor): shape(num_total_anchors, 2) + gt_labels (Tensor): shape(bs, n_max_boxes, 1) + gt_bboxes (Tensor): shape(bs, n_max_boxes, 4) + mask_gt (Tensor): shape(bs, n_max_boxes, 1) + + Returns: + target_labels (Tensor): shape(bs, num_total_anchors) + target_bboxes (Tensor): shape(bs, num_total_anchors, 4) + target_scores (Tensor): shape(bs, num_total_anchors, num_classes) + fg_mask (Tensor): shape(bs, num_total_anchors) + target_gt_idx (Tensor): shape(bs, num_total_anchors) + """ + self.bs = pd_scores.shape[0] + self.n_max_boxes = gt_bboxes.shape[1] + + if self.n_max_boxes == 0: + device = gt_bboxes.device + return ( + torch.full_like(pd_scores[..., 0], self.bg_idx).to(device), + torch.zeros_like(pd_bboxes).to(device), + torch.zeros_like(pd_scores).to(device), + torch.zeros_like(pd_scores[..., 0]).to(device), + torch.zeros_like(pd_scores[..., 0]).to(device), + ) + + mask_pos, align_metric, overlaps = self.get_pos_mask( + pd_scores, pd_bboxes, gt_labels, gt_bboxes, anc_points, mask_gt + ) + + target_gt_idx, fg_mask, mask_pos = self.select_highest_overlaps(mask_pos, overlaps, self.n_max_boxes) + + # Assigned target + target_labels, target_bboxes, target_scores = self.get_targets(gt_labels, gt_bboxes, target_gt_idx, fg_mask) + + # Normalize + align_metric *= mask_pos + pos_align_metrics = align_metric.amax(dim=-1, keepdim=True) # b, max_num_obj + pos_overlaps = (overlaps * mask_pos).amax(dim=-1, keepdim=True) # b, max_num_obj + norm_align_metric = (align_metric * pos_overlaps / (pos_align_metrics + self.eps)).amax(-2).unsqueeze(-1) + target_scores = target_scores * norm_align_metric + + return target_labels, target_bboxes, target_scores, fg_mask.bool(), target_gt_idx + + def get_pos_mask(self, pd_scores, pd_bboxes, gt_labels, gt_bboxes, anc_points, mask_gt): + """Get in_gts mask, (b, max_num_obj, h*w).""" + mask_in_gts = self.select_candidates_in_gts(anc_points, gt_bboxes) + # Get anchor_align metric, (b, max_num_obj, h*w) + align_metric, overlaps = self.get_box_metrics(pd_scores, pd_bboxes, gt_labels, gt_bboxes, mask_in_gts * mask_gt) + # Get topk_metric mask, (b, max_num_obj, h*w) + mask_topk = self.select_topk_candidates(align_metric, topk_mask=mask_gt.expand(-1, -1, self.topk).bool()) + # Merge all mask to a final mask, (b, max_num_obj, h*w) + mask_pos = mask_topk * mask_in_gts * mask_gt + + return mask_pos, align_metric, overlaps + + def get_box_metrics(self, pd_scores, pd_bboxes, gt_labels, gt_bboxes, mask_gt): + """Compute alignment metric given predicted and ground truth bounding boxes.""" + na = pd_bboxes.shape[-2] + mask_gt = mask_gt.bool() # b, max_num_obj, h*w + overlaps = torch.zeros([self.bs, self.n_max_boxes, na], dtype=pd_bboxes.dtype, device=pd_bboxes.device) + bbox_scores = torch.zeros([self.bs, self.n_max_boxes, na], dtype=pd_scores.dtype, device=pd_scores.device) + + ind = torch.zeros([2, self.bs, self.n_max_boxes], dtype=torch.long) # 2, b, max_num_obj + ind[0] = torch.arange(end=self.bs).view(-1, 1).expand(-1, self.n_max_boxes) # b, max_num_obj + ind[1] = gt_labels.squeeze(-1) # b, max_num_obj + # Get the scores of each grid for each gt cls + bbox_scores[mask_gt] = pd_scores[ind[0], :, ind[1]][mask_gt] # b, max_num_obj, h*w + + # (b, max_num_obj, 1, 4), (b, 1, h*w, 4) + pd_boxes = pd_bboxes.unsqueeze(1).expand(-1, self.n_max_boxes, -1, -1)[mask_gt] + gt_boxes = gt_bboxes.unsqueeze(2).expand(-1, -1, na, -1)[mask_gt] + overlaps[mask_gt] = self.iou_calculation(gt_boxes, pd_boxes) + + align_metric = bbox_scores.pow(self.alpha) * overlaps.pow(self.beta) + return align_metric, overlaps + + def iou_calculation(self, gt_bboxes, pd_bboxes): + """IoU calculation for horizontal bounding boxes.""" + return bbox_iou(gt_bboxes, pd_bboxes, xywh=False, CIoU=True).squeeze(-1).clamp_(0) + + def select_topk_candidates(self, metrics, largest=True, topk_mask=None): + """ + Select the top-k candidates based on the given metrics. + + Args: + metrics (Tensor): A tensor of shape (b, max_num_obj, h*w), where b is the batch size, + max_num_obj is the maximum number of objects, and h*w represents the + total number of anchor points. + largest (bool): If True, select the largest values; otherwise, select the smallest values. + topk_mask (Tensor): An optional boolean tensor of shape (b, max_num_obj, topk), where + topk is the number of top candidates to consider. If not provided, + the top-k values are automatically computed based on the given metrics. + + Returns: + (Tensor): A tensor of shape (b, max_num_obj, h*w) containing the selected top-k candidates. + """ + + # (b, max_num_obj, topk) + topk_metrics, topk_idxs = torch.topk(metrics, self.topk, dim=-1, largest=largest) + if topk_mask is None: + topk_mask = (topk_metrics.max(-1, keepdim=True)[0] > self.eps).expand_as(topk_idxs) + # (b, max_num_obj, topk) + topk_idxs.masked_fill_(~topk_mask, 0) + + # (b, max_num_obj, topk, h*w) -> (b, max_num_obj, h*w) + count_tensor = torch.zeros(metrics.shape, dtype=torch.int8, device=topk_idxs.device) + ones = torch.ones_like(topk_idxs[:, :, :1], dtype=torch.int8, device=topk_idxs.device) + for k in range(self.topk): + # Expand topk_idxs for each value of k and add 1 at the specified positions + count_tensor.scatter_add_(-1, topk_idxs[:, :, k : k + 1], ones) + # count_tensor.scatter_add_(-1, topk_idxs, torch.ones_like(topk_idxs, dtype=torch.int8, device=topk_idxs.device)) + # Filter invalid bboxes + count_tensor.masked_fill_(count_tensor > 1, 0) + + return count_tensor.to(metrics.dtype) + + def get_targets(self, gt_labels, gt_bboxes, target_gt_idx, fg_mask): + """ + Compute target labels, target bounding boxes, and target scores for the positive anchor points. + + Args: + gt_labels (Tensor): Ground truth labels of shape (b, max_num_obj, 1), where b is the + batch size and max_num_obj is the maximum number of objects. + gt_bboxes (Tensor): Ground truth bounding boxes of shape (b, max_num_obj, 4). + target_gt_idx (Tensor): Indices of the assigned ground truth objects for positive + anchor points, with shape (b, h*w), where h*w is the total + number of anchor points. + fg_mask (Tensor): A boolean tensor of shape (b, h*w) indicating the positive + (foreground) anchor points. + + Returns: + (Tuple[Tensor, Tensor, Tensor]): A tuple containing the following tensors: + - target_labels (Tensor): Shape (b, h*w), containing the target labels for + positive anchor points. + - target_bboxes (Tensor): Shape (b, h*w, 4), containing the target bounding boxes + for positive anchor points. + - target_scores (Tensor): Shape (b, h*w, num_classes), containing the target scores + for positive anchor points, where num_classes is the number + of object classes. + """ + + # Assigned target labels, (b, 1) + batch_ind = torch.arange(end=self.bs, dtype=torch.int64, device=gt_labels.device)[..., None] + target_gt_idx = target_gt_idx + batch_ind * self.n_max_boxes # (b, h*w) + target_labels = gt_labels.long().flatten()[target_gt_idx] # (b, h*w) + + # Assigned target boxes, (b, max_num_obj, 4) -> (b, h*w, 4) + target_bboxes = gt_bboxes.view(-1, gt_bboxes.shape[-1])[target_gt_idx] + + # Assigned target scores + target_labels.clamp_(0) + + # 10x faster than F.one_hot() + target_scores = torch.zeros( + (target_labels.shape[0], target_labels.shape[1], self.num_classes), + dtype=torch.int64, + device=target_labels.device, + ) # (b, h*w, 80) + target_scores.scatter_(2, target_labels.unsqueeze(-1), 1) + + fg_scores_mask = fg_mask[:, :, None].repeat(1, 1, self.num_classes) # (b, h*w, 80) + target_scores = torch.where(fg_scores_mask > 0, target_scores, 0) + + return target_labels, target_bboxes, target_scores + + @staticmethod + def select_candidates_in_gts(xy_centers, gt_bboxes, eps=1e-9): + """ + Select the positive anchor center in gt. + + Args: + xy_centers (Tensor): shape(h*w, 2) + gt_bboxes (Tensor): shape(b, n_boxes, 4) + + Returns: + (Tensor): shape(b, n_boxes, h*w) + """ + n_anchors = xy_centers.shape[0] + bs, n_boxes, _ = gt_bboxes.shape + lt, rb = gt_bboxes.view(-1, 1, 4).chunk(2, 2) # left-top, right-bottom + bbox_deltas = torch.cat((xy_centers[None] - lt, rb - xy_centers[None]), dim=2).view(bs, n_boxes, n_anchors, -1) + # return (bbox_deltas.min(3)[0] > eps).to(gt_bboxes.dtype) + return bbox_deltas.amin(3).gt_(eps) + + @staticmethod + def select_highest_overlaps(mask_pos, overlaps, n_max_boxes): + """ + If an anchor box is assigned to multiple gts, the one with the highest IoU will be selected. + + Args: + mask_pos (Tensor): shape(b, n_max_boxes, h*w) + overlaps (Tensor): shape(b, n_max_boxes, h*w) + + Returns: + target_gt_idx (Tensor): shape(b, h*w) + fg_mask (Tensor): shape(b, h*w) + mask_pos (Tensor): shape(b, n_max_boxes, h*w) + """ + # (b, n_max_boxes, h*w) -> (b, h*w) + fg_mask = mask_pos.sum(-2) + if fg_mask.max() > 1: # one anchor is assigned to multiple gt_bboxes + mask_multi_gts = (fg_mask.unsqueeze(1) > 1).expand(-1, n_max_boxes, -1) # (b, n_max_boxes, h*w) + max_overlaps_idx = overlaps.argmax(1) # (b, h*w) + + is_max_overlaps = torch.zeros(mask_pos.shape, dtype=mask_pos.dtype, device=mask_pos.device) + is_max_overlaps.scatter_(1, max_overlaps_idx.unsqueeze(1), 1) + + mask_pos = torch.where(mask_multi_gts, is_max_overlaps, mask_pos).float() # (b, n_max_boxes, h*w) + fg_mask = mask_pos.sum(-2) + # Find each grid serve which gt(index) + target_gt_idx = mask_pos.argmax(-2) # (b, h*w) + return target_gt_idx, fg_mask, mask_pos + + +class RotatedTaskAlignedAssigner(TaskAlignedAssigner): + def iou_calculation(self, gt_bboxes, pd_bboxes): + """IoU calculation for rotated bounding boxes.""" + return probiou(gt_bboxes, pd_bboxes).squeeze(-1).clamp_(0) + + @staticmethod + def select_candidates_in_gts(xy_centers, gt_bboxes): + """ + Select the positive anchor center in gt for rotated bounding boxes. + + Args: + xy_centers (Tensor): shape(h*w, 2) + gt_bboxes (Tensor): shape(b, n_boxes, 5) + + Returns: + (Tensor): shape(b, n_boxes, h*w) + """ + # (b, n_boxes, 5) --> (b, n_boxes, 4, 2) + corners = xywhr2xyxyxyxy(gt_bboxes) + # (b, n_boxes, 1, 2) + a, b, _, d = corners.split(1, dim=-2) + ab = b - a + ad = d - a + + # (b, n_boxes, h*w, 2) + ap = xy_centers - a + norm_ab = (ab * ab).sum(dim=-1) + norm_ad = (ad * ad).sum(dim=-1) + ap_dot_ab = (ap * ab).sum(dim=-1) + ap_dot_ad = (ap * ad).sum(dim=-1) + return (ap_dot_ab >= 0) & (ap_dot_ab <= norm_ab) & (ap_dot_ad >= 0) & (ap_dot_ad <= norm_ad) # is_in_box + + +def make_anchors(feats, strides, grid_cell_offset=0.5): + """Generate anchors from features.""" + anchor_points, stride_tensor = [], [] + assert feats is not None + dtype, device = feats[0].dtype, feats[0].device + for i, stride in enumerate(strides): + _, _, h, w = feats[i].shape + sx = torch.arange(end=w, device=device, dtype=dtype) + grid_cell_offset # shift x + sy = torch.arange(end=h, device=device, dtype=dtype) + grid_cell_offset # shift y + sy, sx = torch.meshgrid(sy, sx, indexing="ij") if TORCH_1_10 else torch.meshgrid(sy, sx) + anchor_points.append(torch.stack((sx, sy), -1).view(-1, 2)) + stride_tensor.append(torch.full((h * w, 1), stride, dtype=dtype, device=device)) + return torch.cat(anchor_points), torch.cat(stride_tensor) + + +def dist2bbox(distance, anchor_points, xywh=True, dim=-1): + """Transform distance(ltrb) to box(xywh or xyxy).""" + lt, rb = distance.chunk(2, dim) + x1y1 = anchor_points - lt + x2y2 = anchor_points + rb + if xywh: + c_xy = (x1y1 + x2y2) / 2 + wh = x2y2 - x1y1 + return torch.cat((c_xy, wh), dim) # xywh bbox + return torch.cat((x1y1, x2y2), dim) # xyxy bbox + + +def bbox2dist(anchor_points, bbox, reg_max): + """Transform bbox(xyxy) to dist(ltrb).""" + x1y1, x2y2 = bbox.chunk(2, -1) + return torch.cat((anchor_points - x1y1, x2y2 - anchor_points), -1).clamp_(0, reg_max - 0.01) # dist (lt, rb) + + +def dist2rbox(pred_dist, pred_angle, anchor_points, dim=-1): + """ + Decode predicted object bounding box coordinates from anchor points and distribution. + + Args: + pred_dist (torch.Tensor): Predicted rotated distance, (bs, h*w, 4). + pred_angle (torch.Tensor): Predicted angle, (bs, h*w, 1). + anchor_points (torch.Tensor): Anchor points, (h*w, 2). + Returns: + (torch.Tensor): Predicted rotated bounding boxes, (bs, h*w, 4). + """ + lt, rb = pred_dist.split(2, dim=dim) + cos, sin = torch.cos(pred_angle), torch.sin(pred_angle) + # (bs, h*w, 1) + xf, yf = ((rb - lt) / 2).split(1, dim=dim) + x, y = xf * cos - yf * sin, xf * sin + yf * cos + xy = torch.cat([x, y], dim=dim) + anchor_points + return torch.cat([xy, lt + rb], dim=dim) diff --git a/ultralytics/utils/torch_utils.py b/ultralytics/utils/torch_utils.py new file mode 100644 index 0000000..2b0ad95 --- /dev/null +++ b/ultralytics/utils/torch_utils.py @@ -0,0 +1,631 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import math +import os +import random +import time +from contextlib import contextmanager +from copy import deepcopy +from pathlib import Path +from typing import Union + +import numpy as np +import torch +import torch.distributed as dist +import torch.nn as nn +import torch.nn.functional as F + +from ultralytics.utils import ( + DEFAULT_CFG_DICT, + DEFAULT_CFG_KEYS, + LOGGER, + PYTHON_VERSION, + TORCHVISION_VERSION, + __version__, + colorstr, +) +from ultralytics.utils.checks import check_version + +try: + import thop +except ImportError: + thop = None + +# Version checks (all default to version>=min_version) +TORCH_1_9 = check_version(torch.__version__, "1.9.0") +TORCH_1_13 = check_version(torch.__version__, "1.13.0") +TORCH_2_0 = check_version(torch.__version__, "2.0.0") +TORCHVISION_0_10 = check_version(TORCHVISION_VERSION, "0.10.0") +TORCHVISION_0_11 = check_version(TORCHVISION_VERSION, "0.11.0") +TORCHVISION_0_13 = check_version(TORCHVISION_VERSION, "0.13.0") + + +@contextmanager +def torch_distributed_zero_first(local_rank: int): + """Decorator to make all processes in distributed training wait for each local_master to do something.""" + initialized = torch.distributed.is_available() and torch.distributed.is_initialized() + if initialized and local_rank not in {-1, 0}: + dist.barrier(device_ids=[local_rank]) + yield + if initialized and local_rank == 0: + dist.barrier(device_ids=[0]) + + +def smart_inference_mode(): + """Applies torch.inference_mode() decorator if torch>=1.9.0 else torch.no_grad() decorator.""" + + def decorate(fn): + """Applies appropriate torch decorator for inference mode based on torch version.""" + if TORCH_1_9 and torch.is_inference_mode_enabled(): + return fn # already in inference_mode, act as a pass-through + else: + return (torch.inference_mode if TORCH_1_9 else torch.no_grad)()(fn) + + return decorate + + +def get_cpu_info(): + """Return a string with system CPU information, i.e. 'Apple M2'.""" + import cpuinfo # pip install py-cpuinfo + + k = "brand_raw", "hardware_raw", "arch_string_raw" # info keys sorted by preference (not all keys always available) + info = cpuinfo.get_cpu_info() # info dict + string = info.get(k[0] if k[0] in info else k[1] if k[1] in info else k[2], "unknown") + return string.replace("(R)", "").replace("CPU ", "").replace("@ ", "") + + +def select_device(device="", batch=0, newline=False, verbose=True): + """ + Selects the appropriate PyTorch device based on the provided arguments. + + The function takes a string specifying the device or a torch.device object and returns a torch.device object + representing the selected device. The function also validates the number of available devices and raises an + exception if the requested device(s) are not available. + + Args: + device (str | torch.device, optional): Device string or torch.device object. + Options are 'None', 'cpu', or 'cuda', or '0' or '0,1,2,3'. Defaults to an empty string, which auto-selects + the first available GPU, or CPU if no GPU is available. + batch (int, optional): Batch size being used in your model. Defaults to 0. + newline (bool, optional): If True, adds a newline at the end of the log string. Defaults to False. + verbose (bool, optional): If True, logs the device information. Defaults to True. + + Returns: + (torch.device): Selected device. + + Raises: + ValueError: If the specified device is not available or if the batch size is not a multiple of the number of + devices when using multiple GPUs. + + Examples: + >>> select_device('cuda:0') + device(type='cuda', index=0) + + >>> select_device('cpu') + device(type='cpu') + + Note: + Sets the 'CUDA_VISIBLE_DEVICES' environment variable for specifying which GPUs to use. + """ + + if isinstance(device, torch.device): + return device + + s = f"Ultralytics YOLOv{__version__} 🚀 Python-{PYTHON_VERSION} torch-{torch.__version__} " + device = str(device).lower() + for remove in "cuda:", "none", "(", ")", "[", "]", "'", " ": + device = device.replace(remove, "") # to string, 'cuda:0' -> '0' and '(0, 1)' -> '0,1' + cpu = device == "cpu" + mps = device in {"mps", "mps:0"} # Apple Metal Performance Shaders (MPS) + if cpu or mps: + os.environ["CUDA_VISIBLE_DEVICES"] = "-1" # force torch.cuda.is_available() = False + elif device: # non-cpu device requested + if device == "cuda": + device = "0" + visible = os.environ.get("CUDA_VISIBLE_DEVICES", None) + os.environ["CUDA_VISIBLE_DEVICES"] = device # set environment variable - must be before assert is_available() + if not (torch.cuda.is_available() and torch.cuda.device_count() >= len(device.split(","))): + LOGGER.info(s) + install = ( + "See https://pytorch.org/get-started/locally/ for up-to-date torch install instructions if no " + "CUDA devices are seen by torch.\n" + if torch.cuda.device_count() == 0 + else "" + ) + raise ValueError( + f"Invalid CUDA 'device={device}' requested." + f" Use 'device=cpu' or pass valid CUDA device(s) if available," + f" i.e. 'device=0' or 'device=0,1,2,3' for Multi-GPU.\n" + f"\ntorch.cuda.is_available(): {torch.cuda.is_available()}" + f"\ntorch.cuda.device_count(): {torch.cuda.device_count()}" + f"\nos.environ['CUDA_VISIBLE_DEVICES']: {visible}\n" + f"{install}" + ) + + if not cpu and not mps and torch.cuda.is_available(): # prefer GPU if available + devices = device.split(",") if device else "0" # range(torch.cuda.device_count()) # i.e. 0,1,6,7 + n = len(devices) # device count + if n > 1 and batch > 0 and batch % n != 0: # check batch_size is divisible by device_count + raise ValueError( + f"'batch={batch}' must be a multiple of GPU count {n}. Try 'batch={batch // n * n}' or " + f"'batch={batch // n * n + n}', the nearest batch sizes evenly divisible by {n}." + ) + space = " " * (len(s) + 1) + for i, d in enumerate(devices): + p = torch.cuda.get_device_properties(i) + s += f"{'' if i == 0 else space}CUDA:{d} ({p.name}, {p.total_memory / (1 << 20):.0f}MiB)\n" # bytes to MB + arg = "cuda:0" + elif mps and TORCH_2_0 and torch.backends.mps.is_available(): + # Prefer MPS if available + s += f"MPS ({get_cpu_info()})\n" + arg = "mps" + else: # revert to CPU + s += f"CPU ({get_cpu_info()})\n" + arg = "cpu" + + if verbose: + LOGGER.info(s if newline else s.rstrip()) + return torch.device(arg) + + +def time_sync(): + """PyTorch-accurate time.""" + if torch.cuda.is_available(): + torch.cuda.synchronize() + return time.time() + + +def fuse_conv_and_bn(conv, bn): + """Fuse Conv2d() and BatchNorm2d() layers https://tehnokv.com/posts/fusing-batchnorm-and-conv/.""" + fusedconv = ( + nn.Conv2d( + conv.in_channels, + conv.out_channels, + kernel_size=conv.kernel_size, + stride=conv.stride, + padding=conv.padding, + dilation=conv.dilation, + groups=conv.groups, + bias=True, + ) + .requires_grad_(False) + .to(conv.weight.device) + ) + + # Prepare filters + w_conv = conv.weight.clone().view(conv.out_channels, -1) + w_bn = torch.diag(bn.weight.div(torch.sqrt(bn.eps + bn.running_var))) + fusedconv.weight.copy_(torch.mm(w_bn, w_conv).view(fusedconv.weight.shape)) + + # Prepare spatial bias + b_conv = torch.zeros(conv.weight.shape[0], device=conv.weight.device) if conv.bias is None else conv.bias + b_bn = bn.bias - bn.weight.mul(bn.running_mean).div(torch.sqrt(bn.running_var + bn.eps)) + fusedconv.bias.copy_(torch.mm(w_bn, b_conv.reshape(-1, 1)).reshape(-1) + b_bn) + + return fusedconv + + +def fuse_deconv_and_bn(deconv, bn): + """Fuse ConvTranspose2d() and BatchNorm2d() layers.""" + fuseddconv = ( + nn.ConvTranspose2d( + deconv.in_channels, + deconv.out_channels, + kernel_size=deconv.kernel_size, + stride=deconv.stride, + padding=deconv.padding, + output_padding=deconv.output_padding, + dilation=deconv.dilation, + groups=deconv.groups, + bias=True, + ) + .requires_grad_(False) + .to(deconv.weight.device) + ) + + # Prepare filters + w_deconv = deconv.weight.clone().view(deconv.out_channels, -1) + w_bn = torch.diag(bn.weight.div(torch.sqrt(bn.eps + bn.running_var))) + fuseddconv.weight.copy_(torch.mm(w_bn, w_deconv).view(fuseddconv.weight.shape)) + + # Prepare spatial bias + b_conv = torch.zeros(deconv.weight.shape[1], device=deconv.weight.device) if deconv.bias is None else deconv.bias + b_bn = bn.bias - bn.weight.mul(bn.running_mean).div(torch.sqrt(bn.running_var + bn.eps)) + fuseddconv.bias.copy_(torch.mm(w_bn, b_conv.reshape(-1, 1)).reshape(-1) + b_bn) + + return fuseddconv + + +def model_info(model, detailed=False, verbose=True, imgsz=640): + """ + Model information. + + imgsz may be int or list, i.e. imgsz=640 or imgsz=[640, 320]. + """ + if not verbose: + return + n_p = get_num_params(model) # number of parameters + n_g = get_num_gradients(model) # number of gradients + n_l = len(list(model.modules())) # number of layers + if detailed: + LOGGER.info( + f"{'layer':>5} {'name':>40} {'gradient':>9} {'parameters':>12} {'shape':>20} {'mu':>10} {'sigma':>10}" + ) + for i, (name, p) in enumerate(model.named_parameters()): + name = name.replace("module_list.", "") + LOGGER.info( + "%5g %40s %9s %12g %20s %10.3g %10.3g %10s" + % (i, name, p.requires_grad, p.numel(), list(p.shape), p.mean(), p.std(), p.dtype) + ) + + flops = get_flops(model, imgsz) + fused = " (fused)" if getattr(model, "is_fused", lambda: False)() else "" + fs = f", {flops:.1f} GFLOPs" if flops else "" + yaml_file = getattr(model, "yaml_file", "") or getattr(model, "yaml", {}).get("yaml_file", "") + model_name = Path(yaml_file).stem.replace("yolo", "YOLO") or "Model" + LOGGER.info(f"{model_name} summary{fused}: {n_l} layers, {n_p} parameters, {n_g} gradients{fs}") + return n_l, n_p, n_g, flops + + +def get_num_params(model): + """Return the total number of parameters in a YOLO model.""" + return sum(x.numel() for x in model.parameters()) + + +def get_num_gradients(model): + """Return the total number of parameters with gradients in a YOLO model.""" + return sum(x.numel() for x in model.parameters() if x.requires_grad) + + +def model_info_for_loggers(trainer): + """ + Return model info dict with useful model information. + + Example: + YOLOv8n info for loggers + ```python + results = {'model/parameters': 3151904, + 'model/GFLOPs': 8.746, + 'model/speed_ONNX(ms)': 41.244, + 'model/speed_TensorRT(ms)': 3.211, + 'model/speed_PyTorch(ms)': 18.755} + ``` + """ + if trainer.args.profile: # profile ONNX and TensorRT times + from ultralytics.utils.benchmarks import ProfileModels + + results = ProfileModels([trainer.last], device=trainer.device).profile()[0] + results.pop("model/name") + else: # only return PyTorch times from most recent validation + results = { + "model/parameters": get_num_params(trainer.model), + "model/GFLOPs": round(get_flops(trainer.model), 3), + } + results["model/speed_PyTorch(ms)"] = round(trainer.validator.speed["inference"], 3) + return results + + +def get_flops(model, imgsz=640): + """Return a YOLO model's FLOPs.""" + if not thop: + return 0.0 # if not installed return 0.0 GFLOPs + + try: + model = de_parallel(model) + p = next(model.parameters()) + if not isinstance(imgsz, list): + imgsz = [imgsz, imgsz] # expand if int/float + try: + # Use stride size for input tensor + stride = max(int(model.stride.max()), 32) if hasattr(model, "stride") else 32 # max stride + im = torch.empty((1, p.shape[1], stride, stride), device=p.device) # input image in BCHW format + flops = thop.profile(deepcopy(model), inputs=[im], verbose=False)[0] / 1e9 * 2 # stride GFLOPs + return flops * imgsz[0] / stride * imgsz[1] / stride # imgsz GFLOPs + except Exception: + # Use actual image size for input tensor (i.e. required for RTDETR models) + im = torch.empty((1, p.shape[1], *imgsz), device=p.device) # input image in BCHW format + return thop.profile(deepcopy(model), inputs=[im], verbose=False)[0] / 1e9 * 2 # imgsz GFLOPs + except Exception: + return 0.0 + + +def get_flops_with_torch_profiler(model, imgsz=640): + """Compute model FLOPs (thop alternative).""" + if TORCH_2_0: + model = de_parallel(model) + p = next(model.parameters()) + stride = (max(int(model.stride.max()), 32) if hasattr(model, "stride") else 32) * 2 # max stride + im = torch.zeros((1, p.shape[1], stride, stride), device=p.device) # input image in BCHW format + with torch.profiler.profile(with_flops=True) as prof: + model(im) + flops = sum(x.flops for x in prof.key_averages()) / 1e9 + imgsz = imgsz if isinstance(imgsz, list) else [imgsz, imgsz] # expand if int/float + flops = flops * imgsz[0] / stride * imgsz[1] / stride # 640x640 GFLOPs + return flops + return 0 + + +def initialize_weights(model): + """Initialize model weights to random values.""" + for m in model.modules(): + t = type(m) + if t is nn.Conv2d: + pass # nn.init.kaiming_normal_(m.weight, mode='fan_out', nonlinearity='relu') + elif t is nn.BatchNorm2d: + m.eps = 1e-3 + m.momentum = 0.03 + elif t in {nn.Hardswish, nn.LeakyReLU, nn.ReLU, nn.ReLU6, nn.SiLU}: + m.inplace = True + + +def scale_img(img, ratio=1.0, same_shape=False, gs=32): + """Scales and pads an image tensor of shape img(bs,3,y,x) based on given ratio and grid size gs, optionally + retaining the original shape. + """ + if ratio == 1.0: + return img + h, w = img.shape[2:] + s = (int(h * ratio), int(w * ratio)) # new size + img = F.interpolate(img, size=s, mode="bilinear", align_corners=False) # resize + if not same_shape: # pad/crop img + h, w = (math.ceil(x * ratio / gs) * gs for x in (h, w)) + return F.pad(img, [0, w - s[1], 0, h - s[0]], value=0.447) # value = imagenet mean + + +def make_divisible(x, divisor): + """Returns nearest x divisible by divisor.""" + if isinstance(divisor, torch.Tensor): + divisor = int(divisor.max()) # to int + return math.ceil(x / divisor) * divisor + + +def copy_attr(a, b, include=(), exclude=()): + """Copies attributes from object 'b' to object 'a', with options to include/exclude certain attributes.""" + for k, v in b.__dict__.items(): + if (len(include) and k not in include) or k.startswith("_") or k in exclude: + continue + else: + setattr(a, k, v) + + +def get_latest_opset(): + """Return second-most (for maturity) recently supported ONNX opset by this version of torch.""" + return max(int(k[14:]) for k in vars(torch.onnx) if "symbolic_opset" in k) - 1 # opset + + +def intersect_dicts(da, db, exclude=()): + """Returns a dictionary of intersecting keys with matching shapes, excluding 'exclude' keys, using da values.""" + return {k: v for k, v in da.items() if k in db and all(x not in k for x in exclude) and v.shape == db[k].shape} + + +def is_parallel(model): + """Returns True if model is of type DP or DDP.""" + return isinstance(model, (nn.parallel.DataParallel, nn.parallel.DistributedDataParallel)) + + +def de_parallel(model): + """De-parallelize a model: returns single-GPU model if model is of type DP or DDP.""" + return model.module if is_parallel(model) else model + + +def one_cycle(y1=0.0, y2=1.0, steps=100): + """Returns a lambda function for sinusoidal ramp from y1 to y2 https://arxiv.org/pdf/1812.01187.pdf.""" + return lambda x: max((1 - math.cos(x * math.pi / steps)) / 2, 0) * (y2 - y1) + y1 + + +def init_seeds(seed=0, deterministic=False): + """Initialize random number generator (RNG) seeds https://pytorch.org/docs/stable/notes/randomness.html.""" + random.seed(seed) + np.random.seed(seed) + torch.manual_seed(seed) + torch.cuda.manual_seed(seed) + torch.cuda.manual_seed_all(seed) # for Multi-GPU, exception safe + # torch.backends.cudnn.benchmark = True # AutoBatch problem https://github.com/ultralytics/yolov5/issues/9287 + if deterministic: + if TORCH_2_0: + torch.use_deterministic_algorithms(True, warn_only=True) # warn if deterministic is not possible + torch.backends.cudnn.deterministic = True + os.environ["CUBLAS_WORKSPACE_CONFIG"] = ":4096:8" + os.environ["PYTHONHASHSEED"] = str(seed) + else: + LOGGER.warning("WARNING ⚠️ Upgrade to torch>=2.0.0 for deterministic training.") + else: + torch.use_deterministic_algorithms(False) + torch.backends.cudnn.deterministic = False + + +class ModelEMA: + """Updated Exponential Moving Average (EMA) from https://github.com/rwightman/pytorch-image-models + Keeps a moving average of everything in the model state_dict (parameters and buffers) + For EMA details see https://www.tensorflow.org/api_docs/python/tf/train/ExponentialMovingAverage + To disable EMA set the `enabled` attribute to `False`. + """ + + def __init__(self, model, decay=0.9999, tau=2000, updates=0): + """Create EMA.""" + self.ema = deepcopy(de_parallel(model)).eval() # FP32 EMA + self.updates = updates # number of EMA updates + self.decay = lambda x: decay * (1 - math.exp(-x / tau)) # decay exponential ramp (to help early epochs) + for p in self.ema.parameters(): + p.requires_grad_(False) + self.enabled = True + + def update(self, model): + """Update EMA parameters.""" + if self.enabled: + self.updates += 1 + d = self.decay(self.updates) + + msd = de_parallel(model).state_dict() # model state_dict + for k, v in self.ema.state_dict().items(): + if v.dtype.is_floating_point: # true for FP16 and FP32 + v *= d + v += (1 - d) * msd[k].detach() + # assert v.dtype == msd[k].dtype == torch.float32, f'{k}: EMA {v.dtype}, model {msd[k].dtype}' + + def update_attr(self, model, include=(), exclude=("process_group", "reducer")): + """Updates attributes and saves stripped model with optimizer removed.""" + if self.enabled: + copy_attr(self.ema, model, include, exclude) + + +def strip_optimizer(f: Union[str, Path] = "best.pt", s: str = "") -> None: + """ + Strip optimizer from 'f' to finalize training, optionally save as 's'. + + Args: + f (str): file path to model to strip the optimizer from. Default is 'best.pt'. + s (str): file path to save the model with stripped optimizer to. If not provided, 'f' will be overwritten. + + Returns: + None + + Example: + ```python + from pathlib import Path + from ultralytics.utils.torch_utils import strip_optimizer + + for f in Path('path/to/weights').rglob('*.pt'): + strip_optimizer(f) + ``` + """ + x = torch.load(f, map_location=torch.device("cpu")) + if "model" not in x: + LOGGER.info(f"Skipping {f}, not a valid Ultralytics model.") + return + + if hasattr(x["model"], "args"): + x["model"].args = dict(x["model"].args) # convert from IterableSimpleNamespace to dict + args = {**DEFAULT_CFG_DICT, **x["train_args"]} if "train_args" in x else None # combine args + if x.get("ema"): + x["model"] = x["ema"] # replace model with ema + for k in "optimizer", "best_fitness", "ema", "updates": # keys + x[k] = None + x["epoch"] = -1 + x["model"].half() # to FP16 + for p in x["model"].parameters(): + p.requires_grad = False + x["train_args"] = {k: v for k, v in args.items() if k in DEFAULT_CFG_KEYS} # strip non-default keys + # x['model'].args = x['train_args'] + torch.save(x, s or f) + mb = os.path.getsize(s or f) / 1e6 # file size + LOGGER.info(f"Optimizer stripped from {f},{f' saved as {s},' if s else ''} {mb:.1f}MB") + + +def convert_optimizer_state_dict_to_fp16(state_dict): + """ + Converts the state_dict of a given optimizer to FP16, focusing on the 'state' key for tensor conversions. + + This method aims to reduce storage size without altering 'param_groups' as they contain non-tensor data. + """ + for state in state_dict["state"].values(): + for k, v in state.items(): + if k != "step" and isinstance(v, torch.Tensor) and v.dtype is torch.float32: + state[k] = v.half() + + return state_dict + + +def profile(input, ops, n=10, device=None): + """ + Ultralytics speed, memory and FLOPs profiler. + + Example: + ```python + from ultralytics.utils.torch_utils import profile + + input = torch.randn(16, 3, 640, 640) + m1 = lambda x: x * torch.sigmoid(x) + m2 = nn.SiLU() + profile(input, [m1, m2], n=100) # profile over 100 iterations + ``` + """ + results = [] + if not isinstance(device, torch.device): + device = select_device(device) + LOGGER.info( + f"{'Params':>12s}{'GFLOPs':>12s}{'GPU_mem (GB)':>14s}{'forward (ms)':>14s}{'backward (ms)':>14s}" + f"{'input':>24s}{'output':>24s}" + ) + + for x in input if isinstance(input, list) else [input]: + x = x.to(device) + x.requires_grad = True + for m in ops if isinstance(ops, list) else [ops]: + m = m.to(device) if hasattr(m, "to") else m # device + m = m.half() if hasattr(m, "half") and isinstance(x, torch.Tensor) and x.dtype is torch.float16 else m + tf, tb, t = 0, 0, [0, 0, 0] # dt forward, backward + try: + flops = thop.profile(m, inputs=[x], verbose=False)[0] / 1e9 * 2 if thop else 0 # GFLOPs + except Exception: + flops = 0 + + try: + for _ in range(n): + t[0] = time_sync() + y = m(x) + t[1] = time_sync() + try: + (sum(yi.sum() for yi in y) if isinstance(y, list) else y).sum().backward() + t[2] = time_sync() + except Exception: # no backward method + # print(e) # for debug + t[2] = float("nan") + tf += (t[1] - t[0]) * 1000 / n # ms per op forward + tb += (t[2] - t[1]) * 1000 / n # ms per op backward + mem = torch.cuda.memory_reserved() / 1e9 if torch.cuda.is_available() else 0 # (GB) + s_in, s_out = (tuple(x.shape) if isinstance(x, torch.Tensor) else "list" for x in (x, y)) # shapes + p = sum(x.numel() for x in m.parameters()) if isinstance(m, nn.Module) else 0 # parameters + LOGGER.info(f"{p:12}{flops:12.4g}{mem:>14.3f}{tf:14.4g}{tb:14.4g}{str(s_in):>24s}{str(s_out):>24s}") + results.append([p, flops, mem, tf, tb, s_in, s_out]) + except Exception as e: + LOGGER.info(e) + results.append(None) + torch.cuda.empty_cache() + return results + + +class EarlyStopping: + """Early stopping class that stops training when a specified number of epochs have passed without improvement.""" + + def __init__(self, patience=50): + """ + Initialize early stopping object. + + Args: + patience (int, optional): Number of epochs to wait after fitness stops improving before stopping. + """ + self.best_fitness = 0.0 # i.e. mAP + self.best_epoch = 0 + self.patience = patience or float("inf") # epochs to wait after fitness stops improving to stop + self.possible_stop = False # possible stop may occur next epoch + + def __call__(self, epoch, fitness): + """ + Check whether to stop training. + + Args: + epoch (int): Current epoch of training + fitness (float): Fitness value of current epoch + + Returns: + (bool): True if training should stop, False otherwise + """ + if fitness is None: # check if fitness=None (happens when val=False) + return False + + if fitness >= self.best_fitness: # >= 0 to allow for early zero-fitness stage of training + self.best_epoch = epoch + self.best_fitness = fitness + delta = epoch - self.best_epoch # epochs without improvement + self.possible_stop = delta >= (self.patience - 1) # possible stop may occur next epoch + stop = delta >= self.patience # stop training if patience exceeded + if stop: + prefix = colorstr("EarlyStopping: ") + LOGGER.info( + f"{prefix}Training stopped early as no improvement observed in last {self.patience} epochs. " + f"Best results observed at epoch {self.best_epoch}, best model saved as best.pt.\n" + f"To update EarlyStopping(patience={self.patience}) pass a new patience value, " + f"i.e. `patience=300` or use `patience=0` to disable EarlyStopping." + ) + return stop diff --git a/ultralytics/utils/triton.py b/ultralytics/utils/triton.py new file mode 100644 index 0000000..3f873a6 --- /dev/null +++ b/ultralytics/utils/triton.py @@ -0,0 +1,92 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +from typing import List +from urllib.parse import urlsplit + +import numpy as np + + +class TritonRemoteModel: + """ + Client for interacting with a remote Triton Inference Server model. + + Attributes: + endpoint (str): The name of the model on the Triton server. + url (str): The URL of the Triton server. + triton_client: The Triton client (either HTTP or gRPC). + InferInput: The input class for the Triton client. + InferRequestedOutput: The output request class for the Triton client. + input_formats (List[str]): The data types of the model inputs. + np_input_formats (List[type]): The numpy data types of the model inputs. + input_names (List[str]): The names of the model inputs. + output_names (List[str]): The names of the model outputs. + """ + + def __init__(self, url: str, endpoint: str = "", scheme: str = ""): + """ + Initialize the TritonRemoteModel. + + Arguments may be provided individually or parsed from a collective 'url' argument of the form + ://// + + Args: + url (str): The URL of the Triton server. + endpoint (str): The name of the model on the Triton server. + scheme (str): The communication scheme ('http' or 'grpc'). + """ + if not endpoint and not scheme: # Parse all args from URL string + splits = urlsplit(url) + endpoint = splits.path.strip("/").split("/")[0] + scheme = splits.scheme + url = splits.netloc + + self.endpoint = endpoint + self.url = url + + # Choose the Triton client based on the communication scheme + if scheme == "http": + import tritonclient.http as client # noqa + + self.triton_client = client.InferenceServerClient(url=self.url, verbose=False, ssl=False) + config = self.triton_client.get_model_config(endpoint) + else: + import tritonclient.grpc as client # noqa + + self.triton_client = client.InferenceServerClient(url=self.url, verbose=False, ssl=False) + config = self.triton_client.get_model_config(endpoint, as_json=True)["config"] + + # Sort output names alphabetically, i.e. 'output0', 'output1', etc. + config["output"] = sorted(config["output"], key=lambda x: x.get("name")) + + # Define model attributes + type_map = {"TYPE_FP32": np.float32, "TYPE_FP16": np.float16, "TYPE_UINT8": np.uint8} + self.InferRequestedOutput = client.InferRequestedOutput + self.InferInput = client.InferInput + self.input_formats = [x["data_type"] for x in config["input"]] + self.np_input_formats = [type_map[x] for x in self.input_formats] + self.input_names = [x["name"] for x in config["input"]] + self.output_names = [x["name"] for x in config["output"]] + + def __call__(self, *inputs: np.ndarray) -> List[np.ndarray]: + """ + Call the model with the given inputs. + + Args: + *inputs (List[np.ndarray]): Input data to the model. + + Returns: + (List[np.ndarray]): Model outputs. + """ + infer_inputs = [] + input_format = inputs[0].dtype + for i, x in enumerate(inputs): + if x.dtype != self.np_input_formats[i]: + x = x.astype(self.np_input_formats[i]) + infer_input = self.InferInput(self.input_names[i], [*x.shape], self.input_formats[i].replace("TYPE_", "")) + infer_input.set_data_from_numpy(x) + infer_inputs.append(infer_input) + + infer_outputs = [self.InferRequestedOutput(output_name) for output_name in self.output_names] + outputs = self.triton_client.infer(model_name=self.endpoint, inputs=infer_inputs, outputs=infer_outputs) + + return [outputs.as_numpy(output_name).astype(input_format) for output_name in self.output_names] diff --git a/ultralytics/utils/tuner.py b/ultralytics/utils/tuner.py new file mode 100644 index 0000000..91d3aa6 --- /dev/null +++ b/ultralytics/utils/tuner.py @@ -0,0 +1,148 @@ +# Ultralytics YOLO 🚀, AGPL-3.0 license + +import subprocess + +from ultralytics.cfg import TASK2DATA, TASK2METRIC, get_save_dir +from ultralytics.utils import DEFAULT_CFG, DEFAULT_CFG_DICT, LOGGER, NUM_THREADS, checks + + +def run_ray_tune( + model, space: dict = None, grace_period: int = 10, gpu_per_trial: int = None, max_samples: int = 10, **train_args +): + """ + Runs hyperparameter tuning using Ray Tune. + + Args: + model (YOLO): Model to run the tuner on. + space (dict, optional): The hyperparameter search space. Defaults to None. + grace_period (int, optional): The grace period in epochs of the ASHA scheduler. Defaults to 10. + gpu_per_trial (int, optional): The number of GPUs to allocate per trial. Defaults to None. + max_samples (int, optional): The maximum number of trials to run. Defaults to 10. + train_args (dict, optional): Additional arguments to pass to the `train()` method. Defaults to {}. + + Returns: + (dict): A dictionary containing the results of the hyperparameter search. + + Example: + ```python + from ultralytics import YOLO + + # Load a YOLOv8n model + model = YOLO('yolov8n.pt') + + # Start tuning hyperparameters for YOLOv8n training on the COCO8 dataset + result_grid = model.tune(data='coco8.yaml', use_ray=True) + ``` + """ + + LOGGER.info("💡 Learn about RayTune at https://docs.ultralytics.com/integrations/ray-tune") + if train_args is None: + train_args = {} + + try: + subprocess.run("pip install ray[tune]".split(), check=True) # do not add single quotes here + + import ray + from ray import tune + from ray.air import RunConfig + from ray.air.integrations.wandb import WandbLoggerCallback + from ray.tune.schedulers import ASHAScheduler + except ImportError: + raise ModuleNotFoundError('Ray Tune required but not found. To install run: pip install "ray[tune]"') + + try: + import wandb + + assert hasattr(wandb, "__version__") + except (ImportError, AssertionError): + wandb = False + + checks.check_version(ray.__version__, "<=2.9.3", "ray") + default_space = { + # 'optimizer': tune.choice(['SGD', 'Adam', 'AdamW', 'NAdam', 'RAdam', 'RMSProp']), + "lr0": tune.uniform(1e-5, 1e-1), + "lrf": tune.uniform(0.01, 1.0), # final OneCycleLR learning rate (lr0 * lrf) + "momentum": tune.uniform(0.6, 0.98), # SGD momentum/Adam beta1 + "weight_decay": tune.uniform(0.0, 0.001), # optimizer weight decay 5e-4 + "warmup_epochs": tune.uniform(0.0, 5.0), # warmup epochs (fractions ok) + "warmup_momentum": tune.uniform(0.0, 0.95), # warmup initial momentum + "box": tune.uniform(0.02, 0.2), # box loss gain + "cls": tune.uniform(0.2, 4.0), # cls loss gain (scale with pixels) + "hsv_h": tune.uniform(0.0, 0.1), # image HSV-Hue augmentation (fraction) + "hsv_s": tune.uniform(0.0, 0.9), # image HSV-Saturation augmentation (fraction) + "hsv_v": tune.uniform(0.0, 0.9), # image HSV-Value augmentation (fraction) + "degrees": tune.uniform(0.0, 45.0), # image rotation (+/- deg) + "translate": tune.uniform(0.0, 0.9), # image translation (+/- fraction) + "scale": tune.uniform(0.0, 0.9), # image scale (+/- gain) + "shear": tune.uniform(0.0, 10.0), # image shear (+/- deg) + "perspective": tune.uniform(0.0, 0.001), # image perspective (+/- fraction), range 0-0.001 + "flipud": tune.uniform(0.0, 1.0), # image flip up-down (probability) + "fliplr": tune.uniform(0.0, 1.0), # image flip left-right (probability) + "bgr": tune.uniform(0.0, 1.0), # image channel BGR (probability) + "mosaic": tune.uniform(0.0, 1.0), # image mixup (probability) + "mixup": tune.uniform(0.0, 1.0), # image mixup (probability) + "copy_paste": tune.uniform(0.0, 1.0), # segment copy-paste (probability) + } + + # Put the model in ray store + task = model.task + model_in_store = ray.put(model) + + def _tune(config): + """ + Trains the YOLO model with the specified hyperparameters and additional arguments. + + Args: + config (dict): A dictionary of hyperparameters to use for training. + + Returns: + None + """ + model_to_train = ray.get(model_in_store) # get the model from ray store for tuning + model_to_train.reset_callbacks() + config.update(train_args) + results = model_to_train.train(**config) + return results.results_dict + + # Get search space + if not space: + space = default_space + LOGGER.warning("WARNING ⚠️ search space not provided, using default search space.") + + # Get dataset + data = train_args.get("data", TASK2DATA[task]) + space["data"] = data + if "data" not in train_args: + LOGGER.warning(f'WARNING ⚠️ data not provided, using default "data={data}".') + + # Define the trainable function with allocated resources + trainable_with_resources = tune.with_resources(_tune, {"cpu": NUM_THREADS, "gpu": gpu_per_trial or 0}) + + # Define the ASHA scheduler for hyperparameter search + asha_scheduler = ASHAScheduler( + time_attr="epoch", + metric=TASK2METRIC[task], + mode="max", + max_t=train_args.get("epochs") or DEFAULT_CFG_DICT["epochs"] or 100, + grace_period=grace_period, + reduction_factor=3, + ) + + # Define the callbacks for the hyperparameter search + tuner_callbacks = [WandbLoggerCallback(project="YOLOv8-tune")] if wandb else [] + + # Create the Ray Tune hyperparameter search tuner + tune_dir = get_save_dir(DEFAULT_CFG, name="tune").resolve() # must be absolute dir + tune_dir.mkdir(parents=True, exist_ok=True) + tuner = tune.Tuner( + trainable_with_resources, + param_space=space, + tune_config=tune.TuneConfig(scheduler=asha_scheduler, num_samples=max_samples), + run_config=RunConfig(callbacks=tuner_callbacks, storage_path=tune_dir), + ) + + # Run the hyperparameter search + tuner.fit() + + # Return the results of the hyperparameter search + return tuner.get_results()