🔍 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 custom-built FiftyOne plugins that are 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.
@ultralytics/dataset-curation	Select a diverse subset of your dataset and export it as a new YOLO dataset. See Similarity search and dataset curation.		Click the operator browser icon, then select the operator from the list.

🔎 Similarity search and dataset curation

Unless skip_embeddings is set, every dataset gets a similarity index and a uniqueness field computed automatically alongside the CLIP embeddings, at no extra cost since they reuse the same embeddings. These power two workflows.

1. Finding similar images

This is a native FiftyOne feature, nothing extra to install. Click the + next to the Samples tab, open the Similarity Search panel, and click New Search. You can search using an image already in the dataset, or upload an external one (a production image, for example) to find its closest matches.

2. Finding redundant images

Every sample gets a uniqueness field, 1 meaning very different from the rest of the dataset and values close to 0 meaning near-duplicates of other samples. Sort or filter by it in the sidebar to spot the most redundant images, or the most unique ones.

3. Selecting a diverse subset and exporting it

Use the two operators from the @ultralytics/dataset-curation plugin together. Click the operator browser icon and select the operator from the list, one at a time.

1. Select a diverse subset (k-center-greedy): set a similarity threshold between 0 and 1, where 1 means identical. No two kept images will ever be more similar than this threshold, so a lower value keeps fewer, more diverse images. How many images this keeps depends on your dataset, not a number you pick upfront, so start around 0.9 and adjust based on the resulting count.
2. Export current view as a YOLO dataset: pick an output directory. The current view (the one from step 1, or any other filter you've applied) is copied there as a new YOLO dataset, images and label files copied as-is and the splits are preserved.

⚒️ 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