DynamicWallpaperCreator/docs/USAGE.md

Using Dynamic Wallpaper Creator

This walks through the app window shown by java -jar target/dynamic-wallpaper-creator.jar (see 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 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.