@realsee/five/ai_guides/features/pano-filter.md

Realsee Renderer SDK

# Pano Filter (全景图滤镜)

- **Summary**: `PBMPanoFilter` 用于调整全景图的视觉效果，包括亮度、对比度、饱和度、色温、色调等。它作为参数传递给 `ModelScene`，可实时改变全景图的渲染表现。
- **Schema**: `PBMPanoFilter`, `PBMUpdateable`
- **Concepts**: Material Filter, Color Correction
- **Configuration**: Temperature, Tint, Brightness, Contrast, Saturation
- **Examples**: 滤镜开启与参数调整

## Schema

> **Definition**: [PBMPanoFilter](../../five/model/materials/pbmMaterial.d.ts)

`PBMPanoFilter` 类定义了全景图的滤镜参数。所有属性均为对象引用，直接修改其内部属性即可生效。

```typescript
import { PBMUpdateable } from "@realsee/five";

export class PBMPanoFilter extends PBMUpdateable {
  /** 对比度控制 */
  public readonly contrast: {
    /** 对比度偏移 [-1, 1] (默认 0) */
    contrastBias: number;
  };

  /** 饱和度控制 */
  public readonly saturation: {
    /** 饱和度偏移 [-1, 1] (默认 0) */
    saturationBias: number;
  };

  /** 颜色控制 (色温与色调) */
  public readonly color: {
    /** 色温偏移 [-100, 100] (默认 0) */
    temperatureBias: number;
    /** 色调偏移 [-100, 100] (默认 0) */
    tintBias: number
  };

  /** 高光与阴影控制 */
  public readonly highlightShadow: {
    /** 全局亮度偏移 [-255, 255] (默认 0) */
    globalBias: number;
    /** 高光偏移 [-255, 255] (默认 0) */
    highlightBias: number;
    /** 阴影偏移 [-255, 255] (默认 0) */
    shadowBias: number;
  };
}
```

## Concepts

### Material Filter (材质滤镜)
与 [Postprocessing](./postprocessing.md) (后处理) 不同，`PBMPanoFilter` 是作用于全景图材质 (Material) 阶段的滤镜。这意味着它直接影响纹理的采样和着色计算，而不是对最终渲染图像进行二次处理。

### Parameter Binding (参数绑定)
滤镜实例需要通过 `five.modelScene.parameter.set('panoFilter', filter)` 绑定到场景中才能生效。

## Configuration

以下参数均通过修改 `PBMPanoFilter` 实例的属性进行配置。

### Color & Tone (色彩与色调)

| Property | Type | Range | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `color.temperatureBias` | `number` | `[-100, 100]` | `0` | **色温**。正值偏暖 (黄)，负值偏冷 (蓝)。 |
| `color.tintBias` | `number` | `[-100, 100]` | `0` | **色调**。正值偏洋红，负值偏绿。 |
| `saturation.saturationBias` | `number` | `[-1, 1]` | `0` | **饱和度**。`0` 为原色，`-1` 为黑白。 |
| `contrast.contrastBias` | `number` | `[-1, 1]` | `0` | **对比度**。正值增强对比，负值降低对比。 |

### Light & Shadow (光影)

| Property | Type | Range | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `highlightShadow.globalBias` | `number` | `[-255, 255]` | `0` | **亮度 (Brightness)**。整体提升或降低画面亮度。 |
| `highlightShadow.highlightBias` | `number` | `[-255, 255]` | `0` | **高光 (Highlight)**。仅调整画面亮部的亮度。 |
| `highlightShadow.shadowBias` | `number` | `[-255, 255]` | `0` | **阴影 (Shadow)**。仅调整画面暗部的亮度。 |

## Examples

### Basic Usage (基础用法)

创建一个滤镜实例并应用到 Five 场景中。

```typescript
import { Five, PBMPanoFilter } from "@realsee/five";

const five = new Five();
// ... 初始化 five ...

// 1. 创建滤镜实例
const panoFilter = new PBMPanoFilter();

// 2. 配置参数 (例如：增加一点暖色调和亮度)
panoFilter.color.temperatureBias = 10; // 暖色
panoFilter.highlightShadow.globalBias = 20; // 提亮

// 3. 启用滤镜
five.modelScene.parameter.set('panoFilter', panoFilter);

// 4. (可选) 停用滤镜
// five.modelScene.parameter.reset('panoFilter');
```

### Interactive Adjustment (动态调整)

滤镜参数支持实时修改，适合制作调节面板。

```typescript
import { Five, PBMPanoFilter } from "@realsee/five";

// 假设已经有 five 实例
const panoFilter = new PBMPanoFilter();
five.modelScene.parameter.set('panoFilter', panoFilter);

// 模拟 UI 绑定的数据对象
const filterSettings = {
  brightness: 0,
  contrast: 0,
};

// 监听 UI 变化 (示例伪代码)
function onBrightnessChange(value: number) {
  // value range: [-255, 255]
  panoFilter.highlightShadow.globalBias = value;
  // 如果 five 没有开启自动渲染 (play: false)，需要手动触发重绘
  five.needsRender = true;
}

function onContrastChange(value: number) {
  // value range: [-1, 1]
  panoFilter.contrast.contrastBias = value;
  five.needsRender = true;
}
```

## Related

*   [Model](./model.md): 了解 ModelScene 及其参数系统。
*   [Parameter](./parameter.md): 了解 Five 的全局初始化参数。
*   [Postprocessing](./postprocessing.md): 了解屏幕空间的后处理效果。
*   [Material](./material.md): 材质参数配置（透明度、点云等）。

---

```yaml
tags: [滤镜, 色温, 暖色, 冷色, 饱和度, 亮度, 对比度, filter, material, visual, color, brightness, contrast, color-correction, warm, cool, tone]
```