@realsee/five/ai_guides/features/move-pano-effect.md

Realsee Renderer SDK

# 全景切换效果 (Move Pano Effect)

- **Summary**: 介绍 `moveToPano` 方法中 `effect` 和 `effectEasing` 参数的作用及使用方式，用于控制全景点位切换时的视觉过渡效果。
- **Schema**: `MovePanoEffect` (枚举字符串), `MovePanoOptions` (接口).
- **Concepts**: Effect Modes (切换模式), Easing Function (缓动函数), Blend Ratio (混合比例).
- **Configuration**: `moveToPano` 的 `options` 参数.
- **Examples**: 基础切换、自定义缓动函数.

## Schema

### MovePanoEffect

> **Definition**: [MovePanoEffect](../../five/types/movePanoEffect.d.ts)

`effect` 参数定义了全景切换的动画模式。

```typescript
type MovePanoEffect =
  | "fly"      // 飞行效果 (默认)：模拟相机在空间中的移动
  | "instant"  // 瞬间切换：无动画，直接跳变
  | "fade"     // 淡入淡出：原场景渐隐，新场景渐现 (位置保持不变)
  | "montage"  // 蒙太奇：通过黑屏过渡 (渐变穿插到黑屏再亮起)
  | "spread"   // 扩散：新场景从中心向四周扩散
  | "zoomin"   // 放大：新场景从小放大覆盖
  | "zoomout"  // 缩小：原场景缩小消失
  | "model";   // 模型过渡：切换过程中展示 3D 模型结构
```

### effectEasing

`effectEasing` 是一个函数，用于控制前后全景图的混合进度。

```typescript
// 输入 0-1 的进度值，返回 0-1 的混合比例
type EffectEasing = (progress: number) => number;
```

*   **输入 (Input)**: `progress` (0 到 1)，表示动画的时间进度。
*   **输出 (Output)**: 混合比例 (0 到 1)。
    *   `0`: 完全显示前一个全景图。
    *   `1`: 完全显示后一个全景图。
    *   `0.5`: 两个全景图各显示 50%。

## Concepts

### Effect Modes (切换模式)

*   **Fly (飞行)**: 最常用的模式。相机在三维空间中真实移动，给用户强烈的空间位置感。适用于相邻或视线通透的点位切换。
*   **Fade (渐变)**: 保持相机位置不变，仅改变图像透明度。适用于距离较远、不通视或空间关系不明确的点位切换，避免产生"穿墙"的违和感。
*   **Model (模型)**: 在切换过程中淡入模型的线框或白模，强调空间结构。

### Easing Function (缓动函数)

默认情况下，混合比例与时间进度是线性的 (`y = x`)。通过自定义 `effectEasing`，可以实现非线性的混合效果。例如：

*   **快速切入**: 开始时混合很快，后面变慢。
*   **延迟切入**: 开始时保持原图较长时间，最后快速切换到新图。
*   **特殊场景**: 如“地面-天空”切换，可能希望在特定的时间点才开始显示新图。

## Examples

### 1. 基础用法 (Basic Usage)

使用不同的 `effect` 进行切换。

```typescript
// 1. 飞行模式 (默认)
five.moveToPano(1, {
  effect: 'fly',
  duration: 1500
});

// 2. 瞬间切换 (无动画)
five.moveToPano(2, {
  effect: 'instant'
});

// 3. 淡入淡出 (适用于远距离切换)
five.moveToPano(10, {
  effect: 'fade',
  duration: 1000
});
```

### 2. 自定义缓动 (Custom Easing)

使用 `effectEasing` 控制混合节奏。

```typescript
// 示例：Ease-In-Quad (先慢后快)
function easeInQuad(x: number): number {
  return x * x;
}

five.moveToPano(5, {
  effect: 'fly',
  duration: 2000,
  // 自定义混合曲线
  effectEasing: easeInQuad
});
```

### 3. 高级缓动控制 (Advanced Easing)

在某些特殊场景（如从地面点切换到航拍点），我们可能希望前 80% 的时间都显示地面点，最后 20% 才快速过渡到航拍图。

```typescript
five.moveToPano(aerialPanoIndex, {
  effect: 'fly',
  duration: 3000,
  effectEasing: (progress) => {
    // 0 - 0.8 期间返回 0 (显示原图)
    // 0.8 - 1.0 期间线性过渡到 1
    if (progress < 0.8) return 0;
    return (progress - 0.8) / 0.2;
  }
});
```

## Configuration

`moveToPano` 的第二个参数 `options` 支持以下配置：

| 参数 | 类型 | 说明 | 默认值 |
| :--- | :--- | :--- | :--- |
| `effect` | `MovePanoEffect` | 切换效果模式 | `'fly'` |
| `effectEasing` | `(p: number) => number` | 图片混合缓动函数 | `p => p` (线性) |
| `duration` | `number` | 动画耗时 (ms) | 根据距离自动计算 |

## Common Pitfalls

1.  **Effect 适用性**: `fly` 效果虽然炫酷，但在穿过墙体或障碍物时可能会导致视觉上的“穿帮”。此时应优先考虑使用 `fade` 或 `model`。
2.  **Easing 范围**: `effectEasing` 函数的返回值应严格控制在 `0` 到 `1` 之间。超出此范围可能会导致渲染异常（如过曝或反色）。
3.  **Duration**: 如果 `duration` 设置为 `0`，无论 `effect` 是什么，效果都等同于 `instant`。

## Related

*   [Camera Animation](./camera-animation.md): 更多关于相机控制的说明。
*   [Five](./five.md): Five 实例及 API。

---

```yaml
tags: [全景切换, 走点效果, 淡入淡出, 飞行, 过渡动画, 缓动, move-pano-effect, camera-animation, pano-switch, fly, fade, easing]
```