From 554af34ecec8c8da6e63199d18a2663debda65ef Mon Sep 17 00:00:00 2001 From: Glenn Jocher Date: Thu, 21 Aug 2025 13:50:33 +0200 Subject: [PATCH] `ultralytics 8.3.183` New NDJSON dataset format support (#21747) Signed-off-by: Glenn Jocher Co-authored-by: UltralyticsAssistant --- docs/en/datasets/detect/index.md | 102 +++++++++++++++++++++++++-- docs/en/datasets/obb/index.md | 8 ++- docs/en/datasets/pose/index.md | 8 ++- docs/en/datasets/segment/index.md | 8 ++- docs/mkdocs_github_authors.yaml | 3 + tests/test_python.py | 9 +++ ultralytics/__init__.py | 2 +- ultralytics/data/converter.py | 113 +++++++++++++++++++++++++++++- ultralytics/engine/trainer.py | 9 +++ 9 files changed, 245 insertions(+), 17 deletions(-) diff --git a/docs/en/datasets/detect/index.md b/docs/en/datasets/detect/index.md index bb36c1d7..f274f4d6 100644 --- a/docs/en/datasets/detect/index.md +++ b/docs/en/datasets/detect/index.md @@ -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

Example dataset directory structure

-## 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? diff --git a/docs/en/datasets/obb/index.md b/docs/en/datasets/obb/index.md index 178190a3..ca1bdff6 100644 --- a/docs/en/datasets/obb/index.md +++ b/docs/en/datasets/obb/index.md @@ -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 diff --git a/docs/en/datasets/pose/index.md b/docs/en/datasets/pose/index.md index 7b1fd8ea..24ffa0a1 100644 --- a/docs/en/datasets/pose/index.md +++ b/docs/en/datasets/pose/index.md @@ -40,9 +40,11 @@ In this format, `` is the index of the class for the object,` 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 diff --git a/ultralytics/engine/trainer.py b/ultralytics/engine/trainer.py index 3b47c82a..d9db7e3d 100644 --- a/ultralytics/engine/trainer.py +++ b/ultralytics/engine/trainer.py @@ -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",