ultralytics 8.3.183 New NDJSON dataset format support (#21747)

Signed-off-by: Glenn Jocher <glenn.jocher@ultralytics.com>
Co-authored-by: UltralyticsAssistant <web@ultralytics.com>
This commit is contained in:
Glenn Jocher 2025-08-21 13:50:33 +02:00 committed by GitHub
parent 02558d1a77
commit 554af34ece
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
9 changed files with 245 additions and 17 deletions

View File

@ -14,9 +14,11 @@ Training a robust and accurate [object detection](https://www.ultralytics.com/gl
The Ultralytics YOLO format is a dataset configuration format that allows you to define the dataset root directory, the relative paths to training/validation/testing image directories or `*.txt` files containing image paths, and a dictionary of class names. Here is an example:
```yaml
--8<-- "ultralytics/cfg/datasets/coco8.yaml"
```
!!! example "ultralytics/cfg/datasets/coco8.yaml"
```yaml
--8<-- "ultralytics/cfg/datasets/coco8.yaml"
```
Labels for this format should be exported to YOLO format with one `*.txt` file per image. If there are no objects in an image, no `*.txt` file is required. The `*.txt` file should be formatted with one row per object in `class x_center y_center width height` format. Box coordinates must be in **normalized xywh** format (from 0 to 1). If your boxes are in pixels, you should divide `x_center` and `width` by image width, and `y_center` and `height` by image height. Class numbers should be zero-indexed (start with 0).
@ -30,9 +32,9 @@ When using the Ultralytics YOLO format, organize your training and validation im
<p align="center"><img width="800" src="https://github.com/ultralytics/docs/releases/download/0/two-persons-tie-2.avif" alt="Example dataset directory structure"></p>
## Usage
#### Usage Example
Here's how you can use these formats to train your model:
Here's how you can use YOLO format datasets to train your model:
!!! example
@ -55,6 +57,94 @@ Here's how you can use these formats to train your model:
yolo detect train data=coco8.yaml model=yolo11n.pt epochs=100 imgsz=640
```
### Ultralytics NDJSON format
The NDJSON (Newline Delimited JSON) format provides an alternative way to define datasets for Ultralytics YOLO11 models. This format stores dataset metadata and annotations in a single file where each line contains a separate JSON object.
An NDJSON dataset file contains:
1. **Dataset record** (first line): Contains dataset metadata including task type, class names, and general information
2. **Image records** (subsequent lines): Contains individual image data including dimensions, annotations, and file paths
!!! example "NDJSON Example"
=== "Dataset record (line 1)"
```json
{
"type": "dataset",
"task": "detect",
"name": "Example",
"description": "COCO NDJSON example dataset",
"url": "https://app.ultralytics.com/user/datasets/example",
"class_names": { "0": "person", "1": "bicycle", "2": "car" },
"bytes": 426342,
"version": 0,
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2025-01-01T00:00:00Z"
}
```
=== "Image record (lines 2+)"
```json
{
"type": "image",
"file": "image1.jpg",
"url": "https://www.url.com/path/to/image1.jpg",
"width": 640,
"height": 480,
"split": "train",
"annotations": {
"boxes": [
[0, 0.52481, 0.37629, 0.28394, 0.41832],
[1, 0.73526, 0.29847, 0.19275, 0.33691]
]
}
}
```
**Annotation formats by task:**
- **Detection:** `"annotations": {"boxes": [[class_id, x_center, y_center, width, height], ...]}`
- **Segmentation:** `"annotations": {"segments": [[class_id, x1, y1, x2, y2, ...], ...]}`
- **Pose:** `"annotations": {"pose": [[class_id, x1, y1, v1, x2, y2, v2, ...], ...]}`
- **OBB:** `"annotations": {"obb": [[class_id, x_center, y_center, width, height, angle], ...]}`
- **Classification:** `"annotations": {"classification": [class_id]}`
#### Usage Example
To use an NDJSON dataset with YOLO11, simply specify the path to the `.ndjson` file:
!!! example
=== "Python"
```python
from ultralytics import YOLO
# Load a model
model = YOLO("yolo11n.pt")
# Train using NDJSON dataset
results = model.train(data="path/to/dataset.ndjson", epochs=100, imgsz=640)
```
=== "CLI"
```bash
# Start training with NDJSON dataset
yolo detect train data=path/to/dataset.ndjson model=yolo11n.pt epochs=100 imgsz=640
```
#### Advantages of NDJSON format
- **Single file**: All dataset information contained in one file
- **Streaming**: Can process large datasets line-by-line without loading everything into memory
- **Cloud integration**: Supports remote image URLs for cloud-based training
- **Extensible**: Easy to add custom metadata fields
- **Version control**: Single file format works well with git and version control systems
## Supported Datasets
Here is a list of the supported datasets and a brief description for each:
@ -163,7 +253,7 @@ To start training a YOLO11 model, ensure your dataset is formatted correctly and
yolo detect train data=path/to/your_dataset.yaml model=yolo11n.pt epochs=100 imgsz=640
```
Refer to the [Usage](#usage) section for more details on utilizing different modes, including CLI commands.
Refer to the [Usage](#usage-example) section for more details on utilizing different modes, including CLI commands.
### Where can I find practical examples of using Ultralytics YOLO for object detection?

View File

@ -32,9 +32,11 @@ An example of a `*.txt` label file for the above image, which contains an object
The Ultralytics framework uses a YAML file format to define the dataset and model configuration for training OBB Models. Here is an example of the YAML format used for defining a OBB dataset:
```yaml
--8<-- "ultralytics/cfg/datasets/dota8.yaml"
```
!!! example "ultralytics/cfg/datasets/dota8.yaml"
```yaml
--8<-- "ultralytics/cfg/datasets/dota8.yaml"
```
## Usage

View File

@ -40,9 +40,11 @@ In this format, `<class-index>` is the index of the class for the object,`<x> <y
The Ultralytics framework uses a YAML file format to define the dataset and model configuration for training pose estimation models. Here is an example of the YAML format used for defining a pose dataset:
```yaml
--8<-- "ultralytics/cfg/datasets/coco8-pose.yaml"
```
!!! example "ultralytics/cfg/datasets/coco8-pose.yaml"
```yaml
--8<-- "ultralytics/cfg/datasets/coco8-pose.yaml"
```
The `train` and `val` fields specify the paths to the directories containing the training and validation images, respectively.

View File

@ -44,9 +44,11 @@ Here is an example of the YOLO dataset format for a single image with two object
The Ultralytics framework uses a YAML file format to define the dataset and model configuration for training Segmentation Models. Here is an example of the YAML format used for defining a segmentation dataset:
```yaml
--8<-- "ultralytics/cfg/datasets/coco8-seg.yaml"
```
!!! example "ultralytics/cfg/datasets/coco8-seg.yaml"
```yaml
--8<-- "ultralytics/cfg/datasets/coco8-seg.yaml"
```
The `train` and `val` fields specify the paths to the directories containing the training and validation images, respectively.

View File

@ -208,6 +208,9 @@ priytosh.revolution@live.com:
rulosanti@gmail.com:
avatar: null
username: null
shuai.lyu@foxmail.com:
avatar: https://avatars.githubusercontent.com/u/31230805?v=4
username: ShuaiLYU
shuizhuyuanluo@126.com:
avatar: https://avatars.githubusercontent.com/u/171016?v=4
username: nihui

View File

@ -228,6 +228,15 @@ def test_train_scratch():
model(SOURCE)
@pytest.mark.skipif(not ONLINE, reason="environment is offline")
def test_train_ndjson():
"""Test training the YOLO model using NDJSON format dataset."""
model = YOLO(WEIGHTS_DIR / "yolo11n.pt")
model.train(
data="https://github.com/ultralytics/assets/releases/download/v0.0.0/coco8-ndjson.ndjson", epochs=1, imgsz=32
)
@pytest.mark.parametrize("scls", [False, True])
def test_train_pretrained(scls):
"""Test training of the YOLO model starting from a pre-trained checkpoint."""

View File

@ -1,6 +1,6 @@
# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
__version__ = "8.3.182"
__version__ = "8.3.183"
import os

View File

@ -1,5 +1,6 @@
# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
import asyncio
import json
import random
import shutil
@ -12,7 +13,8 @@ import cv2
import numpy as np
from PIL import Image
from ultralytics.utils import DATASETS_DIR, LOGGER, NUM_THREADS, TQDM
from ultralytics.utils import DATASETS_DIR, LOGGER, NUM_THREADS, TQDM, YAML
from ultralytics.utils.checks import check_file, check_requirements
from ultralytics.utils.downloads import download, zip_directory
from ultralytics.utils.files import increment_path
@ -754,3 +756,112 @@ def convert_to_multispectral(path: Union[str, Path], n_channels: int = 10, repla
multispectral = f(target_wavelengths)
cv2.imwritemulti(str(output_path), np.clip(multispectral, 0, 255).astype(np.uint8).transpose(2, 0, 1))
LOGGER.info(f"Converted {output_path}")
async def convert_ndjson_to_yolo(ndjson_path: Union[str, Path], output_path: Optional[Union[str, Path]] = None) -> Path:
"""
Convert NDJSON dataset format to Ultralytics YOLO11 dataset structure.
This function converts datasets stored in NDJSON (Newline Delimited JSON) format to the standard YOLO
format with separate directories for images and labels. It supports parallel processing for efficient
conversion of large datasets and can download images from URLs if they don't exist locally.
The NDJSON format consists of:
- First line: Dataset metadata with class names and configuration
- Subsequent lines: Individual image records with annotations and optional URLs
Args:
ndjson_path (Union[str, Path]): Path to the input NDJSON file containing dataset information.
output_path (Optional[Union[str, Path]], optional): Directory where the converted YOLO dataset
will be saved. If None, uses the parent directory of the NDJSON file. Defaults to None.
Returns:
(Path): Path to the generated data.yaml file that can be used for YOLO training.
Examples:
Convert a local NDJSON file:
>>> yaml_path = convert_ndjson_to_yolo("dataset.ndjson")
>>> print(f"Dataset converted to: {yaml_path}")
Convert with custom output directory:
>>> yaml_path = convert_ndjson_to_yolo("dataset.ndjson", output_path="./converted_datasets")
# Use with YOLO training
>>> from ultralytics import YOLO
>>> model = YOLO("yolo11n.pt")
>>> model.train(data="https://github.com/ultralytics/assets/releases/download/v0.0.0/coco8-ndjson.ndjson")
"""
check_requirements("aiohttp")
import aiohttp
ndjson_path = Path(check_file(ndjson_path))
output_path = Path(output_path or DATASETS_DIR)
with open(ndjson_path) as f:
lines = [json.loads(line.strip()) for line in f if line.strip()]
dataset_record, image_records = lines[0], lines[1:]
dataset_dir = output_path / ndjson_path.stem
splits = {record["split"] for record in image_records}
# Create directories and prepare YAML structure
dataset_dir.mkdir(parents=True, exist_ok=True)
data_yaml = dict(dataset_record)
data_yaml["names"] = {int(k): v for k, v in dataset_record.get("class_names", {}).items()}
for split in sorted(splits):
(dataset_dir / "images" / split).mkdir(parents=True, exist_ok=True)
(dataset_dir / "labels" / split).mkdir(parents=True, exist_ok=True)
data_yaml[split] = f"images/{split}"
async def process_record(session, semaphore, record):
"""Process single image record with async session."""
async with semaphore:
split, original_name = record["split"], record["file"]
label_path = dataset_dir / "labels" / split / f"{Path(original_name).stem}.txt"
image_path = dataset_dir / "images" / split / original_name
annotations = record.get("annotations", {})
lines_to_write = []
for key in annotations.keys():
lines_to_write = [" ".join(map(str, item)) for item in annotations[key]]
break
if "classification" in annotations:
lines_to_write = [str(cls) for cls in annotations["classification"]]
label_path.write_text("\n".join(lines_to_write) + "\n" if lines_to_write else "")
if http_url := record.get("url"):
if not image_path.exists():
try:
async with session.get(http_url, timeout=aiohttp.ClientTimeout(total=30)) as response:
response.raise_for_status()
with open(image_path, "wb") as f:
async for chunk in response.content.iter_chunked(8192):
f.write(chunk)
return True
except Exception as e:
LOGGER.warning(f"Failed to download {http_url}: {e}")
return False
return True
# Process all images with async downloads
semaphore = asyncio.Semaphore(64)
async with aiohttp.ClientSession() as session:
pbar = TQDM(
total=len(image_records),
desc=f"Converting {ndjson_path.name} → {dataset_dir} ({len(image_records)} images)",
)
async def tracked_process(record):
result = await process_record(session, semaphore, record)
pbar.update(1)
return result
await asyncio.gather(*[tracked_process(record) for record in image_records])
pbar.close()
# Write data.yaml
yaml_path = dataset_dir / "data.yaml"
YAML.save(yaml_path, data_yaml)
return yaml_path

View File

@ -598,6 +598,15 @@ class BaseTrainer:
try:
if self.args.task == "classify":
data = check_cls_dataset(self.args.data)
elif self.args.data.rsplit(".", 1)[-1] == "ndjson":
# Convert NDJSON to YOLO format
import asyncio
from ultralytics.data.converter import convert_ndjson_to_yolo
yaml_path = asyncio.run(convert_ndjson_to_yolo(self.args.data))
self.args.data = str(yaml_path)
data = check_det_dataset(self.args.data)
elif self.args.data.rsplit(".", 1)[-1] in {"yaml", "yml"} or self.args.task in {
"detect",
"segment",