Fix: Make decord import lazy to prevent cv2.imshow() segfault

[mattiagaggi]

Fix: Make decord import lazy to prevent cv2.imshow() segfault

fixed #228

Problem

When importing the sam3 library, calling cv2.imshow() throws a segmentation fault, even without calling any sam3 interface.

Example that causes the issue:

import cv2
from sam3.model_builder import build_sam3_image_model

video_path = "02.mp4"
cap = cv2.VideoCapture(video_path)
# ... 
cv2.imshow('Original Frame', frame)  # Segfaults here

Root Cause

The issue is in sam3/train/data/sam3_image_dataset.py which has a module-level import of decord:

from decord import cpu, VideoReader  # Line 18 - executes on import

When sam3_image_dataset.py is imported (which happens when importing sam3.model_builder), the decord import is executed immediately at module load time. This causes a conflict with OpenCV's initialization, leading to a segmentation fault when cv2.imshow() is called.

Solution

Make the decord import lazy - only import it when actually needed (inside the function that uses it), not at module level.

Changes

1. Removed module-level import (line 18):

   • Before: from decord import cpu, VideoReader (at module level)
   • After: Removed; only comments remain

2. Added lazy import inside _load_images() method:

   • Decord is now imported only when processing .mp4 files
   • Wrapped in try/except for proper error handling
   • Only executes when actually needed

Code Changes

# Before (module level - problematic):
from decord import cpu, VideoReader

# After (lazy import - fixed):
# Inside _load_images() method:
if ".mp4" in path and path[-4:] == ".mp4":
    # Lazy import decord only when needed to avoid conflicts with OpenCV
    try:
        from decord import cpu, VideoReader
    except ImportError:
        raise ImportError(
            "decord is required for video loading but is not installed. "
            "Install it with: pip install decord or pip install -e '.[notebooks]'"
        )
    # ... use decord

Impact

• ✅ Before fix: Importing sam3 causes decord to load → conflicts with OpenCV → cv2.imshow() segfaults
• ✅ After fix: Importing sam3 does NOT load decord → OpenCV works normally → decord only loads when actually needed for video loading

Testing

The fix ensures:

• Importing sam3 does not load decord
• cv2.imshow() works normally after importing sam3
• Video loading still works when needed (decord loads on demand)

Related Issues

This fixes the issue reported where importing sam3 causes cv2.imshow() to segfault.

[drduhe]

Looks good to me - I am wondering if we might want to add some troubleshooting step to the README to inform users that the video components might not work correctly when running locally in an env that doesn't support decord.