asset-index 元数据字段全解:scale_m、pbr_maps、recommended_tier等30列完整参考

原创2026-11-09 09:08:162,344 阅读
文章标签:数据集3D建模数据目录

asset-index 元数据字段全解:scale_m、pbr_maps、recommended_tier等30列完整参考

asset-index 是 CodePawl 开源的 3D 资产索引数据集:把 6 个主流 3D 资源库(Quixel Megascans、Kenney、Smithsonian、ambientCG、Poly Haven、Quaternius)共 37,668 个 3D 资产汇总进一张结构统一的表格,每行包含真实尺寸 scale_m、PBR 贴图清单 pbr_maps、优化档位 recommended_tier 等 30 多个元数据字段。无论你是给 AI Agent 写资产检索逻辑、给 Web 游戏选资源,还是给动画资产做分镜管理,读懂这些元数据字段就是第一课。本文就是这份 asset-index 元数据字段的完整参考。

一、为什么需要统一的 3D 资产元数据?

不同资源库对同一个资产的描述五花八门:有的只给贴图分辨率,有的只给文件名,有的连真实尺寸都不标注。结果就是"一个 0.5 米的木箱"在不同库里需要不同的筛选方式。

asset-index 的解法是:每一行都使用同一套列,并且把尺寸统一换算成真实米数。这样一行查询就能跨库命中:

python tool/query.py metadata.parquet "wooden crate, 0.5 m, game tier"
python tool/query.py metadata.parquet "rock cliff, wet, 2 m, film" --top 5
python tool/query.py metadata.parquet "tileable forest floor material, web" --free

命令细节可以查看 tool/query.py,数据本体是两个文件:

  • metadata.parquet:Parquet 格式,适合 pyarrow / pandas / Hugging Face datasets 读取
  • metadata.jsonl:逐行 JSON,方便脚本和 AI Agent 逐条解析

两个文件都通过 Git LFS 存储(见 .gitattributes),clone 后若内容是指针文本,运行 git lfs pull 即可拉取真实数据。

二、字段分组速览

全部列可以按用途分成 7 组,先看全景表,再逐组细读:

分组 字段 回答的问题
识别 asset_id source title source_url collection authors 它是谁、从哪来
授权 licence redistributable credit no_ai ai_generated 能不能用、要不要署名
分类 kind style category_path tags surface_type biomes 属于哪类、什么风格
尺寸 size_m scan_area_m scale_m size_class size_from 真实多大、数据可信度
技术 triangles lods texel_density_px_m pbr_maps max_texture_px 性能开销多少
能力 tileable atlas rigged animated 能不能平铺/换装/播放
使用 use_for animation_role recommended_tier get files search_text 怎么用、怎么拿

三、识别与来源字段

  • asset_id:行内唯一标识,跨库不重复
  • source:来源库名(如 quaternius、megascans),query.py --source kenney 就是按它过滤(query.py#L105-L107)
  • title / source_url:原始名称和详情页地址
  • collection:Kenney 的工具包名或 Quaternius 的资源包名
  • authors:作者信息

四、授权字段:先看 redistributable,再看 credit

  • licence:SPDX 许可证 ID(CC0、CC-BY、Fab Standard 等)
  • redistributable:文件是否可以直接随项目分发——这是最关键的布尔值,query.py 的 --free 参数就是按它过滤的(query.py#L108-L111)
  • credit:使用时需要展示署名文案的那一行文字
  • no_ai / ai_generated:Fab 的 NoAI 与 CreatedWithAI 标记(仅 Megascans 行有值),read_on 记录读取日期
  • --trainable 参数会剔除被 Fab 标记 NoAI 的行

一句话经验:CC0 行指向可直接下载的文件;Megascans 行只指向 Fab 页面,仓库本身不存放任何 Megascans 文件(授权不允许转分发)。

五、分类字段:一套规则统一所有资源库

  • kind:model(模型)、material(材质)、decal(贴花)、atlas(图集)、hdri、brush、terrain
  • style:photoreal(写实扫描)、stylized(风格化)、lowpoly(低模)
  • category_path / tags:原库分类路径与标签
  • surface_type:表面材质类型(rock、wood、leather…),所有库共用同一套词表
  • biomes:适用生态(forest、desert、urban…)

query.py 会把 material / model / decal / hdri 等关键词映射到 kind,把 lowpoly / photoreal 映射到 style 做硬过滤(query.py#L19-L22)。

六、尺寸字段:scale_m 是全文案匹配的核心

这是整个索引最有价值的一组字段:

字段 含义
scale_m 真实尺寸(米),道具入场景时按它摆正大小
size_m 原始标注尺寸
scan_area_m 扫描/贴图的覆盖面积(材质类资产)
size_class 尺寸档位分类
size_from 尺寸数据出处:列表页、库 API 还是项目自测

scale_m 是 query.py 匹配尺寸词的字段:请求 "0.5 m" 会保留 0.25 ~ 1.0 m(目标值一半到两倍)的行(query.py#L72-L75)。官方统计:ambientCG 572 行、Megascans 22,223 行、Poly Haven 1,390 行具有已知尺寸。

对动画师来说,scale_m 意味着道具可以直接按相机距离取用,不用猜"这个木箱到底 30cm 还是 3m"。

七、技术字段:pbr_maps、texel_density_px_m 与性能预算

  • pbr_maps:该资产拥有的 PBR 贴图角色清单(albedo、normal、roughness、metallic、occlusion、opacity、displacement 等)。判断"能否做金属材质"就看它有没有 metalness 与 roughness
  • triangles / lods:三角面数与 LOD 层级(库提供或项目实测)
  • texel_density_px_m:每米纹素密度,衡量贴图精度密度,query.py 排序时用它做同分决胜(query.py#L82)
  • max_texture_px:最大贴图分辨率

贴图角色的命名规则可以参考转换器的识别表(tool/converters/megascans/megascans.mjs#L28-L40):文件名含 orm/arm 记为 ORM 合图、normal/nor_gl 记为法线、diffuse/albedo 记为基色等。

八、能力字段:tileable、atlas、rigged、animated

字段 含义 典型用途
tileable 可无缝平铺 地面、墙面重复材质
atlas 是"可切割的图集合" Kenney 式道具合集
rigged 带骨骼 全库共 192 行,--rigged 直接筛出
animated 附带可播放的动画片段 直接用于镜头

九、使用建议字段:recommended_tier 决定用哪个优化档位

recommended_tier 是一个按用途分档的 JSON 对象,取值来自 game / web / mobile / film 四个用途,指向 tool/lib/common.mjs#L19-L28 里定义的优化档位:

  • web:meshopt 几何 + WebP 贴图(objects/),适配 three.js 与 WebGPU
  • ktx2:KTX2 贴图(objects_ktx2/),省 GPU 显存
  • lod:50% / 20% / 6% 三角面三级 LOD(lods/)
  • mobile:小贴图 + 轻几何(mobile/)
  • engine:面向 Unreal / Unity / Godot 的全精度(engine/)
  • collision:凸包碰撞体(collision/)

配套的另外三列:

  • use_for:适合的使用场景描述
  • animation_role:按"镜头里怎么用它"排序的角色——character(角色)、terrain/set surface(地形或场景面)、ground cover(植被)、hand prop(手持道具)、set dressing(陈设)、background(背景)、lighting(HDR 照明)
  • get / files:现在怎么拿到它;files 在该资源库打包完成后,列出各档位的优化 GLB 地址

query.py 会按你请求里的用途词(如 "game tier")取出对应档位并输出下载地址(query.py#L24 与 query.py#L85-L96)。

十、search_text:为匹配而生的一行小写文本

search_text 把标题、分类、标签、材质、生态等拼成一行小写文字,query.py 的其余关键词全部在这一列上做词干匹配并按命中数排序。自己写 Agent 检索逻辑时,把它当作向量库之外的轻量全文字段直接用即可:

from datasets import load_dataset
rows = load_dataset("codepawl/asset-index", split="train")
crates = rows.filter(lambda row: "crate" in row["search_text"]
                     and row["scale_m"] and 0.25 <= row["scale_m"] <= 1)

十一、常见误区速查

  • 误区:clone 完就能打开 parquet —— 两个数据文件走 Git LFS,显示为指针时需 git lfs pull;读取 parquet 需要 pyarrow(tool/README.md)
  • 误区:Megascans 行有文件链接 —— 仓库只存 Fab 公开列表信息,Megascans 需先在 Fab 领取,再用 tool/megascans/optimize.mjs 在本地优化
  • 误区:size 单位混乱 —— 请求里写 30 cm 或 2 m 均可,工具会统一换算为米再做"半倍到两倍"区间过滤

总结

asset-index 的 30 多个列围绕一条主线设计:让一句自然语言请求(尺寸 + 用途 + 类型 + 风格)能精确命中一行可执行的资源地址。日常只需记住三列——scale_m 看真实尺寸、pbr_maps 看材质能力、recommended_tier 看优化档位,其余字段按需查阅本文的分组速览即可。完整列说明见 README.md,查询工具见 tool/query.py。

登录后查看全文
asset-index