{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "point-cloud",
  "type": "registry:component",
  "title": "Point Cloud",
  "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.",
  "categories": [
    "three"
  ],
  "dependencies": [
    "@react-three/fiber",
    "three"
  ],
  "devDependencies": [
    "@types/three"
  ],
  "registryDependencies": [
    "@rivier-ui/theme",
    "@rivier-ui/chart",
    "@rivier-ui/theme-color"
  ],
  "files": [
    {
      "path": "registry/three/point-cloud.tsx",
      "type": "registry:component",
      "target": "components/three/point-cloud.tsx",
      "content": "\"use client\";\n/**\n * @name point-cloud\n * @category three\n * @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.\n * @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.\n * @example\n * <Scene label=\"Samples by depth, width and height\" aspect={4 / 3} fallback={<ScatterChart label=\"Samples\" data={rows} x=\"width\" y=\"height\" />}>\n *   <ModelStage><PointCloud data={rows} x=\"width\" y=\"height\" z=\"depth\" group=\"kind\" /></ModelStage>\n * </Scene>\n * <PointCloudTable caption=\"Samples\" data={rows} x=\"width\" y=\"height\" z=\"depth\" group=\"kind\" />\n */\nimport { useMemo } from \"react\";\nimport { BufferAttribute, BufferGeometry, Color, EdgesGeometry, BoxGeometry } from \"three\";\nimport { useThree } from \"@react-three/fiber\";\nimport { useThemeColors } from \"@/lib/theme-color\";\nimport { ChartDataTable, formatNumber, readNumber } from \"@/components/viz/chart\";\n\nexport type PointCloudProps<T extends object> = {\n  data: readonly T[];\n  x: keyof T & string;\n  y: keyof T & string;\n  z: keyof T & string;\n  /** 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). */\n  group?: keyof T & string;\n  /** The point size in scene units. Default 0.06. */\n  size?: number;\n  /** Half the cube's side in scene units. Default 1.4. */\n  extent?: number;\n};\n\nconst SERIES = [\"--chart-1\", \"--chart-2\", \"--chart-3\", \"--chart-4\", \"--chart-5\", \"--muted-foreground\", \"--border-strong\"] as const;\n\nfunction extentOf(values: number[]): [number, number] {\n  const low = Math.min(...values);\n  const high = Math.max(...values);\n  return low === high ? [low - 1, high + 1] : [low, high];\n}\n\nexport function PointCloud<T extends object>({ data, x, y, z, group, size = 0.06, extent = 1.4 }: PointCloudProps<T>) {\n  const canvas = useThree((state) => state.gl.domElement);\n  const colors = useThemeColors(SERIES, canvas);\n  const { geometry, frame } = useMemo(() => {\n    const rows = data.flatMap((row) => {\n      const px = readNumber(row, x);\n      const py = readNumber(row, y);\n      const pz = readNumber(row, z);\n      return px === null || py === null || pz === null ? [] : [{ px, py, pz, g: group ? String((row as Record<string, unknown>)[group] ?? \"\") : \"\" }];\n    });\n    const groups = [...new Set(rows.map((r) => r.g))];\n    const [x0, x1] = extentOf(rows.map((r) => r.px));\n    const [y0, y1] = extentOf(rows.map((r) => r.py));\n    const [z0, z1] = extentOf(rows.map((r) => r.pz));\n    const place = (v: number, a: number, b: number): number => ((v - a) / (b - a) - 0.5) * 2 * extent;\n    const positions = new Float32Array(rows.length * 3);\n    const tints = new Float32Array(rows.length * 3);\n    const color = new Color();\n    rows.forEach((r, i) => {\n      positions[i * 3] = place(r.px, x0, x1);\n      positions[i * 3 + 1] = place(r.py, y0, y1);\n      positions[i * 3 + 2] = place(r.pz, z0, z1);\n      const slot = Math.min(groups.indexOf(r.g), 5);\n      const value = colors[SERIES[slot] ?? \"--muted-foreground\"];\n      // Before the theme is read, a neutral grey (as a number, not a colour of its own).\n      if (value) color.set(value);\n      else color.setScalar(0.5);\n      tints[i * 3] = color.r;\n      tints[i * 3 + 1] = color.g;\n      tints[i * 3 + 2] = color.b;\n    });\n    const points = new BufferGeometry();\n    points.setAttribute(\"position\", new BufferAttribute(positions, 3));\n    points.setAttribute(\"color\", new BufferAttribute(tints, 3));\n    const box = new EdgesGeometry(new BoxGeometry(extent * 2, extent * 2, extent * 2));\n    return { geometry: points, frame: box };\n  }, [data, x, y, z, group, extent, colors]);\n  return (\n    <group>\n      <points geometry={geometry}>\n        <pointsMaterial size={size} vertexColors sizeAttenuation />\n      </points>\n      <lineSegments geometry={frame}>\n        <lineBasicMaterial color={colors[\"--border-strong\"] ? new Color(colors[\"--border-strong\"]) : new Color().setScalar(0.6)} />\n      </lineSegments>\n    </group>\n  );\n}\n\nexport type PointCloudTableProps<T extends object> = Omit<PointCloudProps<T>, \"size\" | \"extent\"> & { caption: string; locale?: string; xLabel?: string; yLabel?: string; zLabel?: string };\n\n/** The points as a table for screen readers: put it beside the scene, outside the canvas. */\nexport function PointCloudTable<T extends object>({ caption, data, x, y, z, group, xLabel, yLabel, zLabel, locale }: PointCloudTableProps<T>) {\n  const number = (v: number | null): string => (v === null ? \"\" : formatNumber(v, locale));\n  return (\n    <ChartDataTable\n      caption={caption}\n      columns={[\"#\", xLabel ?? x, yLabel ?? y, zLabel ?? z, ...(group ? [group] : [])]}\n      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] ?? \"\")] : [])])}\n    />\n  );\n}\n"
    }
  ],
  "meta": {
    "category": "three",
    "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\" />}>\n  <ModelStage><PointCloud data={rows} x=\"width\" y=\"height\" z=\"depth\" group=\"kind\" /></ModelStage>\n</Scene>\n<PointCloudTable caption=\"Samples\" data={rows} x=\"width\" y=\"height\" z=\"depth\" group=\"kind\" />",
    "client": true
  }
}
