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

{dataflow_cv-1.2.0 → dataflow_cv-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dataflow-cv
-Version: 1.2.0
+Version: 1.3.0
 Summary: A computer vision dataset processing library
 Author-email: DataFlow-CV Team <example@example.com>
 License: MIT
@@ -73,10 +73,10 @@ graph LR
 
 | | | |
 |:---|:---|:---|
-| 🔄 **Format Conversion** | Convert between YOLO, LabelMe, and COCO in any direction — 6 conversion paths, plus prediction file support with confidence scores |
+| 🔄 **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 |
+| 📊 **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` |
@@ -146,7 +146,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 +174,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 +195,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,9 +221,12 @@ 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
+# 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)
 dataflow-cv evaluate segmentation anno.json pred.json
 
@@ -273,9 +278,17 @@ evaluator = DetectionEvaluator(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).
@@ -301,8 +314,8 @@ print(f"F1: {prf1.overall.f1_score:.3f}")
 - **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.
+- **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()`.
 
 ---
 
@@ -312,7 +325,7 @@ For detailed developer guidance including advanced test commands, debugging, and
 
 ### 🧪 Testing
 
-**370 tests, 75% code coverage.**
+**405 tests, 76% code coverage (3986 statements).**
 
 ```bash
 pytest                                    # All tests
@@ -326,12 +339,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%), file_util (84%) |
 
 </details>
 

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

@@ -30,10 +30,10 @@ graph LR
 
 | | | |
 |:---|:---|:---|
-| 🔄 **Format Conversion** | Convert between YOLO, LabelMe, and COCO in any direction — 6 conversion paths, plus prediction file support with confidence scores |
+| 🔄 **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 |
+| 📊 **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` |
@@ -103,7 +103,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 +131,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 +152,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,9 +178,12 @@ 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
+# 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)
 dataflow-cv evaluate segmentation anno.json pred.json
 
@@ -230,9 +235,17 @@ evaluator = DetectionEvaluator(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).
@@ -258,8 +271,8 @@ print(f"F1: {prf1.overall.f1_score:.3f}")
 - **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.
+- **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()`.
 
 ---
 
@@ -269,7 +282,7 @@ For detailed developer guidance including advanced test commands, debugging, and
 
 ### 🧪 Testing
 
-**370 tests, 75% code coverage.**
+**405 tests, 76% code coverage (3986 statements).**
 
 ```bash
 pytest                                    # All tests
@@ -283,12 +296,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%), file_util (84%) |
 
 </details>
 

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

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

{dataflow_cv-1.2.0 → dataflow_cv-1.3.0}/dataflow/cli/commands/convert.py

@@ -28,8 +28,9 @@ def convert_group():
 @click.option(
     "--prediction",
     is_flag=True,
-    help="Treat input as prediction format (with confidence scores). "
-         "Output COCO JSON will include 'score' fields.",
+    help="Treat input as prediction format (YOLO: 6 tokens for detection, "
+         "even tokens for segmentation). Output COCO as plain JSON list of "
+         "annotation dicts (prediction format, Variant B).",
 )
 def yolo2coco(
     ctx,

{dataflow_cv-1.2.0 → dataflow_cv-1.3.0}/dataflow/cli/commands/evaluate.py

@@ -48,6 +48,13 @@ def add_evaluate_options(func):
         show_default=True,
         help="Confidence threshold for P/R/F1 calculation",
     )
+    @click.option(
+        "--prf1-method",
+        type=click.Choice(["macro", "micro"], case_sensitive=False),
+        default="macro",
+        show_default=True,
+        help="Aggregation method for overall P/R/F1",
+    )
     @click.option(
         "--output",
         "-o",
@@ -98,7 +105,7 @@ def evaluate_group():
     "dt_json",
     type=click.Path(exists=True, path_type=Path),
 )
-def detection(ctx, gt_json, dt_json, verbose, prf1, prf1_iou, prf1_conf, output):
+def detection(ctx, gt_json, dt_json, verbose, prf1, prf1_iou, prf1_conf, prf1_method, output):
     """Evaluate object detection results (bbox IoU).
 
     GT_JSON: COCO format Ground Truth JSON file.
@@ -140,7 +147,7 @@ def detection(ctx, gt_json, dt_json, verbose, prf1, prf1_iou, prf1_conf, output)
 
     # Print results
     if result.success and result.metrics is not None:
-        _print_detection_result(result, verbose, prf1, prf1_iou, prf1_conf, gt_json, dt_json, logger)
+        _print_detection_result(result, verbose, prf1, prf1_iou, prf1_conf, prf1_method, gt_json, dt_json, logger)
 
         if output:
             _save_result_json(result, output)
@@ -171,7 +178,7 @@ def detection(ctx, gt_json, dt_json, verbose, prf1, prf1_iou, prf1_conf, output)
     "dt_json",
     type=click.Path(exists=True, path_type=Path),
 )
-def segmentation(ctx, gt_json, dt_json, verbose, prf1, prf1_iou, prf1_conf, output):
+def segmentation(ctx, gt_json, dt_json, verbose, prf1, prf1_iou, prf1_conf, prf1_method, output):
     """Evaluate instance segmentation results (mask IoU).
 
     GT_JSON: COCO format Ground Truth JSON file (annotations must include 'segmentation').
@@ -213,7 +220,7 @@ def segmentation(ctx, gt_json, dt_json, verbose, prf1, prf1_iou, prf1_conf, outp
 
     # Print results
     if result.success and result.metrics is not None:
-        _print_segmentation_result(result, verbose, prf1, prf1_iou, prf1_conf, gt_json, dt_json, logger)
+        _print_segmentation_result(result, verbose, prf1, prf1_iou, prf1_conf, prf1_method, gt_json, dt_json, logger)
 
         if output:
             _save_result_json(result, output)
@@ -234,7 +241,7 @@ def segmentation(ctx, gt_json, dt_json, verbose, prf1, prf1_iou, prf1_conf, outp
 # Output helpers
 # ---------------------------------------------------------------------------
 
-def _print_detection_result(result, verbose, prf1, prf1_iou, prf1_conf, gt_json, dt_json, logger):
+def _print_detection_result(result, verbose, prf1, prf1_iou, prf1_conf, prf1_method, gt_json, dt_json, logger):
     """Print detection evaluation results."""
     from dataflow.evaluate.utils import format_metric_table, format_per_class_table, format_prf1_output
 
@@ -262,12 +269,14 @@ def _print_detection_result(result, verbose, prf1, prf1_iou, prf1_conf, gt_json,
             str(gt_json), str(dt_json),
             iou_threshold=prf1_iou,
             confidence_threshold=prf1_conf,
-            iou_type="bbox", verbose=verbose, logger=logger,
+            iou_type="bbox",
+            method=prf1_method,
+            verbose=verbose, logger=logger,
         )
         click.echo(format_prf1_output(prf1_result))
 
 
-def _print_segmentation_result(result, verbose, prf1, prf1_iou, prf1_conf, gt_json, dt_json, logger):
+def _print_segmentation_result(result, verbose, prf1, prf1_iou, prf1_conf, prf1_method, gt_json, dt_json, logger):
     """Print segmentation evaluation results."""
     from dataflow.evaluate.utils import format_metric_table, format_per_class_table, format_prf1_output
 
@@ -291,22 +300,14 @@ def _print_segmentation_result(result, verbose, prf1, prf1_iou, prf1_conf, gt_js
     if prf1:
         from dataflow.evaluate import compute_pr_f1
         click.echo()
-        # Manual mask IoU not yet supported — fallback to bbox
-        try:
-            prf1_result = compute_pr_f1(
-                str(gt_json), str(dt_json),
-                iou_threshold=prf1_iou,
-                confidence_threshold=prf1_conf,
-                iou_type="segm", verbose=verbose, logger=logger,
-            )
-        except NotImplementedError:
-            logger.warning("Mask IoU P/R/F1 not yet supported in manual matching. Falling back to bbox IoU.")
-            prf1_result = compute_pr_f1(
-                str(gt_json), str(dt_json),
-                iou_threshold=prf1_iou,
-                confidence_threshold=prf1_conf,
-                iou_type="bbox", verbose=verbose, logger=logger,
-            )
+        prf1_result = compute_pr_f1(
+            str(gt_json), str(dt_json),
+            iou_threshold=prf1_iou,
+            confidence_threshold=prf1_conf,
+            iou_type="segm",
+            method=prf1_method,
+            verbose=verbose, logger=logger,
+        )
         click.echo(format_prf1_output(prf1_result))
 
 

{dataflow_cv-1.2.0 → dataflow_cv-1.3.0}/dataflow/convert/base.py

@@ -200,6 +200,10 @@ class BaseConverter(ABC):
             target_path=target_path,
         )
 
+        # Store source_path for subclasses that need it in
+        # create_target_handler() (e.g., image copying in LabelMe→YOLO)
+        self._source_path = source_path
+
         num_images = 0
         num_objects = 0
 
@@ -267,48 +271,56 @@ class BaseConverter(ABC):
         return result
 
     def convert(self, source_path: str, target_path: str, **kwargs) -> ConversionResult:
-        """
-        Convert annotations from source format to target format (enhanced with verbose logging).
+        """Convert annotations from source format to target format.
+
+        Auto-dispatches to the correct pipeline based on target format:
+        - COCO target (single JSON) → batch pipeline (``_batch_convert()``)
+        - YOLO / LabelMe target (per-file output) → streaming pipeline
+          (``stream_convert()``)
+
+        Subclasses should NOT override this method. Instead, override the
+        abstract hooks: ``create_source_handler()``, ``create_target_handler()``,
+        ``_convert_single_image()``, ``convert_annotations()``, and optionally
+        ``_post_batch_convert()``.
 
         Args:
-            source_path: Path to source annotations
-            target_path: Path for target annotations
-            **kwargs: Additional conversion parameters
+            source_path: Path to source annotations.
+            target_path: Path for target annotations.
+            **kwargs: Additional conversion parameters.
 
         Returns:
-            ConversionResult containing conversion status and details
+            ConversionResult containing conversion status and details.
         """
-        start_time = datetime.datetime.now()
-        self.conversion_stats["start_time"] = start_time
+        if self.target_format == "coco":
+            return self._batch_convert(source_path, target_path, **kwargs)
+        else:
+            return self.stream_convert(source_path, target_path, **kwargs)
 
-        # Log start information
-        if self.verbose:
-            self.logger.debug(f"Starting conversion: {source_path} -> {target_path}")
-            self.logger.debug(f"Conversion parameters: {kwargs}")
+    def _batch_convert(
+        self, source_path: str, target_path: str, **kwargs
+    ) -> ConversionResult:
+        """Batch pipeline: read ALL → convert ALL → write ALL.
 
-        # 1. Validate input parameters
+        Used when the target format is a single file (COCO JSON).
+        Subclasses should NOT override this — override the abstract
+        hooks and the optional ``_post_batch_convert()`` hook instead.
+        """
+        self._source_annotations_for_target = None
+
+        # 1. Validate inputs
         if not self.validate_inputs(source_path, target_path, kwargs):
-            if self.verbose:
-                self.logger.error("Input parameter validation failed")
             return self._create_conversion_result(
                 success=False,
                 source_path=source_path,
                 target_path=target_path,
-                errors=["Input parameter validation failed"],
+                errors=["Input validation failed"],
                 log_file_path=self.log_file_path,
             )
 
-        # 2. Use source handler to read data
+        # 2. Read data using source handler
         source_handler = self.create_source_handler(source_path, kwargs)
-        if self.verbose:
-            self.logger.debug(
-                f"Created source handler: {source_handler.__class__.__name__}"
-            )
-
         read_result = source_handler.read()
         if not read_result.success:
-            if self.verbose:
-                self.logger.error(f"Failed to read source data: {read_result.errors}")
             return self._create_conversion_result(
                 success=False,
                 source_path=source_path,
@@ -317,34 +329,33 @@ class BaseConverter(ABC):
                 log_file_path=self.log_file_path,
             )
 
-        # Record read results
+        # 3. Convert data
         annotations = read_result.data
         if self.verbose:
-            self.logger.info(f"Read annotations for {annotations.num_images} images")
+            self.logger.info(
+                f"Read annotations for {annotations.num_images} images"
+            )
             self.logger.debug(f"Category count: {len(annotations.categories)}")
 
-        # 3. Convert data (format-specific conversion)
-        if self.verbose:
-            self.logger.debug("Starting format-specific conversion")
-
         converted_annotations = self.convert_annotations(annotations, kwargs)
-        self.conversion_stats["objects_converted"] = converted_annotations.num_objects
 
         if self.verbose:
             self.logger.debug(
-                f"Conversion completed, object count: {converted_annotations.num_objects}"
+                f"Conversion completed, object count: "
+                f"{converted_annotations.num_objects}"
             )
 
-        # 4. Use target handler to write data
-        target_handler = self.create_target_handler(target_path, kwargs)
-        if self.verbose:
-            self.logger.debug(
-                f"Created target handler: {target_handler.__class__.__name__}"
+        # 4. Write data (with state cleanup guarantee)
+        self._source_annotations_for_target = converted_annotations
+        try:
+            target_handler = self.create_target_handler(target_path, kwargs)
+            write_result = target_handler.write(
+                converted_annotations, target_path
             )
+        finally:
+            self._source_annotations_for_target = None
 
-        write_result = target_handler.write(converted_annotations, target_path)
-
-        # 5. Create result
+        # 5. Build result
         result = self._create_conversion_result(
             success=write_result.success,
             source_path=source_path,
@@ -354,32 +365,37 @@ class BaseConverter(ABC):
             log_file_path=self.log_file_path,
         )
 
-        # Add verbose log entries
         if self.verbose:
-            result.add_verbose_log(f"Source format: {self.source_format}")
-            result.add_verbose_log(f"Target format: {self.target_format}")
-            result.add_verbose_log(f"Source path: {source_path}")
-            result.add_verbose_log(f"Target path: {target_path}")
-            result.add_verbose_log(f"Images processed: {annotations.num_images}")
             result.add_verbose_log(
-                f"Objects converted: {converted_annotations.num_objects}"
-            )
-
-            if write_result.warnings:
-                for warning in write_result.warnings:
-                    result.add_verbose_log(f"Warning: {warning}")
-
-            # Record conversion statistics
-            self.conversion_stats["end_time"] = datetime.datetime.now()
-            duration = (
-                self.conversion_stats["end_time"] - self.conversion_stats["start_time"]
+                f"Images processed: {annotations.num_images}"
             )
             result.add_verbose_log(
-                f"Total duration: {duration.total_seconds():.2f} seconds"
+                f"Objects converted: {converted_annotations.num_objects}"
             )
+            if write_result.errors:
+                for error in write_result.errors:
+                    result.add_verbose_log(f"Error: {error}")
+
+        # 6. Post-processing hook (e.g., RLE warnings)
+        self._post_batch_convert(result, source_handler, kwargs)
 
         return result
 
+    def _post_batch_convert(
+        self,
+        result: ConversionResult,
+        source_handler: BaseAnnotationHandler,
+        kwargs: Dict,
+    ) -> None:
+        """Optional post-processing hook for batch conversions.
+
+        Called after a successful batch write. Subclasses override this
+        to add format-specific warnings or metadata (e.g., RLE accuracy
+        warnings).
+
+        Default: no-op.
+        """
+
     def validate_inputs(self, source_path: str, target_path: str, kwargs: Dict) -> bool:
         """
         Validate conversion input parameters.
@@ -442,19 +458,38 @@ class BaseConverter(ABC):
     def convert_annotations(
         self, source_annotations: DatasetAnnotations, kwargs: Dict
     ) -> DatasetAnnotations:
-        """
-        Convert annotation data (format-specific conversion).
+        """Convert annotation data (format-specific transformation).
+
+        Subclasses MUST override this to implement the coordinate
+        transformation for their conversion direction.  There is no
+        safe pass-through default because coordinate semantics differ
+        between formats.
+
+        The canonical implementation delegates to
+        ``_convert_single_image()`` per image:
+
+        .. code-block:: python
+
+            target = DatasetAnnotations(format=target_format)
+            target.categories = source_annotations.categories.copy()
+            for img in source_annotations.images:
+                target.add_image(self._convert_single_image(img, **kwargs))
+            return target
 
         Args:
-            source_annotations: Annotations read from source format
-            kwargs: Additional conversion parameters
+            source_annotations: Annotations in source-native coordinates.
+            kwargs: Additional conversion parameters.
 
         Returns:
-            Converted DatasetAnnotations ready for writing to target format
+            Converted DatasetAnnotations in target-native coordinates.
+
+        Raises:
+            NotImplementedError: Always — subclasses must implement.
         """
-        # Default implementation: return as-is (assuming categories and data are already correct)
-        # Subclasses should override for format-specific conversions like category mapping
-        return source_annotations
+        raise NotImplementedError(
+            "Subclass must implement convert_annotations() "
+            "for this conversion direction"
+        )
 
     def _create_conversion_result(
         self,
@@ -514,6 +549,6 @@ class BaseConverter(ABC):
 
     def _log_error(self, message: str):
         """Log error message, raise exception in strict mode."""
-        self.logger.error(message)
-        if self.strict_mode:
-            raise ValueError(message)
+        from dataflow.util.logging_util import logging_error_or_raise
+
+        logging_error_or_raise(message, self.logger, self.strict_mode)