img2threejs 图像材质分析门禁从参考图证据到 Three.js PBR 材质的强制验收管线【免费下载链接】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导读本文以 docs/materials/IMAGE_MATERIAL_ANALYSIS.md 为核心系统讲解 img2threejs 项目中图像材质分析这一强制准入门的完整契约从参考图像的可观察证据出发产出结构化材质假设经material-reference.json注册表对账后映射为 Three.jsMeshPhysicalMaterial候选并在受控渲染视角下验证、由门禁脚本最终放行。读完本文你将掌握该项目的材质分析七阶段流程、假设记录与状态机、查找解析顺序、贴图色彩空间与通道打包规则、受控验证视图体系以及如何在源码层面对照实现细节。1. 定位材质分析是材质创作的准入闸门在 img2threejs 的九阶段材质管线中有材质 ID不等于材质合格。材料分析material analysis是一条强制准入闸门一个模型不能仅仅因为每个部件都被分配了一个材质 ID就进入或通过材质构建阶段material build pass。每一个关键可见区域critical visible region都必须有证据证明该区域的材质 ID 与渲染响应相对参考图是可信的plausible。这一立场被完整地实现于仓库源码中区域级分析入口forge/stage1_intake/material_region_analysis.py注册表加载与解析forge/materials/reference.py规格接线forge/stage2_spec/apply_material_analysis.py阻断式验收forge/stage4_review/material_gate.py。整套契约的端到端行为由 forge/tests/test_material_pipeline.py 覆盖下文会逐一对照。2. 阶段一输入与准入Inputs2.1 分析器的输入清单每个材料区域的分析需要以下输入已准入的参考图像带哈希hash、角色role与相机元数据组件掩码与材质区域掩码每个可用视图per usable view一份用户提供的提示词或权威元数据prompt or authoritative metadata稳定命名的组件与区域 ID这些 ID 必须在 UV、蒙皮skinning、形变morphs与 LOD 全流程中保持稳定裁剪分辨率与可见足迹覆盖率crop resolution and visible-footprint coverage。2.2 裁剪前的拒绝规则在进入分类之前必须拒绝空裁剪、反转裁剪、碎片化裁剪、重复裁剪以及过小的裁剪。文档特别强调裁剪到了相邻组件cropping a nearby component是一次失败的门禁而不是低置信度证据——分析器不得把错误的裁剪区域包装成低置信度结论来蒙混过关。这一规则在源码_bounded_bboxmaterial_region_analysis.py中有量化实现bbox 必须包含数值型x、y、width、height支持normalized: true的相对坐标模式自动乘以图像宽高坐标被钳制到图像边界内最小裁剪尺寸为 8 像素if (x1 - x0) 8 or (y1 - y0) 8: raise ValueError(material crop is too small; minimum crop dimension is 8 pixels)。裁剪后会记录coverage裁剪面积占源图比例作为可见足迹覆盖率的证据字段见crop_region返回值。2.3 区域清单manifest格式分析器以 JSON manifest 为输入其结构示例摘自material_region_analysis.py的 docstring为{ referenceId: armor-front, regions: [ { componentId: torso-armor, regionId: paint, sourceImage: front.png, bbox: {x: 120, y: 80, width: 420, height: 300}, family: coating, subtype: paint-over-metal, finish: gloss-or-satin, materialSpecId: armor-paint } ] }测试夹具 test_material_pipeline.py 中的 manifest 与之对应区域torso-armor/paint声明为coating/paint-over-metal/gloss-or-satin分析后analysis[status]为proceed且解析出的profileId恰为coating.painted-metal。3. 阶段二先观察后分类Observation before classification分类之前对每个材质区域先记录可观察信号先不要命名材质。需要记录的信号维度包括去光照基色分布与颜色变化de-lit base-colour distribution and colour variation高光的颜色、宽度、锐利度、拉长程度与视角依赖性漫反射与镜面反射的平衡diffuse vs specular balance纤维、纹理、发丝、刷痕或机加工方向宏观、中观、微观三个表面频率带macro/meso/micro surface frequency bands不透明度、折射、透射与表观厚度线索边缘磨损、涂层剥落、氧化、污渍、湿润感与凹腔响应组件上下文服装、皮肤表面、刀刃、饰边、镜片、发团、轮胎、木板每个视图的遮挡与不确定性。文档给出的核心告诫是绝不能仅凭颜色分类材质。黑色塑料、橡胶、皮革和布料可以共享同一 albedo金色金属、黄铜和金属黄漆可以共享同一色相。真正的判别依据是光响应证据light-response evidence。源码在_observationsmaterial_region_analysis.py中把这些可观察信号量化成了可复用的判定阈值纹理统计量阈值产出的观察结论meanSaturation 0.18近中性色响应 / 彩色基色响应streakRatio 1.9或 0.53方向性表面频率拉丝/纹理方向mottle 0.038可见中观/微观变化gradientStrength 0.18强图像空间梯度需验证是材质图案而非光照最后还会追加一条通用观察单图 PBR 推断必须经过受控渲染验证——这是整套契约的底线立场。4. 阶段三假设记录Hypothesis record每个区域必须产出一条结构化假设而非一个裸词。文档中的标准格式为{ componentId: jacket, regionId: body-cloth, family: fabric, subtype: woven, finish: matte, confidence: 0.78, evidenceViews: [front-primary, three-quarter-right], sourceCropPaths: [jacket-front.png, jacket-3q.png], observations: [], alternatives: [ {materialId: leather.matte, confidence: 0.31} ], status: proceed }允许的状态值status只有四种proceed证据充分可进入下一步probe需进一步探测/拟合request-input需要更多视图或用户元数据unknown无法判定。缺失置信度、裁剪、掩码或证据视图时按失败关闭fails closed——宁可失败不可静默通过。在analyze_manifestmaterial_region_analysis.py中产出的 hypothesis 还合并了语义假设与 PBR 像素证据的置信度confidence min(region.confidence, pbr_report.confidence)即取两者较低者任何一方薄弱都会拉低整体置信度。同时若 PBR 置信度低于目标阈值target_threshold默认 0.7且解析状态为proceed会被强制降级为probe——低置信度推断永远不会被静默提升为proceed。5. 阶段四查找与证据对账Lookup and evidence reconciliation5.1 双证据源原则假设生成后需对照 docs/materials/material-reference.json 进行解析**语义视觉semantic vision**提供候选身份identity**确定性图像分析deterministic image analysis**提供颜色、梯度、高光与频率证据。任何单一来源都不能独自决定结果。5.2 对账规则双方都高于配置阈值且一致 → 播种候选配方seed the candidate recipe身份已知但表面证据弱 → 保留身份将 PBR 值标记为受控渲染拟合controlled-render fitting最高候选之间存在实质性差异且该区分是关键的 → 请求另一个视图或显式用户元数据绝不因为默认配方渲染好看就提高置信度。5.3 源码中的解析顺序resolve_materialforge/materials/reference.py实现了文档规定的查找顺序显式权威 materialId若 hypothesis 携带的materialId在注册表中存在直接以methodexplicit-material-id、confidence1.0、statusproceed返回。用户提供的材质身份优先于图像推断精确 family subtype finish 匹配仅命中唯一候选时采用置信度取自 hypothesis≥0.7 为proceed否则probe别名匹配遍历aliases/alternatives字段归一化分词后与注册表别名交集唯一命中才采用并保留所有匹配候选而非静默选择家族回退family fallback仅剩 family 维度匹配时置信度乘以 0.65 折减状态为probe无法解析家族匹配存在多个 →request-input完全没有家族匹配 →unknownreason 为 ambiguous or unknown material; request more evidence。build_assignmentreference.py进一步把解析结果组装成 spec 可用的赋值对象包含profileId、family/subtype/finish、renderPrior先验默认值、requiredMaps、optionalMaps、validationViews、sourceRefs与visualCues。测试 test_material_pipeline.py 验证了这三条核心语义显式 ID 即使置信度只有 0.2 也能以explicit-material-id通过coating/paint-over-metal/gloss-or-satin精确命中coating.painted-metal只有 family 的metal假设则落入request-input/probe。5.4 低置信度不得覆盖显式元数据文档明确用户提供的材质身份优先于图像推断低置信度的视觉猜测不得覆盖显式元数据。反过来文本材质名只提供身份不提供最终颜色、磨损或粗糙度——这些仍必须来自图像证据。6. 阶段五贴图与着色器编写Map and shader authoring6.1 贴图的色彩空间契约material-reference.json的textureContract字段给出了机器可读的权威规定颜色数据贴图sRGBmap、emissiveMap、sheenColorMap、specularColorMap数学数据贴图无色彩空间变换roughnessMap、metalnessMap、normalMap、aoMap、bumpMap、displacementMap、clearcoatMap、clearcoatRoughnessMap、clearcoatNormalMap、sheenRoughnessMap、transmissionMap、thicknessMap、anisotropyMap、iridescenceMap、iridescenceThicknessMap。通道打包channel packing约定如下贴图打包通道备注roughnessMap绿色通道—metalnessMap蓝色通道—aoMap红色通道需要 UV channel 1clearcoatMap红色通道—clearcoatRoughnessMap绿色通道—transmissionMap红色通道—thicknessMap绿色通道—sheenRoughnessMap透明通道alpha—anisotropyMap红-绿为方向、蓝色为强度—6.2 独立信号与分层表面albedo、roughness、metalness、normal/height、AO 是相互独立的信号各自单独创作涂层表面必须正确表示顶层完整漆面即使基材是金属其本身仍是电介质dielectric暴露的漆面破损处可使用独立的金属区域或 mask。对应到 Three.js 参数完整漆面metalness接近 0破损处才用独立 mask 暴露金属基材几何负责轮廓级形态纤维、毛簇、发团、褶皱、棱面、深损伤法线/凹凸贴图只负责亚像素或小尺度浮雕。albedo 不得伪造缺失的形体不得把褶皱/明暗烘焙进 albedo。6.3 运行时实现模式THREEJS_MATERIAL_REFERENCE.md给出了可复制的 Three.js 写法颜色贴图用SRGBColorSpace数据贴图用NoColorSpace标量与贴图是相乘关系白色数据贴图保留标量、黑色贴图抑制标量。贴图槽在首次编译后才附加时需设material.needsUpdate truePBR 对比必须使用稳定 HDR 环境PMREMGenerator预过滤。7. 阶段六受控验证视图Controlled validation views每个关键材质都需要其查找记录中列出的验证视图视图验证内容albedo-unlit去光照的颜色与图案、区域指派是否正确neutral-studio平衡的漫反射/镜面响应grazing粗糙度、法线强度、sheen、各向异性、涂层environment-reflection区分导体与抛光涂层backlight-transmission透射/体积材料透光、折射、厚度reference-beauty在已求解相机位姿下的最终观感一致性必须在所有纹理加载完成后才截图。保存每张图、读回校验并比较组件在整场景中的可见足迹visible footprint——不能用隔离渲染isolation render去暴露参考图中被遮挡的表面。源码侧由 forge/stage4_review/material_views.py 实现视图计划与捕获校验build_view_plan生成视图计划测试中要求至少 12 个视图、覆盖 4 个以上方位角validate_capture对截图做读回校验最小尺寸 64×64。门禁要求受控视图必须依赖稳定环境view_plan.environment.required true。8. 阶段七门禁策略Gate policy8.1 材质环节失败的条件材质环节material pass在以下任一情况发生时失败某个关键可见区域没有假设或查找结果一个材质被指派到多个视觉上不兼容的区域证据置信度低于阈值且无显式用户身份解决必需贴图或受控视图缺失导体渲染成电介质、织物渲染成光滑塑料、毛发渲染成橡胶、玻璃渲染成 alpha 混合的空气高全局美感分数掩盖了某个失败的关键材质区域纹理加载、色彩空间、环境预处理或截图读回失败。8.2unknown可接受静默替换不可接受文档最后一句点题unknown是可接受的分析结果静默替换silent substitution不是。8.3 门禁实现run_material_gateforge/stage4_review/material_gate.py把上述策略翻译成可执行检查spec 未接入materialPipeline、或materialPipeline.status ! proceed→ 失败存在未解析的unresolvedNotObservedMaterials→ 失败隐藏区域无法观察时最多只能获得低置信度家族先验任一区域的status ! proceed→ 失败无材质裁剪对比证据comparisons→ 失败视图计划少于 4 个方位角、或捕获读回/覆盖校验未通过 → 失败环境未要求 → 失败再叠加几何/UV/蒙皮/碰撞/LOD 的材质 ID 兼容性检查check_compatibility见 forge/materials/compatibility.py。门禁的requiredEvidence字段明确列出了五条硬性证据要求作为最终验收清单。9. 参考库起始先验而非普适真理README.md 明确指出材质库存放的是有界的起始先验bounded starting priors不是普适真理。粗糙度、clearcoat、transmission 等外观参数取决于表面处理、磨损、尺度、光照和真实参考。管线必须先对可见材质区域分类 → 用匹配记录作为有界起点 → 对照已准入图像证据拟合 → 在受控渲染下验证。9.1 查找契约的应用顺序权威元数据或已评审 spec 提供的精确规范 materialId精确的family subtype finish匹配别名匹配保留所有候选不静默选择家族回退降低置信度当区分影响关键可见区域时 →unknown与request-input。9.2 应用契约Application contract将记录的renderPrior复制进候选材质绝不直接写入已接受的 spec颜色与图案取自已准入、去光照的组件裁剪不得把参考图的烘焙阴影或高光当作 albedo颜色贴图保持在THREE.SRGBColorSpace粗糙度/金属度/法线/AO/厚度/各向异性等数据贴图保持在THREE.NoColorSpace创作每一个requiredMap仅当表面在目标分辨率下确实均匀时才允许用明确记录的常量替换贴图初始只在先验范围内拟合超出范围必须有记录的理由涂层、风化、风格化或矛盾证据捕获每个validationView并比较组件可见足迹美感beauty永远不足以作为材质证据。9.3 硬限制Hard limits单张 RGB 图像无法唯一分离光照、反射率、粗糙度与几何钢 vs 铝、真皮 vs 合成革、金 vs 金属漆在缺乏上下文/多视图/受控光源时可能保持歧义MeshPhysicalMaterial只是对皮肤、毛发、皮毛和分层织物的近似不是光谱/次表面/发丝渲染器环境强度与曝光是场景校准控制项不是材质固有常量被刻意排除在逐材质物理身份之外隐藏区域在获得更多证据前只能继承低置信度的家族先验。10. 起始先验速查表THREEJS_MATERIAL_REFERENCE.md提供了一张速查表结合material-reference.json中每个记录的renderPrior含默认值与合法范围常用材质起点如下规范材质metalnessroughness高级起始值关键证据人类皮肤00.52clearcoat 0.12, IOR 1.4中性光掠射光毛孔无塑料光泽人类毛发00.45anisotropy 0.65方向性高光随发丝/发团风格化皮毛00.78sheen 0.45掠射响应破碎轮廓编织哑光织物00.85sheen 0.65编织法线宽掠射 sheen丝绸/缎面00.32sheen 0.85, anisotropy 0.45移动的方向性高光天鹅绒00.72sheen 1.0暗正面体柔和亮边缘哑光皮革00.62clearcoat 0.08不规则纹理更平滑的磨损边缘抛光钢/铬10.12—锐利的中性环境反射拉丝钢10.35anisotropy 0.85沿拉丝方向拉长的反射铝10.30anisotropy 0.20亮中性缎面导体铜10.28—红橙导体反射铜绿单独处理黄铜/青铜10.30—黄棕导体响应金10.22—黄色反射能量而非黄色漫反射漆涂层金属烤漆00.45clearcoat 0.75电介质漆面金属破损需 mask/区域亮面塑料00.28clearcoat 0.20, IOR 1.5彩色漫反射体上的中性高光哑光塑料00.68IOR 1.5宽高光注塑/麻点微结构哑光橡胶00.88IOR 1.48弱宽高光抓握微纹理未上漆木材00.72anisotropy 0.12纹理方向影响颜色与粗糙度清漆木材00.42clearcoat 0.75独立涂层反射下的木纹天然石材00.78可选 clearcoat多尺度矿物图案与浮雕釉面陶瓷00.26clearcoat 0.70, IOR 1.5硬电介质体釉面反射透明玻璃00.05transmission 1, IOR 1.5背景畸变、反射与厚度磨砂玻璃00.52transmission 0.85, IOR 1.5模糊透射蚀刻微法线石英类宝石00.06transmission 0.9, IOR 1.54刻面与厚度相关透射必须使用 JSON 中的范围而非只看默认列。磨损、湿润、氧化、落尘、刮伤、抛光或风格化表面可能落在范围内其他位置或需要全新的 finish 记录。注册表还包含几个**纯代码code-only**变体例如hair.human.code-only、skin.human.code-only、fabric.woven-matte.code-only它们requiredMaps为空完全依靠标量先验承载观感。skin.human.code-only还声明了forbiddenPropertiestransmission/thickness/attenuationDistance因为 transmission 是屏幕空间折射模型在封闭人体网格上会渲染成玻璃人。这些记录附带的note给出了从 Three.js 源码反推的实现细节如lights_physical_fragment.glsl.js中clearcoatRoughness下限 0.0525、WebGLMaterials.js中 sheen 与 sheenColor 相乘等。11. 材质创作要点速览皮肤albedo 用去光照图像颜色绝不要把面部阴影烘焙进去metalness 恒为 0clearcoat 只是克制的湿油近似不是塑料外壳褶皱/皱纹等改变轮廓的形体归几何负责。毛发与皮毛几何发团/卡片负责轮廓与分缝贴图负责发丝尺度变化毛发需按 UV/切线流向创作各向异性贴图皮毛与天鹅绒用 sheen 表达掠射响应但改变可见轮廓的纤维仍需几何。织物与皮革织物是电介质metalness 0、高 roughness、编织法线、可选 sheen缎面需要更低 roughness 与方向响应哑光棉不需要皮革需要不规则纹理与磨损感知 roughness——不要仅凭棕色识别皮革大褶皱、缝线、下摆、针脚厚度属于几何或显式浮雕不是 albedo。裸金属清洁暴露的导体 metalness 置 1可见色调由基色/贴图驱动PMREM 过滤环境是有效验证的前提粗糙度控制反射扩散各向异性方向贴图建模拉丝氧化、污渍、漆和铜绿是独立的电介质/过渡区域除非像素在目标尺度下确实无法解析否则不要平均成单一分数金属度表面。涂漆金属完整漆面是电介质metalness≈0即便基材是金属用 clearcoat 表达清漆/汽车涂层并配独立 clearcoat 粗糙度贴图露出基材的破损需独立区域或金属度 mask——漆色本身无法揭示底层金属。塑料与橡胶两者都是电介质靠粗糙度、形变/上下文与微结构区分而非黑色或高光有无亮面塑料可用克制 clearcoat哑光橡胶一般不用。木材、石材与陶瓷木纹必须在颜色、粗糙度、法线通道间对齐清漆木是分层电介质纹理体清漆涂层石材用多尺度 albedo 与浮雕抛光石材仍是电介质釉面陶瓷用涂层反射破损处暴露更粗糙的坯体区域。玻璃与宝石用transmission而非低 opacity 实现物理透明opacity 保持 1厚度由几何尺度/thicknessMap推导提供可被折射的 PMREM 环境与背景磨砂主要是 roughness蚀刻微法线不是灰色 albedo不透明的宝石状漆面是涂层不是透射石英应按光响应分类。12. 常见分类失败清单文档总结了最常见的八类失败可直接作为评审 checklist黑织物、皮革、橡胶、塑料仅凭 albedo 分类黄铜、金、金属黄漆被折叠进同一个gold预设涂漆金属在完整漆面上被赋metalness 1毛发被做成哑光均匀读起来像橡胶或黏土织物被给予平坦法线且无 sheen读起来像塑料透明玻璃用 opacity 实现缺体积/折射为掩盖错误材质而改环境或曝光而不是修材质本身参考图原始高光被烘焙进 albedo随后又被二次照明。文档给出的收尾原则受控视图若相互矛盾把矛盾保留在证据中然后细化分类或请求输入绝不允许高美感相似度分数覆盖失败的材质硬门禁。13. 端到端管道接线与未来扩展材质库目录 docs/materials/ 定义了三方交接人类可读契约THREEJS_MATERIAL_REFERENCE.md、强制分析门禁IMAGE_MATERIAL_ANALYSIS.md与版本化查找表material-reference.json。预期的交接链为component/material-region mask - semantic material hypothesis - material-reference.json lookup - image-derived colour/PBR evidence - ObjectSculptSpec material assignment - Three.js material generation - controlled render and component microscope当前接线实现于 forge/stage1_intake/material_region_analysis.py、forge/stage2_spec/apply_material_analysis.py、生成器 provenance 钩子以及材质评审/门禁脚本。不含materialPipeline的 spec 保持向后兼容一旦 spec 选择接入该契约就会被阻塞直到其区域、裁剪、受控对比与几何/UV/蒙皮/LOD 兼容性证据全部通过。14. 实战命令行速查以下命令均为仓库内现成入口可用于复现整个材质分析→接线→门禁流程参考 test_material_pipeline.py 的垂直切片# 1) 区域级材质分析产出 material-analysis.json python forge/stage1_intake/material_region_analysis.py \ --manifest regions.json --out-dir analysis-data --out material-analysis.json \ --target-threshold 0.7 # 2) 将分析结果写入 ObjectSculptSpecprobe 区域需先评审再用 --allow-probe 显式放行 python forge/stage2_spec/apply_material_analysis.py spec.json material-analysis.json \ --out spec.wired.json # 3) 受控视图计划与截图读回 python forge/stage4_review/material_views.py --component torso-armor --region paint \ --validation-view neutral-studio --validation-view grazing --validation-view environment-reflection # 4) 阻断式材质门禁 python forge/stage4_review/material_gate.py spec.wired.json \ --analysis material-analysis.json \ --comparison comparison.json --view-plan view-plan.json \ --out material-gate.json执行门禁后passed: true才意味着材质环节通过返回码 2 表示存在失败项。记住文档的最终立场unknown是可接受的分析结果静默替换不是。【免费下载链接】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），仅供参考