# ThreejsGNM

**Repository Path**: Images_3d_project/ThreejsGNM

## Basic Information

- **Project Name**: ThreejsGNM
- **Description**: 人头项目3：用three实现的人头编辑器
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-08-05
- **Last Updated**: 2026-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Three.js GNM Head Editor

A client-only TypeScript port of the Google GNM v3 head model and the reference
Blender editor. It evaluates identity, expression, pose correctives, and
four-joint skinning in the browser, then renders the generated head with
Three.js.

## Run locally

Requirements: Node.js 20 or newer.

```bash
npm install
npm run dev
```

Open the URL printed by Vite (normally `http://localhost:5173`). There is no
application server or API: Vite only serves static local files during
development.

```bash
npm test
npm run build
npm run preview
```

The production output is in `dist/` and can be served by any static file host.

## Model assets

The initial load downloads and decompresses the official 53 MB
`gnm_head.npz`. The browser retains larger uncompressed basis tensors in GPU
memory, so a desktop browser with WebGL enabled is recommended.

Official assets are stored in `public/gnm/` and retain Google's Apache-2.0
license and attribution. To download and regenerate them:

```bash
python3 -m pip install numpy h5py
npm run assets:prepare
```

The preparation step converts the two Keras HDF5 semantic decoders to a compact
NPZ consumed directly by TensorFlow.js. No Python dependency is required to run
or build the web app after the assets have been prepared.

## Features

- Full 253-component identity and 383-component expression state
- Seeded semantic identity and 20-class expression sampling
- Identity/expression blending and bilateral eye-expression mirroring
- Neck, head, and independent eye pose controls
- Official topology, per-corner UVs, texture, and anatomical materials
- Browser-saved named presets and Blender-compatible JSON import/export

GNM has documented representation limitations inherited from its training
data. Review the upstream project before using demographic controls in a
product or study.