dataflow-cv 1.2.0__tar.gz → 1.4.0__tar.gz

{dataflow_cv-1.2.0/dataflow_cv.egg-info → dataflow_cv-1.4.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: dataflow-cv
-Version: 1.2.0
+Version: 1.4.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 with confidence scores |
-| 🎯 **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 |
-| 💻 **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
@@ -146,7 +112,7 @@ dataflow-cv convert coco2yolo input.json yolo_labels/
 # COCO → LabelMe
 dataflow-cv convert coco2labelme input.json labelme_json/
 
-# YOLO predictions → COCO (with confidence scores)
+# YOLO predictions → COCO (output: plain JSON list — prediction format)
 dataflow-cv convert yolo2coco --prediction images/ yolo_preds/ classes.txt pred.json
 
 # Options
@@ -174,10 +140,10 @@ dataflow-cv visualize yolo --verbose --no-display images/ yolo_labels/ classes.t
 
 Evaluate object detection and instance segmentation model outputs using COCO-standard metrics. Two COCO-format JSON files are required:
 
-| File | Role | Source |
-|------|------|--------|
-| **`anno.json`** | Ground Truth (GT) — reference annotations | `yolo2coco` (label mode) |
-| **`pred.json`** | Detection (DT) — model predictions with `score` | `yolo2coco --prediction` |
+| 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 |
 
 ##### ① Preparing Evaluation Data
 
@@ -195,7 +161,9 @@ dataflow-cv convert yolo2coco images/ yolo_labels/ classes.txt anno.json
 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 preserves confidence as the COCO `score` field. Mixed label/prediction files in the same directory are not supported.
+> ⚠️ **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
 
@@ -219,8 +187,11 @@ dataflow-cv evaluate detection 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
-dataflow-cv evaluate detection --prf1 --prf1-iou 0.5 anno.json pred.json
+# P/R/F1 only (skips mAP computation) — default: macro averaging
+dataflow-cv evaluate detection --prf1 anno.json pred.json
+
+# P/R/F1 with custom IoU threshold and micro averaging
+dataflow-cv evaluate detection --prf1 --prf1-iou 0.75 --prf1-method micro anno.json pred.json
 
 # Instance segmentation evaluation (mask IoU)
 dataflow-cv evaluate segmentation anno.json pred.json
@@ -235,19 +206,22 @@ dataflow-cv evaluate detection --output results.json anno.json pred.json
 # 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
+dataflow-cv evaluate detection --verbose anno.json pred.json           # mAP
+dataflow-cv evaluate detection --prf1 anno.json pred.json             # P/R/F1
 ```
 
 ### 🐍 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/",
@@ -264,21 +238,29 @@ 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}")
 
-# Quick P/R/F1 at IoU=0.5
+# 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"F1: {prf1.overall.f1_score:.3f}")
+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/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).
 
 ---
 
@@ -294,15 +276,13 @@ print(f"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 and P/R/F1 computation.
-- **Prediction Files**: YOLO prediction files (6 tokens detection, even tokens segmentation) differ from label files (5/odd tokens). Use `--prediction` flag.
+- **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()`.
 
 ---
 
@@ -312,7 +292,7 @@ For detailed developer guidance including advanced test commands, debugging, and
 
 ### 🧪 Testing
 
-**370 tests, 75% code coverage.**
+**418 tests, 76% code coverage (3986 statements).**
 
 ```bash
 pytest                                    # All tests
@@ -326,12 +306,12 @@ pytest tests/evaluate/test_evaluator.py     # Single module
 
 | Module | Coverage | Highlights |
 |--------|:--------:|------------|
-| `dataflow/label/` | 68% | models (87%), coco_handler (74%), labelme_handler (72%), yolo_handler (57%) |
-| `dataflow/convert/` | 84% | yolo_and_coco (89%), labelme_and_yolo (93%), coco_and_labelme (88%), rle (81%) |
-| `dataflow/visualize/` | 81% | yolo_vis (97%), labelme_vis (100%), coco_vis (97%), base (80%) |
-| `dataflow/evaluate/` | 88% | evaluator (100%), metrics (96%), result (99%), base (91%), utils (69%) |
+| `dataflow/label/` | 68% | models (87%), coco_handler (75%), labelme_handler (70%), yolo_handler (58%) |
+| `dataflow/convert/` | 87% | yolo_and_coco (90%), labelme_and_yolo (86%), coco_and_labelme (87%), rle (80%), base (83%), utils (92%) |
+| `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 (99%), file_util (84%) |
+| `dataflow/util/` | 93% | logging (98%) |
 
 </details>
 
@@ -362,12 +342,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.2.0 → dataflow_cv-1.4.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 with confidence scores |
-| 🎯 **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 |
-| 💻 **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
@@ -103,7 +73,7 @@ dataflow-cv convert coco2yolo input.json yolo_labels/
 # COCO → LabelMe
 dataflow-cv convert coco2labelme input.json labelme_json/
 
-# YOLO predictions → COCO (with confidence scores)
+# YOLO predictions → COCO (output: plain JSON list — prediction format)
 dataflow-cv convert yolo2coco --prediction images/ yolo_preds/ classes.txt pred.json
 
 # Options
@@ -131,10 +101,10 @@ dataflow-cv visualize yolo --verbose --no-display images/ yolo_labels/ classes.t
 
 Evaluate object detection and instance segmentation model outputs using COCO-standard metrics. Two COCO-format JSON files are required:
 
-| File | Role | Source |
-|------|------|--------|
-| **`anno.json`** | Ground Truth (GT) — reference annotations | `yolo2coco` (label mode) |
-| **`pred.json`** | Detection (DT) — model predictions with `score` | `yolo2coco --prediction` |
+| 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 |
 
 ##### ① Preparing Evaluation Data
 
@@ -152,7 +122,9 @@ dataflow-cv convert yolo2coco images/ yolo_labels/ classes.txt anno.json
 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 preserves confidence as the COCO `score` field. Mixed label/prediction files in the same directory are not supported.
+> ⚠️ **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
 
@@ -176,8 +148,11 @@ dataflow-cv evaluate detection 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
-dataflow-cv evaluate detection --prf1 --prf1-iou 0.5 anno.json pred.json
+# P/R/F1 only (skips mAP computation) — default: macro averaging
+dataflow-cv evaluate detection --prf1 anno.json pred.json
+
+# P/R/F1 with custom IoU threshold and micro averaging
+dataflow-cv evaluate detection --prf1 --prf1-iou 0.75 --prf1-method micro anno.json pred.json
 
 # Instance segmentation evaluation (mask IoU)
 dataflow-cv evaluate segmentation anno.json pred.json
@@ -192,19 +167,22 @@ dataflow-cv evaluate detection --output results.json anno.json pred.json
 # 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
+dataflow-cv evaluate detection --verbose anno.json pred.json           # mAP
+dataflow-cv evaluate detection --prf1 anno.json pred.json             # P/R/F1
 ```
 
 ### 🐍 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/",
@@ -221,21 +199,29 @@ 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}")
 
-# Quick P/R/F1 at IoU=0.5
+# 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"F1: {prf1.overall.f1_score:.3f}")
+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/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).
 
 ---
 
@@ -251,15 +237,13 @@ print(f"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 and P/R/F1 computation.
-- **Prediction Files**: YOLO prediction files (6 tokens detection, even tokens segmentation) differ from label files (5/odd tokens). Use `--prediction` flag.
+- **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()`.
 
 ---
 
@@ -269,7 +253,7 @@ For detailed developer guidance including advanced test commands, debugging, and
 
 ### 🧪 Testing
 
-**370 tests, 75% code coverage.**
+**418 tests, 76% code coverage (3986 statements).**
 
 ```bash
 pytest                                    # All tests
@@ -283,12 +267,12 @@ pytest tests/evaluate/test_evaluator.py     # Single module
 
 | Module | Coverage | Highlights |
 |--------|:--------:|------------|
-| `dataflow/label/` | 68% | models (87%), coco_handler (74%), labelme_handler (72%), yolo_handler (57%) |
-| `dataflow/convert/` | 84% | yolo_and_coco (89%), labelme_and_yolo (93%), coco_and_labelme (88%), rle (81%) |
-| `dataflow/visualize/` | 81% | yolo_vis (97%), labelme_vis (100%), coco_vis (97%), base (80%) |
-| `dataflow/evaluate/` | 88% | evaluator (100%), metrics (96%), result (99%), base (91%), utils (69%) |
+| `dataflow/label/` | 68% | models (87%), coco_handler (75%), labelme_handler (70%), yolo_handler (58%) |
+| `dataflow/convert/` | 87% | yolo_and_coco (90%), labelme_and_yolo (86%), coco_and_labelme (87%), rle (80%), base (83%), utils (92%) |
+| `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 (99%), file_util (84%) |
+| `dataflow/util/` | 93% | logging (98%) |
 
 </details>
 
@@ -319,12 +303,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.2.0 → dataflow_cv-1.4.0}/dataflow/__init__.py

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