AstroPlan — User Guide

AstroPlan is an iOS app for astrophotographers and visual observers. It combines your location, weather, moon phase, light pollution (Bortle), equipment, and imaging style to rank deep-sky objects, planets, and the Sun for any night you plan—then helps you explore them on a live sky map.

The app has five main tabs: Home, Targets, Calendar, Sky Map, and Settings.

Free vs Pro: Core planning—tonight’s ranked targets, calendar, disc sky map, and basic conditions—is free. AstroPlan Pro (subscription) unlocks equipment rigs, the full catalogue, richer guides, hourly forecasts, and unlimited AR. See AstroPlan Pro.

Table of contents

Getting started

AstroPlan Pro

Home

Targets

Target details

Calendar

Sky Map

Site horizon

Settings

Location & saved sites

Equipment & field of view

How targets are ranked

Reminders & notifications

In-app learning tour

Permissions

Data sources & privacy

Tips & troubleshooting

Getting started

On first launch, AstroPlan:

• Asks for location permission so it can use GPS for sky calculations and weather.
• Asks for notification permission if you later set imaging reminders or favourite alerts.
• May offer a short guided tour (Home & Targets) highlighting key controls.

All astronomy for rise/set, transit, moon phase, imaging windows, and target scoring runs on your device (pure Swift). Weather and Bortle data are fetched from the internet when you refresh or change location. Some Pro guides use on-device text first, with optional cloud AI when available.

Planning date: Almost everything follows the date shown on Home (sky header). Change it to plan a future or past night; the app recomputes targets, moon, and darkness for that date.

Active location: Shown under the date on Home. By default the app follows GPS. You can pick a saved site, search for a place, or drop a pin on the map—then all tabs use those coordinates until you switch back to GPS.

AstroPlan Pro

AstroPlan Pro is a subscription managed through your Apple ID. Open Settings → Pro to upgrade, restore purchases, or manage your subscription.

What stays free

What Pro unlocks

Pro content may show an AI or on-device attribution footer depending on network and availability. Guides still work offline using built-in fallbacks.

Home

Home is your nightly dashboard.

Sky header card

Three rows:

Current conditions / Sky plan

• Today: Section title is Current Conditions. Shows moon phase, Bortle light-pollution class (with SQM when available), seeing, transparency, cloud cover, wind, humidity, and dew margin.
• Other dates: Section title is Sky Plan. Shows moon, Bortle, days to new moon, and darkness (astronomical night length) instead of live seeing/cloud.

Tappable items:

• Moon → Moon detail (NASA phase image, rise/set, illumination, age).
• Bortle → Light pollution map centered on your site, with a Bortle legend.
• Seeing, Transp., Cloud, Wind, Humidity, Dew (today only) → Hourly detail charts through the conditions window (Pro). Free users see current values only; tapping opens the Pro paywall.

Best imaging window

Shows the span of astronomical darkness (sun more than 18° below the horizon) for your location and selected date:

• Start and end times, plus total duration.
• Twilight timeline — visual band of civil, nautical, and astronomical twilight, moon up/down, and sunrise/sunset.
• Chart icon (Pro, today only) — expands an hourly breakdown inside the dark window (cloud, wind, humidity). For future nights, astronomy-only planning is shown without hourly weather overlap.

If there is no astronomical darkness (e.g. polar summer), the card explains that no dark window exists tonight.

Tonight’s Outlook

A go/no-go synopsis for the selected night:

• Free: Verdict headline (e.g. promising, marginal, unlikely) with colour cue.
• Pro: Full paragraph covering cloud, moon, site Bortle, and dark-window weather when forecast data is available. For dates outside the 7-day forecast, moon and darkness context only.

Works for future planning dates as well as tonight.

Tonight's top targets

The highest-ranked objects for your location, date, and sky. Each row shows catalogue ID, name, max altitude, and a score bar. Tap a row for full target details. Swipe through neighbours in the pager when opened from a list.

Tonight's rig

Summary of your active equipment profile (telescope, camera, FOV, focal length, aperture). Tap to open My Equipment in a sheet. Pro required to save rigs; free users see an upgrade prompt.

7-day / 3-day forecast

Shown only when the selected date is today. Horizontal strip of upcoming nights with:

• Observing quality band (excellent → poor)
• Moon phase and illumination
• Cloud and wind summaries
• Bortle at your site
• Free: First 3 nights.
• Pro: Full 7 nights.

Use this to pick a clearer night before you commit to a long imaging run.

Targets

Tonight's Targets lists every object that passes your filters for the same planning date as Home, sorted by visibility score.

Search

Filter the list by object name, catalogue ID (e.g. M31, NGC 7000), or constellation.

Catalogue & Favourites

• Catalogue — Browse the full in-app catalogue (Messier, NGC, IC, planets, Sun) grouped by type. Free: open Popular targets and anything on tonight’s ranked list; other rows show a lock and open Pro. Pro: open any object. Search and type chips work the same as on the main list. Popular limits to a curated classic-imaging subset.
• Favourites — Objects you have starred. Always open, even without Pro. Persists across app launches.

Filter chips

• All — Clear type filter.
• Popular — Curated well-known imaging targets.
• Per type — Galaxy, nebula types, clusters, planets, etc. Tap again to clear.

These chips combine with Settings → Target Filters (minimum altitude, minimum aperture, premier-only, imaging style).

List rows

Each row shows:

• Rank (in ordered list)
• Thumbnail, catalogue ID, name, constellation, type
• Favourite star (toggle without opening detail)
• Visibility rating (Excellent / Good / Fair / Poor / Not recommended)
• Transit altitude and magnitude
• Gold star on catalogue ID = premier flagship target
• Lock badge on catalogue rows that need Pro

Tap a row for target details. Use the pager to move between objects in the current list order.

Target details

Opened from Home, Targets, Catalogue, Favourites, Calendar, or Sky Map.

Hero image

Reference image with credit. Tap for full-screen view (pinch/zoom). Sun and many DSOs use curated or catalogue art. Premier images can be cached for offline use (see Settings → Offline Images).

Tonight's visibility

• Rise, Transit, Set times (local)
• Max altitude at transit
• Moon separation — angular distance from the moon; colour indicates how favourable (wider is better for faint DSOs)
• Score — 0–100% visibility score (see How targets are ranked)
• Imaging window — overlap between object visibility and astronomical darkness
• Clear of your horizon — when you have traced a site horizon, hours the target stays above obstructions during darkness

Score breakdown (Pro)

Expandable card showing points from altitude, moon separation, moon illumination, dark-window overlap (or horizon-clear time), premier bonus, type/moon synergy, Bortle adjustment, and imaging-style affinity. Free users see total score with an upgrade prompt.

Tonight's Guide

Plain-English why tonight and framing tips for ranked targets.

• Free: Teaser for your #1 target; upgrade prompt for others.
• Pro: Full guide on every ranked target; Quick questions sheet for follow-ups.

Best season / Solar imaging

• Deep-sky objects: Best season card (opposition-style guidance for when the object is well placed in the evening sky).
• Sun: Separate solar imaging season guidance for daytime work.

Altitude curve

Chart of object altitude through the night for the selected date.

Field of view (FOV) — Pro

If you have at least one equipment profile, a card shows how the object fits your active rig (or lets you preview other saved rigs). Indicates whether the object is a good fit, tight, or too small/large on your sensor. Free users see a locked preview.

About

• Free: Short catalogue about text and basic photography tips where available.
• Pro About: Expandable article—overview, deep dive, what to look for, tonight’s context.

Pro Imaging Guide — Pro

Expandable structured guide: filters, subs, integration, processing, drizzle, dither, tonight’s notes—tuned to your rig and Bortle when equipment is configured.

Session checklist — Pro

Checklist of moon, light pollution, weather, and rig prep items for this target tonight. Free users see an upgrade prompt.

Object data

Catalogue ID, type, constellation, magnitude, angular size, RA/Dec, and minimum recommended aperture (0 = visible naked eye).

Toolbar

• Star — Add/remove favourite.
• Bell — Set or edit an imaging reminder (see Reminders). Per-target Notify anyway overrides the cloud threshold.

When opened from a list with multiple targets, a pager at the bottom moves to previous/next object in that list.

Calendar

Plan beyond “tonight” with four modes (segmented control): Day, Week, Month, Year. Use chevrons to step the period forward or backward.

Day

For the selected day:

• Moon phase and illumination
• Astronomical dark window (if any)
• Top targets for that date at your location (up to ten), tappable for details

Week

Seven rows (one per day): date, moon phase, best target that day, and its visibility rating. Tap a day for day detail (full day view as above).

Month

Grid of days with moon icons and quality hints. Tap a day for day detail; tap the month title where offered for month overview.

Year

Twelve-month overview for long-range planning (moon and seasonal patterns).

Calendar computations use your active location from Home/Settings. They do not change the global “planning date” on Home unless you open a day and then align Home’s date yourself.

Sky Map

Interactive map of the sky for your location and planning context. Opens in AR mode by default: hold the phone up and the map aligns with the real sky using the compass and motion sensors. Toggle to disc map mode for a traditional zenith-centered chart.

AR access (free trial)

• First 7 days after install: unlimited AR.
• After trial (free): 3 AR sessions per day (resets at midnight). Status shown on the map; tap when limit reached to upgrade.
• Pro: Unlimited AR.

Gestures

Reset returns zoom/pan (disc) or default AR FOV.

Use portrait orientation for AR; landscape may show a prompt because the projection is tuned for portrait.

Toolbar

• AR / map toggle — Switch between augmented reality and disc view.
• Live camera — Show the real sky through the camera with the overlay blended on top (requires Camera permission). Adjust blend in Layers.
• Search — Find Sun, planets, bright stars, or DSOs. Selecting one starts find-in-sky guidance: in AR, gold edge arrows show which way to turn and tilt your phone until the crosshair sits on the target; in disc mode the chart pans and zooms toward the object with the same arrows if it is off screen. Tap × on the banner to stop guiding.
• Layers — Control what is drawn (see below).
• Site horizon — Trace or edit your local obstruction profile (see Site horizon).
• Moon / Sun align (AR) — Fine-tune overlay alignment against the real moon or sun when visible.

Selection banner

When you select a deep-sky object on the map, a banner appears with name and type. Tap through to target details for that object.

Share

Export an annotated snapshot of the current sky view with a caption (useful for planning posts or notes).

Layers sheet

Sky objects

• Stars
• Planets & Sun
• Deep-sky objects
• Tonight's Top 10 only — Restrict DSOs to the current top ten ranked targets

Constellations

• Stick figures (constellation lines)
• Constellation art — Silhouettes from member stars
• Constellation names

Horizon

• Horizon silhouette (uses custom site horizon when traced)

Reference lines

• Celestial equator
• Ecliptic
• Alt/az grid

Equipment overlays (when a rig is active — Pro)

• Sensor field of view rectangle
• Telrad-style circles

Live camera

• Toggle live video background
• Overlay blend slider (map vs camera)

Deep-sky filter

• All, Galaxies, Nebulae, or Clusters (affects DSO plotting only)

Layer choices are remembered between sessions.

Site horizon

Trees, buildings, and hills block part of the sky. AstroPlan lets you trace a site horizon so rankings and imaging windows account for real obstructions.

Tracing

• Open Sky Map while physically at the observing site (GPS must match the active location within about 1 km).
• Tap the mountain toolbar icon (or Trace horizon in Layers).
• Point the phone at the skyline and tap along the treeline or rooftops. With live camera on, tap directly on obstructions in the video feed.
• Save when enough azimuth bins are covered (or save empty to clear a previous profile).

You cannot trace for a saved site you selected from home until you visit it. A horizon traced on a previous visit is still used for planning.

Effect on planning

• Target scores gain horizon-clear points when the object stays above your traced skyline during darkness.
• Peak imaging window on target detail may shrink to the longest uninterrupted clear run.
• The horizon silhouette on Sky Map reflects your profile.

Horizon data is stored per saved location on device.

Settings

Help

• Learn AstroPlan — Interactive spotlight tours (see In-app learning tour).
• User Guide — Full documentation on the web (opens in Safari). Same content as this guide.

Location

• Current location name and Bortle class (auto from LightPollutionMap.info unless overridden).
• Manual Bortle override — Slider from Auto (0) to 9. Use this if the map API does not match your experience at a familiar site. Changing it triggers a data refresh.

Map

Location Map — Same map as Home’s location sheet, pushed on the navigation stack (no Done button; use back).

Equipment — Pro

My Equipment — Manage telescope/camera rigs (see Equipment). Free users see Pro and the paywall.

Target filters

• Imaging style — Balanced, Broadband (LRGB/OSC), Narrowband (Ha/OIII), or Planets & Sun. Biases rankings toward targets that suit how you image.
• Filter presets — Built-in and custom one-tap combinations of type, altitude, aperture, premier, and popular filters.
• Min. altitude — Objects must reach at least this altitude at transit (0–60°, step 5°). Default 15°.
• Min. aperture — Hide objects that need a larger telescope than your limit (0 = any; steps of 50 mm).
• Premier targets only — Preference toggle (premier objects are flagship targets marked with a gold star in lists).

Display

Night vision red tint — Applies a red multiply overlay while AstroPlan is open to preserve dark adaptation. For a system-wide red filter, use iPhone Settings → Accessibility → Display & Text Size → Color Filters.

Notifications

• Max. cloud cover — Alerts only fire when forecast cloud is at or below this threshold (unless overridden).
• Notify anyway (all alerts) — Global override; also available per target from the bell on target detail.
• Favourite target alerts — Optional notification when a starred object’s imaging window approaches.
• Imaging window Live Activity — Lock-screen / Dynamic Island card with cloud, wind, dew margin, and time until astronomical dark ends.

Alerts re-check cloud cover about 3 hours before they fire.

Sky conditions

Read-only snapshot of seeing, transparency, cloud %, wind, humidity, and dew, plus Refresh conditions to reload weather and Bortle.

Moon

Phase name, illumination %, and lunar age (days).

Catalog

Counts: total catalogue objects, tonight’s visible targets, premier object count.

Offline Images

• Cache on Wi‑Fi — Automatically cache popular target photos on Wi‑Fi.
• Download premier images — Pull high-res copies for offline use at the eyepiece.
• Clear image cache — Free storage.

Pro

Upgrade, restore purchases, manage subscription (Apple ID). Status shows Active or Free.

About

App version, astronomy engine note, and attributions for Open-Meteo (weather) and LightPollutionMap.info (Bortle).

Location & saved sites

Open from Home → Location or Settings → Location Map.

Map

• Active site — Large pin; all calculations use this point.
• GPS pin — Shown when GPS is on but differs from the active pin (e.g. you selected a saved site).
• Saved locations — Pins you have stored; tap a row to activate. Can store an optional site horizon from a visit.
• Search result — Temporary pin from place search.
• Dropped pin — Long-press (~0.6 s) on the map, then name and Save or Use without saving.

Search

Type a city or place name; pick a suggestion or submit. Use sets it as the active location for tonight. Save adds it to your saved list for one-tap reuse.

GPS

Use Current GPS Location returns to live GPS tracking and refreshes coordinates as you move.

Saved locations are stored on device (SwiftData). Deleting a saved row removes it from the list.

Equipment & field of view

Pro feature. Configure one or more rigs (telescope + camera). The active rig (checkmark) drives Home’s “Tonight’s rig” card, Sky Map FOV overlays, and default FOV on target pages.

Adding a rig

Tap + and enter:

• Profile name
• Telescope name
• Focal length (native mm) and optional focal reducer multiplier
• Aperture (mm)
• Camera name and sensor size (width × height mm)

FOV is computed from plate scale and shown as arcminutes or degrees.

Managing rigs

• Tap the circle to set active.
• Tap the row to edit.
• Swipe to delete.

On target detail, the FOV card compares the object’s angular size to your sensor field and labels fit quality (good fit, tight, too large, too small for useful detail, etc.). You can switch which saved rig to preview without changing the active rig.

How targets are ranked

For each night, AstroPlan scores every catalogue object at your latitude/longitude. Objects below a minimal score are hidden; the rest sort highest first.

Score ingredients (0–100):

Ratings:

Objects need roughly >10° altitude at transit to be scored meaningfully. The list also respects your minimum altitude, minimum aperture, premier-only, and imaging style settings.

Catalogue contents: Hundreds of Messier/NGC/IC entries plus Sun and major planets with positions computed for the selected date.

Reminders & notifications

On any target detail page, tap the bell:

• 10 minutes, 1 hour, 12 hours, or 24 hours before the imaging window
• Notify anyway — Fire even if cloud exceeds your threshold
• Remove reminder if one is already set

Favourite alerts (Settings): optional lead-time notification for starred objects.

Reminders are stored on device. AstroPlan schedules a local notification when:

• The object’s visibility score is above a minimal threshold,
• Cloud cover is at or below your max. cloud cover setting (default 20%) at the recheck ~3 hours before fire—unless Notify anyway is on,
• The astronomical imaging window is still in the future,

Notification fires at your chosen lead time before the window (or at least 30 seconds from now). The message includes clarity and the object’s imaging window times.

Live Activity (optional): while the imaging window is active, the lock screen can show cloud, wind, dew margin, and remaining dark time.

Allow notifications when iOS prompts you; without permission, reminders are saved but alerts will not appear.

In-app learning tour

Settings → Help → Learn AstroPlan offers five spotlight tours:

The first time you use the app, the Home & Targets tour may start automatically. Tours switch tabs, open Equipment when needed, and switch Calendar modes for each step. You can dismiss any tour and replay topics from Learn AstroPlan.

TipKit hints may also appear on some controls (catalogue button, cloud cell, calendar, sky map, etc.) after you use related features.

For full written documentation, use Settings → Help → User Guide (web).

Permissions

Denying location still allows manual map/search sites; AR and accurate times require a known latitude and longitude.

Data sources & privacy

Network requests identify the app as AstroPlan/1.0 where required. Favourites and filter prefs use UserDefaults; locations, equipment, reminders, and horizons use on-device SwiftData. AstroPlan does not require an account. Subscriptions are handled entirely by Apple.

Tips & troubleshooting

Targets list empty

• Check Settings → Min. altitude, Min. aperture, and Premier only.
• Confirm location is correct (polar regions may have few objects above the horizon).
• Change the planning date on Home if you are looking at a future afternoon.

Bortle shows “–” or wrong class

• Wait for refresh after GPS fix.
• Set manual Bortle in Settings if the map grid does not match your site.
• Open Bortle from conditions to view the pollution map.

Weather / seeing unavailable

• Requires network. Tap Refresh conditions in Settings.
• Open-Meteo may be unreachable; astronomy still works offline for rise/set and targets.

AR map misaligned

• Calibrate using moon or sun align buttons when they are visible.
• Calibrate the compass away from metal and magnets; wave phone in a figure-eight.
• Use portrait; enable location services.
• Toggle off AR and use disc mode if sensors are unreliable indoors.

AR limit reached

• Free users get 3 AR sessions per day after the 7-day trial. Upgrade to Pro or use disc map (unlimited).

Catalogue row locked

• Free users can open Popular targets, tonight’s list, and favourites. Upgrade for the full catalogue.

Reminders never fire

• Enable notifications for AstroPlan in iOS Settings.
• Check max. cloud cover and whether Notify anyway is off—alerts skip cloudy forecasts unless overridden.

Pro guide says “AI unavailable”

• On-device fallback text is shown. Check network for full AI articles.

Night vision tint

• Only affects AstroPlan while open; lower screen brightness separately.

7-day forecast missing or shortened

• Forecast strip appears only when Home’s selected date is today. Free shows 3 nights; Pro shows 7.

Horizon trace disabled

• You must be on site (GPS near the active pin). Visit the location or trace on a previous trip.

Quick reference — main tabs

Document version: 1.1 — matches AstroPlan app build 1.0.0 (Pro tier). PDF copy: HELP.pdf in this folder. Web copy: astroplan.p2apps.com. For developer navigation structure, see AstroPlan-App-Navigation-Map.pdf. Regenerate PDF: python3 scripts/gen_help_pdf.py (requires reportlab). Regenerate website: python3 scripts/build_help_site.py.