# Pano Filter (全景图滤镜)

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

## Schema

> Definition: PBMPanoFilter

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

    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 (后处理) 不同，`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 场景中。

    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 (动态调整)

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

    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: 了解 ModelScene 及其参数系统。
- Parameter: 了解 Five 的全局初始化参数。
- Postprocessing: 了解屏幕空间的后处理效果。
- Material: 材质参数配置（透明度、点云等）。

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