# pixel2motion

**Repository Path**: K_a1/pixel2motion

## Basic Information

- **Project Name**: pixel2motion
- **Description**: pixel2motion的Motion only网页操作版
配合UI组件库使用
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-20
- **Last Updated**: 2026-08-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Pixel2Motion Motion Studio Web

Motion Studio 是 Pixel2Motion Motion-Only 的本地 Web 工作台。内置规则式特色编排，
可选接入 OpenAI 兼容协议的 AI 模型生成 Motion；所有产物统一过 Motion 契约校验。

## 运行

要求 Node.js 20.19 或更高版本。

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

访问 `http://127.0.0.1:4178`。

生产模式：

```bash
npm run build
npm start
```

可通过 `P2M_HOST` 和 `P2M_PORT` 环境变量调整监听地址。

## 架构

```text
Browser UI
  → POST /api/svg/analyze
  → POST /api/motion/generate（可选 options.style）
  → POST /api/motion/ai（可选，OpenAI 兼容协议）
  → motion_engine/（规则 / AI → contract.mjs 校验）
  → DLC MotionDefinition[]
```

- `motion_engine/svg.mjs`：SVG XML 解析、静态化、结构分析、目标清单和 SHA-256 hash。
- `motion_engine/generate.mjs`：规则式、无事件绑定的 CSS Motion 候选；`options.style` 支持集合特色编排。
- `motion_engine/set_styles.mjs`：flexpop / freehand / plump / colos 四套集合特色编排与 auto 推断。
- `motion_engine/contract.mjs`：Motion 契约校验器（镜像 dlc-icon `normalizeIconMotion`）。
- `web/backend/ai.mjs`：OpenAI 兼容协议的 AI 生成路径（可选）。
- `schemas/dlc-motion.schema.json`：稳定的 DLC MotionDefinition JSON Schema。
- `docs/MOTION_CONTRACT.md`：Motion 创作契约（单一事实来源）。
- `web/backend/server.mjs`：开发/生产共用 API 和静态服务入口。
- `web/frontend/`：上传、粘贴、预览、速度/次数、事件映射和导出。

原来的 `scripts/` 保持独立，仍可用于 Motion-Only 检查、gallery 和确定性 QA。

## API

### `POST /api/svg/analyze`

```json
{
  "svg": "<svg viewBox=\"0 0 24 24\">...</svg>"
}
```

响应包含：

- `sanitizedSvg`：移除主动内容后的静态 SVG；不改 path、viewBox、fill、stroke。
- `svgHash`：安全静态 SVG 的 SHA-256。
- `analysis`：尺寸、path/group 数量、ID、可动画目标和警告。

### `POST /api/motion/generate`

```json
{
  "svg": "<svg viewBox=\"0 0 24 24\">...</svg>",
  "options": { "count": 3, "style": "auto" }
}
```

`count` 支持 1～5（仅经典预设生效）。`options.style` 支持：

| style | 说明 |
| --- | --- |
| `auto` | 按 SVG 特征自动推断（渐变→plump、≥3 色槽→colos、描边主导→freehand、其余→flexpop）。 |
| `flexpop` | 整体 squash-and-stretch 弹跳 + 部件错峰弹入。 |
| `freehand` | 手绘感小幅旋转抖动 + 部件级联。 |
| `plump` | 软果冻挤压回弹 + `filter` 微光感。 |
| `colos` | 多部件级联入场 + 轻微 `hue-rotate` 点缀。 |
| `legacy` / 不传 | 经典五预设（默认行为不变）。 |

集合特色路径输出单个针对性 Motion，选择器使用 dlc-icon 原生 gate（见
`docs/MOTION_CONTRACT.md`），可直接烘焙进组件库。响应额外包含解析后的 `style`。

### `GET /api/ai/config`

返回 AI 是否已配置（环境变量层）与默认模型提示，不泄露 API key。

### `POST /api/motion/ai`

```json
{
  "svg": "<svg viewBox=\"0 0 24 24\">...</svg>",
  "options": { "style": "colos" },
  "ai": { "baseUrl": "...", "apiKey": "...", "model": "..." }
}
```

走 OpenAI 兼容 Chat Completions 协议。配置优先级：请求体 `ai`（前端面板，
仅存浏览器 localStorage）> 环境变量 `P2M_AI_BASE_URL` / `P2M_AI_API_KEY` /
`P2M_AI_MODEL`。示例：

- DeepSeek：`https://api.deepseek.com/v1`
- 阿里百炼：`https://dashscope.aliyuncs.com/compatible-mode/v1`
- Anthropic 原生协议不在内置支持之列，请通过网关转成 OpenAI 兼容协议后接入。

AI 原文解析后先过 `contract.mjs` 校验；校验失败会返回明确错误与模型原文，便于重试。

## MotionDefinition

```json
{
  "id": "expressive-nod",
  "name": "Expressive Nod",
  "kind": "css",
  "source": "pixel2motion",
  "activation": "expressive-nod",
  "css": "...",
  "duration": 820,
  "iterations": 1,
  "targets": [
    { "selector": "#face", "name": "face", "role": "primary" }
  ],
  "suggestedEvents": ["hover", "click"],
  "svgHash": "..."
}
```

`kind: "css"` 是现有 `dlc-icon` 的必填字段。`suggestedEvents` 仅提供建议，Motion CSS 不包含 `:hover`、点击监听或自动挂载逻辑。

Web 候选区的“预览速度 / 预览次数”会通过 `--p2m-duration` 与
`--p2m-iterations` 真实控制 iframe 中的 CSS 播放，但不会修改或覆盖导出的
`duration / iterations / css`。最终接入 `dlc-icon` 时，应在对应事件上配置：

```js
clickAnm: { anm: defineIconMotion(motionJson), speed: 1.5, count: 2 }
```

`targets`、`suggestedEvents`、`svgHash` 属于生成、推荐和结构校验元数据；可以随整份
Motion JSON 一起传给 `defineIconMotion()`，但不参与动画播放。单 Motion JSON 是
`defineIconMotion()` 的输入；`04 / ROUTE & EXPORT` 的 bundle manifest 则是多 Motion
交付清单，不能把整个 manifest 当成一个 MotionDefinition。

### ID 唯一性

生成 ID 使用 `<动作特征>-<SVG SHA-256 结构指纹前 32 位>`（128 bit），例如
`expressive-nod-a80e99d74b8a6ef25da7a842546a61e3`。对应的 activation gate 和 keyframes 使用同一短码：

- 同一 SVG 结构重复生成时 ID 稳定，便于缓存和版本比较；
- 不同 SVG 结构不会误用同一个 Motion ID；
- 同一批候选会执行重复 ID 检测测试；
- 完整 64 位 `svgHash` 仍保存在 MotionDefinition 中，用于严格校验。

这里不使用毫秒时间戳，因为时间戳会让相同输入每次生成不同 ID，破坏缓存和可复现构建。

### 04 / ROUTE & EXPORT 的事件选择

左侧 create / hover / click / focus 下拉框只决定交付 ZIP 中对应事件 JSON 使用哪个候选，
例如选择 click 后生成 `motions/click.json`，并把 motion id 写入 manifest。它不会监听 DOM
事件，也不会把事件写进 Motion CSS。实际使用时对应：

```js
createAnm // Vue 模板：create-anm
hoverAnm  // Vue 模板：hover-anm
clickAnm  // Vue 模板：click-anm
focusAnm  // Vue 模板：focus-anm
```

### LINE MD 与外部 Motion

外部 Motion 可以直接绑定在 LINE MD 静态图标上：

```vue
<dlc-icon type="linemd" name="bell" :create-anm="false"
  :click-anm="{ anm: motion, speed: 1.5, count: 2 }" />
```

前提是生成 Motion 时使用的 SVG 与最终 LINE MD 图标具有相同结构，确保 CSS selector 能命中。
Pixel2Motion 不会自动删除 SVG 背景；LINE MD 默认透明，自定义 SVG 若带全画布背景节点，应在
确认它是背景后于生成前删除。

## 导出

- 单 Motion CSS：`<id>.css`
- 单 Motion JSON：`<id>.motion.json`
- DLC Icon Bundle：`icon-motion.zip`

Bundle 结构：

```text
icon-motion/
├─ icon.svg
├─ manifest.json
└─ motions/
   ├─ <motion-id>.css
   ├─ create.json
   ├─ hover.json
   ├─ click.json
   └─ focus.json
```

事件 JSON 只在对应事件已配置时生成。事件映射记录在 bundle 层，MotionDefinition 本身仍保持事件中立。

## Motion 契约与独立校验

任何来源的 MotionDefinition（规则 / AI / 手写 / 其他 Agent）都必须满足
[`docs/MOTION_CONTRACT.md`](docs/MOTION_CONTRACT.md) 并通过同一校验器：

```bash
npm run validate:motion -- <motion.json>
```

契约要点：选择器必须被 `[data-p2m-motion~="{activation}"]` 或
`[data-dlc-icon-motion~="MOTION"]` gate；禁改 `width/height/color/fill/stroke`
（`stroke-dasharray/dashoffset` 除外）；禁外部资源；结束帧回到静态。

## 安全边界

输入最大 2 MB。静态化会拒绝 `DOCTYPE/ENTITY`，并移除：

- `script`、`style`、SVG 原生 animation 标签
- `foreignObject`、`iframe`、`object`、`embed`、音视频和 canvas
- `on*` 内联事件
- 外部 `href/src` 和外部 CSS `url(...)`

候选 Motion 不设置 `width`、`height`、`viewBox`、`color`、`fill` 或 `stroke`，因此组件仍可控制尺寸和颜色。

## 验证

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

测试包含真实 Edge/Chromium 浏览器闭环：自动分析、生成、iframe 预览、速度/次数、hash 检查、ZIP 导出和 390px 移动端无横向溢出。