3D 散点图 XYZ

3D 散点图 XYZ 在三维空间中展示点数据的空间分布，每个点由 [x, y, z] 三个坐标值确定位置，适用于聚类分析、空间分布、多变量关系等场景。

快速开始

最简单的 3D 散点图需要提供三维坐标数据：

<template>
  <RayScatter3DXyz :option="chartOption" />
</template>

<script setup>
import { ref } from 'vue';
import { RayScatter3DXyz } from 'raychart';

const chartOption = ref({
  xAxis3D: { show: true },
  yAxis3D: { show: true },
  zAxis3D: { show: true },
  series: [
    {
      type: 'scatter3DXyz',
      data: [
        [1, 2, 3], // 第1个点的 [x, y, z] 坐标
        [4, 5, 6], // 第2个点的 [x, y, z] 坐标
        [7, 3, 2], // 第3个点的 [x, y, z] 坐标
        [2, 8, 5], // 第4个点的 [x, y, z] 坐标
      ],
    },
  ],
});
</script>

智能默认值

自动配置点大小、颜色渐变、材质效果和光照系统。

核心配置

坐标轴配置

属性	类型	默认值	说明
xAxis3D.show	boolean	true	显示 X 轴
yAxis3D.show	boolean	true	显示 Y 轴
zAxis3D.show	boolean	true	显示 Z 轴

数据配置

属性	类型	默认值	说明
series.data	number[][]	-	三维坐标数据（必填）
series.name	string	-	系列名称
series.label	object	不显示	点标签，如 { show: true, distance: 0.3 }

数据格式说明

series.data 是二维数组，每个元素是一个包含 3 个数值的数组 [x, y, z]，代表点在三维空间中的坐标。X/Z 轴刻度由数据范围自动生成，Y 轴范围自动取最大值 1.1 倍。

示例：

data: [
  [1.2, 3.5, 2.8],  // 点1的坐标
  [4.5, 2.1, 5.3],  // 点2的坐标
  [2.8, 6.7, 1.9],  // 点3的坐标
]

样式配置

属性	类型	默认值	说明
series.symbolSize	number	4	点大小（半径 = symbolSize / 10，默认半径 0.4）
series.color	string[]	自动分配	颜色数组，按索引轮转

材质配置（进阶）

通过 series.itemStyle 配置点的材质效果：

itemStyle: {
  opacity: 0.9,              // 不透明度（0-1）
  roughness: 0.55,           // 粗糙度（0-1）
  metalness: 0,              // 金属度（0-1）
  clearcoat: 0.1,            // 清漆层强度（0-1）
  clearcoatRoughness: 0.6,   // 清漆层粗糙度（0-1）
  emissiveIntensity: 0.1     // 自发光强度
}

网格配置（可选）

通过 grid3D 配置三维空间尺寸：

grid3D: {
  show: true,       // 显示网格边框
  boxWidth: 20,     // 宽度
  boxHeight: 10     // 高度
}

boxDepth 自动计算

grid3D.boxDepth 会根据数据的 X/Z 范围比例自动计算，手动配置不生效；Y 轴范围（yAxis3D.min/max）也会自动设置为数据的最大值的 1.1 倍。X/Z 轴刻度由数据范围自动生成，无需（也不应）手动指定 xAxis3D.data。

:::

常见场景

基础 3D 散点图

展示随机分布的三维点数据：

<template>
  <RayScatter3DXyz :option="chartOption" />
</template>

<script setup>
import { ref } from 'vue';
import { RayScatter3DXyz } from 'raychart';

// 生成随机3D散点数据
const data = [];
for (let i = 0; i < 50; i++) {
  data.push([
    Math.random() * 10,     // x坐标
    Math.random() * 8 + 1,  // y坐标
    Math.random() * 10,     // z坐标
  ]);
}

const chartOption = ref({
  grid3D: {
    show: true,
    boxWidth: 20,
    boxHeight: 10,
  },
  xAxis3D: { show: true },
  yAxis3D: { show: true },
  zAxis3D: { show: true },
  series: [
    {
      type: 'scatter3DXyz',
      name: '3D散点',
      data,
      symbolSize: 5, // 点大小
      color: ['#5470c6', '#91cc75', '#fac858', '#ee6666', '#73c0de'],
      itemStyle: {
        opacity: 0.9,
        roughness: 0.55,
        metalness: 0,
        clearcoat: 0.1,
        emissiveIntensity: 0.1,
      },
    },
  ],
});
</script>

聚类分布

展示多个聚类中心的数据分布：

<script setup>
// 生成3个聚类
const clusters = [
  { cx: 2, cy: 3, cz: 2, count: 15 }, // 聚类1中心
  { cx: 7, cy: 7, cz: 7, count: 15 }, // 聚类2中心
  { cx: 5, cy: 2, cz: 8, count: 15 }, // 聚类3中心
];

const data = [];
clusters.forEach(({ cx, cy, cz, count }) => {
  for (let i = 0; i < count; i++) {
    data.push([
      cx + (Math.random() - 0.5) * 2, // 在中心附近随机分布
      cy + (Math.random() - 0.5) * 2,
      cz + (Math.random() - 0.5) * 2,
    ]);
  }
});

const chartOption = ref({
  grid3D: {
    show: true,
    boxWidth: 20,
    boxHeight: 10,
  },
  xAxis3D: { show: true },
  yAxis3D: { show: true },
  zAxis3D: { show: true },
  series: [
    {
      type: 'scatter3DXyz',
      name: '聚类散点',
      data,
      symbolSize: 5,
      color: ['#5470c6', '#91cc75', '#fac858'],
      itemStyle: {
        opacity: 0.9,
        roughness: 0.55,
        metalness: 0,
        clearcoat: 0.1,
      },
    },
  ],
});
</script>

波浪分布

使用数学函数生成波浪形分布：

<script setup>
// 生成波浪分布数据
const data = [];
for (let i = 0; i < 80; i++) {
  const x = Math.random() * 10;
  const z = Math.random() * 10;
  const y = Math.sin(x) * Math.cos(z) * 3 + 4; // 波浪函数
  data.push([x, y, z]);
}

const chartOption = ref({
  grid3D: {
    show: true,
    boxWidth: 20,
    boxHeight: 10,
  },
  xAxis3D: { show: true },
  yAxis3D: { show: true },
  zAxis3D: { show: true },
  series: [
    {
      type: 'scatter3DXyz',
      name: '波浪散点',
      data,
      symbolSize: 5,
      color: ['#4facfe', '#00f2fe', '#43e97b', '#f093fb', '#667eea'],
      itemStyle: {
        opacity: 0.9,
        roughness: 0.5,
        metalness: 0,
        clearcoat: 0.1,
        emissiveIntensity: 0.15, // 增加自发光
      },
    },
  ],
});
</script>

多变量关系分析

展示身高、体重和年龄的三维关系：

<script setup>
const chartOption = ref({
  grid3D: {
    show: true,
    boxWidth: 20,
    boxHeight: 10,
  },
  xAxis3D: {
    show: true,
    name: '身高（cm）',
  },
  yAxis3D: {
    show: true,
    name: '体重（kg）',
  },
  zAxis3D: {
    show: true,
    name: '年龄',
  },
  series: [
    {
      type: 'scatter3DXyz',
      name: '人员数据',
      data: [
        [170, 65, 25], // 身高170cm，体重65kg，年龄25岁
        [175, 70, 30],
        [160, 55, 22],
        [180, 75, 35],
        [165, 60, 28],
        [172, 68, 26],
        [168, 63, 24],
        [178, 73, 32],
      ],
      symbolSize: 6,
      color: ['#5470c6', '#91cc75', '#fac858'],
      itemStyle: {
        opacity: 0.9,
        roughness: 0.5,
        metalness: 0.1,
      },
    },
  ],
});
</script>

组件属性

属性	类型	默认值	说明
option	RayChartOption	-	图表配置对象（必填）
width	string | number	'100%'	图表宽度
height	string | number	'600px'	图表高度

相关文档

基础学习

• 快速上手 - 如果您是新手，从这里开始
• 图表配置 - 完整配置选项说明
• 坐标系统 - 理解 3D 坐标系

进阶主题

• 材质系统 - 自定义材质效果（金属度、粗糙度等）
• 光照系统 - 光照原理和配置
• 交互控制 - 相机控制和事件监听
• 性能优化 - 大数据量优化技巧

API 参考

• 组件 API - RayScatter3DXyz 组件属性和方法
• 配置项 API - 完整的配置项文档
• 事件系统 - 事件监听和处理

其他图表类型

• 散点图 - 二维散点图
• 柱状图 - 展示数据对比
• 3D 热力图 - 展示密度分布
• 查看所有图表 - 浏览完整图表库

在线示例

• 图表库 - 查看更多 3D 散点图示例
• 在线编辑器 - 实时调试配置