DEPLOYMENT_PATHS.md

Deployment Paths Configuration

Overview

This document explains how paths work for both local testing and Hugging Face Spaces deployment.

Directory Structure

Local Structure

huggingface/
  ├── models/              # Sibling to spad_for_vision_space
  │   ├── spatiotemporal/
  │   ├── material_detection_head/
  │   └── ...
  ├── datasets/             # Sibling to spad_for_vision_space
  │   ├── testmages_spatiotemporal/
  │   └── ...
  └── spad_for_vision_space/
      └── app.py           # BASE_DIR

Hugging Face Spaces Structure

/app/                      # BASE_DIR (Space root)
  ├── models/              # Downloaded from Hub
  │   ├── spatiotemporal/
  │   └── ...
  ├── datasets/            # Downloaded from Hub
  │   ├── testmages_spatiotemporal/
  │   └── ...
  └── app.py

Path Resolution

Base Directory

• BASE_DIR: Always resolves to the directory containing app.py
• Local: /Users/pd3rvr/Documents/pubs/THESIS/thetex/huggingface/spad_for_vision_space
• Hugging Face Spaces: /app (or wherever the Space runs from)

Models Paths

The app uses get_models_dir() helper function to determine the correct path:

Local Testing:

• Models are siblings to spad_for_vision_space: ../models/<model_type>/
• Example: /Users/pd3rvr/Documents/pubs/THESIS/thetex/huggingface/models/spatiotemporal/training_results_material_classifier_best_99.25%.pth

Hugging Face Spaces:

• Models are downloaded from mvplus/spatiotemporal_models to: BASE_DIR/models/
• The download preserves folder structure, so files end up in: BASE_DIR/models/<model_type>/<file>
• Example: /app/models/spatiotemporal/training_results_material_classifier_best_99.25%.pth

Dataset Paths

The app uses get_datasets_dir() helper function to determine the correct path:

Local Testing:

• Datasets are siblings to spad_for_vision_space: ../datasets/<dataset_name>/
• Example: /Users/pd3rvr/Documents/pubs/THESIS/thetex/huggingface/datasets/testmages_spatiotemporal/

Hugging Face Spaces:

• Datasets are downloaded from mvplus/spatiotemporal_dataset to: BASE_DIR/datasets/
• The download preserves folder structure, so files end up in: BASE_DIR/datasets/<dataset_name>/
• Example: /app/datasets/testmages_spatiotemporal/

Upload Strategy

Models Upload

When uploading models to mvplus/spatiotemporal_models, preserve the folder structure:

• Upload spatiotemporal/training_results_material_classifier_best_99.25%.pth (not just the file)
• This ensures it downloads to BASE_DIR/models/spatiotemporal/training_results_material_classifier_best_99.25%.pth

Datasets Upload

When uploading datasets to mvplus/spatiotemporal_dataset, preserve the folder structure:

• Upload testmages_spatiotemporal/ directory (with all files inside)
• This ensures it downloads to BASE_DIR/datasets/testmages_spatiotemporal/

Verification

The setup_huggingface_resources() function:

1. Downloads to BASE_DIR/models/ and BASE_DIR/datasets/
2. Verifies expected files exist after download
3. Prints warnings if expected structure is not found

Key Points

✅ Consistent Paths: All paths use BASE_DIR, which works the same locally and on Hugging Face Spaces

✅ Folder Structure Preserved: Uploads maintain folder structure, so downloads end up in correct locations

✅ Automatic Download: On Hugging Face Spaces, models/datasets download automatically on first startup

✅ Local Skip: Local testing skips downloads (models/datasets must be present locally)