Skip to main content

Crate arcsec_catalogue

Crate arcsec_catalogue 

Source
Expand description

Catalogue management for the arcsec plate solver.

arcsec solves against star databases (ASTAP’s D05 … W08) and, for blind solving, a blind index built from one of them or Astrometry.net index files. This crate is everything about those files that is not solving:

  • what can be installed, and how to recognise it on disk (registry);
  • where catalogues live (default_dir) and which database suits a field (select_db_for_fov, re-exported from arcsec_core::auto, which the solver itself uses);
  • downloading and unpacking them (install, fetch; the download feature);
  • removing and checking them (remove, verify);
  • planning, costing and building arcsec’s own blind index (index).

Nothing here prints or exits: results and errors are typed. Long operations (a download, an index build) report through a callback, and stop early when the thread’s arcsec_core::cancel token is cancelled, as a solve does.

use arcsec_catalogue::{default_dir, registry, select_db_for_fov};

let dir = default_dir();
for e in registry::REGISTRY {
    let state = if registry::is_installed(&dir, e) { "installed" } else { "-" };
    println!("{:<10} {:<10} {state}", e.id, e.purpose.label());
}
println!("for a 1.5° field: {:?}", select_db_for_fov(&dir, 1.5));

§Features

  • download (default): fetch and install, over HTTPS with ureq and rustls, and zip, tar and xz extraction. Without it the crate pulls in no network or TLS code; everything else still works.

The arcsec command line is built on this crate; its API follows that user and may change between minor versions.

Modules§

fetch
Downloading and unpacking catalogues: resumable HTTPS downloads, and zip and .deb (ar, tar, xz) extraction that cannot write outside its destination.
index
arcsec’s own blind index: which one to build for the databases installed, what it will cost, whether the one there is current, and building it. See docs/offline-index.md in the arcsec repository.
registry
Every catalogue arcsec knows how to install, and how to recognise its files on disk.
sys
What the machine has to spare: free disk space and memory, for the checks made before building a blind index or downloading a catalogue.

Structs§

CatalogueCheck
verify’s finding for one installed catalogue.
IndexCheck
verify’s finding for one blind index file.
InstallOptions
Options for install.
Installed
What install installed.
Removed
What remove removed.
Verification
What verify found in a directory.

Enums§

Error
A catalogue operation that failed. The Display text is a complete sentence fragment naming the file or download concerned, fit to show a user.
IndexHealth
The state of a blind index file.
InstallEvent
What install reports while it runs, in order.
Problem
Something wrong with an installed catalogue.

Constants§

ASTAP_EXTS
Choosing a star database. These live in arcsec_core::auto because a solve makes the same choice when it is not told; they are re-exported here so that a program managing catalogues finds them in one place. File extensions of the star database formats, with the number of sky cells each layout has: .1476 and .290 tile the sky, .001 is one all-sky file.
DB_FOV_RANGES
Choosing a star database. These live in arcsec_core::auto because a solve makes the same choice when it is not told; they are re-exported here so that a program managing catalogues finds them in one place. Field-of-view range each ASTAP database is built for, and how much we prefer it when several are eligible (higher = denser, so a better fit).

Functions§

available_dbs
Choosing a star database. These live in arcsec_core::auto because a solve makes the same choice when it is not told; they are re-exported here so that a program managing catalogues finds them in one place. Every database prefix present in db_path, in any supported format, sorted.
default_db_path
Choosing a star database. These live in arcsec_core::auto because a solve makes the same choice when it is not told; they are re-exported here so that a program managing catalogues finds them in one place. The star database directory to use when none is named.
default_dir
Where catalogues are kept and the solver looks by default: $ARCSEC_CATALOG_DIR, else the platform’s data directory (~/.local/share/arcsec/catalogs on Linux). See arcsec_core::auto::default_catalog_dir for the full rules. The directory may not exist yet.
download_disk
Disk an install of e needs at its peak: an archive and its extracted files side by side (assumed no smaller than the archive), or the loose files.
duration
A duration rounded the way a person would say it: under 10 s, ~20 s, ~13 min, ~1 h 30 min.
gigabytes
0.6 GB, or 90.0 MB below 0.1 GB.
has_star_database
Choosing a star database. These live in arcsec_core::auto because a solve makes the same choice when it is not told; they are re-exported here so that a program managing catalogues finds them in one place. Whether dir holds any of the star databases arcsec knows (D05 … W08), judged by the file each ships for its first cell (d50_0101.1476, w08_0101.001, …).
human_bytes
Bytes, in decimal units, to one decimal place: 901.3 MB.
install
Download catalogue e into dir (created if need be) and unpack it there, reporting progress to on_event.
recommend
The catalogue to suggest for purpose and a field fov_deg degrees across: the smallest download whose published range covers the field, so the advice does not push a gigabyte on someone who does not need it. None if none covers it.
remove
Delete every file of catalogue e from dir. Blind indexes built from it are not touched; see crate::index::indexes_removed_with.
select_db_for_fov
Choosing a star database. These live in arcsec_core::auto because a solve makes the same choice when it is not told; they are re-exported here so that a program managing catalogues finds them in one place. Pick the installed database best suited to a fov_deg field (the longer side, degrees): the densest whose published range contains it, else the nearest. None when db_path holds no star database at all.
verify
Check that every catalogue installed in dir looks structurally sound: no truncated files and the right number of them, and every blind index readable, intact and built from the database now installed.

Type Aliases§

Result
A catalogue operation’s result.