dataflow-cv 0.6.2__tar.gz → 1.0.1__tar.gz

{dataflow_cv-0.6.2/dataflow_cv.egg-info → dataflow_cv-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dataflow-cv
-Version: 0.6.2
+Version: 1.0.1
 Summary: A computer vision dataset processing library
 Author-email: DataFlow-CV Team <example@example.com>
 License: MIT
@@ -49,17 +49,19 @@ Dynamic: license-file
 [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/) ![License](https://img.shields.io/badge/license-MIT-green) [![PyPI](https://img.shields.io/pypi/v/dataflow-cv.svg)](https://pypi.org/project/dataflow-cv/) ![Development Status](https://img.shields.io/badge/status-alpha-yellow) [![GitHub Actions](https://github.com/zjykzj/DataFlow-CV/actions/workflows/python-publish.yml/badge.svg)](https://github.com/zjykzj/DataFlow-CV/actions/workflows/python-publish.yml) 
 ![Linux](https://img.shields.io/badge/Linux-Supported-fcc624?logo=linux) ![Windows](https://img.shields.io/badge/Windows-Supported-00a2e8?logo=windows) ![macOS](https://img.shields.io/badge/macOS-Supported-999999?logo=apple)
 
-A computer vision dataset processing library for seamless format conversion and visualization between LabelMe, COCO, and YOLO annotation formats. Designed for researchers and developers working with multi-format annotation pipelines.
+A computer vision dataset processing library for seamless format conversion and visualization between YOLO, LabelMe, and COCO annotation formats. Designed for researchers and developers working with multi-format annotation pipelines.
 
 ## Features
 
-- **Bidirectional Conversion**: Convert between LabelMe, COCO, and YOLO formats in any direction
+- **Bidirectional Conversion**: Convert between YOLO, LabelMe, and COCO formats in any direction
 - **Multi-format Support**: Handle object detection bounding boxes and instance segmentation polygons
-- **Lossless Round-trip**: Preserve original coordinates through conversion chains
+- **Native Coordinate Storage**: Coordinates stored in format-native representation (YOLO normalized, LabelMe/COCO absolute pixels)
 - **Visualization**: Visualize annotations with OpenCV, supporting both display and save modes
 - **Command-line Interface**: User-friendly CLI with `convert` and `visualize` subcommands
 - **Python API**: Programmatic access for integration into larger pipelines
 - **Verbose Logging**: Detailed logging with file output for debugging
+- **Headless Mode**: Run visualization in server/Docker environments with `--no-display`
+- **Flexible Error Handling**: Choose between strict (abort on error) or lenient (skip and continue) modes
 - **Cross-platform**: Full support for Windows, Linux, and macOS
 
 ## Table of Contents
@@ -131,12 +133,6 @@ dataflow-cv convert yolo2coco images/ yolo_labels/ classes.txt coco_annotations.
 # YOLO to LabelMe
 dataflow-cv convert yolo2labelme images/ yolo_labels/ classes.txt labelme_json/
 
-# COCO to YOLO
-dataflow-cv convert coco2yolo coco_annotations.json yolo_labels/
-
-# COCO to LabelMe
-dataflow-cv convert coco2labelme coco_annotations.json labelme_json/
-
 # LabelMe to YOLO
 dataflow-cv convert labelme2yolo labelme_json/ classes.txt yolo_labels/
 
@@ -146,8 +142,17 @@ dataflow-cv convert labelme2coco labelme_json/ classes.txt coco_annotations.json
 # With RLE encoding
 dataflow-cv convert labelme2coco labelme_json/ classes.txt coco_annotations.json --do-rle
 
+# COCO to YOLO
+dataflow-cv convert coco2yolo coco_annotations.json yolo_labels/
+
+# COCO to LabelMe
+dataflow-cv convert coco2labelme coco_annotations.json labelme_json/
+
 # Enable verbose logging
 dataflow-cv convert yolo2coco images/ yolo_labels/ classes.txt coco_annotations.json --verbose
+
+# Disable strict mode (skip invalid annotations instead of aborting)
+dataflow-cv convert yolo2coco --no-strict images/ yolo_labels/ classes.txt coco_annotations.json
 ```
 
 #### Visualization
@@ -155,14 +160,17 @@ dataflow-cv convert yolo2coco images/ yolo_labels/ classes.txt coco_annotations.
 # Visualize YOLO annotations
 dataflow-cv visualize yolo images/ yolo_labels/ classes.txt --save visualized/
 
-# Visualize COCO annotations
-dataflow-cv visualize coco images/ coco_annotations.json --save visualized/
-
 # Visualize LabelMe annotations
 dataflow-cv visualize labelme images/ labelme_json/ --save visualized/
 
+# Visualize COCO annotations
+dataflow-cv visualize coco images/ coco_annotations.json --save visualized/
+
 # Enable verbose logging for detailed debug output
 dataflow-cv visualize yolo --verbose images/ yolo_labels/ classes.txt --save visualized/
+
+# Run on headless server (no display window)
+dataflow-cv visualize yolo --no-display images/ yolo_labels/ classes.txt --save visualized/
 ```
 
 ### Python API
@@ -203,37 +211,53 @@ See the `samples/` directory for complete examples:
 
 ## Documentation
 
-- **[CLAUDE.md](CLAUDE.md)**: Detailed architecture and development guide
-- **`docs/formats/`**: Format specifications (YOLO, COCO, LabelMe)
-- **`docs/specs/`**: Module specifications and design documents
-- **`CHANGELOG.md`**: Version history and breaking changes
+- **[CLAUDE.md](CLAUDE.md)**: Detailed architecture, development guide, and known gotchas
+- **[CHANGELOG.md](CHANGELOG.md)**: Version history and breaking changes
+- **[specs/](specs/)**: Canonical specifications organized into two layers:
+  - **`formats/`** — External format contracts (YOLO, LabelMe, COCO) and conversion rules
+  - **`modules/`** — Internal module architecture, interface contracts, and dependency constraints
 
 ### Key Concepts
 
-- **Normalized Coordinates**: All internal coordinates are in 0-1 range
-- **Original Data Preservation**: Lossless round-trip conversion through `OriginalData` system
-- **Strict Mode**: Validation errors raise exceptions (default: enabled in CLI, can be disabled via `strict_mode=False` parameter in Python API)
+- **Format-Native Coordinates**: Coordinates stored in each format's native representation — YOLO normalized [0,1] center-based, LabelMe/COCO absolute pixels top-left. See `DatasetAnnotations.format` to determine semantics
+- **Explicit Coordinate Transforms**: Converters handle all coordinate transformations between formats. No hidden normalization — lossy vs lossless behavior is explicitly documented
+- **Strict Mode**: Validation errors raise exceptions (default). Disable in CLI with `--no-strict`, or in Python API with `strict_mode=False`
 - **Verbose Logging**: Detailed debug logs saved to files when `--verbose` is used. The CLI prints "Verbose log saved to: <path>" after operations.
-- **Keyboard Shortcuts**: During visualization, press `q` or `ESC` to exit early; any other key continues
+- **Headless Support**: Use `--no-display` for servers/Docker; use `--save` to output visualization images without a window
+- **Keyboard Shortcuts**: During visualization, press `q` or `ESC` to exit early; `Enter`/`Space` to advance; any other key continues
 - **Missing Image Handling**: Missing images are skipped with warnings, allowing processing to continue
 - **RLE Mask Visualization**: COCO RLE masks are displayed with semi-transparent fills for better visibility
-- **Color Management**: Each class ID gets a unique color from a palette of 1000 distinct colors for consistent visualization
+- **Color Management**: Each class ID gets a unique color from an HSV-based palette for consistent visualization
+- **Specifications**: The `specs/` directory contains the canonical format and module specifications — the authoritative reference for expected behavior
 
 ## Development
 For detailed developer guidance including advanced test commands, debugging, and architecture overview, see [CLAUDE.md](CLAUDE.md).
 
 ### Testing
+
+289 tests, **73%** code coverage.
+
 ```bash
 # Run all tests
 pytest
 
-# Run tests with coverage
-pytest --cov=dataflow
+# Run tests with coverage report
+pytest --cov=dataflow --cov-report=term
 
 # Run specific test module
 pytest tests/convert/test_yolo_and_coco.py
 ```
 
+**Coverage by module:**
+
+| Module | Coverage | Notes |
+|--------|----------|-------|
+| `dataflow/label/` | 78% | Core data models (66%), handlers (67-82%) |
+| `dataflow/convert/` | 83% | Converters (81-92%), base pipeline (62%) |
+| `dataflow/visualize/` | 69% | Visualizers (94-100%), base drawing (79%) |
+| `dataflow/cli/` | 76% | CLI commands (47-96%), utils (86%) |
+| `dataflow/util/` | 87% | File ops (84%), logging (99%) |
+
 ### Linting and Formatting
 ```bash
 # Install development dependencies
@@ -252,17 +276,39 @@ mypy dataflow
 flake8 dataflow tests samples
 ```
 
+### Pre-commit Hooks (Optional)
+
+Automatically check code quality before each commit:
+
+```bash
+# Install pre-commit
+pip install pre-commit
+
+# Install git hooks (run once)
+pre-commit install
+
+# After this, every `git commit` will auto-run:
+#   black (code formatting)
+#   isort (import sorting)
+#   flake8 (linting)
+#   trailing-whitespace / end-of-file-fixer / check-yaml / check-toml
+
+# Manually run against all files
+pre-commit run --all-files
+```
+
 ### Project Structure
 ```
 dataflow/
-├── label/           # Annotation handlers (YOLO, LabelMe, COCO)
-├── convert/         # Format converters
-├── visualize/       # Visualization modules
-├── util/           # Utilities (logging, file operations)
-└── cli/            # Command-line interface
-tests/              # Comprehensive test suite
-samples/            # Usage examples
-assets/             # Sample data for testing
+├── label/           # Annotation handlers + data models (YOLO, LabelMe, COCO)
+├── convert/         # Format converters + RLE conversion utility
+├── visualize/       # Visualization modules (OpenCV-based)
+├── util/            # Logging and file operation utilities
+└── cli/             # CLI entry point, commands, and validation
+tests/               # Unit and integration tests (label, convert, visualize, cli, util)
+samples/             # Python API usage examples (visualize, convert, label, cli)
+assets/              # Test data organized by format (det/seg) and annotation type
+specs/               # Canonical specifications (formats/ + modules/ layers)
 ```
 
 ## Contributing
@@ -284,6 +330,6 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## Acknowledgments
 
-- Thanks to the creators of LabelMe, COCO, and YOLO formats for establishing these annotation standards
+- Thanks to the creators of YOLO, LabelMe, and COCO formats for establishing these annotation standards
 - Built with OpenCV, NumPy, and Click
 - Inspired by the need for seamless format conversion in multi-tool CV pipelines

{dataflow_cv-0.6.2 → dataflow_cv-1.0.1}/README.md

@@ -6,17 +6,19 @@
 [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/) ![License](https://img.shields.io/badge/license-MIT-green) [![PyPI](https://img.shields.io/pypi/v/dataflow-cv.svg)](https://pypi.org/project/dataflow-cv/) ![Development Status](https://img.shields.io/badge/status-alpha-yellow) [![GitHub Actions](https://github.com/zjykzj/DataFlow-CV/actions/workflows/python-publish.yml/badge.svg)](https://github.com/zjykzj/DataFlow-CV/actions/workflows/python-publish.yml) 
 ![Linux](https://img.shields.io/badge/Linux-Supported-fcc624?logo=linux) ![Windows](https://img.shields.io/badge/Windows-Supported-00a2e8?logo=windows) ![macOS](https://img.shields.io/badge/macOS-Supported-999999?logo=apple)
 
-A computer vision dataset processing library for seamless format conversion and visualization between LabelMe, COCO, and YOLO annotation formats. Designed for researchers and developers working with multi-format annotation pipelines.
+A computer vision dataset processing library for seamless format conversion and visualization between YOLO, LabelMe, and COCO annotation formats. Designed for researchers and developers working with multi-format annotation pipelines.
 
 ## Features
 
-- **Bidirectional Conversion**: Convert between LabelMe, COCO, and YOLO formats in any direction
+- **Bidirectional Conversion**: Convert between YOLO, LabelMe, and COCO formats in any direction
 - **Multi-format Support**: Handle object detection bounding boxes and instance segmentation polygons
-- **Lossless Round-trip**: Preserve original coordinates through conversion chains
+- **Native Coordinate Storage**: Coordinates stored in format-native representation (YOLO normalized, LabelMe/COCO absolute pixels)
 - **Visualization**: Visualize annotations with OpenCV, supporting both display and save modes
 - **Command-line Interface**: User-friendly CLI with `convert` and `visualize` subcommands
 - **Python API**: Programmatic access for integration into larger pipelines
 - **Verbose Logging**: Detailed logging with file output for debugging
+- **Headless Mode**: Run visualization in server/Docker environments with `--no-display`
+- **Flexible Error Handling**: Choose between strict (abort on error) or lenient (skip and continue) modes
 - **Cross-platform**: Full support for Windows, Linux, and macOS
 
 ## Table of Contents
@@ -88,12 +90,6 @@ dataflow-cv convert yolo2coco images/ yolo_labels/ classes.txt coco_annotations.
 # YOLO to LabelMe
 dataflow-cv convert yolo2labelme images/ yolo_labels/ classes.txt labelme_json/
 
-# COCO to YOLO
-dataflow-cv convert coco2yolo coco_annotations.json yolo_labels/
-
-# COCO to LabelMe
-dataflow-cv convert coco2labelme coco_annotations.json labelme_json/
-
 # LabelMe to YOLO
 dataflow-cv convert labelme2yolo labelme_json/ classes.txt yolo_labels/
 
@@ -103,8 +99,17 @@ dataflow-cv convert labelme2coco labelme_json/ classes.txt coco_annotations.json
 # With RLE encoding
 dataflow-cv convert labelme2coco labelme_json/ classes.txt coco_annotations.json --do-rle
 
+# COCO to YOLO
+dataflow-cv convert coco2yolo coco_annotations.json yolo_labels/
+
+# COCO to LabelMe
+dataflow-cv convert coco2labelme coco_annotations.json labelme_json/
+
 # Enable verbose logging
 dataflow-cv convert yolo2coco images/ yolo_labels/ classes.txt coco_annotations.json --verbose
+
+# Disable strict mode (skip invalid annotations instead of aborting)
+dataflow-cv convert yolo2coco --no-strict images/ yolo_labels/ classes.txt coco_annotations.json
 ```
 
 #### Visualization
@@ -112,14 +117,17 @@ dataflow-cv convert yolo2coco images/ yolo_labels/ classes.txt coco_annotations.
 # Visualize YOLO annotations
 dataflow-cv visualize yolo images/ yolo_labels/ classes.txt --save visualized/
 
-# Visualize COCO annotations
-dataflow-cv visualize coco images/ coco_annotations.json --save visualized/
-
 # Visualize LabelMe annotations
 dataflow-cv visualize labelme images/ labelme_json/ --save visualized/
 
+# Visualize COCO annotations
+dataflow-cv visualize coco images/ coco_annotations.json --save visualized/
+
 # Enable verbose logging for detailed debug output
 dataflow-cv visualize yolo --verbose images/ yolo_labels/ classes.txt --save visualized/
+
+# Run on headless server (no display window)
+dataflow-cv visualize yolo --no-display images/ yolo_labels/ classes.txt --save visualized/
 ```
 
 ### Python API
@@ -160,37 +168,53 @@ See the `samples/` directory for complete examples:
 
 ## Documentation
 
-- **[CLAUDE.md](CLAUDE.md)**: Detailed architecture and development guide
-- **`docs/formats/`**: Format specifications (YOLO, COCO, LabelMe)
-- **`docs/specs/`**: Module specifications and design documents
-- **`CHANGELOG.md`**: Version history and breaking changes
+- **[CLAUDE.md](CLAUDE.md)**: Detailed architecture, development guide, and known gotchas
+- **[CHANGELOG.md](CHANGELOG.md)**: Version history and breaking changes
+- **[specs/](specs/)**: Canonical specifications organized into two layers:
+  - **`formats/`** — External format contracts (YOLO, LabelMe, COCO) and conversion rules
+  - **`modules/`** — Internal module architecture, interface contracts, and dependency constraints
 
 ### Key Concepts
 
-- **Normalized Coordinates**: All internal coordinates are in 0-1 range
-- **Original Data Preservation**: Lossless round-trip conversion through `OriginalData` system
-- **Strict Mode**: Validation errors raise exceptions (default: enabled in CLI, can be disabled via `strict_mode=False` parameter in Python API)
+- **Format-Native Coordinates**: Coordinates stored in each format's native representation — YOLO normalized [0,1] center-based, LabelMe/COCO absolute pixels top-left. See `DatasetAnnotations.format` to determine semantics
+- **Explicit Coordinate Transforms**: Converters handle all coordinate transformations between formats. No hidden normalization — lossy vs lossless behavior is explicitly documented
+- **Strict Mode**: Validation errors raise exceptions (default). Disable in CLI with `--no-strict`, or in Python API with `strict_mode=False`
 - **Verbose Logging**: Detailed debug logs saved to files when `--verbose` is used. The CLI prints "Verbose log saved to: <path>" after operations.
-- **Keyboard Shortcuts**: During visualization, press `q` or `ESC` to exit early; any other key continues
+- **Headless Support**: Use `--no-display` for servers/Docker; use `--save` to output visualization images without a window
+- **Keyboard Shortcuts**: During visualization, press `q` or `ESC` to exit early; `Enter`/`Space` to advance; any other key continues
 - **Missing Image Handling**: Missing images are skipped with warnings, allowing processing to continue
 - **RLE Mask Visualization**: COCO RLE masks are displayed with semi-transparent fills for better visibility
-- **Color Management**: Each class ID gets a unique color from a palette of 1000 distinct colors for consistent visualization
+- **Color Management**: Each class ID gets a unique color from an HSV-based palette for consistent visualization
+- **Specifications**: The `specs/` directory contains the canonical format and module specifications — the authoritative reference for expected behavior
 
 ## Development
 For detailed developer guidance including advanced test commands, debugging, and architecture overview, see [CLAUDE.md](CLAUDE.md).
 
 ### Testing
+
+289 tests, **73%** code coverage.
+
 ```bash
 # Run all tests
 pytest
 
-# Run tests with coverage
-pytest --cov=dataflow
+# Run tests with coverage report
+pytest --cov=dataflow --cov-report=term
 
 # Run specific test module
 pytest tests/convert/test_yolo_and_coco.py
 ```
 
+**Coverage by module:**
+
+| Module | Coverage | Notes |
+|--------|----------|-------|
+| `dataflow/label/` | 78% | Core data models (66%), handlers (67-82%) |
+| `dataflow/convert/` | 83% | Converters (81-92%), base pipeline (62%) |
+| `dataflow/visualize/` | 69% | Visualizers (94-100%), base drawing (79%) |
+| `dataflow/cli/` | 76% | CLI commands (47-96%), utils (86%) |
+| `dataflow/util/` | 87% | File ops (84%), logging (99%) |
+
 ### Linting and Formatting
 ```bash
 # Install development dependencies
@@ -209,17 +233,39 @@ mypy dataflow
 flake8 dataflow tests samples
 ```
 
+### Pre-commit Hooks (Optional)
+
+Automatically check code quality before each commit:
+
+```bash
+# Install pre-commit
+pip install pre-commit
+
+# Install git hooks (run once)
+pre-commit install
+
+# After this, every `git commit` will auto-run:
+#   black (code formatting)
+#   isort (import sorting)
+#   flake8 (linting)
+#   trailing-whitespace / end-of-file-fixer / check-yaml / check-toml
+
+# Manually run against all files
+pre-commit run --all-files
+```
+
 ### Project Structure
 ```
 dataflow/
-├── label/           # Annotation handlers (YOLO, LabelMe, COCO)
-├── convert/         # Format converters
-├── visualize/       # Visualization modules
-├── util/           # Utilities (logging, file operations)
-└── cli/            # Command-line interface
-tests/              # Comprehensive test suite
-samples/            # Usage examples
-assets/             # Sample data for testing
+├── label/           # Annotation handlers + data models (YOLO, LabelMe, COCO)
+├── convert/         # Format converters + RLE conversion utility
+├── visualize/       # Visualization modules (OpenCV-based)
+├── util/            # Logging and file operation utilities
+└── cli/             # CLI entry point, commands, and validation
+tests/               # Unit and integration tests (label, convert, visualize, cli, util)
+samples/             # Python API usage examples (visualize, convert, label, cli)
+assets/              # Test data organized by format (det/seg) and annotation type
+specs/               # Canonical specifications (formats/ + modules/ layers)
 ```
 
 ## Contributing
@@ -241,6 +287,6 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## Acknowledgments
 
-- Thanks to the creators of LabelMe, COCO, and YOLO formats for establishing these annotation standards
+- Thanks to the creators of YOLO, LabelMe, and COCO formats for establishing these annotation standards
 - Built with OpenCV, NumPy, and Click
 - Inspired by the need for seamless format conversion in multi-tool CV pipelines

{dataflow_cv-0.6.2 → dataflow_cv-1.0.1}/dataflow/__init__.py

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

{dataflow_cv-0.6.2 → dataflow_cv-1.0.1}/dataflow/cli/__init__.py

@@ -6,7 +6,7 @@ offering convenient access to visualization and format conversion functionality
 through a unified command-line interface.
 
 The CLI follows a `<main-task> <sub-task>` structure:
-- `dataflow-cv visualize <format>`: Visualize annotations in YOLO, COCO, or LabelMe format
+- `dataflow-cv visualize <format>`: Visualize annotations in YOLO, LabelMe, or COCO format
 - `dataflow-cv convert <direction>`: Convert between six annotation format combinations
 
 Example usage: