Crate target_match

Expand description

§target-match

Rust library that identifies which catalogued sky objects a telescope frame covers, given a pointing (right ascension / declination) and a field of view.

Matching is by angular position; object names are never used as search keys (a designation can be carried on a result for display). The crate holds no catalogue data and performs no I/O: callers supply objects by implementing the one-method SkyObject trait, and the library computes the geometry — angular separation, in-frame Membership (a fast circular radius that approximates the frame, or the exact rectangle, with optional camera rotation), tangent-plane Offsets, and deterministic ranking.

The field of view can be computed from Optics (focal length, pixel size, binning, sensor dimensions), from a pixel scale, or supplied directly via Field. Each Field constructor is fallible: non-positive or non-finite inputs return Error::InvalidOptics (the snippets below .unwrap() on known-good values). Matching itself is infallible once inputs are valid. Pointings at any epoch are precessed to J2000 before matching.

Coordinate and angle types come from the skymath crate and appear directly in this crate’s API (skymath::Equatorial, skymath::Angle — with decimal and strict/lenient sexagesimal parsing); skymath is re-exported as target_match::skymath so a version-matched copy is always available.

API documentation, generated from the source on every release: docs.rs/target-match. For a task-oriented walkthrough, see the guide module.

§Usage

[dependencies]
target-match = "0.3"

use skymath::{Angle, Equatorial, ParseMode};
use target_match::{rank, Constraint, Field, Optics, RadiusPolicy, SkyObject};

// Your catalogue type — target-match owns no catalogue data, and never reads the name.
struct Target { name: &'static str, ra_deg: f64, dec_deg: f64 }
impl SkyObject for Target {
    fn position(&self) -> Equatorial {
        Equatorial::j2000(Angle::from_degrees(self.ra_deg), Angle::from_degrees(self.dec_deg)).unwrap()
    }
}

let catalog = [
    Target { name: "M 31", ra_deg: 10.6847, dec_deg: 41.2688 },
    Target { name: "M 33", ra_deg: 23.4621, dec_deg: 30.6599 },
];

// Where the scope pointed (decimal degrees or sexagesimal)...
let pointing = Equatorial::parse_j2000("00:42:44.3", "+41:16:09", ParseMode::Strict).unwrap();

// ...and how much sky the frame covers (from optics, a pixel scale, or a direct FOV).
let field = Field::from_optics(Optics {
    focal_mm: 800.0, pixel_um: (3.76, 3.76), binning: (1, 1), pixels: (6248, 4176),
}).unwrap();

// Nearest catalogued object within the frame's search radius. `within` uses a
// circular approximation (here the circumscribed circle, half the diagonal); for
// the exact sensor rectangle use `Constraint::frame(&field)`.
let hits = rank(pointing, &catalog, Constraint::within(&field, RadiusPolicy::Circumscribed).nearest_one());
assert_eq!(hits[0].object.name, "M 31");

Each hit is a Match carrying the borrowed object, its separation, in-frame flag, offset, and position angle. The Query mode on the constraint selects all-within-field, nearest-one, or nearest-N. To test a single object without ranking a catalogue, call is_framed.

For a batch of frames against one catalogue, build the index once with Matcher::from_objects(..) and call .query(pointing, constraint) repeatedly. See examples/identify.rs for a runnable end-to-end demo, and the guide module for a task-oriented walkthrough.

§Features

serde (off by default) — derives Serialize/Deserialize on the public match types, and forwards to skymath/serde for the coordinate types they embed.

§Development

Requires a stable Rust toolchain (pinned via rust-toolchain.toml) and, optionally, just.

just verify   # fmt-check + clippy (-D warnings) + tests
just test
just doc

§License

Licensed under the Apache License, Version 2.0.

§Modules

optics — plate scale and field-of-view geometry from focal length, pixel size (x/y), binning (x/y), and sensor dimensions — or a directly supplied pixel scale / field of view — plus the search-radius policies.
matcher — the SkyObject input trait, match constraints (radius, rectangular field of view, nearest-N), and deterministic ranking.
guide — a task-oriented walkthrough, from implementing SkyObject through repeated queries with Matcher.

Re-exports§

pub use skymath;

Modules§

error: Error type for target-match.
guide: A task-oriented walkthrough of target-match, from implementing SkyObject through repeated queries with Matcher. Source: docs/guide.md.
matcher: The matching engine: input trait, constraints, ranking, and a prebuilt index.
optics: Plate scale and field-of-view geometry.

Structs§

Constraint: A Membership shape combined with a Query mode (and the plate scale, when known, so pixel offsets can be reported).
Field: The angular extent of a frame.
Match: A ranked match: a borrowed catalogue object plus its computed geometry.
Matcher: A prebuilt, declination-sorted index for repeated queries against one catalogue.
Offset: The offset of a matched object relative to the frame centre.
Optics: Full optical train: focal length, per-axis pixel size, per-axis binning, and sensor pixel counts.

Enums§

Error: Everything that can go wrong constructing target-match values.
Membership: The shape that decides whether an object is “in frame”.
Query: What to return from a match.
RadiusPolicy: How a search radius is derived from a Field.

Constants§

ARCSEC_PER_DEGREE: Arcseconds per degree.
ARCSEC_PER_RADIAN: Exact number of arcseconds in one radian (supersedes the rounded 206.265).
DEFAULT_FALLBACK_RADIUS: Fallback search radius when a field of view cannot be derived (5°).

Traits§

SkyObject: A catalogue object that can be matched by sky position.

Functions§

is_framed: Evaluate a single object against a frame, returning its membership + geometry.
rank: Rank a slice of objects against a pointing under a constraint (stateless scan).

Type Aliases§

Result: Convenience alias for Result<T, Error>.