# Using Dynamic Wallpaper Creator

This walks through the app window shown by `java -jar
target/dynamic-wallpaper-creator.jar` (see [BUILD.md](BUILD.md) if you
haven't built it yet).

## 1. Pick a wallpaper type

The dropdown at the top switches between the two supported wallpaper types:

- **Light / Dark Appearance** — the simple case: one image for Light Mode,
  one for Dark Mode. Good for a first try, or if you just want two specific
  images to swap automatically.
- **Sun Position (Solar)** — the full "Dynamic Desktop" experience: any
  number of images, each tied to a point in the sun's daily arc, cross-fading
  as the actual time of day changes.

## 2. Light / Dark Appearance tab

Two side-by-side cards, one per appearance. For each:

1. Click **Choose Image…**.
2. Pick a PNG, JPEG, TIFF, BMP, GIF, or HEIC file.

A thumbnail preview appears once selected. Both a light and a dark image are
required before you can generate.

**Tip:** the two images should be the same pixel dimensions — same scene,
different lighting, works best. The app warns you (but doesn't block you) if
they don't match.

## 3. Sun Position (Solar) tab

1. Click **Add Images…** and select one or more image files (multi-select is
   supported in the file picker). Each becomes a row in the table.
2. For each row, set:
   - **Altitude (°)** — how high the sun is: `90` = directly overhead, `0` =
     right on the horizon, negative values = below the horizon (night/dusk).
   - **Azimuth (°)** — the sun's compass direction, `0`–`360`.
   - **Light Ref. / Dark Ref.** checkboxes (optional) — mark the single
     frame that best represents "daytime" and the one that best represents
     "nighttime". If you leave these unchecked, the app picks them for you
     automatically (highest and lowest altitude).
3. Don't want to hand-enter every value? Select at least two images and
   click **Auto-Distribute Sun Positions** — it fills in a smooth
   sunrise → noon → sunset → night arc across however many images you've
   added, evenly spaced. You can still tweak any individual cell afterward
   by double-clicking it.
4. Use **Move Up** / **Move Down** to reorder rows, or **Remove Selected** /
   **Clear All** to edit the set. Order doesn't affect how macOS displays the
   wallpaper (that's entirely driven by the altitude/azimuth values you set),
   it's just for your own bookkeeping.

At least two images are required to generate a solar wallpaper.

## 4. Generate

At the bottom of the window:

1. **Output file** — where to save the `.heic` file. Defaults to
   `~/Desktop/MyDynamicWallpaper.heic`; click **Choose…** to pick somewhere
   else.
2. **Quality** — HEIC compression quality from `0.1` (small file, more
   compression artifacts) to `1.0` (largest file, best quality). `0.9` is a
   good default.
3. Click **Generate Wallpaper**.

The first time you do this on a fresh install, there's a short one-time delay
(a few seconds) while the app compiles its native helper tool in the
background — see [BUILD.md](BUILD.md#3-building-the-native-helper-heic-builder)
for what's happening. Every generation after that is fast.

Progress is streamed into the log box at the very bottom as each image is
loaded and the file is written. If something goes wrong (a missing image, an
unwritable output path, a missing Swift toolchain), you'll see an error
dialog and the reason in the log.

## 5. Set as Desktop Picture

Once generation finishes successfully, the **Set as Desktop Picture** button
becomes active. Clicking it applies the file you just built as your current
desktop picture on all displays, via the same mechanism as System Settings.
This only changes your desktop picture setting — it's fully reversible from
System Settings → Wallpaper at any time, the same as picking any other
wallpaper.

You can also just leave the generated `.heic` file where you saved it and add
it manually later: open **System Settings → Wallpaper → Add Photo**, or
double-click the file in Finder and choose **Set Desktop Picture**.

## Troubleshooting

| Symptom | Likely cause / fix |
|---|---|
| "The Swift compiler (swiftc) was not found" | Install Xcode Command Line Tools: `xcode-select --install`, then try again. |
| Generate fails immediately with a decode error | One of your source images is in a format Apple's ImageIO can't read, or the file is corrupt. Try re-exporting it as PNG or JPEG. |
| Wallpaper doesn't animate after setting it | Make sure you're on macOS Mojave (10.14) or later, and that "Dynamic Desktop" hasn't been disabled — check System Settings → Wallpaper on the image you just set; it should show a Light/Dark/Dynamic selector under the thumbnail. |
| Images look stretched or misaligned when swapping | Your light/dark or solar images have different pixel dimensions. Re-export them all at the same resolution. |
