🔍 YoloScout — YOLO Dataset quality analysis tool

A comprehensive tool for analyzing and visualizing YOLO dataset quality using a custom FiftyOne wrapper

🚀 Quick Start

Installation

# Install the package from PyPI
pip install yolo-scout

Basic Usage

# Object detection dataset
yolo-scout data=/path/to/dataset task=detect

# Segmentation with MetaCLIP embeddings
yolo-scout data=/path/to/data.yaml task=segment model=metaclip_400m

# Ultralytics Platform dataset
ULTRALYTICS_API_KEY=<your_key> yolo-scout data=ul://username/datasets/my-dataset task=detect

# Config file with CLI overrides
yolo-scout config=my_config.yaml batch=8

# Force reload of an existing dataset
yolo-scout data=/path/to/dataset task=detect reload=true

If you want to use the configuration file option, you can create a config file (e.g., my_config.yaml) with the following structure (all keys are optional and override the defaults):

data: "/path/to/your/dataset" # directory, data.yaml, or ul://username/datasets/slug
task: "detect" # detect, segment, classify, pose, obb
name: "my_dataset" # auto-generated from path if not set
reload: false
dataset_dir: "yolo_scout/datasets" # where URL-sourced datasets are downloaded

skip_embeddings: false
model: "openai_clip"
batch: 16
mask_background: true

thumbnail_dir: "yolo_scout/thumbnails"
thumbnail_width: 800

skip_quality: false

port: 5151
skip_launch: false
verbose: false

Command-Line Arguments

📊 Supported tasks and image metadata

For each expected task format, the following metadata will be computed and available in FiftyOne for each annotation:

Also, for each image, the following metadata will be computed:

The following quality metrics are computed unless skip_quality is passed. All metrics operate on grayscale pixel values and are available at both image and patch level.

⭐️ Supported Models

All models use 224x224 input resolution. This is a constraint imposed by FiftyOne's OpenCLIP integration (higher resolution variants (384, 512) cause preprocessing errors when computing embeddings). The 224x224 resolution provides excellent quality for most computer vision tasks while maintaining compatibility with FiftyOne's model zoo.

Model Selection Guide

• Use openai_clip if you want to use the most common embeddings model
• Use metaclip_400m for better quality embeddings (recommended default)
• Use metaclip_fullcc when you need the highest quality embeddings
• Use siglip_base_224 as an alternative to CLIP-based models

All models have similar inference speed and produce 512-dimensional embeddings with full support for FiftyOne visualization and analysis features.

🌐 Supported data sources

The supported URL schemes for the data argument are:

🧩 Additional installed plugins

This tool ships with a custom-built FiftyOne plugin that is automatically installed at startup. No manual setup required.

Plugin	Description	Icon	How to use?
@ultralytics/image-adjuster	Custom plugin to adjust image brightness, contrast, and label overlay opacity.		Open a sample, then click the slider icon in the bottom-left corner.

⚒️ Dataset Structure

This tool supports two common YOLO dataset directory structures:

Format 1: Type-First Structure

dataset/
├── images/
│   ├── train/
│   │   ├── image1.jpg
│   │   ├── image2.jpg
│   │   └── ...
│   ├── val/
│   │   ├── image1.jpg
│   │   └── ...
│   └── test/
│       └── ...
└── labels/
    ├── train/
    │   ├── image1.txt
    │   ├── image2.txt
    │   └── ...
    ├── val/
    │   ├── image1.txt
    │   └── ...
    └── test/
        └── ...

In this format, images and labels are organized by type first, then by split.

Format 2: Split-First Structure

dataset/
├── train/
│   ├── images/
│   │   ├── image1.jpg
│   │   ├── image2.jpg
│   │   └── ...
│   └── labels/
│       ├── image1.txt
│       ├── image2.txt
│       └── ...
├── val/
│   ├── images/
│   │   └── ...
│   └── labels/
│       └── ...
└── test/
    ├── images/
    │   └── ...
    └── labels/
        └── ...

In this format, the dataset is organized by split first, then by type (images/labels).

⌨️ FiftyOne commands

If you have used this tool at least one time to visualize a dataset, you can then use the following commands bellow to interact with the FiftyOne datasets and application:

# List all the datasets
fiftyone datasets list

# Delete a specific dataset using its name
fiftyone datasets delete <dataset_name>

# Delete all datasets
python -c "import fiftyone as fo; [fo.delete_dataset(name) for name in fo.list_datasets()]"

# Launch the FiftyOne app
fiftyone app launch

# Launch the FiftyOne app and pre-select a dataset using its name
fiftyone app launch <dataset_name>

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with FiftyOne by Voxel51
• Inspired by Ultralytics YOLO ecosystem
• CLIP models from OpenAI