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:
parent
02558d1a77
commit
554af34ece
@ -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?
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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."""
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
|
||||
|
||||
__version__ = "8.3.182"
|
||||
__version__ = "8.3.183"
|
||||
|
||||
import os
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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",
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user