@realsee/five/ai_guides/features/image-options.md

Realsee Renderer SDK

# ImageOptions (图片配置)

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

## Schema

### ImageOptions

> **Definition**: [ImageOptions](../../five/types/imageOptions.d.ts)

全局图片加载配置接口。

```typescript
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
域名映射规则配置，用于支持多云存储或私有化部署。

```typescript
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`，适用于大多数场景。

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

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

### 多云/私有化部署配置
将数据中的 `custom-oss-public.ljcdn.com` 域名映射到对应的资源专用 OSS 域名。

```typescript
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 区域）。

```typescript
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](./pano-tile.md): 全景图瓦片加载策略与 WorkTile 数据结构说明。

---

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