Update README with comprehensive documentation for SkymapGen tool

README.md

@@ -1 +1,170 @@
-# Projekt in skymap-gen
+# 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.
+
+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
+```