# 全景图 UV 与方向转换 (Panorama UV Conversion)

- Summary: 提供了一组工具方法，用于在全景图 UV 坐标 (Equirectangular UV / Cubemap UV) 与三维空间方向向量 (Vector3) 之间进行转换。
- Schema: 依赖 `WorkObserver` 实例，提供四个核心转换方法。
- Concepts: Equirectangular Projection, Cubemap Projection, UV Origin, Coordinate Systems.
- Configuration: `uvOrigin` (UV 原点设置).
- Examples: 向量转全景 UV、UV 转向量、Cubemap 转换。

## Schema

> Definition: WorkObserver

这些方法挂载在 `WorkObserver` 实例上，依赖当前观察点 (Observer) 的位姿信息 (Position & Quaternion) 以及 `work.transform` 进行计算。

    interface WorkObserver {
      /**
       * 将方向向量转化为全景图 uv
       * @param vector - 全局方向向量 (World Space)
       * @param uvOrigin - UV 原点位置，默认为 'top-left'
       */
      vectorToEquirectangularUv(vector: THREE.Vector3, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector2;

      /**
       * 将全景图 uv 转化为方向向量
       * @param uv - 全景图 UV 坐标 [0, 1]
       * @param uvOrigin - UV 原点位置，默认为 'top-left'
       */
      equirectangularUvToVector(uv: THREE.Vector2, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector3;

      /**
       * 将方向向量转化为六视图 uv
       * @param vector - 全局方向向量 (World Space)
       * @param uvOrigin - UV 原点位置，默认为 'top-left'
       */
      vectorToCubemapUv(vector: THREE.Vector3, uvOrigin?: 'top-left' | 'bottom-left'): [cubeFace: CubeFace, cubemapUv: THREE.Vector2];

      /**
       * 将六视图 uv 转化为方向向量
       * @param cubeFace - 立方体面 ('up' | 'down' | 'left' | 'right' | 'front' | 'back')
       * @param uv - 该面上的 UV 坐标 [0, 1]
       * @param uvOrigin - UV 原点位置，默认为 'top-left'
       */
      cubemapUvToVector(cubeFace: CubeFace, uv: THREE.Vector2, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector3;
    }

    type CubeFace = 'up' | 'down' | 'left' | 'right' | 'front' | 'back';

## Concepts

### 1. 坐标系转换 (Coordinate Transformation)

转换过程会自动处理以下坐标空间的变换：

1. World Space (世界坐标系): `vector` 参数所处的坐标系。
2. Work Space (Work 坐标系): 考虑 `work.transform` 带来的整体旋转。
3. Observer Space (观察者坐标系): 考虑 `observer.quaternion` 带来的观察点旋转。
4. Panorama Space (全景图空间): 最终映射到 2D 图片上的 UV 坐标。

### 2. 投影方式 (Projection Types)

- Equirectangular (等距柱状投影): 将球体展开为 2:1 的矩形图片。常用于全景图预览。
- Cubemap (立方体贴图): 将球体投影到立方体的六个面上。常用于高清全景浏览。

### 3. UV 原点 (UV Origin)

- top-left (默认): 原点 `(0, 0)` 在图片左上角。U 轴向右，V 轴向下。符合大多数 Web 图片处理习惯 (Canvas, DOM)。
- bottom-left: 原点 `(0, 0)` 在图片左下角。U 轴向右，V 轴向上。符合 WebGL / OpenGL 纹理坐标习惯。

## Configuration

所有方法均包含可选参数 `uvOrigin`。

### Common Configuration

Parameter | Type | Default | Description
--- | --- | --- | ---
`uvOrigin` | `'top-left' | 'bottom-left'` | `'top-left'` | 指定 UV 坐标系的原点位置。

## Examples

### 1. 点击全景图获取空间方向 (Click to Vector)

假设你有一个全景图的点击事件，获取到了点击位置的 UV：

    const observer = five.work.observers[0];
    // 假设这是用户点击全景图后归一化得到的 UV (0~1)
    const clickUv = new THREE.Vector2(0.5, 0.5);

    // 转换为世界空间的方向向量
    const direction = observer.equirectangularUvToVector(clickUv);

    console.log('点击方向:', direction);

### 2. 将空间点映射到全景图上 (World Point to UV)

假设场景中有一个 3D 物体，你想知道它在当前全景图上的位置（例如打标签）：

    const observer = five.work.observers[0];
    const objectPosition = new THREE.Vector3(10, 2, 5);

    // 计算物体相对于观察点的方向向量
    const direction = objectPosition.clone().sub(observer.position).normalize();

    // 获取全景图 UV
    const uv = observer.vectorToEquirectangularUv(direction);

    console.log(`物体在全景图上的位置: u=${uv.x}, v=${uv.y}`);

### 3. 处理 Cubemap 坐标 (Cubemap Conversion)

如果你使用的是六面体全景图资源：

    const observer = five.work.observers[0];
    const direction = new THREE.Vector3(0, 0, -1); // 正前方

    // 获取对应的面和 UV
    const [face, uv] = observer.vectorToCubemapUv(direction);

    console.log(`正前方对应 Cubemap 的 ${face} 面，UV 为`, uv);

## Related

- Work: 了解 WorkObserver 的数据结构。
- Coordinate System: 了解 Five 的坐标系定义。

    tags: [全景UV, 方向转换, 全景坐标, 像素映射, 全景标注, work, observer, uv, projection, math, equirectangular, cubemap]