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.

Which catalogue do I need?

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:

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:

Name	Purpose	Download	Fields	Notes
`d05`	Solving	102.2 MB	0.6°–6°	Gaia DR3 to 500 stars/deg². Smallest useful solving database.
`d20`	Solving	399.6 MB	0.3°–6°	Gaia DR3 to 2000 stars/deg².
`d50`	Solving	901.3 MB	0.2°–6°	Gaia DR3 to 5000 stars/deg². The usual choice for solving.
`d80`	Solving	1.2 GB	0.15°–6°	Gaia DR3 to 8000 stars/deg². Densest; needed below ~0.2° fields.
`g05`	Solving	101.6 MB	3°–20°	Wide fields, 3°–20°. The D-series stops at 6°.
`w08`	Solving	330.0 kB	20°–80°	Very wide fields, 20°–80°, to magnitude 8. Tiny.
`v05`	Photometry	116.9 MB	0.6°–6°	Johnson-V magnitudes plus Gaia BP-RP colour, 500 stars/deg².
`v50`	Photometry	1.0 GB	0.2°–6°	Johnson-V plus BP-RP colour, 5000 stars/deg². Deeper photometry.
`anet-4100`	Blind	355.5 MB	0.7°–180°	Tycho-2 blind indexes, scales 07–19 (fields ~0.7° and wider).
`anet-5200`	Blind	8.8 GB	0.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. 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 (-i): only if you cannot supply an approximate position. With a mount that reports where it is pointing, you do not need these at all. The index only finds the rough position; the solve is then finished against a solving catalogue, so you need one of those as well.

Installing and removing

arcsec catalog install d50                 # shows the size and asks first
arcsec catalog install d50 v05 g05 --yes   # several at once, no prompt
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.

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.

Where they are stored

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:

export ARCSEC_CATALOG_DIR=/mnt/data/star_databases              # Linux and macOS

setx ARCSEC_CATALOG_DIR "D:\star_databases"                      # Windows

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.

Astrometry.net index files install into the same folder, as index-*.fits. The solver only uses them when asked, so blind solving means passing that folder (or one index file) to -i:

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

If you already have ASTAP

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

export ARCSEC_CATALOG_DIR=~/star_database    # or wherever ASTAP keeps them
arcsec catalog list                          # confirms what it found

On Windows, ASTAP’s default folder is C:\Program Files\astap; the N.I.N.A. guide shows how to set the variable.

arcsec reads ASTAP’s files directly and the solver never modifies them, so the two programs can share a folder.

File formats

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.

Building your own

Not possible yet. Generating a catalogue from Gaia, or a pre-computed pattern index, is designed but not implemented. Until then, arcsec catalog install is the supported route.