Skip to content
ES App (ES) ↗

Technical documentation

How Astrolarius works inside

For anyone who wants to know where each number comes from. If you're after how to use the app, start with the help.

Where the data comes from

  • Object catalog: OpenNGC, by Mattia Verga (CC BY-SA 4.0), filled out with Sharpless, LDN, LBN, Barnard, vdB and Abell from VizieR (CDS), plus RCW, Gum, Cederblad, the open cluster names, Arp, Hickson and the Abell galaxy clusters. Duplicate designations are kept as aliases of the same object.
  • Weather: Open-Meteo (CC BY 4.0), by the hour: total, low, mid and high cloud, temperature, humidity, dew point, wind and gusts, probability and amount of rain, the weather code and the wind at 250, 500 and 850 hPa. Eight days plus the previous one are requested, with your position rounded to two decimals (about a kilometer, 0.6 mi). For imminent rain, 15-minute steps over the next 12 hours, and for transparency, the aerosol optical depth and the dust.
  • Seeing: an estimate of our own from the wind at 250 hPa and the wind shear between layers. It is a rough guide: the real seeing only shows at the telescope.
  • Sky brightness (Bortle): a grid taken from VIIRS Nighttime Lights (EOG, CC BY 4.0), interpolated between its points. Turning that into the Bortle scale is an estimate of our own; if you measure your sky with an SQM, you can enter your own value.
  • Town search: our own search, with GeoNames data (CC BY 4.0).
  • Positions of the Sun, the Moon, the planets and the objects: Astronomy Engine (MIT), on your device, topocentric and with refraction.
  • Sky images: DSS2 in color, through the CDS hips2fits service; the planets, from Wikimedia (CC BY 4.0) and from Raúl Hussein (with his permission).
  • Bright stars: the Yale Bright Star Catalogue (5th edition, VizieR V/50), down to magnitude 6.5.
  • Maps for Alignments: OpenStreetMap worldwide and, in Spain, the aerial photos of the IGN, the national mapping agency (PNOA, CC BY 4.0); the terrain altitude, from Open-Meteo. Their photos: the Moon, by Fran López; the Sun, NASA/SDO (public domain); the sky, the ESO/S. Brunier panorama (CC BY 4.0).

The full credits are on the credits page.

What is stored on your device

Everything of yours stays in the browser's local storage: your site and its Bortle class, your horizons, your gear, your rigs and the ones you have ready, the projects and the history, the plans, the alignments and their landscape projects, and your settings (red mode and type size). No account is required and there is no analytics. Without an account, nothing of yours is uploaded: the only requests that leave are reads to Open-Meteo (the weather, with your position rounded), to the map servers, to hips2fits (the sky images) and to our own town search. With an account, that backup is also kept on our server, along with the photos you upload to the gallery and, if you turn it on, the evening alert.

The backup is a .json file that downloads to your device; it isn't sent anywhere. If you create an account (optional, with your email), that same copy is also kept in it and updates itself, so you have the same thing on several devices.

The app installs as a web app (a PWA). Its pages are stored on the device when you install it and work offline; the sky images are stored as you look at them and aren't deleted when it updates. The weather and the maps need a connection.

Tonight's best targets

Every object, with each of your rigs, gets a score from 0 to 100: the weighted average of seven components.

ComponentWeightWhat it looks at
Appeal25%How striking the object is to photograph.
Rig23%Whether your telescope and camera suit it: image scale, field and focal length.
Moon and filter14%The Moon (phase and distance to the object) with the filter you have.
Framing11%Ideally it fills 40% to 60% of the field; if it doesn't fit, the score drops.
Time10%The useful hours (100 with six) and the mean altitude, from 30° to 70°.
Season10%100 if it crosses the meridian in astronomical darkness; 65 if it crosses less than two hours away; 25 if it doesn't.
Interests7%What you said you like to photograph.

A useful hour is one in which the object is above its minimum altitude in astronomical darkness, total cloud is no more than 50% (and low and mid cloud no more than 40%), and the weather score reaches 60. At least one is needed.

The Moon within 30° of the object rules the combination out; between 30° and 60° it takes 25 points off, and beyond 90° it adds 3. In broadband, a Moon lit 30% or more takes 20 off, and a Bortle 6 sky or worse, another 20. Your horizon trims, minute by minute, the time each object is actually visible.

The labels are relative to the night: the top 10% is “excellent”, the next 20% “very good”, the next 30% “good” and the rest “fair”. At most 30 objects are shown. On the home page, “tonight's best” adds up the minutes above 30° in astronomical darkness, in steps of 10 minutes; with the Moon up (more than 25% lit and above the horizon), each step counts as 8 minutes with a narrowband filter and 2 with broadband. The objects chosen are more than 10° apart.

The night, the Moon and your horizon

  • Twilight: civil with the Sun at −6°, nautical at −12° and astronomical at −18°. Astronomical darkness runs from evening −18° to morning −18°.
  • Moon: its angular distance to each object and its illumination, as a percentage with one decimal.
  • Horizon: what blocks each direction, in 5° steps of bearing with its altitude. If two stretches overlap, the higher one wins.
  • The active night is the one that starts the previous day and runs until sunrise, and it is named after the day it starts.

The night's plan and the Copiloto

The plan puts each object in the longest free slot of its mount inside its useful window, with a minimum of 30 minutes, and never two rigs on the same mount at once. Changing rig costs 40 minutes and changing object, 10; changing filter costs one minute with a wheel, five with a drawer and nothing with a built-in filter.

The frames that fit are the real ones, not a division: after each frame, 10 seconds of download; a 20-second dither every 3 frames when they last 300 seconds or more (every 5 when they're shorter); 3 minutes of autofocus every hour, only with a motorized focuser; and the meridian flip, 8 minutes, only with an equatorial mount and if the object crosses in that stretch. The plan assumes −10 °C for cooled cameras.

The Copiloto splits the night into phases (afternoon, setup from an hour and a half before sunset, twilight, capture, night and packing up) and warns of each step ten minutes ahead and at the moment: the meridian, the handovers and changes, the horizon (“behind your horizon in 15 minutes”), the altitude, refocusing, the clouds, the rain and the cold. The voice speaks only for the important ones.

The rain watch checks the next 45 minutes every 15 minutes and warns if the probability reaches 40% or more than 0.1 mm is expected in a stretch. It repeats every two minutes, up to five times (“snooze” is ten minutes), and keeps the screen on while it watches.

Filters

Each filter is classified by what it lets through: narrowband (dual band included), light pollution or broadband (with UV/IR cut). An IR Pass is never suggested for deep sky.

ObjectNarrowbandLight pollutionBroadband
With strong emission lines956540
Broadband (galaxies, clusters)207295

A narrowband filter only scores 95 if it lets through every strong line of the object; if it lets some through but not all (an Hα alone on the Veil, which is also strong in OIII) it scores 60, and if it lets none through, 15: below broadband, which at least picks up the Hα in the red channel.

If several filters would do, the choice goes in this order: the one you marked as your favorite; if there's a star of magnitude 4 or brighter in the field, one without halos; if the object is strong in OIII, the narrowest; with the Moon up (more than 30% or closer than 60°), the narrowest; and if it's strong in Hα and 30′ or larger, the widest. With “I'm starting out” a narrowband filter is never suggested for galaxies.

It also warns about what usually goes wrong: a filter of 4 nm or less on a telescope at f/4 or faster (at f/5, “you're pushing it”), a 1.25″ filter with a sensor whose diagonal is over 22 mm (it vignettes) and a light pollution filter on galaxies from Bortle 5 up.

Projects

A project is an object with a rig. The hours aren't logged by hand: they come from adding frames × exposure for each night you confirm in “how did it go?”, and confirming a night again replaces it rather than counting it twice. The target hours suggested are, for nebulae, 10, 6 or 4 hours (narrowband, light pollution or broadband) and, for galaxies, 6, 6 or 8; you can change them per filter.

A project is in progress, waiting (with the date it comes back into season: when it crosses the meridian in astronomical darkness and gives at least 5 useful hours) or finished. The next good night is looked for within the following 14 days: the one that reaches 3 useful hours (1 for planets).

The landscape shots that start in Alignments are projects of another kind: a date and a time, the spot, the focal length, the forecast clouds when it's less than 16 days away and, once the date has passed, “how did it come out?”, with a search for the next chance if it didn't.

DSLR exposure (with a tripod and a lens)

The seconds per frame before the stars trail come from the NPF rule:

seconds = (35 × f + 30 × pixel in µm) ÷ focal length × advantage

where f is the f-number (f/2.8 → 2.8) and the advantage is min(3, 1 ÷ cos(declination)): near the celestial poles the stars move less. The result is rounded down to a shutter speed the camera can actually be set to, in third stops (1 · 1.3 · 1.6 · 2 · 2.5 · 3.2 · 4 s…), and the full-stop one (1 · 2 · 4 · 8 s…) is given too for cameras that only take those; above 30 seconds, in whole seconds with bulb mode. It warns you if it drops below a second and, on a tripod, if the focal length goes over 300 mm. The starting ISO comes from a table per camera (400 to 1600; 800 if it isn't listed).

Calibration frames

  • Darks: with a cooled camera, only if the exposure or the temperature changed, or if the ones in your library are old (30 to 50); with an uncooled dedicated camera, 20 to 30 when you finish; with a DSLR, shoot them on a cloudy night at a similar temperature.
  • Flats: 25 per filter if you rotated the camera, there's dust or you use a DSLR.
  • Dark flats or bias: dark flats with dedicated CMOS cameras; bias with a DSLR.

At the end, the total time and a sentence with what tonight calls for. The same calculation is on the website: which calibration frames do I need?

Exporting to N.I.N.A. and the ASIAIR

For N.I.N.A., the app fills in the sequence template you exported yourself: the object's name, its RA and Dec, the camera angle, the exposure, the gain, the offset, the temperature and the number of frames.

For the ASIAIR (and for N.I.N.A. too), a CSV in the Telescopius format, with one row per panel if it's a mosaic. Its header is Pane, RA, DEC, Position Angle (East), Pane width (arcmins), Pane height (arcmins), Overlap, Row, Column, and the coordinates go as 20hr 15' 22" and 39º 33' 28".

Alignments

The bearing and the distance between your spot and the subject are worked out on the sphere (a radius of 6,371 km). Distant things drop with the Earth's curvature, partly offset by refraction: drop = d² ÷ 2R × (1 − 0.13). With the terrain altitude of both points and your camera height, it works out at what altitude above the horizon you see the base and the top of the subject.

  • The Moon and the Sun, “sitting” on it: the next 12 months are searched in 20-minute steps for the moment when the center of the disc is 0.6 radii above the top (the disc resting, slightly behind), and it is refined by bisection; it counts if at that moment it falls within the width of the subject.
  • The Milky Way: the core is Sagittarius A* (RA 17 h 45 min 40 s, Dec −29.0°). The good nights are those in full darkness (Sun below −18°), with no Moon (below the horizon or less than 25% lit) and with the core above the subject and within 30° either side; the best one of each week is shown.
  • “Where do I stand?”: the size you choose (the subject is k times the Moon or the Sun, or k degrees with the Milky Way) sets the distance; each pass of the body through the altitude you marked gives the spot, on the other side of the subject. When you pick one, the time is corrected with the real altitude and the line of sight is checked with 40 altitude points between you and the subject. Houses, trees and rocks aren't in that data.
  • The preview is a rectilinear camera: the sky is projected onto the sensor plane, as a real lens does (the pixels per unit of tangent are half the width over the tangent of half the field). The Milky Way sky is the ESO panorama, in galactic coordinates, projected pixel by pixel with the sidereal time of that moment.
  • Coordinates it understands: decimal degrees (with a point or a comma, and with N, S, E or W), degrees, minutes and seconds, Google Maps links and Plus Codes (the short ones, within about 50 km (30 mi) of your site). Short maps.app.goo.gl links don't carry the coordinates.
  • The calendar event (.ics) starts half an hour earlier, with reminders the day before and two hours before.

Red mode and type size

Red mode turns the whole palette to reds and puts the images through a filter that leaves them in shades of red, so you don't lose your dark adaptation. The type has three sizes: normal, large (15% bigger) and very large (30% bigger). The typefaces are Lexend and Atkinson Hyperlegible (SIL OFL 1.1).

The numbers on this page are those of the current version of the app; when they change, they are changed here.