Command line
arcsec -f <image> [options]arcsec catalog <command> [options]arcsec mirrors the command line of ASTAP’s astap_cli: the same options, the same
report on stdout, the same output files and the same exit codes. arcsec --help lists
everything below.
Solving options
Section titled “Solving options”| Option | Meaning | Default |
|---|---|---|
-f <file> |
Image to solve: FITS, XISF, ASDF, JPEG, PNG or TIFF, recognised from the file’s contents | required |
-r <deg> |
Radius of the area to search around the start position, in degrees | 180 (whole sky) |
--fov <deg> |
Field height in degrees; 0 or absent to take it from the header |
from header |
--fov-search |
If nothing solves at the given field size, try ¼ to 4× it near the start position before giving up (arcsec only) | off |
--ra <hours> |
Right ascension of the search centre, in hours | from header |
--spd <deg> |
South pole distance of the search centre (90 + Dec), in degrees | from header |
-s <n> |
Maximum number of stars to use | 500 |
-t <tol> |
Quad matching tolerance, at most 0.1 | 0.007 |
-m <arcsec> |
Minimum star size (HFD), in arcseconds | 1.5 |
-z <factor> |
Downsample (bin) the image by this factor before solving; 0 or absent for automatic |
automatic |
-d <dir> |
Star database folder | the catalogue folder if it holds a database, else the current folder |
-D <name> |
Star database to use: d80, d50, d20, d05, v50, v05, g05, w08 |
chosen by field size |
-o <base> |
Base path for the output files | the image path without its extension |
-i, --index <path> |
Blind index: arcsec’s own (<name>.arcsecix, or the catalogue folder holding it), or Astrometry.net index-*.fits files. See blind solving |
off; arcsec’s index is used by itself for searches of 10° or more |
--threads <n> |
Maximum worker threads; 0 for one per core. 1 runs single-threaded |
0 |
--method <m> |
Matching method: quads, or the experimental tetra (three-star triangles) |
quads |
--speed <mode> |
Search mode: auto, or slow, which reads twice the field at every search position for more overlap |
auto |
--sip [y|n] |
Add third-order SIP distortion terms to the .wcs file (and the header with --update) when the field shows significant distortion |
off |
--check [y|n] |
Even out a raw one-shot-colour (Bayer) image before solving; for unbinned raw colour frames only | off |
--wcs |
Accepted for compatibility; the .wcs file is always written |
|
--update |
Write the solution into the input FITS file’s header | off |
--log |
Write the solver log to <base>.log |
off |
--progress |
Log every step to stderr | off |
-h, --help |
Print help | |
-V, --version |
Print the version |
ASTAP spellings
Section titled “ASTAP spellings”ASTAP writes its multi-letter options with a single dash, and arcsec accepts those
spellings too, so an astap_cli command line works unchanged:
-fov, -ra, -spd, -check, -sip, -speed, -wcs, -log, -update,
-progress, -analyse, -extract, -extract2
-fov 1.2 and --fov 1.2 mean the same. Options not in that list, such as
--threads, --method and --index, are arcsec’s own and take two dashes.
Star analysis and export
Section titled “Star analysis and export”These follow ASTAP’s output exactly, so tools that call astap_cli for star
measurements (focus and filter-offset utilities, for example) can use arcsec instead.
| Option | What it does |
|---|---|
--analyse <snr> |
Measure without solving: prints HFD_MEDIAN= and STARS=, writes no .ini or .wcs and needs no catalogue. 0 means an SNR of 30 |
--extract <snr> |
As --analyse, and writes every star to <image>.csv (x,y,hfd,snr,flux,ra[0..360],dec[0..360]; RA/Dec only if the header already holds a WCS). As in ASTAP the CSV goes next to the image whatever -o says |
--extract2 <snr> |
Solve (with SIP), then write the same CSV with every star’s RA and Dec, whether or not the solve succeeded |
Where arcsec differs from ASTAP, deliberately: --extract alone prints the real median
HFD (ASTAP prints 21.5), a bare --check turns the filter on (as ASTAP’s help says it
should), and SIP terms are added only when the distortion is statistically significant.
Position and scale from the header
Section titled “Position and scale from the header”Without --ra/--spd, arcsec takes the start position from the image’s RA and DEC
keywords (in degrees), falling back to CRVAL1/CRVAL2. Without --fov, it works out
the pixel scale from FOCALLEN (mm), XPIXSZ (µm) and XBINNING. If neither is
available, arcsec says so on stderr and searches for the scale: it tries 17 scales from
0.25″ to 64″ per pixel (√2 apart, nearest 1″ first) within one field of the start
position, then searches the whole radius at 1″ per pixel. Giving --fov is still
faster. A --fov you give is used as given; add --fov-search to let a solve that finds
nothing at it try a quarter to four times the field.
When the solved scale differs from the starting one by more than 5%, arcsec prints
astap_cli’s Warning scale was inaccurate! Set FOV=…d, scale=…" after the solution and
writes it to the .ini as WARNING. XISF files carry the same keywords; ASDF files are
read from their metadata tree. JPEG, PNG and TIFF files carry neither a position nor a
scale that arcsec reads, so give --ra/--spd (or have a blind index) and, for speed,
--fov.
Automatic binning
Section titled “Automatic binning”When the image is sampled finer than 1″ per pixel and -z is absent or 0, arcsec
bins it back to about 1″ per pixel before solving, up to 16×. The solution is always
reported in the original image’s pixels.
Blind solving
Section titled “Blind solving”arcsec’s blind index is built from the installed star catalogue: arcsec catalog install builds it, or arcsec catalog index build for catalogues installed otherwise
(see the catalogue guide). With -i naming it, or
the catalogue folder that holds it, arcsec finds the field with no position hint, and
with no pixel scale if neither --fov nor the header gives one; the result is then
verified against the star catalogue like any other solve.
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)Without -i, a search of -r 10° or more that reaches past five fields round the
position (N.I.N.A.’s blind solve sends -r 180) uses the installed index once those
five fields have failed. If none is installed, arcsec prints a one-line hint on the
error output saying how to build one; the solve and its output are otherwise the same.
-i also takes Astrometry.net index files: one file or a folder of index-*.fits, of
which arcsec picks those whose scale suits the field. They only estimate the position,
which is then refined against the star catalogue. The anet-4100 set covers fields of
about 0.7° and wider; for narrower fields, the anet-5200 set is an 8.8 GB download.
Output files
Section titled “Output files”On a successful solve arcsec writes, next to the image or at -o <base>:
-
<base>.wcs: the solution as a FITS header (CRVAL,CRPIX,CD,CDELTandCROTA), as ASTAP and Astrometry.net write it. -
<base>.ini: ASTAP’s summary, which imaging software such as N.I.N.A. reads:PLTSOLVD=TCRPIX1=1.4505000000000E3CRPIX2=1.4505000000000E3CRVAL1=51.399930729CRVAL2=49.850092402CDELT1=-3.4481840519016E-4CDELT2=3.4484393775396E-4CROTA1=-0.0028CROTA2=0.0092CD1_1=-3.4481840477539E-4CD1_2=1.6912616906569E-8CD2_1=-5.5529976585669E-8CD2_2=3.4484393328298E-4CMDLINE=arcsec -f image.fitsNSTARS=500NQUADS=217RMS=0.9949
When a solve fails, <base>.ini is still written, holding only PLTSOLVD=F and the
command line, as ASTAP does; software that waits for the .ini relies on it. It is
not written when arcsec stops before trying to solve: an unreadable image (exit
code 16) or a mistake on the command line.
With --update, arcsec also writes the solution into the image’s own FITS header,
in place, first removing any PC matrix and SIP terms an earlier solve left there, so
the header describes only the new solution. This is FITS only; for any other input
it prints a warning and writes the .wcs and .ini files as usual. With --log, it writes the step-by-step log that
--progress prints to <base>.log.
The report on stdout follows ASTAP’s layout, ending with the solved centre:
Solution found: 03: 25 36.0 +49d 51 00Solved in 0.4 sec. Δ was 0.0". Mount Δα=-0.2", Δδ=0.3". Used stars down to magnitude: 14.5Exit codes
Section titled “Exit codes”The same as ASTAP’s:
| Code | Meaning |
|---|---|
0 |
Solved |
1 |
No solution. Also a command-line usage error, or an ASTAP option arcsec does not implement |
2 |
Not enough stars detected |
16 |
Image file error: missing, unreadable or not a recognised format |
32 |
Star database or index files not found |
33 |
Star database read error |
Catalogue commands
Section titled “Catalogue commands”arcsec catalog installs and manages star catalogues. See the
catalogue guide for which to choose.
| Command | What it does |
|---|---|
arcsec catalog list |
Show every catalogue and whether it is installed |
arcsec catalog path |
Print the catalogue folder |
arcsec catalog recommend --fov <deg> |
Suggest catalogues for a field size |
arcsec catalog recommend --like <image> |
Suggest catalogues, reading the field size from an image header |
arcsec catalog install <name>... |
Download and unpack catalogues, e.g. d50 v05 g05, and build the blind index from a solving catalogue |
arcsec catalog remove <name>... |
Delete installed catalogue files, and the blind index built from them |
arcsec catalog verify |
Check installed catalogues for missing or truncated files, and the blind index for damage or a changed source |
arcsec catalog index build |
Build the blind index from the installed catalogues |
arcsec catalog index info |
Describe the blind index: source, fields, tiers, size |
Options:
| Option | Applies to | Meaning |
|---|---|---|
--dir <dir> |
all | Catalogue folder. Default: ARCSEC_CATALOG_DIR, else the per-platform folder |
--photometry |
recommend |
Also suggest a photometric catalogue |
-y, --yes |
install, remove, index build |
Do not ask for confirmation (index build asks only before a large build) |
--keep-archive |
install |
Keep the downloaded archive after unpacking |
--no-index |
install |
Do not build the blind index |
--index-min-fov <deg> |
install |
Smallest field (short side) the blind index serves; default from the catalogues, e.g. 0.3 for D80. 0.15 reaches D80’s narrowest fields |
--index-max-fov <deg> |
install |
Largest field the blind index serves; default 30, or 80 with W08 |
--keep-index |
remove |
Keep the blind index built from a removed catalogue |
--min-fov, --max-fov <deg> |
index build |
As --index-min-fov and --index-max-fov |
-D <name>, --db <dir>, -o <file> |
index build |
Build from a particular catalogue or folder, or to another file |
--threads <n> |
index build |
Worker threads; 0 for one per core |
Environment
Section titled “Environment”| Variable | Meaning |
|---|---|
ARCSEC_CATALOG_DIR |
The catalogue folder, for both arcsec catalog and the solver |