# SkinTokens (로컬 자동 리깅)

> 로컬 자동 리깅: VAST-AI의 SkinTokens가 캐릭터나 크리처 메시(GLB, OBJ, FBX)에 스켈레톤과 스킨 웨이트를 추가하고, 원본 머티리얼과 UV를 유지한 리깅된 GLB를 출력합니다. 14 GB의 VRAM을 갖춘 NVIDIA GPU에서 Asset Studio로 실행됩니다. MIT, 상업적 사용 허용.

- Id: `aigd.model3d-skintokens`
- 소스: 공식 (자사 `aigd.*`)
- 카테고리: 도구
- 게시자: AI Game Dev (`aigd`), 인증됨
- 최신 버전: 1.0.4 (2026-11-22 게시)
- 라이선스: MIT
- AI Game Dev 앱 필요: `>=0.32.0-beta.6`
- 네이티브 코드: 아니요
- 평점: 아직 평가 없음
- HTML 페이지: https://ai-game.dev/ko/packages/aigd.model3d-skintokens

## 설치

gamedev CLI를 사용한다면 프로젝트 폴더에서:

```bash
gamedev pkg add aigd.model3d-skintokens
```

데스크톱 앱에서 Packages 창을 열고(상태 표시줄의 패키지 아이콘) **Browse**를 선택한 뒤 `aigd.model3d-skintokens`를 검색하고 **Add to Project**를 클릭합니다. 자세히: https://ai-game.dev/docs/wiki/app/packages

## 버전

| 버전 | 게시일 | 앱 필요 | 참고 |
|---|---|---|---|
| 1.0.4 | 2026-11-22 | `>=0.32.0-beta.6` | 최신 |
| 1.0.3 | 2026-11-21 | `>=0.32.0-beta.6` | - |

## 설명

````markdown
# SkinTokens (`aigd.model3d-skintokens`)

SkinTokens는 NVIDIA GPU(VRAM 14 GB 이상)에서 VAST-AI의 [SkinTokens](https://github.com/VAST-AI-Research/SkinTokens)로 3D 모델을 리깅합니다. 캐릭터나 크리처 메시의 스켈레톤과 스킨 웨이트를 예측해 원본 파일에 기록하므로 머티리얼과 UV가 그대로 유지됩니다. 결과물은 리깅된 GLB입니다. AI Game Dev에서는 **Local Python models runtime**(`aigd.python`)을 통해 로컬로 실행됩니다. 생성했거나 직접 만든 캐릭터를 애니메이션하기 전에 첫 리그가 필요한 개발자에게 적합합니다.

## 무엇을 만들 수 있나요

- GLB, OBJ 또는 FBX 메시로 만든 리깅된 캐릭터와 크리처로, 엔진이나 DCC 도구에서 바로 애니메이션할 수 있습니다.
- 로컬 image-to-3D 모델이 만든 메시를 위한 1차 스켈레톤과 스킨 웨이트.
- 하나의 메시에 대한 여러 리그 후보: 실행할 때마다 새로운 스켈레톤을 샘플링합니다.

## 사용 방법

리깅은 채팅 에이전트가 아니라 **Asset Studio**에서 실행됩니다:

1. Asset Studio를 열고 **3D → SkinTokens → Rig**를 선택합니다.
2. 리깅할 메시를 추가합니다: `Assets/Models/goblin.glb` 같은 GLB, OBJ 또는 FBX 파일입니다.
3. 리깅된 GLB를 확인합니다. 스켈레톤이 모델에 맞지 않으면 다시 실행하세요. 실행할 때마다 새로운 스켈레톤을 샘플링합니다.

## 주요 특징

|  |  |
|---|---|
| 모델 id | `aigd.model3d-skintokens.v1` |
| 동작 | 3D 모델 리깅(입력 메시 1개: GLB, OBJ 또는 FBX) |
| 출력 | 스켈레톤과 스킨 웨이트가 포함된 리깅된 GLB, 원본 머티리얼과 UV 유지 |
| 실행 환경 | VRAM 14 GB 이상의 NVIDIA GPU(CUDA) |
| 다운로드 | 약 1.6 GB, 첫 로드 시 런타임의 Python 환경(Blender가 Python 모듈로 포함) 추가 |
| 라이선스 | MIT, 모델과 그 리그의 상업적 사용 허용 |

리깅할 메시는 [TripoSG](https://ai-game.dev/packages/aigd.model3d-triposg), [Hunyuan3D-2.1 Shape](https://ai-game.dev/packages/aigd.model3d-hunyuan3d-2-1-shape), [Step1X-3D Geometry](https://ai-game.dev/packages/aigd.model3d-step1x-3d-geometry), [TRELLIS.2](https://ai-game.dev/packages/aigd.model3d-trellis2-4b) 또는 직접 사용하는 도구에서 가져올 수 있습니다.

## 실행 방식

이 패키지는 데이터만 포함합니다. **Local Python models runtime**(`aigd.python`)이 필요합니다. 첫 로드 시 PyTorch와 Blender를 Python 모듈로 포함한 전용 Python 3.11 환경을 구성합니다(`bpy` 4.5 LTS, 약 330 MB). 메시 읽기와 쓰기는 Blender가 담당합니다. FlashAttention은 설치되지 않습니다: 어텐션은 PyTorch의 내장 커널로 실행됩니다. Open3D도 설치되지 않습니다: 스킨 웨이트 스무딩용 복셀 그리드는 Open3D와 동일한 수학을 사용해 NumPy로 구성합니다. 체크포인트는 코드가 아닌 텐서로만 로드됩니다. 모델은 오프라인으로 실행되며, 가중치는 사용자가 확인한 후 Hugging Face에서 다운로드하는 아래 파일에서만 가져옵니다. AI Game Dev는 이를 호스팅하지 않습니다.

## 무엇이 다운로드되나요

약 1.6 GB, Hugging Face 리비전과 sha256으로 고정됩니다:

| 파일 | 크기 | 라이선스 | 출처 |
|---|---|---|---|
| `skin_vae_2_10_32768-last.ckpt` | 0.49 GB | MIT | [파일](https://huggingface.co/VAST-AI/SkinTokens/resolve/79736cad0fd84de384d5eede659b4ebd24effe33/experiments/skin_vae_2_10_32768/last.ckpt) |
| `articulation_xl_quantization_256_token_4-grpo_1400.ckpt` | 1.13 GB | MIT | [파일](https://huggingface.co/VAST-AI/SkinTokens/resolve/79736cad0fd84de384d5eede659b4ebd24effe33/experiments/articulation_xl_quantization_256_token_4/grpo_1400.ckpt) |
| `Qwen3-0.6B-config.json` | 0.00 GB | Apache-2.0 | [파일](https://huggingface.co/Qwen/Qwen3-0.6B/resolve/c1899de289a04d12100db370d81485cdf75e47ca/config.json) |

모델의 Python 코드(`src/`, `configs/skeleton/`)는 GitHub의 커밋 [`273b691`](https://github.com/VAST-AI-Research/SkinTokens/tree/273b691d35989d71cd17ff2895fdc735097b92d1)에서 다운로드하며, 각 파일은 sha256으로 검증합니다.

## 라이선스

- **가중치와 코드: MIT**, © 2025 VAST-AI-Research ([라이선스](https://github.com/VAST-AI-Research/SkinTokens/blob/273b691d35989d71cd17ff2895fdc735097b92d1/LICENSE), [모델 카드](https://huggingface.co/VAST-AI/SkinTokens/tree/79736cad0fd84de384d5eede659b4ebd24effe33)).
- **Qwen3-0.6B 구성 파일**: Apache-2.0, © Alibaba Cloud ([모델 카드](https://huggingface.co/Qwen/Qwen3-0.6B/tree/c1899de289a04d12100db370d81485cdf75e47ca)). `config.json`만 다운로드하며, 언어 모델의 가중치는 SkinTokens에 포함되어 있습니다.
- **Blender as a Python module**(`bpy` 4.5.16): GPL-3.0-or-later, © Blender Foundation ([PyPI](https://pypi.org/project/bpy/4.5.16/)). 런타임이 PyPI에서 모델의 전용 환경으로 설치하며, 앱의 리깅 핸들러가 이를 임포트해 메시를 읽고 씁니다. AI Game Dev는 bpy를 배포하지 않습니다.
- **리깅 핸들러**(앱의 Python 런타임에 있는 `skintokens/handler.py`): bpy를 임포트하므로 **GPL-3.0-or-later**입니다. 별도 프로그램으로, 모델 자체의 Python 워커 프로세스에서 실행되며, 앱은 이 프로세스를 시작하고 stdio를 통한 JSON 메시지로만 통신합니다. 소스는 앱과 함께 배포됩니다. `THIRD_PARTY_NOTICES.md`를 참고하세요.

필수 저작자 표시: "SkinTokens © 2025 VAST-AI-Research (MIT)".

**제한 사항:** 모델과 그것이 만든 리그의 상업적 사용은 허용됩니다. 가중치를 재배포하려면 MIT 저작권 고지를 포함해야 합니다.
````
