@realsee/five 6.8.0-alpha.2 → 6.8.0-alpha.21

package/docs/media/pass.ts

@@ -1,64 +0,0 @@
-import * as THREE from 'three';
-import { FullScreenQuad } from '../../tools/full-screen-quad';
-
-
-/**
- * Pass基类
- * three.js 的 Pass 接口，用于 EffectComposer
- */
-export interface Pass {
-  enabled: boolean;
-  needsSwap: boolean;
-  clear: boolean;
-  renderToScreen: boolean;
-  setSize(width: number, height: number): void;
-  render(
-    renderer: THREE.WebGLRenderer,
-    writeBuffer: THREE.WebGLRenderTarget,
-    readBuffer: THREE.WebGLRenderTarget,
-    deltaTime?: number,
-    maskActive?: boolean
-  ): void;
-}
-
-
-/**
- * FivePass
- *
- * Five 引擎优化的 Pass 基类
- * 支持 G-Buffer 注入，避免重复渲染场景
- */
-export class FivePass implements Pass {
-
-  public static FullScreenQuad = FullScreenQuad;
-
-  public enabled: boolean = true;
-  public needsSwap: boolean = true;
-  public clear: boolean = false;
-  public renderToScreen: boolean = true;
-  public dependencies: ('depth' | 'normal' | 'color')[];
-
-  /**
-   * G-Buffer 纹理集合
-   * 包含 depth、normal、color 等纹理
-   * 由 EffectComposer 在 render 时注入
-   */
-  public gbuffer!: Map<'depth' | 'normal' | 'color', THREE.Texture>;
-
-  constructor(dependencies?: ('depth' | 'normal' | 'color')[]) {
-    this.dependencies = dependencies ?? [];
-  }
-
-  public setSize(width: number, height: number): void {};
-
-  public render(
-    renderer: THREE.WebGLRenderer,
-    writeBuffer: THREE.WebGLRenderTarget,
-    readBuffer: THREE.WebGLRenderTarget,
-    deltaTime?: number,
-    maskActive?: boolean
-  ): void {}
-
-  public dispose(): void {}
-
-}

package/guides/ai-doc-guidelines.md

@@ -1,72 +0,0 @@
-<!-- AI-friendly guide template for `guides/` -->
-# AI 文档与维护指南 (AI Documentation & Maintenance Guide)
-
-## Summary
-本文档包含两部分内容：
-1.  **Writing Guide**: 供 AI 和人类编写新文档时的标准模板与风格规范。
-2.  **Maintenance Guide**: 供 AI 维护者进行文档更新、同步与体检的操作指南。
-
----
-
-# Part 1: Writing Guide (编写指南)
-
-## 目的
-提供统一、结构化的 Markdown 模板，便于 AI 自动解析、索引与生成功能性示例。
-
-## 建议风格
-- 使用中文为主，代码示例使用 TypeScript。
-- **受众意识**: 文档面向 SDK 的**外部使用者**。避免暴露无用的内部实现细节（如私有属性、临时状态），除非对调试有帮助。
-- **结构规范**: 严格使用二级标题 (`##`) 作为主要段落分割（如 `## Schema`, `## Concepts`），避免使用中文标题（如 `## 格式说明`）。
-- **代码缩进**: 强制使用 **两个空格** 缩进。
-- **相对路径**: 内部文档链接必须使用 **相对路径**（如 `./state.md`）。
-- **Schema**: 必须提供 TypeScript Interface 定义，并保留关键字段的注释（JSDoc）。
-- **Metadata**: 结尾必须包含 YAML 格式的 `tags`。
-
-## 标准模板结构 (Standard Template Structure)
-
-新建文档时，请参考独立模板文件：[template.md](./template.md)。
-
-请严格遵循该模板的结构，以保证文档风格一致性。
-
----
-
-# Part 2: Maintenance Guide (维护指南)
-
-## 核心原则 (Core Principles)
-为了防止文档与代码脱节，我们遵循 **“代码变更驱动文档更新”** 的原则。
-
-## 1. 语义化检索 (Semantic Retrieval)
-不再维护硬编码的“源码-文档”映射表。AI 维护者在修改代码后，应利用自身的语义搜索能力（如 `SearchCodebase` 或 `Grep`）来定位需要更新的文档。
-
-**推荐策略**:
-- 搜索**类名/方法名**: 如修改了 `five.load`，搜索 `five.load` 或 `load`。
-- 搜索**概念关键词**: 如修改了射线检测逻辑，搜索 `Raycast` 或 `project2d`。
-
-## 2. 单一事实来源 (Single Source of Truth)
-- **API 签名**: 以 `package/five/index.d.ts` 和代码中的 TSDoc 为准。
-- **guides/api.md**: 仅作为 **索引 (Index)** 和 **摘要 (Summary)**。不要试图复制所有参数细节，除非是核心参数。
-- **guides/features/*.md**: 重点解释 **“为什么”** 和 **“怎么用”**，避免机械复制类型定义。
-
-## 3. 维护工作流 (Maintenance Workflow)
-
-### 场景 A：代码功能迭代后 (Post-Coding)
-当修改了 SDK 源码后，请执行以下检查：
-1.  **反向查找**: 利用工具搜索关键词（API 名称、Feature 名称），找到 `guides/` 下相关的文档。
-2.  **更新文档**:
-    *   如果修改了 API 签名 -> 更新对应的 `Schema` 和 `Examples`。
-    *   如果废弃了功能 -> 在文档中添加 `> [!WARNING] Deprecated` 提示。
-3.  **更新索引**: 如果是新功能，确保将其添加到 `guides/README.md` 的合适章节中。
-
-### 场景 B：API 文档同步 (Sync API Doc)
-定期检查 `guides/api.md` 的完整性：
-1.  读取 `package/five/index.d.ts` 获取最新公开 API。
-2.  对比 `guides/api.md`，找出缺失的高频 API 或已删除的 API。
-3.  **注意**: 只收录高频/核心 API，低频 API 应引导用户查看源码或专门的 Feature 文档。
-
-## 目录结构说明
-- `guides/`: 文档根目录。
-- `guides/features/`: 功能性文档 (Features)。
-- `guides/release_notes/`: 版本更新记录。
-- `guides/api.md`: 核心 API 索引。
-- `guides/README.md`: 文档总索引。
-- `package/five/index.d.ts`: **API 签名的真理来源**。

package/guides/features/3dtile.md

@@ -1,264 +0,0 @@
-# 3DTile
-
-- **Summary**: Five 用于加载和渲染大规模三维场景的核心模块，支持动态 LOD 调度与流式加载。
-- **Schema**: 通过 Parameter 配置 LOD、显存与并发控制。
-- **Concepts**: LOD, SSE, Cache Management, ViewLayer。
-- **Examples**: 画质平衡与多图层优化。
-
-## Schema
-
-3DTile 的核心配置通过 `Parameter` 系统进行控制。以下是 `ParameterValue` 接口中与 3DTile 调度相关的关键字段。
-
-```typescript
-interface Tile3DParameterValue {
-  // --- 核心画质控制 ---
-  /**
-   * 屏幕空间误差阈值 (Screen Space Error, SSE)
-   * 单位: 像素
-   * 默认值: 16
-   * 说明: 控制加载精度的核心参数。
-   * - 值越小: 画质越高，加载更精细的瓦片，网络/渲染压力越大。
-   * - 值越大: 画质越低，性能越好。
-   */
-  maxScreenSpaceError: number;
-
-  // --- 显存与内存管理 ---
-  /**
-   * 最大显存占用
-   * 单位: MB
-   * 默认值: 512
-   * 说明: 当已加载瓦片的显存占用超过此阈值时，引擎会自动卸载不可见或低优先级的瓦片。
-   */
-  maxMemoryUsage: number;
-
-  /**
-   * 是否开启基于内存的动态 SSE 调整
-   * 默认值: false
-   * 说明: 开启后，引擎会根据当前显存占用情况自动调整 maxScreenSpaceError。
-   * - 目标: 尽量占满 maxMemoryUsage 设定的显存配额。
-   * - 行为: 实际使用的 SSE 会在 1.0 到 maxScreenSpaceError 之间动态变化。
-   */
-  memoryAdjustedScreenSpaceError: boolean;
-
-  // --- 几何误差控制 ---
-  /**
-   * 最小几何误差 (精度上限锁)
-   * 默认值: 0
-   * 说明: 当瓦片的几何误差小于此值时，强制停止细分。
-   * - 作用: 限制加载的最精细层级，防止过度细分。
-   * - 场景: 数据本身层级过深，或者不需要看清极微小细节时，调大此值可显著节省性能。
-   */
-  minGeometricError: number;
-
-  /**
-   * 最大几何误差 (最低精度保证)
-   * 默认值: 10000
-   * 说明: 当瓦片的几何误差大于此值时，强制继续细分，直到误差小于此值。
-   * - 作用: 设定模型允许的最粗糙程度。
-   * - 场景: 无论相机距离多远，都希望模型至少保持一定的精细度（例如不希望看到过于简化的多边形）时，调小此值。
-   */
-  maxGeometricError: number;
-
-  // --- LOD 层级控制 (不推荐) ---
-  /**
-   * 最小 LOD 层级
-   * 默认值: 0
-   * 说明: 限制加载的最小层级深度 (Tree Depth)。即小于此层级的瓦片（更粗糙的）不会被显示。
-   * - 建议: 推荐优先使用 maxGeometricError。两者都用于控制模型显示的“最粗糙”程度（下限）。
-   */
-  minLevelOfDetail: number;
-
-  /**
-   * 最大 LOD 层级
-   * 默认值: 20
-   * 说明: 限制加载的最大层级深度 (Tree Depth)。即大于此层级的瓦片（更精细的）不会被加载。
-   * - 建议: 推荐优先使用 minGeometricError。两者都用于控制模型显示的“最精细”程度（上限）。
-   */
-  maxLevelOfDetail: number;
-
-  // --- 剔除策略 ---
-  /**
-   * 视锥体剔除
-   * 默认值: true
-   * 说明: 是否不加载/渲染相机视锥体之外的瓦片。
-   */
-  cameraCulling: boolean;
-
-  /**
-   * 是否预加载兄弟节点
-   * 默认值: true
-   * 说明: 是否在加载当前瓦片时，同时预加载其兄弟节点（同一层级的其他瓦片）。
-   */
-  loadSiblings: boolean;
-  /**
-   * 是否允许跳级加载
-   * 默认值: false
-   * 说明: 是否在加载当前瓦片时，允许跳级加载。
-   * - 作用: 在快速移动视角或直接跳转到深层级位置时，跳过中间层级的瓦片，直接加载目标精度的瓦片。
-   * - 场景: 倾斜摄影等外表面模型，为了减少请求数并加快最终形态的呈现（可能会看到明显的从空白到精细的跳变）。
-   */
-  skipLevelOfDetail: boolean;
-
-  // --- 网络并发控制 ---
-  /**
-   * 最大并发请求数
-   * 范围: 0 - 20
-   * 默认值: 4
-   * 说明: 同时进行的最大网络下载请求数。建议保持默认，过大可能阻塞主线程或导致拥堵。
-   */
-  maxRequests: number;
-
-  /**
-   * 请求优先级策略
-   * 默认值: 'SCREEN_SPACE_ERROR'
-   * 选项:
-   * - 'SCREEN_SPACE_ERROR': 优先加载 SSE 最大的瓦片 (最影响视觉质量的部分)。
-   * - 'SCREEN_LEVEL_VERTICAL': 优先加载垂直方向层级较高的瓦片 (通常用于多楼层建筑，优先加载当前楼层)。
-   * - 'SCREEN_VERTICAL': 优先加载屏幕垂直方向的瓦片。
-   */
-  requestOrder: 'SCREEN_SPACE_ERROR' | 'SCREEN_LEVEL_VERTICAL' | 'SCREEN_VERTICAL';
-}
-```
-
-## Concepts
-
-### 1. LOD & Screen Space Error (SSE)
-
-LOD (Level of Detail) 是 3DTile 的核心机制。引擎不会一次性加载整个从宏观到微观的所有模型数据，而是根据相机位置动态计算每个瓦片的 **屏幕空间误差 (SSE)**。
-
-*   **Geometric Error (几何误差)**: 3D Tiles 数据源中定义的指标（单位：米），表示当前瓦片与真实物体之间的最大形状差异。
-    *   **根节点**: 误差巨大（如 100米），仅有模糊轮廓。
-    *   **叶子节点**: 误差极小（如 0.01米），细节丰富。
-*   **SSE 计算逻辑**: `SSE = (GeometricError / DistanceToCamera) * ScreenHeight`。
-*   **判定标准**: 如果 `SSE > maxScreenSpaceError`，说明当前瓦片在屏幕上看起来太粗糙（误差像素太大），需要分裂并加载下一级子瓦片；反之则停止细分。
-*   **调整影响**: 调低 `maxScreenSpaceError` 会迫使引擎加载更深层级的瓦片，从而获得更清晰的细节，但也会急剧增加渲染三角形数量和显存占用。
-
-### 2. 显存管理 (Cache Management)
-
-为了在浏览器有限的资源下渲染海量数据（如城市级倾斜摄影），3DTile 实现了基于 LRU (Least Recently Used) 的缓存淘汰机制和动态画质调整策略。
-
-*   **LRU 淘汰**: 当 `maxMemoryUsage` 超限时，引擎会优先保留当前视锥体内的瓦片。视锥体外的、或者距离相机较远的瓦片会被优先释放。
-*   **动态画质调整 (Dynamic Scaling)**: 如果开启了 `memoryAdjustedScreenSpaceError`，引擎会以 `maxMemoryUsage` 为目标，实时调整 SSE。
-    *   **目标**: 尽量跑满 `maxMemoryUsage` 设定的显存额度，不浪费资源。
-    *   **范围**: 实际 SSE 会在 `1.0` (极高画质) 到 `maxScreenSpaceError` (设定底线) 之间波动。
-    *   **场景**: 适合显存充足但希望自动平衡画质的场景。
-
-### 3. 并发控制 (Max Requests)
-
-为了平衡网络加载与渲染性能，3DTile 限制了最大并发请求数。
-
-*   **默认值**: 4
-*   **建议**: 保持默认值，避免设置过大导致网络拥堵。
-*   **影响**: 增加并发数可能提升加载速度，但也会增加服务器压力。
-
-### 4. 格式支持 (Supported Formats)
-
-Five 的 3DTile 引擎支持多种 3D Tiles 1.0/1.1 规范的瓦片格式及主流压缩标准。
-
-*   **瓦片格式**:
-    *   **B3DM (Batched 3D Model)**: 传统的 3D Tiles 格式，用于建筑模型。
-    *   **PNTS (Point Cloud)**: 传统的点云格式。
-    *   **GLB / GLTF**: 3D Tiles 1.1 标准推荐的格式，支持 Mesh 和点云。
-*   **压缩与优化**:
-    *   **[Draco](https://google.github.io/draco/)**: 几何压缩，显著减小模型体积。
-    *   **[Meshopt](https://github.com/zeux/meshoptimizer)**: 另一种高效的几何压缩算法。
-    *   **[KTX2](https://github.com/KhronosGroup/KTX-Software) / [BasisU](https://github.com/BinomialLLC/basis_universal)**: 纹理压缩，大幅降低显存占用并提升上传速度。
-
-### 5. ViewLayer 与 3DTile
-
-目前所有的 `ViewLayer` 在底层都是一个 `Tile3D` 实例。它们各自拥有独立的：
-*   **配置**: `maxScreenSpaceError`, `maxMemoryUsage` 等参数互不干扰。
-*   **缓存**: 显存配额各自独立计算。
-
-> **注意**: 即使是通过 `file_url` 加载的单体模型（如 `.obj`, `.at3d`），在 Five 内部也会被封装为 `Tile3D` 实例进行统一管理。
-
-### 6. Lod 参数调整
-
-优先修改 `maxScreenSpaceError` 而不是 `minLevelOfDetail` `maxGeometricError`。 SSE 是更直接、更符合渲染逻辑的 LOD 控制指标，而 `minLevelOfDetail` `maxGeometricError` 更关注数据切片方式，容易引入错误的 LOD 决策。
-
-可以适当开启 `memoryAdjustedScreenSpaceError` 动态调整 SSE，以平衡画质与显存占用。但是同时，需要合理配置 `maxScreenSpaceError` 与 `maxMemoryUsage`，避免出现内存整体占用过高导致 Crash 问题。
-- `maxScreenSpaceError` 尽量设置较为大的值，比如 32 / 48，根据场景和设备性能调整。
-- `maxMemoryUsage` 建议根据设备显存和场景复杂度调整。
-
-在特定场景，比如 **全景模式下** 不需要很高清的模型，可以定义上限的 `maxLevelOfDetail` `minGeometricError` 来限制加载层级优化性能。
-
-
-## Examples
-
-### 调整画质与内存平衡
-
-在移动端或性能受限设备上，建议适当降低画质以保证流畅度。
-
-```typescript
-const parameter = five.modelScene.parameter;
-
-// 1. 性能优先模式 (适用于低端设备)
-// 增大 SSE 阈值，降低画质
-parameter.set('maxScreenSpaceError', 16);
-// 限制显存，防止 Crash
-parameter.set('maxMemoryUsage', 256);
-
-// 2. 画质优先模式 (适用于桌面端/截图)
-// 减小 SSE 阈值，提升细节
-parameter.set('maxScreenSpaceError', 4);
-// 允许更多显存占用
-parameter.set('maxMemoryUsage', 1024);
-
-// 3. 重置为默认
-parameter.reset('maxScreenSpaceError', 'maxMemoryUsage');
-```
-
-### 多 ViewLayer 优化
-
-在对比查看或多楼层场景中，通常存在多个 `ViewLayer`。为了避免资源竞争，建议对非焦点的 ViewLayer 进行降级处理。
-
-```typescript
-// 假设 viewLayerA 是当前主要查看的模型，viewLayerB 是背景参考
-
-// 聚焦 ViewLayerA: 正常画质
-viewLayerA.parameter.reset('maxScreenSpaceError');
-
-// 降级 ViewLayerB: 仅显示轮廓，节省资源
-viewLayerB.parameter.set('maxScreenSpaceError', 48); // 极低画质
-viewLayerB.parameter.set('maxMemoryUsage', 128);     // 极低显存配额
-```
-
-## Debugging
-
-在开发过程中，可以通过访问 `ViewLayer` 内部的 `tileset` 对象来实时监控渲染状态。
-
-```typescript
-// 假设已获取 viewLayer 实例
-const tileset = viewLayer.tileset;
-
-// 1. 查看当前加载的瓦片数量
-console.log(tileset.loadedTiles.size);
-
-// 2. 查看当前实际生效的 SSE (如果开启了动态调整，此值会波动)
-console.log(tileset.currentMaxScreenSpaceError);
-
-// 3. 查看显存占用 (近似值，单位字节)
-// 注意: 这是内部私有属性，仅供调试参考
-console.log((tileset as any).cacheMemoryUsageInBytes / 1024 / 1024 + ' MB');
-```
-
-## Common Pitfalls
-
-1.  **误解 GeometricError 作用域**: `minGeometricError` 和 `maxGeometricError` 是**全局硬约束**，不随相机距离变化。
-    *   错误设置（例如将 `maxGeometricError` 设得极小）会强制全场景所有瓦片（哪怕是远处的背景）都加载到极高精度。
-    *   这会导致三角形数量和显存占用**指数级爆炸**，瞬间卡死浏览器。
-2.  **过度降低 `maxScreenSpaceError`**: 设置过小（如 < 4）可能导致每帧需要加载和渲染的三角形数量指数级上升，瞬间撑爆显存或导致掉帧。
-3.  **忽略 `cameraCulling`**: 默认应该开启。如果手动关闭视锥体剔除，引擎将尝试加载全场景数据，极易导致崩溃。
-4.  **频繁切换配置**: `maxMemoryUsage` 等参数的修改会触发缓存整理，高频修改可能导致卡顿。
-
-## Related
-
-*   [parameter.md](./parameter.md): 了解参数的继承关系及材质、点云相关配置。
-*   [model.md](./model.md): 了解 Model 和 ViewLayer 的关系。
-*   [work.md](./work.md): 了解 Work 数据结构。
-
----
-
-```yaml
-tags: [3dtile, viewLayer, performance, lod, optimization]
-```

package/guides/features/parameter.md

@@ -1,178 +0,0 @@
-# Parameter (配置)
-
-- **Summary**: Five 用于控制三维模型渲染表现的核心配置系统，采用树形继承设计。
-- **Schema**: 包含材质、楼层、阴影、LOD 等配置项。
-- **Concepts**: Hierarchy (树形继承), Material, LOD, Point Cloud。
-- **Examples**: 全局设置与局部差异化配置。
-
-## Schema
-
-### Parameter Class
-
-`Parameter` 是一个配置容器，提供了读写配置项的方法。
-
-```typescript
-// 简化定义
-class Parameter implements Readonly<Partial<ParameterValue>> {
-  // 可以直接通过属性访问配置项，例如 parameter.opacity
-  readonly [key in keyof ParameterValue]?: ParameterValue[key];
-
-  /** 设置配置项 */
-  set<K extends keyof ParameterValue>(key: K, value: ParameterValue[K]): void;
-  set(values: Partial<ParameterValue>): void;
-
-  /** 重置当前层级的配置项 (恢复继承) */
-  reset(...keys: (keyof ParameterValue)[]): void;
-
-  /**
-   * 获取最终计算值 (包含继承逻辑)
-   * @param upstream - 上游 Parameter 对象列表
-   */
-  resolveValue(...upstream: Parameter[]): ResolvedParameterValue;
-}
-```
-
-### ParameterValue Interface
-
-所有的配置项定义在 `ParameterValue` 接口中。
-
-```typescript
-import * as THREE from 'three';
-
-export interface ParameterValue {
-  // --- 基础材质表现 ---
-  /** 模型透明度 [0-1] */
-  opacity: number;
-  /** 模型整体亮度 */
-  brightness: number;
-  /** 颜色饱和度调整 */
-  colorSaturation: number;
-  /** 颜色亮度调整 */
-  colorBrightness: number;
-
-  // --- 全景混动与过渡 ---
-  /** 模型贴图和全景图的混合程度 [0-1] (0:纯模型纹理, 1:纯全景纹理) */
-  modelAlpha: number;
-
-  // --- 楼层控制 ---
-  /** 当前显示的楼层索引 (null 为显示所有) */
-  shownFloorIndex: number | null;
-  /** 楼层隐藏样式 ('OPACITY': 透明, 'VISIBILITY': 隐藏) */
-  floorStyle: 'OPACITY' | 'VISIBILITY';
-
-  // --- 阴影 ---
-  /** 是否产生阴影 */
-  castShadow: boolean;
-  /** 是否接受阴影 */
-  receiveShadow: boolean;
-
-  // --- 点云特有 ---
-  /** 点云大小 */
-  pointSize: number;
-  /** 点云基础缩放 */
-  pointScale: number;
-
-  // --- 3DTile / LOD 控制 ---
-  /** 最小细节层级 */
-  minLevelOfDetail: number;
-  /** 最大细节层级 */
-  maxLevelOfDetail: number;
-  /** 几何误差阈值 (越小越精细) */
-  minGeometricError: number;
-  /** 最大网络并发请求数 */
-  maxRequests: number;
-  /** 最大内存使用量 (MB) */
-  maxMemoryUsage: number;
-
-  // ... 更多高级参数请参考 five/index.d.ts
-}
-```
-
-## Concepts
-
-### 1. 树形继承关系 (Hierarchy)
-
-Parameter 遵循 **“就近原则” (Override)** 的继承逻辑。当渲染引擎需要获取某个属性值时，会按照以下顺序查找：
-
-1.  **ViewLayer Parameter**: 最具体，优先级最高。
-2.  **Model Parameter**: 覆盖该 Model 下的所有 ViewLayer。
-3.  **ModelScene Parameter**: 全局默认值，优先级最低。
-
-```mermaid
-graph TD
-  Scene[ModelScene.parameter] -->|Inherit| Model[Model.parameter]
-  Model -->|Inherit| Layer1[ViewLayer.parameter]
-  Model -->|Inherit| Layer2[ViewLayer.parameter]
-```
-
-**示例逻辑**:
-*   如果 `ModelScene` 设置 `opacity = 0.5`，所有模型都会变半透明。
-*   如果此时 `Model A` 设置 `opacity = 1.0`，那么 `Model A` 及其下的 ViewLayer 会变为不透明，而其他 Model 保持半透明。
-
-### 2. 参数分类
-
-#### 材质与外观 (Material & Appearance)
-控制模型“长什么样”。比如：
-*   **`modelAlpha`**: 核心参数。Five 的模型纹理通常来自全景图投影。该值控制是显示原始模型 UV 贴图，还是显示全景投影贴图。
-*   **`shownFloorIndex`**: 实现“分层拆解”效果。
-*   **`floorStyle`**: 控制楼层隐藏的表现形式。
-
-#### 3DTile & 性能 (LOD)
-控制模型“怎么加载”。比如：
-*   **`maxMemoryUsage`**: 显存控制。当加载的模型块超过此限制时，会自动卸载不可见的块。
-*   **`maxScreenSpaceError`**: 画质控制。值越小，加载的模型精度越高（允许的屏幕空间误差越小），但网络和渲染开销越大。
-*   **`minGeometricError`**: 几何误差阈值。值越小，加载的模型精度越高（允许的几何误差越小），但网络和渲染开销越大。
-*   **`maxRequests`**: 最大并发请求数。控制同时加载的模型块数量，避免对服务器压力过大。
-
-#### 点云 (Point Cloud)
-专用于 `type: point_cloud` 的 ViewLayer。比如：
-*   **`pointSize`**: 控制点的像素大小。
-*   **`pointScale`**: 点云整体缩放。
-
-## Examples
-
-### 基础用法：设置全局透明度
-
-```typescript
-// 将整个场景的模型设为半透明
-five.modelScene.parameter.set('opacity', 0.5);
-
-// 恢复默认
-five.modelScene.parameter.remove('opacity');
-```
-
-### 进阶用法：差异化配置
-
-```typescript
-// 1. 全局开启阴影
-five.modelScene.parameter.set('castShadow', true);
-
-// 2. 但让第一个模型不产生阴影
-const mainModel = five.models[0];
-if (mainModel) {
-  mainModel.parameter.set('castShadow', false);
-}
-
-// 3. 让特定的点云图层点变大
-const pointCloudLayer = mainModel.viewLayers.find(l => l.type === 'point_cloud');
-if (pointCloudLayer) {
-  pointCloudLayer.parameter.set('pointSize', 2.0);
-}
-```
-
-## Common Pitfalls
-
-1.  **拼写错误**: `parameter.set()` 的 key 是字符串，拼写错误不会报错（除非使用 TypeScript），但配置不会生效。
-2.  **层级混淆**: 在 `ModelScene` 上设置了 `shownFloorIndex`，却期望只影响某个 Model。请务必确认操作的 `parameter` 对象所属的层级。
-3.  **类型错误**: 某些数值参数（如 `opacity`）需要 `number` 类型，传入字符串可能导致渲染计算 NaN 错误。
-
-## Related
-
-*   [Model](./model.md): Parameter 的宿主之一。
-*   [3DTile](./3dtile.md): 受 Parameter 控制的底层技术。
-
----
-
-```yaml
-tags: [parameter, config, appearance, 3dtile]
-```