Skip to content

Command line

Terminal window
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.

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 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.

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.

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.

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.

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.

Terminal window
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.

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, CDELT and CROTA), as ASTAP and Astrometry.net write it.

  • <base>.ini: ASTAP’s summary, which imaging software such as N.I.N.A. reads:

    PLTSOLVD=T
    CRPIX1=1.4505000000000E3
    CRPIX2=1.4505000000000E3
    CRVAL1=51.399930729
    CRVAL2=49.850092402
    CDELT1=-3.4481840519016E-4
    CDELT2=3.4484393775396E-4
    CROTA1=-0.0028
    CROTA2=0.0092
    CD1_1=-3.4481840477539E-4
    CD1_2=1.6912616906569E-8
    CD2_1=-5.5529976585669E-8
    CD2_2=3.4484393328298E-4
    CMDLINE=arcsec -f image.fits
    NSTARS=500
    NQUADS=217
    RMS=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 00
Solved in 0.4 sec. Δ was 0.0". Mount Δα=-0.2", Δδ=0.3". Used stars down to magnitude: 14.5

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

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
Variable Meaning
ARCSEC_CATALOG_DIR The catalogue folder, for both arcsec catalog and the solver