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;
  };
}
Copy

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');
Copy

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;
}
Copy

Related

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

---

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