# ImageOptions (图片配置)

- Summary: `Five` 初始化参数 `imageOptions` 用于全局配置全景图与资源的加载策略，支持多云/私有化部署映射、图片格式自适应、质量控制及内部瓦片裁剪。
- Schema: `ImageOptions` 接口定义及相关配置。
- Concepts: CDN Mapping, Format Adaptation, Tile Cutting.
- Configuration: `imageOptions` 参数详解。
- Examples: 基础优化、多云部署映射、瓦片裁剪调用。

## Schema

### ImageOptions

> Definition: ImageOptions

全局图片加载配置接口。

    interface ImageOptions {
      /** 图片类型标识 (内部使用，如 "pano.front") */
      key?: string;
      /** 图片尺寸参数 (例如 512, 1024...) */
      size?: number;
      /** 图片质量参数 (0-100) */
      quality?: number;
      /**
       * 图片格式参数
       * 自动降级逻辑：如果指定格式（如 avif/webp）当前浏览器不支持，会自动降级为 jpg
       */
      format?: "jpg" | "jpeg" | "png" | "heif" | "heic" | "webp" | "avif";
      /**
       * 图片裁切 [x, y, width, height]
       * 通常用于内部工具获取局部图片，初始化 Five 时一般不设置此项
       */
      cut?: [x: number, y: number, width: number, height: number];
      /** 锐化参数 (仅部分 CDN 支持) */
      sharpen?: number;
      /** 域名匹配规则，用于多云或私有化部署 */
      mappings?: ImageURLMappings;
      /** 自定义 URL 转换函数 */
      transform?: (url: string, options: ImageURLOptions) => string;
    }

### ImageURLMappings

域名映射规则配置，用于支持多云存储或私有化部署。

    interface ImageURLMappings {
      [publicDomain: string]: {
        /** CDN 类型，目前支持 'tencentCloud' | 'aliyun' 用于区分特定云厂商的图片处理参数 */
        "type"?: string;
        /** 全景图域名映射列表 */
        "pano": [string, string];
        /** 全景图瓦片域名映射列表 */
        "tile": [string, string];
        /** 3D Tile 模型域名映射列表 */
        "model": [string, string];
        /** AT3D 材质域名映射列表 */
        "texture": [string];
        /** 默认域名映射列表 */
        "default": [string];
      }
    }

## Concepts

### CDN Mapping (多云部署与私有化)

通过 `mappings` 字段，可以将原始数据中的 初始域名（`publicDomain`，即数据中尚未进行资源分流的统一地址）映射到不同用途的具体域名下。

- 资源分流: 针对不同资源类型配置不同域名：
  - `pano`: 全景图
  - `tile`: 全景图瓦片
  - `model`: 3D Tile 模型
  - `texture`: AT3D 材质
- 负载均衡: 每个资源类型支持配置多个域名（如 `[domain1, domain2]`），SDK 会自动进行轮询负载均衡。
- 私有化支持: 将初始数据中的通用域名映射到内网或私有 OSS 域名。
- CDN 适配: 指定 `type` ('tencentCloud' | 'aliyun') 可启用特定云厂商的图片处理参数（如缩放、裁剪、格式转换）。

### Format Adaptation (浏览器兼容性)

SDK 内置了图片格式兼容性检测（`imageSupport`）。

- 自动降级: 当配置 `format: 'webp'` 或 `format: 'avif'` 时，SDK 会检测当前浏览器是否支持该格式。如果不支持，自动降级请求 `jpg` 格式，确保图片能正常显示。
- 性能优化: 推荐默认开启 `avif`，在支持的浏览器上大幅减小流量消耗。

### Tile Cutting (内部瓦片裁剪)

利用云厂商的图片处理能力（如腾讯云 ImageMogr2 或阿里云 OSS Process），可以通过 `cut` 参数获取大图的局部区域。

- 应用场景: 内部工具调用、生成特定视角的缩略图、动态获取全景图的某一部分。
- 调用方式: 通常配合 `imageURL` 工具函数使用。

## Configuration

在 `new Five()` 时传入 `imageOptions`。

参数 | 类型 | 说明
--- | --- | ---
`format` | string | 推荐设置为 `"avif"`，SDK 会自动处理兼容性。
`quality` | number | 图片质量 (0-100)，非必要不设置。
`mappings` | object | 域名映射表，用于替换数据中的原始域名，非必要不设置。
`size` | number | 全景图初始尺寸，推荐设置为 `512`，可根据场景调整。

## Examples

### 基础优化配置 (推荐)

启用 AVIF 格式并设置初始尺寸为 `512`，适用于大多数场景。

    import { Five } from "@realsee/five";

    const five = new Five({
      imageOptions: {
        format: "avif",
        size: 512,
      }
    });

### 多云/私有化部署配置

将数据中的 `custom-oss-public.ljcdn.com` 域名映射到对应的资源专用 OSS 域名。

    import { Five } from "@realsee/five";

    const five = new Five({
      imageOptions: {
        mappings: {
          "custom-oss-public.ljcdn.com": {
            type: "tencentCloud", // 指定使用腾讯云图片处理协议
            pano: ["custom-oss-image-1.com", "custom-oss-image-2.com"], // 双域名负载均衡
            tile: ["custom-oss-tile-1.com", "custom-oss-tile-2.com"],
            model: ["custom-oss-model-1.com", "custom-oss-model-2.com"],
            texture: ["custom-oss-image-3.com"],
            default: ["custom-oss-image-4.com"]
          }
        }
      }
    });

### 内部调用：获取全景图局部裁剪

使用 SDK 提供的 `defaultImageURLTransform` 工具函数（通常导出为 `defaultImageURLTransform`，可重命名为 `imageURL`），结合 `cut` 参数获取全景图特定区域（例如获取前方图片的中心 512x512 区域）。

    import { defaultImageURLTransform as imageURL } from "@realsee/five";

    const originalUrl = "https://vr-public.realsee-cdn.com/.../pano_f.jpg";

    const cutUrl = imageURL(originalUrl, {
      cut: [256, 256, 512, 512], // x, y, width, height
      format: "webp",
      quality: 80,
    });

    console.log(cutUrl);
    // 输出示例: https://vr-image-4.realsee-cdn.com/.../pano_f.jpg?imageMogr2/format/webp/cut/512x512x256x256/quality/80

## Related

- Pano Tile: 全景图瓦片加载策略与 WorkTile 数据结构说明。

    tags: [图片配置, 图片格式, 域名映射, 多云部署, 私有化, 图片质量, 流量优化, imageOptions, configuration, optimization, cdn, private-deployment, avif, webp]