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-babylon

v0.1.5

Published

Babylon.js adapter for spatial label layout: camera views, renderers that place the application's own 3D label objects and their leaders, render loop hook, and the SPACEXR_label glTF extension.

Readme

License

@spacexr/spatial-label-layout-babylon

Babylon.js adapter for @spacexr/spatial-label-layout-core: it gives the solver the views of the camera, and places the 3D objects of the application where the layout puts their labels, with a leader from each to its pin.

The labels are objects the application builds itself: an extruded tag, a textured plane, a group of meshes. The adapter writes their position, orientation and scaling. It draws no text of its own.

Install

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

@babylonjs/core 9 is a peer dependency. @babylonjs/loaders and @babylonjs/serializers are optional ones, needed only to read and to write glTF labels.

Use

import { BabylonLabelLayout } from "@spacexr/spatial-label-layout-babylon";

const layout = new BabylonLabelLayout({
  scene,
  labels: {
    // Called once per label: returns the object that shows it, with its local size.
    create: (label) => ({ node: buildMyTag(label), width: 2, height: 0.8, front: "+z" }),
  },
  leaders: { width: 1.5 }, // pixels
});

layout.engine.setAnchorPosition("summit", { x: 0, y: 2, z: 0 });
layout.controller.addLabel({
  id: "label-summit", anchorId: "summit", position: { x: 0, y: 2, z: 0 },
  dimensions: { width: 120, height: 48 }, sizing: "screen",
  priority: 1, visible: true, enabled: true,
});

The layout advances before each render of the scene. An application that runs its own frame loop passes autoTick: false and calls layout.tick() once the camera of the frame is set. layout.dispose() releases the label objects and the leaders.

Label objects

create returns a BabylonLabelNode:

| Member | Meaning | |---|---| | node | A TransformNode with no parent that moves it. Its local x axis reads to the right, its local y axis upward. | | width, height | Its size along local x and y, before scaling, in any unit. The adapter scales the node so that this size shows as the size the layout gives. | | front | Local z direction the readable face looks toward: "-z" (default, as the planes Babylon.js builds) or "+z". | | dispose | Releases what the node owns. Default: node.dispose(). |

The node is oriented from the axes the layout measured the label with, not from a billboard mode of the engine, so the quad drawn is the quad solved. Leave billboardMode at 0 on it.

Leaders

A leader is a polyline in the world, pin first. Each segment is a thin cylinder, so straight, elbow and polyline routes are all drawn, with a width in pixels (widthUnit: "screen", the default here) or in world units. material gives a material per leader, and configure is applied once to each segment mesh (rendering group, metadata).

Camera

BabylonCameraProvider reads the active camera of the scene, or the one given as camera. The viewport is in CSS pixels by default (pixels: "css"), and so is every pixel quantity of the layout: screen-sized labels, paddingPx, leaderLengthPx. pixels: "render" uses the pixels of the render target.

View matrices are read as they are in left- and right-handed scenes, and in scenes with floating origin (large world rendering), whose view matrix holds the true world position.

A camera with rig cameras (WebXR, stereoscopic rigs) gives one view per rig camera, with the rig parent as reference view. Call bumpReferenceFrame() on the provider when an XR session starts or ends. This path has not run in a headset yet.

glTF labels: SPACEXR_label

A glTF node may declare itself a label. The package reads the extension, writes it, and presents the nodes that carry it.

"SPACEXR_label": {
  "facing": "screen",
  "size": { "referenceHeight": 0.35, "pixels": 14 },
  "overlay": true,
  "leader": { "color": [0.87, 0.47, 0.01], "width": 1.6, "anchorRadius": 6 },
  "priority": 1
}

A label is an object made to be read. The origin of its node is where it stands. The point it names, its anchor, is given by anchor: a position in the frame of the parent of the node, as the translation of the node, on the ground the client displays when ground is given. A leader links the label to its anchor. With leader and no anchor, the anchor is the origin of the node, as before version 0.6 of the GeoModels v2 specification; a label with neither names nothing but its own place and has no leader. It reads along its local +X axis, its height along +Y, its face toward +Z. Every property is optional.

| Property | Role | |---|---| | facing | screen: the label stays parallel to the screen. Without it, it keeps the orientation of the glTF. | | size | The length referenceHeight of its local +Y axis takes pixels CSS pixels on screen. Without it, its size is metric. | | overlay | The label is drawn over the rest of the scene, never occluded. | | leader | The style of the line that links the label to its anchor. Without anchor, it also makes the origin of the node the anchor. | | anchor | The point the label names: position in the frame of the parent of the node, and ground ({ offset }) to stand it on the displayed ground. | | priority | Labels of higher priority move less and are hidden last. Defaults to 1. |

leader.color is linear RGB, white by default; leader.width is in pixels, 1.5 by default; leader.anchorRadius is the radius in pixels of the mark drawn on the anchor, 0 by default for no mark. The extension is listed in extensionsUsed and never in extensionsRequired: a client that does not know it shows the node with the transform written in the glTF.

Reading, with @babylonjs/loaders:

import "@babylonjs/loaders/glTF/2.0/index.js";
import { LabelRuntime } from "@spacexr/spatial-label-layout-babylon";
import { registerSpaceXrLabelLoader } from "@spacexr/spatial-label-layout-babylon/gltf-loader";

registerSpaceXrLabelLoader();
const labels = new LabelRuntime(scene, { hides, layout });

The loader declares the label on the Babylon node it creates and attaches the node to the LabelRuntime of the scene it loads into. A scene has one runtime at most; without one, the declaration is kept and the node is not presented. layout holds settings of the layout engine, merged over the defaults: the length of the leaders, the gap between labels, the routing of the leaders. hides(anchor, eye) tells when the scene hides an anchor, the far side of a globe for instance: the label and its leader are then hidden.

Writing, with @babylonjs/serializers:

import { setNodeLabel } from "@spacexr/spatial-label-layout-babylon";
import { registerSpaceXrLabelExporter } from "@spacexr/spatial-label-layout-babylon/gltf-exporter";

registerSpaceXrLabelExporter();
setNodeLabel(node, { facing: "screen", size: { referenceHeight: 0.35, pixels: 14 }, overlay: true, leader: { anchorRadius: 6 } });

An application that holds its own copy of Babylon.js passes its GLTFExporter to registerSpaceXrLabelExporter.

How the runtime presents a label:

  • Anchor. The node is the anchor and is never moved: something else may place it, on the ground for instance. What the node holds is put under a body node, which the runtime turns, scales and moves.
  • Facing. A label that faces the screen looks along the axis of the camera, toward the viewer, not at the position of the camera: labels are parallel to one another, and two neighbours never cut through each other. In a headset, where the plane of the screen turns with the head, the label faces the head.
  • Size. The label is scaled by pixels × m / H: H is the reference height in the scene with the authored scale, m the length a CSS pixel covers at the view depth of the anchor.
  • Overlay. The meshes of the label go to a rendering group drawn last on a cleared depth buffer. Overlays are drawn back to front, the depth buffer cleared between two of them: each one covers those behind it, and its own parts still hide one another.
  • Leader. A label with an anchor is handed to a BabylonLabelLayout. It stands on its node when nothing is in the way, is moved around it where it would cover another label, the least important ones hidden where they cannot all fit, and the leader is drawn to the anchor. The runtime draws the anchor mark, and stands an anchor with ground on the ground the ground option of LabelRuntime gives. An anchor the scene hides (the hides option) takes its leader and its mark away; the label stays while its own place shows.

Limits: a label with a leader always faces the screen, since the layout places a rectangle of the screen; leaders share one width, that of the first label that has one; a mesh shared by several nodes is one Babylon mesh with instances, drawn in one rendering group; in a headset, how a pixel maps to an angle of view is not settled.

The pieces

BabylonLabelLayout builds the three ports and a controller. They can be used on their own with a LabelLayoutController of the core:

  • BabylonCameraProvider (CameraProvider)
  • BabylonLabelRenderer (LabelRenderer)
  • BabylonLeaderRenderer (LeaderRenderer)

License

Apache-2.0