1# Building and Managing ArkGraphics 3D Scenes
2
3A 3D scene consists of three essential parts: light, camera, and model.
4- Light provides illumination for a 3D scene so that the models in the 3D scene become visible. Without light, the rendering result is all black.
5- The camera acts as a viewer of the 3D scene. In essence, 3D rendering is to observe a 3D scene from a perspective and project it to a 2D image. Without a camera, no rendering result is obtained.
6- A model in a 3D scene is used to describe a shape, structure, and appearance of an object, and generally has attributes such as meshes, materials, textures, and animations. Popular 3D model formats are OBJ, FBX, and glTF.
7
8After a model is loaded, it can be rendered using the ArkUI component [Component3D](../reference/apis-arkui/arkui-ts/ts-basic-components-component3d.md). You can also call ArkTS APIs to modify the camera and light settings, which will help you achieve the desired perspective and lighting conditions. The ArkTS APIs can use NAPIs to call the capabilities implemented by C++ APIs in AGP.
9
10![3D scene display process](./figures/scene.PNG)
11
12## Model Loading and Display
13Models come in a multitude of formats, but currently, ArkGraphics 3D supports only the loading of glTF models. glTF represents 3D scenes. For details about glTF, see [glTF-2.0](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html).
14
15A glTF model can contain key elements of a 3D scene, including the light, camera, and model. If a glTF model contains a camera, you can use the APIs provided by ArkGraphics 3D to load the glTF model to render the 3D scene in the camera view. If the model does not contain a camera, you can use the ArkGraphics 3D APIs to create a camera for rendering. Due to the large size, a 3D model is usually loaded in asynchronous mode. After a model is loaded, a scene object is returned, based on which you can edit the 3D scene.
16
17You can call the [load](../reference/apis-arkgraphics3d/js-apis-inner-scene.md#load) API provided by **Scene** to load a glTF model. The sample code is as follows:
18```ts
19import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
20  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
21
22function loadModel() : void {
23  // Load the model.
24  let scene: Promise<Scene> = Scene.load($rawfile("gltf/DamagedHelmet/glTF/DamagedHelmet.gltf"));
25  scene.then(async (result: Scene) => {});
26}
27```
28
29Once the model is loaded, you can use the **SceneResourceFactory** instance to create a camera and light source, and modify the camera and light settings to adjust the viewing angle and illumination effect. Finally, you can pass the **Scene** instance and **ModelType** as **SceneOptions** to the **Component3D** component to display them on the screen.
30
31Below is the comprehensive sample code for displaying a model. It is crucial to verify that the .gltf file's content and its path are correctly specified.
32
33```ts
34import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
35  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
36
37@Entry
38@Component
39struct Model {
40  scene: Scene | null = null;
41  @State sceneOpt: SceneOptions | null = null;
42  cam: Camera | null = null;
43
44  onPageShow(): void {
45    this.Init();
46  }
47
48  Init(): void {
49    if (this.scene == null) {
50      // Load the model and place the .gltf file in the related path. Use the actual path during loading.
51      Scene.load($rawfile('gltf/DamagedHelmet/glTF/DamagedHelmet.gltf'))
52      .then(async (result: Scene) => {
53        this.scene = result;
54        let rf:SceneResourceFactory = this.scene.getResourceFactory();
55        // Create a camera.
56        this.cam = await rf.createCamera({ "name": "Camera" });
57        // Set proper camera parameters.
58        this.cam.enabled = true;
59        this.cam.position.z = 5;
60        this.sceneOpt = { scene: this.scene, modelType: ModelType.SURFACE } as SceneOptions;
61      })
62      .catch((reason: string) => {
63        console.log(reason);
64      });
65    }
66  }
67
68  build() {
69    Row() {
70      Column() {
71        if (this.sceneOpt) {
72          // Use Component3D to display the 3D scenario.
73          Component3D(this.sceneOpt)
74        } else {
75          Text("loading ...")
76        }
77      }.width('100%')
78    }.height('60%')
79  }
80}
81```
82
83## Creating and Managing a Camera
84
85As an important part of a 3D scene, a camera determines the projection process from the 3D scene to a 2D image. Key camera parameters, such as the near plane, far plane, and FoV, also pose an important impact on 3D rendering. You can set these camera parameters to control the rendering process, thereby achieving the desired rendering effect.
86
87The sample code for camera-related control is as follows:
88```ts
89import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
90  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
91
92function createCameraPromise() : Promise<Camera> {
93  return new Promise(() => {
94    let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
95    scene.then(async (result: Scene) => {
96      let sceneFactory: SceneResourceFactory = result.getResourceFactory();
97      let sceneCameraParameter: SceneNodeParameters = { name: "camera1" };
98      // Create a camera.
99      let camera: Promise<Camera> = sceneFactory.createCamera(sceneCameraParameter);
100      camera.then(async (cameraEntity: Camera) => {
101        // Enable the camera node.
102        cameraEntity.enabled = true;
103
104        // Set the camera position.
105        cameraEntity.position.z = 5;
106
107        // Set the FoV.
108        cameraEntity.fov = 60 * Math.PI / 180;
109
110        // Set other camera parameters.
111        // ...
112      });
113      return camera;
114    });
115  });
116}
117```
118
119
120## Creating and Managing Light
121
122Light in a 3D scene is a data model that simulates the impact of the light in the physical world on an object in the 3D scene.
123
124There are many types of lights, for example, directional light and spot light. Directional light, similar to the sunlight, emits parallel light rays with uniform intensity. Spot light is like a flashlight that produces cone-shaped light, which attenuates with distance. The light color also affects the color of the object in the scene. The interaction between the light color and the object color should be consistent with that in the physical world. ArkGraphics 3D provides APIs for creating light and modifying light parameters. You can adjust the 3D scene by setting light attributes to obtain the expected rendering effect.
125
126The sample code for controlling light is as follows:
127```ts
128import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
129  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
130
131function createLightPromise() : Promise<Light> {
132  return new Promise(() => {
133    let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
134    scene.then(async (result: Scene) => {
135      let sceneFactory: SceneResourceFactory = result.getResourceFactory();
136      let sceneLightParameter: SceneNodeParameters = { name: "light" };
137      // Create directional light.
138      let light: Promise<Light> = sceneFactory.createLight(sceneLightParameter, LightType.DIRECTIONAL);
139      light.then(async (lightEntity: Light) => {
140        // Set the color of the directional light.
141        lightEntity.color = { r: 0.8, g: 0.1, b: 0.2, a: 1.0 };
142
143        // Set other light parameters.
144        // ...
145      });
146      return light;
147    });
148  });
149}
150```
151