# 3D人物模型

**Repository Path**: licq_workspace/3d-task-model

## Basic Information

- **Project Name**: 3D人物模型
- **Description**: demo展示，只用于学习
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-04
- **Last Updated**: 2026-08-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HarmonyHuman3D — 鸿蒙 3D 人物案例(ArkGraphics 3D 原生)

一个基于 HarmonyOS **ArkGraphics 3D**(`@kit.ArkGraphics3D`)的 3D 人物案例:展示一个可交互的 3D 人形,支持**手指拖拽旋转**、**身高/体重滑块实时调节体型**、**BMI 实时计算**,以及自动旋转/重置。

技术路线为**原生 ArkGraphics 3D**(非 WebView),契合鸿蒙原生与 KMP 多端架构。详细设计见 [`docs/DESIGN.md`](docs/DESIGN.md)。

---

## 功能

- 🧍 **3D 人形渲染**:加载 glTF 2.0 模型,PBR 材质 + 双平行光
- 🔄 **拖拽旋转**:水平拖拽人物绕 Y 轴旋转(四元数),捏合缩放镜头
- 📏 **身高/体重调节**:滑块实时驱动体型(身高=Y 缩放,体重=BMI 驱动 XZ 围度)
- 📊 **BMI 计算**:实时显示数值与分类(偏瘦/正常/超重/肥胖),分类色联动
- 🔁 **自动旋转 / 重置**

## 快速上手

> 前置:DevEco Studio(最新稳定版)、HarmonyOS 5.0+(API 12+,`Component3D` 最低要求)。

1. **放入模型**(必须,否则渲染空白):
   ```bash
   bash tools/fetch-model.sh
   ```
   会下载 Khronos CC0 人形 `RiggedFigure.glb` 并改名为 `human.glb` 放入 `entry/src/main/resources/rawfile/gltf/`。
   也可手动放入任意 CC0 glTF 人形(文件名 `human.glb`)。

2. **DevEco Studio 打开** `HarmonyHuman3D/` 目录 → `File → Sync and Refresh Project`。

3. **Run `entry`** 到 API 12+ 模拟器/真机。

4. 期望:模型可见 → 左右拖拽旋转 → 拖身高/体重滑块人物实时变形 → BMI 随动。

## 调试:旋转/缩放不生效?

不同 glTF 的根节点 path 不同。打开 `entry/src/main/ets/scene/HumanSceneManager.ets` 中的 `DEBUG_DUMP_NODES = true`,运行后用 DevEco HiLog 过滤 `HumanScene`,把打印出的**根节点 path** 填入 `ROOT_NODE_PATH` 常量即可。

## 项目结构

```
HarmonyHuman3D/
├── AppScope/                       # 应用级配置
├── entry/                          # 主 HAP 模块
│   └── src/main/
│       ├── ets/
│       │   ├── entryability/EntryAbility.ets
│       │   ├── pages/Human3DPage.ets          # 主页面:Component3D + 手势 + 面板
│       │   ├── scene/
│       │   │   ├── Math3D.ets                  # lookAt / 四元数 / 向量工具
│       │   │   └── HumanSceneManager.ets       # 场景生命周期 / 相机 / 光照 / 体型
│       │   ├── model/
│       │   │   ├── BodyParams.ets              # 身高/体重/BMI 模型
│       │   │   └── BodyScaler.ets             # 身高体重→scale 映射
│       │   └── components/BodyControlPanel.ets # 滑块面板
│       └── resources/
│           └── rawfile/gltf/                   # glTF 模型放这里
├── docs/DESIGN.md                  # 详细设计
└── tools/fetch-model.sh            # 拉取 CC0 glTF 模型
```

## 技术要点

- **渲染**:ArkGraphics 3D `Scene.load($rawfile(...))` → `getResourceFactory()` 建相机/光照 → `Component3D(sceneOptions)` 渲染
- **取节点**:`scene.getNodeByPath(path)`(按路径,非 getNodeByName)
- **旋转**:`Node.rotation` 为**四元数** `{x,y,z,w}`,人物水平旋转用绕 Y 轴四元数
- **体型**:ArkGraphics 3D 在 API 13+ 暂未暴露 morph 权重 → 用**节点 scale** 兜底(模型无关、必能跑)
- **相机**:无内置 `lookAt`,`Math3D.lookAt` 复刻官方 raycast 示例的用户态实现

## 许可与致谢

- 代码:Apache-2.0
- 模型:按各自来源协议(默认 Khronos `RiggedFigure`,CC0)