From a0e8a7bd90de3829a1c6b480ef2e1e5ca1f2fab9 Mon Sep 17 00:00:00 2001 From: Bimantoro Maesa Date: Mon, 9 Mar 2026 19:36:37 +0700 Subject: [PATCH 1/3] Update package name from 'mata' to 'datamata' in installation instructions and workflows; adjust permissions for GitHub Actions --- .github/workflows/publish.yml | 4 +++- pyproject.toml | 6 +++--- src/mata/adapters/huggingface_sam_adapter.py | 2 +- src/mata/adapters/huggingface_segment_adapter.py | 4 ++-- src/mata/adapters/huggingface_zeroshot_segment_adapter.py | 2 +- src/mata/adapters/ocr/easyocr_adapter.py | 2 +- src/mata/adapters/ocr/paddleocr_adapter.py | 2 +- src/mata/adapters/ocr/tesseract_adapter.py | 2 +- src/mata/adapters/onnx_base.py | 2 +- src/mata/core/exporters/valkey_exporter.py | 2 +- src/mata/runtimes/onnx_runtime.py | 2 +- src/mata/visualization.py | 2 +- 12 files changed, 17 insertions(+), 15 deletions(-) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index d1f6d00..7679f2f 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -7,7 +7,7 @@ jobs: publish: runs-on: ubuntu-latest permissions: - id-token: write + contents: read steps: - uses: actions/checkout@v4 @@ -21,3 +21,5 @@ jobs: - name: Publish to PyPI uses: pypa/gh-action-pypi-publish@release/v1 + with: + password: ${{ secrets.PYPI_API_TOKEN }} diff --git a/pyproject.toml b/pyproject.toml index d5cc7c5..1c95792 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -3,7 +3,7 @@ requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta" [project] -name = "mata" +name = "datamata" version = "1.9.2b1" description = "Model-Agnostic Task Architecture - A task-centric, model-agnostic framework for computer vision" readme = "README.md" @@ -116,11 +116,11 @@ redis = [ # Full installation (all optional features except GPU ONNX) all = [ - "mata[onnx,classification,eval,viz,segmentation,ocr]", + "datamata[onnx,classification,eval,viz,segmentation,ocr]", ] dev = [ - "mata[all,valkey,redis]", + "datamata[all,valkey,redis]", "pytest>=7.4.0", "pytest-cov>=4.1.0", "black>=23.0.0", diff --git a/src/mata/adapters/huggingface_sam_adapter.py b/src/mata/adapters/huggingface_sam_adapter.py index 1acab99..252f756 100644 --- a/src/mata/adapters/huggingface_sam_adapter.py +++ b/src/mata/adapters/huggingface_sam_adapter.py @@ -254,7 +254,7 @@ def __init__( if not mask_utils: warnings.warn( "pycocotools not available. Falling back to binary masks. " - "Install with: pip install mata[segmentation] or pip install pycocotools", + "Install with: pip install datamata[segmentation] or pip install pycocotools", UserWarning, stacklevel=2, ) diff --git a/src/mata/adapters/huggingface_segment_adapter.py b/src/mata/adapters/huggingface_segment_adapter.py index 33a5931..a20f2dc 100644 --- a/src/mata/adapters/huggingface_segment_adapter.py +++ b/src/mata/adapters/huggingface_segment_adapter.py @@ -89,7 +89,7 @@ class HuggingFaceSegmentAdapter(PyTorchBaseAdapter): Mask Format: - By default, returns RLE-encoded masks (compact, JSON-serializable) - - Requires pycocotools: pip install mata[segmentation] + - Requires pycocotools: pip install datamata[segmentation] - Falls back to binary numpy arrays if pycocotools not available Segmentation Modes: @@ -221,7 +221,7 @@ def __init__( if not mask_utils: warnings.warn( "pycocotools not available. Falling back to binary masks. " - "Install with: pip install mata[segmentation] or pip install pycocotools", + "Install with: pip install datamata[segmentation] or pip install pycocotools", UserWarning, stacklevel=2, ) diff --git a/src/mata/adapters/huggingface_zeroshot_segment_adapter.py b/src/mata/adapters/huggingface_zeroshot_segment_adapter.py index e4e962f..527dc0d 100644 --- a/src/mata/adapters/huggingface_zeroshot_segment_adapter.py +++ b/src/mata/adapters/huggingface_zeroshot_segment_adapter.py @@ -212,7 +212,7 @@ def __init__( if not mask_utils: warnings.warn( "pycocotools not available. Falling back to binary masks. " - "Install with: pip install mata[segmentation] or pip install pycocotools", + "Install with: pip install datamata[segmentation] or pip install pycocotools", UserWarning, stacklevel=2, ) diff --git a/src/mata/adapters/ocr/easyocr_adapter.py b/src/mata/adapters/ocr/easyocr_adapter.py index 1c3be0a..af792f9 100644 --- a/src/mata/adapters/ocr/easyocr_adapter.py +++ b/src/mata/adapters/ocr/easyocr_adapter.py @@ -36,7 +36,7 @@ def _ensure_easyocr() -> Any: raise ImportError( "easyocr is required for EasyOCRAdapter. " "Install with: pip install easyocr\n" - "or: pip install mata[ocr]" + "or: pip install datamata[ocr]" ) from exc return _easyocr diff --git a/src/mata/adapters/ocr/paddleocr_adapter.py b/src/mata/adapters/ocr/paddleocr_adapter.py index fa9c0a3..f00ef0a 100644 --- a/src/mata/adapters/ocr/paddleocr_adapter.py +++ b/src/mata/adapters/ocr/paddleocr_adapter.py @@ -291,7 +291,7 @@ def _set_opt_level(self: Any, level: int) -> None: # noqa: ANN001 raise ImportError( "paddleocr is required for PaddleOCRAdapter. " "Install with: pip install paddleocr paddlepaddle\n" - "or: pip install mata[ocr-paddle]\n" + "or: pip install datamata[ocr-paddle]\n" "Note: paddlepaddle GPU wheel is ~500 MB. Use paddlepaddle-gpu for GPU support." ) from exc return _paddleocr_module diff --git a/src/mata/adapters/ocr/tesseract_adapter.py b/src/mata/adapters/ocr/tesseract_adapter.py index d57ff52..5638544 100644 --- a/src/mata/adapters/ocr/tesseract_adapter.py +++ b/src/mata/adapters/ocr/tesseract_adapter.py @@ -33,7 +33,7 @@ def _ensure_tesseract() -> Any: raise ImportError( "pytesseract is required for TesseractAdapter.\n" "Install Python package: pip install pytesseract\n" - "or: pip install mata[ocr-tesseract]\n" + "or: pip install datamata[ocr-tesseract]\n" "Also install the Tesseract binary:\n" " Ubuntu/Debian: sudo apt-get install tesseract-ocr\n" " macOS: brew install tesseract\n" diff --git a/src/mata/adapters/onnx_base.py b/src/mata/adapters/onnx_base.py index f849a7d..9f016c2 100644 --- a/src/mata/adapters/onnx_base.py +++ b/src/mata/adapters/onnx_base.py @@ -43,7 +43,7 @@ def _ensure_onnxruntime(): ONNX_AVAILABLE = False raise ImportError( "ONNX Runtime is required for ONNX models. " - "Install with: pip install mata[onnx] (CPU) or pip install mata[onnx-gpu] (CUDA)" + "Install with: pip install datamata[onnx] (CPU) or pip install datamata[onnx-gpu] (CUDA)" ) return _ort diff --git a/src/mata/core/exporters/valkey_exporter.py b/src/mata/core/exporters/valkey_exporter.py index 77a475a..b81ca43 100644 --- a/src/mata/core/exporters/valkey_exporter.py +++ b/src/mata/core/exporters/valkey_exporter.py @@ -84,7 +84,7 @@ def _get_valkey_client(url: str, **kwargs: Any): except ImportError: raise ImportError( "Valkey export requires 'valkey' or 'redis' package. " - "Install with: pip install mata[valkey] or pip install mata[redis]" + "Install with: pip install datamata[valkey] or pip install datamata[redis]" ) diff --git a/src/mata/runtimes/onnx_runtime.py b/src/mata/runtimes/onnx_runtime.py index c4a19f9..493bcb8 100644 --- a/src/mata/runtimes/onnx_runtime.py +++ b/src/mata/runtimes/onnx_runtime.py @@ -30,7 +30,7 @@ def __init__(self, device: str = "auto", **session_options: Any) -> None: if not ONNX_AVAILABLE: raise ImportError( "ONNX Runtime is not installed. " - "Install with: pip install mata[onnx] (CPU) or pip install mata[onnx-gpu] (CUDA)" + "Install with: pip install datamata[onnx] (CPU) or pip install datamata[onnx-gpu] (CUDA)" ) self.device = device diff --git a/src/mata/visualization.py b/src/mata/visualization.py index f51d6d3..be7d008 100644 --- a/src/mata/visualization.py +++ b/src/mata/visualization.py @@ -52,7 +52,7 @@ def _get_track_color(track_id: int) -> tuple[int, int, int]: MATPLOTLIB_AVAILABLE = False warnings.warn( "matplotlib is not installed — matplotlib-based visualization unavailable. " - "Install with: pip install mata[viz]", + "Install with: pip install datamata[viz]", ImportWarning, stacklevel=2, ) From 41553b9da869a35d33dbd73a41c3d12ae46deb75 Mon Sep 17 00:00:00 2001 From: Bimantoro Maesa Date: Mon, 9 Mar 2026 20:14:18 +0700 Subject: [PATCH 2/3] Refactor package name from 'mata' to 'datamata' across documentation, examples, and tests - Updated all instances of 'mata' to 'datamata' in documentation files including VALIDATION_GUIDE.md and VALKEY_GUIDE.md. - Modified example scripts to reflect the new package name in installation instructions. - Adjusted test cases to ensure compatibility with the new package name. - Ensured that all references to optional dependencies for Valkey and Redis are updated accordingly. --- .github/workflows/publish.yml | 5 +- CHANGELOG.md | 10 +- QUICKSTART.md | 4 +- README.md | 4 +- docs/CLIP_QUICK_START.md | 2 +- docs/GRAPH_API_REFERENCE.md | 4 +- docs/OCR_IMPLEMENTATION_SUMMARY.md | 6 +- docs/REAL_WORLD_SCENARIOS.md | 182 +++++++++++++++------ docs/VALIDATION_GUIDE.md | 85 ++++++---- docs/VALKEY_GUIDE.md | 8 +- examples/classify/clip_zeroshot.py | 2 +- examples/detect/zeroshot_detection.py | 2 +- examples/graph/scenarios/README.md | 6 +- examples/graph/valkey_pipeline.py | 4 +- examples/graph/valkey_rtsp_pipeline.py | 6 +- examples/segment/grounding_sam_pipeline.py | 2 +- examples/track/basic_tracking.py | 2 +- examples/track/cross_camera_reid.py | 4 +- examples/track/persist_tracking.py | 2 +- examples/track/reid_tracking.py | 2 +- examples/track/stream_tracking.py | 2 +- tests/test_ocr_adapter.py | 8 +- tests/test_valkey_exporter.py | 2 +- 23 files changed, 226 insertions(+), 128 deletions(-) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 7679f2f..bdc0dd2 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -6,8 +6,9 @@ on: jobs: publish: runs-on: ubuntu-latest + environment: pypi permissions: - contents: read + id-token: write steps: - uses: actions/checkout@v4 @@ -21,5 +22,3 @@ jobs: - name: Publish to PyPI uses: pypa/gh-action-pypi-publish@release/v1 - with: - password: ${{ secrets.PYPI_API_TOKEN }} diff --git a/CHANGELOG.md b/CHANGELOG.md index 8241115..9e0bff8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,14 @@ Versions follow [Semantic Versioning](https://semver.org/). ## [1.9.2] Beta Release - 2026-03-09 +### Changed + +**PyPI Distribution Rename** + +- PyPI distribution name changed from `mata` to `datamata`; users now run `pip install datamata` to install +- `import mata` is unchanged — all existing code continues to work without modification +- Follows the PIL/Pillow precedent: distribution name and import name differ intentionally + ### Added **Valkey / Redis Graph Pipeline Storage** @@ -26,7 +34,7 @@ Versions follow [Semantic Versioning](https://semver.org/). - `valkey://` and `redis://` URI scheme dispatch added to all six `result.save()` methods (`VisionResult`, `DetectResult`, `SegmentResult`, `ClassifyResult`, `DepthResult`, `OCRResult`) — existing file-based paths are fully unaffected - `ModelRegistry.get_valkey_connection(name="default")` — reads named Valkey connection profiles from the `storage.valkey` section of `.mata/models.yaml` or `~/.mata/models.yaml`; resolves `password_env` from environment variables; raises `ModelNotFoundError` for unknown connection names - YAML `storage.valkey.` config schema with `url`, `db`, `ttl`, `password_env`, and `tls` fields -- Optional dependency groups: `pip install mata[valkey]` → `valkey>=6.0.0`; `pip install mata[redis]` → `redis>=5.0.0`; both added to the `dev` extras group +- Optional dependency groups: `pip install datamata[valkey]` → `valkey>=6.0.0`; `pip install datamata[redis]` → `redis>=5.0.0`; both added to the `dev` extras group - `export_valkey`, `load_valkey`, and `publish_valkey` exported from `mata.core.exporters` - `ValkeyStore` and `ValkeyLoad` exported from `mata.nodes` - 89 new tests: 42 exporter tests (`test_valkey_exporter.py`), 33 graph node tests (`test_valkey_nodes.py`), 14 config and pub/sub tests (`test_valkey_config.py`) diff --git a/QUICKSTART.md b/QUICKSTART.md index 1f636fb..08b0b2c 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -373,8 +373,8 @@ Persist any MATA result to [Valkey](https://valkey.io/) or Redis for distributed ### Install ```bash -pip install mata[valkey] # valkey-py (recommended) -pip install mata[redis] # redis-py (alternative) +pip install datamata[valkey] # valkey-py (recommended) +pip install datamata[redis] # redis-py (alternative) ``` ### Save and load a result diff --git a/README.md b/README.md index 1dcd12a..0b1c640 100644 --- a/README.md +++ b/README.md @@ -101,8 +101,8 @@ pip install onnxruntime-gpu # GPU pip install matplotlib # For Valkey/Redis result storage -pip install mata[valkey] # valkey-py client (recommended) -pip install mata[redis] # redis-py client (alternative) +pip install datamata[valkey] # valkey-py client (recommended) +pip install datamata[redis] # redis-py client (alternative) ``` ## 🚀 Quick Start diff --git a/docs/CLIP_QUICK_START.md b/docs/CLIP_QUICK_START.md index ec491be..52fc173 100644 --- a/docs/CLIP_QUICK_START.md +++ b/docs/CLIP_QUICK_START.md @@ -37,7 +37,7 @@ print(result.predictions[0].label_name) # "cat" ## Installation ```bash -pip install mata transformers torch +pip install datamata transformers torch ``` **Requirements:** diff --git a/docs/GRAPH_API_REFERENCE.md b/docs/GRAPH_API_REFERENCE.md index d1d6099..98b5b42 100644 --- a/docs/GRAPH_API_REFERENCE.md +++ b/docs/GRAPH_API_REFERENCE.md @@ -872,8 +872,8 @@ from mata.nodes import ValkeyStore, ValkeyLoad **Installation:** ```bash -pip install mata[valkey] # valkey-py client -pip install mata[redis] # redis-py client (fallback) +pip install datamata[valkey] # valkey-py client +pip install datamata[redis] # redis-py client (fallback) ``` Both nodes lazy-import the client library — `import mata` succeeds without either installed. An `ImportError` with an actionable message is raised only when a storage node actually executes. diff --git a/docs/OCR_IMPLEMENTATION_SUMMARY.md b/docs/OCR_IMPLEMENTATION_SUMMARY.md index 2725244..8994680 100644 --- a/docs/OCR_IMPLEMENTATION_SUMMARY.md +++ b/docs/OCR_IMPLEMENTATION_SUMMARY.md @@ -63,7 +63,7 @@ pip install transformers accelerate # EasyOCR pip install easyocr -# or: pip install mata[ocr] +# or: pip install datamata[ocr] # PaddleOCR — IMPORTANT: paddleocr and paddlepaddle MAJOR versions must match. # paddleocr 3.x requires paddlepaddle 3.x (mismatched installs cause native crashes). @@ -75,11 +75,11 @@ pip install paddlepaddle-gpu==3.0.0 -i https://www.paddlepaddle.org.cn/packages/ pip install paddlepaddle-gpu==3.0.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu123/ # CUDA 12.3 pip install paddlepaddle-gpu==3.0.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/ # CUDA 12.6 (recommended) # Wheel is ~1–1.5 GB. See https://www.paddlepaddle.org.cn/install/quick for all options. -# or: pip install mata[ocr-paddle] (installs CPU wheel only) +# or: pip install datamata[ocr-paddle] (installs CPU wheel only) # Tesseract pip install pytesseract -# or: pip install mata[ocr-tesseract] +# or: pip install datamata[ocr-tesseract] # + system binary: # Ubuntu/Debian: sudo apt-get install tesseract-ocr # macOS: brew install tesseract diff --git a/docs/REAL_WORLD_SCENARIOS.md b/docs/REAL_WORLD_SCENARIOS.md index f597fcd..ab49f25 100644 --- a/docs/REAL_WORLD_SCENARIOS.md +++ b/docs/REAL_WORLD_SCENARIOS.md @@ -23,28 +23,28 @@ This document showcases 20 production-ready computer vision scenarios built with ## Quick Reference Table -| # | Scenario | Industry | Preset Used | Example Script | Models | -|---|----------|----------|-------------|----------------|--------| -| 1 | Surface defect detection & classification | Manufacturing | `defect_detect_classify` | `manufacturing_defect_classify.py` | GroundingDINO + CLIP | -| 2 | Defect segmentation & area measurement | Manufacturing | `grounding_dino_sam` | `manufacturing_defect_segment.py` | GroundingDINO + SAM | -| 3 | Assembly verification with VLM | Manufacturing | `assembly_verification` | `manufacturing_assembly_verify.py` | Qwen3-VL + DETR | -| 4 | Per-component VLM inspection | Manufacturing | `component_inspection` | `manufacturing_component_inspect.py` | DETR + Qwen3-VL | -| 5 | Shelf product analysis | Retail | `shelf_product_analysis` | `retail_shelf_analysis.py` | Faster R-CNN + CLIP | -| 6 | Zero-shot product search | Retail | `grounding_dino_sam` | `retail_product_search.py` | GroundingDINO + SAM | -| 7 | Multi-modal stock assessment | Retail | `stock_level_analysis` | `retail_stock_level.py` | Qwen3-VL + DETR + CLIP | -| 8 | Vehicle distance estimation | Driving | `vehicle_distance_estimation` | `driving_distance_estimation.py` | DETR + Depth Anything | -| 9 | Complete road scene analysis | Driving | `road_scene_analysis` | `driving_road_scene.py` | DETR + Mask2Former + Depth + CLIP | -| 10 | Traffic object tracking | Driving | `traffic_tracking` | `driving_traffic_tracking.py` | RT-DETR + BYTETrack | -| 11 | Obstacle detection with VLM | Driving | `vlm_scene_understanding` | `driving_obstacle_vlm.py` | Qwen3-VL + GroundingDINO + Depth | -| 12 | Crowd monitoring & tracking | Security | `crowd_monitoring` | `security_crowd_monitoring.py` | DETR + BYTETrack | -| 13 | Suspicious object detection | Security | `suspicious_object_detection` | `security_suspicious_object.py` | GroundingDINO + SAM + Qwen3-VL | -| 14 | Situational awareness monitoring | Security | `vlm_scene_understanding` | `security_situational_awareness.py` | Qwen3-VL + GroundingDINO | -| 15 | Crop disease classification | Agriculture | `defect_detect_classify` | `agriculture_disease_classify.py` | GroundingDINO + CLIP | -| 16 | Aerial crop segmentation | Agriculture | `aerial_crop_analysis` | `agriculture_aerial_crop.py` | Mask2Former + Depth Anything | -| 17 | Pest detection & mapping | Agriculture | `grounding_dino_sam` | `agriculture_pest_detection.py` | GroundingDINO + SAM | -| 18 | Medical ROI segmentation | Healthcare | Custom graph | `medical_roi_segmentation.py` | GroundingDINO + SAM | -| 19 | Medical report generation | Healthcare | `vlm_scene_understanding` | `medical_report_generation.py` | Qwen3-VL | -| 20 | Pathology triage workflow | Healthcare | Custom graph | `medical_pathology_triage.py` | DETR + CLIP + Qwen3-VL | +| # | Scenario | Industry | Preset Used | Example Script | Models | +| --- | ----------------------------------------- | ------------- | ----------------------------- | ------------------------------------ | --------------------------------- | +| 1 | Surface defect detection & classification | Manufacturing | `defect_detect_classify` | `manufacturing_defect_classify.py` | GroundingDINO + CLIP | +| 2 | Defect segmentation & area measurement | Manufacturing | `grounding_dino_sam` | `manufacturing_defect_segment.py` | GroundingDINO + SAM | +| 3 | Assembly verification with VLM | Manufacturing | `assembly_verification` | `manufacturing_assembly_verify.py` | Qwen3-VL + DETR | +| 4 | Per-component VLM inspection | Manufacturing | `component_inspection` | `manufacturing_component_inspect.py` | DETR + Qwen3-VL | +| 5 | Shelf product analysis | Retail | `shelf_product_analysis` | `retail_shelf_analysis.py` | Faster R-CNN + CLIP | +| 6 | Zero-shot product search | Retail | `grounding_dino_sam` | `retail_product_search.py` | GroundingDINO + SAM | +| 7 | Multi-modal stock assessment | Retail | `stock_level_analysis` | `retail_stock_level.py` | Qwen3-VL + DETR + CLIP | +| 8 | Vehicle distance estimation | Driving | `vehicle_distance_estimation` | `driving_distance_estimation.py` | DETR + Depth Anything | +| 9 | Complete road scene analysis | Driving | `road_scene_analysis` | `driving_road_scene.py` | DETR + Mask2Former + Depth + CLIP | +| 10 | Traffic object tracking | Driving | `traffic_tracking` | `driving_traffic_tracking.py` | RT-DETR + BYTETrack | +| 11 | Obstacle detection with VLM | Driving | `vlm_scene_understanding` | `driving_obstacle_vlm.py` | Qwen3-VL + GroundingDINO + Depth | +| 12 | Crowd monitoring & tracking | Security | `crowd_monitoring` | `security_crowd_monitoring.py` | DETR + BYTETrack | +| 13 | Suspicious object detection | Security | `suspicious_object_detection` | `security_suspicious_object.py` | GroundingDINO + SAM + Qwen3-VL | +| 14 | Situational awareness monitoring | Security | `vlm_scene_understanding` | `security_situational_awareness.py` | Qwen3-VL + GroundingDINO | +| 15 | Crop disease classification | Agriculture | `defect_detect_classify` | `agriculture_disease_classify.py` | GroundingDINO + CLIP | +| 16 | Aerial crop segmentation | Agriculture | `aerial_crop_analysis` | `agriculture_aerial_crop.py` | Mask2Former + Depth Anything | +| 17 | Pest detection & mapping | Agriculture | `grounding_dino_sam` | `agriculture_pest_detection.py` | GroundingDINO + SAM | +| 18 | Medical ROI segmentation | Healthcare | Custom graph | `medical_roi_segmentation.py` | GroundingDINO + SAM | +| 19 | Medical report generation | Healthcare | `vlm_scene_understanding` | `medical_report_generation.py` | Qwen3-VL | +| 20 | Pathology triage workflow | Healthcare | Custom graph | `medical_pathology_triage.py` | DETR + CLIP + Qwen3-VL | --- @@ -59,6 +59,7 @@ Manufacturing quality control requires automated visual inspection to maintain p **Problem Statement**: Detect surface defects (scratches, cracks, dents) on metal/plastic parts and classify each defect type for root-cause analysis. **Architecture Diagram**: + ``` Image → GroundingDINO → Filter → ExtractROIs → CLIP → Fuse (text-prompted (>0.3) (crop each (classify @@ -72,11 +73,13 @@ Image → GroundingDINO → Filter → ExtractROIs → CLIP → Fuse | `classifier` | Zero-shot classifier | Defect type classification | `openai/clip-vit-base-patch32` | **Hardware Requirements**: + - **GPU**: Recommended (4GB+ VRAM) - **CPU**: Supported (slower inference, ~5-10x) - **Inference Time**: ~200ms per image (GPU), ~2s (CPU) **Code Example**: + ```python import mata from mata.presets import defect_detect_classify @@ -101,6 +104,7 @@ for inst in result['final'].instances: ``` **Use Cases**: + - Automotive body panel inspection - Electronics PCB defect detection - Metal casting quality control @@ -113,6 +117,7 @@ for inst in result['final'].instances: **Problem Statement**: Segment defect regions precisely and measure their area in pixels/mm² for acceptance criteria evaluation. **Architecture Diagram**: + ``` Image → GroundingDINO → Filter → PromptBoxes(SAM) → RefineMask → Fuse (detect (>0.25) (segment each (morphology @@ -126,11 +131,13 @@ Image → GroundingDINO → Filter → PromptBoxes(SAM) → RefineMask → Fuse | `segmenter` | Prompt-based segmenter | Pixel-precise masks | `facebook/sam-vit-base` | **Hardware Requirements**: + - **GPU**: Recommended (6GB+ VRAM for SAM) - **CPU**: Supported (very slow, 10-20s per image) - **Inference Time**: ~500ms per image (GPU), ~15s (CPU) **Code Example**: + ```python import mata from mata.presets import grounding_dino_sam @@ -158,6 +165,7 @@ for inst in result['final'].instances: **Problem Statement**: Verify assembled products have all components installed correctly using holistic VLM assessment alongside component detection. **Architecture Diagram**: + ``` ┌─→ VLMQuery (holistic check) Image ──parallel────┤ @@ -174,11 +182,13 @@ Image ──parallel────┤ | `detector` | Object detector | Component detection | `facebook/detr-resnet-50` | **Hardware Requirements**: + - **GPU**: Required (8GB+ VRAM for VLM) - **CPU**: Not recommended (VLM inference extremely slow) - **Inference Time**: ~1-2s per image (GPU) **Code Example**: + ```python import mata from mata.presets import assembly_verification @@ -206,6 +216,7 @@ print(f"Detected {len(result['final'].instances)} components") **Problem Statement**: Detect individual components, crop each, then use VLM to inspect for issues like damage, incorrect orientation, or missing sub-parts. **Architecture Diagram**: + ``` Image → Detect → Filter → TopK → ExtractROIs → VLMQuery → Fuse (find (>0.5) (top 5 (crop each (inspect @@ -219,11 +230,13 @@ Image → Detect → Filter → TopK → ExtractROIs → VLMQuery → Fuse | `vlm` | Vision-Language Model | Per-component inspection | `Qwen/Qwen3-VL-2B-Instruct` | **Hardware Requirements**: + - **GPU**: Required (8GB+ VRAM) - **CPU**: Not recommended - **Inference Time**: ~2-5s per image depending on component count **Code Example**: + ```python import mata from mata.presets import component_inspection @@ -254,6 +267,7 @@ Retail operations require automated shelf monitoring, inventory tracking, and pl **Problem Statement**: Detect products on shelves, identify brands, and verify planogram compliance. **Architecture Diagram**: + ``` Image → Detect → Filter → NMS → ExtractROIs → Classify → Fuse (find (>0.5) (0.5 (crop each (brand/ @@ -267,11 +281,13 @@ Image → Detect → Filter → NMS → ExtractROIs → Classify → Fuse | `classifier` | Zero-shot classifier | Brand identification | `openai/clip-vit-base-patch32` | **Hardware Requirements**: + - **GPU**: Recommended (4GB+ VRAM) - **CPU**: Supported (~3-5s per image) - **Inference Time**: ~300ms per image (GPU) **Code Example**: + ```python import mata from mata.presets import shelf_product_analysis @@ -300,6 +316,7 @@ print("Brand counts:", dict(brands)) **Problem Statement**: Find specific products on shelves using natural language descriptions without pre-training. **Architecture Diagram**: + ``` Image → GroundingDINO → Filter → PromptBoxes(SAM) → RefineMask → Fuse (text-prompted (>0.3) (segment each (cleanup @@ -313,11 +330,13 @@ Image → GroundingDINO → Filter → PromptBoxes(SAM) → RefineMask → Fuse | `segmenter` | Prompt segmenter | Precise boundaries | `facebook/sam-vit-base` | **Hardware Requirements**: + - **GPU**: Recommended (6GB+ VRAM) - **CPU**: Supported (~10s per image) - **Inference Time**: ~500ms per image (GPU) **Code Example**: + ```python import mata from mata.presets import grounding_dino_sam @@ -342,6 +361,7 @@ print(f"Found {len(result['final'].instances)} products matching prompts") **Problem Statement**: Comprehensive stock evaluation combining VLM semantic assessment, object counting, and stock level classification. **Architecture Diagram**: + ``` ┌─→ VLMDescribe (semantic stock check) │ @@ -360,11 +380,13 @@ Image ──parallel────┼─→ Detect → Filter (count products) | `classifier` | Zero-shot classifier | Stock level category | `openai/clip-vit-base-patch32` | **Hardware Requirements**: + - **GPU**: Required (8GB+ VRAM) - **CPU**: Not recommended - **Inference Time**: ~1.5s per image (GPU) **Code Example**: + ```python import mata from mata.presets import stock_level_analysis @@ -400,6 +422,7 @@ Autonomous vehicles and ADAS systems require real-time scene understanding, incl **Problem Statement**: Detect vehicles/pedestrians and estimate their distance using depth maps for collision avoidance. **Architecture Diagram**: + ``` ┌─→ Detect → Filter (vehicles/pedestrians) Image ──parallel────┤ (>0.4) @@ -415,11 +438,13 @@ Image ──parallel────┤ (>0.4) | `depth` | Depth estimator | Monocular depth | `depth-anything/Depth-Anything-V2-Small-hf` | **Hardware Requirements**: + - **GPU**: Recommended (4GB+ VRAM) - **CPU**: Supported (~5s per frame) - **Inference Time**: ~150ms per frame (GPU) — 6 FPS real-time capable **Code Example**: + ```python import mata from mata.presets import vehicle_distance_estimation @@ -451,6 +476,7 @@ for inst in result['final'].instances: **Problem Statement**: Comprehensive scene understanding with detection, segmentation, depth, and scene classification. **Architecture Diagram**: + ``` ┌─→ Detect (objects) │ @@ -472,11 +498,13 @@ Image ──parallel────┤ | `classifier` | Zero-shot classifier | Scene classification | `openai/clip-vit-base-patch32` | **Hardware Requirements**: + - **GPU**: Required (8GB+ VRAM for Mask2Former) - **CPU**: Not recommended (very slow) - **Inference Time**: ~800ms per frame (GPU) — 1-2 FPS **Code Example**: + ```python import mata from mata.presets import road_scene_analysis @@ -505,6 +533,7 @@ print(f"Detected {len(result['final'].instances)} objects") **Problem Statement**: Track vehicles and pedestrians across video frames with persistent IDs for traffic flow analysis. **Architecture Diagram**: + ``` Frame → Detect → Filter → Track → Annotate → Fuse (fast (>0.4) (BYTETrack (draw IDs @@ -519,11 +548,13 @@ Frame → Detect → Filter → Track → Annotate → Fuse | `tracker` | Multi-object tracker | Persistent ID assignment | `ByteTrackWrapper` | **Hardware Requirements**: + - **GPU**: Recommended (4GB VRAM) - **CPU**: Supported (~10 FPS) - **Inference Time**: ~50ms per frame (GPU) — 20 FPS real-time **Code Example**: + ```python import mata from mata.presets import traffic_tracking @@ -541,7 +572,7 @@ for frame_idx, frame in enumerate(video_frames): ), providers={"detector": detector, "tracker": tracker}, ) - + print(f"Frame {frame_idx}: {len(result['final'].instances)} tracked objects") for inst in result['final'].instances: print(f" Track ID {inst.track_id}: {inst.label} at {inst.bbox}") @@ -554,6 +585,7 @@ for frame_idx, frame in enumerate(video_frames): **Problem Statement**: Detect road obstacles and use VLM to reason about hazard level and recommended actions. **Architecture Diagram**: + ``` ┌─→ VLMQuery (hazard assessment) │ @@ -572,11 +604,13 @@ Image ──parallel────┼─→ Detect (obstacles) | `depth` | Depth estimator | Distance estimation | `depth-anything/Depth-Anything-V2-Small-hf` | **Hardware Requirements**: + - **GPU**: Required (8GB+ VRAM) - **CPU**: Not recommended - **Inference Time**: ~1s per frame (GPU) **Code Example**: + ```python import mata from mata.presets import vlm_scene_understanding @@ -610,6 +644,7 @@ Security operations require automated monitoring for crowd management, suspiciou **Problem Statement**: Track individuals in crowded spaces for density analysis and safety alerts. **Architecture Diagram**: + ``` Frame → Detect → Filter(person) → Track → Annotate → Fuse (person (fuzzy match (persistent (render @@ -623,11 +658,13 @@ Frame → Detect → Filter(person) → Track → Annotate → Fuse | `tracker` | Multi-object tracker | Crowd tracking | `ByteTrackWrapper` | **Hardware Requirements**: + - **GPU**: Recommended (4GB VRAM) - **CPU**: Supported (~5 FPS) - **Inference Time**: ~100ms per frame (GPU) **Code Example**: + ```python import mata from mata.presets import crowd_monitoring @@ -657,6 +694,7 @@ if len(unique_ids) > 50: **Problem Statement**: Detect abandoned objects (bags, packages) and use VLM to assess suspiciousness. **Architecture Diagram**: + ``` Image → Detect → Filter → PromptBoxes(SAM) → RefineMask → VLMQuery → Fuse (text- (>0.25) (segment (cleanup) (assess @@ -672,11 +710,13 @@ Image → Detect → Filter → PromptBoxes(SAM) → RefineMask → VLMQuery → | `vlm` | Vision-Language Model | Contextual reasoning | `Qwen/Qwen3-VL-2B-Instruct` | **Hardware Requirements**: + - **GPU**: Required (10GB+ VRAM for 3-model chain) - **CPU**: Not recommended - **Inference Time**: ~2s per image (GPU) **Code Example**: + ```python import mata from mata.presets import suspicious_object_detection @@ -706,6 +746,7 @@ for inst in result['final'].instances: **Problem Statement**: Use VLM to monitor camera feeds for security concerns, unusual behavior, or policy violations. **Architecture Diagram**: + ``` Image → VLMQuery → PromoteEntities → Fuse (security (extract bboxes @@ -719,11 +760,13 @@ Image → VLMQuery → PromoteEntities → Fuse | `detector` | Zero-shot detector | Entity extraction | `IDEA-Research/grounding-dino-tiny` | **Hardware Requirements**: + - **GPU**: Required (8GB+ VRAM) - **CPU**: Not recommended - **Inference Time**: ~1s per frame (GPU) **Code Example**: + ```python import mata from mata.presets import vlm_scene_understanding @@ -758,6 +801,7 @@ Agricultural monitoring requires early disease detection, crop health assessment **Problem Statement**: Detect diseased leaves and classify disease types for targeted treatment. **Architecture Diagram**: + ``` Image → Detect → Filter → ExtractROIs → Classify → Fuse (diseased (>0.5) (crop each (disease @@ -771,11 +815,13 @@ Image → Detect → Filter → ExtractROIs → Classify → Fuse | `classifier` | Zero-shot classifier | Disease classification | `openai/clip-vit-base-patch32` | **Hardware Requirements**: + - **GPU**: Recommended (4GB+ VRAM) - **CPU**: Supported (~2s per image) - **Inference Time**: ~200ms per image (GPU) **Code Example**: + ```python import mata from mata.presets import defect_detect_classify @@ -805,6 +851,7 @@ print("Disease distribution:", dict) **Problem Statement**: Segment aerial images into crop regions and estimate terrain depth for coverage/planning. **Architecture Diagram**: + ``` ┌─→ SegmentImage (crop regions) Image ──parallel────┤ @@ -820,11 +867,13 @@ Image ──parallel────┤ | `depth` | Depth estimator | Terrain depth | `depth-anything/Depth-Anything-V2-Small-hf` | **Hardware Requirements**: + - **GPU**: Required (8GB+ VRAM for Mask2Former) - **CPU**: Not recommended - **Inference Time**: ~600ms per image (GPU) **Code Example**: + ```python import mata from mata.presets import aerial_crop_analysis @@ -850,6 +899,7 @@ print(f"Identified {len(stuff_regions)} crop/terrain regions") **Problem Statement**: Detect and segment pest infestations for targeted treatment planning. **Architecture Diagram**: + ``` Image → Detect → Filter → PromptBoxes(SAM) → RefineMask → Fuse (text- (>0.3) (segment pests) (cleanup @@ -864,11 +914,13 @@ Image → Detect → Filter → PromptBoxes(SAM) → RefineMask → Fuse | `segmenter` | Prompt segmenter | Infestation area | `facebook/sam-vit-base` | **Hardware Requirements**: + - **GPU**: Recommended (6GB+ VRAM) - **CPU**: Supported (~10s per image) - **Inference Time**: ~500ms per image (GPU) **Code Example**: + ```python import mata from mata.presets import grounding_dino_sam @@ -903,6 +955,7 @@ Medical imaging research requires automated ROI detection, segmentation, and ana **Problem Statement**: Detect and segment regions of interest (lesions, nodules, masses) with area measurements for research analysis. **Architecture Diagram**: + ``` Image → Detect → Filter → PromptBoxes(SAM) → RefineMask → Fuse (text- (>0.25) (segment ROIs) (cleanup @@ -917,11 +970,13 @@ Image → Detect → Filter → PromptBoxes(SAM) → RefineMask → Fuse | `segmenter` | Prompt segmenter | Precise boundaries | `facebook/sam-vit-base` | **Hardware Requirements**: + - **GPU**: Recommended (6GB+ VRAM) - **CPU**: Supported (~10s per image) - **Inference Time**: ~500ms per image (GPU) **Code Example**: + ```python import mata from mata.presets import grounding_dino_sam @@ -949,6 +1004,7 @@ for inst in result['final'].instances: **Problem Statement**: Generate descriptive reports of medical images for research documentation. **Architecture Diagram**: + ``` Image → VLMQuery → Fuse (describe @@ -961,11 +1017,13 @@ Image → VLMQuery → Fuse | `vlm` | Vision-Language Model | Image description | `Qwen/Qwen3-VL-2B-Instruct` | **Hardware Requirements**: + - **GPU**: Required (8GB+ VRAM) - **CPU**: Not recommended - **Inference Time**: ~800ms per image (GPU) **Code Example**: + ```python import mata from mata.presets import vlm_scene_understanding @@ -991,6 +1049,7 @@ print("Research Report:", result['final'].meta.get('vlm_response')) **Problem Statement**: Automated triage system for pathology samples using detection + classification + conditional VLM analysis (research tool). **Architecture Diagram**: + ``` Image → Detect → Filter → ExtractROIs → Classify → [Conditional VLM] → Fuse (find (>0.4) (crop (normal/benign/ (detailed @@ -1006,11 +1065,13 @@ Image → Detect → Filter → ExtractROIs → Classify → [Conditional VLM] | `vlm` | Vision-Language Model | Detailed analysis | `Qwen/Qwen3-VL-2B-Instruct` | **Hardware Requirements**: + - **GPU**: Required (8GB+ VRAM) - **CPU**: Not recommended - **Inference Time**: ~1-3s per image depending on flagged regions **Code Example**: + ```python import mata from mata.core.graph.graph import Graph @@ -1057,36 +1118,40 @@ for inst in result['classifications'].instances: ### Models Used Across Scenarios -| Model | Type | Scenarios | Total Uses | -|-------|------|-----------|------------| -| `IDEA-Research/grounding-dino-tiny` | Zero-shot detection | 1, 2, 6, 11, 13, 14, 15, 17, 18 | 9 | -| `openai/clip-vit-base-patch32` | Zero-shot classification | 1, 5, 7, 9, 15, 20 | 6 | -| `facebook/sam-vit-base` | Prompt segmentation | 2, 6, 13, 17, 18 | 5 | -| `Qwen/Qwen3-VL-2B-Instruct` | Vision-Language Model | 3, 4, 7, 11, 13, 14, 19, 20 | 8 | -| `facebook/detr-resnet-50` | Object detection | 3, 4, 7, 8, 9, 12, 20 | 7 | -| `depth-anything/Depth-Anything-V2-Small-hf` | Depth estimation | 8, 9, 11, 16 | 4 | -| `torchvision/fasterrcnn_resnet50_fpn_v2` | Object detection | 5, 12 | 2 | -| `facebook/mask2former-swin-large-cityscapes` | Panoptic segmentation | 9 | 1 | -| `facebook/mask2former-swin-large-ade` | Panoptic segmentation | 16 | 1 | -| `PekingU/rtdetr_r18vd` | Fast detection | 10 | 1 | -| `ByteTrackWrapper` | Multi-object tracking | 10, 12 | 2 | +| Model | Type | Scenarios | Total Uses | +| -------------------------------------------- | ------------------------ | ------------------------------- | ---------- | +| `IDEA-Research/grounding-dino-tiny` | Zero-shot detection | 1, 2, 6, 11, 13, 14, 15, 17, 18 | 9 | +| `openai/clip-vit-base-patch32` | Zero-shot classification | 1, 5, 7, 9, 15, 20 | 6 | +| `facebook/sam-vit-base` | Prompt segmentation | 2, 6, 13, 17, 18 | 5 | +| `Qwen/Qwen3-VL-2B-Instruct` | Vision-Language Model | 3, 4, 7, 11, 13, 14, 19, 20 | 8 | +| `facebook/detr-resnet-50` | Object detection | 3, 4, 7, 8, 9, 12, 20 | 7 | +| `depth-anything/Depth-Anything-V2-Small-hf` | Depth estimation | 8, 9, 11, 16 | 4 | +| `torchvision/fasterrcnn_resnet50_fpn_v2` | Object detection | 5, 12 | 2 | +| `facebook/mask2former-swin-large-cityscapes` | Panoptic segmentation | 9 | 1 | +| `facebook/mask2former-swin-large-ade` | Panoptic segmentation | 16 | 1 | +| `PekingU/rtdetr_r18vd` | Fast detection | 10 | 1 | +| `ByteTrackWrapper` | Multi-object tracking | 10, 12 | 2 | ### Model Substitutions Most scenarios support model substitutions: **Detection**: + - `facebook/detr-resnet-50` ↔ `PekingU/rtdetr_r18vd` (faster) - `IDEA-Research/grounding-dino-tiny` ↔ `IDEA-Research/grounding-dino-base` (better accuracy) **Classification**: + - `openai/clip-vit-base-patch32` ↔ `openai/clip-vit-large-patch14` (better accuracy) **Segmentation**: + - `facebook/sam-vit-base` ↔ `facebook/sam-vit-huge` (better quality) - Mask2Former models interchangeable depending on target domain **VLM**: + - `Qwen/Qwen3-VL-2B-Instruct` ↔ `Qwen/Qwen3-VL-7B-Instruct` (better reasoning) --- @@ -1124,11 +1189,11 @@ python retail_stock_level.py --real retail_shelf.jpg ```bash # Install MATA with all dependencies -pip install mata[all] +pip install datamata[all] # Or minimal install + selective model backends -pip install mata[transformers] # HuggingFace models only -pip install mata[torchvision] # Torchvision models only +pip install datamata[transformers] # HuggingFace models only +pip install datamata[torchvision] # Torchvision models only ``` ### Mock vs. Real Mode @@ -1136,12 +1201,14 @@ pip install mata[torchvision] # Torchvision models only Every scenario supports two modes: **Mock Mode** (default): + - No model downloads - Verifies graph construction - Prints expected output structure - **Use for**: Testing, learning, CI/CD **Real Mode** (`--real `): + - Downloads models on first run - Runs actual inference - Returns real results @@ -1154,6 +1221,7 @@ Every scenario supports two modes: ### CPU vs. GPU Scenarios **CPU-Compatible** (acceptable performance on CPU): + - Scenario 1: Defect detection & classification (~2s/image) - Scenario 5: Shelf product analysis (~3s/image) - Scenario 6: Product search (~10s/image) @@ -1161,6 +1229,7 @@ Every scenario supports two modes: - Scenario 15: Crop disease classification (~2s/image) **GPU-Recommended** (slow on CPU, practical on GPU): + - Scenario 2: Defect segmentation (~15s CPU, ~500ms GPU) - Scenario 9: Road scene analysis (~60s CPU, ~800ms GPU) - Scenario 16: Aerial crop (~40s CPU, ~600ms GPU) @@ -1168,6 +1237,7 @@ Every scenario supports two modes: - Scenario 18: Medical ROI (~10s CPU, ~500ms GPU) **GPU-Required** (VLM scenarios, impractical on CPU): + - Scenario 3, 4: Manufacturing VLM inspection - Scenario 7: Multi-modal stock assessment - Scenario 11: Obstacle VLM reasoning @@ -1184,12 +1254,12 @@ Every scenario supports two modes: ### VRAM Requirements -| VRAM | Compatible Scenarios | -|------|---------------------| -| **4GB** | 1, 5, 8, 10, 15 (detection + classification) | -| **6GB** | 2, 6, 17, 18 (SAM segmentation) | -| **8GB** | 3, 4, 7, 11, 12, 13, 14, 19, 20 (VLM) | -| **12GB+** | 9, 16 (Mask2Former panoptic) | +| VRAM | Compatible Scenarios | +| --------- | -------------------------------------------- | +| **4GB** | 1, 5, 8, 10, 15 (detection + classification) | +| **6GB** | 2, 6, 17, 18 (SAM segmentation) | +| **8GB** | 3, 4, 7, 11, 12, 13, 14, 19, 20 (VLM) | +| **12GB+** | 9, 16 (Mask2Former panoptic) | ### Optimization Tips @@ -1248,11 +1318,13 @@ Every scenario supports two modes: All scenarios are built from 22 reusable nodes. To create your own: 1. **Identify your workflow**: + ``` Input → Task1 → Transform → Task2 → Output ``` 2. **Select appropriate nodes**: + ```python from mata.core.graph.graph import Graph from mata.nodes.detect import Detect @@ -1260,6 +1332,7 @@ All scenarios are built from 22 reusable nodes. To create your own: ``` 3. **Compose the graph**: + ```python graph = ( Graph("my_scenario") @@ -1333,6 +1406,7 @@ pytest tests/ -v ## Version History **v1.6.1** (February 15, 2026): + - ✅ 20 production scenarios across 6 industries - ✅ 12 new preset functions (manufacturing, retail, driving, surveillance, agriculture, general) - ✅ 88 comprehensive preset tests (all passing) @@ -1341,6 +1415,7 @@ pytest tests/ -v - ✅ Zero-shot capabilities with GroundingDINO and CLIP **v1.6.0**: + - Graph system with 22 nodes - 8 initial presets (VLM, detection+segmentation, full scene analysis) - 2185 tests passing (>80% coverage) @@ -1353,6 +1428,7 @@ pytest tests/ -v **Model Licenses**: Vary by model (HuggingFace, Meta, OpenAI, etc. — see model cards) **Model Acknowledgments**: + - GroundingDINO: IDEA-Research (Apache 2.0) - CLIP: OpenAI (MIT) - SAM: Meta AI (Apache 2.0) @@ -1371,14 +1447,14 @@ pytest tests/ -v ## Appendix: All 20 Scenarios At A Glance -| Industry | Count | Key Capabilities | -|----------|-------|-----------------| -| **Manufacturing** | 4 | Zero-shot defect detection, VLM assembly verification, per-component inspection | -| **Retail** | 3 | Shelf monitoring, zero-shot product search, multi-modal stock assessment | -| **Driving** | 4 | Distance estimation, 4-way scene analysis, real-time tracking, VLM hazard reasoning | -| **Security** | 3 | Crowd tracking, suspicious object detection with VLM, situational awareness | -| **Agriculture** | 3 | Disease classification, aerial segmentation + depth, pest mapping | -| **Healthcare** | 3 | ROI segmentation, report generation, conditional triage workflow | +| Industry | Count | Key Capabilities | +| ----------------- | ----- | ----------------------------------------------------------------------------------- | +| **Manufacturing** | 4 | Zero-shot defect detection, VLM assembly verification, per-component inspection | +| **Retail** | 3 | Shelf monitoring, zero-shot product search, multi-modal stock assessment | +| **Driving** | 4 | Distance estimation, 4-way scene analysis, real-time tracking, VLM hazard reasoning | +| **Security** | 3 | Crowd tracking, suspicious object detection with VLM, situational awareness | +| **Agriculture** | 3 | Disease classification, aerial segmentation + depth, pest mapping | +| **Healthcare** | 3 | ROI segmentation, report generation, conditional triage workflow | **Total Presets**: 20 (8 existing + 12 new) **Total Graph Nodes**: 22 diff --git a/docs/VALIDATION_GUIDE.md b/docs/VALIDATION_GUIDE.md index a3af987..4ef4440 100644 --- a/docs/VALIDATION_GUIDE.md +++ b/docs/VALIDATION_GUIDE.md @@ -121,7 +121,7 @@ def val( | Parameter | Type | Default | Description | | -------------- | ------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------ | -| `task` | `str` | _required_ | One of `"detect"`, `"segment"`, `"classify"`, `"depth"`, `"ocr"` | +| `task` | `str` | _required_ | One of `"detect"`, `"segment"`, `"classify"`, `"depth"`, `"ocr"` | | `model` | `str \| adapter \| None` | `None` | HuggingFace ID, local path, config alias, or a pre-loaded adapter. Required when `predictions` is not given. | | `data` | `str \| dict \| None` | `None` | Path to a dataset YAML file, or dict with equivalent keys. Required when `predictions` is not given. | | `predictions` | `list \| None` | `None` | Pre-computed `VisionResult`/`ClassifyResult`/`DepthResult` list (standalone mode). | @@ -202,8 +202,8 @@ annotations: diode_val_annotations.json # {rgb_path: depth_npy_path} mapping ```yaml # examples/configs/coco_text.yaml path: /data/coco-text -val: val2014 # COCO 2014 validation images directory -annotations: cocotext_v2.json # COCO-Text annotations with "text" field per annotation +val: val2014 # COCO 2014 validation images directory +annotations: cocotext_v2.json # COCO-Text annotations with "text" field per annotation names: 0: text ``` @@ -212,10 +212,23 @@ The annotation JSON must follow COCO-Text format — each annotation dict contai ```json { - "images": [{"id": 1, "file_name": "COCO_val2014_000001.jpg", "width": 640, "height": 480}], - "categories": [{"id": 1, "name": "text"}], + "images": [ + { + "id": 1, + "file_name": "COCO_val2014_000001.jpg", + "width": 640, + "height": 480 + } + ], + "categories": [{ "id": 1, "name": "text" }], "annotations": [ - {"id": 1, "image_id": 1, "category_id": 1, "bbox": [100, 200, 50, 20], "text": "STOP"} + { + "id": 1, + "image_id": 1, + "category_id": 1, + "bbox": [100, 200, 50, 20], + "text": "STOP" + } ] } ``` @@ -565,18 +578,18 @@ from mata import OCRMetrics # or: from mata.eval import OCRMetrics #### Configuration Fields -| Field | Type | Default | Description | -| ---------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------ | +| Field | Type | Default | Description | +| ---------------- | ------ | ------- | -------------------------------------------------------------------------------------------------------------- | | `case_sensitive` | `bool` | `False` | When `False` (default), both predicted and GT text are lowercased before comparison. Matches ICDAR convention. | #### Metric Fields -| Field | Type | Description | -| ---------- | ------------------ | ----------------------------------------------------------------------------------------------- | -| `cer` | `float` | Mean Character Error Rate: $\text{CER} = \frac{\text{Levenshtein}(pred, gt)}{\max(|gt|, 1)}$ | -| `wer` | `float` | Mean Word Error Rate: $\text{WER} = \frac{\text{Levenshtein}(pred_{words}, gt_{words})}{\max(|gt_{words}|, 1)}$ | +| Field | Type | Description | +| ---------- | ------------------ | ----------------------------------------------------------------------------------------------------------- | ----------- | ------ | +| `cer` | `float` | Mean Character Error Rate: $\text{CER} = \frac{\text{Levenshtein}(pred, gt)}{\max( | gt | , 1)}$ | +| `wer` | `float` | Mean Word Error Rate: $\text{WER} = \frac{\text{Levenshtein}(pred*{words}, gt*{words})}{\max( | gt\_{words} | , 1)}$ | | `accuracy` | `float` | Exact-match accuracy: $\frac{\text{count}(pred = gt)}{N}$ — fraction of images with identical transcription | -| `speed` | `dict[str, float]` | Timing breakdown per image | +| `speed` | `dict[str, float]` | Timing breakdown per image | #### Key Methods @@ -596,21 +609,21 @@ metrics.update(pred_text, gt_text) #### Properties -| Property | Returns | Description | -| ---------------------- | ----------- | ---------------------------------------- | -| `metrics.fitness` | `float` | `accuracy` (exact-match ratio) | -| `metrics.keys` | `list[str]` | 3 metric key names | -| `metrics.results_dict` | `dict` | 4 entries (3 metrics + fitness) | +| Property | Returns | Description | +| ---------------------- | ----------- | ------------------------------- | +| `metrics.fitness` | `float` | `accuracy` (exact-match ratio) | +| `metrics.keys` | `list[str]` | 3 metric key names | +| `metrics.results_dict` | `dict` | 4 entries (3 metrics + fitness) | #### Methods -| Method | Returns | Description | -| ---------------- | ------------ | ----------------------------------------- | -| `mean_results()` | `list[float]`| `[cer, wer, accuracy]` | -| `summary()` | `list[dict]` | Single-row summary with all metrics | -| `to_dict()` | `dict` | Full results dict | -| `to_json()` | `str` | JSON string | -| `to_csv()` | `str` | CSV string (header + one data row) | +| Method | Returns | Description | +| ---------------- | ------------- | ----------------------------------- | +| `mean_results()` | `list[float]` | `[cer, wer, accuracy]` | +| `summary()` | `list[dict]` | Single-row summary with all metrics | +| `to_dict()` | `dict` | Full results dict | +| `to_json()` | `str` | JSON string | +| `to_csv()` | `str` | CSV string (header + one data row) | #### `case_sensitive` Parameter @@ -1139,11 +1152,11 @@ Appearance-Based Re-Identification (ReID) in MATA enhances BotSort's track-recov ### What ReID Adds Without ReID, BotSort associates detections to tracks using two cues: + 1. **IoU** — spatial overlap between predicted and detected bounding boxes 2. **GMC** — global motion compensation (sparse optical flow) for camera motion -With ReID enabled (`reid_model=...`), a third cue is added: -3. **Cosine appearance distance** — L2-normalised embedding vectors extracted from detection crops are compared against cached track features (`smooth_feat`) +With ReID enabled (`reid_model=...`), a third cue is added: 3. **Cosine appearance distance** — L2-normalised embedding vectors extracted from detection crops are compared against cached track features (`smooth_feat`) This allows BotSort to re-associate tracks even when the predicted position drifts significantly due to occlusion gaps. @@ -1230,14 +1243,14 @@ if matches: ### ReID Validation Tips -| Scenario | Recommended Approach | -| -------- | -------------------- | -| Verify embeddings are populated | Check `inst.embedding is not None` after `update()` | -| Measure track-recovery rate | Count frames where a lost track recovers its original ID | -| Tune appearance threshold | Adjust `appearance_thresh` in `tracker_config` (BotSort default: 0.25) | -| Reduce false re-associations | Increase `reid_model` → use a more discriminative encoder (e.g., OSNet vs CLIP) | -| GPU inference for ReID | Pass `device="cuda"` at `mata.load("track", ..., device="cuda")` | -| ONNX production deployment | Export your ReID model to ONNX and pass the `.onnx` path as `reid_model` | +| Scenario | Recommended Approach | +| ------------------------------- | ------------------------------------------------------------------------------- | +| Verify embeddings are populated | Check `inst.embedding is not None` after `update()` | +| Measure track-recovery rate | Count frames where a lost track recovers its original ID | +| Tune appearance threshold | Adjust `appearance_thresh` in `tracker_config` (BotSort default: 0.25) | +| Reduce false re-associations | Increase `reid_model` → use a more discriminative encoder (e.g., OSNet vs CLIP) | +| GPU inference for ReID | Pass `device="cuda"` at `mata.load("track", ..., device="cuda")` | +| ONNX production deployment | Export your ReID model to ONNX and pass the `.onnx` path as `reid_model` | ### Known Limitations (ReID) @@ -1249,4 +1262,4 @@ if matches: 4. **Embedding warm-up:** BotSort's `smooth_feat` is a running average that stabilises after ~5 frames. Track re-association quality may be lower for newly initialised tracks. -5. **Valkey dependency for `ReIDBridge`:** `ReIDBridge` requires `pip install mata[valkey]` (or `mata[redis]`). If the server is unreachable, `publish()` / `query()` log a warning and return gracefully — tracking continues unaffected. \ No newline at end of file +5. **Valkey dependency for `ReIDBridge`:** `ReIDBridge` requires `pip install datamata[valkey]` (or `datamata[redis]`). If the server is unreachable, `publish()` / `query()` log a warning and return gracefully — tracking continues unaffected. diff --git a/docs/VALKEY_GUIDE.md b/docs/VALKEY_GUIDE.md index c0074c3..9c928e9 100644 --- a/docs/VALKEY_GUIDE.md +++ b/docs/VALKEY_GUIDE.md @@ -27,8 +27,8 @@ MATA supports [Valkey](https://valkey.io/) (the open-source Redis fork) and Redis via optional extras: ```bash -pip install mata[valkey] # valkey-py >= 6.0.0 (recommended) -pip install mata[redis] # redis-py >= 5.0.0 (alternative, wire-compatible) +pip install datamata[valkey] # valkey-py >= 6.0.0 (recommended) +pip install datamata[redis] # redis-py >= 5.0.0 (alternative, wire-compatible) ``` Both clients are optional — `import mata` succeeds without either installed. An `ImportError` with an actionable message is raised only when a storage operation is actually executed. @@ -660,13 +660,13 @@ async def async_export(result, url, key, ttl=None): ``` ImportError: Valkey export requires 'valkey' or 'redis' package. -Install with: pip install mata[valkey] or pip install mata[redis] +Install with: pip install datamata[valkey] or pip install datamata[redis] ``` **Solution:** ```bash -pip install mata[valkey] # or pip install mata[redis] +pip install datamata[valkey] # or pip install datamata[redis] ``` This error only occurs when a storage operation is actually called — `import mata` succeeds without either package. diff --git a/examples/classify/clip_zeroshot.py b/examples/classify/clip_zeroshot.py index 3d99118..2052247 100644 --- a/examples/classify/clip_zeroshot.py +++ b/examples/classify/clip_zeroshot.py @@ -17,7 +17,7 @@ - Any HuggingFace CLIP-compatible model Requirements: - pip install mata transformers pillow + pip install datamata transformers pillow Usage: python examples/classify/clip_zeroshot.py diff --git a/examples/detect/zeroshot_detection.py b/examples/detect/zeroshot_detection.py index cf05736..9b275c1 100644 --- a/examples/detect/zeroshot_detection.py +++ b/examples/detect/zeroshot_detection.py @@ -10,7 +10,7 @@ - OWL-ViT v2 (Google): Best speed/accuracy tradeoff Requirements: - pip install mata transformers pillow + pip install datamata transformers pillow Usage: python examples/detect/zeroshot_detection.py diff --git a/examples/graph/scenarios/README.md b/examples/graph/scenarios/README.md index 567a411..05f95a2 100644 --- a/examples/graph/scenarios/README.md +++ b/examples/graph/scenarios/README.md @@ -217,11 +217,11 @@ scenarios/ ```bash # Install MATA with all dependencies -pip install mata[all] +pip install datamata[all] # Or install specific model types -pip install mata[transformers] # HuggingFace models -pip install mata[torchvision] # Torchvision models +pip install datamata[transformers] # HuggingFace models +pip install datamata[torchvision] # Torchvision models ``` ## Support diff --git a/examples/graph/valkey_pipeline.py b/examples/graph/valkey_pipeline.py index 8ece4d6..70fd338 100644 --- a/examples/graph/valkey_pipeline.py +++ b/examples/graph/valkey_pipeline.py @@ -15,7 +15,7 @@ server required). When running against a real server, pass ``--real``. Requirements: - pip install mata[valkey] # or mata[redis] + pip install datamata[valkey] # or datamata[redis] Usage: # Mock mode — fully self-contained, no server needed @@ -372,7 +372,7 @@ def main(): if use_real: print(f"Running against real Valkey server: {url}") - print("Make sure valkey-py is installed: pip install mata[valkey]") + print("Make sure valkey-py is installed: pip install datamata[valkey]") providers = create_real_providers() else: print("Running in MOCK mode (in-memory store, no server required)") diff --git a/examples/graph/valkey_rtsp_pipeline.py b/examples/graph/valkey_rtsp_pipeline.py index 2ea2fcc..af720e8 100644 --- a/examples/graph/valkey_rtsp_pipeline.py +++ b/examples/graph/valkey_rtsp_pipeline.py @@ -11,8 +11,8 @@ A round-trip verification load is performed after the loop. Requirements: - pip install mata[valkey] # Valkey / Redis client - pip install mata opencv-python # RTSP frame capture + pip install datamata[valkey] # Valkey / Redis client + pip install datamata opencv-python # RTSP frame capture Usage: python examples/graph/rtsp_pipeline.py @@ -163,7 +163,7 @@ def main(): print(f"Valkey server : {url}") print(f"RTSP source : {rtsp_url}") - print("Make sure valkey-py is installed: pip install mata[valkey]") + print("Make sure valkey-py is installed: pip install datamata[valkey]") tracker = create_tracker(rtsp_url) run(url=url, rtsp_url=rtsp_url, tracker=tracker, frames=frames) diff --git a/examples/segment/grounding_sam_pipeline.py b/examples/segment/grounding_sam_pipeline.py index 1d5d557..2521ec4 100644 --- a/examples/segment/grounding_sam_pipeline.py +++ b/examples/segment/grounding_sam_pipeline.py @@ -8,7 +8,7 @@ Text Prompts > GroundingDINO (bboxes) > SAM (masks) > VisionResult Run: python examples/segment/grounding_sam_pipeline.py -Requirements: pip install mata transformers pillow numpy +Requirements: pip install datamata transformers pillow numpy """ import sys diff --git a/examples/track/basic_tracking.py b/examples/track/basic_tracking.py index 39af5b5..5dc9991 100644 --- a/examples/track/basic_tracking.py +++ b/examples/track/basic_tracking.py @@ -18,7 +18,7 @@ python examples/track/basic_tracking.py --real examples/videos/cup.mp4 Requirements: - pip install mata opencv-python + pip install datamata opencv-python """ from __future__ import annotations diff --git a/examples/track/cross_camera_reid.py b/examples/track/cross_camera_reid.py index d7379c1..4bf24c5 100644 --- a/examples/track/cross_camera_reid.py +++ b/examples/track/cross_camera_reid.py @@ -27,9 +27,9 @@ python examples/track/cross_camera_reid.py --valkey valkey://localhost:6379 Requirements: - pip install mata[valkey] transformers torch + pip install datamata[valkey] transformers torch # or: - pip install mata[redis] transformers torch + pip install datamata[redis] transformers torch """ from __future__ import annotations diff --git a/examples/track/persist_tracking.py b/examples/track/persist_tracking.py index a330f66..98a0fc5 100644 --- a/examples/track/persist_tracking.py +++ b/examples/track/persist_tracking.py @@ -20,7 +20,7 @@ python examples/track/persist_tracking.py --real examples/videos/cup.mp4 Requirements: - pip install mata opencv-python + pip install datamata opencv-python """ from __future__ import annotations diff --git a/examples/track/reid_tracking.py b/examples/track/reid_tracking.py index fbd0e21..299a85e 100644 --- a/examples/track/reid_tracking.py +++ b/examples/track/reid_tracking.py @@ -17,7 +17,7 @@ python examples/track/reid_tracking.py --real examples/videos/cup.mp4 Requirements: - pip install mata transformers torch + pip install datamata transformers torch """ from __future__ import annotations diff --git a/examples/track/stream_tracking.py b/examples/track/stream_tracking.py index 348b550..e4fc8fb 100644 --- a/examples/track/stream_tracking.py +++ b/examples/track/stream_tracking.py @@ -29,7 +29,7 @@ python examples/track/stream_tracking.py --real 0 Requirements: - pip install mata opencv-python + pip install datamata opencv-python """ from __future__ import annotations diff --git a/tests/test_ocr_adapter.py b/tests/test_ocr_adapter.py index 9c27a55..a1e91b0 100644 --- a/tests/test_ocr_adapter.py +++ b/tests/test_ocr_adapter.py @@ -849,7 +849,9 @@ def test_predict_filters_blank_text(self, mock_ensure_easyocr): @patch("mata.adapters.ocr.easyocr_adapter._ensure_easyocr") def test_missing_easyocr_raises_import_error(self, mock_ensure_easyocr): mock_ensure_easyocr.side_effect = ImportError( - "easyocr is required for EasyOCRAdapter. " "Install with: pip install easyocr\n" "or: pip install mata[ocr]" + "easyocr is required for EasyOCRAdapter. " + "Install with: pip install easyocr\n" + "or: pip install datamata[ocr]" ) from mata.adapters.ocr import easyocr_adapter @@ -1028,7 +1030,7 @@ def test_missing_paddleocr_raises_import_error(self, mock_ensure_paddle): mock_ensure_paddle.side_effect = ImportError( "paddleocr is required for PaddleOCRAdapter. " "Install with: pip install paddleocr paddlepaddle\n" - "or: pip install mata[ocr-paddle]\n" + "or: pip install datamata[ocr-paddle]\n" "Note: paddlepaddle GPU wheel is ~500 MB." ) @@ -1359,7 +1361,7 @@ def test_missing_pytesseract_raises_import_error(self, mock_ensure_tesseract): mock_ensure_tesseract.side_effect = ImportError( "pytesseract is required for TesseractAdapter.\n" "Install Python package: pip install pytesseract\n" - "or: pip install mata[ocr-tesseract]\n" + "or: pip install datamata[ocr-tesseract]\n" "Also install the Tesseract binary:\n" " Ubuntu/Debian: sudo apt-get install tesseract-ocr\n" " macOS: brew install tesseract\n" diff --git a/tests/test_valkey_exporter.py b/tests/test_valkey_exporter.py index 6785f7c..d8593d1 100644 --- a/tests/test_valkey_exporter.py +++ b/tests/test_valkey_exporter.py @@ -183,7 +183,7 @@ def test_import_error_no_client(self): # Patch the imports inside the function with patch.dict(sys.modules, {"valkey": None, "redis": None}): - with pytest.raises(ImportError, match="pip install mata"): + with pytest.raises(ImportError, match="pip install datamata"): valkey_exporter._get_valkey_client("valkey://localhost:6379") def test_valkey_client_fallback_to_redis(self): From 75d5a13c8c356a69d076ad765aeca542052b0483 Mon Sep 17 00:00:00 2001 From: Bimantoro Maesa Date: Mon, 9 Mar 2026 20:24:41 +0700 Subject: [PATCH 3/3] Update framework version reference to 'datamata' in Fuse node --- src/mata/nodes/fuse.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/mata/nodes/fuse.py b/src/mata/nodes/fuse.py index e9caca2..030d0b2 100644 --- a/src/mata/nodes/fuse.py +++ b/src/mata/nodes/fuse.py @@ -163,7 +163,7 @@ def _build_provenance(self, ctx: ExecutionContext) -> dict[str, Any]: "timestamp": datetime.now(timezone.utc).isoformat(), "node_type": "Fuse", "node_name": self.name, - "framework_version": f"mata-{importlib.metadata.version('mata')}", + "framework_version": f"mata-{importlib.metadata.version('datamata')}", } # Add model information if available from context