DataFlow-CV
🌊 Everything your model doesn't do. Analyse, convert, visualize, evaluate — a single CLI for all CV data.
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-cto control the order) - Also used by
analyse stats -cfor display names and strict category validation
💡 Converting a COCO dataset first? Run
coco2yoloonce — it writes a ready-to-useclasses.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/
# iscrowd=1 (crowd) annotations are skipped by default on both directions;
# opt in to writing them as ordinary rows/shapes:
dataflow-cv convert coco2yolo --save-crowd input.json yolo_labels/
# 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/.jsonis named by the image file stem — leading zeros preserved (000001.jpg→000001.txt). The converter generateslabels/(or the.jsonfiles) +classes.txt; theimages/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/
📊 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
⚠️
--predictionis required for YOLO prediction files — they have an extraconfidencetoken per line. The flag outputs a plain JSON list (not a full COCO dict), which is the standard DT format forloadRes(). Onlyyolo2cocosupports--prediction;labelme2cocodoes 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 requiresscore. - Instance Segmentation — mask IoU. GT and DT require
bbox,segmentation(polygon or RLE), andarea; DT additionally requiresscore.
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.formatto interpret coordinate semantics. - Strict Mode (default): Validation errors raise exceptions immediately. Disable with
--no-strict(CLI) orstrict_mode=False(API) to skip invalid annotations and continue. - Verbose Logging:
--verboseenables per-module file logging viaLogManager— console shows INFO-level progress, log files capture DEBUG details. All logging is owned by modules; the CLI usesclick.echo()for terminal output. - Headless Support: Use
--no-displayfor servers/Docker — pair with--saveto render visualization images without a GUI window. - Keyboard Shortcuts (visualization):
←/↑for previous,→/↓/Enter/Spacefor next,sto save snapshot,hto show hints,q/ESCto exit. First/last-image boundaries are no-ops. Title bar shows[N/T]position. - Evaluation:
--prf1computes 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--prf1for 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
--predictionwithyolo2coco— outputs a plain JSON list of annotation dicts compatible with pycocotoolsloadRes().
🔧 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.
- 🍴 Fork the repository
- 🌿 Create a feature branch
- ✏️ Make your changes — spec-first: if a change affects a contract in specs/, update the spec before the code (SDD, see the
/maestro:specskill) - 🧪 Add or update tests as needed
- ✅ Ensure code passes formatting and linting checks
- 📬 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.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| dataflow_cv-3.3.0.tar.gz | 140.5 kB | With provenance | Details for dataflow_cv-3.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| dataflow_cv-3.3.0-py3-none-any.whl | Python 3 | none | any | Details for dataflow_cv-3.3.0-py3-none-any.whl |
Total release size: 301.8 kB
Release files / dataflow_cv-3.3.0.tar.gz
| Download URL | dataflow_cv-3.3.0.tar.gz |
|---|---|
| Size | 140.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
72e7f0b7136543d36ff75643d79bb2209783eae080b1bccd681832651ea20042
|
|
BLAKE2b-256 checksum How to use checksums |
a0c4ba331de37664caaae769604df58dead1690090c53c3accddd2cf8f441731
|
| 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 19, 2026.
Transparency logRelease files / dataflow_cv-3.3.0-py3-none-any.whl
| Download URL | dataflow_cv-3.3.0-py3-none-any.whl |
|---|---|
| Size | 161.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
197ef4b4d210ddd48266204a6dfbad1c1a05c568b96c1fd90bd57b7ce9d74f30
|
|
BLAKE2b-256 checksum How to use checksums |
d49d9377b386d84f93298b617c9d35ac02362250fa4f6d74477c9739eb9cee54
|
| 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 19, 2026.
Transparency logSecurity for dataflow-cv 3.3.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.
Attestation for dataflow_cv-3.3.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 19, 2026.
Transparency logA 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.