目录

spatialRender

The spatialRender module is mainly used for rendering 3DGS data and displaying rendered 3DGS scenes.

Since: 6.0.1(21)

Modules to Import

import { spatialRender } from '@kit.SpatialReconKit';

GSNode

Represents a 3D Gaussian Splatting (3DGS) render object, which helps you manipulate the 3DGS model. This class inherits from Node. For details about how to use it, please refer to Node.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Graphics.SpatialRender

Since: 6.0.1(21)

Example:

import { Scene, RenderContext } from '@kit.ArkGraphics3D';
import { spatialRender } from '@kit.SpatialReconKit';

// Obtain the default rendering context.
let renderContext: RenderContext | null = Scene.getDefaultRenderContext();

if (renderContext != null) {
  renderContext.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    let uri = "OhosRawFile://assets/gltf/model.glb";
    let offset = 0;
    
    // Obtain the GSNode instance through GSPlugin.loadGSNode.
    let gsNode: spatialRender.GSNode = await spatialRender.GSPlugin.loadGSNode(scene, { uri, offset }, scene.root);
    
    // Set the node position.
    gsNode.position = { x: 3, y: 0, z: 0 };
    // Set the node scaling.
    gsNode.scale = { x: 1.5, y: 1.5, z: 1.5 };
    // Set the node visibility.
    gsNode.visible = true;
  });
}

TiledGSNode

Represents a tiled 3D Gaussian Splatting (3DGS) rendering object, specifically designed for loading and rendering large-scale 3DGS scenes. This class inherits from Node. For details about how to use it, please refer to Node.

[h2]setCamera

setCamera(camera: Camera): void

Sets the camera that drives tile selection.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Graphics.SpatialRender

Since: 26.0.0

Parameters:

Name Type Mandatory Description
camera Camera Yes Camera that drives tile selection. By default, the camera that renders the current scene is used. You can set another camera.

Example:

import { Scene, RenderContext, Camera, Node } from '@kit.ArkGraphics3D';
import { spatialRender } from '@kit.SpatialReconKit';

// Obtain the default rendering context.
let renderContext: RenderContext | null = Scene.getDefaultRenderContext();

if (renderContext != null) {
  renderContext.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    if (!scene.root) {
      return;
    }
    let root: Node = scene.root as Node;

    // Create a camera.
    let srf = scene.getResourceFactory();
    let camera: Camera = await srf.createCamera({ name: "Camera1", path: root.path });
    camera.clearColor = { r: 202/255.0, g: 233/255.0, b: 246/255.0, a: 1.0 };
    camera.nearPlane = 0.5;
    camera.farPlane = 10000.0;
    let PI = 3.141592653;
    let DEG2RAD = PI * 2.0 / 360.0;
    camera.fov = 60.0 * DEG2RAD;
    camera.enabled = true;

    // Configure tiled 3DGS import parameters.
    let params: spatialRender.TiledGSImportSettings = {
      uri: "file:///data/storage/el2/base/files/uav-lod/sanyapo.scene.json"
    };

    // Load the tiled 3DGS model.
    let promise = spatialRender.GSPlugin.loadTiledGSNode(scene, params, root);
    promise.then((tiledGSNode: spatialRender.TiledGSNode) => {
      if (!camera) {
        return;
      }
      // Set the camera that drives tile selection.
      tiledGSNode.setCamera(camera);
      // Set node attributes.
      tiledGSNode.position = { x: 0, y: 0, z: 0 };
      tiledGSNode.scale = { x: 1, y: 1, z: 1 };
      tiledGSNode.visible = true;
    });
  });
}

[h2]setTileRequestCallback

setTileRequestCallback(callback: GSTileRequestCallback | null): void

Sets the tile request callback function, which will be called by the renderer when it requires the app to provide tile data. This callback receives a list of tiles (files) that the app should load. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Graphics.SpatialRender

Since: 26.0.0

Parameters:

Name Type Mandatory Description
callback GSTileRequestCallback Yes Callback function. If the callback is successfully triggered when the renderer requests tiles, the GSTile list requested by the renderer from the app is returned. Otherwise, an error object is returned.

Example:

import { Scene, RenderContext, Camera, Node } from '@kit.ArkGraphics3D';
import { spatialRender } from '@kit.SpatialReconKit';

// Obtain the default rendering context.
let renderContext: RenderContext | null = Scene.getDefaultRenderContext();

if (renderContext != null) {
  renderContext.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    if (!scene.root) {
      return;
    }
    let root: Node = scene.root as Node;

    // Create a camera.
    let srf = scene.getResourceFactory();
    let camera: Camera = await srf.createCamera({ name: "Camera1", path: root.path });
    camera.clearColor = { r: 202/255.0, g: 233/255.0, b: 246/255.0, a: 1.0 };
    camera.nearPlane = 0.5;
    camera.farPlane = 10000.0;
    let PI = 3.141592653;
    let DEG2RAD = PI * 2.0 / 360.0;
    camera.fov = 60.0 * DEG2RAD;
    camera.enabled = true;

    // Configure tiled 3DGS import parameters.
    let params: spatialRender.TiledGSImportSettings = {
      uri: "file:///data/storage/el2/base/files/uav-lod/sanyapo.scene.json"
    };

    // Load the tiled 3DGS model.
    let promise = spatialRender.GSPlugin.loadTiledGSNode(scene, params, root);
    promise.then((tiledGSNode: spatialRender.TiledGSNode) => {
      if (!camera) {
        return;
      }
      // Set the camera that drives tile selection.
      tiledGSNode.setCamera(camera);
      // Set node attributes.
      tiledGSNode.position = { x: 0, y: 0, z: 0 };
      tiledGSNode.scale = { x: 1, y: 1, z: 1 };
      tiledGSNode.visible = true;
      // Register the tile request callback with the renderer.
      tiledGSNode.setTileRequestCallback((tiles: spatialRender.GSTile[]) => {
        // Obtain and save the remote tile data, and notify the renderer that the tile data is ready.
        if (!tiles || tiles.length <= 0) {
          return;
        }
      });
    });
  });
}

[h2]notifyTileReady

notifyTileReady(tile: GSTile): void

Notifies the renderer that the specified tile is ready to be loaded. The file at the relative path specified by tile.uri is accessible and readable by the renderer. If the renderer no longer needs the tile (for example, the camera has moved away before the tile is obtained), this call does not perform any operation.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Graphics.SpatialRender

Since: 26.0.0

Parameters:

Name Type Mandatory Description
tile GSTile Yes Tile that contains available data.

Example:

import { Scene, RenderContext, Camera, Node } from '@kit.ArkGraphics3D';
import { spatialRender } from '@kit.SpatialReconKit';

// Obtain the default rendering context.
let renderContext: RenderContext | null = Scene.getDefaultRenderContext();

if (renderContext != null) {
  renderContext.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    if (!scene.root) {
      return;
    }
    let root: Node = scene.root as Node;

    // Create a camera.
    let srf = scene.getResourceFactory();
    let camera: Camera = await srf.createCamera({ name: "Camera1", path: root.path });
    camera.clearColor = { r: 202/255.0, g: 233/255.0, b: 246/255.0, a: 1.0 };
    camera.nearPlane = 0.5;
    camera.farPlane = 10000.0;
    let PI = 3.141592653;
    let DEG2RAD = PI * 2.0 / 360.0;
    camera.fov = 60.0 * DEG2RAD;
    camera.enabled = true;

    // Configure tiled 3DGS import parameters.
    let params: spatialRender.TiledGSImportSettings = {
      uri: "file:///data/storage/el2/base/files/uav-lod/sanyapo.scene.json"
    };

    // Load the tiled 3DGS model.
    let promise = spatialRender.GSPlugin.loadTiledGSNode(scene, params, root);
    promise.then((tiledGSNode: spatialRender.TiledGSNode) => {
      if (!camera) {
        return;
      }
      // Set the camera that drives tile selection.
      tiledGSNode.setCamera(camera);
      // Set node attributes.
      tiledGSNode.position = { x: 0, y: 0, z: 0 };
      tiledGSNode.scale = { x: 1, y: 1, z: 1 };
      tiledGSNode.visible = true;
      // Register the tile request callback with the renderer.
      tiledGSNode.setTileRequestCallback((tiles: spatialRender.GSTile[]) => {
        if (!tiles || tiles.length <= 0) {
          return;
        }
        for (const tile of tiles) {
          // Request tile data from the remote end and save the data to the relative path specified by the uri.
          // ......
          // Notify the renderer that a tile is ready.
          tiledGSNode..notifyTileReady(tile);
        }
      });
    });
  });
}

GSPlugin

Encapsulates 3DGS-related content, including the 3DGS plugin ID and 3DGS model loading API, helping you implement custom 3DGS features.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Graphics.SpatialRender

Since: 6.0.1(21)

Before calling this API, you must load the corresponding plugin ID. Otherwise, undefined behavior may occur.

Example:

import { spatialRender } from '@kit.SpatialReconKit';
import { Scene } from '@kit.ArkGraphics3D';

// Obtain the default rendering context.
let renderContext = Scene.getDefaultRenderContext();
if (renderContext != null) {
  // Load the spatial reconstruction plugin GSPlugin.
  renderContext.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
}

[h2]Constants

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Graphics.SpatialRender

Since: 6.0.1(21)

Name Type Description
PLUGIN_ID string 3DGS plugin ID. Before using this plugin, call renderContext.loadPlugin(GSPlugin.PLUGIN_ID) to load it.
RETRO_EFFECT_ID string Retro effect ID. You need to load PLUGIN_ID first, and then pass this constant as EffectParameters.effectId to createEffect to create an effect instance.
COMIC_EFFECT_ID string Comic effect ID. Load PLUGIN_ID first, and then pass this constant as EffectParameters.effectId into createEffect to create an effect instance.
OBRA_DINN_EFFECT_ID string 1-bit monochrome effect ID. Load PLUGIN_ID first, and then pass this constant as EffectParameters.effectId into createEffect to create an effect instance.
COLOR_EDITING_EFFECT_ID string Color editing effect ID. Load PLUGIN_ID first, and then pass this constant as EffectParameters.effectId into createEffect to create an effect instance.

You do not need to be aware of the specific values of these IDs. It is recommended that you directly use the string variables.

[h2]loadGSNode

static loadGSNode(scene: Scene, params: GSImportSettings, parent?: Node): Promise<GSNode>

Loads a 3DGS model. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Graphics.SpatialRender

Since: 6.0.1(21)

Parameters:

Name Type Mandatory Description
scene Scene Yes Scene to be displayed on the app UI. It is a fundamental module of ArkGraphics 3D. You are advised to obtain the scene by calling Scene.load.
params GSImportSettings Yes Configurations for loading the 3DGS model.
parent Node No Node to which the 3DGS model is expected to be attached. If this parameter is not passed, the loaded 3DGS model will be attached to the root node of the scene.

Returns:

Type Description
Promise<GSNode> Promise used to return the GSNode corresponding to the 3DGS model.

Example:

import { Scene, RenderContext } from '@kit.ArkGraphics3D';
import { spatialRender } from '@kit.SpatialReconKit';

// Obtain the default rendering context.
let renderContext: RenderContext | null = Scene.getDefaultRenderContext();

if (renderContext != null) {
  // Load the spatial reconstruction plugin GSPlugin.
  renderContext.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  let scene = Scene.load().then(async (scene: Scene) => {
    // Set the URI of the 3DGS model file based on the actual situation.
    let uri = "OhosRawFile://assets/gltf/model.glb";
    // Offset parameter (used for adjusting model displacement). Set it as needed.
    let offset = 0;
    // Load the specified 3DGS node using GSPlugin and add it to the scene root node.
    let gsNodeext: spatialRender.GSNode = await spatialRender.GSPlugin.loadGSNode(scene, {uri, offset}, scene.root);
  });
}

[h2]loadTiledGSNode

static loadTiledGSNode(scene: Scene, params: TiledGSImportSettings, parent?: Node): Promise<TiledGSNode>

Loads a tiled 3DGS model. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Graphics.SpatialRender

Since: 26.0.0

Parameters:

Name Type Mandatory Description
scene Scene Yes Scene to be displayed on the app UI. It is a fundamental module of ArkGraphics 3D. You are advised to obtain the scene by calling Scene.load.
params TiledGSImportSettings Yes Configurations for loading the tiled 3DGS model.
parent Node No Node to which the tiled 3DGS model is expected to be attached. If this parameter is not passed, the loaded tiled 3DGS model will be attached to the root node of the scene.

Returns:

Type Description
Promise<TiledGSNode> Promise used to return the TiledGSNode corresponding to the tiled 3DGS model.

Example:

import { Scene, RenderContext } from '@kit.ArkGraphics3D';
import { spatialRender } from '@kit.SpatialReconKit';

// Obtain the default rendering context.
let renderContext: RenderContext | null = Scene.getDefaultRenderContext();

if (renderContext != null) {
  // Load the spatial reconstruction plugin GSPlugin.
  renderContext.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  let scene = Scene.load().then(async (scene: Scene) => {
    // Set the URI of the tiled 3DGS model manifest file based on the actual situation.
    let uri = "file:///data/storage/el2/base/files/uav-lod/sanyapo.scene.json";
    // Load the specified tiled 3DGS node using GSPlugin and add it to the scene root node.
    let tiledGSNode: spatialRender.TiledGSNode = await spatialRender.GSPlugin.loadTiledGSNode(scene, { uri }, scene.root);
  });
}

GSImportSettings

Encapsulates the configurations for loading a 3DGS model, including the model path and the data offset within the file.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Graphics.SpatialRender

Since: 6.0.1(21)

Name Type Read-Only Optional Description
uri string No No File path of the 3DGS model. If an empty string is passed, the loading will fail.
offset number No Yes Offset of the data to be loaded with the 3DGS model file. The default value is 0.

Example:

import { Scene, RenderContext } from '@kit.ArkGraphics3D';
import { spatialRender } from '@kit.SpatialReconKit';

// Obtain the default rendering context.
let renderContext: RenderContext | null = Scene.getDefaultRenderContext();

if (renderContext != null) {
  // Load the spatial reconstruction plugin GSPlugin.
  renderContext.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  let scene = Scene.load().then(async (scene: Scene) => {
    // Set the URI of the 3DGS model file based on the actual situation.
    let uri = "OhosRawFile://assets/gltf/doll.glb";
    // Offset parameter (used for adjusting model displacement).
    let offset = 0;
    // Configure import parameters.
    let setting: spatialRender.GSImportSettings = { uri: uri, offset : offset};
    // Load the specified 3DGS node using GSPlugin and add it to the scene root node.
    let gsNodeext: spatialRender.GSNode = await spatialRender.GSPlugin.loadGSNode(scene, setting, scene.root);
  });
}

TiledGSImportSettings

Encapsulates the configurations for loading a tiled 3DGS model, including the manifest file path.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Graphics.SpatialRender

Since: 26.0.0

Name Type Read-Only Optional Description
uri string No No Path of the manifest file (JSON) of the tiled 3DGS model, which is used to describe the tile layer structure. If an empty string is passed, the loading will fail.

Example:

import { Scene, RenderContext } from '@kit.ArkGraphics3D';
import { spatialRender } from '@kit.SpatialReconKit';

// Obtain the default rendering context.
let renderContext: RenderContext | null = Scene.getDefaultRenderContext();

if (renderContext != null) {
  // Load the spatial reconstruction plugin GSPlugin.
  renderContext.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  let scene = Scene.load().then(async (scene: Scene) => {
    // Set the URI of the tiled 3DGS model manifest file based on the actual situation.
    let uri = "file:///data/storage/el2/base/files/uav-lod/sanyapo.scene.json";
    // Configure import parameters.
    let setting: spatialRender.TiledGSImportSettings = { uri: uri };
    // Load the specified tiled 3DGS node using GSPlugin and add it to the scene root node.
    let tiledGSNode: spatialRender.TiledGSNode = await spatialRender.GSPlugin.loadTiledGSNode(scene, setting, scene.root);
  });
}

RetroEffectParams

RetroEffect parameter, which is a string enum. It can be used in the getPropertyValue and setPropertyValue methods of Effect to declare the names of attributes in order to obtain or update their values.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Graphics.SpatialRender

Since: 6.1.0(23)

Name Value Description
COLOR_NUM 'colorNum'

Name of the colorNum attribute in RetroEffect.

The value type of this attribute is number. This attribute specifies the number of colors used for color dithering. Generally, a larger value results in higher image quality, while a smaller value enhances the retro style. The value must be greater than 0, with a default value of 8.
PIXEL_SIZE 'pixelSize'

Name of the pixelSize attribute in RetroEffect.

The value type of this attribute is number. This attribute indicates the degree of downsampling. A larger value applies a stronger effect. If this attribute is set to 1, no downsampling is performed. The value must be greater than or equal to 1, with a default value of 4.
BLEND_ENABLED 'blendEnabled'

Name of the blendEnabled attribute in RetroEffect.

The value type of this attribute is boolean. This attribute indicates whether to blend the processed image with the original image. The value true indicates yes and the value false indicates no. Since the retro style causes loss of image brightness and color shifts, you can set this attribute to true to maintain the original brightness and color. The default value is true.
CURVE 'curve'

Name of the curve attribute in RetroEffect.

The value type of this attribute is number. This attribute indicates the screen curvature of a CRT television, which is a characteristic feature of the retro style. A larger value results in a greater curvature. The value range is [0, 1], and the default value is 0.25.

Example:

import { Scene, RenderContext, RenderingPipelineType, Effect } from '@kit.ArkGraphics3D';
import { spatialRender } from '@kit.SpatialReconKit';

// Obtain the default rendering context.
let renderContext: RenderContext | null = Scene.getDefaultRenderContext();

if (renderContext != null) {
  // Load the spatial reconstruction plugin GSPlugin.
  renderContext.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    // Obtain the resource factory for the scene.
    let rf = scene.getResourceFactory();
    // Create a retro effect instance (using the effect ID predefined by GSPlugin).
    let effect : Effect =
      await rf.createEffect({ effectId: spatialRender.GSPlugin.RETRO_EFFECT_ID });
    // Obtain the current value of the retro effect parameter (number of colors).
    let colNum = effect.getPropertyValue(spatialRender.RetroEffectParams.COLOR_NUM);
    // Set the retro effect parameter (number of colors) to 4.
    let res = effect.setPropertyValue(spatialRender.RetroEffectParams.COLOR_NUM, 4);
    // Create a camera.
    let camera = await rf.createCamera({ name: "gsCam", path: "//gsCam" }, { renderingPipeline: RenderingPipelineType.FORWARD });
    // Add the effect to the effect chain of the camera.
    camera.effects.append(effect)
  });
}

RetroEffect

Encapsulates the effect parameters of the retro style, allowing for custom retro styles. This class inherits from Effect.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Graphics.SpatialRender

Since: 6.0.1(21)

Name Type Read-Only Optional Description
colorNum number No No Number of colors used for color dithering. Generally, a larger value results in higher image quality, while a smaller value enhances the retro style. The value must be greater than 0. The default value is 8.
pixelSize number No No Degree of downsampling. A larger value applies a stronger effect. If the value is set to 1, downsampling is not performed. The value must be greater than or equal to 1. The default value is 4.
blendEnabled boolean No No Indicates whether to blend the processed image with the original image. The value true indicates yes and the value false indicates no. Since the retro style causes loss of image brightness and color shifts, you can set this parameter to true to maintain the original brightness and color. The default value is true.
curve number No No

Screen curvature of a CRT television, which is a characteristic feature of the retro style.

A larger value results in a greater curvature. The value range is [0, 1]. The default value is 0.25.

Example:

import { Scene, RenderContext, RenderingPipelineType } from '@kit.ArkGraphics3D';
import { spatialRender } from '@kit.SpatialReconKit';

// Obtain the default rendering context.
let renderContext: RenderContext | null = Scene.getDefaultRenderContext();

if (renderContext != null) {
  // Load the spatial reconstruction plugin GSPlugin.
  renderContext.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    // Obtain the resource factory for the scene.
    let rf = scene.getResourceFactory();
    // Create a retro effect instance (of the RetroEffect type).
    let effect : spatialRender.RetroEffect =
      await rf.createEffect({ effectId: spatialRender.GSPlugin.RETRO_EFFECT_ID }) as spatialRender.RetroEffect;
    // Create a camera.
    let camera = await rf.createCamera({ name: "gsCam", path: "//gsCam" }, { renderingPipeline: RenderingPipelineType.FORWARD });
    // Add the effect to the effect chain of the camera.
    camera.effects.append(effect)
  });
}

ComicEffectParams

ComicEffect parameter, which is a string enum. It can be used in the getPropertyValue and setPropertyValue methods of Effect to declare the names of attributes in order to obtain or update their values.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Graphics.SpatialRender

Since: 6.1.0(23)

Name Value Description
LINE_THRESHOLD 'lineThreshold'

Name of the lineThreshold attribute in ComicEffect.

The value type of this attribute is number. This attribute indicates the threshold for identifying edge pixels. Pixels with an image gradient greater than this threshold are determined to be outlines. The value range is [0, 1], and the default value is 0.2.
LINE_COLOR 'lineColor'

Name of the lineColor attribute in ComicEffect.

For details about the values, please refer to Color. This attribute indicates the color of the outline.

Example:

import { Scene, RenderContext, RenderingPipelineType, Effect } from '@kit.ArkGraphics3D';
import { spatialRender } from '@kit.SpatialReconKit';

// Obtain the default rendering context.
let renderContext: RenderContext | null = Scene.getDefaultRenderContext();

if (renderContext != null) {
  // Load the spatial reconstruction plugin GSPlugin.
  renderContext.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    // Obtain the resource factory for the scene.
    let rf = scene.getResourceFactory();
    // Create a comic effect instance (using the effect ID predefined by GSPlugin).
    let effect : Effect =
      await rf.createEffect({ effectId: spatialRender.GSPlugin.COMIC_EFFECT_ID });
    // Obtain the current value of the comic effect parameter (line threshold).
    let threshold = effect.getPropertyValue(spatialRender.ComicEffectParams.LINE_THRESHOLD);
    // Set the comic effect parameter (line threshold) to 0.5.
    let res = effect.setPropertyValue(spatialRender.ComicEffectParams.LINE_THRESHOLD, 0.5);
    // Create a camera.
    let camera = await rf.createCamera({ name: "gsCam", path: "//gsCam" }, { renderingPipeline: RenderingPipelineType.FORWARD });
    // Add the comic effect to the effect chain of the camera.
    camera.effects.append(effect)
  });
}

ComicEffect

Encapsulates the effect parameters of the comic style, allowing for custom comic styles. This class inherits from Effect.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Graphics.SpatialRender

Since: 6.0.1(21)

Name Type Read-Only Optional Description
lineThreshold number No No Threshold for identifying edge pixels. Pixels with an image gradient greater than this threshold are determined to be outlines. (The image gradient indicates the contrast in brightness between a pixel and its neighbors. A greater contrast yields a higher gradient value, indicating a higher probability of being an outline.) The value range is [0, 1], and the default value is 0.2.
lineColor Color No No Color of the outline.

Example:

import { Scene, RenderContext, RenderingPipelineType } from '@kit.ArkGraphics3D';
import { spatialRender } from '@kit.SpatialReconKit';

// Obtain the default rendering context.
let renderContext: RenderContext | null = Scene.getDefaultRenderContext();

if (renderContext != null) {
  // Load the spatial reconstruction plugin GSPlugin.
  renderContext.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    // Obtain the resource factory for the scene.
    let rf = scene.getResourceFactory();
    // Create a comic effect instance (of the ComicEffect type).
    let effect : spatialRender.ComicEffect =
      await rf.createEffect({ effectId: spatialRender.GSPlugin.COMIC_EFFECT_ID }) as spatialRender.ComicEffect;
    // Create a camera.
    let camera = await rf.createCamera({ name: "gsCam", path: "//gsCam" }, { renderingPipeline: RenderingPipelineType.FORWARD });
    // Add the comic effect to the effect chain of the camera.
    camera.effects.append(effect)
  });
}

ObraDinnEffectParams

ObraDinnEffect parameter, which is a string enum. It can be used in the getPropertyValue and setPropertyValue methods of Effect to declare the names of attributes in order to obtain or update their values.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Graphics.SpatialRender

Since: 6.1.0(23)

Name Value Description
NOISE_STRENGTH 'noiseStrength'

Name of the noiseStrength attribute in ObraDinnEffect.

The value type of this attribute is number. This attribute specifies pixels used for color dithering. This attribute helps smooth edges. Increasing the noise intensity will result in blurrier edges. The value range is [0, 1], and the default value is 0.3.
THRESHOLD 'threshold'

Name of the threshold attribute in ObraDinnEffect.

The value type of this attribute is number. This attribute specifies the threshold for classifying pixels into either the foreground or background color. A higher value causes the overall image colors to shift closer to the background color. The value range is [0, 1], and the default value is 0.4.
FOREGROUND_COLOR 'foregroundColor'

Name of the foregroundColor attribute in ObraDinnEffect.

For details about the values, please refer to Color. This attribute indicates the foreground color.
BACKGROUND_COLOR 'backgroundColor'

Name of the backgroundColor attribute in ObraDinnEffect.

For details about the values, please refer to Color. This attribute indicates the background color.

Example:

import { Scene, RenderContext, RenderingPipelineType, Effect } from '@kit.ArkGraphics3D';
import { spatialRender } from '@kit.SpatialReconKit';

// Obtain the default rendering context.
let renderContext: RenderContext | null = Scene.getDefaultRenderContext();

if (renderContext != null) {
  // Load the spatial reconstruction plugin GSPlugin.
  renderContext.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    // Obtain the resource factory for the scene.
    let rf = scene.getResourceFactory();
    // Create a 1-bit monochrome effect instance (using the effect ID predefined by GSPlugin).
    let effect : Effect =
      await rf.createEffect({ effectId: spatialRender.GSPlugin.OBRA_DINN_EFFECT_ID });
    // Obtain the current value of the 1-bit monochrome effect parameter (noise intensity).
    let noiseStrength = effect.getPropertyValue(spatialRender.ObraDinnEffectParams.NOISE_STRENGTH);
    // Set the 1-bit monochrome effect parameter (noise intensity) to 0.5.
    let res = effect.setPropertyValue(spatialRender.ObraDinnEffectParams.NOISE_STRENGTH, 0.5);
    // Create a camera.
    let camera = await rf.createCamera({ name: "gsCam", path: "//gsCam" }, { renderingPipeline: RenderingPipelineType.FORWARD });
    // Add the 1-bit monochrome effect to the effect chain of the camera.
    camera.effects.append(effect)
  });
}

ObraDinnEffect

Encapsulates the effect parameters of the 1-bit monochrome style, allowing for custom 1-bit monochrome styles. This class inherits from Effect.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Graphics.SpatialRender

Since: 6.0.1(21)

Name Type Read-Only Optional Description
noiseStrength number No No Pixels are used for color dithering. This parameter helps smooth edges. Increasing the noise intensity will result in blurrier edges. The value range is [0, 1], and the default value is 0.3.
threshold number No No Threshold for classifying pixels into either the foreground or background color. Pixels above this threshold are rendered in the foreground color. A lower threshold shifts the overall image colors closer to the foreground color, while a higher threshold shifts them closer to the background color. The value range is [0, 1], and the default value is 0.4.
foregroundColor Color No No Foreground color.
backgroundColor Color No No Background color.

Example:

import { Scene, RenderContext, RenderingPipelineType } from '@kit.ArkGraphics3D';
import { spatialRender } from '@kit.SpatialReconKit';

// Obtain the default rendering context.
let renderContext: RenderContext | null = Scene.getDefaultRenderContext();

if (renderContext != null) {
  // Load the spatial reconstruction plugin GSPlugin.
  renderContext.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    // Obtain the resource factory for the scene.
    let rf = scene.getResourceFactory();
    // Create a 1-bit monochrome effect instance (of the ObraDinnEffect type).
    let effect : spatialRender.ObraDinnEffect =
      await rf.createEffect({ effectId: spatialRender.GSPlugin.OBRA_DINN_EFFECT_ID }) as spatialRender.ObraDinnEffect;
    // Create a camera.
    let camera = await rf.createCamera({ name: "gsCam", path: "//gsCam" }, { renderingPipeline: RenderingPipelineType.FORWARD });
    // Add the 1-bit monochrome effect to the effect chain of the camera.
    camera.effects.append(effect)
  });
}

ColorEditingEffectParams

ColorEditingEffect parameter, which is a string enum. It can be used in the getPropertyValue and setPropertyValue methods of Effect to declare the names of attributes in order to obtain or update their values.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Graphics.SpatialRender

Since: 6.1.0(23)

Name Value Description
EXPOSURE 'exposure'

Name of the exposure attribute in ColorEditingEffect.

The value type of this attribute is number. This attribute indicates the image exposure. The recommended value range is [-5, 5], and the default value is 0.0.
CONTRAST 'contrast'

Name of the contrast attribute in ColorEditingEffect.

The value type of this attribute is number. This attribute indicates the image contrast. The recommended value range is [0, 2], and the default value is 1.0.
TEMPERATURE 'temperature'

Name of the temperature attribute in ColorEditingEffect.

The value type of this attribute is number. This attribute indicates the image temperature. The recommended value range is [-2, 2], and the default value is 0.0.
TINT 'tint'

Name of the tint attribute in ColorEditingEffect.

The value type of this attribute is number. This attribute indicates the image tint. The recommended value range is [-1, 1], and the default value is 0.0.
SATURATION 'saturation'

Name of the saturation attribute in ColorEditingEffect.

The value type of this attribute is number. This attribute indicates the image saturation. The recommended value range is [0, 2], and the default value is 1.0.
VIBRANCE 'vibrance'

Name of the vibrance attribute in ColorEditingEffect.

The value type of this attribute is number. This attribute indicates the image vibrance. The recommended value range is [-1, 1], and the default value is 0.0.

Example:

import { Scene, RenderContext, RenderingPipelineType, Effect } from '@kit.ArkGraphics3D';
import { spatialRender } from '@kit.SpatialReconKit';

// Obtain the default rendering context.
let renderContext: RenderContext | null = Scene.getDefaultRenderContext();

if (renderContext != null) {
  // Load the spatial reconstruction plugin GSPlugin.
  renderContext.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    // Obtain the resource factory for the scene.
    let rf = scene.getResourceFactory();
    // Create a color editing effect instance (using the effect ID predefined by GSPlugin).
    let effect : Effect =
      await rf.createEffect({ effectId: spatialRender.GSPlugin.COLOR_EDITING_EFFECT_ID });
    // Obtain the current value of the color editing effect parameter (exposure).
    let exposure = effect.getPropertyValue(spatialRender.ColorEditingEffectParams.EXPOSURE);
    // Set the color editing effect parameter (exposure) to 0.5.
    let res = effect.setPropertyValue(spatialRender.ColorEditingEffectParams.EXPOSURE, 0.5);
    // Create a camera.
    let camera = await rf.createCamera({ name: "gsCam", path: "//gsCam" }, { renderingPipeline: RenderingPipelineType.FORWARD });
    // Add the color editing effect to the effect chain of the camera.
    camera.effects.append(effect)
  });
}

ColorEditingEffect

Encapsulates parameters of the color editing style, allowing for custom image styles. This class inherits from Effect.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Graphics.SpatialRender

Since: 6.0.1(21)

Name Type Read-Only Optional Description
exposure number No No Image exposure. The recommended value range is [-5, 5]. The default value is 0.0.
contrast number No No Image contrast. The recommended value range is [0, 2]. The default value is 1.0.
temperature number No No Image temperature. The recommended value range is [-2, 2]. The default value is 0.0.
tint number No No Image tint. The recommended value range is [-1, 1]. The default value is 0.0.
saturation number No No Image saturation. The recommended value range is [0, 2]. The default value is 1.0.
vibrance number No No Image vibrance. The recommended value range is [-1, 1]. The default value is 0.0.

Example:

import { Scene, RenderContext, RenderingPipelineType } from '@kit.ArkGraphics3D';
import { spatialRender } from '@kit.SpatialReconKit';

// Obtain the default rendering context.
let renderContext: RenderContext | null = Scene.getDefaultRenderContext();

if (renderContext != null) {
  // Load the spatial reconstruction plugin GSPlugin.
  renderContext.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    // Obtain the resource factory for the scene.
    let rf = scene.getResourceFactory();
    // Create a color editing effect instance (of the ColorEditingEffect type).
    let effect : spatialRender.ColorEditingEffect =
      await rf.createEffect({ effectId: spatialRender.GSPlugin.COLOR_EDITING_EFFECT_ID }) as spatialRender.ColorEditingEffect;
    // Create a camera.
    let camera = await rf.createCamera({ name: "gsCam", path: "//gsCam" }, { renderingPipeline: RenderingPipelineType.FORWARD });
    // Add the color editing effect to the effect chain of the camera.
    camera.effects.append(effect)
  });
}

GSTile

Descriptor of a 3D Gaussian tile. A GSTile corresponds to a .sog file in the manifest file.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Graphics.SpatialRender

Since: 26.0.0

Name Type Read-Only Optional Description
uri string No No URI of a .sog file that contains 3D Gaussian tile data.

Example:

import { Scene, RenderContext, Camera, Node } from '@kit.ArkGraphics3D';
import { spatialRender } from '@kit.SpatialReconKit';

// Obtain the default rendering context.
let renderContext: RenderContext | null = Scene.getDefaultRenderContext();

if (renderContext != null) {
  renderContext.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    if (!scene.root) {
      return;
    }
    let root: Node = scene.root as Node;

    // Create a camera.
    let srf = scene.getResourceFactory();
    let camera: Camera = await srf.createCamera({ name: "Camer1", path: root.path });
    camera.enabled = true;

    // Configure tiled 3DGS import parameters.
    let params: spatialRender.TiledGSImportSettings = {
      uri: "file:///data/storage/el2/base/files/uav-lod/sanyapo.scene.json"
    };

    // Load the tiled 3DGS model.
    let promise = spatialRender.GSPlugin.loadTiledGSNode(scene, params, root);
    promise.then((tiledGSNode: spatialRender.TiledGSNode) => {
      if (!camera) {
        return;
      }
      // Set the camera that drives tile selection.
      tiledGSNode.setCamera(camera);
      // Register the tile request callback with the renderer.
      tiledGSNode.setTileRequestCallback((tiles: spatialRender.GSTile[]) => {
        if (!tiles || tiles.length <= 0) {
          return;
        }
        // Iterate through the requested tiles to retrieve their URIs.
        for (const tile of tiles) {
          console.debug('tile uri=', tile.uri);
        }
      });
    });
  });
}

GSTileRequestCallback

type GSTileRequestCallback = (tiles: GSTile[]) => void

Callback function used to pass the tile data request from the renderer. It is triggered when the driving camera moves and the renderer needs to load more tiles.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Graphics.SpatialRender

Since: 26.0.0

Parameters:

Name Type Mandatory Description
tiles GSTile[] Yes List of tiles requested by the renderer from the app.

Example:

import { Scene, RenderContext, Camera, Node } from '@kit.ArkGraphics3D';
import { spatialRender } from '@kit.SpatialReconKit';

// Obtain the default rendering context.
let renderContext: RenderContext | null = Scene.getDefaultRenderContext();

if (renderContext != null) {
  renderContext.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    if (!scene.root) {
      return;
    }
    let root: Node = scene.root as Node;

    // Create a camera.
    let srf = scene.getResourceFactory();
    let camera: Camera = await srf.createCamera({ name: "Camer1", path: root.path });
    camera.enabled = true;

    // Configure tiled 3DGS import parameters.
    let params: spatialRender.TiledGSImportSettings = {
      uri: "file:///data/storage/el2/base/files/uav-lod/sanyapo.scene.json"
    };

    // Load the tiled 3DGS model.
    let promise = spatialRender.GSPlugin.loadTiledGSNode(scene, params, root);
    promise.then((tiledGSNode: spatialRender.TiledGSNode) => {
      if (!camera) {
        return;
      }
      // Set the camera that drives tile selection.
      tiledGSNode.setCamera(camera);
      // Register the tile request callback with the renderer.
      tiledGSNode.setTileRequestCallback((tiles: spatialRender.GSTile[]) => {
        if (!tiles || tiles.length <= 0) {
          return;
        }
        // Iterate through the requested tiles.
        for (const tile of tiles) {
          // Send a request to the remote end to obtain the corresponding tile data and persist the data.
        }
      });
    });
  });
}