User guide
From planning to on-site checks: what each screen does and how to use it.
Getting started
Plan on a Mac's larger screen or prepare your shoot entirely on mobile. Apple devices sync projects through iCloud when using the same account with iCloud enabled. Turn on Google Drive sync to sync between Android devices. Share plans between Apple and Android with a link.
Screen-by-screen examples use Apple devices. Android map, sync, and AR requirements are called out where they differ.
Home
The app opens on Home. The Today's sky card at the top shows today's sunrise and sunset, moonrise and moonset, the day strip (day, twilight, night, and when the Moon is up), your next planned alignment, and the nearest sky event. It uses your device's location, or the shooting spot of your last project if location isn't available.
The tiles below:
| Tile | What it does |
|---|---|
| Continue | Back to the project you were working on. Hidden when there's nothing to continue. |
| New project | Name a project and start an empty plan. Leave the name blank and it's named from the target and date. |
| Projects | Your saved projects (Managing projects). |
| Landmarks | Start from a landmark whose height has already been researched (Tables and tools). |
| Sky calendar | Full moons, eclipses, meteor showers, planet events (Sky calendar). |
| Eclipses | Solar and lunar eclipses of the next ten years with path maps; pick one to start a plan (Eclipses). |
| Moon Exposure Table · Hyperfocal Table | Reference tables for the field. |
| Settings | Time zone, language, default heights, Google key, subscription (Settings). |
| Help & About | User guide, support email, data sources, open-source licenses (Help & About). |
The planning screen

The tabs at the top center switch between four screens: Plan → Simulation → Photo Check → AR Check (shortened to Plan · Sim · Photo · AR on iPhone). The house icon at the top left is Home; the gear at the right opens settings. AR Check isn't available on Mac.
On iPhone in portrait the map fills the screen and you drag the drawer up to see the panel. iPhone landscape and iPad landscape show the map and panel side by side; on the Mac it's a resizable sidebar.
Body and subject
Two choices at the top of the panel shape the rest of the flow.
- Body: what to shoot in the sky: Moon · Sun · Milky Way.
- Subject: what to put in front of it: Structure (towers, bridges, skylines) · Person (a silhouette) · None (the body alone) · Space station (ISS, Tiangong) · Plane.
For example, to plan a shot of the Moon behind N Seoul Tower, the Body is Moon, the Subject is Structure, and the target you set on the map is N Seoul Tower. The app calls the moment the Moon appears right behind the target an 'alignment'.
Setting the target and shooting spot
The target is what you line up with the Moon (teal); the shooting spot is where you stand (orange). There are several ways to set them, all with the same result.
In Structure and Person modes, set the target first. The shooting spot is calculated from the target, so the Shooting spot chip stays dimmed until a target is set.
- iPhone: tap the Target or Shooting spot chip below the map and a crosshair appears. Move the map to put the crosshair on the spot, then tap Target here / Shooting spot here.
- iPad · Mac: the Set target · Set shooting spot buttons in the panel, or long-press the map (right-click on the Mac).
- Search: the magnifier at the top left of the map, Search places.
- The shooting spot can also come from My location or From photo (a photo with location data).
- On iPhone and iPad you can drag the pins. Moved one by mistake? Undo move at the top left of the map puts it back, and Redo move applies it again (positions only; date and time stay as they are).
Heights and ground elevation
Alignment is a matter of angles, so heights matter. The target card has Ground elevation and Structure height (Person height in person mode); the shooting spot has Ground elevation and Camera height. The three values are defined as follows.
- Ground elevation: the elevation above sea level of the floor at that spot. On a rooftop, it is the elevation of the roof floor.
- Structure height: the height from the target's base to the top of the structure (not above sea level).
- Camera height: the height from the floor you stand on to the camera. With a tripod on a rooftop, the spot's ground elevation is the roof floor's elevation, and if the camera is 1.4 m above the rooftop surface, enter 1.4 m as Camera height.
- The badge next to each value tells you where it came from: Auto (looked up from terrain data) · Manual (you typed it) · Sim terrain (corrected to the surface measured by the 3D simulation) · Settings default.
- Structures in the landmark list fill in their height automatically. If none is found you'll see Couldn't find the structure height: type it in, or measure it with Measure height in the simulation.
- Camera height has presets: Prone 0.3 · Tripod 1.4 · Standing 1.6.
- Shooting from a rooftop or bridge? Ground elevation is the floor you stand on. If the spot's ground elevation is set to Auto and the height of the surface the camera stands on can be read in the 3D view, opening the simulation corrects it to that height (shown as Sim terrain). A manually entered value is kept, and if the surface height can't be read, the existing value stays. If the camera lands outside the roof in the 3D view, it is corrected to ground level, so check Position differences between the map and the 3D view.
Date, time, and time zone
Use Date at the top of the panel to open the calendar, or < > to step a day at a time. The calendar shows the Moon's phase on each date. Times are shown in the shooting spot's local time; set a spot in another time zone and you'll be asked Switch to local time?. You can also change it under Time zone in settings.
The Sun & Moon card
Once a target or shooting spot is set, the Sun & Moon card appears: sunrise and sunset, moonrise and moonset, moon age and illumination, plus the day strip. The strip's background is how bright the sky is (light blue day → orange and navy twilight → black night); the yellow bar is when the Moon is up.
Map tools
The buttons at the top left of the map move to My location, change the map type (layers button), and open Search places (magnifying glass). Legend explains each color and line on the map. The available map types depend on the platform.
- iPhone, iPad, and Mac: Apple Maps by default, plus Apple Satellite · V-World · V-World Satellite (detailed maps of Korea). Add your own Google API key in Settings and Google Maps appears in the list too (not part of the subscription).
- Android: Google Maps by default, with no key needed, plus Google Satellite (satellite imagery with place names) · V-World · V-World Satellite.
Structure: the Moon behind a tower
▶ Watch on YouTubeyoutu.be/Mk3fT5VbnUc

This is MoonAlign's core flow; the other modes follow the same pattern.
- Choose Body Moon and Subject Structure.
- Set the target (say, the Eiffel Tower). Once its height is filled in, a band appears on the map.
- Set the shooting spot on the band. The yellow band is where the target lines up as the Moon rises, the blue band as it sets.
- Read the result on the shooting spot card: Moon aligned ✓ with the Aligns at time, the reference window, and the distance to the target. No alignment shows No alignment.
- If it doesn't work that day, tap Search 90 days. In Dates with alignment, check the date and time, moon age, and visibility (for example night · easily visible or Hidden by terrain), then tap Select to jump to that day.
- Preview the shot in the simulation.
When you like a plan, Add to Calendar puts it in your device's calendar, and the Share button lets you share it as a link.
My landmarks
Measured the height of something that isn't in the list, such as a local spire or a pylon? Save its name and height with Save as my landmark on the target card in structure mode. Next time, tapping that spot on the map fills in the height automatically. If you already saved one within 200 m, the button becomes Edit my landmark.
Person: a silhouette in front of the Moon
▶ Watch on YouTubeyoutu.be/wq53xdteF4k
Stand far back and zoom in: the person stays the same size while the Moon grows. Person mode draws the band using Person height (1.7 m by default).
- Choose Subject Person and set the spot where the person will stand (a ridge, a hilltop) as the target.
- You'll usually try several spots. Save good ones to Person spot candidates and switch between the A · B · C chips to compare bands (long-press a chip to delete it).
- Once the spot is settled, set your shooting spot on the band.
None and the Milky Way
Subject None is for shooting the body itself with nothing in front. Set just a shooting spot and the map shows where it rises (yellow line) and sets (blue line).
With Body Milky Way, the shooting spot card shows Light pollution and When the Milky Way is visible. Light pollution is how dark the night sky is at the shooting spot, shown as a Bortle class and mag/arcsec² and estimated from satellite night lights. A Moon in the sky shortens the visible window.
Space stations (ISS, Tiangong): lunar and solar transits
▶ Watch on YouTubeyoutu.be/_E6EDLS49NQ
MoonAlign predicts where and when the International Space Station (ISS) and China's Tiangong station cross in front of the Moon or Sun. Both stations are searched at the same time. A crossing of the disk typically takes around a second; check the exact duration in the result you select. Predictions use each station's orbit data. The ISS is computed from NASA's precise orbit data (OEM), falling back to CelesTrak TLE, and Tiangong from CelesTrak orbit data.
- Choose Subject Space station and Body Moon (or Sun). The ISS and Tiangong are searched together, so there is no station to pick.
- Not sure where to go? Tap Find transit spots under Predicted transit areas. It draws the bands where a transit is visible within the current map view. Each row shows the time, the Moon's altitude, its phase (for example, Full Moon 99%), and day or night. Tap a row to move the map to that band. Each station has its own band color (ISS purple, Tiangong pink), and each row is labeled with the station. Daytime and near-horizon bands are collected in a folded group.
- Set the shooting spot on a band and tap Search 14 days under Space station transit across the Moon.
- Check each result's station, grade (Transit expected · Possible · Close pass), separation, and duration, then tap Select to confirm. Confirming saves automatically, and the simulation lets you step through it in 0.1-second increments.
Night-sky passes (folded) lists the stations crossing the night sky rather than the Moon: brightness, peak altitude, direction, and how long it's visible.
Plane: live watch
▶ Watch on YouTubeyoutu.be/2aP1zqz9EeY
A plane crossing the Moon can't be forecast in advance. Instead, MoonAlign watches live air traffic around your shooting spot from your own ADS-B receiver and warns you seconds before a crossing.
- Choose Subject Plane and set your shooting spot.
- Under My receiver, enter the
aircraft.jsonaddress of your own ADS-B receiver (readsb, dump1090). You need to be on the same network as the receiver; live watch can't start without one. See Setting up an ADS-B receiver. - Set Max distance (km) and tap Start live watch. Your receiver's data refreshes every second.
- Candidate rows show seconds remaining, separation, altitude, and distance. When a crossing is close you get a countdown and an alert to get ready for burst.

While watching, nearby aircraft appear on the map as plane icons turned in their direction of travel, with their flight numbers. The color shows their status: yellow normal · orange a candidate passing near the Moon · red transit expected · gray no position update for several seconds. On the Mac, hover over an icon to see the flight number, altitude, and when its position was received.
- While watching, the shooting spot and body are locked. Tap Stop watching first to change them.
- Transit history keeps past candidates.
- Camera auto capture: Burst-shoot with a USB-connected camera around a plane crossing. Supported cameras and setup differ by device, so read Camera auto capture first.
Camera auto capture
The camera auto capture panel on the live watch screen presses the shutter of a camera connected over USB. With auto capture on, it follows likely and predicted transits: it presses the shutter at the Start burst time (before the transit) and releases it at the End burst time (after the transit). If 5 seconds or more have passed since the aircraft's position was last observed, the app stops shooting and releases the shutter. The app only presses the shutter; photos are saved to the camera's memory card and are not downloaded to the app.
Camera setup for all devices:
- Set the focus mode to manual focus (MF) and the drive mode to continuous shooting.
- On a Sony α, enable PC Remote in the camera menu and set the remote-shooting still image destination to 'Camera Only'.
- After connecting, always use Test shutter for 1 second to check that capture and shutter release work. Not every model is compatible.
The order is: camera setup → Connect USB → Test shutter for 1 second → Start live watch → Enable automatic capture. Auto capture can be enabled only during a live watch with the camera connected.
These differ by the device you use:
| Item | Mac · iPhone · iPad | Android |
|---|---|---|
| Supported cameras | Sony α · Canon EOS (Canon confirmed on the EOS R50 V) | Sony α · Canon EOS (Canon confirmed on the EOS R50 V) |
| Sony USB connection mode | Set the camera's 'USB Connection Mode' to 'Remote Shooting', or pick 'Remote Shooting' on the selection screen that appears when you plug in the cable. | Set the camera's 'USB Connection Mode' to 'Remote Shooting' in advance. With the default 'Sel. When Connect', the camera shows a selection screen (Live Stream · Image Transfer (MSC) · Image Transfer (MTP) · Remote Shooting) when you plug in the cable, and picking 'Remote Shooting' there won't connect. |
| Canon save destination | The app sets it to the memory card when connecting. | The app sets it to the memory card when connecting. |
| First connection | On the Mac, allow access to removable volumes in System Settings > Privacy & Security > Files and Folders. | Allow the USB access request that appears when you tap Connect USB. |
| During auto capture | The Mac stays awake. On iPhone and iPad, the screen stays on while the app is open on screen; switching to another app turns auto capture off and releases the shutter. | The screen stays on while the app is open on screen; turning the screen off or switching to another app turns auto capture off and releases the shutter. |
Setting up an ADS-B receiver
Live watch uses data from an ADS-B receiver you run yourself. It picks up the position signals aircraft broadcast on 1090 MHz, and you can build one from a Raspberry Pi, a USB receiver, and an antenna. Below is the setup the developer actually uses. Products and stores may change.
What you need
- Raspberry Pi: used here on a Raspberry Pi 5. The receiver image below supports Pi 2 through 5. You also need a power adapter and a microSD card.
- USB receiver: FlightAware Pro Stick Plus. Its built-in 1090 MHz filter and amplifier help in cities or near cell towers. The antenna port is SMA female.
- Antenna: FlightAware 1090 MHz antenna (about 66 cm, outdoor). Its connector is N-type female, so you need a separate N-male to SMA-male coaxial cable. Shorter, lower-loss cable is better.
Setup
- Download the receiver image. Get the ADS-B Feeder Image for Raspberry Pi from adsb.im.
- Write it to the microSD card. Use a tool such as Raspberry Pi Imager to write the image to the microSD card.
- Connect everything and power on. Connect antenna → coaxial cable → Pro Stick Plus → a USB port on the Pi, connect it to your network (wired Ethernet is easiest), then power it on. The first boot takes a few minutes.
- Open the setup page.
From a browser on the same network, go to my.adsb.im to find the receiver. If it isn't found, look up the Pi's IP address in your router and open
http://IP-address. - Enter the basics. Enter a receiver name, location (latitude and longitude), and antenna height, then pick the USB receiver. You can also choose here whether to share the data with community networks such as adsb.lol (optional).
- Check reception. If nearby aircraft appear under MAP on the setup page, the receiver is working.
Where to put the antenna: 1090 MHz signals travel almost in straight lines, so the higher and more open the sky view, the farther you can receive. Outdoors (a rooftop or outside a balcony) is best; indoors, stand it by a window. Range varies a lot with terrain, buildings, and mounting height.
Connecting MoonAlign
- The data address is
http://receiver-name.l.adsb.im:8080/data/aircraft.json. Take the name address shown at the bottom of the receiver's setup page (http://receiver-name.l.adsb.im/) and add:8080/data/aircraft.json. - If the name address doesn't open, use the IP address instead (
http://192.168.x.x:8080/data/aircraft.json). Some routers block the name address. - If opening the address in a browser shows aircraft data as JSON text, it's the right one.
- Enter the address under My receiver in the Plane section, and allow local network access when asked the first time you start watching.
Using it at the shooting spot (iPhone hotspot example)
The receiver needs to be at the shooting spot. The app only works with aircraft the receiver picks up, so the receiver has to cover the sky around your spot to warn you of a crossing. In the field, use your phone's hotspot to put the receiver and the phone on the same network. The steps and the 172.20.10.x address below are for an iPhone hotspot; on Android the hotspot menu and address range vary by device.
- Turn on the hotspot. On iPhone, go to Settings → Personal Hotspot and turn on "Allow Others to Join" and "Maximize Compatibility".
- Add the hotspot to the receiver (once, at home). Enter the hotspot name and password under Wi-Fi on the receiver's setup page. If the hotspot doesn't appear in the list (sometimes only the currently connected Wi-Fi shows up), add it with the advanced steps below.
- Use the IP address in the field.
On the hotspot, the receiver gets a
172.20.10.xaddress, and the name address (…l.adsb.im) may keep pointing to the IP address you used at home for a while. If you pin the IP to172.20.10.9as below, enterhttp://172.20.10.9:8080/data/aircraft.jsonunder My receiver. - Check the connection. Power the Pi, receiver, and antenna from a power bank with enough output (USB-C PD), then open the address above in a browser on the phone running the hotspot. If you see the aircraft list, the app can connect too. At the spot, set the antenna up as high as you can with an open view of the sky.
Advanced: add the hotspot and pin the IP over SSH
Register an SSH key on the receiver's setup page, connect to the receiver, and run the commands below. Replace the capitalized parts with your home Wi-Fi connection name, the hotspot name (Settings → General → About → Name on iPhone), and the hotspot password. At home the home Wi-Fi connects first; anywhere without it, the receiver joins the hotspot automatically. The 172.20.10.x addresses are for iPhone hotspots; Android hotspots use a different range.
nmcli con modify "HOME_WIFI" connection.autoconnect-priority 10
nmcli con add type wifi con-name phone-hotspot ifname wlan0 ssid "HOTSPOT_NAME" \
wifi.hidden yes wifi-sec.key-mgmt wpa-psk wifi-sec.psk "HOTSPOT_PASSWORD" \
connection.autoconnect yes connection.autoconnect-priority 0 \
ipv4.method manual ipv4.addresses 172.20.10.9/28 \
ipv4.gateway 172.20.10.1 ipv4.dns 172.20.10.1
Simulation: preview in 3D

Preview the plan with real terrain, buildings, and your lens's field of view. In Korea it uses V-World 3D (Ministry of Land, Infrastructure and Transport); outside Korea it uses Google Photorealistic 3D.
- Time slider: move around the alignment time and watch the Moon slide behind the target. The range is in the (i). Tap ◀ ▶ beside the slider to step one notch at a time (10 seconds for an alignment), which makes it easy to stop on the framing you want.
- Focal length: 14–1200mm, plus the sensor (Full frame · APS-C Sony/Nikon · APS-C Canon · Micro Four Thirds). Crop sensors also show the 35mm-equivalent focal length. You can also pinch the scene (on the Mac, pinch the trackpad or Control-scroll) to change the focal length; it's saved to the project when you let go.
- Aperture: picking one adds focus advice: whether focusing on the Moon keeps the target sharp too, or where to focus, or whether to blend two frames.
- Measure height: measure a structure on the 3D model and put it into the plan with Use this height.
- Chips over the scene: View camera position (see your spot from outside) · Landscape/Portrait · Show silhouette. Save the current view with Save image in the panel below. Drag the scene to look around; pinch to zoom in.
- The time you set with the slider and the view you dragged to are saved to the project when you leave Simulation, so it reopens on the same scene. The View button below brings the view back to facing the Moon or Sun. Moving the target or shooting spot, or changing the date, clears the saved scene.
Position differences between the map and the 3D view
The planning maps (Apple, Google, V-World) and the 3D view in the simulation are built from different aerial and satellite imagery and 3D models, so the same coordinates can put a building a few meters off. In Korea, the V-World 3D view is shifted a few meters from the maps in some areas, and on satellite maps the roofs of tall buildings can look offset to one side because the photos were taken at an angle. If you set the spot on a rooftop on the map but the 3D view puts you at the roof edge or on the ground beside the building, this is why.
- Little effect on alignment with a distant target. For a tower 3 km away, moving the spot 3 m sideways shifts where the Moon sits by only about a tenth of its diameter.
- The height can change a lot. When the spot's ground elevation is Auto, the simulation uses the height of the surface the camera stands on in the 3D view (a roof or the ground) as the spot's ground elevation (a manually entered value is kept). If the spot lands on the ground outside the roof in the 3D view, it is calculated lower by the building's height.
- How to check: Use View camera position in the simulation to see whether the camera is standing on the 3D building's roof. If not, go back to the planning screen, move the spot a few meters toward the roof as it appears in the 3D view, then open the simulation again to confirm the camera stands on the roof. This aligns the placement within the 3D model; confirm where you can actually stand on site.
- When the target is close, as with a Person subject, a few meters can change the composition. Fine-tune on site with Photo Check and AR Check.
Photorealistic 3D outside Korea
In Korea, V-World provides 3D buildings without a separate key setup. Outside Korea, use your own Google API key or an app subscription for photorealistic 3D. Building models are shown where data is available.
Your own key takes priority over the subscription. It's stored in iCloud Keychain on Apple devices and on the device on Android, sent only to Google, and never to the developer.
Your own key requires Google Cloud billing to be enabled. Usage within Google's monthly free allowance is free; overage charges apply beyond it. Check current pricing and your usage in the Cloud console.
The subscription covers the cost of photorealistic 3D data outside Korea. With your own Google API key, no app subscription is needed; Google's free allowance and overage charges apply. The app subscription allows 30 scene loads per device per day, including reloads, and resets at local midnight. After the limit, only terrain is shown. Your own key is not subject to this app limit.
Choose Monthly or Yearly. The subscription renews automatically each period until you cancel. On iPhone, iPad, and Mac it's charged to your Apple Account and can be canceled anytime under Subscriptions in your App Store account settings (Manage subscription in Settings). On Android it's charged to your Google Play account and can be canceled anytime under subscriptions in Google Play. If you reinstalled the app or added a device, tap Restore purchases. The subscription screen links to the Terms of Use (EULA) and the Privacy Policy.
On Apple devices, Google Maps on the plan screen is available only with your own key (it is not part of the subscription). On Android it is the default map and needs no key.
Creating and setting up a Google API key
- Sign in to the Google Cloud console. console.cloud.google.com: any regular Google account works.
- Create a project.
Project picker at the top → "New project." Enter any name (e.g.
moonalign-3d). - Link a billing account. Map APIs require a card on file. Costs may apply beyond the free allowance, so check Google's current pricing before you start.
- Enable the Map Tiles API.
In "APIs & Services → Library," search for
Map Tiles APIand enable it. Photorealistic 3D tiles are part of this API. - Create an API key. "APIs & Services → Credentials → + Create credentials → API key." Copy the key string.
- Restrict the key (recommended).
Edit the key → "API restrictions" → allow
Map Tiles APIonly. This limits which APIs the key can be used for. Set "Application restrictions" to "None". A key restricted to iOS apps won't work in MoonAlign. - Paste it into MoonAlign. Plan screen → Settings → "Google API key." It takes effect the next time the simulation loads.
You can set cost alerts under "Billing → Budgets & alerts" in the Google Cloud console. Budget alerts don't stop usage or charges automatically, so keep an eye on both usage and charges.
Photo Check: the path on your scouting photo


Take one photo from the shooting spot while scouting, and MoonAlign draws the planned day's path of the Moon (or Sun) on top of it. Use it to catch trees, cranes, and fences that aren't on any map.
- In the Photo Check tab, load a photo with Choose photo. An original photo with capture time, focal length, and GPS (EXIF) works best.
- Choose the Reference (Moon, Sun, Milky Way, or target) and the Location (this photo's location / the shooting spot / my location).
- Place the marker on your reference point. The red ring marks a body; the teal marker marks the top of the target or the person's head. The Moon and Sun are found in the photo automatically; just check the ring is in the right place.
- iPhone · iPad · Android: pan the photo with one finger to put the center crosshair on the reference point, then tap Place marker here. Pinch to zoom in for a more precise fit. To move it later, tap Place marker again.
- Mac: click the reference point in the photo. Pinch the trackpad, or scroll while holding Control (⌃) or Command (⌘), to zoom; while zoomed, scroll to pan.
- Scrub the Time slider to see the path around the planned time.
- Camera clock off by a few seconds? Enter the difference in Clock offset.
- 35mm equiv. is the 35mm-equivalent focal length; if it differs from the EXIF value, the original is shown too.
- Space station and plane projects don't have Photo Check.
AR Check: aim on site
Overlay celestial paths on the camera view on iPhone, iPad, or an ARCore-supported Android device. Android requires Google Play Services for AR. AR Check is not available on Mac. Calibrate the heading before checking your shooting direction and framing.
- Time: scrub through the whole time the body is up.
- Align: corrects compass error. If the body is visible, put it in the crosshair and tap Align to Moon; if not, put the top of the target in the crosshair and tap Align to target (Align to person in person mode).
- Refine further with Fine-tune; the reset button clears the calibration.
- Use the zoom chips to match the 35mm equiv. view to your planned lens.
Sky calendar, widgets, and Calendar
The Sky calendar shows full moons (supermoons and micromoons), new moons, lunar and solar eclipses, meteor showers, planet oppositions and conjunctions, close approaches and occultations of the Moon with planets and bright stars, Venus at greatest brilliancy, and the equinoxes and solstices. Close approaches and conjunctions are reported at the time they're actually visible from your reference location. Tap a date to see that day's Sun & Moon card, your saved plans, and its events. Meteor showers note how much moonlight will interfere. For eclipse path maps and eclipse times at your shooting spot, see Eclipses.
Add to Calendar on an event or plan row adds it to your device's calendar (with reminders the evening before and an hour before). iPhone and iPad show the event editor; the Mac saves it directly. Android also shows the event editor, but it can't add reminders automatically, so the recommended reminder times are written on the first line of the notes; set the reminders yourself. The app never reads your calendar.
Home screen and Notification Center widgets: Today's sky · Today's Moon · Today's Sun · Next shooting chance, plus Lock Screen widgets on iPhone and iPad. Widgets show what the app last calculated, so open the app once in a while.
Eclipses
Eclipses on Home lists the solar and lunar eclipses of the next ten years by date. Each row shows the type (total, annular, or partial solar eclipse, total lunar eclipse, and so on), the date, where it's visible, and whether it can be seen from your reference location (Visible · Partly visible · Not visible from here). Solar eclipses also show how much of the Sun is covered at most. Visibility is judged by whether the body is above the horizon during the eclipse; mountains and buildings are not taken into account.
- Tap an eclipse to open a new project for it. Subject is set to None, Body to Sun for a solar eclipse or Moon for a lunar one, and the date and time to the moment of greatest eclipse.
- The map shows where the eclipse is visible. Total and annular solar eclipses also show the path band, the northern and southern limits (dashed), the central line, and times every 10 minutes along it. The path crosses several time zones, so these times are in UTC.
- Set a shooting spot, and the eclipse card in the panel shows whether it's visible there and the contact times (Partial begins · Maximum · Partial ends, and so on) in the plan's time zone, each with the body's altitude. Altitudes below the horizon are shown in red. The project is saved when you set the shooting spot.
- Simulation opens at greatest eclipse. For a solar eclipse the Moon's disk covers the Sun and the sky darkens; for a lunar eclipse Earth's shadow falls across the Moon.
Managing and sharing projects
A plan is saved as a project automatically as soon as you set the shooting spot. Projects lists them by most recently edited; long-press a row (right-click on the Mac) for Open · Rename… · Share as Link… · Export as File… · Delete…. To delete several at once, use Select.
Projects sync through iCloud Drive across devices on the same Apple Account. Without iCloud they stay on that device. On iPhone and iPad, downloads over cellular can be slow or stall; if the list shows a notice, connect to Wi-Fi or turn on iCloud Drive in Settings > Cellular. A notice that a project file or the folder couldn't be read doesn't mean anything was deleted; the app tries again automatically shortly after.
On Android, turn on Google Drive sync in Settings to sync between Android devices on the same Google account. It doesn't sync with Apple devices (iPhone, iPad, Mac); move plans with a link or file. While projects first download, an empty list shows Waiting for your Google Drive projects, and if it can't connect you're asked to check your network. Projects download again when you reopen the app.
Sharing as a link
To share a plan with a friend, tap Share as Link… and send it in any messaging app. When they tap the link, the Shared plan screen opens and Import creates a new project. If the same plan is already there, Open opens that project; to make another copy, tap Import Again. For someone without the app, the same link opens a web page with the plan's summary and a map.
- The link contains the shooting spot's location and the project name. A link can't be taken back once sent, so you're asked to confirm the first time.
- The plan lives only inside the link; nothing is stored on a server.
- Automatic values such as ground elevation are looked up again on the receiving device. Heights you typed in yourself travel as they are.
- The time and view you set in Simulation travel too, so the receiver can open the same scene.
- If a messaging app cuts the link off, use Export as File… to send a
.moonplanfile instead. Opening it brings up the same screen.
Export project JSON… and Import project JSON… in the Mac menu bar are for full backups.
Tables and tools
Landmarks
The Landmarks tile lists landmarks around the world whose heights have been researched, grouped by region, with My landmarks on top. Tap one to open a new project with it as the target, ready for you to set the shooting spot. You can rename, change the height of, or delete your own landmarks here (adding new ones happens on the planning screen).
Moon Exposure Table
A table of starting exposures: the full-moon f/11 rule adjusted for the Moon's phase and altitude. Pick Aperture and Shutter to read the Starting ISO by phase. For a low Moon, tap the cell in Extra exposure for a low Moon that best matches the air conditions to add it. Take a frame, zoom in to check the lunar detail survives, then adjust.
Hyperfocal Table
For each focal length and aperture, the target distance at which focusing on the Moon or stars still keeps the target sharp. If your target is farther than that, one frame gets both sharp. Tap a cell to highlight its row and column; it's remembered.
Settings
| Item | What it does |
|---|---|
| Time zone | The time zone plan times are shown in. |
| Language | System default · 한국어 · English · 日本語. Takes effect after restarting the app. |
| Default heights | Camera height and Person height for new plans (camera height 0–50 m, person height 0.5–3 m). |
| Google API key | Register your own key for photorealistic 3D outside Korea and Google Maps (optional). It takes priority over the subscription. See Photorealistic 3D outside Korea for how it is stored and sent. |
| Photorealistic 3D subscription | Subscribe · Manage subscription · Restore purchases. For plans, renewal, and canceling, see Photorealistic 3D outside Korea. |
| Google Drive sync | Android only. Syncs projects and My landmarks between Android devices on the same Google account (Managing projects). |
Help & About
Help & About on Home shows the app version and the following.
- User guide: opens this guide in the app's language.
- Privacy Policy: opens how the app handles your information, in the app's language.
- Email support: starts an email to support@yjlab.io. The app version, device model, OS, and language are filled in for you, and you can delete them before sending. No location or project information is included.
- Data sources: where the map, terrain, light pollution, orbit, air traffic, and eclipse data come from.
- Open-source licenses: licenses of the open-source libraries used in the app.
Tips
Check the shooting spot in different map types
Once you've picked a candidate spot on the band, zoom in close and switch map types before settling on it. The same place shows different information on each map (available maps depend on your device; see Map tools).
- Can you get there? (standard map): check the roads, footpaths, and stairs that lead to the spot, and the nearest parking. Make sure it isn't somewhere you can't enter, such as fenced grounds, a military site, a construction site, or private land.
- What is it really like? (satellite map): see what the standard map leaves out: trees, walls and noise barriers, the slope of a riverbank and where the water starts. In Korea, V-World Satellite is the most detailed.
- Is the view open? (along the direction line): follow the red line from the shooting spot toward the target and look for tall buildings, woods, or hills in between. The blocking marks on the plan map only check terrain, so buildings and trees are up to you.
If no spot looks right, move a little along the band and repeat. Other places on the band line up on the same day at a similar time, so the key is to pick one that's easy to reach and has a clear view toward the target.
Preview the view from the shooting spot with Street View
Maps and 3D models can be missing trees, fences, and new buildings, or differ from reality. Before scouting, use Street View in Google Maps to check that the target can be seen from the shooting spot.
- Note the latitude and longitude shown at the bottom of the shooting spot card.
- Search for those coordinates in Google Maps (app or web) and open Street View.
- Turn toward the target and check that nothing blocks it and that you can actually stand there (fences, restricted access).
Line up the Sun or Moon with the end of a road or a mountain peak: a virtual target
Some scenes are about direction rather than a structure: the end of a long straight road, the far side of a bridge, a street between buildings. For these, plan as if a tall virtual pole stood in that direction. The app doesn't care what's really there; it calculates the dates and times when the Sun or Moon lines up with that pole.
The example project [DEMO] Road to Heaven Sunset, Hokkaido works this way. From a shooting spot on a hill, the target sits on the road about 11 km ahead where the road leads, with a structure height of 200 m, to find the days when the Sun sets at the end of the road.
Plan a mountain peak the same way. Landmark heights aren't filled in for mountains, so set the summit as the target and enter a virtual height. With a height of 0, only the moment the Sun or Moon touches the single summit point counts as aligned, so almost no dates come up. The height sets how far above the summit still counts as aligned. The example project [DEMO] Diamond Fuji, Lake Tanuki puts a 100 m height (about 0.36°, a little less than the Sun's diameter) on the summit of Mount Fuji, seen from the shore of Lake Tanuki about 16 km away, and finds the Sun rising over the summit at 06:05 on April 22, 2027. Near a mountain top, the automatic ground elevation can come out lower than the real one because the terrain grid smooths the peak (Mount Fuji 3,776 m → about 3,728 m). If you know the exact elevation, enter it in Ground elevation.
▶ Watch on YouTubeyoutu.be/tckrLog3sBs
- Choose Subject Structure and set the target at a far point the road leads to (a few km ahead, toward the end of the road or its vanishing point). The farther it is, the more precise the direction.
- Type a virtual height into Structure height. It sets how high above the horizon the Sun or Moon can be and still count as aligned. 17 m at 1 km is about 1°, so 200 m at 11 km is about 1°, roughly twice the diameter of the Sun or Moon (about 0.5°).
- Set the shooting spot and find alignment dates with Search 90 days. If you have to stand in a particular place, such as on the road, make that the shooting spot and search for dates.
- Check in the simulation that the Sun or Moon sits at the end of the road.
When you don't know the target's height: Measure height
If the building the Moon will sit on isn't in the landmark list and its height isn't published anywhere, you can measure it against the photorealistic 3D model with Measure height in the simulation, like holding up a ruler. A wrong structure height shifts the alignment date and time too, so measure it instead of leaving a placeholder.
- For Subject, choose Structure, set the target at the base of the building, and set the shooting spot. The simulation opens only once a shooting spot is set.
- Turn on Measure height in the simulation. A thin pillar stands at the target, with a wide disc at its base.
- First check that the disc sits on the ground. If it floats or is buried, check Ground elevation on the target card in the planning screen. If the value was entered manually, on Mac, iPhone, and iPad you can tap Auto to return to the automatic lookup; if you know a confirmed elevation, enter it directly (Heights and ground elevation). Don't guess a value you don't know.
- Use the slider to bring the top of the pillar level with the top of the building. Zooming in and turning the view so the top is clearly visible makes this easier.
- Tap Use this height to put the value into the plan's structure height. If you shoot there often, save it as my landmark.
Troubleshooting
The alignment seems to be a day off
A Moon that sets before dawn can align on a different calendar date than the plan's date (the night it began). Go by the Aligns at time on the shooting spot card.
For example, if a plan for 10/26 aligns at 10/27 (Tue) 07:40, that Moon rises on the evening of 10/26 and sets early on 10/27. If you change the plan date to 10/27, the app calculates the Moon that sets early the following morning instead, so there may be no alignment. Pick the plan date (the night it begins), not the alignment date. If you pick the alignment date, the shooting spot card says so and shows a Go to previous day button.
For spots in another time zone, also check that the time zone is set to local time.
The structure height is empty or wrong
Buildings that aren't in the landmark table may not have a height. Type it in, or measure it on the 3D model with Measure height in the simulation. For something you shoot often, use Save as my landmark.
The simulation shows a wall instead of the Moon or the target
A spot that looks open on the map can end up inside a building, right behind a wall or embankment, or among trees in 3D, or there may be a building or hill between the target and the shooting spot. The blocking marks on the plan map only check terrain, not buildings.
Tap View camera position in the simulation to see from outside where the camera is placed. If it's inside a building or behind a wall, move the shooting spot a little to an open place or change the Camera height. If something stands between the target and the shooting spot, pick another place on the band. You can also preview the real view with Street View.
I set the spot on a rooftop on the map, but the simulation puts me on the ground next to it
The maps and the 3D view are built from different imagery and models and can differ by a few meters. Check with View camera position in the simulation and move the spot toward the roof as it appears in the 3D view. See Position differences between the map and the 3D view.
No buildings outside Korea in the simulation
Outside Korea, buildings need the Photorealistic 3D subscription or your own Google key. If you already have one, check the notice shown on screen. If it says the daily usage limit has been reached, buildings come back the next day.
The space station transit time changed since yesterday
That's expected. ISS and Tiangong orbits are adjusted from time to time and forecasts change with new orbit data. Search again the day before you shoot.
Tapping a shared link opens a web page
If the app is installed, tap Open in MoonAlign on the page. A link pasted into the browser's address bar doesn't open the app; it opens the app when you tap it in a messaging app or similar.
Projects don't show up on my other device
Both devices need iCloud Drive turned on with the same Apple Account. While projects first download, the list says they're downloading. If it takes long on iPhone or iPad, or the list says projects couldn't be downloaded yet, connect to Wi-Fi or turn on iCloud Drive in Settings > Cellular. When a file or the folder couldn't be read, the app tries again automatically, and the projects haven't been deleted.
On Android, both devices need Google Drive sync turned on with the same Google account. Android and Apple devices don't sync with each other; move plans with a link or file.
For anything else, write to support@yjlab.io.




