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.

Captured-image geometry uses SkyFootprint values built from a solved centre, ordered sky boundary, solved sky position angle, image parity, and evidence identity. Pair comparison reports intersection over the smaller footprint, centre separation relative to the smaller diagonal, transported sky-axis rotation, and parity. FootprintUnion preserves disconnected captured regions and interior gaps for point, footprint, and sampled-ellipse coverage queries. The crate reports measurements and does not apply session or mosaic policy.

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

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

This project is licensed under the Mozilla Public License 2.0 — see LICENSE for details.

You can use this library in closed-source projects. If you modify any of the source files in this library, the modified files must be made available under the MPL-2.0 when distributed.

§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.
footprint — solved sky-boundary comparison, residual-rotation coverage intervals, and hole-aware captured unions.
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.
footprint: Captured sky-footprint comparison and union geometry.
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§

ComponentCoverageEvidence: Area evidence for one disconnected captured-union component.
Constraint: A Membership shape combined with a Query mode (and the plate scale, when known, so pixel offsets can be reported).
CoverageBand: Inclusive normalized-coverage band supplied by the caller.
Field: The angular extent of a frame.
FootprintComparison: Measured relationship between two captured footprints.
FootprintProvenance: Opaque caller-supplied identity for the evidence behind a footprint.
FootprintUnion: Hole-aware union of captured footprints on one persisted gnomonic plane.
Match: A ranked match: a borrowed catalogue object plus its computed geometry.
Matcher: A prebuilt, declination-sorted index for repeated queries against one catalogue.
ObjectCoverageEvidence: Measured object coverage and its component/panel evidence.
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.
PanelContainmentEvidence: Point-containment evidence for one input panel.
PanelCoverageEvidence: Area evidence for one input panel.
PointContainmentEvidence: Point-containment result for the captured union.
RotationInterval: Closed residual-rotation interval whose coverage lies inside a band.
RotationSearch: Caller-controlled numerical search domain for coverage rotation intervals.
SkyEllipse: A tangent-plane ellipse on the sky.
SkyFootprint: An ordered solved image boundary on the sky.

Enums§

Containment: Position of a point relative to a footprint union or one of its members.
CoverageState: Captured-union coverage state for an object.
Error: Everything that can go wrong constructing target-match values.
ImageParity: Whether a solved image transform preserves or mirrors handedness.
Membership: The shape that decides whether an object is “in frame”.
ObjectShape: Caller-supplied object geometry to measure against a captured union.
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§

compare_footprints: Compare two footprints on their deterministic common plane.
coverage_at_residual_rotation: Measure normalized coverage at a caller-supplied residual sky rotation.
coverage_rotation_intervals: Find closed residual-rotation intervals whose coverage lies in band.
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>.