Skip to the content

3D

point-cloud

Data as points in 3D: three numbers place each point inside a framed cube, a fourth field gives its group colour from the chart series; it goes inside scene (and model-stage to turn it), with PointCloudTable as its text alternative.

Effects and 3D data

When to use it

Three measures that belong together and are best turned in space: a scan, positions in a volume, an embedding. It is harder to read exactly than a 2D chart, so pass a scatter-chart as the scene's fallback and keep the table. For two measures use scatter-chart; for thousands of points in 2D use density-chart.

See it working

The demonstration the browser checks drive, with the keyboard as well as the pointer. More of it is on the Effects and 3D data page.

Word rotate and pattern

Maps for teams, schools, or newsrooms

Animated beam

A map becomes a film.

Orbit

  • Maps
  • Charts
  • Films
  • Motion
Rivier

Confetti

Not yet published.

Point cloud

Ninety finds
#widthheightdepthkind
11.22.52.5Clay
23.22.73.2Stone
32.92.53.8Glass
40.30.64.3Clay
52.71.24.5Stone
642.54.4Glass
70.52.14.1Clay
81.63.13.5Stone
94.13.32.9Glass
101.61.32.1Clay
111.21.21.4Stone
123.11.80.9Glass
132.21.30.6Clay
142.12.70.5Stone
152.23.70.7Glass
161.62.11.2Clay
173.11.81.8Stone
182.61.82.5Glass
190.50.63.2Clay
2031.93.9Stone
213.73.44.3Glass
220.32.54.5Clay
231.92.74.4Stone
244.22.44.1Glass
251.20.63.5Clay
261.21.22.8Stone
273.42.52.1Glass
282.12.21.4Clay
291.73.10.9Stone
302.43.30.6Glass
311.91.20.5Clay
322.81.20.7Stone
332.41.81.2Glass
340.81.41.8Clay
353.12.82.5Stone
363.43.73.2Glass
370.22.13.9Clay
382.31.84.3Stone
394.21.84.5Glass
400.90.64.4Clay
411.324.1Stone
423.83.43.5Glass
4322.52.8Clay
441.52.62.1Stone
452.62.41.4Glass
462.10.60.9Clay
472.51.30.6Stone
482.22.60.5Glass
491.12.20.7Clay
503.23.11.2Stone
5133.21.8Glass
520.21.22.5Clay
532.61.23.3Stone
5441.93.9Glass
550.61.44.3Clay
561.52.84.5Stone
5743.74.4Glass
581.724.1Clay
591.31.73.5Stone
6031.72.8Glass
612.20.72.1Clay
622.221.4Stone
632.23.40.9Glass
641.52.50.6Clay
653.12.60.5Stone
662.72.30.7Glass
670.40.51.2Clay
682.91.31.8Stone
693.82.62.6Glass
700.32.23.3Clay
711.83.13.9Stone
724.23.24.3Glass
731.31.14.5Clay
741.21.14.4Stone
753.31.94.1Glass
762.21.53.5Clay
771.82.92.8Stone
782.33.72.1Glass
791.821.4Clay
802.91.70.9Stone
812.41.70.6Glass
820.70.70.5Clay
833.12.10.7Stone
843.53.51.2Glass
850.22.51.8Clay
862.22.62.6Stone
874.22.33.3Glass
8810.53.9Clay
891.31.34.3Stone
903.72.74.5Glass

Model annotations

  1. Lid — Hinged at the back.
  2. Side — A handle was here.
  3. Front — The maker's mark.

Add it

npx shadcn@latest add @rivier-ui/point-cloud

The registry is named once in components.json: see Installation.

Example

Import it from @/components/three/point-cloud.

<Scene label="Samples by depth, width and height" aspect={4 / 3} fallback={<ScatterChart label="Samples" data={rows} x="width" y="height" />}>
  <ModelStage><PointCloud data={rows} x="width" y="height" z="depth" group="kind" /></ModelStage>
</Scene>
<PointCloudTable caption="Samples" data={rows} x="width" y="height" z="depth" group="kind" />

What it needs

A client component: it uses state, effects or browser behaviour. Packages: @react-three/fiber, three.

It imports

Source

The whole file. Once copied it is yours: the registry item holds the same text.

src/components/three/point-cloud.tsx
"use client";
/**
 * @name point-cloud
 * @category three
 * @description Data as points in 3D: three numbers place each point inside a framed cube, a fourth field gives its group colour from the chart series; it goes inside scene (and model-stage to turn it), with PointCloudTable as its text alternative.
 * @when Three measures that belong together and are best turned in space: a scan, positions in a volume, an embedding. It is harder to read exactly than a 2D chart, so pass a scatter-chart as the scene's fallback and keep the table. For two measures use scatter-chart; for thousands of points in 2D use density-chart.
 * @example
 * <Scene label="Samples by depth, width and height" aspect={4 / 3} fallback={<ScatterChart label="Samples" data={rows} x="width" y="height" />}>
 *   <ModelStage><PointCloud data={rows} x="width" y="height" z="depth" group="kind" /></ModelStage>
 * </Scene>
 * <PointCloudTable caption="Samples" data={rows} x="width" y="height" z="depth" group="kind" />
 */
import { useMemo } from "react";
import { BufferAttribute, BufferGeometry, Color, EdgesGeometry, BoxGeometry } from "three";
import { useThree } from "@react-three/fiber";
import { useThemeColors } from "@/lib/theme-color";
import { ChartDataTable, formatNumber, readNumber } from "@/components/viz/chart";
 
export type PointCloudProps<T extends object> = {
  data: readonly T[];
  x: keyof T & string;
  y: keyof T & string;
  z: keyof T & string;
  /** A field naming each point's group: one series colour per group, in order of first appearance (five at most; the rest share the neutral). */
  group?: keyof T & string;
  /** The point size in scene units. Default 0.06. */
  size?: number;
  /** Half the cube's side in scene units. Default 1.4. */
  extent?: number;
};
 
const SERIES = ["--chart-1", "--chart-2", "--chart-3", "--chart-4", "--chart-5", "--muted-foreground", "--border-strong"] as const;
 
function extentOf(values: number[]): [number, number] {
  const low = Math.min(...values);
  const high = Math.max(...values);
  return low === high ? [low - 1, high + 1] : [low, high];
}
 
export function PointCloud<T extends object>({ data, x, y, z, group, size = 0.06, extent = 1.4 }: PointCloudProps<T>) {
  const canvas = useThree((state) => state.gl.domElement);
  const colors = useThemeColors(SERIES, canvas);
  const { geometry, frame } = useMemo(() => {
    const rows = data.flatMap((row) => {
      const px = readNumber(row, x);
      const py = readNumber(row, y);
      const pz = readNumber(row, z);
      return px === null || py === null || pz === null ? [] : [{ px, py, pz, g: group ? String((row as Record<string, unknown>)[group] ?? "") : "" }];
    });
    const groups = [...new Set(rows.map((r) => r.g))];
    const [x0, x1] = extentOf(rows.map((r) => r.px));
    const [y0, y1] = extentOf(rows.map((r) => r.py));
    const [z0, z1] = extentOf(rows.map((r) => r.pz));
    const place = (v: number, a: number, b: number): number => ((v - a) / (b - a) - 0.5) * 2 * extent;
    const positions = new Float32Array(rows.length * 3);
    const tints = new Float32Array(rows.length * 3);
    const color = new Color();
    rows.forEach((r, i) => {
      positions[i * 3] = place(r.px, x0, x1);
      positions[i * 3 + 1] = place(r.py, y0, y1);
      positions[i * 3 + 2] = place(r.pz, z0, z1);
      const slot = Math.min(groups.indexOf(r.g), 5);
      const value = colors[SERIES[slot] ?? "--muted-foreground"];
      // Before the theme is read, a neutral grey (as a number, not a colour of its own).
      if (value) color.set(value);
      else color.setScalar(0.5);
      tints[i * 3] = color.r;
      tints[i * 3 + 1] = color.g;
      tints[i * 3 + 2] = color.b;
    });
    const points = new BufferGeometry();
    points.setAttribute("position", new BufferAttribute(positions, 3));
    points.setAttribute("color", new BufferAttribute(tints, 3));
    const box = new EdgesGeometry(new BoxGeometry(extent * 2, extent * 2, extent * 2));
    return { geometry: points, frame: box };
  }, [data, x, y, z, group, extent, colors]);
  return (
    <group>
      <points geometry={geometry}>
        <pointsMaterial size={size} vertexColors sizeAttenuation />
      </points>
      <lineSegments geometry={frame}>
        <lineBasicMaterial color={colors["--border-strong"] ? new Color(colors["--border-strong"]) : new Color().setScalar(0.6)} />
      </lineSegments>
    </group>
  );
}
 
export type PointCloudTableProps<T extends object> = Omit<PointCloudProps<T>, "size" | "extent"> & { caption: string; locale?: string; xLabel?: string; yLabel?: string; zLabel?: string };
 
/** The points as a table for screen readers: put it beside the scene, outside the canvas. */
export function PointCloudTable<T extends object>({ caption, data, x, y, z, group, xLabel, yLabel, zLabel, locale }: PointCloudTableProps<T>) {
  const number = (v: number | null): string => (v === null ? "" : formatNumber(v, locale));
  return (
    <ChartDataTable
      caption={caption}
      columns={["#", xLabel ?? x, yLabel ?? y, zLabel ?? z, ...(group ? [group] : [])]}
      rows={data.map((row, i) => [String(i + 1), number(readNumber(row, x)), number(readNumber(row, y)), number(readNumber(row, z)), ...(group ? [String((row as Record<string, unknown>)[group] ?? "")] : [])])}
    />
  );
}