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;
}
Copy

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];
  }
}
Copy

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,
  }
});
Copy

多云/私有化部署配置

将数据中的 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"]
      }
    }
  }
});
Copy

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

使用 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
Copy

Related

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

---

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