Update to Ultralytics YOLO

{
  "description": "Use when testing, running, or deploying Ultralytics YOLO inference in Platform or code on images, video, webcams, or streams — Platform Predict and dedicated endpoints, model.predict()/yolo predict, Results API boxes/masks/keypoints, persistent tracking, annotated video, and Solutions such as counting, heatmaps, speed, queues, and parking. For optimized runtime exports, see yolo-export.\n",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 267
    },
    {
      "relative_path": "solutions.md",
      "size_in_bytes": 6098
    }
  ],
  "name": "yolo-inference",
  "skill_md_contents": "---\nname: yolo-inference\ndescription: >\n  Use when testing, running, or deploying Ultralytics YOLO inference in Platform or code on images, video, webcams, or streams — Platform Predict and dedicated endpoints, model.predict()/yolo predict, Results API boxes/masks/keypoints, persistent tracking, annotated video, and Solutions such as counting, heatmaps, speed, queues, and parking. For optimized runtime exports, see yolo-export.\n---\n\n# Inference, Results API & tracking\n\n## Fastest route: test and deploy in Platform\n\nEvery Platform model has a **Predict** tab: upload an image, choose an example, or capture a webcam frame; inference runs automatically and shows the task overlay, summary, raw JSON, and timing. Adjust `conf`, `iou`, and `imgsz` with the same meanings used below.\n\nFor production, open **Deploy**, choose a nearby region, and wait for the dedicated endpoint to become **Ready**. Its deployment page provides health, metrics, logs, a Predict panel, and ready-to-use Python/JavaScript/cURL examples. Call `/predict` with the deployment's bound API key as a bearer token:\n\n```python\nimport requests\n\nwith open(\"image.jpg\", \"rb\") as image_file:\n    response = requests.post(\n        \"https://YOUR_DEPLOYMENT_URL.run.app/predict\",\n        headers={\"Authorization\": \"Bearer YOUR_API_KEY\"},\n        files={\"file\": image_file},\n        data={\"conf\": 0.25, \"iou\": 0.5, \"imgsz\": 640},\n    )\nresponse.raise_for_status()\nprint(response.json())\n```\n\nDefault-size endpoints scale to zero, so expect a cold start after idle periods; custom sizes keep a warm instance billed for uptime. See [Platform Inference](https://docs.ultralytics.com/platform/deploy/inference) and [Dedicated Endpoints](https://docs.ultralytics.com/platform/deploy/endpoints).\n\n## Quickstart\n\n```python\nfrom ultralytics import YOLO\n\nmodel = YOLO(\"yolo26n.pt\")  # or your runs/detect/train/weights/best.pt\nresults = model(\"https://ultralytics.com/images/bus.jpg\")  # list[Results], one per image\nresults[0].show()\n```\n\n```bash\nyolo predict model=yolo26n.pt # source= omitted → the bundled bus.jpg and zidane.jpg, saved to runs/detect/predict\n```\n\n**The one rule for video/streams: `stream=True`.** The default builds a list of ALL results in RAM — OOM on long videos. `stream=True` returns a generator:\n\n```python\nfor r in model(\"video.mp4\", stream=True):\n    ...\n```\n\n## Sources\n\nAccepted directly: image/video path, directory, glob, URL, webcam index (`0`), RTSP/RTMP/HTTP streams, YouTube URL (needs `pytubefix`), PIL image, numpy array (assumed BGR), torch tensor, or a list of these. `vid_stride=N` processes every Nth frame.\n\n## Arguments that matter\n\n| Arg            | Default | Notes                                                                                                                        |\n| -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |\n| `conf`         | 0.25    | lower → more recall + more false positives                                                                                   |\n| `iou`          | 0.5     | NMS threshold; ignored by the NMS-free head (`nms=False`)                                                                    |\n| `nms`          | None    | default: one-to-many head + NMS; `False`: faster NMS-free YOLO26 head; `True`: embed NMS on export. Exports keep that choice |\n| `imgsz`        | model   | inherited from the checkpoint; set explicitly for a different shape (static exports always run at their export size)         |\n| `classes`      | None    | keep only these ids, e.g. `classes=[0]`                                                                                      |\n| `max_det`      | 300     | raise for dense scenes                                                                                                       |\n| `quantize`     | None    | `16` selects FP16 compute for PyTorch/TorchScript off CPU; artifact/runtime precision otherwise applies; see caveat below    |\n| `batch`        | 1       | >1 speeds up folders/videos with `stream=True`                                                                               |\n| `retina_masks` | False   | full-resolution masks (slower, crisper)                                                                                      |\n| `augment`      | False   | detect-only test-time augmentation (+accuracy, ~3× slower); `nms=False` and exports warn and run normal inference            |\n| `verbose`      | True    | False in loops to silence per-frame logs                                                                                     |\n\n`quantize=16` also rounds OpenVINO inputs to FP16. It replaces the deprecated `half` argument.\n\nSaving/drawing: `save`, `save_txt`, `save_conf`, `save_crop`, `show`, `line_width` → `runs/<task>/predict*/`.\n\n## Results API\n\nEach `Results` has the task's payload — `.boxes`, `.masks`, `.keypoints`, `.probs` (classify), `.obb`, `.semantic_mask`, `.depth` — plus `.names` (id→name), `.orig_img` (BGR), `.speed`, and methods `.plot()`, `.show()`, `.save()`, `.save_txt()`, `.save_crop()`, and `.summary()`. The only exporters are `to_df()`, `to_csv()`, and `to_json()`.\n\n```python\nr = results[0]\nr.boxes.xyxy / .xywh / .xyxyn / .xywhn   # (N,4) boxes, pixel / normalized\nr.boxes.conf, r.boxes.cls, r.boxes.id    # confidence, class ids, track ids (track mode)\nr.masks.xy                                # list of (K,2) pixel polygons per instance\nr.keypoints.xy, r.keypoints.conf          # (N,K,2), (N,K)\nr.probs.top1, r.probs.top1conf            # classify; r.names[r.probs.top1] → label\nr.obb.xyxyxyxy, r.obb.xywhr               # oriented boxes\n\nfrom collections import Counter\ncounts = Counter(r.names[int(c)] for c in r.boxes.cls)   # count per class\n```\n\n`model.embed(\"https://ultralytics.com/images/bus.jpg\")` returns feature vectors (similarity search, clustering).\n\n## Tracking (persistent IDs across frames)\n\n```python\nfor r in model.track(\"video.mp4\", stream=True):\n    ids = r.boxes.id  # tensor of track ids, or None\n\n# Frame-by-frame loop with your own capture: persist=True is REQUIRED\nr = model.track(frame, persist=True)[0]  # else the tracker resets every frame\n```\n\n- Six trackers, selected with `tracker=`: **`tracktrack.yaml` (default)**, `botsort.yaml`, `bytetrack.yaml`, `ocsort.yaml`, `deepocsort.yaml`, `fasttrack.yaml`. ByteTrack is lightest; BoT-SORT/TrackTrack/DeepOCSORT support ReID (`with_reid: True`) and camera-motion compensation (`gmc_method`).\n- Custom behavior: copy the YAML from `ultralytics/cfg/trackers/`, tweak (`track_buffer` = frames a lost track survives, `track_high_thresh`), pass your path.\n- Tracking accepts all predict args but defaults to `conf=0.1` so trackers see low-confidence boxes. Always guard `r.boxes.id is not None`.\n\n## Annotated-video writing pattern\n\n```python\nimport cv2\n\ncap = cv2.VideoCapture(\"in.mp4\")\nw, h, fps = (int(cap.get(p)) for p in (cv2.CAP_PROP_FRAME_WIDTH, cv2.CAP_PROP_FRAME_HEIGHT, cv2.CAP_PROP_FPS))\nout = cv2.VideoWriter(\"out.mp4\", cv2.VideoWriter_fourcc(*\"mp4v\"), fps, (w, h))\nfor r in model.track(\"in.mp4\", stream=True):\n    out.write(r.plot())  # .plot() returns annotated BGR frame\ncap.release()\nout.release()\n```\n\n## Performance checklist\n\n1. For PyTorch/TorchScript on a supported GPU, benchmark `quantize=16` against FP32.\n2. Export to the target-native backend (TensorRT/OpenVINO/CoreML) and benchmark it (see yolo-export; exports load straight back into `YOLO()`).\n3. Use a smaller model or `imgsz`, or the NMS-free YOLO26 head (`nms=False`).\n4. Set `batch>1` for offline folders; use `vid_stride` when every frame isn't needed.\n5. Set `verbose=False`; skip `.plot()` when only coordinates are needed.\n6. Use one `YOLO()` instance per thread — never share across threads.\n\n## Troubleshooting\n\n| Symptom                            | Cause / fix                                                                                                                                   |\n| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |\n| No detections on visible objects   | `conf` too high; wrong weights; `imgsz` far from training size                                                                                |\n| Boxes offset                       | you pre-resized manually — pass the raw image, preprocessing is internal                                                                      |\n| Red/blue swapped in PIL/matplotlib | Results arrays (`orig_img`, `.plot()`) are BGR; convert with `cv2.cvtColor(..., cv2.COLOR_BGR2RGB)`                                           |\n| RAM climbs on video                | missing `stream=True`                                                                                                                         |\n| `boxes.id is None` crash           | guard for None; `persist=True` in manual loops                                                                                                |\n| Duplicate boxes                    | lower `iou`; drop `nms=False` (its NMS-free head ignores `iou`; re-export such artifacts); add `agnostic_nms=True` for cross-class duplicates |\n| Caps at 300 objects                | raise `max_det`                                                                                                                               |\n| Slow first inference               | warmup — benchmark from the second call                                                                                                       |\n\n## Related pages\n\n- `solutions.md` (this folder) — read BEFORE hand-rolling counting, heatmaps, speed estimation, zone logic, queues, parking, workout counting, or privacy blurring: a prebuilt Solution almost certainly exists.\n\nIf the installed version rejects an argument, trust the error text and `yolo cfg` over this file.\n"
}