User guide

Getting started

MoonAlign is a one-time purchase that works across iPhone, iPad, and Mac. Projects (shooting plans) sync between your devices automatically through iCloud Drive.

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:

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. The Mac has no AR.

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) · ISS · Plane.

Setting the target and shooting spot

The target is what you line up with the Moon (cyan); the shooting spot is where you stand (orange). There are several ways to set them, all with the same result.

• 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 (e.g. Namsan Tower).
• 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 (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 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.2 · Standing 1.5.
• Shooting from a rooftop or bridge? Ground elevation is the floor you stand on. Opening the simulation once corrects it to the 3D model's surface automatically.

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 abroad 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. The dawn and afterglow line is an estimate from the weather forecast.

Map tools

• Layers button: Apple Maps · Apple Satellite · V-World · V-World Satellite (detailed maps of Korea), and Google Maps if you've added your own Google key.
• Legend: what each color and line on the map means.

Structure — the Moon behind a tower

This is MoonAlign's core flow; the other modes follow the same grammar.

1. Choose Body Moon and Subject Structure.
2. Set the target (say, Namsan Tower). Once its height is filled in, a band appears on the map.
3. 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.
4. 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.
5. 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.
6. Preview the shot in the simulation.

When you like a plan, Add to Calendar puts it in your device's calendar, and the share icon lets you share it as a link.

My landmarks

Measured the height of something that isn't in the list — a local spire, 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

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).

1. Choose Subject Person and set the spot where the person will stand (a ridge, a hilltop) as the target.
2. 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).
3. 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 (Bortle class and mag/arcsec², estimated from satellite night lights) and When the Milky Way is visible (the best time). A Moon in the sky shortens that window.

ISS — lunar and solar transits

The International Space Station crosses the Moon's disk in about half a second. MoonAlign forecasts it to the second from NASA orbit data.

1. Choose Subject ISS and Body Moon (or Sun).
2. 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. Tap a row to move the map to that band. Daytime and near-horizon bands are collected in a folded group.
3. Set the shooting spot on a band and tap Search 14 days under ISS lunar transit.
4. Check each result's 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.

ISS passes (folded) lists the ISS crossing the night sky rather than the Moon: brightness, peak altitude, direction, and how long it's visible.

Plane — live watch

A plane crossing the Moon can't be forecast in advance. Instead, MoonAlign watches live air traffic around your shooting spot and warns you seconds before a crossing.

1. Choose Subject Plane and set your shooting spot.
2. Set Max distance (km) and tap Start live watch. The default source is adsb.lol public traffic (updated every 30 seconds, stops automatically after 2 hours).
3. 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.

• Run your own ADS-B receiver (readsb, dump1090)? Turn on My receiver and enter its aircraft.json address — it's faster and more accurate.
• While watching, the shooting spot and body are locked. Tap Stop watching first to change them.
• Transit history keeps past candidates.
• Camera auto capture (Sony · Canon): connect your camera over USB and it bursts automatically around the crossing. Try Test shutter for 1 second first.

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); abroad 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).
• 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.
• 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 image. Drag the scene to look around.

Photorealistic 3D abroad

There are two ways to see photorealistic 3D buildings for shooting spots outside Korea.

• Overseas 3D subscription (monthly or yearly) — works with no setup.
• Your own Google API key (free, optional) — add it under Google API key in settings; it takes priority over the subscription. How to create one is in the Google 3D key section of the home page.

With neither, you'll see terrain only and a one-time card in the scene. Building display has a daily usage limit; if you hit it, buildings come back the next day.

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.

1. In the Photo Check tab, load a photo with Choose photo. An original photo with capture time, focal length, and GPS (EXIF) works best.
2. Choose the Reference (Moon, Sun, Milky Way, or target) and the Location (this photo's location / the shooting spot / my location).
3. Drag the red ring (the body) and the orange marker (top of the target, or the person's head) onto their real positions in the photo. Zoom in and press and hold to drag precisely.
4. Scrub the Time slider to see the path across the planned time.

• Camera clock off by a few seconds? Enter it in Clock offset.
• 35mm equiv. is the 35mm-equivalent focal length; if it differs from the EXIF value, the original is shown too.
• ISS and plane projects don't have Photo Check.

AR Check — aim on site

On the day, hold up your iPhone or iPad on site and the planned path appears over the real sky, so you can frame the shot before the Moon rises (real devices only, not on the Mac).

• 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 returns to the start.
• 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.

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. 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. Widgets show what the app last calculated, so open the app once in a while.

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.

Sharing as a link

To share a plan with a friend, tap Share as Link… and send it in any messenger. When they tap the link, the Shared plan screen opens and Import creates a new project. 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.
• If a messenger cuts the link off, use Export as File… to send a .moonplan file 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

Troubleshooting

For anything else, write to support@yjlab.io.