@realsee/five 6.8.0-alpha.0 → 6.8.0-alpha.10

package/ai_guides/features/load-external-model.md

@@ -0,0 +1,350 @@
+# 加载外部模型 (Load External Models)
+
+- **Summary**: 提供了一系列独立的加载函数 (`loadGltf`, `loadPly`, `loadFbx` 等)，用于加载各种格式的外部 3D 模型（如 .glb, .ply, .splat, .fbx），并将其转换为 Three.js 对象以便添加到 Five 场景中。
+- **Schema**: 涉及 `LoadResultType` 返回结构及各加载器的配置项 (`LoaderOptions`)。
+- **Concepts**: 独立加载函数、坐标系转换 (UpAxis)、资源销毁 (Dispose)、Fetcher。
+- **Configuration**: `modelUpAxis`, `upAxis`, `fetcher` 等通用及特定配置。
+- **Examples**: 加载 GLTF 模型、加载高斯泼溅 (Gaussian Splat)、加载点云。
+
+## Schema
+
+> **Definition**: [LoadResultType](../../five/model/loaders/shared.d.ts)
+
+所有加载函数均返回 `Promise<LoadResultType>`。
+
+```typescript
+// 通用返回类型
+export type LoadResultType<Scene = THREE.Object3D> = {
+  type: 'gltf' | 'obj' | 'ply' | 'fbx' | 'pbm' | 'splat' | 'spz' | 'b3dm' | 'pnts' | 'at3d' | 'dome' | 'domez' | 'x3p'; // 模型类型
+  modelUpAxis: 'Y' | 'Z';     // 原始模型的上轴
+  upAxis: 'Y' | 'Z';          // 输出模型的上轴 (通常为 Z)
+  byteLength: number;         // 文件字节大小
+  memoryUsage: number;        // 显存/内存占用估算
+  uri: string;                // 模型地址
+  scene: Scene;               // Three.js 对象 (Group 或 Object3D)，可直接添加到场景
+  textures: THREE.Texture[];  // 加载的纹理列表
+  animations: THREE.AnimationClip[]; // 动画剪辑列表
+  rtcCenter?: THREE.Vector3;  // 若存在 RTC (Relative To Center) 坐标偏移
+  dispose: () => void;        // 销毁资源函数
+}
+
+// 通用配置项接口
+interface BaseLoaderOptions {
+  upAxis?: 'Y' | 'Z';         // 期望输出的上轴，默认为 'Z' (Five 坐标系)
+  modelUpAxis?: 'Y' | 'Z';    // (部分加载器支持) 原始模型的上轴，用于自动旋转修正
+  fetcher?: Fetcher;          // 自定义网络请求 Fetcher
+  light?: boolean;            // 是否使用简化/无光照材质 (取决于加载器实现)
+  onDownloadProgress?: (progress: { loaded: number, total: number }) => void; // 下载进度回调
+}
+```
+
+## Concepts
+
+### 独立加载函数 (Standalone Functions)
+这些加载函数（如 `loadGltf`, `loadPly`）是 `@realsee/five` 包导出的**独立函数**，而非 `Five` 实例的方法。你需要单独引入它们使用。
+
+### 坐标系转换 (Up-Axis Conversion)
+Five 使用 **Z-up** (Z 轴向上) 的右手坐标系。
+许多外部模型（如 standard GLTF, FBX）通常是 **Y-up** 的。
+加载器提供了 `upAxis` 和 `modelUpAxis` 选项来自动处理旋转：
+- `upAxis`: 你期望得到的结果坐标系上轴（通常保持默认 'Z'）。
+- `modelUpAxis`: 原始文件的上轴（如 GLTF 默认为 'Y'，PLY 默认为 'Z'）。
+如果不指定，加载器会尝试使用合理的默认值将模型旋转到 Z 轴向上。
+
+### 资源销毁 (Disposal)
+加载的模型包含 Geometry、Material 和 Texture 等 WebGL 资源。当你不再需要该模型时（例如切换场景或移除物体），**必须**调用返回结果中的 `dispose()` 方法来释放内存，否则会导致内存泄漏。
+
+### Fetcher
+所有加载器支持传入自定义 `fetcher`。这在需要鉴权、自定义 Header 或处理特定 CDN 逻辑时非常有用。如果不传，默认使用内部的 `internalFetcher`。
+
+## Configuration
+
+### loadGltf
+加载 `.gltf` 或 `.glb` 文件。支持 Draco 压缩。
+支持扩展：
+*   `KHR_binary_glTF`
+*   `KHR_draco_mesh_compression`
+*   `KHR_texture_basisu`
+*   `KHR_texture_transform`
+*   `KHR_mesh_quantization`
+*   `KHR_materials_unlit`
+*   `KHR_node_visibility`
+*   `KHR_animation_pointer`
+*   `EXT_meshopt_compression`
+*   `KHR_materials_clearcoat`
+*   `KHR_materials_sheen`
+*   `KHR_materials_transmission`
+*   `KHR_materials_emissive_strength`
+*   `EXT_texture_webp`
+*   `CESIUM_RTC`
+*   `REALSEE_materials_lightmap`
+*   `KHR_gaussian_splatting_compression_spz`
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `modelUpAxis` | `'Y' | 'Z'` | `'Y'` | 原始模型的上轴。GLTF 标准通常为 Y。 |
+| `upAxis` | `'Y' | 'Z'` | `'Z'` | 输出模型的上轴。 |
+| `light` | `boolean` | `undefined` | 是否强制使用 Unlit 材质或移除光照扩展。 |
+| `fetcher` | `Fetcher` | - | 自定义 Fetcher。 |
+
+### loadPly
+加载 `.ply` 文件。支持网格、线框、点云及 PBM 扩展格式。
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `type` | `'geometry' | 'line' | 'pbmMesh' | 'pbmPointCloud'` | 自动推断 | 指定解析类型。 |
+| `customPropertyMapping` | `Object` | - | 自定义属性映射（用于解析非标准 PLY 属性）。 |
+| `propertyNameMapping` | `Object` | - | 属性名重映射 (e.g. `{'diffuse_red': 'red'}`)。 |
+| `modelUpAxis` | `'Y' | 'Z'` | `'Z'` | PLY 通常为 Z-up。 |
+| `upAxis` | `'Y' | 'Z'` | `'Z'` | 输出模型的上轴。 |
+| `light` | `boolean` | `undefined` | 是否使用简化材质。 |
+| `fetcher` | `Fetcher` | - | 自定义 Fetcher。 |
+
+### loadSplat
+加载 `.splat` 格式的高斯泼溅 (Gaussian Splat) 模型。
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `modelUpAxis` | `'Y' | 'Z'` | `'Y'` | Splat 模型通常为 Y-up。 |
+| `upAxis` | `'Y' | 'Z'` | `'Z'` | 输出模型的上轴。 |
+| `fetcher` | `Fetcher` | - | 自定义 Fetcher。 |
+
+### loadSpz
+加载 `.spz` 格式的高斯泼溅 (Gaussian Splat) 模型。`.spz` 是对 `.splat` 的压缩格式。
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `modelUpAxis` | `'Y' | 'Z'` | `'Y'` | 原始模型的上轴。 |
+| `upAxis` | `'Y' | 'Z'` | `'Z'` | 输出模型的上轴。 |
+| `fetcher` | `Fetcher` | - | 自定义 Fetcher。 |
+
+### loadFbx
+加载 `.fbx` 文件。
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `upAxis` | `'Y' | 'Z'` | `'Z'` | 输出上轴。 |
+| `light` | `boolean` | `undefined` | 是否使用简化材质。 |
+| `fetcher` | `Fetcher` | - | 自定义 Fetcher。 |
+
+### loadObj
+加载 `.obj` 文件。会自动尝试加载同目录下的 `.mtl` 材质文件。
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `modelUpAxis` | `'Y' | 'Z'` | `'Z'` | 原始模型的上轴。 |
+| `upAxis` | `'Y' | 'Z'` | `'Z'` | 输出模型的上轴。 |
+| `light` | `boolean` | `undefined` | 是否使用简化材质。 |
+| `fetcher` | `Fetcher` | - | 自定义 Fetcher。 |
+
+### loadPbm
+加载 Realsee 私有 PBM 格式。
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `upAxis` | `'Y' | 'Z'` | `'Z'` | 输出模型的上轴。 |
+| `light` | `boolean` | `false` | 是否使用简化材质。 |
+| `textureBaseUri` | `string` | 自动推断 | 纹理的基础路径。 |
+| `textureArray` | `string[]` | - | 纹理路径列表。 |
+| `textureOptions` | `TextureOptions` | - | 纹理加载配置 (size, quality 等)。 |
+| `fetcher` | `Fetcher` | - | 自定义 Fetcher。 |
+
+### loadDome / loadDomez
+加载 Dome 全景模型 (`.dome` 或 `.domez` 压缩格式)。
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `upAxis` | `'Y' | 'Z'` | `'Z'` | 输出模型的上轴。 |
+| `light` | `boolean` | `true` | 是否使用简化材质。 |
+| `textureBaseUri` | `string` | - | 纹理基础路径。 |
+| `textureOptions` | `TextureOptions` | - | 纹理加载配置。 |
+| `fetcher` | `Fetcher` | - | 自定义 Fetcher。 |
+
+### loadAt3d
+加载 `.at3d` 格式模型。
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `upAxis` | `'Y' | 'Z'` | `'Z'` | 输出模型的上轴。 |
+| `light` | `boolean` | `false` | 是否使用简化材质。 |
+| `textureBaseUri` | `string` | 自动推断 | 纹理基础路径。 |
+| `textureArray` | `string[]` | - | 纹理路径列表。 |
+| `textureOptions` | `TextureOptions` | - | 纹理加载配置。 |
+| `fetcher` | `Fetcher` | - | 自定义 Fetcher。 |
+
+### loadB3dm
+加载 `.b3dm` (Batched 3D Model) 格式。
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `modelUpAxis` | `'Y' | 'Z'` | `'Y'` | 原始模型的上轴。 |
+| `upAxis` | `'Y' | 'Z'` | `'Z'` | 输出模型的上轴。 |
+| `light` | `boolean` | `undefined` | 是否使用简化材质。 |
+| `fetcher` | `Fetcher` | - | 自定义 Fetcher。 |
+
+### loadPnts
+加载 `.pnts` (Point Cloud) 格式。
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `upAxis` | `'Y' | 'Z'` | `'Z'` | 输出模型的上轴。 |
+| `computeBoundingBox` | `boolean` | `true` | 是否计算包围盒。 |
+| `fetcher` | `Fetcher` | - | 自定义 Fetcher。 |
+
+### loadX3p
+加载 `.x3p` 格式。
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `upAxis` | `'Y' | 'Z'` | `'Z'` | 输出模型的上轴。 |
+| `color` | `THREE.Color` | - | 指定颜色。 |
+| `light` | `boolean` | `true` | 是否使用简化材质。 |
+| `fetcher` | `Fetcher` | - | 自定义 Fetcher。 |
+
+## Examples
+
+### 基础用法：加载 GLTF 模型 (Basic Usage)
+
+```typescript
+import { Five, FivePlugin } from '@realsee/five';
+import { loadGltf } from '@realsee/five';
+import * as THREE from 'three';
+
+const five = new Five({/*...*/});
+
+// 加载 GLB 模型
+loadGltf('https://example.com/model.glb').then((result) => {
+  // 1. 获取模型对象
+  const model = result.scene;
+
+  // 2. 设置位置和大小
+  model.position.set(0, 0, 0);
+  model.scale.set(1, 1, 1);
+
+  // 3. 添加到 Five 场景
+  five.scene.add(model);
+
+  // 4. (可选) 渲染一帧以确保显示
+  five.needsRender = true;
+
+  // 保存 result 用于后续销毁
+  // result.dispose();
+}).catch(err => {
+  console.error('加载失败', err);
+});
+```
+
+### 进阶用法：加载高斯泼溅 (Gaussian Splat)
+
+```typescript
+import { loadSplat } from '@realsee/five';
+
+loadSplat('https://example.com/scene.splat', {
+  modelUpAxis: 'Y', // 假设原始数据是 Y-up
+  upAxis: 'Z',      // 转换到 Five 的 Z-up
+}).then((result) => {
+  const splatMesh = result.scene;
+  five.scene.add(splatMesh);
+  five.needsRender = true;
+});
+```
+
+### 进阶用法：自定义 PLY 属性映射 (Custom PLY Properties)
+
+```typescript
+import { loadPly } from '@realsee/five';
+
+loadPly('https://example.com/data.ply', {
+  type: 'pbmPointCloud',
+  customPropertyMapping: {
+    intensity: {
+      itemType: 'float32',
+      itemNames: ['intensity'],
+      normalized: true
+    }
+  }
+}).then((result) => {
+  // result.scene 是一个 PBMPointCloud 对象
+  five.scene.add(result.scene);
+});
+```
+
+### 基础用法：加载 OBJ 模型 (Basic Usage - OBJ)
+
+```typescript
+import { loadObj } from '@realsee/five';
+
+loadObj('https://example.com/model.obj', {
+  modelUpAxis: 'Z', // OBJ 默认通常是 Z-up (或根据实际情况调整)
+}).then((result) => {
+  five.scene.add(result.scene);
+  // OBJ 文件中定义的 .mtl 材质会自动加载
+});
+```
+
+### 基础用法：加载 FBX 模型
+
+```typescript
+import { loadFbx } from '@realsee/five';
+
+loadFbx('https://example.com/model.fbx').then((result) => {
+  five.scene.add(result.scene);
+  // 动画会自动解析到 result.animations
+});
+```
+
+### 进阶用法：加载 Dome 全景 (Panorama)
+
+```typescript
+import { loadDome } from '@realsee/five';
+
+// 加载 .dome 或 .domez 格式
+loadDome('https://example.com/panorama.domez', {
+  light: false, // 全景模型通常不需要光照计算
+  textureOptions: {
+    size: 4096, // 限制最大纹理尺寸
+  }
+}).then((result) => {
+  result.scene.position.set(0, 0, 0);
+  five.scene.add(result.scene);
+});
+```
+
+### 进阶用法：加载压缩模型 (AT3D)
+
+```typescript
+import { loadAt3d } from '@realsee/five';
+
+loadAt3d('https://example.com/model.at3d', {
+  light: false,
+}).then((result) => {
+  five.scene.add(result.scene);
+});
+```
+
+## Debugging
+
+- **查看网络请求**: 检查 Network 面板，确认模型文件是否成功下载 (200 OK)。
+- **检查模型位置**: 如果加载成功但看不到，尝试 `console.log(result.scene)` 检查其 `position` 和 `scale`。模型可能太小、太大或位置偏离相机视野。
+- **坐标轴辅助**: 在模型上添加 `new THREE.AxesHelper(1)` 来确认其自身的坐标轴方向。
+
+## Common Pitfalls
+
+1.  **坐标轴方向错误**: 模型“躺着”或“倒立”。
+    - **解决**: 调整 `modelUpAxis` 参数。如果是 GLTF 试着改为 'Z' 或 'Y'；如果是 PLY 试着改为 'Y'。
+2.  **内存泄漏**: 频繁加载/卸载模型但未调用 `dispose()`。
+    - **解决**: 务必保存 `load` 返回的 result，并在移除模型时调用 `result.dispose()`。单纯 `scene.remove(object)` 不会释放 GPU 内存。
+3.  **纹理路径错误**: 加载 OBJ/PBM 等带外部纹理的文件时，纹理 404。
+    - **解决**: 确保模型文件内的纹理引用是相对路径，或者通过 `resourcePath` / `textureBaseUri` (视具体 loader 而定) 指定纹理目录。
+4.  **Draco 解码器缺失**: 加载压缩的 GLTF 失败。
+    - **解决**: `loadGltf` 内部集成了 DracoLoader，通常不需要额外配置。如果报错，检查构建配置或网络是否拦截了 wasm 文件。
+
+## Related
+
+*   [model.md](./model.md): 关于 Five 内部模型加载机制的说明。
+
+---
+
+```yaml
+tags: [loader, gltf, ply, splat, fbx, external-model]
+```

package/ai_guides/features/load-progress.md

@@ -0,0 +1,140 @@
+# Resource Loading Progress (资源加载进度)
+
+- **Summary**: 监控 3D 模型与全景图的加载状态和实时进度。
+- **Schema**: `Model`, `Tile`, `PanoTextureEvent`
+- **Concepts**: Loaded vs Refined, Level of Detail (LOD), Panorama Lifecycle
+- **Configuration**: `minLevelOfDetail`, `maxScreenSpaceError`
+- **Examples**: 状态检查、进度监听、生命周期事件
+
+## Schema
+
+> **Definition**: [Model](../../five/model/index.d.ts), [Tile](../../five/model/tile3d/tile.d.ts), [PanoTextureEvent](../../five/controllers/events.d.ts)
+
+## Concepts
+
+在 3D Tiles 模型（如 Five 的 Work 模型）中，"加载" 分为两个阶段：
+
+1.  **Loaded (初步加载完成)**:
+    *   表示模型已经加载了足够用于显示的**基础**数据。
+    *   受 `minLevelOfDetail` 参数影响。只有当满足最小 LOD 要求的 Tile 加载完毕后，`loaded` 才会变为 `true`。
+    *   通常作为 "首屏加载完成" 的标志，此时模型可能还比较模糊。
+
+2.  **Refined (细化完成)**:
+    *   表示模型在当前视角下，已经加载了所有必要的**高清**数据，达到了最佳渲染效果。
+    *   受 `maxScreenSpaceError` 参数影响。该值越小，需要的 Tile 精度越高，细化完成所需的时间越长。
+    *   这是一个动态状态。当相机移动时，可能会因为需要加载新的高清分块而从 `refined: true` 变为 `false`。
+
+## Instance Properties
+
+### Model Status
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `five.model.loaded` | `boolean` | 检查模型是否已完成初步加载 (Loaded)。 |
+| `five.model.refined` | `boolean` | 检查模型是否已完成细化 (Refined)。 |
+| `five.model.refineProgress` | `[number, number]` | 细化进度元组 `[current, total]` (已加载/总需加载)。 |
+
+## Examples
+
+### 1. Model Loading (模型加载)
+
+#### 检查当前状态 (State Checking)
+
+```ts
+if (five.model.loaded) {
+  console.log("Model is ready (basic data loaded)!");
+}
+
+if (five.model.refined) {
+  console.log("Model is fully refined (high-res data loaded)!");
+}
+```
+
+#### 监控细化进度 (Refine Progress)
+
+`five.model.refineProgress` 提供了当前视图下模型细化的整体进度。
+
+```ts
+const [current, total] = five.model.refineProgress;
+console.log(`Model Refine Progress: ${current} / ${total}`);
+
+if (current === total && total > 0) {
+  console.log("Model is fully refined for current view.");
+}
+```
+
+#### 监听加载完成事件
+
+```ts
+five.on("modelLoaded", () => {
+  console.log("Model has been loaded.");
+});
+```
+
+#### (Advanced) Tile 级别进度
+
+对于 `3dtiles` 类型的模型，你可以访问具体的 Tile 对象来查看进度。
+
+```ts
+// 仅示例，通常在调试或特定渲染逻辑中使用
+const progress = tile.content.loadProgress; // [0, 1]
+```
+
+#### Tile Lifecycle Monitoring (Tile 生命周期监控)
+
+监控单个 Tile 的加载与卸载事件，用于更精细的调试或资源统计。
+
+```ts
+five.on("model.tileLoad", (tile) => {
+  console.log(`Tile loaded: ${tile.debugLabel}, Size: ${tile.content.byteLength}`);
+});
+
+five.on("model.tileUnload", (tile) => {
+  console.log(`Tile unloaded: ${tile.debugLabel}`);
+});
+```
+
+### 2. Panorama Loading (全景图加载)
+
+全景图通常在用户移动到某个点位时按需加载。
+
+#### 监听加载进度
+
+使用 `pano.texture.progress` 事件获取当前全景图的加载进度。
+
+```ts
+five.on("pano.texture.progress", (event) => {
+  const { progress, pano } = event;
+  console.log(`Pano ${pano.panoIndex} loading: ${(progress * 100).toFixed(1)}%`);
+});
+```
+
+#### 生命周期事件
+
+*   **`pano.texture.load`**: 开始加载。
+*   **`pano.texture.success`**: 加载完成。
+*   **`pano.texture.error`**: 加载失败。
+
+```ts
+five.on("pano.texture.load", (event) => {
+  console.log(`Started loading pano ${event.pano.panoIndex}`);
+});
+
+five.on("pano.texture.success", (event) => {
+  console.log(`Finished loading pano ${event.pano.panoIndex}`);
+});
+
+five.on("pano.texture.error", (event) => {
+  console.error(`Failed to load pano ${event.pano.panoIndex}`, event.error);
+});
+```
+
+## Related
+
+*   [Five Class](../api.md): Five 核心类 API 索引。
+
+---
+
+```yaml
+tags: [loading, progress, refined, loaded, event]
+```

package/ai_guides/features/material.md

@@ -0,0 +1,151 @@
+# Material Parameters (材质参数)
+
+- **Summary**: 配置 3D 模型与全景图过渡的视觉表现、渲染样式及特效。
+- **Schema**: 对应 `ParameterMaterialValue` 接口，定义了材质、点云、楼层等外观属性。
+- **Concepts**: Transparency (透明度), Point Cloud (点云), Floor Style (楼层样式), PBR (物理渲染)。
+- **Configuration**: 包含透明度、混合模式、点云大小/形状、阴影设置等详细参数。
+- **Examples**: 模型透明度调整、点云样式定制。
+
+## Schema
+
+> **Definition**: [ParameterMaterialValue](../../five/model/parameter.d.ts)
+
+以下是 `ParameterMaterialValue` 的 TypeScript 定义摘要：
+
+```typescript
+export interface ParameterMaterialValue {
+  /** 模型整体透明度 [0, 1] */
+  opacity: number;
+  /** 点云基础缩放比例 */
+  pointScale: number;
+  /** 点云大小绘制方式 ('ATTENUATION' | 'FIXED') */
+  pointSize: PBMPointSize;
+  /** 楼层显示样式 ('OPACITY' | 'VISIBILITY') */
+  floorStyle: PBMFloorStyle;
+  // ... 更多字段见下方配置表
+}
+```
+
+## Concepts
+
+### 1. Transparency & Blending (透明度与混合)
+
+材质系统提供了两种维度的透明度控制：
+*   **Opacity (`opacity`)**: 控制模型整体的不透明度 (0-1)。
+*   **Model Alpha (`modelAlpha`)**: 控制纹理混合的权重。
+    *   `0`: 仅显示模型自带的 UV 纹理（通常是颜色单一的白模或人工烘焙的纹理）。
+    *   `1`: 仅显示从全景图投影到模型上的纹理（真实感强，但可能存在投影误差）。
+    *   `0.5`: 两者混合。
+
+### 2. Point Cloud Rendering (点云渲染)
+
+Five 支持高性能的点云渲染（PBM），并提供灵活的样式配置：
+*   **Size Attenuation**: 通过 `pointSize: 'ATTENUATION'` 开启近大远小的透视效果，增强空间感。
+*   **Pixel Limits**: 通过 `pointMinPixel` 和 `pointMaxPixel` 限制点在屏幕上的最小/最大像素尺寸，防止远处点消失或近处点过大遮挡视线。
+
+### 3. Floor Management (楼层管理)
+
+对于多楼层场景，可以通过参数控制楼层的显示策略：
+*   **Floor Style (`floorStyle`)**: 控制非当前楼层的显示方式（如 `OPACITY` 半透明、`VISIBILITY` 隐藏等）。
+*   **Shown Floor (`shownFloorIndex`)**: 指定当前高亮显示的楼层索引。
+
+### 4. Vertex Marks & Semantic Filtering (顶点标记与语义过滤)
+
+`vertexMarks` 是一个**全局开关**，用于控制是否启用模型顶点上的语义标记（`_feature_id_rsmask`）逻辑。
+
+*   **机制**: 模型顶点预置了 `_feature_id_rsmask` 属性，不同的值代表不同的语义部分。
+*   **当前支持**: 目前主要支持 `_feature_id_rsmask=1`（通常标记为天花板/房顶）。
+    *   当 `vertexMarks` 开启时，标记为 `1` 的顶点部分会在特定视角（如俯视）下自动隐藏，实现“开盖”效果，优化室内布局观测体验。
+*   **未来扩展**: 该机制设计支持更多标记值，未来可能用于控制其他特定模型部件的显示效果。
+
+## Configuration
+
+以下表格列出了控制材质与外观的可用参数，按使用频率和场景分类。
+
+### Common Configuration (常用配置)
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `opacity` | `number` | `1.0` | 模型整体透明度 [0, 1]。0 为完全透明，1 为完全不透明。 |
+| `pointScale` | `number` | `0.02` | 点的基础缩放比例（控制点的大小）。 |
+| `pointSize` | `PBMPointSize` | `'ATTENUATION'` | 点云大小绘制方式。<br>`'ATTENUATION'`: 随距离衰减（近大远小）；<br>`'FIXED'`: 固定像素大小。 |
+| `pointShape` | `PBMPointShape` | `'CIRCLE'` | 点云形状。<br>`'CIRCLE'`: 圆形；<br>`'SQUARE'`:方形。 |
+| `pointBack` | `PBMPointBack` | `'DARK'` | 点云背面绘制方式。 |
+| `pointMinPixel` | `number` | `0` | 点云最小像素尺寸。 |
+| `pointMaxPixel` | `number` | `40` | 点云最大像素尺寸。 |
+| `pointAppearAnimation` | `boolean` | `true` | 是否开启点云出现动画。 |
+| `vertexMarks` | `boolean` | `true` | 是否显示/生效标注。 |
+| `brightness` | `number` | `1.0` | 场景亮度倍数。 |
+| `floorStyle` | `PBMFloorStyle` | `'OPACITY'` | 楼层显示样式。 |
+| `shownFloorIndex` | `number` | `-1` | 当前显示的楼层索引。`-1` 表示显示所有楼层。 |
+| `castShadow` | `boolean` | `false` | 模型是否产生阴影。 |
+| `receiveShadow` | `boolean` | `false` | 模型是否接收阴影。 |
+| `useAddBlend` | `boolean` | `false` | 是否使用半透明叠加渲染。 |
+| `customShaders` | `PBMCustomShader[]` | `[]` | 自定义 Shader 配置。 |
+| `clippers` | `PBMClipperParameter[]` | `[]` | 模型裁切参数。 |
+| `boundingBox` | `THREE.Box3` | `Infinity` | 模型包围盒。 |
+
+### Advanced Appearance (进阶外观配置)
+
+> 这些参数较少使用，仅在需要精细调整特殊视觉效果时修改。
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `colorSaturation` | `number` | `0.0` | 饱和度调整值。 |
+| `colorBrightness` | `number` | `0.0` | 亮度调整值（与 `brightness` 叠加）。 |
+| `colorStyle` | `PBMColorStyle` | `'RGB'` | 颜色显示样式。 |
+| `constantColor` | `THREE.Vector3` | `(0.6, 0.6, 0.6)` | 模型纯色模式下的颜色值。 |
+| `outlineGain` | `number` | `0.0` | 轮廓线增益。 |
+| `distanceGain` | `number` | `0.0` | 距离增益。 |
+| `gsSHDegree` | `number` | `0` | 3D Gaussian Splatting 的球谐阶数。 |
+
+### Internal & Low-Level (内部与底层配置)
+
+> **注意**: 以下参数主要用于引擎内部状态同步或特定底层逻辑，**不建议开发者手动修改**，以免引起渲染异常。
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `modelAlpha` | `number` | `1.0` | 模型纹理混合系数。通常由 Five 内部模式切换控制。 |
+| `useHQWeight` | `boolean` | `false` | 是否使用高质量权重计算（影响渲染质量）。 |
+| `useHQDepth` | `boolean` | `false` | 是否使用高质量深度遮罩。 |
+| `progress` | `number` | `0` | 全景图混合进度。 |
+| `transition` | `PBMTransition` | `'FADE'` | 全景图过渡混合模式。 |
+| `gradientTexture` | `THREE.Texture` | `default` | 高程着色材质纹理。 |
+| `pano0` | `PBMPanoPicture` | `null` | 起始点全景图信息。 |
+| `pano1` | `PBMPanoPicture` | `null` | 结束点全景图信息。 |
+| `pano0Depth` | `PBMPanoDepth` | `null` | 起始点深度信息。 |
+| `pano1Depth` | `PBMPanoDepth` | `null` | 结束点深度信息。 |
+| `refinedScreen` | `PBMRefinedScreen` | `null` | 细化瓦片的屏幕渲染配置。 |
+
+## Examples
+
+### 1. Adjusting Model Transparency and Style (调整模型透明度与样式)
+
+```typescript
+five.model.set({
+  opacity: 0.5,           // Make model semi-transparent (半透明)
+  modelAlpha: 0.0,        // Show original UV texture only (仅显示原始UV贴图)
+  floorStyle: 'wireframe' // Wireframe mode (线框模式)
+});
+```
+
+### 2. Configuring Point Cloud Appearance (配置点云外观)
+
+```typescript
+five.model.set({
+  pointSize: 'ATTENUATION', // 大小随距离衰减
+  pointScale: 0.05,         // 基础大小
+  pointMaxPixel: 20         // 最大像素限制
+});
+```
+
+## Related
+
+*   [Parameter](./parameter.md): 配置系统入口与继承逻辑。
+*   [3DTile Params](./3dtile.md): 性能与加载相关参数。
+
+---
+
+```yaml
+tags: [material, appearance, pointcloud, parameter, roof, ceiling, config]
+```