npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@spacexr/spatial-label-layout-core

v0.1.5

Published

Renderer-agnostic math, solver and public API for spatial label layout.

Readme

License

@spacexr/spatial-label-layout-core

Free placement of 3D labels around pins attached to meshes, with no rendering dependency. The solver projects billboards into each camera view (one for a desktop, two eyes plus a head pose for WebXR), resolves overlaps there, and returns world positions. Each label keeps its leader to the same pin for its whole life.

Math, solver, public API and integration ports. No dependencies.

Install

npm install @spacexr/spatial-label-layout-core

With Babylon.js, add @spacexr/spatial-label-layout-babylon, which implements the ports below.

Use the engine directly

import { SpatialLabelLayoutEngine, createCameraView } from "@spacexr/spatial-label-layout-core";

const engine = new SpatialLabelLayoutEngine();
engine.setAnchorPosition("summit", { x: 0, y: 2, z: 0 });
engine.addLabel({
  id: "label-summit", anchorId: "summit", position: { x: 0, y: 2, z: 0 },
  dimensions: { width: 1.4, height: 0.4 }, priority: 1, visible: true, enabled: true,
});

const view = createCameraView({ eye: { x: 0, y: 4, z: 9 }, target: { x: 0, y: 1, z: 0 }, viewport: { width: 1280, height: 720 } });
const result = engine.solve({ views: [view], deltaTime: 0.016 });
// result.placements: world positions and visibility
// result.diagnostics: per-view collisions, occlusions, crossings, explicit messages

Use the controller

An application normally goes through LabelLayoutController. It resolves anchors, runs the solver at a reduced rate (10 Hz by default), interpolates positions and pushes billboards and leaders to the renderer at every frame:

import { LabelLayoutController } from "@spacexr/spatial-label-layout-core";

const controller = new LabelLayoutController({ camera, anchors, labelRenderer, leaderRenderer });
renderLoop((deltaSeconds) => controller.tick(deltaSeconds));

The four options are ports an adapter implements for its rendering engine:

| Port | Job | |---|---| | CameraProvider | one view for a mono camera, one per eye in XR, and the reference frame version | | AnchorProvider or MeshResolver | world position of a pin, from a mesh world matrix or a deformed triangle | | LabelRenderer | create, place and hide the label objects | | LeaderRenderer | create and update the leaders, as polylines in the world | | OcclusionProvider (optional) | raycast, depth buffer or both |

BillboardOrienter, SpatialIndex2D, CandidateGenerator, DeclutterStrategy, LeaderRouter and PlacementInterpolator are strategies that can be replaced the same way.

Matrices go in as they are: 16 numbers, column-major, translation at 12, 13 and 14, in a left- or right-handed frame. Vectors are plain { x, y, z } shapes read through their properties, so engine vectors can be passed as they are.

Labels with a constant size on screen

By default dimensions are world units, and a label shrinks on screen as the camera moves away. A label with sizing: "screen" gives its dimensions in pixels instead, which suits maps, globes and any scene whose camera distance varies by orders of magnitude:

engine.addLabel({ id: "city", anchorId: "city", position, dimensions: { width: 120, height: 24 }, sizing: "screen", priority: 1, visible: true, enabled: true });
  • its world size is resolved for each solve, and by the controller for each rendered frame, at the depth of its pin;
  • each solve starts from where the label stood on screen relative to its pin;
  • between two solves the default interpolator holds it at that pixel offset, so it follows the camera through a zoom.

Two engine options go with it: anchorOutOfView: "hide" hides the label of a pin that left every view, and temporal.screenThresholdPx measures camera and pin motion in pixels instead of world units.

A label placed apart from its anchor

A label stands around its anchor by default. With home, a world position, it stands on its home instead when nothing is in the way, and is moved around it where it would cover another label; its leader still ends at the anchor. It shows while its home is in view, and a label sized in pixels takes its size at the depth of its home. Moving the home is an update: engine.updateLabel(id, { home }), and home: undefined takes it away. When the scene hides the anchor while the label stays in view (behind the relief, beyond the horizon), leaderHidden: true keeps the label and draws no leader.

engine.addLabel({ id: "mine", anchorId: "collar", position: home, home, dimensions: { width: 120, height: 24 }, sizing: "screen", priority: 1, visible: true, enabled: true });

Leader routing

straight (default) attaches the leader where the line from the pin meets the border of the label. elbow leaves the pin horizontally, turns vertically and enters the label through a horizontal stub. polyline goes through points the caller gives. Crossings are detected in projection and reduced by swapping label positions, never by reassigning a leader.

More

The pipeline, the objective function, the coordinate conventions and the failure cases are in the architecture notes. What an adapter has to implement is in the porting guide.

License

Apache-2.0