Skip to content

Catalogue guide

arcsec cannot solve anything without a star catalogue. Getting one is a single command, and everything is installed into one folder that the solver already reads, so afterwards you can run arcsec -f image.fits with no -d and no -D. The same command builds a blind index from the catalogue, so arcsec can also solve with no position hint.

It depends on your field of view. The Which catalogue do I need? page works it out from your focal length and camera, or ask arcsec, giving either the field size in degrees or an image to read it from:

Terminal window
arcsec catalog recommend --fov 1.5 # field size in degrees
arcsec catalog recommend --like image.fits # read FOCALLEN and XPIXSZ from the header
arcsec catalog recommend --fov 1.5 --photometry # include a photometric catalogue

It suggests the smallest download that covers your field. The full set:

NamePurposeDownloadFieldsNotes
d05Solving102.2 MB0.6°–6°Gaia DR3 to 500 stars/deg². Smallest useful solving database.
d20Solving399.6 MB0.3°–6°Gaia DR3 to 2000 stars/deg².
d50Solving901.3 MB0.2°–6°Gaia DR3 to 5000 stars/deg². The usual choice for solving.
d80Solving1.2 GB0.15°–6°Gaia DR3 to 8000 stars/deg². Densest; needed below ~0.2° fields.
g05Solving101.6 MB3°–20°Wide fields, 3°–20°. The D-series stops at 6°.
w08Solving330.0 kB20°–80°Very wide fields, 20°–80°, to magnitude 8. Tiny.
v05Photometry116.9 MB0.6°–6°Johnson-V magnitudes plus Gaia BP-RP colour, 500 stars/deg².
v50Photometry1.0 GB0.2°–6°Johnson-V plus BP-RP colour, 5000 stars/deg². Deeper photometry.
anet-4100Blind355.5 MB0.7°–180°Tycho-2 blind indexes, scales 07–19 (fields ~0.7° and wider).
anet-5200Blind8.8 GB0.1°–2°Gaia LITE blind indexes 5200/5201/5202, 48 HEALPix each. Large.

The solving catalogues are ASTAP’s star databases, built from Gaia DR3; the blind index sets are Astrometry.net’s, and optional, since arcsec builds its own blind index from the solving catalogue. arcsec catalog list prints the same table, and shows which are installed.

Rules of thumb:

  • Solving: one D-series catalogue is enough for a telescope. Add g05 if you also shoot with a camera lens, and w08 if you shoot all-sky. They are small.
  • Photometry: the V-series add Johnson-V magnitudes and colour, for photometry and colour calibration. v05 unless you need the depth of v50. arcsec can solve with them too, but recommends a solving catalogue for that.
  • Blind solving (no position hint, or N.I.N.A.’s blind mode): nothing extra to download. Installing a solving catalogue builds arcsec’s own blind index from it. The Astrometry.net sets still work with -i, but are slower and find fewer fields.
Terminal window
arcsec catalog install d50 # shows the size and asks first
arcsec catalog install d50 v05 g05 --yes # several at once, no prompt
arcsec catalog install d50 --no-index # download only, no blind index
arcsec catalog list # every catalogue, and what is installed
arcsec catalog verify # check for missing or truncated files
arcsec catalog remove d80 # free the space again
arcsec catalog path # print the catalogue folder

install and remove both list what they will do and ask first; --yes (or -y) skips the question. --keep-archive keeps the downloaded .zip or .deb after unpacking. Run from a script with no --yes, they cancel rather than guess.

Installing a solving catalogue (d05, d20, d50, d80, g05 or w08) also builds the blind index, and the question says what that costs next to the download:

$ arcsec catalog install d50
Installing into /home/me/.local/share/arcsec/catalogs
d50 901.3 MB Gaia DR3 to 5000 stars/deg². The usual choice for solving.
Total download: 901.3 MB
Then build a blind index from D50, fields 0.3°–30° (no blind index is installed yet):
~287.4 MB on disk, ~25 s, ~0.6 GB memory
(--no-index to skip it)
Continue? [y/N]

arcsec checks there is room on the disk for the download, the unpacked files and the index before it starts.

Installs are resumable: interrupt one and run the same command again, and the download continues from where it stopped, provided the server supports it. Files are written under a temporary name and only moved into place once complete, so a half-finished download never looks like an installed catalogue. Downloading and unpacking are built in; no other tools are needed.

The blind index lets arcsec find a field anywhere on the sky in a second or two, without a position hint and, if need be, without a pixel scale. It is built from the solving catalogue you already have, so there is nothing more to download, and catalog install builds it for you. arcsec uses it by itself when a search is wide (a search radius of 10° or more, as N.I.N.A.’s blind solve sends), and -i with the catalogue folder makes any solve blind:

Terminal window
arcsec -f image.fits -i "$(arcsec catalog path)"

One index serves the whole folder. It is built from the densest solving catalogue there, for the fields of every catalogue installed:

Catalogues Fields served Index Build time* Memory while building
d20, d50, d80 0.3°–30° 287 MB about 30 s 0.6 GB
d80 with --index-min-fov 0.15 0.15°–30° 698 MB about 2 min 1.3 GB
d05 0.6°–30° 145 MB about 10 s 0.3 GB
g05 3°–30° 12.5 MB a second 0.1 GB
w08 10°–80° 0.8 MB instant small

* On an 8–24 thread desktop. A four-core mini-PC takes about twice as long; the estimate in the question is worked out for your machine.

For fields narrower than 0.3° (the D80 range), add --index-min-fov 0.15 when you install; arcsec catalog recommend suggests it. The default stops at 0.3° because the extra layer more than doubles the index.

When you are asked separately. If the index would be over 1 GB, take over 5 minutes, or need more than half your free memory (a Raspberry Pi, a small mini-PC), arcsec prints a note and asks about the index on its own, so you can take the download and skip the index. --yes answers both.

Already have catalogues? If you installed them with arcsec 0.4 or earlier, or use ASTAP’s folder, there is no index yet: arcsec catalog list says so and shows what building one costs. Build it once with:

Terminal window
arcsec catalog index build

Keeping it current. arcsec catalog verify checks the index and tells you if the catalogue it was built from has changed since (say, a new ASTAP release); re-running arcsec catalog install <name> or arcsec catalog index build rebuilds it. Installing a denser or wider catalogue rebuilds it too. arcsec catalog remove d80 removes the index built from D80 along with it, unless you add --keep-index. A build interrupted with Ctrl-C leaves nothing behind.

Platform Default folder
Linux $XDG_DATA_HOME/arcsec/catalogs, else ~/.local/share/arcsec/catalogs
macOS ~/Library/Application Support/arcsec/catalogs
Windows %LOCALAPPDATA%\arcsec\catalogs

If none of those can be resolved, ~/.arcsec/catalogs is used. arcsec catalog path prints the folder in effect.

To use another folder, for example on a larger disk, set the ARCSEC_CATALOG_DIR environment variable, or pass --dir to a single catalog command:

Terminal window
export ARCSEC_CATALOG_DIR=/mnt/data/star_databases

On Windows, setx keeps the setting for programs started from now on, and the second line applies it to the window you are in. On macOS and Linux, add the export line to your shell’s startup file (~/.zshrc or ~/.bashrc) to keep it.

The solver reads this folder automatically as long as a star database is installed there; otherwise it falls back to the current working directory, as ASTAP does. -d is only needed to point somewhere else for one run, and -D only to force a particular database. Otherwise arcsec picks the densest installed database whose field range covers the image.

The blind index is in the same folder, as <name>.arcsecix (d50.arcsecix). Astrometry.net index files install there too, as index-*.fits. The solver only uses those when asked, so blind solving with them means passing that folder (or one index file) to -i:

Terminal window
arcsec -f image.fits -i "$(arcsec catalog path)" --fov 3

Point arcsec at ASTAP’s databases and skip the download:

Terminal window
export ARCSEC_CATALOG_DIR=~/star_database # or wherever ASTAP keeps them
arcsec catalog list # confirms what it found
arcsec catalog index build # once: the blind index

C:\Program Files\astap is ASTAP’s default folder on Windows. Only an administrator can write there, so run arcsec catalog index build from a window opened with Run as administrator. The N.I.N.A. guide has more.

arcsec reads ASTAP’s files directly and the solver never modifies them, so the two programs can share a folder. The blind index is the one file arcsec adds to it (d80.arcsecix, for example); ASTAP ignores it.

The ASTAP databases come in three layouts, which arcsec reads transparently. You do not need to care, but catalog verify checks each database’s file count against its layout:

Layout Sky grid Used by
.1476 1476 tiles in 36 rings of equal declination D80, D50, D20, D05, V50
.290 290 tiles in 18 rings of equal area G05, V05
.001 one all-sky file W08

Which database uses which layout cannot be predicted from its name: v05 is .290 even though it covers the same fields as the .1476 D-series. Both catalog and the solver look for whichever is present. The format notes have the details.

The blind index is built locally, as above. Generating a star catalogue itself from Gaia is not possible; arcsec catalog install is the supported route. The index’s design and measurements are in offline-index.md.