Grounding DINO Python Wrapper

Common errors

• ModuleNotFoundError: No module named 'GroundingDINO'

  cause Attempting to use import paths from the original GroundingDINO repository (e.g., IDEA-Research/GroundingDINO) instead of the `groundingdino-py` wrapper.
  fix Change the import statement to `from groundingdino import GroundingDINO`.

• RuntimeError: CUDA error: out of memory

  cause Processing images that are too large, running multiple GPU-intensive tasks, or using a GPU with insufficient VRAM for the model.
  fix Reduce the input image size, free up GPU memory by closing other applications, or use a GPU with more VRAM. For `groundingdino-py[cuda]`, consider installing `xformers` for potential memory optimization.

• AttributeError: 'GroundingDINO' object has no attribute 'predict'

  cause Using a method name (e.g., `predict`) that exists in the original GroundingDINO project but not in the `groundingdino-py` wrapper, or an older/incompatible version of the wrapper.
  fix Refer to the `groundingdino-py` documentation and use the correct method, which is `model.predict_image()`.

• `torch.cuda.is_available()` returns False` despite having a GPU.

  cause `groundingdino-py[cuda]` was not installed, or the installed `torch` version is not compatible with your CUDA toolkit or GPU drivers.
  fix Reinstall with `pip install --force-reinstall groundingdino-py[cuda]`. Ensure your CUDA toolkit and GPU drivers are up to date and compatible with the PyTorch version installed. Check `torch.version.cuda`.

Warnings

• breaking The `groundingdino-py` wrapper uses different import paths and method names compared to the original GroundingDINO repository (IDEA-Research/GroundingDINO). Direct copy-pasting code from the original project will likely fail.
  Fix: Always refer to the `groundingdino-py` documentation and examples for correct imports (e.g., `from groundingdino import GroundingDINO`) and method calls (e.g., `model.predict_image()`).
• gotcha For GPU acceleration, you must install the library with the `[cuda]` extra (e.g., `pip install groundingdino-py[cuda]`). This requires a compatible PyTorch installation and CUDA toolkit on your system.
  Fix: Ensure your system has CUDA drivers and toolkit installed. Then, install with `pip install groundingdino-py[cuda]`. Verify GPU availability with `import torch; print(torch.cuda.is_available())`.
• gotcha The Grounding DINO model weights (approx. 2GB) are downloaded automatically on the first instantiation of the `GroundingDINO()` class. This requires an active internet connection and can take some time.
  Fix: Be prepared for a delay and network activity on the first run. Ensure sufficient disk space and a stable internet connection. Subsequent runs will load weights from cache.
• gotcha Grounding DINO models are computationally intensive. Running inference on a CPU will be significantly slower than on a dedicated GPU.
  Fix: For practical applications and better performance, a GPU is highly recommended. Install with `groundingdino-py[cuda]` and ensure PyTorch is configured correctly for your GPU.

Install

• pip install groundingdino-py For CPU inference
• pip install groundingdino-py[cuda] For GPU inference (requires compatible PyTorch and CUDA)

Imports

• GroundingDINO
  wrong:

  from GroundingDINO import groundingdino_model

  correct:

  from groundingdino import GroundingDINO

  This wrapper uses a simplified import path compared to the original GroundingDINO project (IDEA-Research/GroundingDINO).

Quickstart

Initializes the GroundingDINO model, downloads a sample image (if not present), and performs open-set object detection using a text prompt. The model weights are downloaded automatically on the first instantiation. The `predict_image` method returns bounding box coordinates, confidence scores, and the corresponding detected phrases.

import os
from groundingdino import GroundingDINO

# Instantiate the model
model = GroundingDINO() # Weights are downloaded on first run (approx. 2GB)

# Download a sample image (or use your own local path)
image_url = "https://raw.githubusercontent.com/giswqs/groundingdino-py/main/images/dog.jpg"
image_path = "dog.jpg"
if not os.path.exists(image_path):
    print(f"Downloading {image_path}...")
    model.download_file(image_url, image_path) # Helper method from the wrapper

# Define the text prompt
text_prompt = "a dog, a leash"

# Predict objects in the image
# Returns bounding boxes, confidence scores, and detected phrases
boxes, logits, phrases = model.predict_image(image_path, text_prompt)

print(f"Image: {image_path}")
print(f"Text prompt: '{text_prompt}'")
print(f"Detected boxes (xyxy format): {boxes}")
print(f"Confidence scores: {logits}")
print(f"Detected phrases: {phrases}")

# You can also customize confidence thresholds during prediction:
# boxes, logits, phrases = model.predict_image(image_path, text_prompt, box_threshold=0.3, text_threshold=0.25)