# 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 配置。 |
| `panoFilter` | `PBMPanoFilter` | `null` | 全景图滤镜 (亮度、对比度、色温等)。详情见 [Pano Filter](./pano-filter.md)。 |
| `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` | 距离增益。 |
| `gaussianSplattingSHDegree` | `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.modelScene.parameter.set('opacity', 0.5);

// 仅显示原始 UV 贴图
five.modelScene.parameter.set('modelAlpha', 0.0);

// 设置楼层样式
five.modelScene.parameter.set('floorStyle', 'wireframe');
```

### 2. Configuring Point Cloud Appearance (配置点云外观)

```typescript
// 大小随距离衰减
five.modelScene.parameter.set('pointSize', 'ATTENUATION');

// 基础大小
five.modelScene.parameter.set('pointScale', 0.05);

// 最大像素限制
five.modelScene.parameter.set('pointMaxPixel', 20);
```

## Related

*   [Parameter](./parameter.md): 配置系统入口与继承逻辑。
*   [Pano Filter](./pano-filter.md): 了解全景图滤镜的详细用法。
*   [3DTile Params](./3dtile.md): 性能与加载相关参数。

---

```yaml
tags: [材质, 透明度, 点云, 楼层, 阴影, 亮度, 天花板, 开盖, 顶点标记, 渲染样式, material, appearance, pointcloud, parameter, roof, ceiling, config, opacity]
```