跳到主要内容

Five 初始化配置使用说明

信息

在初始化 five 实例时，可以配置的参数项具体可参考 FiveInitArgs ，以下几个配置项将直接影响到 VR 体验，我们在此为您详细说明。

imageOptions​

imageOptions 是全景图的配置参数，Five 渲染引擎将根据此参数对 work 数据中的全景图片在 runtime 时动态调整 url, 以达到平衡加载时间和图片质量的目的，配置示例：

const five = new Five({
  imageOptions: {
    size: 1024, // 表示全景图加载 1024x1024 的图片
    quality: 70, // 表示图片质量压缩到 70%
  },
})

全景瓦片模式​

为了优化用户在三维空间中漫游的体验，我们引入了瓦片模式。瓦片模式是指在全景图的基础上，将全景图切割成多个小图片，然后根据用户的视角动态加载对应的小图片，以达到平衡加载时间和图片质量的目的。

目前我们已经支持了三级瓦片模式，支持分辨率为 1024x1024（1 级瓦片）, 2048x2048（2 级瓦片） 、4096x4096 （3 级瓦片）、8192x8192 （4 级瓦片） 的全景图。瓦片依赖的原始高清全景图依赖拍摄数据和拍摄设备的不同，分辨率也不同。目前使用我们默认会使用 2048x2048 的全景图，即至少 2 级瓦片。

瓦片数据的解析已经内置在引擎中，您只需要在初始化时配置好对应的参数即可。

const five = new Five({
  imageOptions: {
    size: 512, // 当初始值为512，且work数据中有瓦片数据时，会自动使用瓦片模式
  },
})
提示

动态瓦片使用了图床动态裁剪功能，因此需要配置图床服务，我们内置了腾讯云数据万象，您也可以使用其他对象存储服务。

阿里云图床服务配置示例​

export const imageOptions = {
  format: 'jpg', // 格式 可选 "jpg" | "png" | "heif" | "webp" | "avif"
  quality: 100, // 图片质量参数(0-100)
  size: 2048, // 图片尺寸参数 尽量使用 2 的幂次 如 512 1024 2048，瓦片使用512
  transform: (
    source: string,
    options: {
      size?: number
      quality?: number
      format?: 'jpg' | 'png' | 'heif' | 'webp' | 'avif'
      cut?: [number, number, number, number]
      sharpen?: number
    },
  ) => {
    let base = source.split('?')[0]
    let ext = base.split('.').pop()

    if (ext === 'jpeg') ext = 'jpg'
    if (ext !== 'png' && ext !== 'jpg') return source

    let suffix: string = ''

    const params: string[] = ['x-oss-process=image']
    const { format, quality, size } = options

    // 图片缩放
    // https://help.aliyun.com/document_detail/44688.htm?spm=a2c4g.11186623.0.0.ea05890eIlPbUs#concept-hxj-c4n-vdb
    if (size && size !== 2048) {
      params.push(`resize,w_${size}`)
    }

    // 自定义裁剪
    // https://help.aliyun.com/document_detail/44693.html
    if (options.cut !== undefined) {
      const [x, y, width, height] = options.cut
      params.push(`crop,x_${x},y_${y},w_${width},h_${height},g_nw`)
    }

    // 图片处理包含缩放操作时，建议将格式转换参数放到处理参数的最后。
    // https://help.aliyun.com/document_detail/44703.htm?spm=a2c4g.11186623.0.0.ea0532458MXRu0#concept-mf3-md5-vdb
    if (format !== undefined && format !== ext) {
      params.push(`format,${format}`)
    }

    // 图片质量
    // 质量变换仅支持JPG和WebP，其他图片格式不支持。
    // https://help.aliyun.com/document_detail/44705.htm?spm=a2c4g.11186623.0.0.ea053245KXAlE2#concept-exc-qp5-vdb
    if (quality !== undefined && quality !== 100) {
      const format = options.format ?? ext
      if (format && ['jpg', 'webp'].indexOf(format) >= 0) {
        params.push(`quality,Q_${quality}`)
      }
    }

    // 锐化
    // https://help.aliyun.com/document_detail/44700.html
    if (options.sharpen !== undefined) {
      params.push(`sharpen,${options.sharpen}`)
    }

    // 拼接参数
    if (params.length) {
      suffix = '?' + params.join('/')
    }
    return base + suffix
  },
}

如视推荐配置示例​

我们通常可以使用以下配置作为基准，然后根据不同的条件来适当调整

const defaultInitArgs = {
  backgroundAlpha: 0,
  initWithTransition: false,
  floorplan: {
    minLatitude: 0,
    maxLatitude: Math.PI / 2,
    defaultFov: 95,
  },
  panorama: {
    minLatitude: -Math.PI / 4,
    maxLatitude: Math.PI / 4,
    defaultFov: 95,
  },
  imageOptions: {
    size: 512,
  },
  onlyRenderIfNeeds: true, // 默认值为 true。 大多情况下，都是应该开启按需渲染
  initialBasisLoader: false, // 默认值为 false。 大多数情况并不使用 basis, 不多加载资源
  // five 插件
  plugins: pluginsArray, // 按需配置
}

if (如果支持瓦片) {
  defaultInitArgs.imageOptions.size = 512
}

if (需要展示高清模型) {
  defaultInitArgs.textureOptions.size = null
  defaultInitArgs.textureOptions.autoResize = false
}