# 全景切换效果 (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

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

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

### effectEasing

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

    // 输入 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` 进行切换。

    // 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` 控制混合节奏。

    // 示例：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% 才快速过渡到航拍图。

    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: 更多关于相机控制的说明。
- Five: Five 实例及 API。

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