Skip to main content

DataFlow-CV

🌊 Everything your model doesn't do. Analyse, convert, visualize, evaluate — a single CLI for all CV data.

PyPI Python 3.8+ CI License Ask DeepWiki
Linux Windows macOS YOLO LabelMe COCO

A computer vision dataset processing library — analyse, convert, visualize, and evaluate annotations across YOLO, LabelMe, and COCO formats.

🔍 Analyse Stats, train/val split, category filter, N-way partition & file sampling — format auto-detection dataflow-cv analyse stats ...
🔄 Convert 6 directions: YOLO ↔ LabelMe ↔ COCO, plus model predictions dataflow-cv convert yolo2coco ...
🎨 Visualize OpenCV rendering with color-coded classes, display & save modes dataflow-cv visualize yolo ...
📊 Evaluate COCO mAP via pycocotools, single-threshold P/R/F1 per class dataflow-cv evaluate detection ...
💻 CLI + API Click-based CLI with rich --help; Python API for pipelines from dataflow.convert import ...
🤖 AI Skills Claude Code skill (/dataflow:dataflow-cv) for AI assistants — CLI/API reference & known gotchas claude plugin install dataflow@claude-skills

📦 Installation

pip install dataflow-cv               # from PyPI
pip install dataflow-cv[coco]         # optional: COCO RLE + evaluation

Or from source:

git clone https://github.com/zjykzj/DataFlow-CV.git
cd DataFlow-CV && pip install .

🚀 Quick Start

Command-line Interface

All required parameters (image directories, label directories, class files, output paths) are positional arguments for better usability. Use --help on any subcommand for detailed usage.

📂 Data Layout & classes.txt

Input data must follow each format's native layout — dataflow-cv detects the format automatically from what you point it at:

Format What you pass Expected layout
YOLO labels/ directory (+ images/ directory) One .txt per image: labels/000001.txt next to images/000001.jpg — the label file must share the image's file name. Detection lines are class_id cx cy w h; segmentation lines are class_id x1 y1 x2 y2 … (normalized [0,1] coordinates).
LabelMe a directory of .json files One .json per image (shapes with label + points).
COCO a single .json file One file containing images, annotations, categories arrays.

classes.txt is the class name mapping used by YOLO-related commands. It is just one class name per line — the line number is the class id (0-indexed):

person
bicycle
car
  • Required for: yolo2coco, yolo2labelme, labelme2yolo, labelme2coco, visualize yolo
  • Auto-generated for coco2yolo / coco2labelme (written next to the output — you can pass your own with -c to control the order)
  • Also used by analyse stats -c for display names and strict category validation

💡 Converting a COCO dataset first? Run coco2yolo once — it writes a ready-to-use classes.txt.

🔍 Dataset Analysis

# Dataset statistics (auto-detects YOLO / LabelMe / COCO)
dataflow-cv analyse stats yolo_labels/ --image-dir images/ --class-file classes.txt
dataflow-cv analyse stats labelme_json/
dataflow-cv analyse stats coco_annotations.json

# Multiple paths merge into one report (same format); -R recurses subdirectories
dataflow-cv analyse stats yolo_train/ yolo_val/ --recursive

# Train / test split (YOLO / LabelMe only — labels / images / both modes)
#   → outputs/train/ + outputs/val/  (each with labels/ + images/ in both mode)
dataflow-cv analyse split -l yolo_labels/ outputs/ --ratio 0.8 --seed 42 -c classes.txt
dataflow-cv analyse split -i images/ outputs/ --ratio 0.8
dataflow-cv analyse split -l yolo_labels/ -i images/ outputs/ --ratio 0.8

# Category filter (keep a subset of categories, remap IDs per new classes.txt)
#   → filtered/ receives the filtered labels + the new classes.txt
dataflow-cv analyse filter yolo_labels/ classes.txt classes_new.txt filtered/
dataflow-cv analyse filter coco_annotations.json classes.txt classes_new.txt filtered/

# N-way partition — YOLO / LabelMe only (labels drive, images follow by stem)
#   → parts/part_1/ … parts/part_N/  (each with labels/ + images/ in both mode)
dataflow-cv analyse partition -n 4 --label-dir yolo_labels/ --image-dir images/ parts/
dataflow-cv analyse partition -n 4 --image-dir images/ --shuffle parts/

# File sampling — collect N files (random or sequential, labels / images / both modes)
#   → flat files in output/  (or output/labels/ + output/images/ in both mode)
dataflow-cv analyse sample -l yolo_labels/ output/ -n 10
dataflow-cv analyse sample -i images/ output/ -n 10 --no-shuffle
dataflow-cv analyse sample -l yolo_labels/ -i images/ output/ -n 5 --seed 42

# Sort by count descending (default: class ID ascending)
dataflow-cv analyse stats --sort-by count --descending yolo_labels/

# Verbose logging
dataflow-cv analyse stats --verbose yolo_labels/ --class-file classes.txt

🔄 Format Conversion

# YOLO → COCO                      → output.json: single COCO file
dataflow-cv convert yolo2coco images/ yolo_labels/ classes.txt output.json

# YOLO → COCO (with RLE encoding)
dataflow-cv convert yolo2coco images/ yolo_labels/ classes.txt output.json --do-rle

# YOLO → LabelMe                   → labelme_json/: one .json per image
dataflow-cv convert yolo2labelme images/ yolo_labels/ classes.txt labelme_json/

# LabelMe → YOLO                   → yolo_labels/: one .txt per image + classes.txt
dataflow-cv convert labelme2yolo labelme_json/ classes.txt yolo_labels/

# LabelMe → COCO                   → output.json: single COCO file
dataflow-cv convert labelme2coco labelme_json/ classes.txt output.json

# COCO → YOLO                      → yolo_labels/labels/*.txt + classes.txt
dataflow-cv convert coco2yolo input.json yolo_labels/

# COCO → LabelMe                   → labelme_json/: one .json per image
dataflow-cv convert coco2labelme input.json labelme_json/

# YOLO predictions → COCO (output: plain JSON list — prediction format)
dataflow-cv convert yolo2coco --prediction images/ yolo_preds/ classes.txt pred.json

# Options
dataflow-cv convert yolo2coco --verbose images/ labels/ classes.txt output.json
dataflow-cv convert yolo2coco --no-strict images/ labels/ classes.txt output.json

📂 COCO→YOLO / COCO→LabelMe output naming: each .txt / .json is named by the image file stem — leading zeros preserved (000001.jpg → 000001.txt). The converter generates labels/ (or the .json files) + classes.txt; the images/ directory is created but left empty — images are never copied, place your image files there yourself.

🎨 Visualization

# Visualize YOLO annotations
dataflow-cv visualize yolo images/ yolo_labels/ classes.txt --save visualized/

# Visualize LabelMe annotations
dataflow-cv visualize labelme images/ labelme_json/ --save visualized/

# Visualize COCO annotations
dataflow-cv visualize coco images/ coco_annotations.json --save visualized/

# Verbose logging + headless mode
dataflow-cv visualize yolo --verbose --no-display images/ yolo_labels/ classes.txt --save visualized/

Segmentation visualization demo 1 Segmentation visualization demo 2

📊 Evaluation

Evaluate object detection and instance segmentation models with COCO-standard metrics. Two COCO-format JSON files are required:

File Role Format How to create
anno.json Ground Truth (GT) Full COCO dict (images, annotations, categories) yolo2coco (label mode)
pred.json Detection (DT) Plain JSON list (with score) yolo2coco --prediction
① Prepare Data
# GT: YOLO labels → COCO
dataflow-cv convert yolo2coco images/ yolo_labels/ classes.txt anno.json

# DT: YOLO predictions → COCO (add --prediction for model output)
dataflow-cv convert yolo2coco --prediction images/ yolo_preds/ classes.txt pred.json

⚠️ --prediction is required for YOLO prediction files — they have an extra confidence token per line. The flag outputs a plain JSON list (not a full COCO dict), which is the standard DT format for loadRes(). Only yolo2coco supports --prediction; labelme2coco does not need it (LabelMe has no label vs prediction distinction).

② Run Evaluation
# Object detection (bbox IoU)
dataflow-cv evaluate detection anno.json pred.json
dataflow-cv evaluate detection --verbose anno.json pred.json           # per-class breakdown
dataflow-cv evaluate detection --prf1 anno.json pred.json              # P/R/F1 only (skip mAP)
dataflow-cv evaluate detection --prf1 --prf1-iou 0.75 --prf1-method micro anno.json pred.json

# Instance segmentation (mask IoU)
dataflow-cv evaluate segmentation anno.json pred.json
dataflow-cv evaluate segmentation --verbose anno.json pred.json

# Save results as JSON
dataflow-cv evaluate detection --output results.json anno.json pred.json

# Save P/R/F1 results as JSON (thresholds, method, overall + per-class values)
dataflow-cv evaluate detection --prf1 --output prf1_results.json anno.json pred.json

# Custom log directory
dataflow-cv evaluate detection --verbose --log-dir logs/eval/ anno.json pred.json
③ Detection vs Segmentation

Two evaluation modes, distinguished by how overlap is measured:

  • Object Detection — bounding box IoU. GT and DT require bbox; DT additionally requires score.
  • Instance Segmentation — mask IoU. GT and DT require bbox, segmentation (polygon or RLE), and area; DT additionally requires score.

yolo2coco (label mode) and yolo2coco --prediction (prediction mode) automatically populate all required fields for both modes — no manual editing needed.

🔄 End-to-End Workflow

The full pipeline from raw YOLO data to evaluation — the output of each step feeds the next:

# 0) Your data:  data/images/*.jpg  +  data/labels/*.txt (same file names)
#                +  classes.txt (one class name per line)

# 1) Inspect the dataset
dataflow-cv analyse stats data/labels/ --image-dir data/images/ --class-file classes.txt

# 2) Split into train / val          → data/split/train/ + data/split/val/
dataflow-cv analyse split -l data/labels/ -i data/images/ -c classes.txt \
    --ratio 0.8 --seed 42 data/split/

# 3) Val labels → COCO ground truth  (GT and DT must cover the SAME images —
#    evaluate your model on the val set)
dataflow-cv convert yolo2coco data/split/val/images/ data/split/val/labels/ \
    classes.txt gt.json

# 4) Model predictions on the val set → COCO detections
#    (prediction files carry confidence — 6 tokens for detection)
dataflow-cv convert yolo2coco --prediction data/split/val/images/ preds/ \
    classes.txt pred.json

# 5) Evaluate (mAP, or quick P/R/F1)
dataflow-cv evaluate detection gt.json pred.json
dataflow-cv evaluate detection --prf1 --output prf1.json gt.json pred.json

# 6) Spot-check the val set visually
dataflow-cv visualize yolo --no-display data/split/val/images/ data/split/val/labels/ \
    classes.txt --save viz/

🐍 Python API

from dataflow.util.logging import LogConfig
from dataflow.analyse import (
    StatsAnalyser,
    SplitAnalyser,
    FilterAnalyser,
    PartitionAnalyser,
    SampleAnalyser,
)
from dataflow.convert import YoloAndCocoConverter
from dataflow.visualize import YOLOVisualizer
from dataflow.evaluate import DetectionEvaluator, compute_pr_f1

# ── Analyse ─────────────────────────────────────────
log_cfg = LogConfig(name="analyse", verbose=True)

# Dataset statistics
analyser = StatsAnalyser(log_config=log_cfg)
result = analyser.analyse("yolo_labels/", class_file="classes.txt")
print(f"{result.data.total_files} images, {result.data.total_annotations} objects")

# Train/test split (YOLO / LabelMe)
splitter = SplitAnalyser(log_config=log_cfg)
result = splitter.analyse(
    output_dir="output/",
    ratio=0.8,
    seed=42,
    label_dir="yolo_labels/",
    class_file="classes.txt",
)
print(f"Train: {result.data.train_count}, Val: {result.data.val_count}")

# Split with images (both mode — labels drive, images follow by stem)
result = splitter.analyse(
    output_dir="output/",
    ratio=0.8,
    seed=42,
    label_dir="yolo_labels/",
    image_dir="images/",
    class_file="classes.txt",
)

# Category filter (keep / remap categories per new classes.txt)
filterer = FilterAnalyser(log_config=log_cfg)
result = filterer.analyse(
    "yolo_labels/",
    original_class_file="classes.txt",
    new_class_file="classes_new.txt",
    output_dir="filtered/",
)

# N-way partition (YOLO / LabelMe labels; images follow by stem)
partitioner = PartitionAnalyser(log_config=log_cfg)
result = partitioner.analyse(
    output_dir="parts/",
    num=4,
    label_dir="yolo_labels/",
    image_dir="images/",
)

# File sampling (labels, images, or both — random or sequential)
sampler = SampleAnalyser(log_config=log_cfg)
result = sampler.analyse(
    output_dir="sampled/",
    count=10,
    label_dir="yolo_labels/",
    shuffle=True,
    seed=42,
)

# ── Convert ──────────────────────────────────────────
# YOLO labels → COCO (label mode)
log_cfg = LogConfig(name="convert", verbose=True)
converter = YoloAndCocoConverter(source_to_target=True, log_config=log_cfg, strict_mode=True)
result = converter.convert(
    source_path="yolo_labels/",
    target_path="anno.json",
    class_file="classes.txt",
    image_dir="images/",
)

# YOLO predictions → COCO (prediction mode)
converter = YoloAndCocoConverter(source_to_target=True, prediction=True)
result = converter.convert(
    source_path="yolo_preds/",
    target_path="pred.json",
    class_file="classes.txt",
    image_dir="images/",
)

# ── Visualize ────────────────────────────────────────
visualizer = YOLOVisualizer(
    label_dir="yolo_labels/",
    image_dir="images/",
    class_file="classes.txt",
    is_show=True,
    is_save=True,
    output_dir="visualized/",
    log_config=log_cfg,
)
result = visualizer.visualize()

# ── Evaluate ─────────────────────────────────────────
evaluator = DetectionEvaluator(log_config=LogConfig(name="eval", verbose=True))
result = evaluator.evaluate("anno.json", "pred.json")
print(f"AP: {result.metrics.ap:.3f}, AP50: {result.metrics.ap50:.3f}")

# Quick P/R/F1 at IoU=0.5 (default: macro averaging, bbox IoU)
prf1 = compute_pr_f1("anno.json", "pred.json", iou_threshold=0.5)
print(f"Macro F1: {prf1.overall.f1_score:.3f}")

# Micro averaging P/R/F1 (samples weighted equally)
prf1 = compute_pr_f1("anno.json", "pred.json", method="micro")
print(f"Micro F1: {prf1.overall.f1_score:.3f}")

# Segmentation P/R/F1 (mask IoU)
prf1 = compute_pr_f1("anno_segm.json", "pred_segm.json", iou_type="segm")
print(f"Segm F1: {prf1.overall.f1_score:.3f}")

📂 See the samples/ directory for complete examples: samples/analyse/ (statistics & split), samples/convert/ (6 conversion directions), samples/visualize/ (YOLO, LabelMe, COCO), samples/evaluate/ (detection & segmentation), samples/cli/ (CLI workflows).

🤖 AI Assistant Skills

We maintain a dedicated Claude Code skill for dataflow-cv — /dataflow:dataflow-cv — so LLMs and AI agents can operate its CLI and Python API correctly in any project. The skill covers:

  • CLI command tree and task mapping: 16 subcommands across analyse / convert / visualize / evaluate
  • Python API reference: handlers, analysers, converters, visualizers, evaluators
  • Canonical example commands and known gotchas (coordinate semantics, prediction formats, RLE encoding, …)

Install once per machine:

claude plugin install dataflow@claude-skills

Once installed, AI assistants load the skill on demand when working on dataset conversion, evaluation, or similar tasks — it can also be invoked explicitly via /dataflow:dataflow-cv. The library works normally without it.


📖 Documentation

Resource Description
CLAUDE.md Architecture overview, development guide, and known gotchas
CHANGELOG.md Version history and breaking changes
specs/evaluate/ Evaluation metric contracts — IoU, matching, AP/mAP/AR
specs/formats/ External format contracts — YOLO, LabelMe, COCO, conversion rules
specs/modules/ Internal module architecture, interface contracts, dependency constraints

💡 Key Concepts

  • Format-Native Coordinates: YOLO uses normalized [0,1] center-based coordinates; LabelMe and COCO use absolute pixel top-left. There is no hidden internal normalization — check DatasetAnnotations.format to interpret coordinate semantics.
  • Strict Mode (default): Validation errors raise exceptions immediately. Disable with --no-strict (CLI) or strict_mode=False (API) to skip invalid annotations and continue.
  • Verbose Logging: --verbose enables per-module file logging via LogManager — console shows INFO-level progress, log files capture DEBUG details. All logging is owned by modules; the CLI uses click.echo() for terminal output.
  • Headless Support: Use --no-display for servers/Docker — pair with --save to render visualization images without a GUI window.
  • Keyboard Shortcuts (visualization): ← / ↑ for previous, → / ↓ / Enter / Space for next, s to save snapshot, h to show hints, q / ESC to exit. First/last-image boundaries are no-ops. Title bar shows [N/T] position.
  • Evaluation: --prf1 computes P/R/F1 only (single-threshold, per-class TP/FP/FN) — skips the full COCOeval mAP pipeline for speed. Supports macro/micro averaging and bbox/mask IoU. Run without --prf1 for standard COCO mAP. For both metrics, run twice.
  • Prediction Files: YOLO predictions use 6 tokens (detection) or even tokens (segmentation) vs 5/odd for labels. Use --prediction with yolo2coco — outputs a plain JSON list of annotation dicts compatible with pycocotools loadRes().

🔧 Development

For detailed developer guidance including advanced test commands, debugging, and architecture overview, see CLAUDE.md. Optional Claude Code skills for common tasks (/maestro:spec, /maestro:commit, /maestro:release, /maestro:claude) are available via the maestro plugin — the project develops normally without them.

🧪 Testing

656 tests, 81% code coverage (5645 statements).

pytest                                    # All tests
pytest --cov=dataflow --cov-report=term   # With coverage
pytest tests/convert/test_yolo_and_coco.py  # Single module
pytest tests/evaluate/test_evaluator.py     # Single module
📊 Coverage by module
Module Coverage Highlights
dataflow/label/ 72% models (86%), base (84%), utils (83%), coco_handler (73%), labelme_handler (71%), yolo_handler (63%)
dataflow/analyse/ 85% base (99%), log_templates (93%), sample (88%), split (88%), stats (83%), utils (84%), partition (79%), filter (76%)
dataflow/convert/ 87% labelme_and_yolo (93%), yolo_and_coco (89%), utils (88%), coco_and_labelme (88%), base (86%), log_templates (85%), rle (80%)
dataflow/visualize/ 83% yolo_vis (100%), labelme_vis (100%), coco_vis (93%), base (78%)
dataflow/evaluate/ 92% evaluator (100%), result (99%), metrics (89%), base (92%), utils (89%)
dataflow/cli/ 75% main (96%), utils (88%), visualize cmd (87%), evaluate cmd (83%), analyse cmd (70%), convert cmd (52%)
dataflow/util/ 100% logging (100%)

🎨 Code Quality

pip install -e .[dev]                       # Install dev dependencies
ruff check dataflow tests samples           # Lint
ruff format --check dataflow tests samples  # Format check
mypy dataflow                               # Type check

🔗 Pre-commit Hooks (Optional)

pip install pre-commit
pre-commit install            # Install git hooks (run once)

# After this, every `git commit` auto-runs:
#   ruff (lint, auto-fix) → ruff format → whitespace checks

pre-commit run --all-files    # Manual run against all files

📁 Project Structure

dataflow/
├── label/           # Annotation handlers + data models
├── analyse/         # Dataset stats, train/val split, category filter, N-way partition, file sampling
├── convert/         # Format converters, RLE utility, log templates
├── visualize/       # OpenCV-based rendering, log templates
├── evaluate/        # pycocotools-based metrics, log templates
├── util/            # Unified logging (LogManager + format helpers)
└── cli/             # CLI entry point, commands, validation
tests/               # Unit & integration tests (656 tests, conftest fixtures)
samples/             # Python API usage examples (analyse, convert, visualize, evaluate, cli)
assets/              # Test data (det/seg by format)
specs/               # Canonical specifications (evaluate/ + formats/ + modules/)

🤝 Contributing

Contributions are welcome! Please review CLAUDE.md for architecture and development patterns before contributing.

  1. 🍴 Fork the repository
  2. 🌿 Create a feature branch
  3. ✏️ Make your changes — spec-first: if a change affects a contract in specs/, update the spec before the code (SDD, see the /maestro:spec skill)
  4. 🧪 Add or update tests as needed
  5. ✅ Ensure code passes formatting and linting checks
  6. 📬 Submit a pull request

📄 License

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


🙏 Acknowledgments

  • Thanks to the creators of YOLO, LabelMe, and COCO formats for establishing these annotation standards
  • Built with OpenCV, NumPy, Click, and pycocotools
  • Inspired by the need for seamless format conversion in multi-tool CV pipelines

Metadata

Release files for dataflow-cv 3.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for dataflow-cv 3.1.0
File Size Uploaded Provenance Actions
dataflow_cv-3.1.0.tar.gz 128.6 kB With provenance Details for dataflow_cv-3.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for dataflow-cv 3.1.0
File Interpreter ABI Platform Actions
dataflow_cv-3.1.0-py3-none-any.whl Python 3 none any Details for dataflow_cv-3.1.0-py3-none-any.whl

Total release size: 277.6 kB

Release files / dataflow_cv-3.1.0.tar.gz

Download URL dataflow_cv-3.1.0.tar.gz
Size 128.6 kB
Tags Source
SHA-256 checksum
How to use checksums
4204cd4fb9483c6fc285e187e609a971c388f6a9cb5ae2a4b05ac53cb59dcb78
BLAKE2b-256 checksum
How to use checksums
60d9db70748df491af3e8304039c0492f0e7603450ed64c67fe41cf51f97ff75
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / dataflow_cv-3.1.0-py3-none-any.whl

Download URL dataflow_cv-3.1.0-py3-none-any.whl
Size 149.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cb8e19eed462c814d0a7219ef02f6a9816e983365d2a45886c6b8064c53a2955
BLAKE2b-256 checksum
How to use checksums
8c8b255d349111470d0b9b0ba49c7181fb7bd026ccb387d8878030af04181e6b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for dataflow-cv 3.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for dataflow_cv-3.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page