feat: sphere shape used in 3d lib #5375

[xiaoiver]

#5375

• 官网在 “3D 可视化” 下增加了三个案例
• 文档进阶主题下增加 /manual/extra-topics/3d-charts

透视投影：

正交投影：

使用方式

参考 chartRender3dScatterPlot 示例：

• 创建 WebGL 渲染器
• 注册以下两个插件：
  • https://g.antv.antgroup.com/plugins/3d
  • https://g.antv.antgroup.com/plugins/control
• 使用 WebGL 渲染器创建画布
• (可选)设置相机
• (可选)设置光照，创建光源并添加到画布

import { Renderer } from '@antv/g-webgl';
import { Plugin as ControlPlugin } from '@antv/g-plugin-control';
import { Plugin as ThreeDPlugin, DirectionalLight } from '@antv/g-plugin-3d';

const renderer = new Renderer();
renderer.registerPlugin(new ControlPlugin()); // 提供 3D 相机交互
renderer.registerPlugin(new ThreeDPlugin()); // 提供 3D Geometry、Material、光照等

const canvas = new Canvas({
  container: document.createElement('div'),
  width,
  height,
  renderer,
});

const camera = canvas.getCamera();
camera.setType(CameraType.ORBITING);

// add a directional light into scene
const light = new DirectionalLight({
  style: {
    intensity: 3,
    fill: 'white',
    direction: [-1, 0, 1],
  },
});
canvas.appendChild(light);

乍一看略显繁琐，主要是光照配置和 G2 没太大关系，我们是否有必要把光照也加到 Spec 里？如果需要的话可能长这样：

lights: [
  { type: 'directional', intensity: 3, direction: [-1, 0, 1] },
  { type: 'point', intensity: 3, position: [-1, 0, 1] },
]

自定义 Chart 扩展 threedlib

import { Runtime, corelib, threedlib, extend } from '@antv/g2';
const Chart = extend(Runtime, { ...corelib(), ...threedlib() });

Spec 用法

depth 默认为 640 和 height 相同。

export function bodyPointScatterPlot3D(): G2Spec {
  return {
    type: 'point3D',
    padding: 'auto',
    data: {
      type: 'fetch',
      value: 'data/cars2.csv',
    },
    encode: {
      x: 'Horsepower',
      y: 'Miles_per_Gallon',
      z: 'Weight_in_lbs',
      size: 'Origin',
      color: 'Cylinders',
      shape: 'cube', // 目前 point3D 支持 sphere | cube
    },
    scale: {
      x: { nice: true },
      y: { nice: true },
      z: { nice: true }, // 增加 Z
    },
    coordinate: { type: 'cartesian3D' }, // 使用 Cartesian3D
    axis: {
      x: { gridLineWidth: 3 },
      y: { gridLineWidth: 3 },
      z: { gridLineWidth: 3 },
    },
    // legend: false, // 可以暂时禁用 legend
  };
}

新增 threedlib 包含：

export function threedlib() {
  return {
    'coordinate.cartesian3D': Cartesian3D,
    'component.axisZ': AxisZ,
    'mark.point3D': Point3D,
  } as const;
}

其中 point3D 暂时支持 Sphere 和 Cube 两种 shape：

后续改进

Chart API

chart.axisZ();

Legend

Legend 不应该受相机影响，在 3D 场景中类似 HUD，有趣的是 Three.js 也建议使用 HTML 处理这类需求：
mrdoob/three.js#225

• Highcharts 也使用了 HTML：

• G6 中的图例是通过插件实现的，与主画布分开独立绘制：feat: use GUI legend G6#4822
• G2 中可以使用自定义图例达到类似效果：https://github.com/antvis/G2/pull/5414/files

3D辅助线

hover / click 节点展示辅助线，例如 plot.ly

透视投影

可以参考 chartRender3dScatterPlotPerspective 这个例子，设置相机透视投影：

const camera = canvas.getCamera();
camera.setPerspective(0.1, 5000, 45, 500 / 500);

平面背景色

支持配置 x-z / x-y / y-z 平面的背景色，下面是 highcharts 的效果：

Bugs

• GridLength 根据 depth 推断
• 三根轴的原点 tick label 重合在了一起
• 使用 GUI alpha.30 @pearmini
• Slider 渐变渲染有误 [g-plugin-device-renderer] Path 填充有误 G#1447
• 测试用例支持 WebGL 渲染