@kevlns/art-workshop 0.6.4 → 0.6.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/art-workshop.mjs CHANGED
@@ -4,11 +4,18 @@ import {readdirSync,existsSync} from 'node:fs';
4
4
  import {join,resolve} from 'node:path';
5
5
  import {readJson,writeJson} from './lib/shared.mjs';
6
6
  const args=process.argv.slice(2),pos=[],options={};
7
+ if(args[0]==='spine'){
8
+ try {
9
+ const {spineCli}=await import('./lib/spine.mjs');
10
+ console.log(JSON.stringify(await spineCli(args.slice(1)),null,2));
11
+ } catch(error){console.log(JSON.stringify({ok:false,error:error.message}));process.exitCode=1;}
12
+ process.exit(process.exitCode||0);
13
+ }
7
14
  const channel=['image','video'].includes(args[0])?args.shift():null;
8
15
  if(args.length===1&&['--version','-V'].includes(args[0])){console.log(readJson(new URL('./package.json',import.meta.url)).version);process.exit(0);}
9
16
  const imageHelp='art-workshop image: config path/show/init/validate | doctor [--backend ID] [--start] | workflow list | environment guide/list/prepare/inspect/verify/register/unregister | refs guide | agent index/docs/export | conversation start/status/cancel/resume | list | style export/import/sources/create/list/read/update/confirm/derive/discard/sample-job/sample-select/sample-remove/recover/show | generate show/plan/run | edit show/plan/run | task list/status/wait/cancel/recover/resume | shutdown | check RUN | project init/upgrade | job template/from-candidate/create/list/read/update/derive/discard/restore/analyze | reference import/list/update/remove | candidate list/favorites/favorite/finalize/delete/finalizations | compare PLAN PLAN\nrun --background 返回任务 ID;--backend 选择后端。shutdown 停止当前工作区关联任务,核验共享队列和进程身份后关闭本地服务。';
10
17
  const videoHelp='art-workshop video: describe | snapshot | settings get/save/presets h3 | runtime status/start/stop | task list/read/create/rename/archive | operation create/update/rename/derive/validate/run/resume/cancel/accept/bind | script read/update/plan/apply | film compose/refine/preview/adopt/undo | material list/import/import-file/upload/hide | image | media status | execution status\n--workspace <工程根目录> --project <项目身份,默认 project> --input <工程内 JSON 对象文件> --operation <稳定CLI操作身份>\n所有写入必须传 --operation,重复同身份只核对原回执;execution status --operation 查询意图/回执。先 describe 读取业务输入契约;写入保留 revision/expectedRevision,生成必须传稳定 requestId。unknown 只查询原运行,不换 ID 重投。读取不会启动服务,runtime start/operation run/film 操作必须显式调用。';
11
- const help='art-workshop: image(图片)与 video(视频)两个独立通道。图片旧根命令继续兼容。\n'+imageHelp+'\n'+videoHelp+'\n也可用 v-cli art 调用;先 v-cli agent docs art,再 v-cli agent describe art --json 查看完整参数。';
18
+ const help='art-workshop: image(图片)、video(视频)、spine(骨骼动画)制作通道;spine describe 查看制作契约。图片旧根命令继续兼容。\n'+imageHelp+'\n'+videoHelp+'\n也可用 v-cli art 调用;先 v-cli agent docs art,再 v-cli agent describe art --json 查看完整参数。';
12
19
  if(!args.length||args.length===1&&['--help','-h','help'].includes(args[0])){console.log(channel==='video'?videoHelp:channel==='image'?imageHelp:help);process.exit(0);}
13
20
  if(channel==='video'){
14
21
  let api;
package/docs/commands.md CHANGED
@@ -3270,6 +3270,65 @@ v-cli art image style sample-remove --project ID --id STYLE --revision N --sampl
3270
3270
 
3271
3271
  - 保存或建任务不发起生成;版本冲突重新读取;样张仅作绘制语言参考,不能保证隔离无关特征
3272
3272
 
3273
+ ### spine describe
3274
+
3275
+ 读取 Spine 制作契约
3276
+
3277
+ ```sh
3278
+ v-cli art spine describe
3279
+ ```
3280
+
3281
+ 结构化能力:`art.spine-describe`。
3282
+
3283
+ - `--workspace <dir>`:目标工程,默认当前目录
3284
+
3285
+ - 只读工具契约。
3286
+
3287
+ ### spine parts
3288
+
3289
+ 按母版坐标拆件、蒙版补绘与拼合检查
3290
+
3291
+ ```sh
3292
+ v-cli art spine parts --input <file>
3293
+ ```
3294
+
3295
+ 结构化能力:`art.spine-parts`。
3296
+
3297
+ - `--workspace <dir>`:目标工程,默认当前目录
3298
+ - `--input <file>`:工程内 JSON 制作配方,参见 spine describe
3299
+
3300
+ - 仅使用目标工程内输入;制作结果原子写入新目录。
3301
+
3302
+ ### spine build
3303
+
3304
+ 编译并校验骨架绑定、蒙皮、动作和图集
3305
+
3306
+ ```sh
3307
+ v-cli art spine build --input <file>
3308
+ ```
3309
+
3310
+ 结构化能力:`art.spine-build`。
3311
+
3312
+ - `--workspace <dir>`:目标工程,默认当前目录
3313
+ - `--input <file>`:工程内 JSON 制作配方,参见 spine describe
3314
+
3315
+ - 仅使用目标工程内输入;制作结果原子写入新目录。
3316
+
3317
+ ### spine capture
3318
+
3319
+ 使用 WebGL 取帧、生成对照图和可选 GIF
3320
+
3321
+ ```sh
3322
+ v-cli art spine capture --input <file>
3323
+ ```
3324
+
3325
+ 结构化能力:`art.spine-capture`。
3326
+
3327
+ - `--workspace <dir>`:目标工程,默认当前目录
3328
+ - `--input <file>`:工程内 JSON 制作配方,参见 spine describe
3329
+
3330
+ - 仅使用目标工程内输入;制作结果原子写入新目录。
3331
+
3273
3332
  ## 结果验证
3274
3333
 
3275
3334
  按任务身份、停止证据和实际产物核验;只读检查不证明真实出图。
@@ -0,0 +1,31 @@
1
+ // Spine stores weighted vertices as counts followed by (bone index, local x, local y, weight).
2
+ export function applyBinding(rig,{bones=[],meshes=[]}) {
3
+ for(const bone of bones) {
4
+ if(!bone?.name) throw Error('缺少骨名');
5
+ const prior=rig.bones.find(existing=>existing.name===bone.name);
6
+ if(prior) Object.assign(prior,bone);
7
+ else rig.bones.push(bone);
8
+ }
9
+ const indices=new Map(rig.bones.map((bone,i)=>[bone.name,i]));
10
+ if(indices.size!==rig.bones.length) throw Error('骨名重复');
11
+ for(const mesh of meshes) {
12
+ const skin=rig.skins.find(s=>s.name===(mesh.skin??'default'));
13
+ const slot=skin?.attachments?.[mesh.slot], name=mesh.attachment??mesh.slot;
14
+ if(!slot || !Object.hasOwn(slot,name)) throw Error('找不到待绑定的附件:'+name);
15
+ const {uvs,triangles,points}=mesh;
16
+ if(!Array.isArray(points)||points.length<3||uvs?.length!==points.length*2||!uvs.every(Number.isFinite)||
17
+ !Array.isArray(triangles)||!triangles.length||triangles.length%3||triangles.some(i=>!Number.isInteger(i)||i<0||i>=points.length))throw Error('网格 UV、顶点或三角索引无效');
18
+ const vertices=[];
19
+ for(const weights of points) {
20
+ if(!Array.isArray(weights)||!weights.length) throw Error('每个顶点需要骨骼影响');
21
+ vertices.push(weights.length);
22
+ let sum=0;
23
+ for(const [bone,x,y,weight] of weights) {
24
+ if(!indices.has(bone)||![x,y,weight].every(Number.isFinite)||weight<=0) throw Error('顶点绑定无效:'+bone);
25
+ sum+=weight;vertices.push(indices.get(bone),x,y,weight);
26
+ }
27
+ if(Math.abs(sum-1)>0.0001)throw Error('每个顶点的权重和应为 1');
28
+ }
29
+ slot[name]={type:'mesh',path:mesh.path??slot[name].path??name,uvs,triangles,vertices,hull:mesh.hull??points.length};
30
+ }
31
+ }
@@ -0,0 +1,95 @@
1
+ import {mkdir,readFile,writeFile,stat} from 'node:fs/promises';
2
+ import {dirname,join} from 'node:path';
3
+ import sharp from 'sharp';
4
+ import {SkeletonJson,AtlasAttachmentLoader,TextureAtlas,Skeleton,Physics} from '@esotericsoftware/spine-webgl';
5
+ import {projectPath} from '../video/path.mjs';
6
+ import {applyBinding} from './binding.mjs';
7
+ import {identifier,sheet} from './parts.mjs';
8
+
9
+ export function variantIndex(animations) {
10
+ const groups=Object.create(null);
11
+ for(const name of Object.keys(animations).sort()) {
12
+ const match=/^([a-z][a-z0-9]*(?:_[a-z][a-z0-9]*)*)_(\d{3})$/.exec(name);
13
+ if(!match || match[2]==='000') throw Error('动作须使用 <类别>_<三位正编号>:'+name);
14
+ (groups[match[1]]??=[]).push(name);
15
+ }
16
+ return groups;
17
+ }
18
+ function setup(parts) {
19
+ const bones=[{name:'root'}],slots=[],attachments=Object.create(null);
20
+ for(const {name,pivot:[px,py],rect} of parts.parts) {
21
+ bones.push({name,parent:'root',x:px,y:parts.height-py});
22
+ slots.push({name,bone:name,attachment:name});
23
+ attachments[name]={[name]:{x:rect.left+rect.width/2-px,y:py-rect.top-rect.height/2,width:rect.width,height:rect.height}};
24
+ }
25
+ return {skeleton:{spine:'4.2.0',x:0,y:0,width:parts.width,height:parts.height,images:'./images/'},bones,slots,skins:[{name:'default',attachments}],animations:{}};
26
+ }
27
+
28
+ async function makeAtlas(root,folder,parts,out,name) {
29
+ const blocks=[],pages=[];
30
+ let x=0,y=0,row=0,width=0,layers=[],regions=[];
31
+ async function flush() {
32
+ if(!regions.length)return;
33
+ const filename=name+'-'+(pages.length+1)+'.png',height=y+row;
34
+ const info=await sheet(width,height).composite(layers).png().toFile(join(out,filename));
35
+ pages.push({filename,width,height,bytes:info.size,rgbaBytes:width*height*4});
36
+ blocks.push([filename,'size:'+width+','+height,'filter:Linear,Linear','pma:false',...regions].join('\n'));
37
+ x=y=row=width=0;layers=[];regions=[];
38
+ }
39
+ const names=new Set();
40
+ for(const part of parts) {
41
+ const id=identifier(part.name);
42
+ if(names.has(id.toLowerCase())) throw Error('部件名重复:'+id);
43
+ names.add(id.toLowerCase());
44
+ const img=await projectPath(root,join(folder,part.image)),data=await readFile(img);
45
+ const {width:w,height:h,format}=await sharp(data).metadata();
46
+ if(format!=='png'||w!==part.rect.width||h!==part.rect.height||w+4>4096||h+4>4096) throw Error(id+' 的 PNG 尺寸无法打包');
47
+ if(x+w+4>4096) {y+=row;x=0;row=0;}
48
+ if(y+h+4>4096) await flush();
49
+ const padded=await sharp(data).extend({top:2,left:2,right:2,bottom:2,extendWith:'copy'}).png().toBuffer();
50
+ layers.push({input:padded,left:x,top:y});
51
+ regions.push(id,'bounds:'+[x+2,y+2,w,h].join(','));
52
+ x+=w+4;row=Math.max(row,h+4);width=Math.max(width,x);
53
+ await writeFile(join(out,'images',id+'.png'),data);
54
+ }
55
+ await flush();
56
+ const text=blocks.join('\n\n')+'\n';
57
+ await writeFile(join(out,name+'.atlas'),text);
58
+ return {text,pages};
59
+ }
60
+ export async function buildRig(root,recipe,out) {
61
+ const name=identifier(recipe.name),file=await projectPath(root,recipe.parts);
62
+ const parts=JSON.parse(await readFile(file,'utf8'));
63
+ if(!Array.isArray(parts.parts)||!parts.parts.length||parts.parts.length>256) throw Error('拆件清单无效');
64
+ const rig=recipe.rig ? JSON.parse(await readFile(await projectPath(root,recipe.rig),'utf8')) : setup(parts);
65
+ if(!rig.skeleton?.spine?.startsWith('4.2.')) throw Error('需要 Spine 4.2 JSON');
66
+ applyBinding(rig,recipe);
67
+ rig.skeleton.images='./images/';
68
+ Object.assign(rig.animations??={},recipe.animations??{});
69
+ const groups=variantIndex(rig.animations);
70
+ await mkdir(join(out,'images'));
71
+ const {text,pages}=await makeAtlas(root,dirname(file),parts.parts,out,name);
72
+ const atlas=new TextureAtlas(text),data=new SkeletonJson(new AtlasAttachmentLoader(atlas)).readSkeletonData(rig);
73
+ const skeleton=new Skeleton(data);
74
+ skeleton.updateWorldTransform(Physics.reset);
75
+ let vertices=0,influences=0;
76
+ for(const skin of data.skins) for(const {attachment} of skin.getAttachments()) {
77
+ if(!attachment.worldVerticesLength) continue;
78
+ vertices+=attachment.worldVerticesLength/2;
79
+ if(attachment.bones) {
80
+ for(let i=0;i<attachment.bones.length;) {
81
+ const count=attachment.bones[i++];
82
+ if(!Number.isInteger(count)||count<1||i+count>attachment.bones.length) throw Error('无效的顶点骨骼权重');
83
+ for(const index of attachment.bones.slice(i,i+count)) if(!data.bones[index]) throw Error('权重引用不存在的骨骼');
84
+ influences+=count;i+=count;
85
+ }
86
+ for(let v=2;v<attachment.vertices.length;v+=3) if(!Number.isFinite(attachment.vertices[v])||attachment.vertices[v]<0) throw Error('无效的顶点权重');
87
+ }
88
+ }
89
+ const source=name+'.json';
90
+ await writeFile(join(out,source),JSON.stringify(rig));await writeFile(join(out,'animations.json'),JSON.stringify(groups,null,2));
91
+ const runtimeBytes=pages.reduce((n,p)=>n+p.bytes,0)+(await stat(join(out,source))).size+Buffer.byteLength(text)+(await stat(join(out,'animations.json'))).size;
92
+ const report={source,pages,runtimeBytes,rgbaBytes:pages.reduce((n,p)=>n+p.rgbaBytes,0),bones:data.bones.length,slots:data.slots.length,vertices,influences,clips:data.animations.map(a=>({name:a.name,duration:a.duration}))};
93
+ await writeFile(join(out,'report.json'),JSON.stringify(report,null,2));
94
+ return report;
95
+ }
@@ -0,0 +1,83 @@
1
+ import {chromium} from 'playwright-core';
2
+ import {dirname,join} from 'node:path';
3
+ import {fileURLToPath} from 'node:url';
4
+ import {readFile,writeFile} from 'node:fs/promises';
5
+ import {TextureAtlas} from '@esotericsoftware/spine-webgl';
6
+ import sharp from 'sharp';
7
+ import {projectPath} from '../video/path.mjs';
8
+ import {sheet} from './parts.mjs';
9
+
10
+ async function openBrowser() {
11
+ const options={headless:true,args:['--enable-unsafe-swiftshader']};
12
+ if(process.env.SPINE_CHROMIUM_PATH) return chromium.launch({...options,executablePath:process.env.SPINE_CHROMIUM_PATH});
13
+ const channels=process.platform==='win32'?['msedge','chrome',undefined]:['chrome',undefined];
14
+ for(const channel of channels) {
15
+ try { return await chromium.launch({...options,channel}); } catch(error) { if(!/not found|doesn't exist|distribution/i.test(error.message)) throw error; }
16
+ }
17
+ throw Error('取帧需要 Chromium、Chrome 或 Edge,可用 SPINE_CHROMIUM_PATH 指向浏览器。');
18
+ }
19
+ export async function captureFrames(root,recipe,out) {
20
+ const {clip,source,width=384,height=384,frames=8}=recipe;
21
+ if(![width,height,frames].every(Number.isSafeInteger)||Math.min(width,height,frames)<1||Math.max(width,height)>2048||frames>120||width*height*frames>32e6) throw Error('取帧尺寸或帧数超出范围');
22
+ const file=await projectPath(root,source);
23
+ if(!/\.json$/i.test(file)) throw Error('指定 Spine 4.2 JSON 导出');
24
+ const rig=JSON.parse(await readFile(file,'utf8'));
25
+ if(!rig.skeleton?.spine?.startsWith('4.2.') || !Object.hasOwn(rig.animations??{},clip)) throw Error('骨架版本或所选动作无效');
26
+ let atlasFile=await projectPath(root,source.slice(0,-5)+'.atlas');
27
+ const atlas=await readFile(atlasFile,'utf8').catch(async e=>{
28
+ if(e.code!=='ENOENT') throw e;
29
+ return readFile(await projectPath(root,source.slice(0,-5)+'.atlas.txt'),'utf8');
30
+ });
31
+ const textures=[];
32
+ for(const page of new TextureAtlas(atlas).pages) {
33
+ const png=await readFile(await projectPath(root,join(dirname(file),page.name)));
34
+ textures.push('data:image/png;base64,'+png.toString('base64'));
35
+ }
36
+ const browser=await openBrowser();
37
+ try {
38
+ const page=await browser.newPage({viewport:{width,height}});
39
+ await page.setContent('<canvas></canvas>');
40
+ await page.addScriptTag({path:join(dirname(fileURLToPath(import.meta.resolve('@esotericsoftware/spine-webgl'))),'iife/spine-webgl.js')});
41
+ const duration=await page.evaluate(async ({rig,atlas,textures,clip,width,height})=>{
42
+ const canvas=document.querySelector('canvas');canvas.width=width;canvas.height=height;
43
+ const context=new spine.ManagedWebGLRenderingContext(canvas,{alpha:true,preserveDrawingBuffer:true});
44
+ const pages=new spine.TextureAtlas(atlas);
45
+ for(let i=0;i<pages.pages.length;i++) {
46
+ const image=await createImageBitmap(await (await fetch(textures[i])).blob(),{premultiplyAlpha:'none',colorSpaceConversion:'none'});
47
+ pages.pages[i].setTexture(new spine.GLTexture(context,image));
48
+ }
49
+ const data=new spine.SkeletonJson(new spine.AtlasAttachmentLoader(pages)).readSkeletonData(rig);
50
+ const skeleton=new spine.Skeleton(data); skeleton.updateWorldTransform(spine.Physics.reset);
51
+ const bounds=data.width && data.height ? data : skeleton.getBoundsRect();
52
+ if(!(bounds.width>0 && bounds.height>0)) throw Error('骨架缺少可见范围');
53
+ const scene=new spine.SceneRenderer(canvas,context);
54
+ const scale=Math.max(bounds.width/width,bounds.height/height);
55
+ scene.camera.position.set((bounds.x??0)+bounds.width/2,(bounds.y??0)+bounds.height/2,0);
56
+ scene.camera.setViewport(width*scale,height*scale);scene.camera.update();
57
+ const state=new spine.AnimationState(new spine.AnimationStateData(data));
58
+ window.renderFrame=time=>{
59
+ state.clearTracks();skeleton.setToSetupPose();state.setAnimation(0,clip,false).trackTime=time;
60
+ state.apply(skeleton);skeleton.updateWorldTransform(spine.Physics.reset);
61
+ const gl=context.gl;gl.viewport(0,0,width,height);gl.clearColor(0,0,0,0);gl.clear(gl.COLOR_BUFFER_BIT);
62
+ scene.begin();scene.drawSkeleton(skeleton,pages.pages[0].pma);scene.end();return canvas.toDataURL('image/png').split(',')[1];
63
+ };
64
+ return data.findAnimation(clip).duration;
65
+ },{rig,atlas,textures,clip,width,height});
66
+ const times=recipe.times ?? Array.from({length:frames},(_,i)=>duration*i/frames);
67
+ if(!Array.isArray(times)||!times.length||times.length>120||width*height*times.length>32e6||times.some(t=>!Number.isFinite(t)||t<0||t>duration+1e-5)) throw Error('时间点必须位于动作时长内');
68
+ const columns=Math.ceil(Math.sqrt(times.length)),layers=[],raw=[],files=[];
69
+ for(const [i,time] of times.entries()) {
70
+ const png=Buffer.from(await page.evaluate(t=>window.renderFrame(t),time),'base64');
71
+ const name='frame-'+String(i+1).padStart(3,'0')+'.png';
72
+ await writeFile(join(out,name),png);files.push(name);
73
+ layers.push({input:png,left:i%columns*width,top:Math.floor(i/columns)*height});
74
+ if(recipe.gif) raw.push(await sharp(png).ensureAlpha().raw().toBuffer());
75
+ }
76
+ await sheet(width*columns,height*Math.ceil(times.length/columns)).composite(layers).png().toFile(join(out,'comparison.png'));
77
+ if(recipe.gif) {
78
+ const delay=times.map((t,i)=>Math.max(20,Math.round(1000*((times[i+1]??duration)-t))));
79
+ await sharp(Buffer.concat(raw),{raw:{width,height:height*raw.length,channels:4,pageHeight:height}}).gif({delay,loop:0}).toFile(join(out,'preview.gif'));
80
+ }
81
+ return {clip,duration,width,height,times,files,comparison:'comparison.png',...(recipe.gif?{gif:'preview.gif'}:{})};
82
+ } finally {await browser.close();}
83
+ }
@@ -0,0 +1,76 @@
1
+ import sharp from 'sharp';
2
+ import {mkdir, writeFile} from 'node:fs/promises';
3
+ import {join} from 'node:path';
4
+ import {projectPath} from '../video/path.mjs';
5
+
6
+ export function identifier(value) {
7
+ if (typeof value !== 'string' || !/^[\p{L}\p{N}_-]{1,96}$/u.test(value) || /^(con|prn|aux|nul|(?:com|lpt)\d)$/i.test(value)) throw Error('无效部件或资源名:'+value);
8
+ return value;
9
+ }
10
+ const transparent = {r:0,g:0,b:0,alpha:0};
11
+ export function sheet(width,height) { return sharp({create:{width,height,channels:4,background:transparent}}); }
12
+ function dimensions(actual, expected, label) {
13
+ if(actual.width !== expected.width || actual.height !== expected.height) throw Error(label+' 尺寸与定位矩形不一致');
14
+ }
15
+ export async function splitParts(root, recipe, out) {
16
+ const source = await projectPath(root,recipe.prototype);
17
+ const {width,height} = await sharp(source).metadata();
18
+ if(width*height>32e6 || !Array.isArray(recipe.parts) || !recipe.parts.length || recipe.parts.length>256) throw Error('需要原型和 1–256 个有序部件');
19
+ const images = join(out,'images');
20
+ await mkdir(images);
21
+ const names = new Set(), layers=[], parts=[];
22
+ let pixels=0, patched;
23
+ for (const part of recipe.parts) {
24
+ const name=identifier(part.name), key=name.toLowerCase();
25
+ if(names.has(key)) throw Error('部件名重复:'+name);
26
+ names.add(key);
27
+ const {left,top,width:w,height:h}=part.rect ?? {};
28
+ if(![left,top,w,h].every(Number.isSafeInteger)||left<0||top<0||w<1||h<1||left+w>width||top+h>height) throw Error(name+' 超出母版');
29
+ pixels+=w*h;
30
+ if(pixels>64e6) throw Error('部件总像素过大');
31
+ const pivot=part.pivot ?? [left+w/2,top+h/2];
32
+ if(!Array.isArray(pivot)||pivot.length!==2||!pivot.every(Number.isFinite)) throw Error('轴心使用母版像素坐标 [x,y]');
33
+ let image=sharp(source).extract(part.rect).ensureAlpha();
34
+ if(part.replacement) {
35
+ const replacement=await projectPath(root,part.replacement);
36
+ const size=await sharp(replacement).metadata();
37
+ if(size.width*h!==size.height*w) throw Error(name+' 补绘图与部件矩形宽高比不一致');
38
+ image=sharp(replacement).resize(w,h).ensureAlpha();
39
+ }
40
+ let coverage;
41
+ if(part.mask) {
42
+ const mask=await projectPath(root,part.mask), size=await sharp(mask).metadata();
43
+ // The alpha channel carries coverage; an opaque grayscale mask uses luminance.
44
+ let pipeline=sharp(mask);
45
+ if(size.width===width && size.height===height) pipeline=pipeline.extract(part.rect);
46
+ else dimensions(size,{width:w,height:h},name+' 蒙版');
47
+ coverage=await (size.hasAlpha ? pipeline.extractChannel('alpha') : pipeline.greyscale()).raw().toBuffer();
48
+ }
49
+ if(part.replacement) {
50
+ patched ??= await sharp(source).toColourspace('srgb').ensureAlpha().raw().toBuffer();
51
+ const replacement=await image.clone().toColourspace('srgb').ensureAlpha().raw().toBuffer();
52
+ for(let y=0;y<h;y++) for(let x=0;x<w;x++) {
53
+ const local=y*w+x, origin=((y+top)*width+x+left)*4;
54
+ const mix=coverage ? coverage[local]/255 : 1;
55
+ if(mix===0) continue;
56
+ const a=patched[origin+3]*(1-mix), b=replacement[local*4+3]*mix;
57
+ for(let c=0;c<3;c++) patched[origin+c]=a+b ? Math.round((patched[origin+c]*a+replacement[local*4+c]*b)/(a+b)) : 0;
58
+ patched[origin+3]=Math.round(a+b);
59
+ }
60
+ }
61
+ if(coverage) {
62
+ const alpha=await sharp(coverage,{raw:{width:w,height:h,channels:1}}).toColourspace('srgb').joinChannel(coverage,{raw:{width:w,height:h,channels:1}}).png().toBuffer();
63
+ image=image.composite([{input:alpha,blend:'dest-in'}]);
64
+ }
65
+ const bytes=await image.png().toBuffer();
66
+ await writeFile(join(images,name+'.png'),bytes);
67
+ layers.push({input:bytes,left,top});
68
+ parts.push({name,rect:part.rect,pivot,occludedBy:part.occludedBy ?? [],image:'images/'+name+'.png'});
69
+ }
70
+ for(const part of parts) if(!Array.isArray(part.occludedBy)||part.occludedBy.some(id=>!parts.some(p=>p.name===id) || id===part.name)) throw Error('遮挡关系引用了无效部件:'+part.name);
71
+ await sheet(width,height).composite(layers).png().toFile(join(out,'assembled.png'));
72
+ if(patched) await sharp(patched,{raw:{width,height,channels:4}}).png().toFile(join(out,'patched.png'));
73
+ const metadata={width,height,prototype:recipe.prototype,parts,...(patched?{patched:"patched.png"}:{})};
74
+ await writeFile(join(out,'parts.json'),JSON.stringify(metadata,null,2));
75
+ return metadata;
76
+ }
package/lib/spine.mjs ADDED
@@ -0,0 +1,42 @@
1
+ import {mkdir,mkdtemp,lstat,readFile,rename,rm,writeFile} from 'node:fs/promises';
2
+ import {dirname,join,resolve} from 'node:path';
3
+ import {projectPath} from './video/path.mjs';
4
+ import {splitParts} from './spine/parts.mjs';
5
+ import {buildRig} from './spine/build.mjs';
6
+
7
+ export const spineContract={
8
+ parts:{input:{prototype:'art/prototype.png',out:'work/parts-01',parts:[{name:'body',rect:{left:0,top:0,width:100,height:100},pivot:[50,75],occludedBy:[]}]},optional:'parts 的顺序为从后到前。mask 取透明通道或灰度,可传母版大小或局部大小。replacement 接受同比例补绘图。',outputs:['parts.json','images/','assembled.png']},
9
+ build:{input:{parts:'work/parts-01/parts.json',name:'actor',out:'work/rig-01',animations:{wave_001:{bones:{body:{rotate:[{time:0,value:0},{time:0.5,value:22}]}}}}},meshExample:{slot:'body',uvs:[0,0,1,0,0,1],triangles:[0,1,2],points:[[['body',-50,75,1]],[['body',50,75,1]],[['body',-50,-25,1]]]},optional:'bones 按名增改骨骼;meshes 为网格配方列表,points 每项含 [骨名,骨局部x,y,正权重],权重和为1。rig 可指定可编辑的 Spine 4.2 JSON,保留其骨骼、皮肤、约束、网格、权重及时间线;animations 按动作名合并。未传 rig 时使用 parts 中的轴心建立绑定。',outputs:['骨架 JSON','atlas','PNG 图集','images/','animations.json','report.json']},
10
+ capture:{input:{source:'work/rig-01/actor.json',out:'work/frames-01',clip:'wave_001',width:384,height:384,frames:8,gif:true},optional:'times 可直接指定秒数。无头 Chromium 使用 Spine WebGL 4.2 捕获实际像素。',outputs:['逐帧 PNG','comparison.png','preview.gif(可选)','capture.json']}
11
+ };
12
+ export async function runSpine(root,action,input) {
13
+ if(action==='describe')return spineContract;
14
+ if(!Object.hasOwn(spineContract,action))throw Error('未知 Spine 操作:'+action);
15
+ if(typeof input?.out!=='string'||!input.out.trim()) throw Error('指定新的项目内输出目录 out');
16
+ const target=await projectPath(root,input.out);
17
+ if(await lstat(target).then(()=>true,e=>{if(e.code!=='ENOENT')throw e;return false;}))throw Error('输出目录已存在,请为本次结果选择新目录');
18
+ await mkdir(dirname(target),{recursive:true});
19
+ const stage=await mkdtemp(join(dirname(target),'.spine-'));
20
+ try {
21
+ let result;
22
+ if(action==='parts') result=await splitParts(root,input,stage);
23
+ if(action==='build') result=await buildRig(root,input,stage);
24
+ if(action==='capture') {
25
+ const {captureFrames}=await import('./spine/capture.mjs');
26
+ result=await captureFrames(root,input,stage);
27
+ await writeFile(join(stage,'capture.json'),JSON.stringify(result,null,2));
28
+ }
29
+ await rename(stage,target);
30
+ return {out:input.out,...result};
31
+ } finally {await rm(stage,{recursive:true,force:true});}
32
+ }
33
+ export async function spineCli(args) {
34
+ const [action,...rest]=args, options={};
35
+ for(let i=0;i<rest.length;i+=2) {
36
+ if(!['--workspace','--input'].includes(rest[i])||Object.hasOwn(options,rest[i])||!rest[i+1])throw Error('用法:spine <describe|parts|build|capture> [--workspace 工程] [--input 项目内配方.json]');
37
+ options[rest[i]]=rest[i+1];
38
+ }
39
+ const root=resolve(options['--workspace']??process.cwd());
40
+ const input=options['--input']?JSON.parse(await readFile(await projectPath(root,options['--input']),'utf8')):{};
41
+ return runSpine(root,action,input);
42
+ }
package/package.json CHANGED
@@ -1,12 +1,13 @@
1
1
  {
2
2
  "name": "@kevlns/art-workshop",
3
- "version": "0.6.4",
3
+ "version": "0.6.5",
4
4
  "private": false,
5
5
  "description": "统一管理图片工坊与视频工坊:项目风格、图片生成编辑、剧本镜头、视频生成与成片精修。",
6
6
  "type": "module",
7
7
  "exports": {
8
8
  "./video": "./lib/video.mjs",
9
- "./*": "./*"
9
+ "./*": "./*",
10
+ "./spine": "./lib/spine.mjs"
10
11
  },
11
12
  "bin": {
12
13
  "art-workshop": "art-workshop.mjs"
@@ -53,8 +54,10 @@
53
54
  "manifest": "v-cli.plugin.json"
54
55
  },
55
56
  "dependencies": {
57
+ "@esotericsoftware/spine-webgl": "4.2.120",
56
58
  "bailian-cli": "2.2.1",
57
59
  "bailian-cli-core": "2.2.1",
60
+ "playwright-core": "1.65.1",
58
61
  "sharp": "^0.35.5",
59
62
  "zod": "4.6.7"
60
63
  }
@@ -16,6 +16,8 @@ description: "制作或调整 2D Spine 角色与动画时按需查阅。适用
16
16
  | 原画很像,进引擎后脸宽了、手袖有缝或姿势不对 | [绑定与蒙皮](references/rig-motion.md#绑定与蒙皮)、[对照修形](references/rig-motion.md#对照修形) |
17
17
  | 想做一个动作、改善循环或检查两段动作如何衔接 | [动作与转场](references/rig-motion.md#动作与转场)、[GIF 预览](references/rig-motion.md#gif-预览) |
18
18
  | 要交给程序、接入 Vanter,或运行后模糊、掉帧、包太大 | [导出、运行验收与成本取舍](references/delivery.md) |
19
- | 需要判断 Vant 能直接做哪一段、还缺什么 | [工具与缺口](references/delivery.md#工具与缺口) |
19
+ | 需要选择制作工具或读取输入契约 | [工具入口](references/delivery.md#工具入口) |
20
20
 
21
- **在 Vant 中预览。** 桌面提供 `vant_spine_preview` 时,用项目骨架相对路径或已登记资产 ID 打开浮窗,可指定初始动作。需要逐帧、查看绑定或对照上一版时,打开图片工坊的 Spine 页签。工作台以外使用目标版本的 Spine 播放器。需要分享动图时再导出 GIF。在 Vant 中确认某个项目导出版本入美术仓时,接续工作台的 `vant-asset-intake` 指南。
21
+ **制作入口。** 用 `v-cli art spine describe` 查询配方。原画定位与蒙版回贴用 `parts`;骨架、权重、时间线和运行图集用 `build`;指定时刻实绘、对照图和分享 GIF 用 `capture`。这些命令可在独立工作目录执行。
22
+
23
+ **在 Vant 中预览。** 桌面提供 `vant_spine_preview` 时,用项目骨架相对路径或已登记资产 ID 打开浮窗,可指定初始动作。需要逐帧、查看绑定或对照上一版时,打开美术工坊标题栏右侧的 Spine 页签。工作台以外使用目标版本的 Spine 播放器。需要分享动图时再导出 GIF。在 Vant 中确认某个项目导出版本入美术仓时,接续工作台的 `vant-asset-intake` 指南。
@@ -19,15 +19,13 @@ Vanter 的实例交付 Spine 4.2 骨架 JSON、原始部件 PNG、PMA 图集、
19
19
 
20
20
  记录调整前后的运行包大小、纹理尺寸与页数、目标端测量值,并保留同帧同尺寸的图。交付时从干净目录用实际加载入口播放一次,检查 atlas 各页和附件都能解析、大小写路径匹配、动作完成事件与循环正常。仅验证过 Unity 时,将 Web 验收标为待测,反之亦然。[Spine 性能指标](https://esotericsoftware.com/spine-metrics) · [Spine 图集打包](https://esotericsoftware.com/spine-texture-packer)
21
21
 
22
- ## 工具与缺口
22
+ ## 工具入口
23
23
 
24
- 以下入口由 Vant 桌面工作台提供,按当前宿主实际可用的工具选择。
24
+ 以 `v-cli art spine describe` 读取当前工具契约。各制作命令接受 `--workspace <工程目录> --input <工程内配方.json>`,产物写入配方指定的新目录。以已有产物为输入继续修订。
25
25
 
26
- | 当前工作 | Vant 中的可用入口与边界 |
26
+ | 当前工作 | 入口与产物 |
27
27
  | --- | --- |
28
- | 制作预览与修形复核 | 图片工坊 → Spine → 接入项目资产。填项目相对的骨架路径,图集和页纹理随骨架一起读取。用部件显隐、绑定叠加、时间轴和上一版本对照检查修改;同一项目的美术讨论能读取所选动作、秒数与版本。 |
29
- | 画原型、重绘部件、生成替换手形 | 会话使用 `vant_art_conversation` 的 `generate` 或 `edit`,通过 `describe` 查当前输入,`wait` 取回对应结果。编辑带基准图并注明保留项。图像结果还需配准、抠取和拼回验证。 |
30
- | 项目风格、参考与资产 | 通过 `vant_art` 的 `describe` 查询相应操作。项目已有拆件、打包或预览脚本时,先核对输入、输出和适用角色,再复用。 |
31
- | Unity 实例验收、Vanter 对话里试动作 | Unity 交互复用项目配置的 `v-cli` Unity 工具,先核对目标工作区的项目路径及实例。Vanter 在桌面用 `vanter_animation` 查询和播放已装配动作。 |
32
-
33
- **目前缺少的通用制作入口**有三处:带原画坐标、轴心和遮挡元数据的拆件与精确蒙版回写;创建或编辑 Spine 骨架、网格、权重与时间线;从指定运行端批量取帧、生成对照图和 GIF 并统计导出成本。Vanter 有角色专用的构建和 Unity 预览脚本,可供项目参考。实际制作可用现有项目脚本或匹配版本的 Spine Editor;环境缺少某项时,指出受影响的产物及尚未验证的部分。
28
+ | 原型与补绘 | 使用当前工作环境的生图、编辑工具制作原型和补绘图。用 `spine parts` 指定母版像素矩形、轴心、前后顺序与遮挡关系。蒙版接受透明度或灰度图;同比例高清替换图配准到原矩形。检查 assembled.png,采用补绘前后对照 patched.png 与原图。 |
29
+ | 骨架与动画 | `spine build` 读取 parts.json,按轴心建立初始绑定。用 bones 按名增改骨骼,meshes 指定目标插槽、UV、三角索引、各点的骨名/骨局部坐标/权重。animations 使用 Spine 4.2 时间线。后续可传已编辑的 rig 骨架 JSON,保留其余皮肤、约束和动作。 |
30
+ | 制作验收 | 美术工坊 → Spine 接入导出骨架。桌面对话可用 `vant_spine_preview` 打开同一资产。需要留存指定姿势或分享时,用 `spine capture` 选择动作、秒数或均匀帧数,输出逐帧 PNG、对照图及可选 GIF;需要本机 Chrome、Edge 或 Chromium。 |
31
+ | 交付 | 核对导出的骨架、图集 PNG 与 atlas、animations.json 和 report.json。report 给出运行文件字节数、未压缩 RGBA 占用、骨骼、顶点和影响数。目标引擎的真实帧耗时需在该引擎测量。 |
package/v-cli.plugin.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "package": "@kevlns/art-workshop",
4
4
  "command": "art",
5
5
  "bin": "art-workshop",
6
- "description": "管理图片与视频两个独立制作通道;图片旧命令兼容,视频复用项目状态、CAS及原执行身份。",
6
+ "description": "管理图片、视频与 Spine 骨骼动画制作。",
7
7
  "platforms": [
8
8
  "win32",
9
9
  "linux",
@@ -6918,6 +6918,126 @@
6918
6918
  "保存或建任务不发起生成;版本冲突重新读取;样张仅作绘制语言参考,不能保证隔离无关特征"
6919
6919
  ],
6920
6920
  "capabilityId": "art.image-style-sample-remove"
6921
+ },
6922
+ {
6923
+ "path": [
6924
+ "spine",
6925
+ "describe"
6926
+ ],
6927
+ "usage": "art-workshop spine describe",
6928
+ "description": "读取 Spine 制作契约",
6929
+ "arguments": [],
6930
+ "options": [
6931
+ {
6932
+ "flags": "--workspace <dir>",
6933
+ "description": "目标工程,默认当前目录"
6934
+ }
6935
+ ],
6936
+ "output": {
6937
+ "format": "json",
6938
+ "description": "返回制作契约或输出文件清单"
6939
+ },
6940
+ "exitCodes": {
6941
+ "0": "成功",
6942
+ "1": "输入或制作失败"
6943
+ },
6944
+ "capabilityId": "art.spine-describe",
6945
+ "safety": [
6946
+ "只读工具契约。"
6947
+ ]
6948
+ },
6949
+ {
6950
+ "path": [
6951
+ "spine",
6952
+ "parts"
6953
+ ],
6954
+ "usage": "art-workshop spine parts --input <file>",
6955
+ "description": "按母版坐标拆件、蒙版补绘与拼合检查",
6956
+ "arguments": [],
6957
+ "options": [
6958
+ {
6959
+ "flags": "--workspace <dir>",
6960
+ "description": "目标工程,默认当前目录"
6961
+ },
6962
+ {
6963
+ "flags": "--input <file>",
6964
+ "description": "工程内 JSON 制作配方,参见 spine describe"
6965
+ }
6966
+ ],
6967
+ "output": {
6968
+ "format": "json",
6969
+ "description": "返回制作契约或输出文件清单"
6970
+ },
6971
+ "exitCodes": {
6972
+ "0": "成功",
6973
+ "1": "输入或制作失败"
6974
+ },
6975
+ "capabilityId": "art.spine-parts",
6976
+ "safety": [
6977
+ "仅使用目标工程内输入;制作结果原子写入新目录。"
6978
+ ]
6979
+ },
6980
+ {
6981
+ "path": [
6982
+ "spine",
6983
+ "build"
6984
+ ],
6985
+ "usage": "art-workshop spine build --input <file>",
6986
+ "description": "编译并校验骨架绑定、蒙皮、动作和图集",
6987
+ "arguments": [],
6988
+ "options": [
6989
+ {
6990
+ "flags": "--workspace <dir>",
6991
+ "description": "目标工程,默认当前目录"
6992
+ },
6993
+ {
6994
+ "flags": "--input <file>",
6995
+ "description": "工程内 JSON 制作配方,参见 spine describe"
6996
+ }
6997
+ ],
6998
+ "output": {
6999
+ "format": "json",
7000
+ "description": "返回制作契约或输出文件清单"
7001
+ },
7002
+ "exitCodes": {
7003
+ "0": "成功",
7004
+ "1": "输入或制作失败"
7005
+ },
7006
+ "capabilityId": "art.spine-build",
7007
+ "safety": [
7008
+ "仅使用目标工程内输入;制作结果原子写入新目录。"
7009
+ ]
7010
+ },
7011
+ {
7012
+ "path": [
7013
+ "spine",
7014
+ "capture"
7015
+ ],
7016
+ "usage": "art-workshop spine capture --input <file>",
7017
+ "description": "使用 WebGL 取帧、生成对照图和可选 GIF",
7018
+ "arguments": [],
7019
+ "options": [
7020
+ {
7021
+ "flags": "--workspace <dir>",
7022
+ "description": "目标工程,默认当前目录"
7023
+ },
7024
+ {
7025
+ "flags": "--input <file>",
7026
+ "description": "工程内 JSON 制作配方,参见 spine describe"
7027
+ }
7028
+ ],
7029
+ "output": {
7030
+ "format": "json",
7031
+ "description": "返回制作契约或输出文件清单"
7032
+ },
7033
+ "exitCodes": {
7034
+ "0": "成功",
7035
+ "1": "输入或制作失败"
7036
+ },
7037
+ "capabilityId": "art.spine-capture",
7038
+ "safety": [
7039
+ "仅使用目标工程内输入;制作结果原子写入新目录。"
7040
+ ]
6921
7041
  }
6922
7042
  ]
6923
7043
  },