Initial Application

docs/USAGE.md

@@ -0,0 +1,98 @@
+# 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. |