Configuration Guide | Realsee Developer Platform

Info

When initializing a Five SDK instance, the full set of configurable parameters is documented in FiveInitArgs. The following options directly affect the VR experience, so we explain them in detail here.

imageOptions

imageOptions holds the configuration parameters for panoramas. Based on these parameters, the Five SDK rendering engine dynamically adjusts the URL of the panorama images in the work data at runtime, balancing load time against image quality. Example configuration:

const five = new Five({
  imageOptions: {
    size: 1024, // load the panorama as a 1024x1024 image
    quality: 70, // compress image quality to 70%
  },
})

Panorama tile mode

To optimize the experience of roaming through 3D space, we introduced tile mode. In tile mode, the panorama is split into many smaller images, and the corresponding tiles are loaded dynamically according to the user's viewing direction, balancing load time against image quality.

We currently support three levels of tile mode, covering panoramas at resolutions of 1024x1024 (level 1 tiles), 2048x2048 (level 2 tiles), 4096x4096 (level 3 tiles), and 8192x8192 (level 4 tiles). The resolution of the original high-definition panorama that the tiles are derived from varies depending on the capture data and the capture device. By default we currently use 2048x2048 panoramas, i.e. at least level 2 tiles.

Tile data parsing is built into the engine, so you only need to set the corresponding parameters during initialization.

const five = new Five({
  imageOptions: {
    size: 512, // when the initial value is 512 and the work data contains tile data, tile mode is enabled automatically
  },
})

Tip

Dynamic tiling relies on the image CDN's dynamic cropping capability, so an image CDN service must be configured. We bundle Tencent Cloud Data Wanxiang (CI), but you may also use another object storage service.

Example: Alibaba Cloud image CDN configuration

export const imageOptions = {
  format: 'jpg', // format, one of "jpg" | "png" | "heif" | "webp" | "avif"
  quality: 100, // image quality parameter (0-100)
  size: 2048, // image size parameter; prefer powers of 2 such as 512, 1024, 2048; tiles use 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

    // Image resize
    // 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}`)
    }

    // Custom crop
    // 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`)
    }

    // When the image processing includes a resize operation, it is recommended to place the format conversion parameter last.
    // 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}`)
    }

    // Image quality
    // Quality transformation is only supported for JPG and WebP; other image formats are not supported.
    // 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}`)
      }
    }

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

    // Assemble parameters
    if (params.length) {
      suffix = '?' + params.join('/')
    }
    return base + suffix
  },
}

Realsee recommended configuration example

We typically use the following configuration as a baseline and then adjust it as appropriate for different conditions.

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, // default is true; in most cases on-demand rendering should be enabled
  initialBasisLoader: false, // default is false; basis is not used in most cases, so avoid loading extra resources
  // Five plugins
  plugins: pluginsArray, // configure as needed
}

if (tilesAreSupported) {
  defaultInitArgs.imageOptions.size = 512
}

if (highDefinitionModelNeeded) {
  defaultInitArgs.textureOptions.size = null
  defaultInitArgs.textureOptions.autoResize = false
}