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.
Which catalogue do I need?
Section titled “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 degreesarcsec catalog recommend --like image.fits # read FOCALLEN and XPIXSZ from the headerarcsec catalog recommend --fov 1.5 --photometry # include a photometric catalogueIt 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, 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
g05if you also shoot with a camera lens, andw08if you shoot all-sky. They are small. - Photometry: the V-series add Johnson-V magnitudes and colour, for photometry
and colour calibration.
v05unless you need the depth ofv50. 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.
Installing and removing
Section titled “Installing and removing”arcsec catalog install d50 # shows the size and asks firstarcsec catalog install d50 v05 g05 --yes # several at once, no promptarcsec catalog install d50 --no-index # download only, no blind indexarcsec catalog list # every catalogue, and what is installedarcsec catalog verify # check for missing or truncated filesarcsec catalog remove d80 # free the space againarcsec catalog path # print the catalogue folderinstall 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 d50Installing 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 MBThen 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
Section titled “The blind index”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:
arcsec -f image.fits -i "$(arcsec catalog path)"for /f "delims=" %d in ('arcsec catalog path') do arcsec -f image.fits -i "%d"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:
arcsec catalog index buildKeeping 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.
Where they are stored
Section titled “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_databasessetx ARCSEC_CATALOG_DIR "D:\star_databases"set "ARCSEC_CATALOG_DIR=D:\star_databases"setx ARCSEC_CATALOG_DIR "D:\star_databases"$env:ARCSEC_CATALOG_DIR = "D:\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:
arcsec -f image.fits -i "$(arcsec catalog path)" --fov 3for /f "delims=" %d in ('arcsec catalog path') do arcsec -f image.fits -i "%d" --fov 3arcsec -f image.fits -i (arcsec catalog path) --fov 3If you already have ASTAP
Section titled “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 themarcsec catalog list # confirms what it foundarcsec catalog index build # once: the blind indexsetx ARCSEC_CATALOG_DIR "C:\Program Files\astap"set "ARCSEC_CATALOG_DIR=C:\Program Files\astap"arcsec catalog listarcsec catalog index buildsetx ARCSEC_CATALOG_DIR "C:\Program Files\astap"$env:ARCSEC_CATALOG_DIR = "C:\Program Files\astap"arcsec catalog list # confirms what it foundarcsec catalog index build # once: the blind indexC:\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.
File formats
Section titled “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
Section titled “Building your own”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.