Points

What is a Point3D?

A Point3D renders as a sphere at a specific 3D position. Points are the most basic visual element and are commonly used for:

Marking specific locations in space
Representing vertices of shapes
Creating interactive handles
Tracing paths along curves

Basic Usage

const point = scene.create("point3d", {
  coords: vec3(1, 2, 3),
  color: "crimson",
  radius: 2,
});

Styling Points

Color

Any CSS color string works:

scene.create("point3d", { coords: vec3(0, 0, 0), color: "red" });
scene.create("point3d", { coords: vec3(1, 0, 0), color: "#ff6b6b" });
scene.create("point3d", { coords: vec3(2, 0, 0), color: "rgb(255, 107, 107)" });
scene.create("point3d", { coords: vec3(3, 0, 0), color: "hsl(0, 100%, 70%)" });

Size

The radius property controls the visual size:

scene.create("point3d", { coords: vec3(0, 0, 0), radius: 1 });  // Small
scene.create("point3d", { coords: vec3(2, 0, 0), radius: 3 });  // Medium
scene.create("point3d", { coords: vec3(4, 0, 0), radius: 5 });  // Large

Examples

Labeled Point

A draggable point with an overlay that displays its coordinates:

const point = scene.create("point3d", {
  coords: vec3(2, 1, 0),
  color: "gold",
  radius: 3,
});

scene.create("overlay3d", {
  position: point.coords,
  content: scene.atom((get) => {
    const { x, y, z } = get(point.coords);
    return `(${x.toFixed(1)}, ${y.toFixed(1)}, ${z.toFixed(1)})`;
  }),
  anchor: "bottom-left",
  offset: vec2(8, -8),
});

Drag the point and the label updates automatically.

Mirrored Point

A second point whose position is derived from the first:

const point = scene.create("point3d", {
  coords: vec3(2, 1, 0),
  color: "gold",
});

// Mirror across the origin
scene.create("point3d", {
  coords: scene.atom((get) => {
    const { x, y, z } = get(point.coords);
    return vec3(-x, -y, -z);
  }),
  color: "skyblue",
});

Drag the gold point and the blue one moves to the opposite position.

Updating Properties

Access the atom fields on the returned item to update properties:

const point = scene.create("point3d", {
  coords: vec3(0, 0, 0),
  color: "red",
  radius: 2,
});

// Update properties
point.coords.set(vec3(5, 5, 5));
point.color.set("blue");
point.radius.set(4);

Dragging

Points are draggable by default. Users can click and drag a point to move it around in 3D space. The draggable property controls which axes the point can move along:

// Free movement (default)
scene.create("point3d", { coords: vec3(0, 0, 0), draggable: "xyz" });

// Constrain to the xz-plane (horizontal movement only)
scene.create("point3d", { coords: vec3(0, 0, 0), draggable: "xz" });

// Constrain to the y-axis (vertical only)
scene.create("point3d", { coords: vec3(0, 0, 0), draggable: "y" });

// Disable dragging
scene.create("point3d", { coords: vec3(0, 0, 0), draggable: "none" });

The cursor changes to a grab icon when hovering over a draggable point.

Dragging only works when coords is a writable atom. If you pass a derived (read-only) atom, dragging is automatically disabled.

You can also listen for drag, click, and hover events. See Interactions for details.

API Reference

Options

Property	Type	Default	Description
`coords`	`Vec3`	`{ x: 0, y: 0, z: 0 }`	Position in 3D space
`color`	`string`	`"white"`	CSS color string
`radius`	`number`	`2`	Visual size of the sphere
`draggable`	`"xyz" \| "xy" \| "xz" \| "yz" \| "x" \| "y" \| "z" \| "none"`	`"xyz"`	Axes the point can be dragged along
`visible`	`boolean`	`true`	Whether the point is shown
`pointerEvents`	`"auto" \| "none"`	`"auto"`	Whether the point receives pointer events
`tags`	`string[]`	`[]`	Custom tags for grouping

Returned Item

The scene.create("point3d", options) call returns a Point3D item with these atom fields:

Field	Type	Description
`id`	`string`	Unique identifier
`coords`	`BoundAtom<Vec3>`	Position atom
`color`	`BoundAtom<string>`	Color atom
`radius`	`BoundAtom<number>`	Size atom
`draggable`	`BoundAtom<...>`	Draggable constraint atom
`visible`	`BoundAtom<boolean>`	Visibility atom
`pointerEvents`	`BoundAtom<string>`	Pointer events atom
`tags`	`BoundAtom<string[]>`	Tags atom

On this page