dataflow-cv 1.3.0__tar.gz → 1.5.0__tar.gz

{dataflow_cv-1.3.0/dataflow_cv.egg-info → dataflow_cv-1.5.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: dataflow-cv
-Version: 1.3.0
+Version: 1.5.0
 Summary: A computer vision dataset processing library
-Author-email: DataFlow-CV Team <example@example.com>
+Author: DataFlow-CV Team
 License: MIT
 Project-URL: Bug Reports, https://github.com/zjykzj/DataFlow-CV/issues
 Project-URL: Source, https://github.com/zjykzj/DataFlow-CV
@@ -35,10 +35,6 @@ Requires-Dist: black>=22.0.0; extra == "dev"
 Requires-Dist: isort>=5.12.0; extra == "dev"
 Requires-Dist: flake8>=6.0.0; extra == "dev"
 Requires-Dist: mypy>=1.0.0; extra == "dev"
-Requires-Dist: pylint>=3.0.0; extra == "dev"
-Provides-Extra: docs
-Requires-Dist: sphinx>=7.0.0; extra == "docs"
-Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "docs"
 Dynamic: license-file
 
 # DataFlow-CV
@@ -54,66 +50,36 @@ Dynamic: license-file
   <img src="https://img.shields.io/badge/Linux-Supported-fcc624?logo=linux" alt="Linux">
   <img src="https://img.shields.io/badge/Windows-Supported-00a2e8?logo=windows" alt="Windows">
   <img src="https://img.shields.io/badge/macOS-Supported-999999?logo=apple" alt="macOS">
+  <img src="https://img.shields.io/badge/YOLO-.txt-00a86b?style=flat-square" alt="YOLO">
+  <img src="https://img.shields.io/badge/LabelMe-.json-f39c12?style=flat-square" alt="LabelMe">
+  <img src="https://img.shields.io/badge/COCO-.json-e74c3c?style=flat-square" alt="COCO">
 </p>
 
-A computer vision dataset processing library for seamless format conversion, visualization, and evaluation between YOLO, LabelMe, and COCO annotation formats. Designed for researchers and developers working with multi-format annotation pipelines.
-
-```mermaid
-graph LR
-    A[YOLO<br/>.txt] -->|convert| D[DataFlow-CV]
-    B[LabelMe<br/>.json] -->|convert| D
-    C[COCO<br/>.json] -->|convert| D
-    D -->|visualize| E[🎨 Rendered<br/>Images]
-    D -->|evaluate| F[📊 mAP / AR<br/>Metrics]
-```
-
----
-
-## ✨ Features
+A computer vision dataset processing library — convert, visualize, and evaluate annotations across YOLO, LabelMe, and COCO formats.
 
 | | | |
 |:---|:---|:---|
-| 🔄 **Format Conversion** | Convert between YOLO, LabelMe, and COCO in any direction — 6 conversion paths, plus prediction file support (outputs standard list-format COCO predictions) |
-| 🎯 **Detection & Segmentation** | Handle both object detection (bbox) and instance segmentation (polygon/RLE) annotations |
-| 🎨 **Visualization** | Render annotations with OpenCV — color-coded classes, semi-transparent masks, display & save modes |
-| 📊 **Evaluation** | COCO-standard 12-metric output (mAP, AP50, AP75, AR) via pycocotools, with per-class breakdowns and macro/micro P/R/F1 |
-| 💻 **Command-line Interface** | Intuitive CLI with `convert`, `visualize`, and `evaluate` subcommands — positional args, rich `--help` |
-| 🐍 **Python API** | Programmatic access for integration into larger ML pipelines |
-| 📝 **Verbose Logging** | File-based debug logging with timestamps — toggle with `--verbose` |
-| 🖥️ **Headless Mode** | Server/Docker-friendly: `--no-display` + `--save` for off-screen rendering |
-| 🛡️ **Flexible Error Handling** | Strict mode (abort on error) or lenient mode (skip & continue with warnings) via `--no-strict` |
+| 🔄 **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 ...` |
 
 ---
 
 ## 📦 Installation
 
-### From PyPI
-
 ```bash
-pip install dataflow-cv
+pip install dataflow-cv               # from PyPI
+pip install pycocotools               # optional: COCO RLE + evaluation
 ```
 
-### From Source
+Or from source:
 
 ```bash
 git clone https://github.com/zjykzj/DataFlow-CV.git
-cd DataFlow-CV
-
-# Regular installation
-pip install .
-
-# Editable installation (for development)
-pip install -e .
+cd DataFlow-CV && pip install .
 ```
 
-> 💡 **Tip**: When installed in editable mode, use `python -m dataflow.cli` instead of the `dataflow-cv` command.
-
-### Optional Dependencies
-
-| Dependency | Purpose | Install |
-|-----------|---------|---------|
-| `pycocotools` | COCO RLE segmentation + evaluation | `pip install pycocotools` |
-
 ---
 
 ## 🚀 Quick Start
@@ -170,89 +136,70 @@ dataflow-cv visualize coco images/ coco_annotations.json --save visualized/
 dataflow-cv visualize yolo --verbose --no-display images/ yolo_labels/ classes.txt --save visualized/
 ```
 
-#### 📊 Evaluation
+<p align="center">
+  <img src="assets/showcase/seg_demo_1.jpg" width="45%" alt="Segmentation visualization demo 1">
+  <img src="assets/showcase/seg_demo_2.jpg" width="45%" alt="Segmentation visualization demo 2">
+</p>
 
-Evaluate object detection and instance segmentation model outputs using COCO-standard metrics. Two COCO-format JSON files are required:
+#### 📊 Evaluation
 
-| File | Role | Format | Source |
-|------|------|--------|--------|
-| **`anno.json`** | Ground Truth (GT) — reference annotations | Full COCO dict (`images`, `annotations`, `categories`) | `yolo2coco` (label mode) |
-| **`pred.json`** | Detection (DT) — model predictions | Plain JSON list of annotation dicts (with `score`) | `yolo2coco --prediction`, Detectron2, MMDetection |
+Evaluate object detection and instance segmentation models with COCO-standard metrics. Two COCO-format JSON files are required:
 
-##### ① Preparing Evaluation Data
+| 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` |
 
-If your annotations and predictions are in YOLO format, convert them to COCO JSON first:
+##### ① Prepare Data
 
 ```bash
-# Step 1: YOLO ground truth labels → COCO GT (anno.json)
-#   Label format:   class_id cx cy w h               ← 5 tokens (detection)
-#                   class_id x1 y1 ... xn yn          ← odd tokens (segmentation)
+# GT: YOLO labels → COCO
 dataflow-cv convert yolo2coco images/ yolo_labels/ classes.txt anno.json
 
-# Step 2: YOLO predictions → COCO DT (pred.json)
-#   Prediction fmt: class_id cx cy w h confidence     ← 6 tokens (detection)
-#                   class_id x1 y1 ... xn yn confidence ← even tokens (segmentation)
+# DT: YOLO predictions → COCO (add --prediction for model output)
 dataflow-cv convert yolo2coco --prediction images/ yolo_preds/ classes.txt pred.json
 ```
 
-> ⚠️ **Important**: YOLO label files (GT) use **odd** token counts, while prediction files (DT) use **even** token counts with a trailing `confidence`. The `--prediction` flag is required for DT — it outputs a **plain JSON list** of annotation dicts (not a full COCO dict with `images`/`categories`). Mixed label/prediction files in the same directory are not supported.
->
-> ℹ️ **Note**: The `--prediction` flag is **only available for `yolo2coco`**. `labelme2coco` does not support prediction conversion — LabelMe files (.json) have no label vs prediction format distinction, so there is no equivalent prediction source format to convert from.
-
-##### ② Detection vs Segmentation — Format Requirements
-
-| Field | Detection GT | Detection DT | Segmentation GT | Segmentation DT |
-|-------|:-----------:|:-----------:|:---------------:|:---------------:|
-| `bbox` | ✅ Required | ✅ Required | ✅ Required (for area) | ✅ Required (for area) |
-| `score` | — | ✅ **Required** | — | ✅ **Required** |
-| `segmentation` | ❌ Not required | ❌ Not required | ✅ **Required** | ✅ **Required** |
-| `area` | ⚪ Recommended | ⚪ Recommended | ✅ **Required** | ✅ **Required** |
-| `iscrowd` | ⚪ Optional | — | ⚪ Optional | — |
-
-- **Object Detection** (`iouType='bbox'`): Bounding box overlap evaluation. Only `bbox` + `score` mandatory in DT.
-- **Instance Segmentation** (`iouType='segm'`): Mask overlap evaluation. GT and DT must include `segmentation` (polygon or RLE), `area`, and `bbox`.
+> ⚠️ `--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).
 
-##### ③ CLI Commands
+##### ② Run Evaluation
 
 ```bash
-# Object detection evaluation (bbox IoU)
+# 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
 
-# Verbose per-class breakdown
-dataflow-cv evaluate detection --verbose anno.json pred.json
-
-# With P/R/F1 at IoU=0.5 (default: macro averaging)
-dataflow-cv evaluate detection --prf1 --prf1-iou 0.5 anno.json pred.json
-
-# With P/R/F1 using micro averaging
-dataflow-cv evaluate detection --prf1 --prf1-method micro anno.json pred.json
-
-# Instance segmentation evaluation (mask IoU)
+# 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
 ```
 
-##### ④ End-to-End Workflow
+##### ③ Detection vs Segmentation
 
-```bash
-# Complete pipeline: YOLO → COCO → Evaluation
-dataflow-cv convert yolo2coco images/ yolo_labels/ classes.txt anno.json
-dataflow-cv convert yolo2coco --prediction images/ yolo_preds/ classes.txt pred.json
-dataflow-cv evaluate detection --verbose --prf1 anno.json pred.json
-```
+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.
 
 ### 🐍 Python API
 
 ```python
+from dataflow.util.logging import LogConfig
 from dataflow.convert import YoloAndCocoConverter
 from dataflow.visualize import YOLOVisualizer
 from dataflow.evaluate import DetectionEvaluator, compute_pr_f1
 
 # ── Convert ──────────────────────────────────────────
 # YOLO labels → COCO (label mode)
-converter = YoloAndCocoConverter(source_to_target=True, verbose=True, strict_mode=True)
+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/",
@@ -269,12 +216,12 @@ result = converter.convert(
 visualizer = YOLOVisualizer(
     label_dir="yolo_labels/", image_dir="images/",
     class_file="classes.txt", is_show=True, is_save=True,
-    output_dir="visualized/", verbose=True, strict_mode=True,
+    output_dir="visualized/", log_config=log_cfg,
 )
 result = visualizer.visualize()
 
 # ── Evaluate ─────────────────────────────────────────
-evaluator = DetectionEvaluator(verbose=True)
+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}")
 
@@ -291,7 +238,7 @@ 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/visualize/` (YOLO, LabelMe, COCO demos), `samples/convert/` (conversion examples).
+> 📂 See the `samples/` directory for complete examples: `samples/convert/` (6 conversion directions), `samples/visualize/` (YOLO, LabelMe, COCO), `samples/evaluate/` (detection & segmentation), `samples/cli/` (CLI workflows).
 
 ---
 
@@ -307,15 +254,13 @@ print(f"Segm F1: {prf1.overall.f1_score:.3f}")
 
 ### 💡 Key Concepts
 
-- **Format-Native Coordinates**: Coordinates stored in each format's native representation — YOLO normalized [0,1] center-based, LabelMe/COCO absolute pixels top-left. Check `DatasetAnnotations.format` to determine semantics.
-- **Explicit Coordinate Transforms**: Converters handle all coordinate transformations between formats — no hidden normalization.
-- **Strict Mode**: Validation errors raise exceptions by default. Disable with `--no-strict` (CLI) or `strict_mode=False` (API).
-- **Verbose Logging**: Detailed debug logs saved to files when `--verbose` is used. The CLI prints the log file path after each operation.
-- **Headless Support**: Use `--no-display` for servers/Docker; pair with `--save` to output visualization images without a window.
-- **Keyboard Shortcuts**: During visualization — `q`/`ESC` to exit, `Enter`/`Space` to advance, any other key to continue.
-- **Color Management**: Each class ID gets a unique color from an HSV-based palette (up to 1000 classes) for consistent visualization.
-- **Evaluation Metrics**: COCO-standard 12-metric output with optional per-class breakdown. P/R/F1 supports both macro (default) and micro averaging, and both bbox and mask IoU.
-- **Prediction Files**: YOLO prediction files use 6 tokens (detection) or even tokens (segmentation) vs 5/odd for labels. `--prediction` outputs a plain JSON list of annotation dicts — the standard prediction exchange format compatible with pycocotools `loadRes()`.
+- **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): `q` / `ESC` to exit, `Enter` / `Space` to advance, any other key to continue.
+- **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()`.
 
 ---
 
@@ -325,7 +270,7 @@ For detailed developer guidance including advanced test commands, debugging, and
 
 ### 🧪 Testing
 
-**405 tests, 76% code coverage (3986 statements).**
+**418 tests, 76% code coverage (3986 statements).**
 
 ```bash
 pytest                                    # All tests
@@ -344,7 +289,7 @@ pytest tests/evaluate/test_evaluator.py     # Single module
 | `dataflow/visualize/` | 81% | yolo_vis (100%), labelme_vis (100%), coco_vis (97%), base (74%) |
 | `dataflow/evaluate/` | 87% | evaluator (100%), metrics (93%), result (99%), base (91%), utils (68%) |
 | `dataflow/cli/` | 59% | main (96%), convert cmd (48%), evaluate cmd (24%), visualize cmd (84%), utils (86%) |
-| `dataflow/util/` | 93% | logging (98%), file_util (84%) |
+| `dataflow/util/` | 93% | logging (98%) |
 
 </details>
 
@@ -375,12 +320,12 @@ pre-commit run --all-files    # Manual run against all files
 ```
 dataflow/
 ├── label/           # Annotation handlers + data models
-├── convert/         # Format converters + RLE utility
-├── visualize/       # OpenCV-based rendering
-├── evaluate/        # pycocotools-based metrics
-├── util/            # Logging & file utilities
+├── 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
+tests/               # Unit & integration tests (418 tests, conftest fixtures)
 samples/             # Python API usage examples
 assets/              # Test data (det/seg by format)
 specs/               # Canonical specifications (evaluate/ + formats/ + modules/)

{dataflow_cv-1.3.0 → dataflow_cv-1.5.0}/README.md

@@ -11,66 +11,36 @@
   <img src="https://img.shields.io/badge/Linux-Supported-fcc624?logo=linux" alt="Linux">
   <img src="https://img.shields.io/badge/Windows-Supported-00a2e8?logo=windows" alt="Windows">
   <img src="https://img.shields.io/badge/macOS-Supported-999999?logo=apple" alt="macOS">
+  <img src="https://img.shields.io/badge/YOLO-.txt-00a86b?style=flat-square" alt="YOLO">
+  <img src="https://img.shields.io/badge/LabelMe-.json-f39c12?style=flat-square" alt="LabelMe">
+  <img src="https://img.shields.io/badge/COCO-.json-e74c3c?style=flat-square" alt="COCO">
 </p>
 
-A computer vision dataset processing library for seamless format conversion, visualization, and evaluation between YOLO, LabelMe, and COCO annotation formats. Designed for researchers and developers working with multi-format annotation pipelines.
-
-```mermaid
-graph LR
-    A[YOLO<br/>.txt] -->|convert| D[DataFlow-CV]
-    B[LabelMe<br/>.json] -->|convert| D
-    C[COCO<br/>.json] -->|convert| D
-    D -->|visualize| E[🎨 Rendered<br/>Images]
-    D -->|evaluate| F[📊 mAP / AR<br/>Metrics]
-```
-
----
-
-## ✨ Features
+A computer vision dataset processing library — convert, visualize, and evaluate annotations across YOLO, LabelMe, and COCO formats.
 
 | | | |
 |:---|:---|:---|
-| 🔄 **Format Conversion** | Convert between YOLO, LabelMe, and COCO in any direction — 6 conversion paths, plus prediction file support (outputs standard list-format COCO predictions) |
-| 🎯 **Detection & Segmentation** | Handle both object detection (bbox) and instance segmentation (polygon/RLE) annotations |
-| 🎨 **Visualization** | Render annotations with OpenCV — color-coded classes, semi-transparent masks, display & save modes |
-| 📊 **Evaluation** | COCO-standard 12-metric output (mAP, AP50, AP75, AR) via pycocotools, with per-class breakdowns and macro/micro P/R/F1 |
-| 💻 **Command-line Interface** | Intuitive CLI with `convert`, `visualize`, and `evaluate` subcommands — positional args, rich `--help` |
-| 🐍 **Python API** | Programmatic access for integration into larger ML pipelines |
-| 📝 **Verbose Logging** | File-based debug logging with timestamps — toggle with `--verbose` |
-| 🖥️ **Headless Mode** | Server/Docker-friendly: `--no-display` + `--save` for off-screen rendering |
-| 🛡️ **Flexible Error Handling** | Strict mode (abort on error) or lenient mode (skip & continue with warnings) via `--no-strict` |
+| 🔄 **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 ...` |
 
 ---
 
 ## 📦 Installation
 
-### From PyPI
-
 ```bash
-pip install dataflow-cv
+pip install dataflow-cv               # from PyPI
+pip install pycocotools               # optional: COCO RLE + evaluation
 ```
 
-### From Source
+Or from source:
 
 ```bash
 git clone https://github.com/zjykzj/DataFlow-CV.git
-cd DataFlow-CV
-
-# Regular installation
-pip install .
-
-# Editable installation (for development)
-pip install -e .
+cd DataFlow-CV && pip install .
 ```
 
-> 💡 **Tip**: When installed in editable mode, use `python -m dataflow.cli` instead of the `dataflow-cv` command.
-
-### Optional Dependencies
-
-| Dependency | Purpose | Install |
-|-----------|---------|---------|
-| `pycocotools` | COCO RLE segmentation + evaluation | `pip install pycocotools` |
-
 ---
 
 ## 🚀 Quick Start
@@ -127,89 +97,70 @@ dataflow-cv visualize coco images/ coco_annotations.json --save visualized/
 dataflow-cv visualize yolo --verbose --no-display images/ yolo_labels/ classes.txt --save visualized/
 ```
 
-#### 📊 Evaluation
+<p align="center">
+  <img src="assets/showcase/seg_demo_1.jpg" width="45%" alt="Segmentation visualization demo 1">
+  <img src="assets/showcase/seg_demo_2.jpg" width="45%" alt="Segmentation visualization demo 2">
+</p>
 
-Evaluate object detection and instance segmentation model outputs using COCO-standard metrics. Two COCO-format JSON files are required:
+#### 📊 Evaluation
 
-| File | Role | Format | Source |
-|------|------|--------|--------|
-| **`anno.json`** | Ground Truth (GT) — reference annotations | Full COCO dict (`images`, `annotations`, `categories`) | `yolo2coco` (label mode) |
-| **`pred.json`** | Detection (DT) — model predictions | Plain JSON list of annotation dicts (with `score`) | `yolo2coco --prediction`, Detectron2, MMDetection |
+Evaluate object detection and instance segmentation models with COCO-standard metrics. Two COCO-format JSON files are required:
 
-##### ① Preparing Evaluation Data
+| 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` |
 
-If your annotations and predictions are in YOLO format, convert them to COCO JSON first:
+##### ① Prepare Data
 
 ```bash
-# Step 1: YOLO ground truth labels → COCO GT (anno.json)
-#   Label format:   class_id cx cy w h               ← 5 tokens (detection)
-#                   class_id x1 y1 ... xn yn          ← odd tokens (segmentation)
+# GT: YOLO labels → COCO
 dataflow-cv convert yolo2coco images/ yolo_labels/ classes.txt anno.json
 
-# Step 2: YOLO predictions → COCO DT (pred.json)
-#   Prediction fmt: class_id cx cy w h confidence     ← 6 tokens (detection)
-#                   class_id x1 y1 ... xn yn confidence ← even tokens (segmentation)
+# DT: YOLO predictions → COCO (add --prediction for model output)
 dataflow-cv convert yolo2coco --prediction images/ yolo_preds/ classes.txt pred.json
 ```
 
-> ⚠️ **Important**: YOLO label files (GT) use **odd** token counts, while prediction files (DT) use **even** token counts with a trailing `confidence`. The `--prediction` flag is required for DT — it outputs a **plain JSON list** of annotation dicts (not a full COCO dict with `images`/`categories`). Mixed label/prediction files in the same directory are not supported.
->
-> ℹ️ **Note**: The `--prediction` flag is **only available for `yolo2coco`**. `labelme2coco` does not support prediction conversion — LabelMe files (.json) have no label vs prediction format distinction, so there is no equivalent prediction source format to convert from.
-
-##### ② Detection vs Segmentation — Format Requirements
-
-| Field | Detection GT | Detection DT | Segmentation GT | Segmentation DT |
-|-------|:-----------:|:-----------:|:---------------:|:---------------:|
-| `bbox` | ✅ Required | ✅ Required | ✅ Required (for area) | ✅ Required (for area) |
-| `score` | — | ✅ **Required** | — | ✅ **Required** |
-| `segmentation` | ❌ Not required | ❌ Not required | ✅ **Required** | ✅ **Required** |
-| `area` | ⚪ Recommended | ⚪ Recommended | ✅ **Required** | ✅ **Required** |
-| `iscrowd` | ⚪ Optional | — | ⚪ Optional | — |
-
-- **Object Detection** (`iouType='bbox'`): Bounding box overlap evaluation. Only `bbox` + `score` mandatory in DT.
-- **Instance Segmentation** (`iouType='segm'`): Mask overlap evaluation. GT and DT must include `segmentation` (polygon or RLE), `area`, and `bbox`.
+> ⚠️ `--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).
 
-##### ③ CLI Commands
+##### ② Run Evaluation
 
 ```bash
-# Object detection evaluation (bbox IoU)
+# 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
 
-# Verbose per-class breakdown
-dataflow-cv evaluate detection --verbose anno.json pred.json
-
-# With P/R/F1 at IoU=0.5 (default: macro averaging)
-dataflow-cv evaluate detection --prf1 --prf1-iou 0.5 anno.json pred.json
-
-# With P/R/F1 using micro averaging
-dataflow-cv evaluate detection --prf1 --prf1-method micro anno.json pred.json
-
-# Instance segmentation evaluation (mask IoU)
+# 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
 ```
 
-##### ④ End-to-End Workflow
+##### ③ Detection vs Segmentation
 
-```bash
-# Complete pipeline: YOLO → COCO → Evaluation
-dataflow-cv convert yolo2coco images/ yolo_labels/ classes.txt anno.json
-dataflow-cv convert yolo2coco --prediction images/ yolo_preds/ classes.txt pred.json
-dataflow-cv evaluate detection --verbose --prf1 anno.json pred.json
-```
+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.
 
 ### 🐍 Python API
 
 ```python
+from dataflow.util.logging import LogConfig
 from dataflow.convert import YoloAndCocoConverter
 from dataflow.visualize import YOLOVisualizer
 from dataflow.evaluate import DetectionEvaluator, compute_pr_f1
 
 # ── Convert ──────────────────────────────────────────
 # YOLO labels → COCO (label mode)
-converter = YoloAndCocoConverter(source_to_target=True, verbose=True, strict_mode=True)
+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/",
@@ -226,12 +177,12 @@ result = converter.convert(
 visualizer = YOLOVisualizer(
     label_dir="yolo_labels/", image_dir="images/",
     class_file="classes.txt", is_show=True, is_save=True,
-    output_dir="visualized/", verbose=True, strict_mode=True,
+    output_dir="visualized/", log_config=log_cfg,
 )
 result = visualizer.visualize()
 
 # ── Evaluate ─────────────────────────────────────────
-evaluator = DetectionEvaluator(verbose=True)
+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}")
 
@@ -248,7 +199,7 @@ 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/visualize/` (YOLO, LabelMe, COCO demos), `samples/convert/` (conversion examples).
+> 📂 See the `samples/` directory for complete examples: `samples/convert/` (6 conversion directions), `samples/visualize/` (YOLO, LabelMe, COCO), `samples/evaluate/` (detection & segmentation), `samples/cli/` (CLI workflows).
 
 ---
 
@@ -264,15 +215,13 @@ print(f"Segm F1: {prf1.overall.f1_score:.3f}")
 
 ### 💡 Key Concepts
 
-- **Format-Native Coordinates**: Coordinates stored in each format's native representation — YOLO normalized [0,1] center-based, LabelMe/COCO absolute pixels top-left. Check `DatasetAnnotations.format` to determine semantics.
-- **Explicit Coordinate Transforms**: Converters handle all coordinate transformations between formats — no hidden normalization.
-- **Strict Mode**: Validation errors raise exceptions by default. Disable with `--no-strict` (CLI) or `strict_mode=False` (API).
-- **Verbose Logging**: Detailed debug logs saved to files when `--verbose` is used. The CLI prints the log file path after each operation.
-- **Headless Support**: Use `--no-display` for servers/Docker; pair with `--save` to output visualization images without a window.
-- **Keyboard Shortcuts**: During visualization — `q`/`ESC` to exit, `Enter`/`Space` to advance, any other key to continue.
-- **Color Management**: Each class ID gets a unique color from an HSV-based palette (up to 1000 classes) for consistent visualization.
-- **Evaluation Metrics**: COCO-standard 12-metric output with optional per-class breakdown. P/R/F1 supports both macro (default) and micro averaging, and both bbox and mask IoU.
-- **Prediction Files**: YOLO prediction files use 6 tokens (detection) or even tokens (segmentation) vs 5/odd for labels. `--prediction` outputs a plain JSON list of annotation dicts — the standard prediction exchange format compatible with pycocotools `loadRes()`.
+- **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): `q` / `ESC` to exit, `Enter` / `Space` to advance, any other key to continue.
+- **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()`.
 
 ---
 
@@ -282,7 +231,7 @@ For detailed developer guidance including advanced test commands, debugging, and
 
 ### 🧪 Testing
 
-**405 tests, 76% code coverage (3986 statements).**
+**418 tests, 76% code coverage (3986 statements).**
 
 ```bash
 pytest                                    # All tests
@@ -301,7 +250,7 @@ pytest tests/evaluate/test_evaluator.py     # Single module
 | `dataflow/visualize/` | 81% | yolo_vis (100%), labelme_vis (100%), coco_vis (97%), base (74%) |
 | `dataflow/evaluate/` | 87% | evaluator (100%), metrics (93%), result (99%), base (91%), utils (68%) |
 | `dataflow/cli/` | 59% | main (96%), convert cmd (48%), evaluate cmd (24%), visualize cmd (84%), utils (86%) |
-| `dataflow/util/` | 93% | logging (98%), file_util (84%) |
+| `dataflow/util/` | 93% | logging (98%) |
 
 </details>
 
@@ -332,12 +281,12 @@ pre-commit run --all-files    # Manual run against all files
 ```
 dataflow/
 ├── label/           # Annotation handlers + data models
-├── convert/         # Format converters + RLE utility
-├── visualize/       # OpenCV-based rendering
-├── evaluate/        # pycocotools-based metrics
-├── util/            # Logging & file utilities
+├── 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
+tests/               # Unit & integration tests (418 tests, conftest fixtures)
 samples/             # Python API usage examples
 assets/              # Test data (det/seg by format)
 specs/               # Canonical specifications (evaluate/ + formats/ + modules/)

{dataflow_cv-1.3.0 → dataflow_cv-1.5.0}/dataflow/__init__.py

@@ -1,4 +1,4 @@
 """DataFlow-CV: A computer vision dataset processing library."""
 
-__version__ = "1.3.0"
+__version__ = "1.5.0"
 __author__ = "DataFlow-CV Team"