# cat2avatar

**Repository Path**: cat2bug/cat2avatar

## Basic Information

- **Project Name**: cat2avatar
- **Description**: JS前端脸谱系统
- **Primary Language**: TypeScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-14
- **Last Updated**: 2026-05-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Cat2Avatar

可组合的 2D 头像部件系统：用归一化 SVG 片段（`.c2a`）描述脸型、五官与配饰，经校验与合成后供 API 与前端消费。

## 项目简介

Cat2Avatar 将头像拆分为多个 **slot**（如 `headShape`、`eyes`、`ears`），每个部件一个 `.c2a` JSON 文件，内含 SVG 片段与锚点 / landmark 元数据。`@cat2avatar/c2a` 负责解析与校验；`@cat2avatar/core` 根据脸型 landmark 将成对部件（眼、耳、眉）变换到脸上；`@cat2avatar/api` 提供部件清单与合成 HTTP 服务；`@cat2avatar/studio` 为 MVP 矢量编辑与发布模拟工具。

## 目录结构

```
cat2avatar/
├── packages/
│   ├── c2a/          # .c2a 类型、parse、validate
│   ├── core/         # 合成、landmark 变换、配色
│   ├── api/          # Express 部件 API
│   ├── react/        # <Avatar /> 组件
│   ├── studio/       # 部位矢量编辑 MVP
│   └── customizer/   # 用户选型与预览
├── docs/
│   └── c2a-examples/ # 格式示例
├── openspec/         # 变更提案与规格
└── README.md
```

## 快速开始

```bash
pnpm install
pnpm test
pnpm dev:api      # 启动部件 API（默认端口见 packages/api）
pnpm dev:studio      # Studio 部位编辑（默认 5173）
pnpm dev:customizer  # 用户捏脸选型（默认 5174）
```

首次使用 Studio 前建议构建依赖包：

```bash
pnpm --filter @cat2avatar/c2a build
```

默认示例部位参考 [Avataaars Generator](https://getavataaars.com) 扁平插画风格，说明见 [docs/reference/avataaars-style.md](docs/reference/avataaars-style.md)。

## .c2a 格式简述

`.c2a` 为 **C2A v1** JSON 文档，主要字段：

| 字段 | 说明 |
|------|------|
| `version` | 固定为 `1` |
| `meta` | `id`、`slot`、`category`、`zIndex` 等 |
| `svg` | 无外层 `<svg>` 的片段，坐标系为 **0–1 归一化** |
| `landmarks` | 仅 `headShape`：眼、耳、眉、鼻、口等对齐点 |
| `anchors` | `eyes` / `ears` / `brows`：左右件中心 `left` / `right` |
| `anchor` | 单件 slot（鼻、嘴、头发等）单点锚点 |

发布前须通过 `validate(c2a)`。更多示例见 [docs/c2a-examples/README.md](docs/c2a-examples/README.md)。

## packages 说明

| 包名 | 职责 |
|------|------|
| `@cat2avatar/c2a` | 类型定义、`parseC2A` / `serializeC2A`、`validate` |
| `@cat2avatar/core` | 多部件合成、landmark 对齐、颜色槽 |
| `@cat2avatar/api` | 扫描 `.c2a` 生成 manifest、REST 合成接口 |
| `@cat2avatar/studio` | 侧栏 slot 切换、画布预览、拖拽锚点/landmark、导出校验 |

## 许可证

见仓库根目录 LICENSE（如有）。