What is near

日本語

@johnmorrisdotca/hoshi-stars/nearest answers "what is next to this?" in three calls. It reads the bright-star table (and the Messier table for kind: "deep-sky"), and the boundaries for the neighbouring constellations.

In the sky

nearest(target, options) gives the nearest first, each { thing, angle } with the angle in degrees. The target is a star, a deep-sky object, a name that starByName or deepSkyObject accepts, or { rightAscension, declination } in degrees. The target is never in its own answer.

import { nearest, within } from "@johnmorrisdotca/hoshi-stars/nearest";

const pair = nearest("Mizar", { count: 3 });
console.log(pair.map((n) => `${n.thing.name ?? n.thing.hr} ${n.angle.toFixed(2)}`));
console.log(within("Alcyone", 1, { magnitude: 5 }).map((n) => n.thing.name));
// [ '5055 0.00', 'Alcor 0.20', '5109 1.52' ]
// [ 'Merope', 'Atlas', 'Maia', 'Electra', 'Taygeta' ]

[ '5055 0.00', 'Alcor 0.20', '5109 1.52' ]
[ 'Merope', 'Atlas', 'Maia', 'Electra', 'Taygeta' ]

Mizar is a double star: the nearest thing is its companion (HR 5055), and Alcor is 0.20 degree away. within(target, radius) is nearest with no limit on the count. The options:

The angle is measured with atan2(|a x b|, a . b) on unit vectors, which stays exact at 0 and at 180 degrees, at the poles and across right ascension 0 and 360. A query over all 5,080 stars takes about 1 millisecond; nothing is indexed.

In space

With by: "space" each star is placed from its parallax, and the answer is { thing, distance, parsecs, error }: the straight-line distance in light-years and in parsecs.

import { nearest } from "@johnmorrisdotca/hoshi-stars/nearest";

const close = nearest("Sirius", { by: "space", count: 2 });
console.log(close.map((n) => `${n.thing.name} ${n.distance.toFixed(1)}`));
console.log(close.skipped, close[0].error);
// [ 'Procyon 5.1', 'Ran 8.0' ]
// 2547 undefined

[ 'Procyon 5.1', 'Ran 8.0' ]
2547 undefined

• Only this catalogue. The answers cover the 2,533 of the 5,080 stars that have a parallax; Sirius's nearest neighbour here is Procyon, though fainter, closer stars exist that are not in the table. Pass among: [...stars(), ...nearbyStars()] to count the 5,565 stars of Nearby stars too: Proxima Centauri, Barnard's Star and the red dwarfs.
• skipped is how many candidates had no usable distance (a parallax of 0 or less, or a deep-sky object) and were left out.
• error is undefined: the Yale catalogue gives each parallax to a whole milliarcsecond and no error, so none can be worked out. A distance is good to a few per cent within 100 light-years and not at all for a faint, far star.
• The target needs a distance: a star with a parallax, { rightAscension, declination, lightYears }, or a point { x, y, z } in parsecs on the J2000 equatorial axes with the Sun at the origin.

Constellations that touch

import { neighbouringConstellations } from "@johnmorrisdotca/hoshi-stars/nearest";

console.log(neighbouringConstellations("Orion").map((c) => c.abbreviation));
// [ 'Eri', 'Gem', 'Lep', 'Mon', 'Tau' ]

[ 'Eri', 'Gem', 'Lep', 'Mon', 'Tau' ]

Two constellations are neighbours when they share a piece of boundary; meeting at a corner does not count. The table is worked out from the IAU boundaries the first time it is needed (a few milliseconds) and kept. The answer is in the alphabetical order of the Latin names.