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:

Review deprecation warnings in your logs
Update deep imports to use groundeddino_vl namespace
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 warnings temporarily during migration:

import warnings
warnings.filterwarnings("ignore", category=DeprecationWarning, module="groundingdino")

import groundingdino  # No warning shown

Note: We strongly recommend migrating instead of suppressing warnings.

📚 Documentation Updates

All documentation has been updated to reflect the new architecture:

README.md: Updated feature list and architecture overview
docs/PROJECT_STRUCTURE.md: Documented new minimal groundingdino/ structure
docs/API_REFERENCE.md: Updated import examples and backward compatibility notes
docs/MIGRATION_FROM_GROUNDINGDINO.md: New comprehensive migration guide (2,500+ words)

🐛 Bug Fixes

Fixed version inconsistency: groundingdino.__version__ now correctly references groundeddino_vl.__version__
Fixed package bloat: Removed 9,058 lines of duplicate code
Fixed import confusion: Clear deprecation path guides users to correct namespace

🙏 Credits

This release represents a significant architectural improvement to make GroundedDINO-VL a truly independent, production-ready package.

Contributors:

Architecture design and implementation
Comprehensive testing and validation
Documentation and migration guide

Original GroundingDINO:

Thanks to the original GroundingDINO team for the foundational work
Model weights and architecture remain 100% compatible

📊 Statistics

Code Changes

 37 files changed, 9,058 deletions(-)
 create mode 100644 docs/MIGRATION_FROM_GROUNDINGDINO.md
 delete mode 100644 groundingdino/config/GroundingDINO_SwinT_OGC.py
 delete mode 100644 groundingdino/datasets/__init__.py
 delete mode 100644 groundingdino/datasets/cocodataset.py
 [... 34 more deletions ...]

Package Size

Total reduction: 514.8KB (99.0%)
Files removed: 37
Lines removed: 9,058
Directories cleaned: 4

Test Coverage

Total tests: 47
Passed: 45
Skipped: 2 (CUDA on CPU)
Failed: 0
Coverage: 100% of modified code

🔗 Resources

GitHub Repository: https://github.com/ghostcipher1/GroundedDINO-VL
Documentation: https://github.com/ghostcipher1/GroundedDINO-VL#readme
Migration Guide: docs/MIGRATION_FROM_GROUNDINGDINO.md
API Reference: docs/API_REFERENCE.md
Issue Tracker: https://github.com/ghostcipher1/GroundedDINO-VL/issues

📝 Full Commit History

97a493e refactor: clean up label formatting and remove unused mock outputs in test_api.py
a30e90b refactor: update flake8 configuration and clean up code formatting in multiple files
2e3259b Add batch inference script and testing suite for GroundedDINO-VL
8984927 refactor: improve variable assignment and clean up mock output in test_api.py
0d3f5b5 chore: downgrade version to 1.0.0b1 in version.py
[... previous commits ...]

# v1.1.0 Independence Implementation
- feat: make groundeddino-vl fully independent from groundingdino
- refactor: convert groundingdino to lightweight compatibility shim
- docs: add comprehensive migration guide
- style: apply black formatting
- chore: bump version to 1.1.0

🎉 What's Next

While this release focuses on architectural independence, future releases will bring:

Enhanced model architectures
Performance optimizations
Additional pretrained weights
Expanded API capabilities
More examples and tutorials

Stay tuned for v1.2.0!

📞 Support

If you encounter any issues with the migration or have questions:

Check the Migration Guide
Review the API Reference
Search existing GitHub Issues
Open a new issue with:
- Your use case
- Import errors you're encountering
- Relevant code snippets

We're here to help make your migration smooth!

Released by: GroundedDINO-VL Team
Release Date: November 24, 2025
Version: 1.1.0
License: Apache-2.0

v1.1.0