Fetch names and labels with sidecars

Learning goal

The render octree streams positions, magnitudes, temperatures, and optional public star refs. Metadata sidecars are separate. Your app bootstraps the render dataset id, derives the matching sidecar URL, creates a sidecar provider, and looks up metadata by StarObjectRef or by semantic cell ref.

This lesson deliberately starts from the Sun and sorts candidates by apparent brightness. Bright naked-eye stars are much more likely to have proper names, Bayer designations, and Flamsteed numbers than a random row from a billion-star dataset.

This is still the visible-star stream from the render provider. It is not a true nearest-star query, so faint neighbours such as Proxima Centauri are not the goal of this particular example.

The label policy in this lesson follows the same shape used by Star Pilot: proper name, Bayer designation plus constellation, Flamsteed plus constellation, HD, HIP, Gaia source id, then a cell/ordinal fallback.

Those labelled rows are still plain JavaScript objects. You can draw them with Canvas, PixiJS, Phaser, SVG, or your own renderer.

Run the notebook to render rows.

Things to try

Change the magnitude limit in step 2 to stream a different visible set.
Change the sort in step 2 to distance to find nearest visible candidates.
Require only proper names in step 3 by changing hasHumanReadableName().
Change which name fields are shown in the final table.
Render extra metadata fields in the final table.

What changed in the code

Step 1 calls ensureBootstrap() on the render provider and requires a dataset id. It then derives the sidecar URL from the render octree URL and creates a metadata provider with the render dataset id as its parent.

Step 2 computes each candidate's distance from the Sun and apparent magnitude, then puts the brightest Sun-view rows first. Step 3 uses getMeta(star.ref) and getMetaCell(...) while walking those candidates, then stops only when the selected star has a proper name, Bayer, or Flamsteed designation. The sidecar provider stays schema-neutral; the app decides what a label should be.

Source and next steps

Star Pilot uses this pattern for hover labels.

Star Pilot derives the render dataset id, opens the matching generated meta sidecar, and uses public StarObjectRef values for lookup. The render stream stays compact; metadata is fetched only when labels or richer facts are needed.

Use this in a browser

For standalone browser examples, use stable, pinned CDN URLs directly. The lesson does not introduce version constants or URL helper functions.

Browser import

import {
  OCTREE_DEFAULT,
  createStarOctreeProviderService,
} from "https://esm.sh/@found-in-space/star-octree-provider@0.2.0?bundle";
import {
  createObserverShellStrategy,
} from "https://esm.sh/@found-in-space/star-trees@0.2.0?bundle";
import {
  createMetaSidecarProviderService,
  deriveMetaSidecarUrlFromRenderUrl,
} from "https://esm.sh/@found-in-space/meta-sidecar-provider@0.2.0?bundle";

Use this locally

Install the data packages and keep the label formatter in your app. The sidecar provider intentionally does not choose display names for you.

Install

npm install @found-in-space/star-octree-provider@0.2.0 @found-in-space/star-trees@0.2.0 @found-in-space/meta-sidecar-provider@0.2.0

Local imports

import {
  OCTREE_DEFAULT,
  createStarOctreeProviderService,
} from '@found-in-space/star-octree-provider';
import {
  createMetaSidecarProviderService,
  deriveMetaSidecarUrlFromRenderUrl,
} from '@found-in-space/meta-sidecar-provider';
import { createObserverShellStrategy } from '@found-in-space/star-trees';