---
url: /3d/design.md
---
# 设计规范

三维图的视觉标准（完整版见仓库内 `packages/evoke-charts/DESIGN.md「三维篇章」`），本页给使用视角的摘要：
什么时候图会好看，哪些参数动不得。

## 光照

* 默认一盏**跟随相机的肩后主光**：任意视角下顶面最亮、正面居中、侧面最暗，形体永远清晰；
* `lighting.ambient`（默认 0.56）压不住暗面、`intensity`（默认 0.88）控制明暗落差，
  默认值即验收基准，非展示场景不建议动；
* `lighting.direction` 可以把光固定在世界坐标——旋转物体能看到明暗变化，但可能转到暗面，
  仅建议用于产品展示类场景。

## 纵深

默认开启三件套（`depth` 组，任意一项设 0 即关闭该项），画面的立体感主要来自它们：

* `haze`（默认 0.3）**景深雾化**：按数据层视深把面与线的色相向背景色混合——远景退、近景跳，
  是柱林 / 散点 / 曲面最见效的纵深线索；文字不参与（刻度始终清晰）；
* `edge`（默认 0.06）**实体面描边**：数据面描一圈同色深描边，形体边界更利落、相邻柱体不糊在一起；
* `gradient`（默认 0.08）**面内渐变**：实体面顶亮底暗（假 AO），面片更「实心」；
* 三件套只作用于**实体面**（柱体、饼体的平直面）；落地投影另由 `bar.shadowStrength` /
  `bar.shadowOffset` / `pie.shadowStrength` 调深浅与落点；
* 饼图弧面是细分曲面，只走光照明暗：逐面渐变/描边会在细分缝处对不齐显色带（渲染时用同色
  细描边盖住抗锯齿细缝）。

## 动画

* **进场**：统一 progress 驱动五种图型的生长（柱体升高、曲面抬升、饼图「扫角 + 长厚」）；
  `animation.stagger`（默认 0.25）让条目按序错峰——柱林沿类目依次长起、饼图扇区依次扫入、
  折线/散点按点序推进；设 0 即全部同步；
* **数据更新**：结构不变、只变数值时走**补间过渡**（逐帧插值 series / pieData / scatterData /
  surfaceData，并按类目错峰），不重放整段进场；结构变了才重放进场；
* **拖拽惯性**：松手后按 `camera.damping`（默认 0.14）衰减滑行一段，滑行距离与帧率无关
  （按 dt 归一衰减）；`damping: 0` 即松手停住；
* **减弱动态效果**：系统开启 `prefers-reduced-motion` 时，进场 / 补间 / 惯性一律退化为直接
  出终态图。

## 相机与构图

* 默认机位 yaw -52° / pitch 27°，是三轴都能读清的斜视构图；
* pitch 被限制在 2°–88°：不会钻到地面以下，也不会出现正俯视的「平面图」；
* 柱类目标点略高于地面，饼类对准盘心，构图默认已调平。

## 坐标框

* 轴线刻度**跟随相机**取边：X/Y 轴贴最近底边、Z 轴立最远立柱，任意角度下都衬托数据；
* 背景面**钉在固定侧**：背墙 +Y、侧墙 −X（跟随相机会让它在旋转中整面跳边）；
  相机绕到墙背面时整组（墙面 + 墙内网格 + 顶棱）短距离淡出，不让墙挡在数据前；
* 刻度标签在屏幕空间防碰撞：放不下就丢弃，绝不叠字；网格线不随标签抽稀；
* `box.walls` 可选 `back`（默认，+Y 单片背墙）/ `side`（−X 侧墙）/ `all` / `none`。

## 图型细则（使用视角）

* **bar3d**：柱宽/深默认占带位 62%；缺失值不占位，零值柱保留；
* **line3d**：落地投影线是读数辅助（三维折线没有共同基线），非装饰；
* **scatter3d**：`colorScale` 把 Z 值编码到色带，是表达第四维的正解；
* **surface3d**：矩阵过大自动抽稀（上限 48×48 面片）；线框逐格绘制，保证遮挡正确；
* **pie3d**：悬浮扇区整体上浮（位移强调，不改色）；`innerRadius > 0` 即环形。

## 动效

进场动画：柱/线/散点/曲面按进度生长，饼为角度扫入 + 厚度生长双节奏；默认 600ms。
`animation: { enabled: false }` 直接呈现终态。相机交互不做补间——跟手优先。

## 大数据量

* 曲面按面片上限抽稀；散点/折点的落地线随数据量线性增长，万级点云建议 `scatter: { dropLines: false }`；
* 图元总量建议控制在 1 万以内，超出优先降采样。