asset-index 元数据字段全解:scale_m、pbr_maps、recommended_tier等30列完整参考
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、terrainstyle: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与roughnesstriangles/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 与 WebGPUktx2: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。