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.
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
Confetti
Not yet published.
Point cloud
- Clay
- Stone
- Glass
| # | width | height | kind |
|---|---|---|---|
| 1 | 0.2 | 1.2 | Clay |
| 2 | 0.2 | 2.1 | Clay |
| 3 | 0.2 | 2.5 | Clay |
| 4 | 0.3 | 0.6 | Clay |
| 5 | 0.3 | 2.2 | Clay |
| 6 | 0.3 | 2.5 | Clay |
| 7 | 0.4 | 0.5 | Clay |
| 8 | 0.5 | 0.6 | Clay |
| 9 | 0.5 | 2.1 | Clay |
| 10 | 0.6 | 1.4 | Clay |
| 11 | 0.7 | 0.7 | Clay |
| 12 | 0.8 | 1.4 | Clay |
| 13 | 0.9 | 0.6 | Clay |
| 14 | 1 | 0.5 | Clay |
| 15 | 1.1 | 2.2 | Clay |
| 16 | 1.2 | 0.6 | Clay |
| 17 | 1.2 | 1.1 | Stone |
| 18 | 1.2 | 1.2 | Stone |
| 19 | 1.2 | 1.2 | Stone |
| 20 | 1.2 | 2.5 | Clay |
| 21 | 1.3 | 1.1 | Clay |
| 22 | 1.3 | 1.3 | Stone |
| 23 | 1.3 | 1.7 | Stone |
| 24 | 1.3 | 2 | Stone |
| 25 | 1.5 | 2.5 | Clay |
| 26 | 1.5 | 2.6 | Stone |
| 27 | 1.5 | 2.8 | Stone |
| 28 | 1.6 | 1.3 | Clay |
| 29 | 1.6 | 2.1 | Clay |
| 30 | 1.6 | 3.1 | Stone |
| 31 | 1.7 | 2 | Clay |
| 32 | 1.7 | 3.1 | Stone |
| 33 | 1.8 | 2 | Clay |
| 34 | 1.8 | 2.9 | Stone |
| 35 | 1.8 | 3.1 | Stone |
| 36 | 1.9 | 1.2 | Clay |
| 37 | 1.9 | 2.7 | Stone |
| 38 | 2 | 2.5 | Clay |
| 39 | 2.1 | 0.6 | Clay |
| 40 | 2.1 | 2.2 | Clay |
| 41 | 2.1 | 2.7 | Stone |
| 42 | 2.2 | 0.7 | Clay |
| 43 | 2.2 | 1.3 | Clay |
| 44 | 2.2 | 1.5 | Clay |
| 45 | 2.2 | 2 | Stone |
| 46 | 2.2 | 2.6 | Glass |
| 47 | 2.2 | 2.6 | Stone |
| 48 | 2.2 | 3.4 | Glass |
| 49 | 2.2 | 3.7 | Glass |
| 50 | 2.3 | 1.8 | Stone |
| 51 | 2.3 | 3.7 | Glass |
| 52 | 2.4 | 1.7 | Glass |
| 53 | 2.4 | 1.8 | Glass |
| 54 | 2.4 | 3.3 | Glass |
| 55 | 2.5 | 1.3 | Stone |
| 56 | 2.6 | 1.2 | Stone |
| 57 | 2.6 | 1.8 | Glass |
| 58 | 2.6 | 2.4 | Glass |
| 59 | 2.7 | 1.2 | Stone |
| 60 | 2.7 | 2.3 | Glass |
| 61 | 2.8 | 1.2 | Stone |
| 62 | 2.9 | 1.3 | Stone |
| 63 | 2.9 | 1.7 | Stone |
| 64 | 2.9 | 2.5 | Glass |
| 65 | 3 | 1.7 | Glass |
| 66 | 3 | 1.9 | Stone |
| 67 | 3 | 3.2 | Glass |
| 68 | 3.1 | 1.8 | Glass |
| 69 | 3.1 | 1.8 | Stone |
| 70 | 3.1 | 2.1 | Stone |
| 71 | 3.1 | 2.6 | Stone |
| 72 | 3.1 | 2.8 | Stone |
| 73 | 3.2 | 2.7 | Stone |
| 74 | 3.2 | 3.1 | Stone |
| 75 | 3.3 | 1.9 | Glass |
| 76 | 3.4 | 2.5 | Glass |
| 77 | 3.4 | 3.7 | Glass |
| 78 | 3.5 | 3.5 | Glass |
| 79 | 3.7 | 2.7 | Glass |
| 80 | 3.7 | 3.4 | Glass |
| 81 | 3.8 | 2.6 | Glass |
| 82 | 3.8 | 3.4 | Glass |
| 83 | 4 | 1.9 | Glass |
| 84 | 4 | 2.5 | Glass |
| 85 | 4 | 3.7 | Glass |
| 86 | 4.1 | 3.3 | Glass |
| 87 | 4.2 | 1.8 | Glass |
| 88 | 4.2 | 2.3 | Glass |
| 89 | 4.2 | 2.4 | Glass |
| 90 | 4.2 | 3.2 | Glass |
| # | width | height | depth | kind |
|---|---|---|---|---|
| 1 | 1.2 | 2.5 | 2.5 | Clay |
| 2 | 3.2 | 2.7 | 3.2 | Stone |
| 3 | 2.9 | 2.5 | 3.8 | Glass |
| 4 | 0.3 | 0.6 | 4.3 | Clay |
| 5 | 2.7 | 1.2 | 4.5 | Stone |
| 6 | 4 | 2.5 | 4.4 | Glass |
| 7 | 0.5 | 2.1 | 4.1 | Clay |
| 8 | 1.6 | 3.1 | 3.5 | Stone |
| 9 | 4.1 | 3.3 | 2.9 | Glass |
| 10 | 1.6 | 1.3 | 2.1 | Clay |
| 11 | 1.2 | 1.2 | 1.4 | Stone |
| 12 | 3.1 | 1.8 | 0.9 | Glass |
| 13 | 2.2 | 1.3 | 0.6 | Clay |
| 14 | 2.1 | 2.7 | 0.5 | Stone |
| 15 | 2.2 | 3.7 | 0.7 | Glass |
| 16 | 1.6 | 2.1 | 1.2 | Clay |
| 17 | 3.1 | 1.8 | 1.8 | Stone |
| 18 | 2.6 | 1.8 | 2.5 | Glass |
| 19 | 0.5 | 0.6 | 3.2 | Clay |
| 20 | 3 | 1.9 | 3.9 | Stone |
| 21 | 3.7 | 3.4 | 4.3 | Glass |
| 22 | 0.3 | 2.5 | 4.5 | Clay |
| 23 | 1.9 | 2.7 | 4.4 | Stone |
| 24 | 4.2 | 2.4 | 4.1 | Glass |
| 25 | 1.2 | 0.6 | 3.5 | Clay |
| 26 | 1.2 | 1.2 | 2.8 | Stone |
| 27 | 3.4 | 2.5 | 2.1 | Glass |
| 28 | 2.1 | 2.2 | 1.4 | Clay |
| 29 | 1.7 | 3.1 | 0.9 | Stone |
| 30 | 2.4 | 3.3 | 0.6 | Glass |
| 31 | 1.9 | 1.2 | 0.5 | Clay |
| 32 | 2.8 | 1.2 | 0.7 | Stone |
| 33 | 2.4 | 1.8 | 1.2 | Glass |
| 34 | 0.8 | 1.4 | 1.8 | Clay |
| 35 | 3.1 | 2.8 | 2.5 | Stone |
| 36 | 3.4 | 3.7 | 3.2 | Glass |
| 37 | 0.2 | 2.1 | 3.9 | Clay |
| 38 | 2.3 | 1.8 | 4.3 | Stone |
| 39 | 4.2 | 1.8 | 4.5 | Glass |
| 40 | 0.9 | 0.6 | 4.4 | Clay |
| 41 | 1.3 | 2 | 4.1 | Stone |
| 42 | 3.8 | 3.4 | 3.5 | Glass |
| 43 | 2 | 2.5 | 2.8 | Clay |
| 44 | 1.5 | 2.6 | 2.1 | Stone |
| 45 | 2.6 | 2.4 | 1.4 | Glass |
| 46 | 2.1 | 0.6 | 0.9 | Clay |
| 47 | 2.5 | 1.3 | 0.6 | Stone |
| 48 | 2.2 | 2.6 | 0.5 | Glass |
| 49 | 1.1 | 2.2 | 0.7 | Clay |
| 50 | 3.2 | 3.1 | 1.2 | Stone |
| 51 | 3 | 3.2 | 1.8 | Glass |
| 52 | 0.2 | 1.2 | 2.5 | Clay |
| 53 | 2.6 | 1.2 | 3.3 | Stone |
| 54 | 4 | 1.9 | 3.9 | Glass |
| 55 | 0.6 | 1.4 | 4.3 | Clay |
| 56 | 1.5 | 2.8 | 4.5 | Stone |
| 57 | 4 | 3.7 | 4.4 | Glass |
| 58 | 1.7 | 2 | 4.1 | Clay |
| 59 | 1.3 | 1.7 | 3.5 | Stone |
| 60 | 3 | 1.7 | 2.8 | Glass |
| 61 | 2.2 | 0.7 | 2.1 | Clay |
| 62 | 2.2 | 2 | 1.4 | Stone |
| 63 | 2.2 | 3.4 | 0.9 | Glass |
| 64 | 1.5 | 2.5 | 0.6 | Clay |
| 65 | 3.1 | 2.6 | 0.5 | Stone |
| 66 | 2.7 | 2.3 | 0.7 | Glass |
| 67 | 0.4 | 0.5 | 1.2 | Clay |
| 68 | 2.9 | 1.3 | 1.8 | Stone |
| 69 | 3.8 | 2.6 | 2.6 | Glass |
| 70 | 0.3 | 2.2 | 3.3 | Clay |
| 71 | 1.8 | 3.1 | 3.9 | Stone |
| 72 | 4.2 | 3.2 | 4.3 | Glass |
| 73 | 1.3 | 1.1 | 4.5 | Clay |
| 74 | 1.2 | 1.1 | 4.4 | Stone |
| 75 | 3.3 | 1.9 | 4.1 | Glass |
| 76 | 2.2 | 1.5 | 3.5 | Clay |
| 77 | 1.8 | 2.9 | 2.8 | Stone |
| 78 | 2.3 | 3.7 | 2.1 | Glass |
| 79 | 1.8 | 2 | 1.4 | Clay |
| 80 | 2.9 | 1.7 | 0.9 | Stone |
| 81 | 2.4 | 1.7 | 0.6 | Glass |
| 82 | 0.7 | 0.7 | 0.5 | Clay |
| 83 | 3.1 | 2.1 | 0.7 | Stone |
| 84 | 3.5 | 3.5 | 1.2 | Glass |
| 85 | 0.2 | 2.5 | 1.8 | Clay |
| 86 | 2.2 | 2.6 | 2.6 | Stone |
| 87 | 4.2 | 2.3 | 3.3 | Glass |
| 88 | 1 | 0.5 | 3.9 | Clay |
| 89 | 1.3 | 1.3 | 4.3 | Stone |
| 90 | 3.7 | 2.7 | 4.5 | Glass |
Model annotations
- Lid — Hinged at the back.
- Side — A handle was here.
- 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.
"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] ?? "")] : [])])}
/>
);
}