# SkymapGen

SkymapGen is a desktop tool for generating and previewing equirectangular 360 sky maps from text prompts. It combines a Tauri/Vite/Three.js interface with a Python Diffusers generation pipeline, so generated panoramas can be viewed immediately inside an interactive sphere.

## Features

- Generate equirectangular PNG sky maps from text prompts.
- Preview maps in a full-screen Three.js 360 viewer with orbit controls.
- Keep a thumbnail dock of generated maps from the local `output/` folder.
- Persist generation settings in the app, including size, steps, guidance, scheduler, model paths, upscaling, and seam inpainting.
- Cancel an active generation from the UI.
- Store the enriched prompt in PNG metadata for later display.
- Write generation logs to `logs/`.

## Requirements

- macOS, Linux, or Windows with Tauri prerequisites installed.
- Node.js and npm.
- Rust and Cargo for the Tauri desktop shell.
- Python 3.10 recommended. `run.sh` prefers `python3.10` when available and falls back to `python3`.
- Enough RAM/VRAM for SDXL generation. Apple Silicon MPS and CUDA are detected automatically when available.

Python dependencies are listed in `requirements.txt`. JavaScript dependencies are listed in `package.json`.

## Model Files

The app is offline-first by default. It will use local files or cached Hugging Face assets unless downloads are explicitly enabled.

Recommended local files:

- `models/sdxl360Diffusion_v10.safetensors` for the SDXL 360 checkpoint.
- `RealESRGAN_x4plus.pth` in the project root if you enable Real-ESRGAN upscaling.

If the SDXL 360 checkpoint is missing, the generator can load `ProGamerGov/sdxl-360-diffusion` from the Hugging Face cache, or download it when downloads are enabled.

## Quick Start

```bash
./run.sh
```

The script will:

1. Create `.venv/` if needed.
2. Install Python requirements.
3. Install npm dependencies if `node_modules/` is missing.
4. Start the Tauri dev app with `npm run tauri dev`.

To allow missing Hugging Face assets to download during startup or generation:

```bash
SKYMAP_ALLOW_DOWNLOADS=1 ./run.sh
```

## Manual Setup

```bash
python3.10 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
npm install
```

Start the desktop app:

```bash
npm run tauri dev
```

Build the web assets only:

```bash
npm run build
```

Build a Tauri app bundle:

```bash
npm run tauri build
```

## Desktop Usage

1. Launch the app.
2. Enter a prompt in the bottom prompt bar.
3. Open `Settings` to adjust generation parameters.
4. Click `Generate`.
5. The generated panorama is saved to `output/` and loaded into the 360 viewer.

During generation, the `Generate` button changes to `Cancel`. Existing PNG maps in `output/` are shown in the thumbnail dock, and can be selected or deleted from the app.

Default desktop generation settings:

- Size: `1536x768`
- Steps: `25`
- Guidance: `6.5`
- Scheduler: `dpmsolver-sde`
- Upscale: `none`
- Seam inpainting: disabled
- Model: local `models/sdxl360Diffusion_v10.safetensors` when present, otherwise `ProGamerGov/sdxl-360-diffusion`
- Base model: `stabilityai/stable-diffusion-xl-base-1.0`
- VAE: `madebyollin/sdxl-vae-fp16-fix`

## CLI Usage

You can run the Python generator directly:

```bash
source .venv/bin/activate
python generate_equirect.py \
  --prompt "wide alpine meadow at sunset" \
  --output-dir output \
  --width 1536 \
  --height 768 \
  --steps 25 \
  --guidance 6.5 \
  --scheduler dpmsolver-sde \
  --upscale none
```

Useful options:

- `--output PATH`: write to a specific PNG path.
- `--output-dir DIR`: choose the output directory when `--output` is not set.
- `--model-path VALUE`: use a Hugging Face model id or local model path.
- `--base-model VALUE`: SDXL base pipeline used when the 360 model only provides a UNet.
- `--vae-model VALUE`: VAE repo/path for SDXL models.
- `--scheduler euler|euler_a|heun|ddim|dpmsolver|dpmsolver-sde`: override the scheduler.
- `--upscale none|realesrgan|topaz`: post-process with no upscaler, Real-ESRGAN, or Topaz Photo AI.
- `--seam-inpaint`: shift and inpaint the wrap seam before saving.
- `--allow-downloads`: allow missing model files to be downloaded.

The generator automatically appends `, equirectangular 360 view` to prompts that do not already include that suffix.

## Outputs

- Generated PNGs are saved in `output/`.
- Log files from desktop generations are saved in `logs/`.
- PNG metadata includes a `prompt` text field containing the enriched prompt.
- Temporary generation folders are created under the project root and cleaned up by the generator.
- In the packaged macOS app, bundled maps are seeded into `~/Library/Application Support/com.skymap.gen/output/`, and new maps/logs are written under `~/Library/Application Support/com.skymap.gen/`.

Generated outputs, model weights, local caches, virtual environments, and build artifacts are ignored by Git.

## Troubleshooting

If model loading fails in offline mode, either place the required files locally, warm the Hugging Face cache, or rerun with:

```bash
SKYMAP_ALLOW_DOWNLOADS=1 ./run.sh
```

If Real-ESRGAN upscaling fails, make sure `RealESRGAN_x4plus.pth` exists in the project root and the Python requirements are installed.

If generation is slow or memory constrained, reduce `width`, `height`, or `steps`, disable seam inpainting, and keep upscaling off.

## Project Layout

```text
.
|-- generate_equirect.py       # Diffusers generation and post-processing CLI
|-- run.sh                     # One-command development launcher
|-- src/                       # Vite/Three.js frontend
|-- src-tauri/                 # Tauri Rust desktop backend
|-- configs/                   # SDXL single-file loading config
|-- public/                    # Static frontend assets
|-- models/                    # Local model weights, ignored by Git
|-- output/                    # Generated PNG maps, ignored by Git
`-- logs/                      # Desktop generation logs, ignored by Git
```