# Setup

This repository supports several reproduction levels. Level 1 is CPU-only and uses included CSV/JSON artifacts. Higher levels require local videos, external source data, or GPU/model environments.

## Validated Environment

The release was validated with Python 3.10.12. It does not currently include a fully pinned lockfile, so exact package versions are not guaranteed.

Reference package versions:

- NumPy 2.2.6
- OpenCV 4.13.0
- scikit-image 0.25.2
- matplotlib 3.10.8
- Pillow 12.2.0
- imageio 2.37.3
- PyYAML 6.0.3
- PyTorch 2.11.0+cu128

These versions are reported for transparency, not as strict pins.

## CPU-Only Level 1 Environment

Level 1 artifact regeneration uses included CSV/JSON files and matplotlib. A practical CPU environment needs:

- Python 3.10 or newer
- NumPy
- matplotlib

The CPU test suite also uses:

- OpenCV
- imageio with ffmpeg support
- scikit-image
- Pillow
- PyYAML

Suggested minimal install for Level 1 plus tests:

```bash
python -m pip install numpy matplotlib opencv-python-headless imageio[ffmpeg] scikit-image Pillow PyYAML
```

If your shell treats brackets specially, quote `imageio[ffmpeg]`.

## Metric And Baseline Environment

For `scripts/compute_extended_metrics.py`, install:

- NumPy
- OpenCV
- scikit-image
- imageio with ffmpeg support
- PyYAML

This path recomputes MAD/SSIM, Persistence, and History Farneback metrics from local videos. It does not load generative models.

## Generative-Model Environment

Model inference requires additional external packages and checkpoints. Dependency stacks may differ across model families.

- LTX uses the external `ltx_video` Python package/API.
- SVD and Wan use PyTorch, Diffusers, Transformers, Accelerate, safetensors, imageio, Pillow, and OpenCV.
- Hugging Face access may be required for some checkpoints.

Optional dependency hint files are not included as pinned locks. Use [Models](MODELS.md) for model IDs and config paths.

No model weights are bundled with this repository.

## Environment Variables

Set `GENPD_DATA_ROOT` when rebuilding the clip bank from external source frames:

```bash
export GENPD_DATA_ROOT=/path/to/carla_mile_roach_frames
```

The included source manifests use paths such as:

```text
${GENPD_DATA_ROOT}/Town01/0000/image
```

The release path resolver expands environment variables before resolving paths.

For matplotlib on systems where the default config directory is not writable, use:

```bash
export MPLCONFIGDIR=/tmp/matplotlib
```

## Video / ffmpeg

The code reads and writes MP4 files through OpenCV and imageio/ffmpeg. Install an imageio ffmpeg backend or system ffmpeg before running video-based reproduction levels.

## CPU Check Commands

CLI help:

```bash
python -m src.cli.main --help
```

CPU tests:

```bash
PYTHONDONTWRITEBYTECODE=1 python -m unittest discover -s tests -v
```

Level 1 artifact regeneration:

```bash
python scripts/make_release_artifacts.py \
  --artifacts-dir artifacts \
  --out-dir outputs/release_level1
```