目录

spatialEdit

The spatialEdit module provides the capability for editing 3D Gaussian Splatting (3DGS) models, supporting operations such as selecting, transforming, coloring, and deleting Gaussian points.

System capability: SystemCapability.Graphics.SpatialEdit

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

Since: 26.0.0

Modules to Import

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

PaintMode

Enumerates the color blending modes.

System capability: SystemCapability.Graphics.SpatialEdit

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

Since: 26.0.0

Name Value Description
REPLACE 0 Directly replace the original color.
MULTIPLY 1 Multiply the original color by the given color.
ADD 2 Add the given color to the original color.

GSEdit

3DGS model editing handle class that provides a variety of editing operations for Gaussian models.

System capability: SystemCapability.Graphics.SpatialEdit

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

Since: 26.0.0

[h2]editGSNode

static editGSNode(node: spatialRender.GSNode): GSEdit | undefined

Creates a 3DGS model editing handle.

System capability: SystemCapability.Graphics.SpatialEdit

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

Since: 26.0.0

Parameters:

Name Type Mandatory Description
node spatialRender.GSNode Yes 3DGS node to be edited.

Returns:

Type Description
GSEdit | undefind 3DGS model editing handle. If the node does not meet the editing requirements, undefined is returned.

Example:

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

function EditGSNode() : void {
  // Load the 3DGS plug-in.
  Scene.getDefaultRenderContext()?.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    let rf: SceneResourceFactory = scene.getResourceFactory();
    // Obtain the GSNode instance.
    let gsNode: spatialRender.GSNode = await rf.createNode({ name: "gs", path: "//gs" })
    // Obtain the GSEdit instance.
    let editor: spatialEdit.GSEdit = spatialEdit.GSEdit.editGSNode(gsNode);
  });
}

[h2]selectBy2DBox

selectBy2DBox(rect: Rect): void

Selects Gaussian points within a 2D rectangular area in viewport coordinates (adding them to the current selection).

System capability: SystemCapability.Graphics.SpatialEdit

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

Since: 26.0.0

Parameters:

Name Type Mandatory Description
rect Rect Yes 2D rectangular area in the viewport.

Example:

import { spatialRender, spatialEdit } from '@kit.SpatialReconKit';
import { Rect, Scene, SceneResourceFactory } from '@kit.ArkGraphics3D';

function SelectBy2DBox() : void {
  // Load the 3DGS plug-in.
  Scene.getDefaultRenderContext()?.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    let rf: SceneResourceFactory = scene.getResourceFactory();
    // Obtain the GSNode instance.
    let gsNode: spatialRender.GSNode = await rf.createNode({ name: "gs", path: "//gs" })
    // Obtain the GSEdit instance.
    let editor: spatialEdit.GSEdit = spatialEdit.GSEdit.editGSNode(gsNode);
    // Select Gaussian points within a 2D rectangular area (adding them to the current selection).
    let rect: Rect = {x: 0.25, y: 0.25, height: 0.5, width: 0.5};
    editor.selectBy2DBox(rect);
  });
}

[h2]selectBy3DBox

selectBy3DBox(aabb: Aabb): void

Selects Gaussian points within an axis-aligned bounding box in 3D space (adding them to the current selection).

System capability: SystemCapability.Graphics.SpatialEdit

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

Since: 26.0.0

Parameters:

Name Type Mandatory Description
aabb Aabb Yes 3D axis-aligned bounding box.

Example:

import { spatialRender, spatialEdit } from '@kit.SpatialReconKit';
import { Aabb, Scene, SceneResourceFactory } from '@kit.ArkGraphics3D';

function SelectBy3DBox() : void {
  // Load the 3DGS plug-in.
  Scene.getDefaultRenderContext()?.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    let rf: SceneResourceFactory = scene.getResourceFactory();
    // Obtain the GSNode instance.
    let gsNode: spatialRender.GSNode = await rf.createNode({ name: "gs", path: "//gs" })
    // Obtain the GSEdit instance.
    let editor: spatialEdit.GSEdit = spatialEdit.GSEdit.editGSNode(gsNode);
    // Select Gaussian points within an axis-aligned bounding box (adding them to the current selection).
    let aabb: Aabb = {
      aabbMin: {x: 0, y: 0, z: 0},
      aabbMax: {x: 10, y: 10, z: 10}
    };
    editor.selectBy3DBox(aabb);
  });
}

[h2]selectByIndex

selectByIndex(indices: number[]): void

Select Gaussian points by index (adding them to the current selection).

System capability: SystemCapability.Graphics.SpatialEdit

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

Since: 26.0.0

Parameters:

Name Type Mandatory Description
indices number[] Yes Gaussian point index array.

Example:

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

function SelectByIndex() : void {
  // Load the 3DGS plug-in.
  Scene.getDefaultRenderContext()?.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    let rf: SceneResourceFactory = scene.getResourceFactory();
    // Obtain the GSNode instance.
    let gsNode: spatialRender.GSNode = await rf.createNode({ name: "gs", path: "//gs" })
    // Obtain the GSEdit instance.
    let editor: spatialEdit.GSEdit = spatialEdit.GSEdit.editGSNode(gsNode);
    // Select Gaussian points by index (adding them to the current selection).
    let indices: number[] = [];
    for (let i = 1; i <= 50000; i++) {
      indices.push(i);
    }
    editor.selectByIndex(indices);
  });
}

[h2]selectBy2DMask

selectBy2DMask(mask: image.PixelMap): void

Selects Gaussian points via a 2D mask image (adding them to the current selection).

System capability: SystemCapability.Graphics.SpatialEdit

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

Since: 26.0.0

Parameters:

Name Type Mandatory Description
mask image.PixelMap Yes Mask image.

Example:

import { spatialRender, spatialEdit } from '@kit.SpatialReconKit';
import { Scene, SceneResourceFactory } from '@kit.ArkGraphics3D';
import { resourceManager } from '@kit.LocalizationKit';
import { image } from '@kit.ImageKit';

function SelectBy2DMask(context : Context) : void {
  // Obtain a resource manager.
  const resourceMgr: resourceManager.ResourceManager = context.resourceManager;
  // Load the 3DGS plug-in.
  Scene.getDefaultRenderContext()?.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    let rf: SceneResourceFactory = scene.getResourceFactory();
    // Obtain the GSNode instance.
    let gsNode: spatialRender.GSNode = await rf.createNode({ name: "gs", path: "//gs" })
    // Obtain the GSEdit instance.
    let editor: spatialEdit.GSEdit = spatialEdit.GSEdit.editGSNode(gsNode);
    // Create a PixelMap object via image decoding.
    // 'test.jpg' is only an example. Replace it with the actual one.
    let fileData: Uint8Array = await resourceMgr?.getRawFileContent("test.jpg");
    let imageSource: image.ImageSource = image.createImageSource(fileData?.buffer);
    let pixelMap: image.PixelMap = imageSource.createPixelMapSync();
    imageSource.release();
    // Select Gaussian points via a 2D mask image (adding them to the current selection).
    editor.selectBy2DMask(pixelMap);
  });
}

[h2]invertSelection

invertSelection(): void

Inverts the current selection.

System capability: SystemCapability.Graphics.SpatialEdit

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

Since: 26.0.0

Example:

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

function InvertSelection() : void {
  // Load the 3DGS plug-in.
  Scene.getDefaultRenderContext()?.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    let rf: SceneResourceFactory = scene.getResourceFactory();
    // Obtain the GSNode instance.
    let gsNode: spatialRender.GSNode = await rf.createNode({ name: "gs", path: "//gs" })
    // Obtain the GSEdit instance.
    let editor: spatialEdit.GSEdit = spatialEdit.GSEdit.editGSNode(gsNode);
    // Select Gaussian points within a 2D rectangular area (adding them to the current selection).
    let rect: Rect = {x: 0.25, y: 0.25, height: 0.5, width: 0.5};
    editor.selectBy2DBox(rect);
    // Invert the current selection.
    editor.invertSelection();
  });
}

[h2]clearSelection

clearSelection(): void

Clears the current selection.

System capability: SystemCapability.Graphics.SpatialEdit

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

Since: 26.0.0

Example:

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

function ClearSelection() : void {
  // Load the 3DGS plug-in.
  Scene.getDefaultRenderContext()?.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    let rf: SceneResourceFactory = scene.getResourceFactory();
    // Obtain the GSNode instance.
    let gsNode: spatialRender.GSNode = await rf.createNode({ name: "gs", path: "//gs" })
    // Obtain the GSEdit instance.
    let editor: spatialEdit.GSEdit = spatialEdit.GSEdit.editGSNode(gsNode);
    // Select Gaussian points within a 2D rectangular area (adding them to the current selection).
    let rect: Rect = {x: 0.25, y: 0.25, height: 0.5, width: 0.5};
    editor.selectBy2DBox(rect);
    // Clear the current selection.
    editor.clearSelection();
  });
}

[h2]transform

transform(matrix: Mat4x4): void

Applies a transformation matrix to the current selection.

System capability: SystemCapability.Graphics.SpatialEdit

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

Since: 26.0.0

Parameters:

Name Type Mandatory Description
matrix Mat4x4 Yes 4x4 transformation matrix.

Example:

import { spatialRender, spatialEdit } from '@kit.SpatialReconKit';
import { Mat4x4, Scene, SceneResourceFactory } from '@kit.ArkGraphics3D';

function Transform() : void {
  // Load the 3DGS plug-in.
  Scene.getDefaultRenderContext()?.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    let rf: SceneResourceFactory = scene.getResourceFactory();
    // Obtain the GSNode instance.
    let gsNode: spatialRender.GSNode = await rf.createNode({ name: "gs", path: "//gs" })
    // Obtain the GSEdit instance.
    let editor: spatialEdit.GSEdit = spatialEdit.GSEdit.editGSNode(gsNode);
    // Select Gaussian points within a 2D rectangular area (adding them to the current selection).
    let rect: Rect = {x: 0.25, y: 0.25, height: 0.5, width: 0.5};
    editor.selectBy2DBox(rect);
    // Apply a transformation matrix to the current selection.
    let matrix: Mat4x4 = {
      x: {x: 0.8, y: 0, z: 0, w: 0},
      y: {x: 0, y: 0.8, z: 0, w: 0},
      z: {x: 0, y: 0, z: 0.8, w: 0},
      w: {x: 0, y: 0, z: 0, w: 1}
    };
    editor.transform(matrix);
  });
}

[h2]paint

paint(color: Color, mode: PaintMode): void

Colors the current selection using the specified blending mode.

System capability: SystemCapability.Graphics.SpatialEdit

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

Since: 26.0.0

Parameters:

Name Type Mandatory Description
color Color Yes Color to be applied.
mode PaintMode Yes Color blending mode.

Example:

import { spatialRender, spatialEdit } from '@kit.SpatialReconKit';
import { Color, Scene, SceneResourceFactory } from '@kit.ArkGraphics3D';

function Paint() : void {
  // Load the 3DGS plug-in.
  Scene.getDefaultRenderContext()?.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    let rf: SceneResourceFactory = scene.getResourceFactory();
    // Obtain the GSNode instance.
    let gsNode: spatialRender.GSNode = await rf.createNode({ name: "gs", path: "//gs" })
    // Obtain the GSEdit instance.
    let editor: spatialEdit.GSEdit = spatialEdit.GSEdit.editGSNode(gsNode);
    // Select Gaussian points within a 2D rectangular area (adding them to the current selection).
    let rect: Rect = {x: 0.25, y: 0.25, height: 0.5, width: 0.5};
    editor.selectBy2DBox(rect);
    // Color the current selection using the specified blending mode.
    let color: Color = {
      r: 1.0,
      g: 1.0,
      b: 0.0,
      a: 1.0
    };
    editor.paint(color, spatialEdit.PaintMode.MULTIPLY);
  });
}

[h2]remove

remove(): void

Deletes Gaussian points in the current selection.

System capability: SystemCapability.Graphics.SpatialEdit

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

Since: 26.0.0

Example:

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

function Remove() : void {
  // Load the 3DGS plug-in.
  Scene.getDefaultRenderContext()?.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    let rf: SceneResourceFactory = scene.getResourceFactory();
    // Obtain the GSNode instance.
    let gsNode: spatialRender.GSNode = await rf.createNode({ name: "gs", path: "//gs" })
    // Obtain the GSEdit instance.
    let editor: spatialEdit.GSEdit = spatialEdit.GSEdit.editGSNode(gsNode);
    // Select Gaussian points within a 2D rectangular area (adding them to the current selection).
    let rect: Rect = {x: 0.25, y: 0.25, height: 0.5, width: 0.5};
    editor.selectBy2DBox(rect);
    // Delete Gaussian points in the current selection.
    editor.remove();
  });
}

[h2]undo

undo(): void

Undoes the most recent operation. (Multiple calls are supported for consecutive undo.)

System capability: SystemCapability.Graphics.SpatialEdit

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

Since: 26.0.0

Example:

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

function undo() : void {
  // Load the 3DGS plug-in.
  Scene.getDefaultRenderContext()?.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    let rf: SceneResourceFactory = scene.getResourceFactory();
    // Obtain the GSNode instance.
    let gsNode: spatialRender.GSNode = await rf.createNode({ name: "gs", path: "//gs" })
    // Obtain the GSEdit instance.
    let editor: spatialEdit.GSEdit = spatialEdit.GSEdit.editGSNode(gsNode);
    // Select Gaussian points within a 2D rectangular area (adding them to the current selection).
    let rect: Rect = {x: 0.25, y: 0.25, height: 0.5, width: 0.5};
    editor.selectBy2DBox(rect);
    // Delete Gaussian points in the current selection.
    editor.remove();
    // Undo the previous operation.
    editor.undo();
  });
}

[h2]getRecommended3DBox

getRecommended3DBox(ori: Vec3, dir: Vec3): Aabb

Obtains the recommended 3D axis-aligned bounding box of an object along a specific ray.

System capability: SystemCapability.Graphics.SpatialEdit

Since: 26.0.0

Parameters:

Name Type Mandatory Description
ori Vec3 Yes Origin coordinates of the ray.
dir Vec3 Yes Direction vector of the ray.

Returns:

Type Description
Aabb 3D axis-aligned bounding box (AABB) of the object detected by the ray.

Example:

import { spatialRender, spatialEdit } from '@kit.SpatialReconKit';
import { Scene, SceneResourceFactory, Aabb, Vec3 } from '@kit.ArkGraphics3D';

function getRecommended3DBox() : void {
  // Load the 3DGS plug-in.
  Scene.getDefaultRenderContext()?.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    let rf: SceneResourceFactory = scene.getResourceFactory();
    // Obtain the GSNode instance.
    let gsNode: spatialRender.GSNode = await rf.createNode({ name: "gs", path: "//gs" })
    // Obtain the GSEdit instance.
    let editor: spatialEdit.GSEdit = spatialEdit.GSEdit.editGSNode(gsNode);

    let rayOrigin: Vec3 = { x : 0 , y : 0 , z : 0 };
    let rayDirection: Vec3 = { x : 1 , y : 1 , z : 1 };
    // Obtain the bounding box of the object intersected by the ray.
    let aabb: Aabb = editor.getRecommended3DBox(rayOrigin, rayDirection);
  });
}

[h2]saveToPLY

saveToPLY(uri: string): Promise<boolean>

Saves the edited model in PLY format. This API uses a promise to return the result.

System capability: SystemCapability.Graphics.SpatialEdit

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

Since: 26.0.0

Parameters:

Name Type Mandatory Description
uri string Yes Target file path.

Returns:

Type Description
Promise<boolean> Promise used to return the result. If the operation is successful, true will be returned. Otherwise, false will be returned.

Example:

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

function SaveToPLY(context: Context) : void {
  // Load the 3DGS plug-in.
  Scene.getDefaultRenderContext()?.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    let rf: SceneResourceFactory = scene.getResourceFactory();
    // Obtain the GSNode instance.
    let gsNode: spatialRender.GSNode = await rf.createNode({ name: "gs", path: "//gs" })
    // Obtain the GSEdit instance.
    let editor: spatialEdit.GSEdit = spatialEdit.GSEdit.editGSNode(gsNode);
    // Select Gaussian points within a 2D rectangular area (adding them to the current selection).
    let rect: Rect = {x: 0.25, y: 0.25, height: 0.5, width: 0.5};
    editor.selectBy2DBox(rect);
    // Delete Gaussian points in the current selection.
    editor.remove();
    // Save the edited model in PLY format to the sandbox path /data/storage/el2/base/haps/entry/files.
    // 'edited_model.ply' is only an example. Replace it with the actual one.
    let filePath: string = context.filesDir + "edited_model.ply";
    let result: boolean = await editor.saveToPLY(filePath);
    if (result) {
      console.info("Saved successfully.");
    } else {
      console.error ("Saving failed.");
    }
  });
}

[h2]extract3DMainBody

extract3DMainBody(pressPoint: Vec2): Promise<boolean>

Extracts the 3D subject based on the pressed point set. Upon completion, the extracted results will overwrite the in-memory GSNode data. This API uses a promise to return the result.

System capability: SystemCapability.Graphics.SpatialEdit

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

Since: 26.0.0

Parameters:

Name Type Mandatory Description
pressPoint Vec2 Yes Screen coordinates, which are used to specify the position of the subject to be extracted.

Returns:

Type Description
Promise<boolean> Promise used to return the result. If the operation is successful, true will be returned. Otherwise, false will be returned.

Example:

import { spatialRender, spatialEdit } from '@kit.SpatialReconKit';
import { Scene, SceneResourceFactory, Vec2 } from '@kit.ArkGraphics3D';

function extract3DMainBody() : void {
  // Load the 3DGS plug-in.
  Scene.getDefaultRenderContext()?.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
  // Load the scene.
  Scene.load().then(async (scene: Scene) => {
    let rf: SceneResourceFactory = scene.getResourceFactory();
    // Obtain the GSNode instance.
    let gsNode: spatialRender.GSNode = await rf.createNode({ name: "gs", path: "//gs" });
    // Obtain the GSEdit instance.
    let editor: spatialEdit.GSEdit = spatialEdit.GSEdit.editGSNode(gsNode);

    let pressPoint: Vec2 = { x: 0.5, y: 0.5 };
    // Extract the 3D object at the position.
    let result: boolean = await editor.extract3DMainBody(pressPoint);
  });
}