Jaguar Segmentation Sprint

The focus of this 3-day sprint is to create a custom semantic segmentation model to separate jaguars from their background.

The FiftyOne loading script was created using Python 3.11. It is strongly recommended to use the same version on your local installation.

Installation Guide

This guide provides step-by-step instructions for setting up the Jaguar Re-identification project using uv on Linux, macOS, and Windows.

Overview

This project requires:

• Python 3.11
• uv - A fast Python package installer and resolver
• PyTorch with appropriate GPU acceleration (optional but recommended)
• Various dependencies for data processing and visualization

Step 1: Install uv

uv is a fast Python package installer and resolver written in Rust. Choose the installation method for your operating system:

Linux & macOS

# Using curl (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh

After installation, restart your shell or run:

source $HOME/.cargo/env

Windows

Option 1: PowerShell (recommended)

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Option 2: Using pip

pip install uv

Verify Installation

uv --version

You should see output like uv 0.x.x or similar.

Step 2: Install Python 3.11 with uv

uv can install and manage Python versions for you.

All Platforms

# Install Python 3.11
uv python install 3.11

# Verify installation
uv python list

This will download and install Python 3.11 if not already present on your system.

Step 3: Clone or Navigate to Project Directory

# If cloning from a repository
git clone <repository-url>
cd kaggle_jaguar_reidentification

# Or navigate to existing project
cd /path/to/kaggle_jaguar_reidentification

Step 4: Create Virtual Environment

Create a virtual environment using Python 3.11:

Linux & macOS

# Create virtual environment with Python 3.11
uv venv --python 3.11

# Activate the virtual environment
source .venv/bin/activate

Windows

# Create virtual environment with Python 3.11
uv venv --python 3.11

# Activate the virtual environment
.venv\Scripts\activate

You should see (.venv) prefix in your terminal prompt after activation.

Step 5: Install Project Dependencies

With the virtual environment activated, install all required packages:

# Install dependencies from requirements.txt
uv pip install -r requirements.txt

This will install:

• PyTorch (>=2.0.0) with CPU support by default
• TorchVision and TorchAudio
• FiftyOne for dataset visualization
• HuggingFace Transformers and Datasets
• PyArrow for Parquet file handling
• Data processing libraries (pandas, numpy)
• Image processing libraries (Pillow, OpenCV)
• Various utilities

Note: The installation may take several minutes depending on your internet connection, as PyTorch packages are large (several GB).

Step 6: Verify Installation

Verify that all packages are installed correctly:

# Check Python version
python --version
# Should output: Python 3.11.x

# Test PyTorch installation
python -c "import torch; print(f'PyTorch version: {torch.__version__}')"

# Test other key packages
python -c "import fiftyone; import pyarrow; import pandas; print('All packages imported successfully!')"

GPU Acceleration Setup (Optional)

NVIDIA GPU (CUDA) - Linux & Windows

If you have an NVIDIA GPU and want CUDA support, reinstall PyTorch with CUDA:

# Uninstall CPU version
uv pip uninstall torch torchvision torchaudio

# Install CUDA 11.8 version (recommended)
uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# Or CUDA 12.1 version
uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# Verify CUDA is available
python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}')"
python -c "import torch; print(f'CUDA version: {torch.version.cuda}')"

Apple Silicon (M1/M2/M3) - macOS

PyTorch installed via pip automatically includes MPS (Metal Performance Shaders) support:

# Verify MPS is available
python -c "import torch; print(f'MPS available: {torch.backends.mps.is_available()}')"
python -c "import torch; print(f'MPS built: {torch.backends.mps.is_built()}')"

AMD GPU (ROCm) - Linux

For AMD GPUs on Linux:

# Uninstall CPU version
uv pip uninstall torch torchvision torchaudio

# Install ROCm version (check PyTorch website for latest ROCm version)
uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm5.7

# Verify ROCm is available
python -c "import torch; print(f'ROCm available: {torch.cuda.is_available()}')"

Quick Start Commands Summary

Linux & macOS

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.cargo/env

# Navigate to project
cd kaggle_jaguar_reidentification

# Create and activate virtual environment
uv venv --python 3.11
source .venv/bin/activate

# Install dependencies
uv pip install -r requirements.txt

# Verify installation
python -c "import torch; print(f'PyTorch {torch.__version__} installed successfully!')"

Windows (PowerShell)

# Install uv
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Navigate to project
cd kaggle_jaguar_reidentification

# Create and activate virtual environment
uv venv --python 3.11
.venv\Scripts\activate

# Install dependencies
uv pip install -r requirements.txt

# Verify installation
python -c "import torch; print(f'PyTorch {torch.__version__} installed successfully!')"

Troubleshooting

uv command not found

Solution: Restart your terminal or manually add uv to your PATH:

• Linux/macOS: Add export PATH="$HOME/.cargo/bin:$PATH" to your ~/.bashrc, ~/.zshrc, or equivalent
• Windows: The installer should add uv to PATH automatically. If not, restart your terminal.

Python 3.11 not available

Solution: Ensure uv successfully installed Python 3.11:

uv python install 3.11 --force
uv python list

Permission denied errors (Linux/macOS)

Solution: Don't use sudo with uv. Install in user space:

curl -LsSf https://astral.sh/uv/install.sh | sh

Virtual environment activation issues (Windows)

Solution: If you get an execution policy error, run:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

PyTorch GPU not detected

Solutions:

• CUDA: Verify NVIDIA drivers are installed: nvidia-smi
• MPS (macOS): Ensure you're on macOS 12.3+ with Apple Silicon
• ROCm (AMD): Check ROCm drivers: rocm-smi

Package installation fails

Solution: Try upgrading uv and pip:

uv pip install --upgrade pip setuptools wheel

Out of disk space during installation

Solution: PyTorch packages are large (~2-3GB). Ensure you have at least 5GB free space.

Deactivating the Environment

When you're done working:

# Deactivate virtual environment
deactivate

Updating Dependencies

To update packages to their latest compatible versions:

# Activate virtual environment first
source .venv/bin/activate  # Linux/macOS
# or
.venv\Scripts\activate     # Windows

# Update all packages
uv pip install --upgrade -r requirements.txt

Additional Resources

• uv Documentation
• PyTorch Installation Guide
• FiftyOne Documentation
• Project Documentation

Next Steps

After installation, see CLAUDE.md for:

• Dataset structure and usage
• Working with Parquet files
• Creating FiftyOne visualizations
• Training models with GPU acceleration