MyAstroBoard Documentation

Documentation v1.8.3

Your sky, planned and remembered.

MyAstroBoard is a self-hosted astronomy dashboard: it tells you whether tonight is worth setting up, which targets suit your sky and your gear, and keeps a logbook of everything you image. Your data stays on your server.

Quick start Visual tour Live demo

I want to...

What it looks like

Tonight's targets on the sky map A night planned target by target The sky you have covered

All pages

Note

Some parts of the documentation may be generated with AI.

Why? Documentation is one of the least exciting tasks, but one of the most important.

The pages are grouped by who reads them: using MyAstroBoard, running an instance, and contributing to the code. Not sure where a screen is documented? See Where is it? below.

Using MyAstroBoard

Getting started

• Quick Start - from a fresh install to your first night plan
• Visual Tour - every tab, with screenshots
• Beginner Experience - setup wizard, difficulty ratings, “Tonight for you”, Beginner Catalog
• Glossary - AstroScore, airmass, Bortle, seeing and the other terms on screen
• My settings - theme, startup tab, locations, notifications, password and 2FA, your data
• Phones and tablets - install the app, offline page, push notifications

Tonight

• Astrophotography tab - best imaging window, Moon, Sun, aurora, events calendar
• Weather - Open-Meteo forecast, 7Timer seeing, astro-analysis, alerts
• SkyTonight - targets, AstroScore, catalogues, visibility calendar, framing simulator
• Spaceflight - launches, astronauts, ISS and CSS passes and transits

Planning and logging

• Plan My Night - the night’s timeline, optimizer, exports
• Observation Log - one record per night, what you shot and in which conditions
• Astrodex - your collection of imaged objects, pictures, Photo Map, Catalogue Collection
• Your Sky and Wishlist - progress, sky coverage, best months, what to image next
• Share Cards - ready-to-post images of a picture, a session, tonight’s sky or an event

Equipment

• Equipment - telescopes, cameras, mounts, filters, combinations, FOV, sharing
• Exposure Calculator - sub-exposure length, sky background, integration time

Observatory and integrations

• Observatory - live AllSky image, keogram, timelapse, sensor data
• Home Assistant - sky conditions, targets, events and your activity as Home Assistant devices
• Astrodex Stream - your Astrodex as a Home Assistant camera
• MyAstroShine - send a picture out for re-processing, get the result back

Running an instance

• Installation - Docker, Home Assistant app, system requirements
• Updating - update notice, update, back up, roll back
• Reverse Proxy & HTTPS - NGINX Proxy Manager, Traefik, secure cookies
• Troubleshooting - common problems and how to report one
• Configuration - the App settings tab: constraints, application settings, backup, logs, metrics
• Locations - up to five location presets, attribution, per-user active location
• Users and authentication - roles, sessions, trusted networks, two-factor authentication
• Connectors - AllSky, MQTT, MyAstroShine and Astrodex Stream setup
• Notifications - browser and Web Push notifications (triggers N1-N9, VAPID, iOS)
• Database - SQLite storage, upgrade from 1.6, recovery command line
• Privacy & GDPR - personal data inventory, third parties, retention, user rights
• Demo Mode - a public, read-only demo instance
• Security policy - security model, reporting a vulnerability

Contributing

• Contributing guide - setup, style, tests, pull requests
• Organization - architecture, source tree, runtime data
• Extending MyAstroBoard - extension points and the no-new-dependency-cycles rule
• API Endpoints - every HTTP route
• Cache System - background cache, per-job TTLs, per-location slots, map tiles
• Translations - adding or improving a language
• Release Guide - publishing a version
• Changelog - released and unreleased changes

Where is it?

Quick links

• Install: docker compose up -d, then open http://localhost:5000
• Default credentials: admin / admin (change them at once)
• Update: docker compose pull && docker compose up -d
• Source code: https://github.com/myastroboard/myastroboard
• Report an issue: https://github.com/myastroboard/myastroboard/issues

License

MyAstroBoard is open source software licensed under the AGPL-3.0 License. Copyright (C) 2025-2026 WorldOfGZ and contributors.

In accordance with AGPL-3.0 requirements for network use, the corresponding source code for deployed versions is available in this repository: https://github.com/myastroboard/myastroboard

Quick Start

From a fresh installation to your first night plan. Each step links to the page that covers it in full.

1. Sign in and change the default password

Open http://<host>:5000 and sign in with admin / admin. A warning reminds you to change that password at each sign-in until it is done (My settings -> Security). See AUTHENTICATION.md.

2. Follow the setup wizard

On a fresh install the admin account opens a guided wizard: location, sky quality (Bortle / SQM), equipment, notifications, then a preview of tonight’s best targets. Every step can be skipped and done later. See BEGINNER_EXPERIENCE.md.

What the wizard fills in can be changed afterwards:

3. Wait for the first SkyTonight run

SkyTonight computes tonight’s targets in the background: once at startup, then one hour after nautical dawn and one hour before nautical dusk. The first run takes a few minutes; its progress shows in the SkyTonight tab. To rerun it after changing a setting, use Run SkyTonight Now in App settings -> Configuration. See SKYTONIGHT.md.

4. Decide whether tonight is worth it

• Astrophotography tab: the night’s score, the best imaging window, the Moon, the Sun, aurora and upcoming events (ASTROPHOTOGRAPHY.md).
• Weather tab: hourly forecast, seeing and transparency, observation conditions (WEATHER.md).

5. Pick targets and plan the night

1. In SkyTonight -> Deep Sky Objects, sort by AstroScore, filter by type or constellation, and open a target for its altitude chart and details.
2. Add targets to Plan My Night (Astrodex -> Plan my night), set a duration for each, and let the optimizer order them by visibility (PLAN_MY_NIGHT.md).
3. Check the framing of a target with your camera in the framing simulator (SKYTONIGHT.md).

6. After the night

• Turn the plan into an Observation Log session and record what you actually shot (OBSERVATION_LOG.md).
• Add your pictures to the Astrodex, your personal collection of imaged objects (ASTRODEX.md).
• Watch your progress in Your Sky and keep a Wishlist of what is next (SESSION_ANALYTICS.md).

Next steps

• Several sites or several users: LOCATIONS.md, AUTHENTICATION.md
• Phone use and push notifications: MOBILE.md
• HTTPS and remote access: 6.REVERSE_PROXY.md
• Something does not work: TROUBLESHOOTING.md
• Updating: 3.UPDATE.md

Last updated 2026-11-13

MyAstroBoard - Visual Tour

A walkthrough of MyAstroBoard’s interface, tab by tab - from tonight’s go/no-go decision to the logbook of everything you have imaged. Each section links to the page that documents the feature in full.

Table of Contents

1. Astrophotography
2. Weather
3. SkyTonight
4. Astrodex
5. Spaceflight
6. Observatory
7. Equipment
8. My settings
9. App settings
10. Everywhere

Astrophotography

Everything you need to decide whether tonight is worth setting up the telescope. Details: ASTROPHOTOGRAPHY.md.

Astrophotography

The night’s conditions through an astrophotographer’s eyes - clouds, transparency, seeing, wind, humidity, dew risk - with alerts when something will spoil the session.

Best window

The best imaging window of the night, computed in three modes: Moon below the horizon, Moon below 5 degrees, or Moon less than 15% lit.

Moon

Phase, rise and set, altitude chart, dark-sky window, the next nights and a monthly phase calendar. Lunar eclipses are highlighted.

Sun

Twilight times, altitude chart and the next solar eclipse for your location.

Aurora Borealis

Kp forecast and a visibility assessment for your latitude.

Events Calendar

Upcoming sky events - conjunctions, oppositions, meteor showers, eclipses, ISS transits - with the parameters that help you prioritize them. An event can be turned into a share card.

Weather

Details: WEATHER.md.

Weather

Hourly forecast for the night from Open-Meteo: temperature, precipitation, cloud layers, wind, pressure.

Seeing Forecast

Seeing and transparency from 7Timer for your location.

Observation Conditions

Time series of the atmospheric conditions to find the sweet spot of the night.

SkyTonight

SkyTonight computes the best targets for the coming night from a dozen catalogues and ranks them with an AstroScore (visibility, sky quality, brightness, comfort). Details: SKYTONIGHT.md.

Plot

A polar map of the sky with the path of every observable target tonight; click a target to inspect it.

Deep Sky Objects

Thousands of deep-sky objects, scored and sorted. Filter by type, size, magnitude, constellation, AstroScore, or by how well a target fits your equipment. “Tonight for you” picks a few targets matched to your experience level (BEGINNER_EXPERIENCE.md).

Each target opens a details panel with catalogue names, transit time, a visibility calendar over the year, and the equipment combinations that suit it best.

The Beginner catalogue is a curated list of forgiving targets, each with an explanation.

Solar System Bodies and Comets

The Moon and planets, and the comets currently observable, from live orbital elements.

Altitude charts

An altitude-vs-time chart for every target, with the astronomical night and the observable zone, and your horizon profile.

Framing simulator

Your sensor’s field drawn over a real image of the sky around a target, with rotation and up to three equipment combinations compared side by side. Also opens from the Wishlist, Plan My Night and the Astrodex. See SKYTONIGHT.md.

Astrodex

Your logbook, from the plan to the finished picture: Plan -> Observe -> Log -> Astrodex.

Astrodex

Your collection of imaged objects, with your pictures, their acquisition details, ratings and notes. A picture can be turned into a share card, or sent to MyAstroShine for re-processing (MYASTROSHINE.md). Details: ASTRODEX.md.

Plan my night

Turn your SkyTonight shortlist into a timeline for the night: durations, ordering (by hand or by the optimizer), live progress during the night, CSV and PDF export. Shared equipment combinations appear in the combination selector alongside your own. Details: PLAN_MY_NIGHT.md.

Observation Log

One record per night: conditions, equipment, and what you shot on each target. A plan becomes a session in one click, and frames logged on a target add it to the Astrodex. Details: OBSERVATION_LOG.md.

Your Sky

Everything the Observation Log knows, read back to you: total integration time, the object types and constellations you favour, which equipment did the work, and how your ratings line up with the seeing, transparency, SQM and Moon you recorded. Every comparison shows its own sample count, and a group with too few nights behind it says so. Details: SESSION_ANALYTICS.md.

The sky coverage chart draws your captures over the Milky Way and the ecliptic, with the band of sky that never rises from your location shaded out.

Wishlist

The targets you want to image next, with a priority, when each one is next visible, and how many you have already captured.

Photo Map

Where your pictures were taken, on a map, from the locations you entered on them. Whether other users’ pictures appear is an administrator setting.

Catalogue Collection

Pick a catalogue (Messier, Caldwell, Herschel 400…) and see which of its objects you have already caught.

Spaceflight

Details: SPACEFLIGHT.md.

Launches

Upcoming and recent launches, with a detailed view and the webcast when one is available.

Astronauts

Who is in space right now, on which vehicle, and for how long.

Space Events

Mission milestones, spacewalks, dockings and other spaceflight events.

Orbital Stations

Visible passes of the ISS and the China Space Station (Tiangong) over your location, and their transits across the Sun and the Moon.

Observatory

A live panel fed by your own equipment through connectors: AllSky camera image, keogram, startrails, timelapse and sensor data. The tab appears once a connector is enabled. Details: OBSERVATORY.md, CONNECTORS.md.

Equipment

Telescopes, cameras, mounts, filters and accessories, combined into named equipment combinations. Combinations feed the target recommendations, the field-of-view filters, the framing simulator and the exposure calculator. Details: EQUIPMENT.md, EXPOSURE_CALC.md.

Sharing equipment

Every piece of equipment can be marked Share with all users. Shared items show up, read-only, for every other user: in their Equipment tab, the FOV calculator, the target recommendations, the Astrodex picture form and the Plan My Night combination selector. A combination counts as shared only when every piece it uses is shared. When a shared combination goes away, plans built on it are kept and show a warning. Useful for a family or a club that shares a mount or a filter set.

My settings

Each user’s own preferences: theme (including a red night-vision theme), startup tab, density, time format, experience level, their locations, notifications, password and two-factor authentication, and the download of their personal data. Details: USER_SETTINGS.md.

App settings

Administration of the instance (admin only). Details: CONFIGURATION.md.

• Locations: up to five location presets, attributed to users (LOCATIONS.md).
• Configuration: SkyTonight constraints, Astrodex privacy, notifications contact, reverse proxy, MQTT connections.

• Connectors: AllSky, MyAstroShine, MQTT / Home Assistant, Astrodex Stream (CONNECTORS.md, HOME_ASSISTANT.md).
• Logs: live log viewer, levels, retention, and an export to attach to a GitHub issue.

• Users: accounts and roles (admin, user, read-only), trusted networks, two-factor policy (AUTHENTICATION.md).

• Metrics: system, database, scheduler and cache job health.

• Backup / Restore: one archive with your configuration, accounts and collections.

Everywhere

• Sky status widget in the header: the current state of the night and the active location, with a switcher when you have several.
• Share cards: a picture, a session, tonight’s sky or an event as a ready-to-post image (SHARE_CARDS.md).
• Phones: installable as an app, with push notifications (MOBILE.md).
• Six languages: English, French, Spanish, German, Italian, Portuguese.

Last updated 2026-11-13

Beginner Experience

MyAstroBoard is built to stay useful as an astrophotographer’s skill grows, but the app previously assumed prior knowledge: no onboarding, no skill-aware guidance, no starter target list. The Beginner Experience (v1.1, “First Light”) closes that gap with four cooperating pieces:

All of it is opt-out, not opt-in: existing users default to experience_level: advanced, which behaves exactly like before (all targets shown, no filtering).

Guided Setup Wizard

Module: static/js/first_run.js (logic) + templates/index.html#wizard-modal (markup)

Replaces the old single-step “set your location” popup with a skippable multi-step wizard. The steps shown depend on the user’s context, determined once at launch:

function _getWizardFlow(config, currentUser) {
    const locationSet = config.location_configured === true;
    const isAdmin = currentUser.role === 'admin';
    if (!locationSet && isAdmin) return 'full';   // Context A
    return 'user';                                // Context B
}

Location and Bortle steps only appear for the admin doing the initial install, since those settings are shared/global (see CONFIGURATION.md) rather than per-user.

• Equipment step: preset picker (static/data/equipment_presets.json) or manual entry; also lists the user’s existing telescopes/cameras (including shared equipment). Saves via the existing POST /api/equipment/telescopes / cameras endpoints (see EQUIPMENT.md).
• Notifications step: same triggers as My settings -> Notifications, toggle-only; on the fresh install it also asks for the VAPID contact email (see NOTIFICATIONS.md). Skip is always available and never pressured.
• Tonight step: renders the same “Tonight for you” panel described below, then a button to jump straight to SkyTonight.

Trigger and completion state

A new wizard preference tracks completion:

"wizard": { "completed": false, "skipped": false }

The wizard shows when both are false. Skipping (single step or “skip all”) sets skipped: true and persists via PUT /api/auth/preferences - unlike the old popup, the skip is permanent across sessions/devices, not a sessionStorage flag. Users can run it again anytime from My settings -> Customize -> Redo Setup Wizard.

“Tonight for you” recommendations

Endpoint: GET /api/skytonight/recommendations (@login_required) - see API_ENDPOINTS.md

A panel injected above the DSO table on the SkyTonight tab. It reads the user’s experience_level preference, filters dso_results.json to matching difficulty tiers, sorts by AstroScore descending, and returns the top N (default 5, max 10 via ?limit=):

Each card shows the target name, type badge, difficulty badge, estimated integration time, and an “Add to Plan” button. estimated_integration_hours comes from the Beginner Catalog when the target is one of its ~30 curated entries; otherwise it’s a rough estimate derived from the difficulty tier (beginner -> 2h, intermediate -> 4h, advanced -> 8h) and flagged as such via estimated_integration_hours_is_estimate.

The preference is set in My settings -> Customize alongside density/theme, and defaults to advanced so existing users see no behavior change until they opt in.

Beginner Catalog

Module: backend/observation/beginner_catalog.py · Data: backend/catalogues/beginner_catalog.json (34 hand-picked entries) · Endpoint: GET /api/beginner-catalog - see API_ENDPOINTS.md

A “Beginner” sub-tab on SkyTonight showing a card grid (not a table) of curated, forgiving starter targets - bright nebulae, open clusters, and a few landmark galaxies. Each card explains why the object is beginner-friendly and suggests a framing, plus:

• Visible tonight badge, cross-referenced against the current dso_results.json
• Captured state, cross-referenced against the user’s Astrodex
• In plan state, cross-referenced against Plan My Night
• Filters: visible-tonight-only toggle, difficulty (capped at the user’s own experience_level), object type

The catalogue JSON stores only structural data and an i18n_key per object - no English text is hardcoded in the data file. The why_beginner and suggested_framing strings are resolved at request time via I18nManager from beginner_catalog.objects.<i18n_key>.why / .framing in the i18n files, so the whole catalogue is translated in all 6 supported languages.

This tab can be turned off entirely per-user via the beginner_catalog_enabled preference (My settings -> Customize) for users who find it redundant with the DSO table.

Difficulty model

Module: backend/skytonight/skytonight_calculator.py -> compute_difficulty_score()

Every target that SkyTonight computes gets a static difficulty score alongside its AstroScore. Unlike AstroScore, difficulty does not depend on location, date, or Bortle class - the same object is always the same difficulty everywhere. It is computed once per calculation run and stored in dso_results.json as difficulty_score (0-100, lower = easier) and difficulty (beginner / intermediate / advanced).

A fourth factor (minimum integration hours, weight 0.10) is a documented simplification: no per-target minimum-integration data exists in the general catalogue, so it always contributes 0. This caps the theoretical maximum raw score around ~90 instead of 100 but does not move any target across a threshold.

When magnitude or size is missing, the surface-brightness and size components are zeroed and only the magnitude factor is used (“magnitude-only” scoring). If magnitude is also missing, the target gets a neutral default of (50, 'intermediate').

Thresholds: score ≤ 35 -> beginner, 35 < score ≤ 65 -> intermediate, score > 65 -> advanced.

Difficulty is surfaced as a color-coded badge (green/orange/red) wherever a target appears: the SkyTonight DSO table (with a difficulty filter dropdown), Astrodex entries, and Plan My Night entries.

Preferences reference

New keys added to preferences (see AUTHENTICATION.md):

i18n namespaces

Files reference

Last updated 2026-11-13

Glossary

The terms MyAstroBoard shows on screen, in plain words, with the page that explains how each one is computed.

Last updated 2026-11-13

My settings

Every account has its own preferences, in the My settings tab. They follow the account on every device and never affect other users. Instance-wide settings are in App settings, for administrators (CONFIGURATION.md).

Customize

Reset to defaults restores every choice above. The interface language is picked in the footer and is remembered for the account too.

Location

The locations an administrator gave you access to (LOCATIONS.md):

• Default location: the one every tab uses when you sign in.
• Order: the order of the quick switcher in the sky status widget, where you change the active location for the current session.

Notifications

Which alerts you receive, how long before each event, and on which locations. Not available on a demo instance. See NOTIFICATIONS.md, and MOBILE.md for phones.

Security

• Change password.
• Two-factor authentication: turn on an authenticator app (TOTP), when the administrator allows it (AUTHENTICATION.md).
• Download my data: a ZIP with everything the instance stores about you - account, preferences, Astrodex, equipment, plans, observation log, wishlist, pictures and attachments (PRIVACY.md).

Reference

The preferences are stored on the account (users table, preferences) and saved with PUT /api/auth/preferences; the full key list and allowed values are in AUTHENTICATION.md.

Last updated 2026-11-13

Phones and Tablets

MyAstroBoard works in any modern mobile browser, and can be installed as an app (a Progressive Web App) for a full-screen window, an icon on the home screen, an offline page, and push notifications.

Requirements

Browsers only allow installation, offline support and notifications on a secure address:

Installing the app

Android (Chrome, Edge, Samsung Internet): an Install button appears in the footer when the browser allows it; otherwise use the browser menu -> Install app or Add to Home screen.

iPhone and iPad (Safari): tap Share -> Add to Home Screen, then open MyAstroBoard from the new icon. Push notifications on iOS need Safari 16.4 or later and only reach the installed app, never a Safari tab.

Desktop (Chrome, Edge): the install icon in the address bar, or the Install button in the footer.

Offline

The installed app keeps its shell (pages, styles, translations, icons) on the device. When the server cannot be reached, an offline page appears and retries the connection every 30 seconds. Data (forecasts, targets, your Astrodex) always comes from the server: nothing is edited offline.

Notifications

1. Open My settings -> Notifications on the device that should receive them, allow notifications when the browser asks, and pick the alerts you want (plan start, ISS and CSS transits, eclipses, nightfall, aurora, meteor showers…).
2. Tap Test: it sends a real push through the server. On iOS, background or lock the app right after tapping to see it.
3. Each device subscribes on its own; the preferences are shared by all your devices.

The administrator must set a real contact email in App settings -> Configuration -> Notifications, or Apple drops every push. Full reference: NOTIFICATIONS.md.

At the telescope

• Red Light theme (My settings -> Customize) keeps your eyes dark-adapted.
• Compact density fits more rows on a small screen.
• Set the startup tab to the one you open first, Plan My Night for example (USER_SETTINGS.md).

Last updated 2026-11-13

Astrophotography Tab

The Astrophotography tab is the central planning dashboard. It consolidates every piece of data an astrophotographer needs to decide whether to observe tonight and what to expect.

Tab layout

Best imaging window

Module: backend/astroweather/moon_astrotonight.py

Class: AstroTonightService

Cache TTL: 3 hours (CACHE_TTL_BEST_WINDOW).

The best imaging window is the longest continuous block of time where the sky is astronomically dark and moonlight is minimal, according to three selectable modes.

What “astronomical night” means

Astronomical night begins when the Sun’s altitude drops below −18° (astronomical dusk) and ends at −18° on the way back up (astronomical dawn). Only during this window can faint deep-sky objects be properly imaged.

The three window modes

All three modes use Sun < −18° as the primary constraint. The API returns all three simultaneously - the UI shows the one that gives the longest usable window.

Score

The window score (0-100) reflects how good the dark window is:

• 100: No moon interference during full astronomical night.
• 0: No dark window exists (full moon, high latitude in summer, polar day).

API endpoint

GET /api/tonight/best-window returns:

{
  "best_window": {
    "strict": { "start": "22:15", "end": "04:40", "duration_hours": 6.4, "score": 100 },
    "practical": { "start": "22:15", "end": "04:40", "duration_hours": 6.4, "score": 100 },
    "illumination": { "start": "22:15", "end": "04:40", "duration_hours": 6.4, "score": 100 }
  }
}

Moon

Modules: backend/astroweather/moon_phases.py, backend/astroweather/moon_planner.py, backend/astroweather/moon_eclipse.py

Cache TTL: 2 hours (CACHE_TTL_MOON_REPORT).

Moon report (astroweather/moon_phases.py)

MoonService computes:

Libraries used: astronomy (Astronomy Engine) for rise/set and phase search; astropy for AltAz position.

Moon planner (astroweather/moon_planner.py)

7-night forecast table. For each night it computes moonrise, moonset, illumination, and whether there is a usable dark window. This lets astrophotographers pick the best night within the coming week.

API: GET /api/moon/next-7-nights

Lunar phase calendar (astroweather/moon_calendar.py)

Full calendar-month grid shown under “Moon next days”. For every day it computes the illuminated fraction and waxing/waning state from the Moon phase angle (astronomy.MoonPhase, the same formula as the Moon report, so the drawings match the main Moon visual), flags near-new-moon nights (illumination < 15%) as better deep-sky windows, and locates the month’s four principal phases with astronomy.SearchMoonQuarter / NextMoonQuarter, bucketed into local calendar days via the active location’s timezone. Navigation is restricted to a 2-month window: the current month and the next one.

Every day is sampled at the same fixed night hour (23:00 local) - the calendar is a night-observation planning aid, so each cell shows the Moon as it is when you would be out under it, and every cell is computed the same way. This can differ by a few percent from the live #moon-display widget during the day (that one is a “right now” readout); the two converge at night.

API: GET /api/moon/phase-calendar?year=<yyyy>&month=<1-12> - year / month are clamped to the allowed window; missing or malformed values fall back to the current month. The response also carries is_current_month, can_go_prev, can_go_next, today and principal_phases.

Lunar eclipse (astroweather/moon_eclipse.py)

LunarEclipseService finds the next lunar eclipse visible from the configured location.

Astrophotography score factors in: eclipse type (total > partial > penumbral), altitude at peak, and total duration.

API: GET /api/moon/next-eclipse

Sun

Modules: backend/astroweather/sun_phases.py, backend/astroweather/sun_eclipse.py

Cache TTL: 6 hours (CACHE_TTL_SUN_REPORT).

Sun report (astroweather/sun_phases.py)

SunService computes for the current date at the configured location:

Library: astropy - get_sun() + AltAz transforms over a dense time grid to find threshold crossings.

API: GET /api/sun/today

Solar eclipse (astroweather/sun_eclipse.py)

SolarEclipseService finds the next solar eclipse visible from the configured location.

API: GET /api/sun/next-eclipse

Horizon graph

Module: backend/astroweather/horizon_graph.py

Cache TTL: 6 hours (CACHE_TTL_HORIZON_GRAPH).

The horizon graph displays the altitude vs. time curves for the Sun and Moon throughout the current day. This gives a quick visual of when targets are above the horizon and allows users to identify the dark window at a glance.

HorizonGraphService samples altitude and azimuth at 1-hour resolution using astropy’s get_sun() and get_body('moon') with AltAz transforms.

API: GET /api/astro/horizon-graph

Sidereal time

Module: backend/observation/sidereal_time.py

Cache TTL: 1 hour (CACHE_TTL_SIDEREAL_TIME).

Local Apparent Sidereal Time (LAST) is displayed as a quick reference. LAST equals the Right Ascension (RA) of objects currently on the meridian - useful when manually slewing to targets.

API: GET /api/astro/sidereal-time

Aurora

Module: backend/astroweather/aurora_predictions.py

Class: AuroraService

Cache TTL: 1 hour (CACHE_TTL_AURORA).

Data source: NOAA Space Weather Prediction Center

Kp index

The Kp index (0-9) is the primary indicator of global geomagnetic activity. Higher Kp = larger aurora oval extending further toward the equator.

NOAA API: https://services.swpc.noaa.gov/products/noaa-planetary-k-index.json (current), noaa-planetary-k-index-forecast.json (3-day forecast).

Aurora visibility probability

AuroraService.calculate_aurora_probability() estimates aurora probability (0-100 %) from the current Kp and observer latitude:

aurora_edge_latitude = 67° - (Kp × 3.5°)

• Observer poleward of the edge -> probability = 25% + Kp × 7 (max 88%)
• Observer near the edge -> probability = 15% + Kp × 6
• Observer 5° equatorward -> probability = 5% + Kp × 4
• Observer far equatorward -> probability = max(0, (Kp − 3) × 6)

The latitude of 67° is an approximation of the mean auroral oval edge during quiet conditions; the factor of 3.5°/Kp unit is a well-known empirical rule of thumb.

Best aurora window

Auroras are most visible between 22:00 and 02:00 local time (midnight maximum). The service reports whether the current night has a suitable window given Kp and darkness.

API: GET /api/aurora/predictions

Celestial events

Three separate services feed the Calendar sub-tab.

Planetary events

Module: backend/observation/planetary_events.py

Class: PlanetaryEventsService

Cache TTL: 24 hours (CACHE_TTL_PLANETARY_EVENTS).

Covers all seven naked-eye planets (Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune).

Events are computed over a 365-day rolling window from today using astropy body positions.

API: GET /api/events/planetary

Special phenomena

Module: backend/observation/special_phenomena.py

Class: SpecialPhenomenaService

Cache TTL: 24 hours (CACHE_TTL_SPECIAL_PHENOMENA).

Library: astropy - get_sun() position for equinox/solstice crossing detection; SkyCoord for galactic-plane altitudes.

API: GET /api/events/phenomena

Solar system events (meteor showers)

Module: backend/observation/solar_system_events.py

Class: SolarSystemEventsService

Cache TTL: 24 hours (CACHE_TTL_SOLAR_SYSTEM_EVENTS).

Contains a curated database of annual meteor showers with:

Major showers included: Quadrantids, Lyrids, Eta Aquariids, Delta Aquariids, Perseids, Orionids, Leonids, Geminids, Ursids.

Radiant altitude is computed using astropy AltAz transforms - a shower with a radiant below the horizon is flagged as not visible from the configured location.

API: GET /api/events/solarsystem

Upcoming events aggregator

Module: backend/utils/events_aggregator.py

GET /api/events/upcoming merges all three event sources and returns a single sorted list of events in the coming days/weeks - used for the Calendar sub-tab and for push notification triggers N4 and N5.

Push notification triggers

Two astrophotography events feed the push notification system (see NOTIFICATIONS.md):

Last updated 2026-11-13

Weather & Conditions

The Weather tab provides atmospheric conditions specifically analysed for astronomical observation and astrophotography. It combines two independent data sources: Open-Meteo for standard meteorological data and 7Timer for seeing and transparency forecasts.

Tab layout

Weather alerts

Module: backend/weather/weather_astro.py (alert generation)

Alerts are generated from the Open-Meteo data and include:

Alerts are translated using the i18n system and displayed in the Alerts sub-tab.

Open-Meteo weather forecast

Source: Open-Meteo - free, no API key required.

Cache TTL: 1 hour (WEATHER_CACHE_TTL in utils/constants.py).

Module: backend/weather/weather_openmeteo.py

Variables fetched

Cloud layer discrimination

The three cloud-cover layers help astrophotographers distinguish:

• Low clouds (fog, stratus) - completely block imaging.
• Mid clouds (altocumulus) - usually opaque, block imaging.
• High clouds (cirrus) - thin and sometimes transparent; imaging may still be possible.

Total cloud cover is shown as the primary go/no-go indicator.

Rate-limiting behaviour

Open-Meteo free tier allows a limited number of concurrent requests. weather/weather_openmeteo.py implements two protections:

When rate-limited, the API returns the last successful response (stale-while-error) to avoid empty screens.

Astro weather analysis

Module: backend/weather/weather_astro.py

Class: AstroWeatherAnalyzer

This module transforms raw Open-Meteo variables into astrophotography-specific metrics. It calculates conditions for up to 48 hours and caches results for 30 minutes (in-process), and the cache scheduler additionally keeps a 24 h analysis warm per location in the astro_weather shared cache (see docs/CACHE_SYSTEM.md).

The observation score (single source of truth)

observation_score (0-10) is the one overall astrophotography-quality number in the app:

observation_score = (seeing_pickering*10 + transparency_score + cloud_discrimination + tracking_stability_score) / 4 / 10 * precipitation_factor

• seeing_pickering is 1-10; the other three components are 0-100 (so transparency_score, cloud_discrimination and tracking_stability_score must all stay on that scale - a component accidentally left on a 0-1 scale silently contributes almost nothing).
• precipitation_factor (0-1) is a multiplicative veto, not an averaged component.

It is shown, unchanged, by the navbar sky widget pill, the location switcher, the Weather tab’s hourly cards (served on /api/weather/forecast as condition, x10 to a 0-100 range) and the “Score de la Nuit” hourly cards. weather/weather_openmeteo.py no longer derives its own overall score.

Seeing estimate (Pickering scale)

The seeing estimate is derived from wind speed at multiple altitudes and atmospheric stability proxies available from Open-Meteo:

Note: This is a model-derived estimate. For high-resolution planetary imaging, cross-check with the 7Timer seeing forecast below.

Transparency (limiting magnitude)

transparency_score (0-100) is estimated from cloud cover, humidity, and visibility, and is then mapped linearly onto a limiting magnitude between MAGNITUDE_LIMIT_ZENITH_MIN (4.0) and MAGNITUDE_LIMIT_ZENITH_MAX (8.0):

Dew point warning

When the difference between ambient temperature and dew point is ≤ 2 °C (DEW_POINT_WARNING_THRESHOLD), a dew alert is raised. Dew on optics ends a session; plan dew heaters accordingly.

Jet stream impact

Wind speed at 80 m and 120 m altitude is used as a proxy for jet-stream influence. High upper-atmosphere winds correlate with poor seeing even when the surface is calm.

Best astro period

AstroWeatherAnalyzer identifies the best consecutive window within the forecast where:

• Cloud cover is low
• Humidity is acceptable
• Wind is calm
• Dew margin is safe

These “best period” cards are displayed in the Astrophotography tab.

7Timer seeing forecast

Source: 7Timer ASTRO product

Cache TTL: 6 hours (CACHE_TTL_SEEING_FORECAST). On a fetch failure, the cache is left untouched (previous good forecast keeps being served) instead of being overwritten with a failure marker - a transient 7Timer outage no longer blanks the tab for the full TTL window, since the next 5-minute scheduler tick retries once the existing entry’s TTL naturally elapses.

Module: backend/astroweather/seeing_forecast_7timer.py

Class: SeeingForecastService

7Timer’s ASTRO product returns eight fields per 3-hourly timepoint: seeing, transparency, cloudcover, lifted_index, rh2m (humidity), wind10m (direction + speed class), temp2m and prec_type. All of them are decoded and surfaced - not just seeing - and combined into a single composite quality_score (0-10) per timeslot.

Seeing scale (7Timer)

Transparency scale (7Timer)

7Timer’s transparency field uses the same 1-8 shape as seeing (1 = worst, 8 = best), expressed as limiting magnitude per air mass:

Cloud cover scale (7Timer)

1-9 scale, 1 = clearest (0-6% cover), 9 = fully overcast (94-100% cover).

Wind speed scale (7Timer, 10m)

1-8 scale from calm (< 0.3 m/s) to hurricane (> 32.6 m/s), paired with a compass direction.

Composite quality score

Each forecast point’s quality_score (0-10, higher is better) combines four of the raw 7Timer fields:

Active precipitation (prec_type != none) is a hard multiplicative veto (score × 0.1) rather than an averaged component, the same convention used by weather_astro.py’s precipitation_factor: rain or snow shouldn’t be masked by otherwise-clear metrics. lifted_index is decoded and exposed but not scored, since 7Timer’s seeing value already folds atmospheric stability into its own model.

The Seeing sub-tab renders this as an hourly timeline in the same visual style as the Astrophotography tab’s “Score de la Nuit” (night-score-timeline): one card per timeslot with the combined score, a quality badge, and an icon row for every underlying metric (seeing, transparency, cloud cover, wind, humidity, precipitation).

Best windows

Two “best window” cards are computed from the forecast:

• Best Seeing Window - longest consecutive run with seeing ≤ 3 (Good or better), unchanged from the original seeing-only definition - still the relevant metric for planetary imagers.
• Best Overall Window - longest consecutive run with quality_score ≥ 6 (Good or better), reflecting the full picture (seeing + transparency + clouds + wind).

Data sources

• Open-Meteo: open-meteo.com - free, open-source weather API; no account required.
• 7Timer: 7timer.info - free astronomical weather service based on GFS model data; no account required.

API endpoints

Last updated 2026-11-13

SkyTonight

SkyTonight is the built-in observability calculator. It computes, for every target in the dataset, which objects are worth imaging tonight - ranked by AstroScore - and exposes the results through a cached JSON API.

Using SkyTonight

The SkyTonight tab shows the results of the last calculation, in sub-tabs:

From a row you can open the target’s altitude chart, add it to the Astrodex or to Plan My Night, open its visibility calendar and the framing simulator from their icons, and open More: catalogue names, transit time, the best equipment combinations and the Wishlist button.

The results are recomputed twice a night (Scheduler); after changing a constraint, Run SkyTonight Now in App settings -> Configuration recomputes them at once.

Advanced DSO filters

The Deep Sky Objects tab has a collapsible Advanced filters panel above the table. Unlike the text / constellation / type / catalogue / difficulty filters (which run client-side over the rows already on screen), these five run server-side in _build_dso_section_payload, applied before the max_deep_sky_rows truncation cut - so a filtered result set is a genuine catalogue-wide search, not a filter over the top N by AstroScore. They are passed as query params on GET /api/skytonight/data/dso and debounced (~400 ms) with a spinner.

Unknown values are never silently dropped. A target with no magnitude or size (so no surface brightness, no FOV fill, no integration estimate) stays in the result and is shown as unknown; a size / SB / integration filter only excludes a target whose value is present and fails. The response echoes advanced_filters.size_band and the resolved combination so the UI can label the result set and state how many targets were considered after filtering.

Target visibility calendar

GET /api/skytonight/visibility-calendar?target=<id_or_name>&year=<yyyy> answers “when is this object best this year?” for the user’s active location. It is computed on demand (the SkyTonight pipeline only ever covers tonight) and cached in a small bounded in-process LRU keyed (target, location, year) - deliberately not a scheduler cache job, because the key space (any target x any location) is unbounded and the underlying ephemeris changes only once a year.

Deep-sky objects only. Planets and comets move measurably over a year, so a fixed-RA calendar is meaningless for them - the response returns supported: false with reason: "moving_target". reason: "not_found" means the identifier could not be resolved to coordinates (SkyTonight dataset first, then a SIMBAD fallback for Astrodex items outside the dataset).

Sampling scheme

• 24 sample nights: the 1st and 15th of each month across the requested year. Two samples per month keep a single unlucky Moon phase from dominating the monthly figure.
• Per sample night, the Sun and Moon altitude grid (18:00 -> 06:00 local, 10-minute steps) is built once via the shared astroweather.moon_planner.night_body_altitude_grid helper (one Astropy AltAz transform per body).
• The target’s own altitude/azimuth is analytic, from the hour angle H = LST - RA -> alt = asin(sin(dec)*sin(lat) + cos(dec)*cos(lat)*cos(H)), with LST from the same time grid. Arcminute accuracy at O(1) trig per sample.

Constraint gates (kept in sync with the live calculator)

A sample step counts toward observable_hours when the Sun is below -18 deg (astronomical dark) and the target sits between the effective altitude floor and altitude_constraint_max. The floor is the stricter of altitude_constraint_min, the airmass-derived altitude (asin(1 / airmass_constraint)), and the active location preset’s custom horizon_profile at the target’s azimuth (same _horizon_floor_array helper the calculator uses). moonless_observable_hours additionally requires the Moon below the horizon.

Response shape

{
  target:   { id, name, type },
  location: { id, name },
  year, supported, reason?,
  months:  [ { month, dark_hours, observable_hours, moonless_observable_hours,
               max_altitude, moon_illumination_pct, score, bucket } ],   // 12 aggregates
  samples: [ { date, dark_hours, observable_hours, moonless_observable_hours,
               max_altitude, transit_local_time, moon_illumination_pct } ], // 24 raw nights
  constraints: { altitude_min, altitude_max, has_horizon_profile }
}

score is moonless_observable_hours normalized against the best month of the year (falling back to observable_hours when the target is never moonless-observable); bucket is score mapped to 0-5 for the heatmap cell colour. The 24 raw samples drive the per-month tooltip.

Equipment combination recommendations

For any target, POST /api/skytonight/combination-recommendations rates how well each of the user’s enabled and valid equipment combinations (own + shared, see EQUIPMENT.md) suits that target, on a 1-5 scale.

Unlike AstroScore (which rates the night), this rates the gear - it runs on demand per target, independent of the scheduled calculation (Scheduler).

Scoring factors

A combination without a telescope but with lens_focal_length_mm/lens_focal_ratio set (e.g. a DSLR + lens on a star tracker) is scored the same way, using the lens specs in place of a telescope’s optics. A combination that resolves neither a telescope nor usable lens specs is omitted from the results rather than scored arbitrarily.

Disabled or invalid combinations (see EQUIPMENT.md) never appear in recommendations.

Framing simulator

What does my sensor see on this target? The framing simulator shows a real image of the sky around a deep-sky object with the sensor rectangle of an equipment combination drawn to scale. It opens from the frame icon next to a target in the Deep Sky Objects table, from a Wishlist item, from a Plan My Night entry, and as a Framing section in an Astrodex item detail.

• Select up to three combinations to compare them on the same image. One is selected on opening: from Plan My Night, the plan’s own combination; otherwise the best fit - a good fit before a tight one, and among equals the one whose target fill is closest to 35% of the short side.
• Rotate the sensor (position angle, from north through east) and drag the frame - or use the arrow keys - to move it off the target. The coordinates of the frame centre are shown.
• A dashed circle marks the target’s apparent size, when the catalogue gives one.
• Each selected combination gets a verdict from the ratio “target size / short side of the field”: below 10% small (with the target’s width in pixels), 10-60% good fit, 60-100% tight, above larger than the field. In that last case an approximate mosaic grid is given, assuming 15% overlap; only the target’s longest dimension is known, so it is an upper bound for an elongated object and is labelled as an estimate.
• Download image saves the view as a PNG with the target name, the combinations and the image credit.

A combination appears when it is enabled and valid (own or shared), has a camera with sensor dimensions and pixel size, and a focal length - the telescope’s effective one, or the lens of a camera-only combination. Planets and comets are not supported: they move against the stars, so a fixed image of the sky does not apply (supported: false, reason: "moving_target").

Sky image

The background is a 1000 px DSS2 colour cut-out from CDS hips2fits, north up and east left, in gnomonic (TAN) projection centred on the target. A camera sensor is a gnomonic projection too, so the frame is an exact rectangle on the image whatever the field of view.

The server downloads each image once and keeps it in data/cache/framing_images/ (trimmed to 200 MiB, oldest first); the browser never calls CDS. To bound that cache, the field of view of a background is one of a fixed ladder (0.25 to 45 degrees): the page picks the smallest step that is about 2.2 times wider than the widest selected frame. The request carries the target’s catalogue coordinates and nothing about the user.

When CDS hips2fits cannot be reached, the server builds the same cut-out itself from the tiles of the DSS2 colour HiPS published by mirror sites (ESA ESASky, MAST, CSIRO, China-VO - the list CDS published during its November 2026 incident), tried in that order (object_info.DSS2_HIPS_MIRRORS). observation/hips_cutout.py maps each output pixel to the sky, finds its HEALPix NESTED pixel at the tile resolution hips2fits would use, and averages a 2x2 sub-pixel grid; the result matches hips2fits on the same field. The mirrors serve CDS’s own tiles, so the credit stays “DSS2 Color / CDS HiPS”. The same fallback serves the object thumbnails (/api/object-image/<filename>).

Each server (hips2fits and every mirror) is backed off for a few minutes after a failure, so an unreachable one costs a single timeout. When none answers, the frame is still drawn to scale on a dark background, and image cards show a neutral placeholder.

API

• GET /api/skytonight/framing?target=<id_or_name> - the resolved target (coordinates, apparent size), the image key and allowed fields of view, and one frame per usable combination: field of view, image scale, half extent in tangent-plane units, verdict, fill ratio, target size in pixels and the mosaic estimate. default_combination_id names the best fit.
• GET /api/skytonight/framing/image/<ra>_<dec>_<fov>.jpg - the cached background image.

Implementation: backend/observation/sky_framing.py (target resolution, image cache), backend/equipment/framing.py (sensor geometry and verdict), static/js/framing.js.

Architecture overview

Scheduler (backend/skytonight/skytonight_scheduler.py)
  └─ run_calculations()  (backend/skytonight/skytonight_calculator.py)
       ├─ load_targets_dataset()       <- DSOs (OpenNGC / OpenIC / Caldwell / Messier / Herschel400 / Pensack500 / LBN)
       ├─ load_comets_dataset()        <- MPC / JPL comets (auto-updated)
       ├─ Solar-system bodies          <- Skyfield ephemeris (de421.bsp)
       └─ Writes shared JSON to /data/skytonight/
              calculations/dso_results.json
              calculations/bodies_results.json
              calculations/comets_results.json
              calculations/skymap_data.json
              calculations/calculation_results.json   <- metadata-only "all done" signal
              outputs/<target_id>_alttime.json        <- altitude-vs-time graph data

The API (app.py) reads these JSON files; it never re-runs the heavy calculation per request.

Scheduler

Multiple Gunicorn workers are protected by a file-level lock so only one worker runs the calculator at a time.

Target catalogues

Cross-ref catalogues (Herschel400, Pensack500, LBN, GaryImm, Arp) add a catalogue_names entry and a source_catalogues tag to existing NGC/IC records; they never add new coordinates or change the preferred display name. Standalone catalogues (GaryImm, Sharpless, Barnard, vdB, AbellPNe, AbellClusters) create new records for objects with no NGC/IC identifier. Objects selected by Gary Imm in the Sharpless/Barnard/vdB catalogues receive both the catalogue tag and the GaryImm tag via extra_catalogues.

Target names are preferred in this order: CommonName -> Messier -> OpenNGC -> OpenIC -> Caldwell -> LBN -> Herschel400 -> Pensack500 -> GaryImm -> Arp -> Sharpless -> Barnard -> vdB -> AbellPNe -> AbellClusters.

Observability constraints

All constraints are always active (no on/off toggle).

Bodies (planets, Moon) use a relaxed minimum fraction of 0.05 (≈ 22 min) instead of the DSO threshold, because a planet visible for 3 h in a 7 h night is still a prime target.

AstroScore

AstroScore is a dimensionless number in [0, 1] that ranks targets by their suitability for astrophotography tonight from the configured location.

Normalisation helper

All sub-scores use a linear clamp:

1 - Visibility score (weight 0.40)

Measures how well-placed the target is in the sky:

2 - Sky quality score (weight 0.25)

Penalises Moon interference:

3 - Object score (weight 0.25)

Rewards intrinsically bright, high-contrast targets using surface brightness:

Inverting the normalisation means a low SB value (brighter, easier to image) -> high score.

When magnitude or size data are unavailable, a neutral value of 0.5 is used.

4 - Comfort score (weight 0.10)

Rewards targets that are observable during convenient evening hours:

obs_hours_in_window is the subset of observable hours that fall within the prime-time window, not the total observable hours.

5 - Final weighted sum

6 - Bonuses

Applied after the weighted sum, before final clamping:

The final value is clamped to [0.0, 1.0] and rounded to 4 decimal places.

Score interpretation

Difficulty rating

Alongside AstroScore, every target also gets a static difficulty_score (0-100) and difficulty label (beginner / intermediate / advanced), computed once per calculation run from magnitude, angular size, and surface brightness. Unlike AstroScore, difficulty does not depend on location, date, or Bortle class - the same object is always the same difficulty everywhere. It powers the SkyTonight difficulty filter/badges, the “Tonight for you” recommendations panel, and the Beginner Catalog. Full model and thresholds: BEGINNER_EXPERIENCE.md.

Light Pollution Integration

AstroScore includes an optional light pollution penalty based on your site’s Bortle class or a direct SQM (Sky Quality Meter) reading.

Configuration

Set your site’s Bortle class in App settings -> Locations -> (edit a preset) -> Sky quality:

• Bortle Class (dropdown 1-9): choose the class that matches your observing site. You can look up your location on lightpollutionmap.info using the World Atlas layer.
• SQM (optional, mag/arcsec²): enter if you have a real SQM-meter reading. This overrides the Bortle midpoint estimate and gives more precise weighting.

Leaving both fields empty disables the feature entirely - AstroScore behaves exactly as before.

How it affects AstroScore

The LP factor is applied to the sky score component (weight 0.25) of AstroScore, which already accounts for moon phase and angular distance. The combined factor degrades the sky score in proportion to your light pollution level.

Different object types respond differently to light pollution:

At a Bortle 5 (suburban) site, a galaxy loses roughly 20-25 % of its sky score compared to a Bortle 2 site, while planets are unaffected.

API

GET /api/skyquality returns the current sky quality configuration:

{
  "bortle": 5,
  "sqm": 20.55,
  "sqm_source": "bortle_midpoint",
  "light_pollution_factor": 0.5196,
  "description": "Suburban"
}

sqm_source is one of "user_measured", "bortle_midpoint", or "not_configured".

• Barnard dark nebulae: Barnard (1927), VizieR VII/220A
• van den Bergh reflection nebulae: van den Bergh (1966), VizieR VII/21
• Abell planetary nebulae: Abell (1966), ApJS 12, 391; coordinates from SIMBAD (CDS, Strasbourg)
• Abell galaxy clusters: Abell, Corwin & Olowin (1989), ApJS 70, 1; VizieR VII/110A
• Minor Planet Center comet elements: minorplanetcenter.net
• JPL Small-Body Database: NASA JPL
• Skyfield ephemeris: DE421 / DE430 via Skyfield
• Astropy / Astroplan: coordinate transforms, moon illumination

Output files

All paths are relative to /data/skytonight/.

API endpoints

Full parameter details: API_ENDPOINTS.md

Source references

• OpenNGC / OpenIC: Mattia Verga, PyOngc, CC BY-SA 4.0
• Herschel 400: Astronomical League Herschel 400 Observing Program
• Pensack 500: original list by Pensack, Cloudy Nights - 500 Best DSO List
• LBN cross-refs: Lynds’ Bright Nebulae catalogue, YAML source via uptonight
• GaryImm: astrophotography list compiled by Gary Imm, YAML source via uptonight
• Arp Atlas of Peculiar Galaxies: Halton Arp (1966); NGC/IC cross-refs from NASA/IPAC Extragalactic Database (NED)
• Sharpless catalogue: Sharpless (1959), VizieR VII/20

Last updated 2026-11-13

Spaceflight Tracker

The Spaceflight tab keeps you connected to what is happening above the atmosphere: rocket launches, current ISS crew, orbital transits, and upcoming space events.

Tab layout

Launches

Module: backend/space/spaceflight_tracker.py

Data source: Launch Library 2 (The Space Devs)

API base: https://ll.thespacedevs.com/2.2.0/

Cache TTL: 2 hours (CACHE_TTL_SPACEFLIGHT_LAUNCHES).

Launch Library 2 is the de-facto standard for launch data. The free tier allows ~15 requests/hour; MyAstroBoard’s cache keeps live calls minimal.

What is displayed

Image caching

Launch images from the LL2 CDN are downloaded and served locally via GET /api/spaceflight/img/<filename>. This avoids CORS issues and makes the UI work without external CDN access. A .url sidecar file is written alongside each image so it can be re-fetched if deleted.

Rate limiting

If the LL2 API returns HTTP 429 (rate limit), all further calls to the same endpoint are suppressed for 1 hour (_BACKOFF_TTL = 3600 s) to respect the free-tier quota.

Video URLs

GET /api/spaceflight/launch/<launch_id>/vidurls returns available video stream URLs for a given launch, fetched on demand (not cached) to ensure the latest live-stream link is returned.

Astronauts

Module: backend/space/spaceflight_tracker.py

Cache TTL: 6 hours (CACHE_TTL_SPACEFLIGHT_ASTRONAUTS).

Fetches from Launch Library 2 the list of all people currently in orbit:

API: GET /api/spaceflight/astronauts

Space events

Module: backend/space/spaceflight_tracker.py

Cache TTL: 2 hours (CACHE_TTL_SPACEFLIGHT_EVENTS).

Space events include EVAs (spacewalks), dockings, undockings, and other mission milestones tracked by Launch Library 2.

API: GET /api/spaceflight/events

ISS passes

Module: backend/space/iss_passes.py

Cache TTL: 6 hours (CACHE_TTL_ISS_PASSES).

TLE data

Pass prediction requires up-to-date Two-Line Element (TLE) data. The service tries three sources in priority order:

TLE data is cached locally in data/cache/iss_tle_cache.json for up to 6 hours. (Skyfield’s own ephemeris files are stored separately under data/cache/skyfield/.) If all sources fail, the last valid TLE is used for up to 3 hours before the prediction is considered unreliable.

After Celestrak blocked the server, an admin can clear the block with POST /api/iss/celestrak/restart (/api/css/celestrak/restart for the CSS); the banner offers the button to admins only.

Pass prediction algorithm

Library: Skyfield with EarthSatellite propagation (SGP4 model).

The service predicts passes over a 20-day window (max 30) from the configured location.

For each pass:

Passes with max altitude < 10° (MIN_EVENT_ALTITUDE_DEG) are filtered out.

Visible passes require:

• ISS illuminated by the Sun
• Observer in darkness (Sun altitude < −4°, MAX_VISIBLE_SKY_SUN_ALTITUDE_DEG)

Solar transits

A solar transit occurs when the ISS passes directly in front of the solar disk. This is a rare photographic opportunity.

The service refines transit timing to 0.1 s resolution (SOLAR_TRANSIT_REFINE_SAMPLE_SECONDS) and checks whether the ISS angular path crosses the Sun’s angular disk (radius ≈ 0.267°).

Lunar transits

Similarly, a lunar transit occurs when the ISS crosses the lunar disk. Both transit types are returned separately in the API response.

ISS real-time location

GET /api/iss/location returns the current ISS ground position (latitude, longitude, altitude, velocity). The ground track ±50 minutes is computed once per 5 minutes (server-side cache _TRACK_CACHE_TTL_SECONDS = 300) to reduce SGP4 computation.

API endpoints

The /api/iss/passes response includes:

Push notification triggers

See NOTIFICATIONS.md for the full notification system.

Last updated 2026-11-13

Plan My Night

Plan My Night lets each admin or user build a private target timeline for a single observing night.

SkyTonight Integration

From SkyTonight report tables (deep sky, bodies, comets), a dedicated Plan My Night column is available:

• If no plan exists, first add creates the plan automatically.
• If a current-night plan exists, add appends the target.
• If only a previous-night plan exists, add is disabled until plan is cleared.
• Alias matching is powered by catalogue_aliases to avoid duplicates.

Editing Features

• Per-target planned duration (HH:MM).
• Reorder targets (up/down) inside night timeline.
• Mark targets done / undo.
• Remove targets.
• Add target to Astrodex directly.
• Timeline progress bar and current-target banner while within night timeframe.

Equipment Combination Selector

When a user owns or shares more than one equipment combination, adding a target from SkyTonight shows a picker to choose which combination’s plan to target (badges show each combination’s plan state: active/expired/no plan). With exactly one combination, it’s picked automatically. Only enabled and valid combinations (see EQUIPMENT.md) are offered for a new plan; an existing plan on a combination that’s since been disabled still shows correctly instead of disappearing.

A combination used by any plan can’t be deleted while that plan exists (see EQUIPMENT.md) - plans are never silently orphaned by a combination going away.

Schedule optimizer

GET /api/plan-my-night/optimize previews a target order plus a single pre-first-target delay, derived from each target’s real altitude-based visibility window; POST /api/plan-my-night/optimize/apply applies it (rejected if the plan changed since the preview). As of v1.4 the ordering is flip-aware: targets are clustered by observable-run start (those within _FLIP_TIE_BREAK_WINDOW_MINUTES, ~20 min, of the earliest in the cluster), and inside each cluster the one whose meridian flip comes sooner is scheduled first, so it can finish before flipping. Targets with no flip or an unknown mount keep their prior order at the back of the cluster. A flip_mid_session plan warning is raised when a target still ends up straddling its flip.

Meridian flip

Each timeline entry shows a meridian-flip indicator when the plan is pinned to a location and its equipment combination has a mount. The flip time is derived at read time from the entry’s stored RA plus the plan’s pinned location, offset by the mount’s meridian_flip_delay_min - old plans need no migration. The transit is projected in O(1) from a single local-sidereal-time reading at the start of the night (skytonight_calculator._meridian_transit_from_lst), computed once per plan rather than per entry, since the timeline is polled every 30-60 s. Pre-v1.4 mount files with no meridian_flip_required key are backfilled on read (equipment_profiles.normalize_mount_flip_fields), so the indicator works for existing mounts without a re-save.

The tooltip carries the flip time and the mount’s meridian_flip_duration_min (minutes lost to the flip). The indicator also appears in the schedule-optimizer preview and the PDF export.

Log this session

Once a plan has targets, a Log this session button copies them into an Observation Log session (POST /api/observation-sessions/from-plan), then switches to the Observation Log sub-tab.

• It works on both current and previous plans. A plan flips to previous the moment night_end passes - which is exactly when a user sits down to log what they actually captured, so the button is deliberately not gated the way the current-only CSV/PDF export buttons are. Importing is a read operation from the plan’s perspective; the plan itself is never modified.
• Re-importing is idempotent: a plan entry already imported into the target session is skipped, so pressing the button twice never duplicates targets.
• If exactly one session created today already came from this same plan, the user is offered a merge into it instead of starting a second session for the same night.

See OBSERVATION_LOG.md for the full contract.

Exports

• CSV export: GET /api/plan-my-night/export.csv
• PDF export: GET /api/plan-my-night/export.pdf

Plan States

• none: no plan currently stored.
• current: plan can be edited.
• previous: plan is locked for edits; targets can still be added to Astrodex; plan can be cleared.

Pinned Location

A plan is pinned to the user’s active location at creation time (location_id + a frozen location_name snapshot in the plan payload). Its altitude/timeline math is never silently recomputed against different coordinates:

• The plan view shows which location the plan was computed for.
• If the viewer’s current active location differs from the plan’s pinned location, a non-blocking warning banner appears (altitudes shown may not match what you’ll actually see).
• When an admin deletes a location preset, plans pinned to it are cascade-deleted by default (DELETE /api/locations/<id>?plans=cascade), or kept orphaned with the stale-location banner (?plans=orphan). See LOCATIONS.md.

Access Rules

• admin and user can create, edit, reorder, complete, and clear plans.
• read-only users can view the Astrodex tab but cannot access Plan My Night actions.
• Plans are stored per user, one per equipment combination (database tables plans and plan_entries, keyed by the combination id, or default for the plan with no combination selected). A user can hold a separate plan per combination at once.

Legacy Plan Purge

Plans are daily/ephemeral, so the pre-combination (telescope-keyed) plan schema is never migrated: on every app startup, any plan file whose plan dict still contains the old telescope_id key is deleted outright rather than converted.

API Summary

See API_ENDPOINTS.md for the full list.

Last updated 2026-11-13

Observation Log

The Observation Log (v1.3) is the Log step of the Plan -> Observe -> Log -> Astrodex loop: a private, chronological record of what actually happened on a given night, and what was actually captured.

It lives as the 5th sub-tab of the Astrodex main tab, next to Astrodex, Plan My Night, Photo Map and Catalogue Collection - so the whole loop stays under one navigational roof.

Table of Contents

1. Concept
2. Import from Plan
3. Multi-night sessions
4. Attachments
5. PDF export
6. The one-directional Astrodex relationship
7. Deletion and reference counting
8. Data model
9. Storage and write safety
10. API endpoints
11. Out of scope for v1.3
12. Related documentation

Concept

A session is a trip: location, equipment combination and free-text (trip-level) notes, plus one or more nights - each with its own actual start/end times and sky conditions (SQM, seeing, transparency, moon illumination) and its own notes. The common case is one night; a multi-night dark-sky trip is just a session with more than one. Within the session, an ordered list of entries (one per target) each records the real numbers - frame count, sub-exposure length, integration minutes, a 0-5 rating and per-target notes - and is attributed to whichever night it was captured on. An entry can also optionally override the session’s own equipment combination, for the common case of switching telescopes/cameras partway through a night - see Multi-night sessions.

Sessions are permanently private. There is no private_mode toggle and no cross-user merged view: this is a personal logbook, not a second Astrodex. (The storage mechanics are copied from astrodex.py; the sharing model deliberately is not.)

Access rules

• admin and user can create, edit and delete their own sessions and entries.
• read-only users can view the Observation Log but cannot mutate anything (the two list/detail routes are @login_required; every mutating route is @user_required).
• A session is only ever visible to its owner - there is no admin-wide view.

Import from Plan

POST /api/observation-sessions/from-plan, body {combination_id, session_id?}:

1. Loads the plan via plan_my_night.get_plan_with_timeline().
2. Both 'current' and 'previous' plans are importable. A plan flips to 'previous' the moment night_end passes - which is exactly when a user sits down to log what they captured. Importing is a read operation from the plan’s perspective; only 'none' (nothing to import) is refused with a 404.
3. No target session (session_id omitted): creates a new session, seeding its location and combination from the plan’s frozen fields, with one night built from the plan’s date and nautical-twilight window.
4. Existing target session (session_id given): finds-or-creates the night matching the plan’s date within that session (_find_or_create_night_for_date()) - reusing an existing night of the same date refreshes its start/end from the plan rather than creating a duplicate, so importing “day 2” of a multi-night trip’s plan just adds a second night to the ongoing session. A different date always appends a new night.
5. Every imported entry is attributed to that night. Re-import is idempotent at the entry level too: any plan entry whose id already appears as a source_plan_entry_id in the target session is skipped.

plan_my_night.py itself is unchanged - this is a new blueprint route only.

In the UI, Plan My Night gains a “Log this session” button rendered in its own row (gated only on the plan having entries, independent of state - unlike the CSV/PDF export block, which is 'current'-only). The Observation Log list has an equivalent “Import from Plan” entry point, shown only when at least one importable plan exists. When exactly one session created today already came from the same plan, the user is offered a merge into it instead of a second session for the same night.

Multi-night sessions

A session always has at least one night and can have more - a week at a dark site is one session, not one per night, so the trip stays grouped and its total integration is one number.

• Location is session-level (fixed for the whole trip), not per-night - a deliberate simplification: relocating mid-trip means starting a new session.
• Every entry records its own equipment (entry.combination_id), frozen from the session’s own default at add time and editable afterwards - the session-level combination_id stays the trip’s “usual” equipment, while an individual entry’s own field is what actually gets displayed and counted for that target, whether or not it was changed from the default.
• Everything that changes night to night lives on the night: date, actual start/end, SQM, seeing, transparency, moon illumination, and a per-night notes field (weather, mishaps specific to that night). The session’s own notes field stays trip-level (gear problems, overall impressions).
• Every entry is attributed to a night via night_id. The same target can appear on several different nights of the same trip as separate entries - nothing dedupes across nights, matching “log what actually happened,” not “log each object once.”
• Moon illumination is computed automatically, never typed in. Unlike seeing/transparency (a 7Timer forecast, only available same-day), it is a pure ephemeris calculation (astroweather/moon_planner.py’s moon_illumination_percent() - the same engine behind the 7-night Moon Planner forecast, for consistency app-wide), so it works for any date including the past - recomputed server-side whenever a night’s date changes.
• A night can be added, edited or deleted independently (POST/PUT/DELETE /api/observation-sessions/<id>/nights[/<night_id>]). Deleting a night is refused while it’s the session’s last remaining one, or while any entry still points at it - move or delete those entries first. This mirrors the app’s established delete-guard convention (blocked while referenced) rather than leaving a dangling night_id behind.
• Existing single-night sessions upgrade transparently. A session written before this existed has no nights field; load_user_sessions() synthesizes one nights[0] from its old scalar date/start_time/end_time/sqm/seeing/transparency fields (and stamps every entry with that night’s id) on read. This is lazy - nothing is rewritten to disk until the session is next saved for any reason - and idempotent, so there is no separate migration step to run.
• Importing a Plan My Night plan reuses a night of the same date within the target session rather than duplicating it - see Import from Plan.

Attachments

A session can hold generic files - guiding graphs, subframe logs, planning notes exported from another tool - separate from the entry -> Astrodex picture link above: an attachment never lives in Astrodex, and the actual keeper photo attached through .../astrodex-picture never lives here. Two independent upload paths into two different places, on purpose.

• Allowed types: jpg, jpeg, png, webp, pdf, txt, doc, docx - extension-only validation via secure_filename(), the same allow-list mechanism as Astrodex’s own image upload (just a different, wider set of extensions). No MIME sniffing, no size cap - matches Astrodex’s own upload route, which has neither either. Image attachments (jpg/jpeg/png/webp) are the exception: they must be real images (400 otherwise) and lose their EXIF/GPS metadata on upload, like Astrodex pictures - see Privacy & GDPR.
• Storage: data/observation_sessions/attachments/ (flat, mirroring data/astrodex/images/), filenames regenerated as {user_id}_{uuid4()}.{ext}, never the original name. The directory path is computed by observation_sessions.attachments_dir() - a function, not a module-level constant, so it re-reads OBSERVATION_SESSIONS_DIR on every call and stays correct for test fixtures (and any future runtime reconfiguration) that swap that directory out.
• Upload is one combined step (POST .../attachments, multipart), unlike Astrodex’s own upload-then-attach split - an attachment only ever belongs to the one session it’s uploaded to, so there’s no reason to separate “store the file” from “record it.”
• Download is ownership-checked, not just login-checked: GET /api/observation-sessions/ attachments/<filename> verifies the filename appears in one of the caller’s own sessions before serving it (sessions are never shared, so this is simpler than Astrodex’s own private/shared-mode check on can_user_view_image()). An unrecognized filename and someone else’s real file both get the same 403, so the response never confirms whether a given filename exists. The response’s Content-Disposition filename is display_name (with the real extension re-attached if the custom name omits it) or else original_name - never the on-disk {uuid}.{ext} storage name, which is what a browser would otherwise suggest since it’s the last path segment of the URL.
• Renaming (PUT /api/observation-sessions/<session_id>/attachments/<attachment_id>, {"name": "..."}) only ever writes display_name. It never touches filename or original_name, so the file on disk and its storage key are untouched - purely a cosmetic label plus the download filename above. An empty/blank name clears display_name back to null, reverting the UI to original_name.
• Deleting a session deletes its attachment files too - unlike the entry -> Astrodex link (a soft reference into a different feature’s data, deliberately left untouched on delete), an attachment file is owned entirely by its session, so delete_session() removes them from disk before removing the session record. A missing file on disk (already cleaned up by other means) doesn’t block the deletion - only logged.
• Covered by the admin backup ZIP: observation_sessions/attachments/ is one of the binary folders of utils/backup_archive.py, restored with the sessions themselves.

PDF export

Two routes, both built on the same page-rendering code (backend/observation/observation_sessions.py’s _render_session_section()), styled to match Plan My Night’s own PDF export (same header/footer bar, palette and A4 layout):

Per-session PDF - a button on the session detail view. First page: a common-information card, then the logged targets. The card’s shape depends on the session:

• Single night (still the overwhelmingly common case): unchanged from the original layout - date, location, equipment, start/end time, SQM, seeing, transparency, trip notes, plus a one-line summary (target count, average rating). Targets follow as a flat list.
• Multiple nights: a shorter card with only location, equipment, total integration (across every night) and night count, plus trip notes. Targets are grouped: each night that has at least one logged target gets its own compact sub-header (date, start/end, SQM, seeing, transparency, moon illumination, that night’s own notes) immediately before its targets; an entry whose night_id doesn’t resolve to any of the session’s nights falls back to a final “Other” group rather than being silently dropped. Long nights/target lists paginate onto further pages exactly like the single-night list always did, without repeating a night’s sub-header on the continuation page.

Every target row shows its attached Astrodex photo when it has one (a neutral “No photo” placeholder otherwise) alongside its identity, capture numbers (frames, sub-exposure, integration) and notes - this part is unchanged by the multi-night breakdown.

Global PDF - a button on the session list, shown only once at least one session exists (nothing to configure otherwise). It opens a modal asking for a date range - prefilled with the earliest and latest night dates across all of the user’s sessions, so the untouched default is “every session” - and a sort order (asc/oldest-first is the default, desc available). The resulting PDF is: a cover page (title, date range or “All sessions”, generation timestamp, and aggregate stats - sessions/targets/integration/average rating), a summary table (one row per session: date range for a multi-night session or a single date otherwise, location, equipment, target count, integration, rating), then every session in the range rendered exactly like the per-session export, in the requested order.

Both routes are @login_required (read action, no @user_required gate) and only ever operate on the caller’s own sessions. from_date/to_date match a session when any of its nights falls in range (inclusive, string comparison against YYYY-MM-DD) - a multi-night trip straddling a filter boundary still matches, and every one of its nights still renders regardless of which of them individually fell inside the window. An empty range means every session. lang (or Accept-Language) selects the PDF’s own translated labels, independently of the query’s paging.

An entry’s photo is resolved by the blueprint layer (_resolve_entry_image_path()), never by the storage module - observation/observation_sessions.py never imports astrodex (see its module docstring), so the PDF generators receive a pre-built {entry_id: absolute_file_path} map instead of resolving Astrodex links themselves. A picture whose file has since been deleted, or whose linked Astrodex item/picture no longer resolves, degrades to the “No photo” placeholder rather than failing the export.

The one-directional Astrodex relationship

This is the decision most likely to be re-litigated later, so it is stated explicitly.

A session entry is its own record. It is the source of truth for “what happened this session”, independent of whether the target was ever processed into a keeper image. It is not a view onto an Astrodex picture, and the two are never kept in sync.

Two distinct links exist, with deliberately different triggers:

1. Astrodex item registration is automatic

The moment an entry gets real capture evidence - frame_count > 0, or a picture attached - the matching Astrodex item is found-or-created silently in the background (same dedup rules as Plan My Night’s existing add-to-astrodex), and its id is stored on the entry as astrodex_item_id.

There is no button for this. “Catch them all” is a keypoint of the app, and a manual push button could simply be forgotten, silently defeating it. Auto-linking the item costs nothing (no picture required - it is purely a catalogue-membership fact).

It is never auto-reversed. Editing frame_count back down to 0 leaves astrodex_item_id in place. Once catalogued, always catalogued; removing an Astrodex item stays a deliberate, guarded user action and no automated process undoes it.

2. Attaching the actual picture stays manual

Processing and stacking genuinely happen days after the session, so the photo is attached separately via POST /api/observation-sessions/<id>/entries/<id>/astrodex-picture. (Astrodex picture location was made editable rather than frozen for exactly this reason.)

No picture ever lives in Observation Log storage. The only place an image file is uploaded is the existing, unchanged POST /api/astrodex/upload route, which writes straight into Astrodex’s own image directory; the attach route then calls add_picture_to_item() and stores the resulting astrodex_picture_id on the entry.

Both links are one-shot, never a sync

Editing the entry afterwards does not update the linked Astrodex item/picture, and vice versa - mirroring Plan My Night’s existing one-shot copy behavior. If the linked item or picture is later deleted through Astrodex’s own UI, the entry’s pointer simply stops resolving; nothing is repaired or cascaded, and no reverse delete-guard is added to astrodex.py.

The reverse link is display-only

The forward link (entry -> item/picture) is the only thing ever stored. Astrodex’s own item/picture detail views additionally show a read-only “Logged on <date>” backlink back to the session that produced them, computed on every GET /api/astrodex request via observation_sessions.build_astrodex_session_backlink_index() (a one-pass reverse scan of the caller’s own sessions, keyed by astrodex_item_id/astrodex_picture_id). This is purely a navigation convenience - nothing is written back to either side, and it never crosses users (sessions are private, so the scan only ever covers the requesting user’s own sessions, regardless of whether the item view itself is a merged multi-owner one).

Consequence for v1.5 Session Analytics

Aggregation (“total integration hours”, “objects captured”) should read from Observation Log sessions/entries as the primary source, not from Astrodex pictures. Astrodex’s frames / exposition_time / integration_minutes (v1.3+: validated numeric fields, mirroring this module’s own trio - see docs/ASTRODEX.md) are a per-photo record and may not cover every entry (attaching a picture is a manual, optional step), whereas an entry’s own frame_count / sub_exposure_seconds / integration_minutes are set for every logged target. Pre-v1.3 pictures may also still carry a legacy free-text exposition_time value that predates the numeric field. Cross-reference Astrodex only for gallery/photo display.

Deletion and reference counting

The location choice is deliberate: a session, like an Astrodex picture, is a historical record - its frozen location_name snapshot stays valid as display-only history. That is different from a Plan My Night plan, which is an active object that needs a live location to keep computing altitude data against, and is therefore cascade-deleted.

The reference scans (count_sessions_for_combination, count_sessions_for_location) are fail-open: an unreadable file is skipped rather than aborting the scan, matching count_pictures_for_combination / count_plans_for_combination.

count_sessions_for_combination counts a session once whether the match is its own session-level combination_id, any entry’s own per-target combination_id override, or both - a single session can reference more than one combination across its different targets. An entry’s separate combination_used_components field is unrelated: it’s a checklist of which parts of whichever combination is effective for that entry (its own override, or the session’s) were actually used.

Data model

Session object

A session’s “date” for sorting, filtering and display purposes is always derived, never stored: the earliest night’s date (session_date_range(session)[0]) for a single value, or the full [earliest, latest] range where a range makes sense (list card, PDF summary table).

Night object

Entry object (one per target)

Only the “what actually happened” fields (night_id, frame_count, sub_exposure_seconds, integration_minutes, rating, notes, combination_id, combination_name, combination_used_components) are writable through the update route - night_id is reassignable both when adding an entry and afterwards (unlike the frozen identity fields), so a target logged under the wrong night can be moved. The target identity snapshot is frozen, and the two astrodex_* pointers are set through link_entry_to_astrodex() rather than by a client payload.

Attachment object

Attachments are session-level, not per-night or per-entry - a guiding graph or a subframe log belongs to the whole night’s session, not one specific target. See Attachments.

Storage and write safety

Mechanically identical to backend/observation/astrodex.py:

• Database tables observation_sessions, observation_nights, observation_entries and observation_attachments, one row per object (observation_sessions/<user_id>_sessions.json inside a backup ZIP).
• Attachment files: data/observation_sessions/attachments/ (flat, mirroring data/astrodex/images/)
  • see Attachments.
• Document shape: {user_id, username, created_at, updated_at, sessions: [...]}.
• load_user_sessions() never raises to the caller: an unreadable or malformed stored value yields an empty payload (replaced on the next save).
• save_user_sessions() stamps updated_at, runs validate_sessions_data() (root is a dict, has username, has a list sessions; each session has id and a non-empty nights list, each night has id and date; any entry’s night_id, if set, must resolve within that session’s own nights) and writes the user’s rows in one transaction - nothing is stored when validation fails.
• The observation log and its attachments are included in the admin backup ZIP (GET /api/backup/download) and restored by POST /api/backup/restore.

backend/observation/observation_sessions.py never imports astrodex or plan_my_night at module scope - resolving an entry to an Astrodex item is the blueprint layer’s job.

API endpoints

All routes are self-scoped to the caller. Mutating routes return {"status": "success", "data": ...} on success and {"error": "..."} with the matching HTTP status on failure.

GET /api/observation-sessions also returns a deliberately minimal stats block - {total_sessions, total_entries, total_integration_minutes, average_rating} (average_rating is None until at least one entry has been rated). Full analytics is v1.5 Session Analytics’ job, not this feature’s.

Out of scope for v1.3

• Per-filter sub-exposure breakdown (Ha 20×300s + OIII 15×300s within one entry). v1 keeps one aggregate frame_count / integration_minutes per entry.
• Session sharing / multi-user visibility. Sessions are always private; there is no private_mode toggle and no merged view.
• Full analytics (integration hours over time, equipment usage breakdowns, sky-coverage maps) - shipped in v1.5 Session Analytics, built on this module; see SESSION_ANALYTICS.md.

Related documentation

• SESSION_ANALYTICS.md - the v1.5 aggregations built on this log
• PLAN_MY_NIGHT.md - the plan this log imports from
• EQUIPMENT.md - combination deletion guards
• LOCATIONS.md - preset deletion workflow
• API_ENDPOINTS.md - full endpoint inventory

Last updated 2026-11-13

Astrodex

Astrodex is your personal astrophotography logbook - a Pokédex-style catalogue of every deep-sky object you have imaged.

Where to find it

Astrodex tab -> Astrodex sub-tab

Concepts

Items and pictures

Each item represents one target object (a galaxy, nebula, cluster…). An item can have multiple pictures attached - one per session or per processing attempt.

Items are per-user: each account has its own private collection (database tables astrodex_items and astrodex_pictures, one row per item and per picture). Items from different users sharing the same target are merged into a combined view when browsing.

Catalogue integration

When you add an item by name, Astrodex looks up the name in the SkyTonight catalogue alias table (observation/catalogue_aliases.py) to find the canonical identifier. This allows adding “M31”, “Andromeda Galaxy”, “NGC 224”, or “Andromeda” - and they all resolve to the same record, preventing duplicates.

The check duplicate endpoint (GET /api/astrodex/check/<name>) lets the UI warn before adding a name that already exists.

For names the local SkyTonight dataset doesn’t know (mostly stars, e.g. “Vega”, “HIP 91262”), GET /api/astrodex/catalogue-lookup falls back to a SIMBAD TAP query (CDS first, then its CfA Harvard and IDIA mirrors - object_info.SIMBAD_TAP_ENDPOINTS - each backed off for a few minutes after a failure). The resolved name prefers SIMBAD’s NAME ... proper name when the object has one (surfaced as CommonName, e.g. “Vega” rather than the obscure Flamsteed designation “* 3 Lyr”), then a Bayer-style designation (“* alf Lyr”) over a bare Flamsteed number, then catalogue numbers (HD/HIP/SAO/TYC). The full set of resolved alternate names is captured client-side and submitted as external_aliases when the item is created, so the item detail popup’s “Catalogue names” section - otherwise sourced live from the DSO dataset via catalogue_aliases and empty for any star - has something to show (see enrich_item_with_catalogue_aliases()).

Features

Browsing

The Astrodex grid shows all your objects with cover picture thumbnails. Items without pictures use a default placeholder image. Sort by name, type, date added or photo count, ascending or descending. Name and type sorts are numeric-aware, so catalogue identifiers order the way they read (M 3 before M 31 before M 100, not as plain strings).

Constellation filter: Objects are grouped by constellation, from the IAU list of the constellation-enum package (observation/astrodex.get_constellations_list()); abbreviations are expanded to full names by utils/constellation_names.py. You can filter to show only objects in a specific constellation.

Type filter: Filter by object type (Galaxy, Nebula, Cluster…).

Adding objects

Two ways to add an object:

1. From SkyTonight: Every target in the SkyTonight report tables has an “Add to Astrodex” button. The name, catalogue, and type are pre-filled.
2. From Plan My Night: A “Add to Astrodex” button is available for each target in the plan.
3. Manually: Use the “+” button in the Astrodex tab to add any object by name.

Editing objects

The object editor allows updating:

• Name and catalogue reference
• Object type and constellation
• Notes

Managing pictures

• Upload pictures with drag-and-drop or file picker.
• On upload, EXIF/XMP/IPTC metadata (GPS position, camera serial numbers…) is stripped without re-encoding the pixels; the file must be a real JPEG, PNG, WebP or GIF, otherwise the upload is rejected with 400. See Privacy & GDPR.
• Reorder pictures; set one as the main (cover) picture.
• Delete individual pictures.
• Images larger than the display size are served at original resolution for download.
• Rate your own photos 0-5 stars (half-star steps) - lets you see which equipment combination produces your best results (average rating shown on the combination’s card in the Equipment tab).
• Add/edit picture modal is organized into four sections: File, Date & Location, Equipment, and Photo information.

Re-processing with MyAstroShine

When the MyAstroShine integration is configured and enabled, each of your own photos gets a Send to MyAstroShine action. It opens MyAstroShine in a new tab with an edit session pre-loaded from the photo and its metadata; when you send the result back, a new picture is added to the same object (never a replacement), carrying the source photo’s metadata snapshot plus the immutable enhanced_* provenance fields. The Edit Photo modal of an enhanced picture shows a discreet “Re-processed with MyAstroShine” note with a view settings disclosure.

Catalogue lookup

GET /api/astrodex/catalogue-lookup?name=<name> queries the SkyTonight target catalogue for coordinates, type, magnitude, and angular size for a given object name. This auto-fills metadata when adding a new item.

Constellation list

GET /api/astrodex/constellations returns all constellations represented in the current user’s collection, useful for building the constellation filter dropdown.

Photo Map

Astrodex tab -> Photo Map sub-tab

Shows every geotagged picture (one with latitude/longitude set via a location preset or manually-typed custom coordinates in the Add/Edit Picture modal) on a world map, with marker clustering: bubbles show a photo count and separate into individual pins as you zoom the map in, mirroring the Apple/Google Photos map view. Clicking a bubble opens the existing photo slideshow directly for every photo in that cluster; clicking a single pin opens the slideshow for that one photo.

This does not perform any EXIF GPS extraction - it only visualizes coordinates a user already entered manually. It is powered by a dedicated, lightweight endpoint:

GET /api/astrodex/map returns a flat list of geotagged pictures across all visible users, gated by its own config['astrodex']['map_private'] flag (Configuration -> Astrodex -> “Photo map private”; on by default for new installs, off for installs whose configuration predates the setting) - deliberately independent from the general config['astrodex']['private'] sharing flag used by /api/astrodex. When map_private is off, every shared user’s pictures appear on the map with their real coordinates, even though /api/astrodex itself always strips other users’ exact coordinates for privacy in its own merged view. This app targets small trusted deployments (family/astro-club), so the map keeps its own, separately-labeled switch rather than being tied to the general sharing toggle; since real-world photo locations are often the observer’s home, new installs start with it private.

Catalogue Collection

Astrodex tab -> Catalogue Collection sub-tab

The Pokédex view. Pick a catalogue and see every object in it as a small card, whether you have imaged it or not - captured objects in full colour with your own cover photo, everything else greyed out with a sky-survey preview. Cards are display-only: nothing here adds, edits or deletes anything, it only reflects state already owned by the Astrodex and the SkyTonight catalogue.

What you can browse

Every deep-sky catalogue of the SkyTonight dataset, plus a Solar System pseudo-catalogue:

Comets are deliberately absent: they are transient visitors, not a fixed set to complete.

The picker shows a captured count per catalogue (Messier (12/109)), and a progress bar sits above the grid. An object present in several catalogues - M 31 is also NGC 224 - counts as captured in each of them.

Each card shows its catalogue identifier, name, type, constellation, difficulty badge and magnitude.

Card images

DSS2 previews reuse the existing GET /api/object-image/<filename> proxy, which fetches from CDS hips2fits once (or, when CDS is down, renders it from a mirror of the DSS2 HiPS - see SKYTONIGHT.md) and caches the JPEG in data/cache/object_images/ (trimmed to 200 MiB, oldest first; a trimmed image is fetched again when next asked for). Thumbnails load through an IntersectionObserver as their card nears the viewport, so browsing a 13 000-object catalogue never fires more cold CDS fetches than the objects actually looked at.

Captured detection

An object counts as captured when one of its catalogue identifiers or aliases matches an Astrodex item of the current user. Matching runs through the same _extract_name_candidates() extractor is_item_in_astrodex() uses, so an item saved as "M31 - Andromeda Galaxy" is recognised, and the collection always agrees with the “in Astrodex” badges shown elsewhere in the app.

Filtering, sorting, paging

All three happen server-side (backend/observation/catalogue_collection.py) - the NGC catalogue is far too large to hand to the browser at once. Pages hold 60 cards by default, 120 at most.

• Filters: free-text search (identifier and name), captured / not captured, difficulty, object type, constellation.
• Sorts: catalogue identifier (default, ordered naturally so M 9 precedes M 10), name, captured, difficulty, magnitude, constellation, type - each reversible.
• Objects with no value for the sorted field (no published magnitude, no difficulty) stay grouped at the end in both directions, rather than jumping to the top when the order flips.
• The type and constellation dropdowns are built over the whole catalogue, not the current page, so they do not shrink as you filter or page. They are re-sorted client-side on the translated label, so the list reads alphabetically in the user’s own language.

Difficulty

Cards carry the same beginner / intermediate / advanced badge SkyTonight and the Astrodex grid use, via the shared createDifficultyBadgeNode().

The label comes from skytonight_calculator.compute_difficulty_score(), called directly on the catalogue record. That scorer derives the label from magnitude and apparent size alone and is explicitly independent of location and sky quality, so it can be computed for the whole catalogue rather than only for the targets a given night’s run happened to evaluate - unlike GET /api/astrodex, which cross-references dso_results.json and therefore leaves items unrated when they were not observable. Solar-system bodies have neither magnitude nor size on record, so they get no badge instead of the scorer’s neutral “intermediate” default, which would be a guess.

The difficulty/difficulty_score fields stored in targets.json are not used here: the offline dataset builder writes a placeholder (0 / intermediate) for every object.

Naming and translation

• Constellations are stored in the dataset as IAU abbreviations (And, plus PyOngc’s Se1/Se2 for the two halves of Serpens). The endpoint expands them to full names (Andromeda, Serpens Caput) so the frontend’s existing constellations.* keys resolve; all 91 names in the dataset have a translation.
• Object types go through skytonight.type_*, as everywhere else.
• Object names are catalogue proper nouns and are shown as-is - SkyTonight does not translate them either. The one exception is the Solar System group, whose members have real translations and so go through the shared planets.* dictionary (Moon -> Lune). planets.sun was added for this view; the namespace previously only covered planets, since its only other consumer is the events aggregator.

Shared items

When multiple users on the same instance image the same object, items are merged in the Astrodex view:

• Each user’s pictures are listed under their own section.
• The owner_username field shows who added which picture.
• Users can only edit or delete their own items and pictures.
• The is_owned_by_current_user flag drives UI permissions.

Item data model

Each item of a user’s Astrodex has the following fields:

Additionally, catalogue_aliases is attached to every item at read time only (never persisted) - either from the live SkyTonight DSO catalogue lookup, or, when that finds nothing, from the item’s own external_aliases. It powers the item popup’s “Catalogue names” section and the “use this name” switch action.

Picture data model

Each picture attached to an item:

The five enhanced_* fields are immutable - set once when the duplicate is created and absent from update_picture()’s allowed fields.

Images are stored in data/astrodex/images/ and served by GET /api/astrodex/images/<filename>.

Equipment on a picture

The Add/Edit Picture modal’s Equipment section is a single select: your enabled combinations (own + shared) plus an “Other equipment” option.

• Picking a combination saves combination_id and reveals a checklist of that combination’s actual components (telescope / camera / guide camera / each filter) so you can mark which ones were used for this specific photo - purely optional, stored as combination_used_components.
• Picking “Other equipment” falls back to free-text device/filters fields (with autocomplete drawn from your equipment names and previously-typed values).
• If a picture’s linked combination is later disabled, it still appears in that picture’s edit dropdown (and stays selected) - the same “stays visible if already selected” rule the Equipment tab itself uses.
• A combination can’t be deleted while any picture (yours or another user’s) still references it.

Storage and backup

• Per-user collection: database tables astrodex_items and astrodex_pictures (one row per item and per picture; astrodex/<user_id>_astrodex.json inside a backup ZIP)
• Images directory: data/astrodex/images/
• Both are included in the Backup / Restore ZIP (see CONFIGURATION.md).

Write safety

save_user_astrodex() uses an atomic write pattern:

1. Write to a temporary file (.json.tmp)
2. Validate the temporary file’s JSON
3. os.replace() - atomic rename on POSIX filesystems
4. Delete the backup on success; restore it on failure

Per-user write locks (threading.Lock per user_id) prevent concurrent save race conditions across Gunicorn workers.

API endpoints

Last updated 2026-11-13

Session Analytics and Wishlist

Session Analytics (v1.5) answers two questions from data MyAstroBoard already stores: “how am I progressing?” and “how am I optimizing?”. The Wishlist that ships with it answers a third: “what do I still want to capture?”

They live as two sub-tabs of the Astrodex main tab, alongside Astrodex, Plan My Night, the Observation Log, Photo Map and Catalogue Collection - so the whole Plan -> Observe -> Log -> Astrodex loop and everything derived from it stays under one navigational roof.

Table of Contents

1. The four analytics sections
2. Wishlist
3. What “best months” does and does not say
4. What is computed, and from what
5. Why the Observation Log is the primary source
6. Resolving coordinates
7. Scale directions
8. Performance and caching
9. API endpoints
10. Out of scope
11. Related documentation

The four analytics sections

1. Headline totals

Integration lifetime / this year / this month, sessions and nights, distinct objects captured, constellations, average rating, and the Astrodex collection size.

“This month” is the observer’s month: the date is resolved in the active location’s timezone, not the server’s, so a session logged at 01:30 local on the 1st lands where the user expects it.

2. Where your time goes

Integration over time (a dense monthly series - a month with no activity renders as a zero bar rather than closing up the axis), object types, constellation spread, and equipment usage.

1b. How the headline figures are rendered

Through the shared .stat-plate component (DOMUtils.buildStatPlate()), not a grid of cards - see the Headline Figures Standard in .github/instructions/copilot.instructions.md. The Astrodex and Observation Log tabs render theirs the same way.

A zero duration still carries its unit: at the hero’s size, a bare “0” under “Light collected” is the first thing a new user reads, and it does not say zero of what.

2b. Colours under the red night-vision theme

Both palettes go through _saPalette() / _saQualityPalette(), which return a single-hue red ramp when html[data-theme="red"] is in force - the categories are then separated by lightness rather than by hue. A blue or green dot is exactly the light that theme exists to keep out of a dark-adapted eye, and this page puts a large chart in front of one.

3. Sky coverage

Every captured object placed on an RA/Dec grid: right ascension on the x axis, reversed as on any sky chart, declination on the y axis. Colour by object type or by capture year.

It is drawn as a sky chart rather than as a scatter plot, so the dots have something to sit against:

• the Milky Way is filled behind the data, from the galactic equator transformed into equatorial coordinates (J2000 pole at RA 192.85948 deg, Dec 27.12825 deg). Several faint layers at widening galactic latitudes are filled over one another, so the glow falls off instead of stepping;
• the ecliptic is drawn dashed - the path the Sun, Moon and planets follow;
• the celestial equator is marked at Dec 0;
• a dot grows with the integration time behind its object, on a square root so one very long project does not flatten everything else;
• the top axis reads the same right ascension as a month: an object culminates near local midnight when the Sun sits half a sky away from it. The reading is anchored on the equinoxes and solstices rather than on one straight line through the year, which would name the wrong month for an object near a boundary.

A shaded band marks the declinations that never rise at the active location (dec < -(90 - lat) in the northern hemisphere, mirrored in the southern), so “where have I been” is read against where the observer can actually go.

Objects whose coordinates cannot be resolved at all are counted and named, not silently dropped - the same honest accounting the Photo Map does with its ungeotagged pictures.

Everything painted on the canvas takes its colour from custom properties declared in static/css/bs_session_analytics.css (--sky-chart-*), read back with getComputedStyle at draw time: a canvas cannot carry a class, and the red night-vision theme redefines all of them. The plot area stays dark under the light theme on purpose - a sky chart reads as a window onto the sky, and inverting it would only make the objects harder to place.

4. Conditions and results

Every rated entry joined to its night’s seeing, transparency, SQM and Moon illumination, plotted as four scatters with bucket averages underneath.

This is descriptive, not predictive. Each bucket reports its own sample count next to its average, and a bucket with fewer than five samples is shown as “not enough data yet” rather than plotted. There is no trend line and no correlation coefficient: over a handful of nights, one would be noise dressed as insight.

Wishlist

A wishlist item records intent: an object you want to capture. It is the only new persistent state v1.5 introduces - everything else is derived.

Storage is the wishlist_items database table (one row per item), validated before every write like the Observation Log. Wishlists are permanently private, and they are included in the admin backup ZIP.

Two rules

1. “Captured” is never stored. It is recomputed on every read from the Observation Log entries and the Astrodex items. A stored boolean would go stale the moment an entry is edited or a session deleted, and silently-wrong progress is worse than no progress bar.
2. Coordinates are resolved and frozen at add time, through the resolver (see Resolving coordinates).

Behaviour

• Deduplication is cross-catalogue: adding “NGC 224” when “M 31” is already on the list is reported as a duplicate, not added twice. Aliases count too.
• Captured items stay on the list and are shown as done, so “12 of 20” keeps its denominator. POST /api/wishlist/archive-captured is the explicit opt-in for removing them.
• Moving targets (planets, comets) are accepted as wishes but never get a frozen position: a fixed RA/Dec would be wrong within weeks, so they simply report no window, the same distinction the v1.4 visibility calendar draws.
• Priorities are high / normal / low; the list can also be sorted by visibility (the default) or name.
• Cap: MAX_WISHLIST_ITEMS = 500 per user.

Where objects are added from

All three payloads carry an in_wishlist flag, computed from a preloaded index so annotating a thousand SkyTonight rows stays one file read.

The SkyTonight result tables themselves are built as HTML strings - the legacy path the project style guide says not to extend - which is why the table’s entry point is its per-row More popup rather than a new column.

Next visibility

GET /api/wishlist attaches, per item, the observable hours on the nearest sampled night and the best of the next three sampled months. That is the cheap ranking signal the default sort uses; the precise twelve-month answer stays one click away behind the v1.4 per-object visibility calendar, which every placed item links to.

?visibility=0 skips the ephemeris pass entirely for a fast render.

What “best months” does and does not say

The chart plots two clearly separate series:

• Available - mean dark hours and moonless dark hours per night for that calendar month at the active location, computed live from the Sun and Moon. This is the site’s own nightly budget.
• Logged - the month total the user actually recorded, across all years, plus the nights logged and mean rating.

The two are different units - a nightly average against a cumulative total - so they get separate y axes, each labelled. On one shared axis a well-used month climbs above the available darkness and reads as an impossibility.

It is not a weather statistic. MyAstroBoard stores no historical weather: every weather cache is a short-TTL forecast snapshot that is overwritten in place, and nothing accumulates a climatology. The chart therefore answers “when is it worth planning to be out here, and when have I actually been out” - never “when is it clear here”.

A weather climatology (multi-year cloud cover from an archive API, behind its own scheduler cache job) was specified and deliberately deferred; see feature.md for the full design if it is ever picked up.

If the ephemeris cannot be computed for a location, the personal half still renders and the chart says the sky figures are missing, rather than showing a half-empty chart that looks complete.

What is computed, and from what

Everything is strictly self-scoped: a user only ever sees aggregates of their own log and their own Astrodex. Observation Log sessions are permanently private, so the analytics built on them are too. Read-only accounts may read every analytics route; only the wishlist’s write routes require the user role.

All the aggregation is pure: backend/observation/session_analytics.py takes already-loaded sessions and returns a payload. Loading files, resolving the request’s active location and reaching across feature packages is the blueprint layer’s job (backend/blueprints/session_analytics.py), the same split the Observation Log uses.

Why the Observation Log is the primary source

Attaching a photo to an entry is a manual, optional step, so Astrodex picture metadata covers an unknown subset of what was actually captured. Every logged entry, by contrast, carries its own frame_count / sub_exposure_seconds / integration_minutes.

So: every “hours” and “objects captured” figure comes from the Observation Log. The Astrodex collection size is reported as its own, separately-labelled figure - never folded into the logged totals - and Astrodex items are used on the sky coverage map only to cover objects that were added straight to the gallery without a session entry.

This was decided when v1.3 shipped; see docs/OBSERVATION_LOG.md.

Which figures come from where

• integration_minutes is the one guaranteed-summable field. When it is absent but both frame_count and sub_exposure_seconds were recorded, their product is used instead.
• An entry counts as captured when it has frames or integration time - the same threshold the Observation Log itself uses to auto-register a target in Astrodex. A planned-but-clouded-out entry is logged but is not a capture.
• Entries are attributed to their night’s date, never to created_at: a session written up three weeks later still lands in the month it happened.
• Distinct objects are counted on the dataset’s cross-catalogue catalogue_group_id when it resolves, so “M 31” and “NGC 224” are one object, not two.
• Equipment hours follow the effective combination of each entry: its own override if it has one, else the session’s. Both are frozen snapshots on the records themselves, so renaming or deleting a combination never rewrites history. Entries with no equipment recorded get an explicit bucket rather than being dropped, so the hours always add up to the headline total.

Resolving coordinates

The sky coverage map and the wishlist both need numeric RA/Dec, and neither can take the stored ra/dec at face value. Plan My Night and the Observation Log copy those fields straight from whatever the client sent, and the two SkyTonight frontend paths disagree: the target cards send coordinates.ra_hours (a decimal-hours float) while the result tables send the formatted ra_hms string ("21h 31m 48.32s"). Astrodex items are worse - ra/dec are stripped on every write.

backend/observation/target_coordinates.py is the single resolver, applying one order everywhere (first hit wins):

1. The SkyTonight dataset lookup, which carries canonical numeric ra_deg/dec_deg plus the object’s cross-catalogue group_id. Display labels such as "M31 - Andromeda Galaxy" are reduced to their identifier before the lookup.
2. The record’s own stored values, parsed tolerantly: a number (RA in decimal hours, Dec in degrees) or a sexagesimal string in h m s, d m s, deg ' " or colon form. A negative-zero degrees field (-00 30 00) keeps its sign.
3. Give up - and the caller counts the miss.

The wishlist stamps the resolved values onto the item at add time, so the visibility pass is a pure numeric loop that never re-learns this.

Scale directions

Three of the recorded conditions run in different directions. Every bucket the API emits is ordered best first and carries its own numeric bounds, so no consumer has to re-derive which way a scale goes:

A reversed seeing axis is a correctness bug, not a cosmetic one, and has its own test.

Performance and caching

No scheduler cache job is registered. The analytics are per-user aggregations over that user’s own JSON files - a few milliseconds of dict work even for a heavy log.

The only expensive part is the ephemeris, and it is cached the way v1.4 already caches this class of work, with bounded in-process LRUs:

That is also why the wishlist’s visibility pass scales: the grid is built once per sampled night and every target is folded through it at O(1) trig per time step, so a 500-item wishlist costs the same few grids as a single object would.

API endpoints

All routes require login and are self-scoped. Write routes additionally require the user role.

The four analytics routes are fetched in parallel when the sub-tab opens, so the ephemeris-backed one never holds up the three that are instant.

Out of scope

• Weather climatology - see above.
• Per-filter breakdown of integration time. The Observation Log keeps one aggregate integration_minutes per entry (already out of scope in v1.3).
• Cross-user or club leaderboards. Sessions are private; analytics stay self-scoped. Public profiles are a v2.1 concern.
• A true all-sky projection for the coverage map. v1.5 ships the rectangular RA/Dec grid with the Milky Way and the ecliptic drawn on it; the projected, imagery-backed view arrives with the v2.0 sky chart rather than being built twice.
• Named stars and constellation figures on the coverage map. The landmarks it carries are computed, not catalogued - drawing real stars means shipping a star catalogue to the browser, which belongs with the v2.0 sky chart.
• Guiding-quality trends per equipment combination - that needs the v2.2 PHD2 import.
• PDF export of the dashboard.

Related documentation

• OBSERVATION_LOG.md - the log every figure here is derived from
• ASTRODEX.md - the gallery, counted separately
• SKYTONIGHT.md - the dataset that resolves coordinates and identities
• LOCATIONS.md - the active location that drives visibility and best months

Last updated 2026-11-13

Share Cards

A share card is a ready-to-post image made from data MyAstroBoard already holds: a picture with its acquisition details, a logged session, tonight’s sky, an upcoming event. It answers the question every posted astrophoto gets - “what gear, how many subs?” - without retyping anything.

Where to find them

The share button (a share icon) opens the card:

The framing simulator has its own export, see SKYTONIGHT.md.

Options

• Format: the shapes the main image networks show without cropping. 4:5 is the default.

  Format	Size	Fits
  4:5	1080 x 1350	Portrait feed post: Instagram, Facebook, Threads
  1:1	1080 x 1080	Square, accepted everywhere
  16:9	1920 x 1080	Landscape: X, Facebook, forums. Picture and text sit side by side
  9:16	1080 x 1920	Full screen: stories and reels. Not a feed format: a feed crops it

• Theme: dark or light. The card has its own palette and looks the same whatever the application theme, the red night-vision theme included.

• Show on the card: every fact can be unchecked before export. A fact with no value is not offered at all - a card never shows an empty or invented figure.

• MyAstroBoard signature: a footer with the project name and address, on by default.

• Download saves a PNG. Share appears when the browser can hand a file to the system share sheet (mostly phones) and opens it with the image.

A picture is never cropped: it is drawn whole, and the text block takes the room it needs beside or below it. Where the picture does not fill its area (a tall photo in a wide card), the bands show a blurred, darkened copy of the picture on browsers whose canvas supports filters, plain black otherwise.

Privacy

• The card is drawn on a canvas in the browser. Nothing is uploaded; it leaves the device only when the user downloads or shares it.
• A card never contains a location: no coordinates, no location name, no map. The card model has no field for them, and the Astrodex and Observation Log callers do not pass the ones they hold. Sky quality (SQM) and Moon illumination are the only conditions shown.
• Pictures were already stripped of their EXIF metadata when they were uploaded, and the exported PNG is a new image with no metadata of its own.

Implementation

static/js/share_card.js holds the engine and the four card builders:

• openShareCard(model) - the modal: preview, options, download and share. A model is a plain object: kicker, heading, subheading, an optional same-origin imageUrl, an optional hero figure, facts (each with an id so it can be unchecked), an optional list and paragraph.
• drawShareCard(canvas, model, options, image) - the drawing. The text block is planned first (fonts shrink to fit, long lines are clamped), then the picture gets the remaining height.
• shareAstrodexPicture, shareObservationSession, shareTonight, shareEvent - build a model from the data their caller already has. shareTonight fetches what the dashboard shows (/api/sky-widget, /api/moon/report, /api/tonight/best-window, /api/skytonight/recommendations); a part that is unavailable is left out.
• createShareButton(onClick) - the icon button used at each entry point.

There is no backend part and no new route. Adding a card is one builder function and one button.

Last updated 2026-11-10

Equipment Profiles

The Equipment tab lets you catalogue all your astronomy gear. Profiles pre-fill fields across Astrodex, the Exposure Calculator, and the SkyTonight target scorer.

Module: backend/equipment/equipment_profiles.py

Gear types

Data is stored in the database: equipment_items (one row per telescope, camera, mount, filter or accessory), equipment_combinations and combination_equipment (the filters and accessories of each combination); equipments/<user_id>_<type>.json inside a backup ZIP.

Equipment combinations

A combination is a named configuration that groups a telescope, camera, mount, filters, and accessories. It is the unit used by:

• The FOV Calculator (computes field of view for that telescope + camera pair)
• SkyTonight (“Best Equipment For This Target” rates all your enabled and valid combinations)
• Astrodex picture metadata (which setup was used for an image session)
• Plan My Night combination selector (see PLAN_MY_NIGHT.md)

At least one of telescope or camera is required; both are single-value fields (max one telescope, max one imaging camera per combination). Two additional fields cover setups the base telescope+camera model doesn’t:

A combination is flagged Shared only when every component in it is individually shared. If one component is later made private, the combination shows a ⚠ warning.

Photo badges

Each combination card carries two badges sourced from Astrodex:

• Photo count - number of Astrodex pictures linking to this combination. Click it to open the same slideshow used elsewhere in Astrodex, showing every one of those pictures.
• Average rating - mean of the 0-5 star ratings across those pictures (unrated pictures don’t count toward the average, though they do count toward the photo count).

Both respect the same visibility as the rest of Astrodex: with config['astrodex']['private'] off (default), they aggregate every visible user’s pictures for that combination; with it on, only your own.

Deletion

A combination can’t be deleted while it’s still referenced by any Astrodex picture (any user), pinned to any Plan My Night plan (any user), or referenced by any Observation Log session (any user) - the delete-guard mirrors the one on individual equipment items. This is checked in addition to the component-level guard: deleting the equipment inside a combination is blocked separately (see Disabling equipment) while deleting the combination itself is blocked by its pictures, plans or sessions (see OBSERVATION_LOG.md).

Field of View calculator

Sub-tab: Equipment -> FOV

Endpoint: POST /api/equipment/fov-calculator

Formulas

Image scale (arcsec/pixel)

The constant 206 265 arcsec ≈ 1 radian.

Field of view (degrees)

The constant 57.3° ≈ 1 radian (small-angle approximation valid for typical FOV values).

Sampling classification (Nyquist criterion)

The optimal sampling range is 2-3 pixels per FWHM of the seeing disk:

Default seeing used for the classification: 2.0 arcsec (typical suburban sky). You can override this in the calculator UI.

Equipment sharing

Any telescope, camera, mount, filter, or accessory can be marked “Share with all users” in its edit form. Shared items are immediately visible to every user on the instance:

• Shared items appear under a “Shared by Others” section labelled with the owner’s name.
• Non-owners can read but not edit or delete.
• Your own shared items show a Shared badge.

Shared equipment flows through the whole app:

Disabling equipment

Every gear type (Telescope, Camera, Mount, Filter, Accessory) and every Combination has an is_disabled flag, set from its own edit form.

• Deletion is blocked while an item is still referenced by a combination (your own, or another user’s if the item is shared) - the delete request returns the combination name(s) so you know what to unlink first. Disabling is the alternative when you don’t want to fully delete something that’s still tied to a combination.
• Disabled items are excluded from every combination editor’s dropdowns/checkboxes, unless they are already selected on the combination currently being edited - an existing combination never silently loses a component from the editor UI just because that component got disabled later.
• Disabled items are hidden from their list tab by default. A “Show hidden (N)” toggle at the top of each tab (Telescopes, Cameras, Mounts, Filters, Accessories, Combinations) reveals them, tagged with a “Hidden” badge.
• A combination that references a disabled (or no longer resolvable) piece of equipment is automatically flagged invalid - a computed status, independent of the combination’s own is_disabled toggle - and shown with a warning badge in the Equipment tab. Invalid/disabled combinations are not hidden or blocked from further use here; other features (SkyTonight, Plan My Night, Astrodex) are expected to start filtering on this status as each becomes combination-aware.

SkyTonight integration

For each DSO, POST /api/skytonight/combination-recommendations rates every enabled and valid equipment combination (own + shared) on a 1-5 scale:

1. Resolves each combination’s effective optics - a telescope’s aperture/focal length/f-ratio, or for a camera-only combination (no telescope), its lens_focal_length_mm/lens_focal_ratio.
2. Scores focal length against an ideal range derived from the target’s apparent size/type, and aperture against the target’s magnitude.
3. When the combination’s camera has sensor dimensions, blends in a real field-of-view match (via the FOV Calculator’s formulas) against the target’s apparent size, instead of relying on the focal-length heuristic alone.

Disabled or invalid combinations (see Disabling equipment) never appear in recommendations. See SKYTONIGHT.md for the full scoring model.

Presets

File: static/data/equipment_presets.json (static asset, no backend involvement - fetched directly by the frontend)

A curated list of real-world gear (telescopes, cameras, mounts, filters, accessories) that lets users skip manual data entry for common models. Each entry has an id, a label, a manufacturer, a source_url for provenance, a suggests_experience (beginner / intermediate / advanced) used to sort the closest match to the user’s own experience level to the top, and type-specific spec fields matching the corresponding gear type table above one-to-one (e.g. a telescope preset’s type maps to telescope_type, a filter preset’s filter_type must be one of the enum values listed under Filters, etc.).

Consumed in two places:

• The guided setup wizard’s equipment step (static/js/first_run.js) - offered alongside a manual-entry option.
• The Equipment tab’s “New Telescope / Camera / Mount / Filter / Accessory” modals (static/js/equipment.js) - a “Start from a preset” dropdown prefills the form, which remains fully editable afterward. Only shown when adding a new item, not when editing an existing one.

To add a preset, append an entry to the relevant array in the JSON file - no code change or restart needed (it’s fetched fresh by the browser). Keep enum-like fields (type, sensor_type, mount_type, filter_type) consistent with the values each form’s <select> accepts, or the preset will silently fail to prefill that field.

Bundles (smart telescopes)

A telescope preset can declare a bundle: an array of sibling equipment items that ship built into the same physical unit - most commonly an all-in-one “smart telescope” (Seestar, Dwarf, Vespera, …) whose fixed built-in camera sensor has no other way to be represented, since a plain telescope preset only carries optical specs (aperture/focal length), not sensor data.

{
  "id": "seestar_s50",
  "...": "... normal telescope fields ...",
  "auto_combination": true,
  "bundle": [
    { "kind": "camera", "label": "Seestar S50 built-in camera (Sony IMX462)", "sensor_width_mm": 5.6, "...": "..." },
    { "kind": "mount", "label": "Seestar S50 built-in AZ mount/tripod", "mount_type": "Alt-Azimuth", "...": "..." },
    { "kind": "filter", "label": "Seestar S50 Solar Filter", "filter_type": "Solar", "...": "..." }
  ]
}

• kind is one of camera / mount / filter / accessory; the rest of each bundle entry’s fields match that kind’s normal preset shape one-to-one (same as a standalone entry in the cameras/mounts/ filters/accessories arrays above).
• Set weight_kg: 0 on every bundle entry - the parent telescope’s own weight_kg already represents the whole fused unit’s mass; giving bundle items their own non-zero weight would multiply-count it in a combination card’s total payload calculation.
• auto_combination: true on the parent tells the guided setup wizard (static/js/first_run.js) to create every bundle item alongside the telescope and link them all into one auto-created combination - this is what makes “every time the wizard creates equipment, a combination is created” true even for a single-preset pick. When a bundling preset is selected, the wizard’s separate camera picker is hidden (a combination can only have one imaging camera, and the bundle already supplies it).
• Bundle items are never independently selectable elsewhere (no separate preset dropdown entry) - they only ever get created as part of their parent telescope’s wizard flow.

Telescopes

Cameras

Mounts

The last three feed the Plan My Night meridian flip indicator - see PLAN_MY_NIGHT.md. Absent on older mount files, they are backfilled to these defaults on every read (equipment_profiles.normalize_mount_flip_fields, applied by get_mount, the mounts list endpoint and plan_my_night._resolve_plan_mount); the stored file is not rewritten.

Filters

Accessories

Generic category for any optical or mechanical accessory not covered above: field flatteners, focusers, filter wheels, OAGs, etc.

API endpoints

Last updated 2026-11-13

Exposure Calculator

The Exposure Calculator is a tool inside the Equipment tab that helps astrophotographers determine the optimal sub-exposure length and total number of frames for a given night.

Where to find it

Equipment -> Exposure Calc

Inputs

Outputs

Limitations

• QE is assumed flat across the spectral range. In practice, QE varies with wavelength. The formula uses V-band sky flux (matching the SQM meter passband), which gives the best absolute accuracy for broadband RGB imaging.
• Narrowband filters require different treatment: the sky background is much lower (fewer e⁻/px/s) through Ha/OIII/SII filters, so sub-exposures can and should be much longer. The calculator is primarily intended for broadband (L/RGB/OSC) imaging.
• Dark current is not included. For cooled cameras (−10 °C or colder), dark current is negligible. For uncooled or mildly cooled cameras add dark current to B_sky if known.
• Atmospheric extinction, light pollution gradients, and vignetting are not modelled.

Estimated minimum integration time

The Exposure Calculator sizes subs from a total integration the user supplies. The SkyTonight advanced DSO filter “max estimated integration time” needs the opposite: a rough estimate of the total integration a target needs. This is implemented in backend/equipment/exposure_math.py (estimate_min_integration_hours) and is a deliberately rough planning heuristic, not a promise.

How the estimate is computed

Working in the sky-limited regime (which the sub-exposure length from Method guarantees), the per-pixel signal-to-noise ratio after a total integration time is

where and are the per-pixel photo-electron rates (e⁻/px/s) from the target’s mean surface brightness and from the sky, both computed with the same form used for in Method. Solving for to reach a chosen per-pixel SNR target:

• (per pixel, on the target’s mean surface brightness). This is a “detectable and processable” threshold, not “publication quality” - deep, clean images of faint targets need far more.
• The target’s mean surface brightness comes from the catalogue integrated magnitude spread over the catalogue angular size (skytonight_calculator._surface_brightness, then converted from mag/arcmin² to mag/arcsec²). This over-estimates the required time for objects with a bright core and faint outer halo (e.g. M31, M42) - the mean over the full catalogue extent is much fainter than the part you would actually expose for.
• Sky brightness comes from the active location’s measured SQM if set, otherwise the Bortle -> SQM table in Method.
• Because and share the factor, aperture largely cancels: the estimate is driven by f-ratio, pixel size, sky brightness and target surface brightness - the well-known result that per-pixel SNR on extended sources depends on f-ratio, not aperture.

Limitations

• Broadband (L / RGB / OSC) only, exactly like the sub-exposure calculator - narrowband sky rates are far lower and the estimate does not model them.
• No QE-curve, atmospheric extinction, filter transmission, gradient or vignetting modelling.
• The mean-surface-brightness input skews the estimate long for centrally-concentrated targets.
• Treat the number as an order-of-magnitude planning aid (“minutes”, “a couple of hours”, “many nights”), not a target to hit.

Method

Plate scale

Sky background rate

The sky photon rate per pixel per second is computed from the observed sky surface brightness (SQM value derived from the Bortle class), the telescope aperture, and the plate scale:

Where:

• photons/m²/s/arcsec² - Vega zero-point flux, V-band
• - aperture in metres
• - in arcsec/px (so is arcsec²/px)

Bortle -> SQM mapping

Optimal sub-exposure (5× criterion)

The recommended sub-exposure is chosen so that the sky background contributes 5 times more noise variance than the read noise:

This is the standard “sky-limited” criterion used in amateur astrophotography. Exposures shorter than this threshold are read-noise dominated; longer exposures don’t improve SNR per unit time.

Number of subs

Calibration

The formula was validated against published empirical measurements:

• ASI294MC Pro, f/7, 150 mm aperture, pixel = 4.63 µm, QE ≈ 75%, Bortle 5 (SQM 20.3)
• Expected sky background from real data: ~0.83 e⁻/px/s
• Formula result: ~1.0 e⁻/px/s - within the measurement uncertainty

Last updated 2026-11-13

Observatory

The Observatory tab consolidates live data from all enabled connectors into a single dashboard. The tab is hidden in the navigation bar until at least one connector is enabled in App settings -> Connectors.

Navigation visibility

The Observatory nav item is hidden by default. It appears automatically when a connector is enabled and saved. Disabling all connectors hides it again.

Layout

The panel grid adapts to which modules are active:

Each panel only appears when its module is enabled, so a row with no enabled module is skipped entirely.

AllSky section

When the AllSky connector is enabled, the Observatory renders panels for each active module:

Live image

Auto-refreshing all-sky camera image, reloaded every 30 seconds via the MyAstroBoard proxy. If the image fails to load (AllSky offline or path misconfigured), an “unavailable” placeholder is shown and a reload is retried after 5 minutes.

When sensor data is also enabled, a day/night badge is displayed alongside the image title (sourced from AS_DAY_OR_NIGHT in the AllSky sensor data).

Sensor data

Camera and environment readings, received over MQTT from AllSky’s Publish Data to Redis/MQTT/REST/influxDB module (allsky_publishdata) and polled by the card every 60 seconds. Setup: CONNECTORS.md - Sensor data module.

Displayed fields (when present in the message):

AllSky v2026 declares one environment sensor (Environment group: AS_TEMP, AS_HUMIDITY, AS_DEW, AS_TEMPSENSOR) that the Dew Heater and Fans modules reuse, so their readings repeat it: it is read first, so each quantity shows once. v2024 has a sensor per module, read as the fallback.

Keogram

Daily keogram - a horizontal timeline strip showing sky evolution throughout the night. Generated by AllSky at end of night. Displays “not yet generated” until the file exists on the AllSky server.

Startrails

Stacked startrails image for the current night. Generated by AllSky at end of night.

Daily timelapse

Full-night timelapse video (MP4) generated by AllSky at end of night, embedded as an HTML5 <video> element.

API endpoints

See API_ENDPOINTS.md - Connectors for the full list of connector endpoints used by the Observatory.

Last updated 2026-11-13

Home Assistant integration (MQTT publisher)

MyAstroBoard can publish its state to an MQTT broker, with Home Assistant MQTT Discovery: enable the connector, point it at the broker Home Assistant already uses, and a “MyAstroBoard” device appears in Home Assistant together with one device per location - sky period, night score, sun and moon times, tonight’s best window and top target, current weather-for-astro, upcoming events - and, for users who opted in, one device per user with their Astrodex counters, tonight’s plan and its equipment, observation log totals and the latest Astrodex picture.

It is publish-only: MyAstroBoard never reads commands from the broker. The only thing it subscribes to is Home Assistant’s own birth message, so entities come back by themselves after a Home Assistant restart.

Ready-made Lovelace cards live in a separate repository: lovelace-myastroboard-card.

MyAstroBoard itself can also run inside Home Assistant OS, as an app - see Installation, option 2. The MQTT integration below works the same whichever way MyAstroBoard is installed (broker host core-mosquitto when both run in Home Assistant).

Requirements

Setup

1. Broker. Create a user for MyAstroBoard on the broker (Mosquitto add-on: Settings -> Add-ons -> Mosquitto -> Configuration, or a Home Assistant user - the add-on accepts those). Note the broker’s IP address and port (1883, or 8883 for TLS).
2. MQTT connection. App settings -> Configuration -> MQTT connections -> Add a connection (see MQTT connections):
   • Display name: any name, shown in the connector’s picker.
   • Broker URL: mqtt://192.168.1.10:1883 (or mqtts://host:8883 for TLS). Use the IP address rather than a .local name - mDNS does not resolve inside the container.
   • Username / Password: the broker user. Leave both blank for an anonymous broker.
   • Press the test button (wifi icon): it opens one real connection to the broker with the settings as typed and reports Reachable or the reason it is not (refused, timeout, not authorized, TLS…). Save.
3. Connector. App settings -> Connectors -> MQTT / Home Assistant -> Configure:
   • MQTT connection: pick the connection created above (the wifi button tests it).
   • Tick the modules you want (see Modules), switch Enable connector on, Save.
4. Home Assistant. Settings -> Devices & services -> MQTT: within a minute a MyAstroBoard device and one MyAstroBoard - <location> device per location preset appear. The card’s status line shows Connected, the last publish time and the number of devices and entities.

Nothing has to be added to configuration.yaml.

Per-user activity

Location and board data are install-level and published as soon as the connector is on. A user’s data (Astrodex, plan, observation log, pictures) is private, so it is published only when that user asks for it: My settings -> Customize -> Publish my activity to Home Assistant (MQTT). The switch only shows once an admin has enabled the connector, and it only ever covers the user’s own data - an admin cannot publish another user’s activity. The admin-side User activity and Latest Astrodex picture modules must be on as well.

Modules

Every location the cache scheduler keeps warm gets a device (in practice every preset). Disable the entities you do not need from the device page in Home Assistant.

Settings

MQTT connections

A broker is declared once, in App settings -> Configuration -> MQTT connections, and each MQTT connector picks one. Several connectors can share a connection: each one opens its own client, which is why two connectors on one connection cannot be saved with the same client ID (a broker keeps one session per client ID and would disconnect them in turn).

The list shows, for each connection, whether the broker answers (checked when the page opens and with the wifi button) and which connectors use it. A connection still picked by a connector cannot be deleted: pick another one in that connector first. Editing a connection makes every connector using it reconnect.

Upgrading from 1.7.1 or earlier: a configured connector’s broker becomes a connection named Home Assistant, already picked by the connector, with its password - nothing to re-enter.

Buttons

• Publish now - full republish of discovery and every state on the next tick (a few seconds).
• Remove from Home Assistant - switches the connector off and deletes every retained MyAstroBoard topic from the broker; Home Assistant drops the devices (their history is lost). Broker settings and modules are kept, so enabling the connector again recreates everything. Simply switching the connector off, by contrast, leaves the devices in place as unavailable. See Long-term statistics for the one thing a removal leaves behind.

Long-term statistics

Home Assistant records long-term statistics for every sensor that declares a state_class, and keeps them after the entity disappears. Only the six counters that track your own progress declare one (state_class: total): Astrodex objects, objects with pictures, pictures, constellations, observation sessions and total integration - the numbers a Statistics graph card can show growing month after month. Everything else (sky, Moon, best window, weather, aurora, plan progress) is an ephemeris or a forecast that MyAstroBoard recomputes at any time, so it deliberately records no long-term statistics; the recorder’s short-term history (10 days by default) still draws them in a history graph.

After Remove from Home Assistant (or a user opting out), those six series per user stay in the recorder as orphans. Home Assistant lists them under Developer tools -> Statistics with a Fix issue action that deletes them; Spook reports the same list. Nothing else is left behind.

Automation ideas

# Red observatory light at astronomical dusk
trigger:
  - platform: state
    entity_id: sensor.myastroboard_backyard_sky_period
    to: astronomical_night
action:
  - service: light.turn_on
    target: { entity_id: light.observatory }
    data: { rgb_color: [255, 0, 0], brightness: 40 }

# Tonight looks good
trigger:
  - platform: numeric_state
    entity_id: sensor.myastroboard_backyard_observation_score
    above: 7
condition:
  - condition: state
    entity_id: binary_sensor.myastroboard_backyard_astronomical_night
    state: "on"
action:
  - service: notify.mobile_app_phone
    data:
      message: "Night score {{ states('sensor.myastroboard_backyard_observation_score') }} - top target {{ states('sensor.myastroboard_backyard_top_target_tonight') }}"

Privacy and security

• Outbound only. No command topic exists; nothing Home Assistant publishes is acted upon.
• The password lives in the connector secrets store, never in the configuration, backups, the config export or any API response (the connection list only sees a mask).
• The connection test never pairs the stored password with a URL that differs from the saved one, and the MQTT and MQTT connection routes are admin-only.
• mqtts:// gives TLS; Accept self-signed certificates is meant for a LAN broker with its own CA, nothing else.
• A user’s data is published only while that user’s own switch is on. Location devices carry the preset name and timezone, not its coordinates; pictures are published without location data.

Troubleshooting

Log lines are prefixed MQTT publisher: in data/myastroboard.log.

Tested against Home Assistant 2024.11+ discovery format; re-check the release notes of the Home Assistant version you run if entities fail to appear.

Entities

Home Assistant builds each entity id from the device name and the entity name (never from the JSON key): the Top target tonight sensor of the “MyAstroBoard - Backyard” device is sensor.myastroboard_backyard_top_target_tonight, the Astronomical night binary sensor is binary_sensor.myastroboard_backyard_astronomical_night, the picture is image.myastroboard_alice_latest_astrodex_picture. unique_id is <base>_loc_<location_id>_<key>, so renaming a preset later keeps the entity history. The tables below are generated from backend/connectors/mqtt_payloads.py.

Board device (Board diagnostics)

Location device - Sky conditions

Location device - Weather now

Nearest hourly forecast row plus the astro analysis.

Location device - Upcoming events

User device - User activity