Skip to content

QUICKSTART.md

Latest commit

 

History

History
166 lines (115 loc) · 3.2 KB

QUICKSTART.md

File metadata and controls

166 lines (115 loc) · 3.2 KB

smugVision Quick Start Guide

Get up and running with smugVision in 5 minutes!

Prerequisites

  • Python 3.9+
  • SmugMug account with API access
  • Ollama installed

Installation

# 1. Clone the repository
git clone https://github.com/yourusername/smugvision.git
cd smugvision

# 2. Install dependencies
pip install -r requirements.txt

# 3. Install Ollama and pull the model
ollama pull llama3.2-vision

Configuration

Step 1: Get SmugMug Credentials

  1. API Key & Secret:

  2. User Token & Secret:

    python get_smugmug_tokens.py
    • Follow the OAuth flow in your browser
    • Copy the user token and user secret

Step 2: Run Setup

python -m smugvision.config.manager --setup

This creates ~/.smugvision/config.yaml with your settings.

Step 3: (Optional) Setup Face Recognition

# Create reference faces directory
mkdir -p ~/.smugvision/reference_faces

# Organize faces by person
# ~/.smugvision/reference_faces/
#   ├── John_Doe/
#   │   ├── photo1.jpg
#   │   └── photo2.jpg
#   └── Jane_Smith/
#       └── photo1.jpg

# Optimize for faster processing
python optimize_reference_faces.py ~/.smugvision/reference_faces

Usage

Process an Album

By URL:

python -m smugvision --url "https://yoursite.smugmug.com/.../n-XXXXX/album-name"

By Album Key:

python -m smugvision --gallery abc123

Preview Changes (Dry Run)

python -m smugvision --url "https://..." --dry-run

Force Reprocess Already-Tagged Images

python -m smugvision --gallery abc123 --force-reprocess

Include Videos

python -m smugvision --gallery abc123 --include-videos

Verify Installation

Test SmugMug Connection

python test_smugmug.py --url "https://..." --list

Test Vision Model

python test_vision.py path/to/image.jpg

Test Face Recognition

python debug_face_recognition.py path/to/image.jpg

Common Issues

"Ollama not responding"

# Start Ollama
ollama serve

# Verify model is installed
ollama list

"SmugMug authentication failed"

  • Re-run python get_smugmug_tokens.py
  • Verify credentials in ~/.smugvision/config.yaml

"No faces detected"

  • Ensure reference faces directory exists
  • Try lowering face_recognition.tolerance in config
  • Use clear, well-lit photos in reference faces

Next Steps

Example Workflow

# 1. Preview what would be generated
python -m smugvision --url "https://..." --dry-run

# 2. Process the album
python -m smugvision --url "https://..."

# 3. View results in SmugMug
# Captions and tags are now updated!

Support

  • Issues: GitHub Issues
  • Documentation: See README.md and DESIGN.md

Ready to automate your photo metadata? Let's go! 🚀