Turn one illustration into an animated 2D mesh avatar with a coding agent and a local editor
Close an open mouth before building in npm run create
shinshin86a374f53b713e
diff --git a/README.ja.md b/README.ja.mdindex 0ec43d3..4bc0302 100644--- a/README.ja.md+++ b/README.ja.md@@ -61,7 +61,7 @@ npm run devnpm run create -- /path/to/your-image.png```-Codex は OpenAI の画像生成で、閉じ目・口の形・表情の描き分けも作ります。画像とマスクが OpenAI に送られるため、+Codex は OpenAI の画像生成で、閉じ目・口の形・表情の描き分けも作ります。イラストの口が開いていれば、先に口を閉じた絵にします。画像とマスクが OpenAI に送られるため、コマンドは最初に確認します。`--yes` を付けると事前に同意し、`--no-variants` を付けるとすべて手元のマシンの中で行います。通常は数十分かかります。Codex のメモは `projects/<name>/HANDOVER.md` に書き出されます。Codex は `--approve-for-me` 付きで動くため、ポーズ確認用の Chromium など sandbox の外でツールを動かす許可は、diff --git a/README.md b/README.mdindex 7c67339..970649c 100644--- a/README.md+++ b/README.md@@ -82,10 +82,10 @@ on the result:npm run create -- /path/to/your-image.png```-Codex also draws closed eyes, mouth shapes and expressions with OpenAI image generation. This-sends the image and masks to OpenAI, so the command asks first; add `--yes` to agree in-advance, or `--no-variants` to keep everything on your machine. It usually takes tens of-minutes. Codex writes its notes to `projects/<name>/HANDOVER.md`. It runs with+Codex also draws closed eyes, mouth shapes and expressions with OpenAI image generation, and+first closes an open mouth in the illustration so the avatar rests with it closed. This sends+the image and masks to OpenAI, so the command asks first; add `--yes` to agree in advance, or+`--no-variants` to keep everything on your machine. It usually takes tens of minutes. Codex writes its notes to `projects/<name>/HANDOVER.md`. It runs with`--approve-for-me`, so its requests to run tools outside its sandbox, such as Chromium for thepose review, are reviewed automatically instead of by you. `npm run create -- --help` lists theoptions.diff --git a/README.zh.md b/README.zh.mdindex 17fac06..357c5e0 100644--- a/README.zh.md+++ b/README.zh.md@@ -61,7 +61,7 @@ npm run devnpm run create -- /path/to/your-image.png```-Codex 还会用 OpenAI 图像生成绘制闭眼、嘴型和表情。这会把图像和遮罩发送到 OpenAI,因此命令会先询问;+Codex 还会用 OpenAI 图像生成绘制闭眼、嘴型和表情;如果插画中的嘴是张开的,会先把它画成闭合的。这会把图像和遮罩发送到 OpenAI,因此命令会先询问;加上 `--yes` 可预先同意,加上 `--no-variants` 则全部在本机完成。通常需要几十分钟。Codex 的说明写在`projects/<name>/HANDOVER.md`。Codex 以 `--approve-for-me` 运行,因此在沙箱外运行工具(例如姿势检查用的Chromium)的请求由自动审核代替你决定。用 `npm run create -- --help` 查看全部选项。diff --git a/tests/create-avatar.test.ts b/tests/create-avatar.test.tsindex 0b9d9f1..7775c84 100644--- a/tests/create-avatar.test.ts+++ b/tests/create-avatar.test.ts@@ -1,12 +1,12 @@import { join } from 'node:path';import { fileURLToPath } from 'node:url';import { describe, expect, test } from 'vitest';-import { agentPrompt, create, parseArgs, projectName } from '../tools/create.mjs';+import { agentPrompt, create, parseArgs, projectName, SPRITES } from '../tools/create.mjs';const root = fileURLToPath(new URL('..', import.meta.url));const ready = async () => ['node', 'packages', 'uv', 'python', 'chromium'].map(id => ({ id, status: 'ok', message: id }));-function harness({ files = [] as string[], statuses = {} as Record<string, number | null>, environment = ready, answer = true as boolean | null, interactive = true } = {}) {+function harness({ files = [] as string[], statuses = {} as Record<string, number | null>, environment = ready, answer = true as boolean | null, interactive = true, sprites = SPRITES } = {}) {const calls: { command: string; args: string[]; options?: { stdio?: unknown } }[] = [], logs: string[] = [], errors: string[] = [], questions: string[] = [];const existing = new Set(files);const run = async (command: string, args: string[], options?: { stdio?: unknown }) => {@@ -20,7 +20,8 @@ function harness({ files = [] as string[], statuses = {} as Record<string, numbe};const read = async (command: string) => command === 'codex' ? 'codex-cli 0.164.0' : '/cache/uv';const ask = async (question: string) => { questions.push(question); return answer; };- const deps = { run, read, ask, interactive, exists: (path: string) => existing.has(path), environment, log: (m: string) => logs.push(m), error: (m: string) => errors.push(m), cwd: '/work' };+ const readJson = () => ({ layers: Object.fromEntries(sprites.map(sprite => [sprite, [0, 0, 1, 1]])) });+ const deps = { run, read, readJson, ask, interactive, exists: (path: string) => existing.has(path), environment, log: (m: string) => logs.push(m), error: (m: string) => errors.push(m), cwd: '/work' };return { calls, logs, errors, questions, deps };}@@ -42,6 +43,8 @@ describe('npm run create', () => {expect(plain).toContain('docs/agent-guide.md');expect(plain).toContain('projects/mio/HANDOVER.md');expect(plain).toContain('Step 6: skip it');+ expect(plain).toContain('the avatar rests with it open');+ expect(plain).not.toContain('close it first');expect(plain).toContain('do not stage or commit');expect(plain).toContain('run the same command again with escalated permissions');expect(plain).toContain('Do not post-process built/');@@ -49,6 +52,11 @@ describe('npm run create', () => {const variants = agentPrompt('mio', { variants: true });expect(variants).toContain('the person agreed to send source.png and the masks');expect(variants).toContain('eyes_sad, eyes_surprise, mouth_angry and mouth_sad');+ expect(variants).toContain('Do not finish Step 6 while a variant is missing');+ // an open mouth is closed before the rig is drawn, keeping every other pixel+ expect(variants).toContain('Open mouth (before Step 2)');+ expect(variants).toContain('Every pixel outside the mask, alpha included, must stay identical');+ expect(variants).toContain('projects/mio/work/original-source.png');});test('asks about OpenAI image generation first, then creates the project, runs Codex and opens the editor', async () => {@@ -83,6 +91,19 @@ describe('npm run create', () => {expect(calls).toEqual([]);});+ test('names the drawn variants that are still missing, and still opens the editor', async () => {+ const complete = harness({ files: ['/work/mio.png'] });+ expect(await create(['mio.png', '--lang', 'en'], complete.deps)).toBe(0);+ expect(complete.errors).toEqual([]);+ const partial = harness({ files: ['/work/mio.png'], sprites: SPRITES.filter(sprite => !sprite.startsWith('mouth_o') && !sprite.startsWith('eyes_half')) });+ expect(await create(['mio.png', '--lang', 'en'], partial.deps)).toBe(0);+ expect(partial.errors[0]).toContain('eyes_half_0, eyes_half_1, mouth_o');+ expect(partial.calls.at(-1)!.command).toBe(process.execPath);+ const skipped = harness({ files: ['/work/mio.png'], sprites: [] });+ expect(await create(['mio.png', '--no-variants', '--lang', 'en'], skipped.deps)).toBe(0);+ expect(skipped.errors).toEqual([]);+ });+test('without a terminal it needs --yes or --no-variants before doing anything', async () => {const { calls, errors, deps } = harness({ files: ['/work/mio.png'], interactive: false });expect(await create(['mio.png', '--lang', 'en'], deps)).toBe(1);diff --git a/tools/create.mjs b/tools/create.mjsindex d563aa1..5cc974e 100644--- a/tools/create.mjs+++ b/tools/create.mjs@@ -2,17 +2,23 @@// One command from an illustration to an open editor: creates projects/<name>, has Codex// follow docs/agent-guide.md without questions, then starts the editor on that project.import { spawn } from 'node:child_process';-import { existsSync, realpathSync } from 'node:fs';+import { existsSync, readFileSync, realpathSync } from 'node:fs';import { basename, extname, join, resolve } from 'node:path';import { fileURLToPath, pathToFileURL } from 'node:url';import { checkEnvironment, formatReport, language } from './doctor.mjs';const root = fileURLToPath(new URL('..', import.meta.url));+// Sprite layers that build-sprites cuts from every drawn variant.+export const SPRITES = [+ ...['closed', 'half', 'smile', 'sad', 'surprise'].flatMap(eye => [`eyes_${eye}_0`, `eyes_${eye}_1`]),+ 'mouth_a', 'mouth_a_half', 'mouth_i', 'mouth_o', 'mouth_angry', 'mouth_sad',+];const text = {en: {usage: 'Usage: npm run create -- <image.png> [--name <name>] [--yes | --no-variants] [--no-open]\n\n'- + 'Codex also draws closed eyes, mouth shapes and expressions with OpenAI image generation.\n'+ + 'Codex also draws closed eyes, mouth shapes and expressions with OpenAI image generation,\n'+ + 'and closes an open mouth in the illustration first so the avatar rests with it closed.\n'+ 'The command asks first, because this sends the image and masks to OpenAI.\n\n'+ ' --name project name under projects/ (default: from the file name)\n'+ ' --yes, -y agree to the image generation without asking\n'@@ -22,7 +28,7 @@ const text = {noImage: path => `Image not found: ${path}`,badName: name => `Invalid project name: ${name}. Use letters, digits, hyphens or underscores.`,exists: name => `projects/${name} already exists. Choose another --name.`,- consent: 'Codex will draw closed eyes, mouth shapes and expressions with OpenAI image generation.\nThis sends the image and masks to OpenAI. Continue? [Y/n] ',+ consent: 'Codex will draw closed eyes, mouth shapes and expressions with OpenAI image generation,\nand close the mouth first if it is open in the illustration.\nThis sends the image and masks to OpenAI. Continue? [Y/n] ',noConsent: 'Not sending the image. The avatar is made without drawn variants.',needConsent: 'Drawn variants send the image to OpenAI image generation. Without a terminal to ask, add --yes to agree or --no-variants to skip them.',environment: 'Fix the tools marked above, then run this command again.',@@ -31,12 +37,14 @@ const text = {agent: 'Codex is building the avatar. This usually takes tens of minutes.',agentFailed: status => `Codex stopped with exit code ${status}. Its notes, if any, are in the project folder.`,incomplete: name => `Codex finished but projects/${name} has no built avatar. Read projects/${name}/HANDOVER.md for the reason.`,+ missingVariants: names => `These drawn variants are missing, so the avatar falls back for them: ${names.join(', ')}. See HANDOVER.md.`,ready: name => `The avatar is ready: projects/${name}. Hand-over notes: projects/${name}/HANDOVER.md`,opening: 'Starting the editor. Press Ctrl+C to stop it.',},ja: {usage: '使い方: npm run create -- <image.png> [--name <name>] [--yes | --no-variants] [--no-open]\n\n'+ 'Codex は OpenAI の画像生成で、閉じ目・口の形・表情の描き分けも作ります。\n'+ + 'イラストの口が開いていれば、先に口を閉じた絵にしてから作ります。\n'+ '画像とマスクが OpenAI に送られるため、始める前に確認します。\n\n'+ ' --name projects/ に作るプロジェクト名(既定: ファイル名から作成)\n'+ ' --yes, -y 確認せずに画像生成に同意する\n'@@ -46,7 +54,7 @@ const text = {noImage: path => `画像が見つかりません: ${path}`,badName: name => `プロジェクト名が使えません: ${name}。英数字、ハイフン、アンダースコアを使ってください。`,exists: name => `projects/${name} は既にあります。別の --name を指定してください。`,- consent: 'Codex が OpenAI の画像生成で、閉じ目・口の形・表情の描き分けを作ります。\n画像とマスクが OpenAI に送られます。続けますか? [Y/n] ',+ consent: 'Codex が OpenAI の画像生成で、閉じ目・口の形・表情の描き分けを作ります。\nイラストの口が開いていれば、先に口を閉じた絵にします。\n画像とマスクが OpenAI に送られます。続けますか? [Y/n] ',noConsent: '画像は送りません。描き分けなしでアバターを作ります。',needConsent: '描き分けを作ると画像が OpenAI の画像生成に送られます。確認できる端末がないため、同意するなら --yes、作らないなら --no-variants を付けてください。',environment: '上の警告やエラーのツールを用意してから、もう一度実行してください。',@@ -55,6 +63,7 @@ const text = {agent: 'Codex がアバターを作っています。通常は数十分かかります。',agentFailed: status => `Codex が終了コード ${status} で止まりました。メモがあればプロジェクトフォルダにあります。`,incomplete: name => `Codex は終了しましたが、projects/${name} にアバターができていません。理由は projects/${name}/HANDOVER.md を確認してください。`,+ missingVariants: names => `次の描き分けがなく、代わりの表示になります: ${names.join(', ')}。HANDOVER.md を確認してください。`,ready: name => `アバターができました: projects/${name}。引き継ぎメモ: projects/${name}/HANDOVER.md`,opening: 'エディタを起動します。止めるときは Ctrl+C を押してください。',},@@ -86,6 +95,17 @@ export function projectName(image, taken = name => existsSync(join(root, 'projecreturn name;}+// The rig takes the mouth in the illustration as the closed rest mouth; an open one stays open+// while silent and in every expression. With the image generator allowed, close it first.+const closeMouth = project => [+ `- Open mouth (before Step 2): look at ${project}/source.png. If the mouth is open (teeth, tongue or the inside of the mouth show), close it first:`,+ ` 1. Copy source.png to ${project}/work/original-source.png.`,+ ' 2. With your image generator and source.png as the input, redraw only the mouth as a natural closed mouth in the same art style and expression (one thin lip line, no teeth, tongue or gap). Keep everything else the same.',+ ' 3. The generator may shift, rescale or repaint the picture, so do not use its output directly: align it to source.png at the same size, then composite only the mouth region onto source.png with a soft-edged mask a little larger than the open mouth. Every pixel outside the mask, alpha included, must stay identical; check this with a script.',+ ` 4. Save a 3x zoomed side-by-side crop (original | closed) to ${project}/work/closed-mouth-compare.png and look at it. Generate again, up to 4 tries, if the mouth looks unnatural or off-style, traces of the open mouth remain, or the skin shows a patch at the mask edge.`,+ ` 5. Overwrite ${project}/source.png with the result (same size) and record what you did in the hand-over notes. If the mouth is already closed, leave source.png unchanged.`,+].join('\n');+/** The request Codex runs non-interactively: every question in the guide is answered here. */export function agentPrompt(name, { variants }) {const project = `projects/${name}`;@@ -97,8 +117,9 @@ export function agentPrompt(name, { variants }) {'- Model: state which model you are running as in the hand-over notes and continue.',`- Vision check: run it with ${project}/work/vision-check as the folder. If the score fails, stop and explain it in the hand-over notes.`,'- Image warnings (pose, covered face, missing transparency): record them in the hand-over notes and continue.',+ variants ? closeMouth(project) : '- Open mouth: if the mouth in source.png is open, record in the hand-over notes that the avatar rests with it open, because closing it needs the image generator, which the person declined.',variants- ? '- Step 6: the person agreed to send source.png and the masks to your built-in image generator. Generate every variant: closed, half and smiling eyes; mouths あ, half あ, い, お; and the expression variants eyes_sad, eyes_surprise, mouth_angry and mouth_sad. Then run build-sprites and review the poses again. Generate a variant again when build-sprites rejects it or its pose frames look wrong.'+ ? '- Step 6: the person agreed to send source.png and the masks to your built-in image generator. Generate every variant: closed, half and smiling eyes; mouths あ, half あ, い, お; and the expression variants eyes_sad, eyes_surprise, mouth_angry and mouth_sad. Then run build-sprites and review the poses again. Generate a variant again when build-sprites rejects it or its pose frames look wrong, up to 4 tries each. Do not finish Step 6 while a variant is missing; report any that still fail after 4 tries.': '- Step 6: skip it. The person did not agree to send the image to an image generator.',`- Step 7: write the hand-over notes to ${project}/HANDOVER.md instead of telling the person. The editor is opened for them, so leave out how to open it.`,'',@@ -134,7 +155,7 @@ const capture = (command, args) => new Promise(done => {export async function create(argv, deps = {}) {const { run = execute, read = capture, exists = existsSync, environment = checkEnvironment, log = console.log, error = console.error,- ask = confirm, interactive = Boolean(process.stdin.isTTY), cwd = process.env.INIT_CWD || process.cwd() } = deps;+ readJson = path => JSON.parse(readFileSync(path, 'utf8')), ask = confirm, interactive = Boolean(process.stdin.isTTY), cwd = process.env.INIT_CWD || process.cwd() } = deps;const lang = language(argv), t = text[lang], options = parseArgs(argv);if (options.help) { log(t.usage); return 0; }if (!options.image) { error(`${t.missingImage}\n\n${t.usage}`); return 1; }@@ -170,6 +191,12 @@ export async function create(argv, deps = {}) {if (agent !== 0) { error(t.agentFailed(agent)); return agent ?? 1; }const project = join(root, 'projects', name);if (!exists(join(project, 'rig.json')) || !exists(join(project, 'built', 'base.png'))) { error(t.incomplete(name)); return 1; }+ if (options.variants) {+ let layers = {};+ try { layers = readJson(join(project, 'built', 'sprites', 'sprites.json')).layers ?? {}; } catch { /* no sprites were built */ }+ const missing = SPRITES.filter(sprite => !(sprite in layers));+ if (missing.length) error(t.missingVariants(missing));+ }log(t.ready(name));if (!options.open) return 0;