Skip to content

Troubleshooting

Common issues and solutions for PrimateFace.

Installation Issues

CUDA/GPU Problems

Error: "CUDA out of memory"

Solution: 

# Reduce batch size
processor = PrimateFaceProcessor(batch_size=1)

# Clear GPU cache
import torch
torch.cuda.empty_cache()

# Use CPU instead
processor = PrimateFaceProcessor(device='cpu')

Error: "No CUDA GPUs are available"

Solution: 

# Check CUDA installation
nvcc --version
nvidia-smi

# Install correct PyTorch version
pip install torch==2.1.0 torchvision==0.16.0 --index-url https://download.pytorch.org/whl/cu118

Dependency Conflicts

Error: "Module 'cv2' not found"

Solution: 

pip install opencv-python opencv-contrib-python

Error: "ImportError: cannot import name 'xxx' from 'mmpose'"

Solution: 

# Install specific MMPose version
pip install mmpose==0.29.0 mmdet==2.25.0

Model Loading Issues

Missing Model Files

Error: "Model checkpoint not found"

Solution: 

# Download pretrained models
python demos/download_models.py

# Or specify custom path
processor = PrimateFaceProcessor(
    det_checkpoint="path/to/your/model.pth"
)

Config Mismatch

Error: "Config type mismatch"

Solution: 

# Ensure config matches checkpoint
from demos.constants import DEFAULT_DET_CONFIG, DEFAULT_POSE_CONFIG

processor = PrimateFaceProcessor(
    det_config=DEFAULT_DET_CONFIG,
    pose_config=DEFAULT_POSE_CONFIG
)

Data Format Issues

COCO Format Errors

Error: "Invalid COCO format"

Solution: 

# Validate COCO file
from evals.core.utils import validate_coco

issues = validate_coco("annotations.json")
for issue in issues:
    print(issue)

# Fix common issues
from evals.core.utils import fix_coco_format
fixed_data = fix_coco_format("annotations.json")

Image Loading Problems

Error: "Cannot read image file"

Solution: 

# Check image paths
import os
from pathlib import Path

# Make paths absolute
image_dir = Path("images").absolute()

# Verify images exist
for img in image_list:
    if not os.path.exists(img):
        print(f"Missing: {img}")

GUI Issues

Tkinter Problems

Error: "No module named '_tkinter'"

Solution: 

# Linux
sudo apt-get install python3-tk

# macOS
brew install python-tk

# Windows - reinstall Python with tcl/tk

Display Issues

Error: "Cannot connect to X server"

Solution: 

# SSH with X11 forwarding
ssh -X user@server

# Or use virtual display
export DISPLAY=:0

# Or run without GUI
python process_batch.py --no-gui

Performance Issues

Slow Inference

Solutions: 1. Enable GPU: 

processor = PrimateFaceProcessor(device='cuda:0')

  1. Batch processing: 

    results = processor.process_batch(images, batch_size=8)

  2. Reduce input size: 

    processor = PrimateFaceProcessor(input_size=(640, 480))

Memory Leaks

Solution: 

# Clear cache periodically
import gc
import torch

for batch in data_loader:
    results = process(batch)

    # Clear every 100 batches
    if batch_idx % 100 == 0:
        torch.cuda.empty_cache()
        gc.collect()

Framework-Specific Issues

MMPose/MMDetection

Error: "Registry not found"

Solution: 

# Import required registries
from mmdet.apis import init_detector
from mmpose.apis import init_pose_model

DeepLabCut

Error: "Project config not found"

Solution: 

# Initialize project properly
import deeplabcut
deeplabcut.create_new_project('project', 'author')

SLEAP

Error: "Cannot load SLEAP model"

Solution: 

# Use correct model path structure
model_path = "models/sleap_model.zip"
sleap.load_model(model_path)

Common Runtime Errors

KeyError: 'keypoints'

Solution: 

# Check annotation structure
if 'keypoints' not in annotation:
    annotation['keypoints'] = [0] * (num_keypoints * 3)

ValueError: "too many values to unpack"

Solution: 

# Check return value count
# Wrong:
x, y = function_that_returns_three_values()

# Correct:
x, y, z = function_that_returns_three_values()
# Or:
result = function_that_returns_three_values()
x, y = result[:2]

IndexError: "list index out of range"

Solution: 

# Validate indices
if idx < len(keypoints):
    point = keypoints[idx]
else:
    point = default_value

Data Quality Issues

Poor Detection Results

Checklist: - [ ] Image quality sufficient (>640x480) - [ ] Face clearly visible - [ ] Proper lighting - [ ] Minimal motion blur

Solutions: 

# Preprocess images
from demos.utils import enhance_image
enhanced = enhance_image(img, contrast=1.2, brightness=1.1)

# Adjust detection threshold
processor = PrimateFaceProcessor(det_threshold=0.3)

Inaccurate Landmarks

Solutions: 

# Use higher resolution
processor = PrimateFaceProcessor(pose_input_size=(384, 288))

# Apply smoothing for video
from demos.smooth_utils import smooth_trajectory
smoothed = smooth_trajectory(keypoints, window_size=5)

Getting Help

Before Asking for Help

  1. Check documentation
  2. User Guide
  3. API Reference

  4. Tutorials

  5. Search existing issues

  6. GitHub Issues

  7. Gather information 

    import sys
import torch
print(f"Python: {sys.version}")
print(f"PyTorch: {torch.__version__}")
print(f"CUDA: {torch.cuda.is_available()}")

Reporting Issues

Include: - Error message (full traceback) - Code snippet - Environment details - Sample data (if possible)

Community Support

See Also