img2threejs 图像分析协议八层受控观察法把单张参考图转成可执行的三维重建规格【免费下载链接】img2threejsRebuild the object in a reference image as a code-only, procedural, quality-gated, animation-ready Three.js model. Token-efficient image-to-3D.项目地址: https://gitcode.com/gh_mirrors/im/img2threejs本文讲解 img2threejs 项目中的核心前置环节——Image Analysis Protocol图像分析协议。它是一套面向 Agent 的、与具体对象类型无关object-agnostic的八层观察流程规定了在调用图像探测脚本、撰写ObjectSculptSpec之前必须用受控的 3D 词汇、按固定自下而上的顺序把单张参考图有什么描述成后续每个质量门gate都能消费的结构化证据。读完本文你将掌握八层协议的词汇体系与落地字段映射、三大观察纪律的实操写法以及它如何与probe_image.py、build_detail_inventory.py、new_pre_spec_assessment.py等工具串成看图 → 取证 → 定复杂度 → 建规格的完整链路。为什么需要这套协议先观察再写代码在 img2threejs 的重建管线中grimoire/intake/image_analysis.md被明确要求最先执行——它排在forge/stage1_intake/probe_image.py之前也排在 pre-spec 评估之前。文档给出了存在理由Agent 倾向于整张图扫一眼然后直接跳到写代码跳过那种被纪律约束的观察而后续每一个质量门都依赖这份观察输出。如果观察本身是草率的后面的复杂度分级、组件树、材质通道、身份特征清单都会建立在不可靠的地基上。这套协议是通用、与对象无关的任何主题都适用——道具、工具、武器、载具部件、植物、机械、角色。CS2 皮肤、角色等领域轨道domain tracks是叠在这一遍通用观察之后的特化层而不是替代品详见后文领域特化一节。协议的输出正是forge/stage2_spec/new_pre_spec_assessment.pypre-spec 评估与质量契约骨架和forge/stage1_intake/build_detail_inventory.py分区裁剪与细节清单骨架的原料。三大纪律整个协议的支柱协议的核心规则只有一句话描述那里有什么用固定的自下而上顺序、受控的 3D 词汇——而不是它意味着什么或感觉如何。支撑这条规则的是三条纪律先观察、后推断Observation before inference。把可观察的事实脊柱处有一条低粗糙度光带与从它推断出的结论可能是个抛光倒角分开陈述并且给每条推断打上推断标记。受控词汇优先于形容词。使用下文各层的词汇表以及grimoire/glossary/3d_vocabulary.md中的术语。永远不要写 nice / sleek / aggressive / high-quality 这类模糊形容词。用 3D 对象空间而不是 2D 图像空间。用 front/back/lateral/proximal 描述部件不要用照片里的左侧/右侧。单张照片只是一个投影——要明确指出这个视角隐藏了什么。八层观察协议核心骨架按顺序执行八层每一层的产出都喂给一个真实的评估字段完整映射见下文表格。Layer 1 — 识别与分类Identification classification观察什么对象是什么、属于哪个类别以及你的置信度。在做出任何关于价值/用途的断言之前先完成一份物理清单physical inventory。词汇工作类型一个具体名词——statuette小雕像、karambit爪刀、socket wrench套筒扳手、rhyton角状杯、宽泛分类bladed tool刀具、furnishing陈设、mechanical part机械件、primaryDomain取值为object|character|hybrid、置信度 0–1。避免用对象的标题/名称当作描述在完成清单之前就断言含义索引超出可见证据。在代码侧这一层的结果落在preSpecAssessment.objectClass上。forge/stage2_spec/new_sculpt_spec.py中make_pre_spec_assessment()生成的骨架包含primaryType、primaryDomain、formLanguage、structureKind、motionPotential、materialFamilies等字段注释明确要求从直接视觉检查填写不要使用固定领域档案并提示将 primaryDomain 设为 object、character 或 hybrid。Layer 2 — 整体形态与剪影Overall form silhouette观察什么用一小撮基元描述包围体积与占地轮廓bounding volume footprint对称性。词汇基元cuboid、cylinder、sphere、cone、extruded profile、lofted curve对称性bilateral、radial、asymmetric造型语言geometricvsorganic相对一个指名参照尺寸的长宽比/比例。避免情绪化形状词没有参照系的大/小当形体是混合体时强行塞进单一基元。该层影响复杂度分级complexity tier、几何策略以及referenceCamera的取景。3d_vocabulary.md提供了与之一致的术语silhouette从给定相机角度对对象外轮廓的读取、primitive familybox、sphere、ellipsoid、cylinder、cone、capsule、torus、lathe、extrusion、tube、plane card、instanced cluster 等、topology intenthard-surface blockout、subdivision-ready surface、low-poly prop、organic deformed mesh、alpha-card cluster。Layer 3 — 宏观 → 中观 → 微观分解Macro → meso → micro decomposition观察什么把整体拆成主要组件major assemblies、再拆成子部件sub-parts、再拆成表面级的特征组surface-level feature groups——为组件化建模形成一个parent-child 层级。词汇macro独立的大部件——blade刀刃、grip握把、guard护手meso子组件——rivet row铆钉排、finger choil指槽、pommel尾盖micro特征组——fastener cluster紧固件簇、engraving band雕刻带。避免把对象当成一个整体单体网格把简单结构过度嵌套跳过某一层级macro 直接跳 micro、没有 meso。这一层喂给componentTree的层级数量与minimumSpecDepth。注意new_pre_spec_assessment.py中的复杂度下限表COMPLEXITY_MINIMUMS正是用这一层统计的部件数量来决定规格深度的复杂度macroComponentsmesoComponentsmicroFeatureGroupsmaterialLayersrepetitionSystemsreviewViewpointssimple100102moderate232203complex385314ultra-complex5168425对应的DETAIL_MINIMUMStargetMinDetails下限simple 3、moderate 6、complex 10、ultra-complex 16。Layer 4 — 空间关系场景图Spatial relationships / scene-graph观察什么部件之间在 3D 中如何连接、如何相对放置。词汇视觉三元组subject, predicate, object如guard, separates, bladegrip空间谓词attached-to、above、below、inside、behind、flush-with、embedded-in每条连接都要注明接触类型butt、overlap、socket、embed。避免用 2D 图像空间定位画面里的左/右只描述相邻却不说明部件如何真正接合——悬空部件会直接挂掉后面的 attachment 门。该层喂给attachment字段parentSocket、contactType、embed/overlap。在new_sculpt_spec.py中可以看到 attachment 契约的完整字段集parentSocket、localStart/localEnd、contactType、baseRadius/endRadius、embedDepth、gapTolerance并且质量契约的featureGroups里有专门的attachment-joint-correctness组其失败模式包括子部件根部漂浮在父部件之外分支/肢体/管道悬在空间中央而非绕其根部转动等。Layer 5 — 材质与表面PBR观察什么每个部件的材质构成以及它对光的响应。每个不同表面一条材质声明并绑定到一个组件。词汇albedo/baseColor去除光照的表面色、metalness0 为电介质1 为纯金属、roughness0 抛光 → 1 哑光、specular F0电介质约 4%、normal/reliefpitting点蚀、grain纹理、pores孔隙、brushing拉丝、translucencyopaque/semi-translucent/transparent。避免把烘焙进图的高光/阴影当 albedo 读把亮面塑料叫金属把一个通道别名化到另一个通道详见grimoire/feedback/shading_realism.md。该层喂给materials的 PBR 通道与material.localOverrides。grimoire/feedback/shading_realism.md反复强调一个失败模式程序化对象在形状过关后渲染仍然不像参考图往往是因为每种材质只有一个平铺 albedo 色、没有 roughness 变化、没有可触感的 normal/bump/displacement、缺少局部覆盖苔藓、污渍、边缘磨损、锈蚀等。它要求 material-pass 之前规格必须包含独立的 PBR 通道——绝不能把 albedo 复用作 roughness/height/normal/AO 图。这与3d_vocabulary.md的材质词表edge wear、clearcoat、transmission、anisotropy、local mask等以及new_sculpt_spec.py质量契约中的antiShallowSpecRulesalbedo 被复用作 roughness、height、normal 或 AO 时不得通过材质 look-dev完全呼应。Layer 6 — 颜色与表面处理Color finish观察什么每个区域的色相hue、明度value、饱和度saturation表面处理。词汇hue / value / saturation处理方式matte、satin、gloss、metallic、anodized渐变必须写成带位置的有序色标ordered stops而不是渐变成这种模糊说法。避免用主观/品牌色名皇家蓝代替标准描述vivid blue, mid value存在渐变或多色调处理的地方只给一个平色。该层喂给colorMaterialRecipe、渐变色标gradient stops与finishStyle。仓库提供了配套脚本forge/stage1_intake/extract_gradient_stops.py用于从参考图提取梯度色标。Layer 7 — 身份定义特征Identity-defining features观察什么让这一件物区别于其类别的通用成员的那些标记。词汇铭文/标记签名、日期、Logo、序列号、磨损模式scratch、dent、oxidation/patina、stain、edge-wear、重复出现的母题recurring motifs。避免忽略小而关键的身份标记一个工匠印记、一个会改变拓扑的独特缺口。每个身份特征都应该成为一条detailInventory条目如果它可能出错还应成为featureReviewTarget。该层喂给detailInventory的 details 与featureReviewTargets。grimoire/intake/detail_inventory.md给出了完整的细节分类法kind→ 图形学实现方式是这一层的直接落地手册gloss局部高光局部低 roughness 区或镜面热点而非全局材质变化——落到material.localOverridesroughness 0.05–0.2或用clearcoatclearcoatRoughness拉丝高光用anisotropyanisotropyRotation必须记录热点相对主光方向的位置没有对应光向的 gloss 渲染不出来。bevel倒角真实几何的棱边处理不是贴图技巧——component.localFeatures的edgeTreatment.type chamfer、bevelRadius对象相对值如 0.02–0.08、segments柔和边 2–4硬边 1。参考图里棱边若是清晰亮线必须用真实几何不能用法线贴图。fastener螺丝/铆钉/螺栓重复小件永远是实例化系统InstancedMesh绝不一个个单独建网格记录count、分布linear/radial/grid、头部形状、凹/凸、材质。置信度要反映是所有实例可见还是只可见可推断的子集。linework刻线/涂装线/板件线三种不同手法按证据选一种雕刻凹槽几何凹陷 groove需要真实几何否则任何光线下都显平、涂装线/贴花material.localOverrides画布贴图只有颜色对比、板件线细的 AO 缝——沿接缝的局部 roughness/AO 变暗无真实深度。contour轮廓/卡通描边风格化描边通常用 rim-light 或背面轮廓技术记录哪些剪影边携带它。seam接缝两个表面相遇处的构造线——细的凹陷 groove 或凸起的 ridge 加缝隙处更暗的 AO 覆盖。stitch织物缝线沿缝线的细密凸点或虚线凹槽通常配linework的涂装线表达线色对比。stain污渍/锈蚀/变色/褪色总是material.localOverrides区域子字段含dirtAmount0–1、cavityBias、streak竖直/方向性流淌、patinaColor、fadedMask褪色区、region。scratch划痕细的局部 roughness/normal 扰动可选暴露底层颜色记录方向簇与是否露出不同底色。chip缺角改变剪影时用几何缺口否则用暴露底色的局部覆盖。decal贴花/标签material.localOverrides画布贴图区域记录位置、近似尺寸、旋转除非有物理厚度否则不加几何。emissive自发光material.localOverrides的emissive颜色 emissiveIntensity是否在色调映射下泛光、是否需匹配点/面光源。hole孔洞/插槽改变剪影/拓扑的真实开孔——真实切割或插槽不是深色贴图补丁记录深度与内腔是否需独立材质。groove凹槽沿路径的负向浮雕记录对象相对宽度/深度槽内加 AO 变暗。ridge凸脊groove 的几何逆操作正向浮雕顶部棱线吃高光若参考图在脊顶有高光线配 gloss 或 bevel 注释。detailInventory的每个条目必须设置mapsTo指向真实的component.localFeatures[]或material.localOverrides[]条目。只用散文描述而无法映射的细节是门失败gate failure——生成器读不到它它就到不了渲染结果。Layer 8 — 不确定性与单图局限Uncertainty single-image limits观察什么单视角没显示什么哪里模糊或有歧义。词汇occluded被另一部件挡住、hidden背面/内部本视角看不到、uncertain模糊/歧义、needs another view、undetermined。避免臆造被遮挡/隐藏的细节而不标记为推测忽略透视畸变。这里的每一个未知都会变成preSpecAssessment.unknownsToResolveBeforeImplementation条目并可能成为request-input的理由。在new_sculpt_spec.py的评估骨架中unknownsToResolveBeforeImplementation是preSpecAssessment的顶层字段与detailInventory、complexity、specDepthDecision、anatomy并列——说明不确定性不是可有可无的备注而是实现前必须显式消解或请求用户输入的正式条目。输出每一层落在哪里层流向1 识别分类objectClass.primaryType/primaryDomain、复杂度分类2 形态与剪影复杂度层级、几何策略、referenceCamera取景3 宏/中/微观分解componentTree层级数量 minimumSpecDepth4 空间关系attachmentparentSocket、contactType、embed/overlap5 材质与表面materialsPBR 通道 material.localOverrides6 颜色与处理colorMaterialRecipe、渐变色标、finishStyle7 身份特征detailInventorydetails featureReviewTargets8 不确定性unknownsToResolveBeforeImplementation、request-input决策配套取证工具链从看到结构化证据协议的输出不是凭空写的仓库提供了三个配套脚本把观察过程工具化、防漏检1.forge/stage1_intake/probe_image.py—— 技术性图像探测。文档要求协议先于该脚本执行因为probe_image.py只回答图像的技术属性不回答对象语义是否适合。它通过解析文件头直接读尺寸支持 PNG/JPEG/GIF/WebP/BMP/TIFFdetect_image_type()源码输出type、bytes、width、height、aspectRatio并给出technicalSuitabilitypass/conditional与警告。两个值得注意的警告规则源码宽度或高度小于 512px 时警告低分辨率小的几何/材质细节可能不可靠长宽比超过 3.0 或低于 0.33 时警告极端长宽比对象可能被裁剪或周围是大片空白。脚本结尾的 note 写得很清楚这只是技术性图像探测对象的语义适用性仍需目视检查。——正好印证了协议 Layer 1 的位置分类与清单必须由人/Agent 观察完成脚本只做客观探测。2.forge/stage1_intake/build_detail_inventory.py—— 分区扫描与细节清单骨架。它把参考图按区域切开均匀网格grid-3x3/grid-4x4或命名组件区域component-zones每个区域输出一张裁剪 PNG 加一个 detail 占位条目build_inventory。设计动机与协议 Layer 7 完全一致一次扫全图会漏掉小的身份定义标记。脚本只负责分区和裁剪不判断里面有什么——判断是观察者的工作。每条 stub 的字段id、kind、description、region、scale、affects、mapsTo、evidenceRef、confidence正是协议 Layer 7 要求逐项填写的结构化记录authoringInstruction明确要求用实际观察替换每个 stub 的字段mapsTo必须引用真实的 component.localFeatures 或 material.localOverrides 条目。区域坐标是归一化的units: normalized--components参数支持name:x,y,w,h自定义命名区域。3.forge/stage2_spec/new_pre_spec_assessment.py—— 评估与质量契约生成。读取前两层观察的结论后用命令行把复杂度、细节下限、领域轨道落进 JSONpython forge/stage2_spec/new_pre_spec_assessment.py Karambit \ --image reference.png --complexity ultra-complex --cs2 \ --out assessment.json关键行为源码与 make_payload--complexity可选simple/moderate/complex/ultra-complex不传时 CS2 目标默认ultra-complextargetMinDetails16其他默认moderateCS2 轨道有9 条细节下限CS2_DETAIL_MINIMUM 9即使显式把--complexity设低targetMinDetails也绝不会低于 9——因为皮肤本身就是重点身份细节是硬门槛--cs2也可由关键词启发式自动触发detect_cs2_intent()匹配 cs2/karambit/doppler/fade 等常见表达complex/ultra-complex 层级会自动要求repetitionSystems、materialLocalOverrides且minimumComponentLevels必须含 macromesomicro 三层支持--character角色 v1.5 轨道、--manifestCS2 intake manifest状态须为 proceed/fallback、--spec-query/--reindex-specs本地规格库 BM25 检索authoringInstruction要求实现前必须填充objectClass、复杂度推理、featureGroups、visualDeltaChecks与unknowns。质量契约make_quality_contract()源码定义了五组强制featureGroupsoverall-silhouette、primary-structure、attachment-joint-correctness、surface-material-response、reference-lookdev、五条visualDeltaChecks剪影与负空间、层级深度、重复密度与分布、材质 albedo/roughness/normal 响应、局部特征放置与尺度以及一组antiShallowSpecRules——其中多条直接引用图像观察qualityBar 未评估不得进入代码可见局部特征只写在散文里而未挂到组件/材质/证据引用上不得进入代码。这些规则说明图像分析协议不是建议而是质量门的输入契约。领域特化通用观察跑完后再叠加领域规则通用协议对每个对象都跑一遍。当 Layer 1 识别出专门领域时在其上叠加额外规则但绝不能跳过任何通用层CS2 武器/刀具/手套皮肤→ 叠加grimoire/intake/cs2_technical_analysis.mdCS2 技术分析与逆向工程协议与grimoire/intake/cs2_texture_acquisition.md纹理获取。CS2 协议的 M.C.M.T 框架Macro Shape / Components / Materials / Topology与通用协议严格对齐组件用正确解剖命名Blade 的 Edge/Spine/Swedge/Ricasso、Guard/Quillon、Handle 的 Scales/Tang、Pommel、FastenersPBR 提取严格到 Three.jsMeshStandardMaterial/MeshPhysicalMaterial值区分 Solid Paint、Anodized Metal、Projected Skin磨损Float 值明确为 Edge Wear边缘掉漆露金属、Patina/RustbaseColor 氧化、metalness 降到 0.0、roughness 飙到 0.8、Scratches/Dents高频法线修改。其 JSON 输出 schema 中的featureReviewTargets、visibility_warnings正是通用协议 Layer 7/8 的领域化。在grimoire/feedback/shading_realism.md的实战记录里还有一个强约束当文字简报与参考图冲突时以参考图为准采样匹配——img2threejs 是从图像重建曾因追着 prose 把紫色推进照片里明明是蓝色的区域而浪费了 4 轮渲染。角色/混合体character/hybrid→ 叠加grimoire/character/reconstruction.mdhead-units 头身比、landmarks 面部标志点、proportion lock 比例锁定。在new_sculpt_spec.py中make_pre_spec_assessment()的anatomy块applies、proportions、faceLandmarks、pose仅在primaryDomain为 character 或 hybrid 时才有意义字段来源指向forge/stage1_intake/extract_landmarks.py与grimoire/character/reconstruction.md、grimoire/character/likeness_maximization.md。一句话总结二者的分工通用协议决定那里有什么领域文档决定该类对象按惯例如何参数化。观察纪律的三个实操样本把协议落到笔头下面三组对比可以当作校准标准词汇来自grimoire/glossary/3d_vocabulary.md的 Writing Rule 与grimoire/intake/detail_inventory.md坏the surface is ugly and too smooth。好increase microRoughness to 0.45, add tangent-space fine-noise normal with strength 0.2 and scale 32, add low-frequency albedo mottling at amplitude 0.12, and add cavity dirt local masks in recessed grooves。坏make the edges realistic。好add 0.025 relative bevel radius with 3 segments on exposed hard-surface edges, add edge-wear local overrides on bevel crests, and keep internal seams sharper with 1-segment chamfers。坏用整图平均值描述颜色。好按区域给出主色/次色/点缀色的albedo色板、roughness基值变化量局部响应磨损边缘更光、凹腔更糙、至少一种normal/bump/displacement及其尺度/幅度/强度。与质量门的闭环严格校验协议链路的最后一道闸是严格质量校验。在生成代码之前运行python forge/stage2_spec/validate_sculpt_spec.py spec.json --strict-quality若严格校验失败修复顺序是来自grimoire/intake/quality_contract.md先修订preSpecAssessment如果复杂度被低估、再修订qualityContract如果完成定义太泛、补充缺失的组件/材质层/重复系统/证据引用/局部特征只有在用户明确接受更低保真近似时才能下调质量杆。门的设计意图很直白当这份规格能描述很多不同的对象而不是给定的那张参考图时就应当拦截住代码生成——而防止这种泛化规格的第一道防线正是本文的八层图像分析协议。小结grimoire/intake/image_analysis.md定义的八层协议本质上是一份观察契约Layer 1–2 定身份与剪影、Layer 3–4 建组件层级与场景图、Layer 5–6 提取 PBR 与颜色、Layer 7 锁定身份特征、Layer 8 标注单图局限。它与probe_image.py客观技术探测、build_detail_inventory.py分区防漏检、new_pre_spec_assessment.py复杂度与细节下限落档、validate_sculpt_spec.py --strict-quality实现前闸门共同构成 img2threejs 从单张参考图到可执行、可质量门控的ObjectSculptSpec的第一环。对 Agent 而言最值得记住的一句话是先完整地、按顺序地、用受控词汇说出那里有什么再谈怎么建、建多深——观察的顺序就是规格质量的顺序。【免费下载链接】img2threejsRebuild the object in a reference image as a code-only, procedural, quality-gated, animation-ready Three.js model. Token-efficient image-to-3D.项目地址: https://gitcode.com/gh_mirrors/im/img2threejs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考