3D模型加载：支持glTF/OBJ等格式的模型渲染（185）

Davina_yu

156人浏览 · 2026-07-16 17:37:45

Davina_yu · 2026-07-16 17:37:45 发布

在鸿蒙（HarmonyOS）系统中进行 3D 模型加载与渲染，核心依赖于系统级的 ArkGraphics 3D 框架。虽然开发者可以在 ArkTS 中导入 OBJ、GLTF 等多种标准 3D 格式，但 ArkGraphics 3D 引擎在底层仅原生支持 glTF 2.0 格式（.gltf 或 .glb）的加载与渲染。对于 OBJ 等其他格式，通常建议在开发前通过专业建模工具将其转换为 glTF 格式，或通过 WebGL 容器（如 Three.js）进行渲染。

一、核心加载机制与场景构建

在 ArkGraphics 3D 中，模型加载与场景渲染遵循严格的节点树结构。一个完整的 3D 场景由 Scene（场景）、Camera（相机）、Light（灯光）和 Node（模型节点）构成。

异步加载与场景导入
开发者需将模型文件置于应用的 rawfile 目录下。通过 Scene.load() 异步加载模型源场景后，需创建一个空的目标场景，并使用 importScene 方法将模型节点树挂载到目标场景的根节点下。
节点克隆与复用
当场景中需要渲染大量相同的物体（如一排椅子或树木）时，无需多次加载同一模型文件。开发者可通过 cloneNode 方法在同一个场景内直接克隆节点，从而大幅降低内存开销和 Draw Call 数量。
UI 联动与手势交互
加载完成的场景可通过 Component3D 或 Scene3D 组件嵌入 ArkUI 界面。结合鸿蒙的手势事件（如 PanGesture 旋转、PinchGesture 缩放），可实现模型与原生 UI 的无缝联动。

// ModelViewer.ets
import { Scene, SceneOptions, ModelType } from '@kit.ArkGraphics3D';

@Entry
@Component
struct ModelViewer {
    @State sceneOptions: SceneOptions | undefined = undefined;

    aboutToAppear() {
        // 1. 异步加载 rawfile 目录下的 glTF 模型
        Scene.load($rawfile('gltf/Cube/glTF/Cube.gltf')).then(async (result: Scene) => {
            // 2. 构建场景配置
            this.sceneOptions = {
                scene: result,
                modelType: ModelType.SURFACE
            } as SceneOptions;
        }).catch((err: Error) => {
            console.error('3D模型加载失败:', err);
        });
    }

    build() {
        Column() {
            if (this.sceneOptions) {
                // 3. 使用 Component3D 组件渲染 3D 场景
                Component3D(this.sceneOptions)
                    .width('100%')
                    .height('80%')
                    // 4. 绑定手势交互（如旋转）
                    .gesture(
                        PanGesture({ fingers: 1 })
                            .onActionUpdate((event: GestureEvent) => {
                                // 此处可更新模型的旋转角度
                                console.info(`旋转偏移: X=${event.offsetX}, Y=${event.offsetY}`);
                            })
                    )
            } else {
                LoadingProgress().width(48).height(48)
            }
        }.width('100%').height('100%')
    }
}

二、资源管理与生命周期控制

3D 模型加载对设备的 GPU 和内存消耗极大，必须遵循严格的资源管理规范。

模型轻量化与压缩
推荐使用 .glb 二进制格式以提升加载效率。对于复杂模型，需在建模工具中简化三角面数量，并将纹理压缩为 ETC2 等格式以减少显存占用。
异步预加载与资源销毁
为避免阻塞 UI 主线程，大模型应采用异步预加载机制。当用户退出 3D 页面或组件销毁时，必须显式调用 scene.destroy() 释放占用的内存和 GPU 资源，防止内存泄漏。

// LifecycleManager.ets
import { Scene } from '@kit.ArkGraphics3D';

export class LifecycleManager {
    private activeScene: Scene | null = null;

    // 绑定加载完成的场景
    public bindScene(scene: Scene) {
        this.activeScene = scene;
    }

    // 核心：在组件销毁或页面隐藏时释放 GPU 资源
    public destroyScene() {
        if (this.activeScene) {
            this.activeScene.destroy();
            this.activeScene = null;
            console.info('3D场景资源已安全释放');
        }
    }
}

// 在 ArkUI 组件中应用
@Entry
@Component
struct Safe3DPage {
    private lifecycleManager = new LifecycleManager();

    aboutToDisappear() {
        // 页面销毁时强制释放资源，防止内存泄漏
        this.lifecycleManager.destroyScene();
    }
}

三、渲染优化与高级特性

LOD 分级加载
针对高精度工业模型，可创建高、中、低三种精度的 LOD 模型。系统根据相机与物体的距离自动切换显示精度，确保远距离时的渲染帧率。
批处理渲染
将相同材质的模型节点进行合并（Merge Nodes），可以显著减少 GPU 的 Draw Call 数量，提升整体渲染性能。
高级模型支持（3DGS）
除了传统的 glTF 模型，ArkGraphics 3D 还支持加载 3D Gaussian Splatting (3DGS) 模型（支持 MP4、PLY、GLB 格式），通过加载 spatialRender 插件可实现高保真的空间建模渲染。

// RenderOptimizer.ets
import { Scene, RenderParameters } from '@kit.ArkGraphics3D';

export class RenderOptimizer {
    // 当模型旋转或场景发生变化时，主动请求渲染帧更新
    public static requestRenderFrame(activeScene: Scene | null): void {
        if (activeScene === null) return;
        
        const params: RenderParameters = {
            alwaysRender: true // 即使场景没有变化也强制渲染，确保交互流畅
        };
        activeScene.renderFrame(params);
    }
}

四、多模型场景构建与空间布局

在复杂的业务场景中，通常需要同时展示多个模型以构建完整的 3D 空间。ArkGraphics 3D 提供了灵活的节点树管理机制来支撑这一需求。

多模型层级管理：开发者可以在同一个 Scene3D 容器中加载多个独立的 Model3D 组件。通过为每个模型配置独立的 position（位置）、scale（缩放）和 rotation（旋转）参数，可以精确控制它们在三维空间中的相对位置。
动态场景编排：除了静态摆放，开发者还可以根据业务逻辑动态调整场景树。例如，在数字展厅应用中，可以根据用户的浏览进度，动态加载或卸载特定区域的展品模型，从而实现大场景的按需渲染。

// MultiModelScene.ets
import { Scene, SceneOptions, ModelType } from '@kit.ArkGraphics3D';

@Entry
@Component
struct MultiModelScene {
    @State sceneOptions: SceneOptions | undefined = undefined;

    aboutToAppear() {
        Scene.load($rawfile('models/exhibition_hall.glb')).then(async (result: Scene) => {
            this.sceneOptions = {
                scene: result,
                modelType: ModelType.SURFACE
            } as SceneOptions;
        });
    }

    build() {
        if (this.sceneOptions) {
            Scene3D({ sceneConfig: { /* 场景基础配置 */ } }) {
                // 主展品模型
                Model3D({ modelConfig: { src: 'models/product.glb' } })
                    .position([0, 0, 0])
                    .scale([1, 1, 1])
                
                // 底座模型，通过独立坐标控制空间相对位置
                Model3D({ modelConfig: { src: 'models/base.glb' } })
                    .position([0, -1, 0])
                    .scale([2, 2, 2])
            }
            .width('100%')
            .height('100%')
        }
    }
}

五、光照系统与 PBR 材质渲染

为了让 3D 模型摆脱“塑料感”，呈现出逼真的物理质感，必须合理配置光照与材质。

多光源协同：ArkGraphics 3D 支持环境光（Ambient Light）、方向光（Directional Light）和点光源（Point Light）的组合配置。环境光提供基础照明，方向光模拟太阳光产生阴影，点光源则用于突出特定模型的局部细节。
PBR 材质管线：引擎内置了完整的基于物理的渲染（PBR）纹理管线。当加载 glTF 模型时，引擎会自动解析模型自带的金属度（Metallic）、粗糙度（Roughness）和法线贴图（Normal Map），结合场景中的光照信息，实时计算出真实的光影反射效果。

// LightingAndMaterial.ets
import { scene3d } from '@kit.ArkGraphics3D';

export class LightingAndMaterial {
    // 1. 多光源协同配置
    public static getSceneLightingConfig(): scene3d.SceneConfig {
        return {
            ambientLight: { color: '#FFFFFF', intensity: 0.5 }, // 基础照明
            directionalLight: { 
                color: '#FFFFFF', 
                intensity: 1.0, 
                direction: [-1, -1, -1] // 模拟太阳光
            },
            pointLights: [{
                color: '#FF5722',
                intensity: 2.0,
                position: [3, 3, 3],
                range: 10 // 局部细节点光源
            }]
        };
    }

    // 2. PBR 材质参数说明（通常在 glTF 中自带，也可通过代码覆盖）
    // 引擎会自动解析 Metallic, Roughness, Normal Map 进行物理渲染
}

六、相机控制与空间裁剪优化

相机的配置直接决定了 3D 场景的视觉呈现与渲染性能。

视场角与裁剪面配置：开发者需合理设置相机的 fov（视场角）、near（近裁剪面）和 far（远裁剪面）。近裁剪面设置过大会导致模型被“切头”，设置过小则会引发深度缓冲（Z-fighting）闪烁；远裁剪面则决定了场景的可见深度，超出范围的模型将被剔除以节省 GPU 算力。
平滑的视角过渡：在用户通过手势交互或程序控制相机移动时，应避免生硬的位置跳变。可通过插值算法（Lerp）平滑过渡相机的 position 和 lookAt 目标点，为用户提供流畅的漫游体验。

// CameraControl.ets
import { scene3d } from '@kit.ArkGraphics3D';

@Entry
@Component
struct CameraControlView {
    @State rotationY: number = 0;
    @State modelScale: number = 1;

    private cameraConfig: scene3d.CameraConfig = {
        position: [0, 2, 5],
        lookAt: [0, 0, 0],
        up: [0, 1, 0],
        fov: 45,
        near: 0.1,  // 近裁剪面：防止模型切头
        far: 100,   // 远裁剪面：剔除远处不可见模型
    };

    build() {
        Scene3D({ sceneConfig: { camera: this.cameraConfig } }) {
            Model3D({ modelConfig: { src: 'models/product.glb' } })
                .rotation([0, this.rotationY, 0])
                .scale([this.modelScale, this.modelScale, this.modelScale])
        }
        // 拖拽手势控制旋转
        .gesture(
            PanGesture().onActionUpdate((event: GestureEvent) => {
                this.rotationY += event.offsetX * 0.5;
            })
        )
        // 捏合手势控制缩放（限制极端值）
        .gesture(
            PinchGesture().onActionUpdate((event: GestureEvent) => {
                this.modelScale = Math.max(0.5, Math.min(3, this.modelScale * event.scale));
            })
        )
    }
}

七、动画系统与时间轴控制

glTF 模型通常自带骨骼或关键帧动画，ArkGraphics 3D 提供了精细的动画控制能力。

动画播放与进度控制：通过访问 Scene.animations 数组，开发者可以获取模型内置的动画片段。支持调用 start() 播放、pause() 暂停，以及使用 seek(0.3) 等方法将动画跳转到指定的归一化进度（0~1）。
动画事件回调：系统提供了 onStarted 和 onFinished 回调函数。开发者可以利用这些回调来同步 UI 状态，例如在模型播放完“开门”动画后，自动弹出相关的业务介绍面板。

// AnimationController.ets
import { scene3d } from '@kit.ArkGraphics3D';

@Entry
@Component
struct AnimationControlView {
    @State animationController: scene3d.AnimationController = new scene3d.AnimationController();

    build() {
        Column() {
            Scene3D({ sceneConfig: { /* 配置 */ } }) {
                Model3D({ modelConfig: { src: 'models/character.glb' } })
                    .onComplete(() => {
                        console.info('模型加载完成');
                        // 播放模型内置的第一个动画
                        this.animationController.play(0); 
                    })
            }

            // 动画控制按钮
            Row({ space: 20 }) {
                Button('暂停动画')
                    .onClick(() => this.animationController.pause())
                Button('跳转至50%进度')
                    .onClick(() => this.animationController.seek(0.5))
                Button('继续播放')
                    .onClick(() => this.animationController.play())
            }
        }
    }
}