scripts/README.md

# Scripts Directory

This directory contains scripts for testing, experimentation, and tooling.

## Structure

```
scripts/
├── bin/                    # Shell scripts and executables
│   ├── run_ba_validation.sh
│   ├── run_finetuning.sh
│   └── setup_ba_pipeline.sh
├── experiments/             # Experimental and testing scripts
│   ├── test_api_with_profiling.py  # API testing with profiling
│   ├── run_arkit_ba_validation.py   # ARKit BA validation
│   ├── run_arkit_ba_validation_gui.py  # ARKit validation with GUI
│   └── run_ba_validation_video.py  # Video-based BA validation
├── tests/                   # Unit and integration tests
│   ├── smoke_test.py
│   ├── smoke_test_basic.py
│   ├── test_gui_simple.py
│   └── test_smart_pairing.py
├── tools/                   # Utility tools
│   └── visualize_ba_results.py  # BA validation result visualization
└── test_api.py             # Comprehensive API endpoint testing
```

## Usage

### API Testing

Test API endpoints:

```bash
# Comprehensive API testing (recommended)
python scripts/test_api.py --base-url http://localhost:8000

# Test with specific data directories
python scripts/test_api.py \
    --base-url http://localhost:8000 \
    --sequence-dir data/sequences/seq001 \
    --arkit-dir assets/examples/ARKit \
    --sequences-dir data/raw/sequences \
    --training-data-dir data/training

# Test without optimization parameters
python scripts/test_api.py --skip-optimizations

# Test without job polling (faster)
python scripts/test_api.py --skip-polling

# API testing with profiling
python scripts/experiments/test_api_with_profiling.py --base-url http://localhost:8000
```

### BA Validation Experiments

Run BA validation experiments:

```bash
# ARKit validation
python scripts/experiments/run_arkit_ba_validation.py \
    --arkit-dir assets/examples/ARKit \
    --output-dir data/arkit_ba_validation

# ARKit validation with GUI
python scripts/experiments/run_arkit_ba_validation_gui.py \
    --arkit-dir assets/examples/ARKit \
    --output-dir data/arkit_ba_validation

# Video-based validation
python scripts/experiments/run_ba_validation_video.py \
    --video path/to/video.mp4 \
    --output-dir data/ba_validation
```

### Shell Scripts

Run setup and pipeline scripts:

```bash
# Setup BA pipeline
bash scripts/bin/setup_ba_pipeline.sh

# Run BA validation
bash scripts/bin/run_ba_validation.sh

# Run fine-tuning
bash scripts/bin/run_finetuning.sh
```

### Tools

Visualize BA validation results:

```bash
python scripts/tools/visualize_ba_results.py \
    --results-dir data/arkit_ba_validation \
    --output-dir data/arkit_ba_validation/visualizations
```

### Tests

Run unit and integration tests:

```bash
# Run all tests
python -m pytest scripts/tests/

# Run specific test
python scripts/tests/smoke_test.py
```

## Organization Principles

1. **Core Application Code**: All application logic lives in `ylff/`
2. **Experiments**: Testing and experimental scripts in `scripts/experiments/`
3. **Tools**: Utility scripts for visualization, analysis, etc. in `scripts/tools/`
4. **Tests**: Unit and integration tests in `scripts/tests/`
5. **Binaries**: Shell scripts and executables in `scripts/bin/`

## Adding New Scripts

- **API/Endpoint Testing**: Add to `scripts/experiments/`
- **Data Processing Tools**: Add to `scripts/tools/`
- **New Experiments**: Add to `scripts/experiments/`
- **Unit Tests**: Add to `scripts/tests/`
- **Shell Scripts**: Add to `scripts/bin/`