v1.1.1

Enhancements

• Added support for PyTorch 2.9.
• Added support for CUDA 13.0

Fixes

• Resolved issues with black and flake8.
• Resolved various security issues.

v1.1.0

GroundedDINO-VL v1.1.0 Release Notes

Release Date: November 24, 2025
Type: Minor Release
Status: Production Ready

🎯 Release Highlights

This release marks a major architectural milestone: GroundedDINO-VL is now fully independent from the legacy GroundingDINO implementation.

Key Achievements

• ✅ 9,058 lines of duplicate code removed
• ✅ 99% size reduction in legacy namespace (520KB → 5.2KB)
• ✅ Single source of truth - all code now in groundeddino_vl/
• ✅ Full backward compatibility maintained for public API
• ✅ 100% model weight compatibility with GroundingDINO
• ✅ Clean deprecation path with comprehensive migration guide

---

🚀 What's New

Full Independence from Legacy Code

GroundedDINO-VL now has a clean, modern codebase with all implementation in the groundeddino_vl/ namespace. The groundingdino/ namespace has been converted from a vendored legacy implementation into a lightweight compatibility shim.

Before:

• groundingdino/: 520KB, 31 Python files, 9,058 lines of vendored code
• Duplicate implementations across two namespaces
• Unclear which namespace to use

After:

• groundingdino/: 5.2KB, 2 Python files (compatibility shim)
• Single source of truth in groundeddino_vl/
• Clear migration path with deprecation warnings

Package Size Reduction

Component	Before	After	Reduction
groundingdino/	520KB (31 files)	5.2KB (2 files)	99.0%
Total lines removed	9,058 lines	-	-
Directories deleted	4 (config/, datasets/, models/, util/)	-	-

Maintained Backward Compatibility

The sophisticated re-export shim in groundingdino/__init__.py ensures existing code continues to work:

API Type	Status	Example
High-level API	✅ Still works	from groundingdino import load_model, predict
Module-level access	✅ Still works	from groundingdino import models, util, datasets
CUDA extension	✅ Still works	import groundingdino._C
Deep imports	❌ No longer supported	from groundingdino.util.misc import NestedTensor

Note: Deep imports must now use groundeddino_vl namespace. See Migration Guide.

---

📋 Detailed Changelog

Breaking Changes

⚠️ Deep imports from groundingdino namespace no longer work:

# ❌ No longer works
from groundingdino.util.misc import NestedTensor
from groundingdino.datasets.transforms import Compose
from groundingdino.models import build_model

# ✅ Use groundeddino_vl instead
from groundeddino_vl.utils.misc import NestedTensor
from groundeddino_vl.data.transforms import Compose
from groundeddino_vl.models import build_model

Impact: Users who import internal modules directly must update their imports. The high-level API remains unchanged.

Removed

• 37 legacy implementation files deleted from groundingdino/:
  • groundingdino/config/ - Configuration files (1 file)
  • groundingdino/datasets/ - Dataset implementations (7 files)
  • groundingdino/models/ - Model implementations (17 files, including CUDA sources)
  • groundingdino/util/ - Utility functions (12 files)

Changed

• groundingdino/version.py: Now imports version from groundeddino_vl instead of hardcoding
• pyproject.toml: Updated package configuration to only include top-level groundingdino module
• tests/test_import.py: Removed test_import_datasets_transforms test (deep imports no longer supported)

Added

• docs/MIGRATION_FROM_GROUNDINGDINO.md: Comprehensive migration guide with:
  • Quick reference table for common import patterns
  • Examples of what still works vs. what doesn't
  • Automated migration script
  • FAQ section
• Version 1.1.0: Bumped from 1.0.0b2 to 1.1.0 (production ready)

Fixed

• Version consistency: groundingdino.__version__ now always matches groundeddino_vl.__version__
• Package size: Eliminated 99% of redundant code from groundingdino/ namespace
• Code formatting: Applied black formatting to all modified files

---

📖 Migration Guide

Quick Migration Reference

Most users won't need to change anything. If you're using the high-level API, your code will continue to work with deprecation warnings.

High-Level API (No Changes Needed)

# ✅ Still works (shows deprecation warning)
from groundingdino import load_model, predict, load_image, annotate

model = load_model(config_path, checkpoint_path)
image = load_image(image_path)
result = predict(model, image, "cat . dog")

# ✅ Recommended: Migrate to groundeddino_vl
from groundeddino_vl import load_model, predict, load_image, annotate

Internal Module Access (Requires Changes)

# ❌ No longer works
from groundingdino.util.misc import NestedTensor
from groundingdino.datasets.transforms import Compose
from groundingdino.models import build_model

# ✅ Use groundeddino_vl instead
from groundeddino_vl.utils.misc import NestedTensor
from groundeddino_vl.data.transforms import Compose
from groundeddino_vl.models import build_model

Module Name Changes

Note these namespace differences:

Old (groundingdino)	New (groundeddino_vl)
util	utils
datasets	data
models.GroundingDINO	models.grounding_dino

Automated Migration Script

For projects with many files, use this script to automatically update imports:

#!/bin/bash
# migrate_to_groundeddino_vl.sh

find . -name "*.py" -type f -exec sed -i \
  -e 's/from groundingdino\.util\./from groundeddino_vl.utils./g' \
  -e 's/from groundingdino\.datasets\./from groundeddino_vl.data./g' \
  -e 's/from groundingdino\.models\./from groundeddino_vl.models./g' \
  -e 's/import groundingdino\.util/import groundeddino_vl.utils/g' \
  -e 's/import groundingdino\.datasets/import groundeddino_vl.data/g' \
  -e 's/import groundingdino\.models/import groundeddino_vl.models/g' \
  -e 's/import groundingdino\._C/import groundeddino_vl._C/g' \
  {} \;

echo "Migration complete! Review changes before committing."

Important: Always review automated changes before committing.

Full Migration Documentation

For detailed migration instructions, examples, and FAQ, see:

• docs/MIGRATION_FROM_GROUNDINGDINO.md

---

🔧 Technical Details

Architecture Changes

Before v1.1.0:

groundeddino-vl/
├── groundingdino/          (520KB - vendored legacy implementation)
│   ├── config/
│   ├── datasets/
│   ├── models/
│   └── util/
└── groundeddino_vl/        (13MB - modern implementation)
    ├── data/
    ├── models/
    └── utils/

After v1.1.0:

groundeddino-vl/
├── groundingdino/          (5.2KB - compatibility shim only)
│   ├── __init__.py        (sophisticated re-export shim)
│   └── version.py         (version reference)
└── groundeddino_vl/        (13MB - single source of truth)
    ├── data/
    ├── models/
    └── utils/

Backward Compatibility Matrix

Import Pattern	v1.0.0b2	v1.1.0	Notes
from groundingdino import load_model	✅ Works	✅ Works	Deprecation warning in v1.1.0
from groundingdino import models	✅ Works	✅ Works	Module-level access maintained
from groundingdino.util.misc import NestedTensor	✅ Works	❌ ImportError	Must use groundeddino_vl.utils.misc
from groundeddino_vl import load_model	✅ Works	✅ Works	Recommended approach
from groundeddino_vl.utils.misc import NestedTensor	✅ Works	✅ Works	Recommended approach

Testing

All tests pass with the new architecture:

pytest tests/ -v
# Result: 45 passed, 2 skipped (CUDA tests on CPU)

Key test coverage:

• ✅ Import compatibility (tests/test_import.py)
• ✅ Backward compatibility (tests/test_import_names.py)
• ✅ Model loading and inference (tests/test_api.py)
• ✅ Batch inference (tests/test_batch_inference.py)
• ✅ CUDA extension loading (when available)

Model Weight Compatibility

100% compatible - All GroundingDINO model weights continue to work:

• ✅ groundingdino_swint_ogc.pth
• ✅ groundingdino_swinb_cogcoor.pth
• ✅ Custom fine-tuned weights

No retraining or weight conversion needed.

---

🛠️ Installation & Upgrade

Fresh Installation

pip install groundeddino-vl==1.1.0

Upgrading from v1.0.0b2

pip install --upgrade groundeddino-vl

Important: After upgrading:

1. Review deprecation warnings in your logs
2. Update deep imports to use groundeddino_vl namespace
3. Run your test suite to identify any import issues

Development Installation

git clone https://github.com/ghostcipher1/GroundedDINO-VL.git
cd GroundedDINO-VL
pip install -e . --no-build-isolation

---

⚠️ Deprecation Notices

Current Deprecations

The groundingdino namespace is now deprecated for all new code. While the high-level API continues to work via the compatibility shim, users will see deprecation warnings:

import groundingdino
# DeprecationWarning: The 'groundingdino' namespace is deprecated.
# Please migrate to 'groundeddino_vl'.
# See docs/MIGRATION_FROM_GROUNDINGDINO.md for migration guide.

Timeline

• v1.1.0 (current): Deprecation warnings added, compatibility shim maintained
• Future versions: Compatibility shim will be maintained indefinitely for backward compatibility
• Recommendation: Migrate to groundeddino_vl at your convenience

Suppressing Warnings (Not Recommended)

If you need to suppress w...

v1.0.0b1

Release Notes - v1.0.0b1

GroundedDINO-VL Beta Release

Release Date: 2025-11-20
Version: 1.0.0b1

---

🚀 Highlights

The first beta release of GroundedDINO-VL, a modernized vision-language framework for zero-shot object detection. Built on PyTorch 2.7 with full CUDA 12.8 support, providing a production-ready implementation of GroundingDINO with improved architecture and developer experience.

---

✨ Key Features

• Modern Stack: Full support for PyTorch 2.7 and CUDA 12.8
• Zero-Shot Detection: Detect objects using natural language descriptions with state-of-the-art accuracy (52.5 AP on COCO)
• Label Studio Integration: Production-ready ML backend for real-time auto-annotation workflows
• Clean API: Simplified high-level API (load_model, predict, annotate) with backward compatibility
• Robust Architecture: Graceful fallback mechanisms for CUDA/CPU environments
• Docker Support: Complete Docker Compose setup for Label Studio integration

---

🔧 Improvements & Bug Fixes

• Fixed import path inconsistencies - Standardized module imports across the codebase
• Enhanced C++/CUDA ops loading - Added robust error handling with automatic PyTorch fallback when CUDA extensions are unavailable
• Updated deprecated dependencies - Migrated from deprecated timm.models.layers to timm.layers
• Optimized imports - Moved heavy dependencies (cv2, supervision) to lazy loading for better compatibility
• Improved error messages - More informative errors with actionable debugging instructions

---

📦 Installation

Via PyPI (Recommended)

pip install groundeddino-vl

With CUDA 12.8 Support

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128
pip install groundeddino-vl

Docker Deployment

docker-compose up -d

---

🔗 Quick Links

• Documentation: Installation Guide | Quick Start | API Reference
• Label Studio: Integration Guide
• GitHub: Repository
• PyPI: groundeddino-vl

---

📋 Requirements

• Python 3.9, 3.10, 3.11, or 3.12
• PyTorch 2.7.0+
• CUDA 12.6 or 12.8 (optional, for GPU support)
• C++17 compatible compiler (GCC 7+, Clang 5+, or MSVC 2019+)

---

🙏 Acknowledgments

Based on the groundbreaking work by IDEA Research's GroundingDINO. Licensed under Apache 2.0.

---

Full changelog and detailed migration guide available in the documentation.