Skip to main content

arcsec_catalogue/
lib.rs

1//! Catalogue management for the [arcsec] plate solver.
2//!
3//! arcsec solves against star databases (ASTAP's D05 … W08) and, for blind solving,
4//! a blind index built from one of them or Astrometry.net index files. This crate is
5//! everything about those files that is not solving:
6//!
7//! - what can be installed, and how to recognise it on disk ([`registry`]);
8//! - where catalogues live ([`default_dir`]) and which database suits a field
9//!   ([`select_db_for_fov`], re-exported from [`arcsec_core::auto`], which the
10//!   solver itself uses);
11//! - downloading and unpacking them (`install`, `fetch`; the `download`
12//!   feature);
13//! - removing and checking them ([`remove`], [`verify`]);
14//! - planning, costing and building arcsec's own blind index ([`index`]).
15//!
16//! Nothing here prints or exits: results and errors are typed. Long operations
17//! (a download, an index build) report through a callback, and stop early when the
18//! thread's [`arcsec_core::cancel`] token is cancelled, as a solve does.
19//!
20//! ```no_run
21//! use arcsec_catalogue::{default_dir, registry, select_db_for_fov};
22//!
23//! let dir = default_dir();
24//! for e in registry::REGISTRY {
25//!     let state = if registry::is_installed(&dir, e) { "installed" } else { "-" };
26//!     println!("{:<10} {:<10} {state}", e.id, e.purpose.label());
27//! }
28//! println!("for a 1.5° field: {:?}", select_db_for_fov(&dir, 1.5));
29//! ```
30//!
31//! # Features
32//!
33//! - `download` (default): `fetch` and `install`, over HTTPS with `ureq` and
34//!   `rustls`, and zip, tar and xz extraction. Without it the crate pulls in no
35//!   network or TLS code; everything else still works.
36//!
37//! The `arcsec` command line is built on this crate; its API follows that user and
38//! may change between minor versions.
39//!
40//! [arcsec]: https://github.com/cruzzil/arcsec
41
42// `alloc` is not in the extern prelude for a crate that links std, so it has to
43// be declared before alloc:: paths can be written.
44extern crate alloc;
45
46mod error;
47#[cfg(feature = "download")]
48pub mod fetch;
49mod format;
50pub mod index;
51#[cfg(feature = "download")]
52mod install;
53mod manage;
54pub mod registry;
55pub mod sys;
56
57/// A temporary directory and a tiny star database, for tests: compiled for this
58/// crate's own tests, and with the `test-support` feature for the command line's.
59/// Not a stable API.
60#[cfg(any(test, feature = "test-support"))]
61#[doc(hidden)]
62pub mod test_support;
63
64pub use error::{Error, Result};
65pub use format::{duration, gigabytes, human_bytes};
66#[cfg(feature = "download")]
67pub use install::{InstallEvent, InstallOptions, Installed, install};
68pub use manage::{
69    CatalogueCheck, IndexCheck, IndexHealth, Problem, Removed, Verification, download_disk,
70    recommend, remove, verify,
71};
72
73/// Where catalogues are kept and the solver looks by default: `$ARCSEC_CATALOG_DIR`,
74/// else the platform's data directory (`~/.local/share/arcsec/catalogs` on Linux).
75/// See [`arcsec_core::auto::default_catalog_dir`] for the full rules. The directory
76/// may not exist yet.
77#[must_use]
78pub fn default_dir() -> std::path::PathBuf {
79    arcsec_core::auto::default_catalog_dir()
80}
81
82/// Choosing a star database. These live in [`arcsec_core::auto`] because a solve
83/// makes the same choice when it is not told; they are re-exported here so that a
84/// program managing catalogues finds them in one place.
85pub use arcsec_core::auto::{
86    ASTAP_EXTS, DB_FOV_RANGES, available_dbs, default_db_path, has_star_database, select_db_for_fov,
87};