Ddd---update: en/application-dev/reference/apis-arkgraphics3d/js-apis-inner-scene-nodes.md

SceneNode

The module provides the types and operation methods of scene nodes in 3D graphics.

NOTE

The initial APIs of this module are supported since API version 12. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import { LayerMask, NodeType, Container, Node, Geometry, LightType, Light, SpotLight, DirectionalLight,
  Camera } from '@kit.ArkGraphics3D';

LayerMask

Defines the layer mask of a node.

getEnabled

getEnabled(index: number): boolean

Checks whether the mask is enabled for a layer of a given index.

System capability: SystemCapability.ArkUi.Graphics3D

Parameters

Name	Type	Mandatory	Description
index	number	Yes	Index of the layer. The value is an integer greater than or equal to 0.

Return value

Type	Description
boolean	Check result for whether the layer mask is enabled. true if enabled, false otherwise.

Example

import { Scene, Node } from '@kit.ArkGraphics3D';

function layerMask(): void {
  // Load scene resources, which supports .gltf and .glb formats. The path and file name can be customized based on the specific project resources.
  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"));
  scene.then(async (result: Scene) => {
    if (result) {
      let node : Node | null = result.getNodeByPath("rootNode_");
      if (node) {
          // Obtain the enabling status of the mask. You can perform subsequent processing on the return value based on service requirements.
          let enabled: boolean = node.layerMask.getEnabled(1);
      }
    }
  }).catch((error: Error) => {
    console.error('Scene load failed:', error);
  });
}

setEnabled

setEnabled(index: number, enabled: boolean): void

Enables the mask of a layer of a given index.

System capability: SystemCapability.ArkUi.Graphics3D

Parameters

Name	Type	Mandatory	Description
index	number	Yes	Index of the layer. The value is an integer greater than or equal to 0.
enabled	boolean	Yes	Whether to enable the layer mask. true to enable, false otherwise.

Example

import { Scene, Node } from '@kit.ArkGraphics3D';

function layerMask(): void {
  // Load scene resources, which supports .gltf and .glb formats. The path and file name can be customized based on the specific project resources.
  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"));
  scene.then(async (result: Scene) => {
    if (result) {
      let node : Node | null = result.getNodeByPath("rootNode/Scene/");
      if (node) {
          // Set the enabled status of the mask.
          node.layerMask.setEnabled(1, true);
      }
    }
  }).catch((error: Error) => {
    console.error('Scene load failed:', error);
  });
}

NodeType

Enumerates the node types.

System capability: SystemCapability.ArkUi.Graphics3D

Name	Value	Description
NODE	1	The node is an empty node.
GEOMETRY	2	Geometric type node.
CAMERA	3	Camera type node.
LIGHT	4	Light type node.
CUSTOM²¹⁺	255	Custom node, which is usually defined in an extension plugin.

Container<T>

Container for defining scene nodes. It provides a way to group scene nodes into a hierarchy.

append

append(item: T): void

Appends a node to the container.

System capability: SystemCapability.ArkUi.Graphics3D

Parameters

Name	Type	Mandatory	Description
item	T	Yes	Object of the T type.

Example

import { Scene, Node } from '@kit.ArkGraphics3D';

function append(): void {
  // Load scene resources, which supports .gltf and .glb formats. The path and file name can be customized based on the specific project resources.
  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"));
  scene.then(async (result: Scene) => {
    if (result) {
      let node : Node | null = result.getNodeByPath("rootNode/Scene/");
      if (node) {
        // Append a node. If the node is already in the children list, the total count does not change, but the operation is successful.
        result.root?.children.get(0)?.children.append(node);
      }
    }
  }).catch((error: Error) => {
    console.error('Scene load failed:', error);
  });
}

insertAfter

insertAfter(item: T, sibling: T | null): void

Inserts the object after the sibling node.

System capability: SystemCapability.ArkUi.Graphics3D

Parameters

Name	Type	Mandatory	Description
item	T	Yes	Node to be inserted.
sibling	T \| null	Yes	Sibling node.

Example

import { Scene, Node } from '@kit.ArkGraphics3D';

function insertAfter(): void {
  // Load scene resources, which supports .gltf and .glb formats. The path and file name can be customized based on the specific project resources.
  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"));
  scene.then(async (result: Scene) => {
    if (result) {
      let node : Node | null = result.getNodeByPath("rootNode/Scene/");
      if (node) {
        // Insert a node after another. If the node is already in the children list, the total count does not change, but the operation is successful.
        result.root?.children.get(0)?.children.insertAfter(node, null);
      }
    }
  }).catch((error: Error) => {
    console.error('Scene load failed:', error);
  });
}

remove

remove(item: T): void

Removes a node.

System capability: SystemCapability.ArkUi.Graphics3D

Parameters

Name	Type	Mandatory	Description
item	T	Yes	Node to remove.

Example

import { Scene, Node } from '@kit.ArkGraphics3D';

function remove(): void {
  // Load scene resources, which supports .gltf and .glb formats. The path and file name can be customized based on the specific project resources.
  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"));
  scene.then(async (result: Scene) => {
    if (result) {
      let node : Node | null = result.getNodeByPath("rootNode/Scene/");
      if (node) {
        // Call remove to remove a node.
        result.root?.children.remove(node);
      }
    }
  }).catch((error: Error) => {
    console.error('Scene load failed:', error);
  });
}

get

get(index: number): T | null

Obtains a node of a given index. If no node is obtained, null is returned.

System capability: SystemCapability.ArkUi.Graphics3D

Parameters

Name	Type	Mandatory	Description
index	number	Yes	Index of the node. The value is an integer greater than or equal to 0.

Return value

Type	Description
T \| null	Object obtained. If no object is obtained, null is returned.

Example

import { Scene, Node } from '@kit.ArkGraphics3D';

function get(): void {
  // Load scene resources, which supports .gltf and .glb formats. The path and file name can be customized based on the specific project resources.
  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"));
  scene.then(async (result: Scene) => {
    if (result) {
      let node : Node | null = result.getNodeByPath("rootNode/Scene/");
      // Get node 0 from children.
      result.root?.children.get(0)?.children.insertAfter(node, null);
    }
  }).catch((error: Error) => {
    console.error('Scene load failed:', error);
  });
}

clear

clear(): void

Clears all nodes in the container.

System capability: SystemCapability.ArkUi.Graphics3D

Example

import { Scene, Node } from '@kit.ArkGraphics3D';

function clear(): void {
  // Load scene resources, which supports .gltf and .glb formats. The path and file name can be customized based on the specific project resources.
  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"));
  scene.then(async (result: Scene) => {
    if (result) {
      let node : Node | null = result.getNodeByPath("rootNode/Scene/");
      if (node) {
        //Clear all child nodes of the node.
        node.children.clear();
      }
    }
  }).catch((error: Error) => {
    console.error('Scene load failed:', error);
  });
}

count

count(): number

Obtains the number of nodes in the container.

System capability: SystemCapability.ArkUi.Graphics3D

Return value

Type	Description
number	Number of nodes in the container. The value is a non-negative integer.

Example

import { Container, Scene, Node } from '@kit.ArkGraphics3D';

function count(): void {
  // Load scene resources, which supports .gltf and .glb formats. The path and file name can be customized based on the specific project resources.
  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"));
  scene.then(async (result: Scene) => {
    if (result) {
      let node : Node | null = result.getNodeByPath("rootNode_");
      if (node) {
        let container: Container<Node> = node.children;
        // Obtain the number of nodes in children.
        let count: number = container.count();
      }
    }
  });
}

Node

The 3D scene consists of nodes in a tree hierarchy, where each node implements a Node interface. This class inherits from SceneResource.

Properties

System capability: SystemCapability.ArkUi.Graphics3D

Name	Type	Read Only	Optional	Description
position	Position3	No	No	Node position, in scene units of the world coordinate system (for example, cm, m, or km).
rotation	Quaternion	No	No	Rotation angle of a node.
scale	Scale3	No	No	Node scale.
visible	boolean	No	No	Whether a node is visible. true if visible, false otherwise.
nodeType	NodeType	Yes	No	Node type.
layerMask	LayerMask	Yes	No	Layer mask of a node.
path	string	Yes	No	Node path.
parent	Node \| null	Yes	No	Parent node of the node and null if it does not exist.
children	Container<Node>	Yes	No	Child node of the node and null if it does not exist. This is a read-only property, indicating that you cannot directly replace the entire children container. However, you can operate the child nodes using container methods like append(), insertAfter(), remove(), or clear(). If the node being appended or inserted already exists in the container, it is removed first and then reinserted. As a result, the total number of child nodes remains unchanged, making the operation seem ineffective. The count increases only when a new node is added.

getNodeByPath

getNodeByPath(path: string): Node | null

Obtains a node by path. If no node is obtained, null is returned.

System capability: SystemCapability.ArkUi.Graphics3D

Parameters

Name	Type	Mandatory	Description
path	string	Yes	Path in the scene node tree. Each layer is separated by a slash (/).

Return value

Type	Description
Node \| null	Returns the node object.

Example

import { Scene, Node } from '@kit.ArkGraphics3D';

function getNode(): void {
  // Load scene resources, which supports .gltf and .glb formats. The path and file name can be customized based on the specific project resources.
  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"));
  scene.then(async (result: Scene) => {
    if (result && result.root) {
      // Search for a node.
      let geo : Node | null = result.root.getNodeByPath("scene/node");
    }
  });
}

Geometry

Geometric node type that holds renderable mesh data and supports optional deformation features. It inherits from Node.

System capability: SystemCapability.ArkUi.Graphics3D

Name	Type	Read Only	Optional	Description
mesh	Mesh	Yes	No	Mesh property.
morpher²⁰⁺	Morpher	Yes	Yes	Optional morpher that adds vertex-based deformation or animation effects to the geometry. If this parameter is not specified, the geometry does not support deformation.

LightType

Enumerates the light types.

System capability: SystemCapability.ArkUi.Graphics3D

Name	Value	Description
DIRECTIONAL	1	Directional light.
SPOT	2	Spot light.

Light

Light node, which inherits from Node.

System capability: SystemCapability.ArkUi.Graphics3D

Name	Type	Read Only	Optional	Description
lightType	LightType	Yes	No	Light type.
color	Color	No	No	Color.
intensity	number	No	No	Light density in candelas (cd) with a value range of real numbers greater than 0.
shadowEnabled	boolean	No	No	Whether the shadow effect is enabled. true if enabled, false otherwise.
enabled	boolean	No	No	Whether the light is used. true if used, false otherwise.

SpotLight

Spotlight, which inherits from Light.

A spotlight emits a conical beam of light in a specific direction, with the intensity of the light decaying according to the angles defined by the innerAngle and outerAngle parameters. Like a point light, a spotlight's intensity also diminishes with distance from the source.

System capability: SystemCapability.ArkUi.Graphics3D

Name	Type	Read Only	Optional	Description
innerAngle²³⁺	number	No	Yes	Angle from the center of the spotlight to the start of the decay, corresponding to the semi-apex angle of the cone, within which the light intensity does not decay with angle. The unit is radian (rad), and the default value is 0. The value must be greater than or equal to 0 and less than or equal to outerAngle.
outerAngle²³⁺	number	No	Yes	Angle from the center of the spotlight to the end of the decay, corresponding to the semi-apex angle of the cone, beyond which there is no light intensity. The unit is radian (rad), and the default value is PI/4. The value must be greater than or equal to innerAngle and less than or equal to PI/2.

NOTE

Ensure that the innerAngle and outerAngle values are proper. If the value set for outerAngle is greater than PI/2, it is forcibly set to PI/2 internally. If the value set for outerAngle is less than innerAngle, it is forcibly set to innerAngle internally.

DirectionalLight

Directional light, which inherits from Light.

System capability: SystemCapability.ArkUi.Graphics3D

Camera

Camera node, which inherits from Node.

Properties

System capability: SystemCapability.ArkUi.Graphics3D

Name	Type	Read Only	Optional	Description
fov	number	No	No	Field of view. The unit is radian (rad). The value ranges from 0 to π radians.
nearPlane	number	No	No	Near plane. The unit is the scene unit (such as cm, m, and km) in the world coordinate system. The value is greater than 0.
farPlane	number	No	No	Far plane. The unit is the scene unit (such as cm, m, and km) in the world coordinate system. The value is greater than that of nearPlane.
enabled	boolean	No	No	Whether the camera is enabled. true if enabled, false otherwise.
postProcess	PostProcessSettings \| null	No	No	Post-processing settings.
effects²¹⁺	Container<Effect>	Yes	No	Post-processing effects applied to the camera output.
clearColor	Color \| null	No	No	Color after the render target is cleared.
msaa²²⁺	boolean	No	Yes	Whether Multisample Anti-Aliasing (MSAA) is enabled. true if enabled, false otherwise. The default value is false.
renderingPipeline²¹⁺	RenderingPipelineType	No	Yes	Rendering pipeline type. If this parameter is not set, the lightweight forward rendering pipeline is used by default. (If the FORWARD_LIGHTWEIGHT pipeline is selected, certain features are unavailable.)

raycast²⁰⁺

raycast(viewPosition: Vec2, params: RaycastParameters): Promise<RaycastResult[]>

Casts a ray from a specific position on the screen to detect and retrieve information about all hit 3D objects. This API uses a promise to return the result.

System capability: SystemCapability.ArkUi.Graphics3D

Parameters

Name	Type	Mandatory	Description
viewPosition	Vec2	Yes	Normalized screen coordinates. The value range is [0, 1], where (0,0) corresponds to the top-left corner of the Component3D component, and (1,1) corresponds to the bottom-right corner.
params	RaycastParameters	Yes	Configuration parameters for raycasting, such as detection range and filtered nodes.

Return value

Type	Description
Promise<RaycastResult[]>	An array of hit objects sorted by distance (from nearest to farthest). If no objects are hit, an empty array is returned.

Example

import { SceneNodeParameters, Camera, SceneResourceFactory, Scene, Node, Vec2, Vec3, Quaternion,
  RaycastParameters } from '@kit.ArkGraphics3D';

function Raycast(): void {
  // Load scene resources, which supports .gltf and .glb formats. The path and file name can be customized based on the specific project resources.
  Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"))
    .then(async (result: Scene) => {
      if (!result.root) {
        return;
      }
      let node: Node | null | undefined = result.root.getNodeByPath("rootNode_/Unnamed Node 1/AnimatedCube");
      let sceneFactory: SceneResourceFactory = result.getResourceFactory();
      let sceneCameraParameter: SceneNodeParameters = { name: "camera1" };
      // Create a camera.
      let camera: Camera = await sceneFactory.createCamera(sceneCameraParameter);
      camera.enabled = true;
      // Set the camera view.
      lookAt(camera, { x: 0, y: 0, z: -3 }, { x: 0, y: 0, z: 0 }, { x: 0, y: 1, z: 0 });

      let viewPos: Vec2 = { x: 0.5, y: 0.5 };
      let raycastParams: RaycastParameters = {};
      if (node) {
        raycastParams.rootNode = node;
      }
      return camera.raycast(viewPos, raycastParams);
    });
}

// Vector subtraction, which returns the result of l - r.
function Sub(l: Vec3, r: Vec3): Vec3 {
  return { x: l.x - r.x, y: l.y - r.y, z: l.z - r.z };
}
// Vector dot product, which returns the inner product of l and r.
function Dot(l: Vec3, r: Vec3): number {
  return l.x * r.x + l.y * r.y + r.z * l.z;
}
// Vector normalization, which returns the unit vector of l.
function Normalize(l: Vec3): Vec3 {
  let d = Math.sqrt(Dot(l, l));
  return { x: l.x / d, y: l.y / d, z: l.z / d };
}
// Vector cross product, which returns the cross product of l and r.
function Cross(l: Vec3, r: Vec3): Vec3 {
  return { x: (l.y * r.z - l.z * r.y), y: (l.z * r.x - l.x * r.z), z: (l.x * r.y - l.y * r.x) };
}
// Quaternion scalar multiplication, which returns the result of quaternion l multiplied by scalar d.
function Mul(l: Quaternion, d: number): Quaternion {
  return {
    x: l.x * d,
    y: l.y * d,
    z: l.z * d,
    w: l.w * d
  };
}
// lookAt function: sets the position and orientation of the node to look from the eye position toward the center position, with up as the up direction.
function lookAt(node: Node, eye: Vec3, center: Vec3, up: Vec3) {

  let t: number;

  let q: Quaternion = {
    x: 0.0,
    y: 0.0,
    z: 0.0,
    w: 0.0
  };
  let f = Normalize(Sub(center, eye));
  let m0 = Normalize(Cross(f, up));
  let m1 = Cross(m0, f);
  let m2: Vec3 = { x: -f.x, y: -f.y, z: -f.z };
  if (m2.z < 0) {
    if (m0.x > m1.y) {
      t = 1.0 + m0.x - m1.y - m2.z;
      q = {
        x: t,
        y: m0.y + m1.x,
        z: m2.x + m0.z,
        w: m1.z - m2.y
      };
    } else {
      t = 1.0 - m0.x + m1.y - m2.z;
      q = {
        x: m0.y + m1.x,
        y: t,
        z: m1.z + m2.y,
        w: m2.x - m0.z
      };
    }
  } else {
    if (m0.x < -m1.y) {
      t = 1.0 - m0.x - m1.y + m2.z;
      q = {
        x: m2.x + m0.z,
        y: m1.z + m2.y,
        z: t,
        w: m0.y - m1.x
      };
    } else {
      t = 1.0 + m0.x + m1.y + m2.z;
      q = {
        x: m1.z - m2.y,
        y: m2.x - m0.z,
        z: m0.y - m1.x,
        w: t
      }
    }
  }
  node.position = eye;
  node.rotation = Mul(q, 0.5 / Math.sqrt(t));
}

getViewMatrix²³⁺

getViewMatrix(): Mat4x4

Obtains the view matrix of the camera.

System capability: SystemCapability.ArkUi.Graphics3D

Return value

Type	Description
Mat4x4	View matrix of the camera.

Example

import { Scene, SceneResourceFactory, SceneNodeParameters, Camera, Mat4x4 } from '@kit.ArkGraphics3D';

function GetViewMatrix(): void {
  // Load scene resources, which supports .gltf and .glb formats. The path and file name can be customized based on the specific project resources.
  Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"))
    .then(async (result: Scene) => {
      if (!result.root) {
        return;
      }
      let sceneFactory: SceneResourceFactory = result.getResourceFactory();
      let sceneCameraParameter: SceneNodeParameters = { name: "camera1" };
      // Create a camera.
      let camera: Camera = await sceneFactory.createCamera(sceneCameraParameter);
      camera.enabled = true;
      // Obtain the view matrix of the camera.
      let viewMatrix: Mat4x4 = camera.getViewMatrix();
    });
}

getProjectionMatrix²³⁺

getProjectionMatrix(): Mat4x4

Obtains the projection matrix of the camera.

System capability: SystemCapability.ArkUi.Graphics3D

Return value

Type	Description
Mat4x4	Projection matrix of the camera.

Example

import { Scene, SceneResourceFactory, SceneNodeParameters, Camera, Mat4x4 } from '@kit.ArkGraphics3D';

function GetProjectionMatrix(): void {
  // Load scene resources, which supports .gltf and .glb formats. The path and file name can be customized based on the specific project resources.
  Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"))
    .then(async (result: Scene) => {
      if (!result.root) {
        return;
      }
      let sceneFactory: SceneResourceFactory = result.getResourceFactory();
      let sceneCameraParameter: SceneNodeParameters = { name: "camera1" };
      // Create a camera.
      let camera: Camera = await sceneFactory.createCamera(sceneCameraParameter);
      camera.enabled = true;
      // Obtain the projection matrix of the camera.
      let projectionMatrix: Mat4x4 = camera.getProjectionMatrix();
    });
}

SceneNode

Modules to Import

LayerMask

getEnabled

setEnabled

NodeType

Container<T>

append

insertAfter

remove

get

clear

count

Node

Properties

getNodeByPath

Geometry

LightType

Light

SpotLight

DirectionalLight

Camera

Properties

raycast20+

getViewMatrix23+

getProjectionMatrix23+

raycast²⁰⁺

getViewMatrix²³⁺

getProjectionMatrix²³⁺