99 lines
4.8 KiB
Markdown
99 lines
4.8 KiB
Markdown
# 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. |
|