TRELLIS-500K 数据集构建全指南：从元数据加载到稀疏结构/SLat 潜变量编码的完整数据管线-北京尧图网络

人工智能计算机视觉媒体生成预训练3D渲染【免费下载链接】TRELLISOfficial repo for paper Structured 3D Latents for Scalable and Versatile 3D Generation (CVPR25 Spotlight).项目地址https://gitcode.com/gh_mirrors/trell/TRELLIS点击查看免费下载TRELLIS-500K 是 TRELLISStructured 3D Latents for Scalable and Versatile 3D Generation项目用于训练大型 3D 资产生成模型的核心数据集包含约 50 万个经过美学评分筛选的 3D 资产。本文以 DATASET.md 为主线结合 dataset_toolkits 下的 12 个工具脚本与源码实现完整讲解从安装依赖、加载元数据、下载资产、渲染多视图、美学评分、体素化、DINO 特征提取到稀疏结构SS潜变量与 SLat 潜变量编码、图像条件渲染的九步数据准备流水线帮助你在自有数据上复现 TRELLIS 的完整训练数据。数据集概览TRELLIS-500K 的组成与统计TRELLIS-500K 是一个包含 500K实际训练集 500,777个 3D 资产的公开数据集资产来源包括五个公开数据集Objaverse(XL)含 sketchfab 与 github 两个来源ABOAmazon Berkeley Objects3D-FUTUREHSSDToys4k所有资产均经过美学评分aesthetic score阈值过滤只保留视觉质量达标的模型专门服务于 3D 生成任务的训练。数据集以 CSV 文件形式提供每个文件记录的是 3D 资产的元数据以 sha256 作为资产唯一标识而非资产本身。数据过滤与构成统计下表汇总了各来源的过滤阈值与最终规模摘自 DATASET.md来源美学评分阈值过滤后数量含文本描述数量ObjaverseXL (sketchfab)5.5168307167638ObjaverseXL (github)5.5311843306790ABO4.5448543903D-FUTURE4.594729291HSSD4.566706661All训练集-500777494770Toys4k评估集4.532293180两点需要注意部分 3D 资产缺少文本描述。如果训练文本条件生成模型text-to-3D必须先过滤掉captions为空的资产。原始表中训练集含描述数量为 494,770意味着约有 6000 个资产没有 caption。ObjaverseXL 的阈值更高5.5因为它体量巨大且质量参差ABO、3D-FUTURE、HSSD、Toys4k 使用 4.5。阈值的选择直接对应 build_metadata.py / download.py 等脚本中的--filter_low_aesthetic_score参数默认不启用过滤。数据托管位置数据集托管在 Hugging Face Datasets 上JeffreyXiang/TRELLIS-500K可直接在线预览。无需手动下载 CSV 文件——仓库提供了一整套工具包负责加载与准备数据这也是下文九步流水线的由来。工具包结构与九步流水线总览全部工具位于 dataset_toolkits 目录核心脚本与用途如下脚本流水线阶段核心产物setup.shStep 1 依赖安装Python 依赖环境build_metadata.pyStep 2 元数据加载/合并metadata.csv、statistics.txtdownload.pyStep 3 数据下载raw/原始资产render.pyStep 4 多视图渲染renders/sha256/calculate_aesthetic_scores.pyStep 4 美学评分aesthetic_scores_rank.csvvoxelize.pyStep 5 体素化voxels/sha256.plyextract_feature.pyStep 6 DINO 特征提取features/model/sha256.npzencode_ss_latent.pyStep 7 稀疏结构编码ss_latents/model/sha256.npzencode_latent.pyStep 8 SLat 编码latents/model/sha256.npzrender_cond.pyStep 9 图像条件渲染renders_cond/sha256/datasets/各来源适配模块ObjaverseXL.py、ABO.py等blender_script/渲染后端render.py、io_scene_usdz.zip注意原文档 Step 6 中写作extract_features.py仓库内实际文件名是extract_feature.py下文按实际文件名执行。Step 1安装依赖工具包只依赖少量 Python 库通过 setup.sh 一键安装. ./dataset_toolkits/setup.sh脚本内部实际执行与文档一致pip install pillow imageio imageio-ffmpeg tqdm easydict opencv-python-headless pandas open3d objaverse huggingface_hub open_clip_torch关键依赖用途objaverse下载 ObjaverseXLsketchfab/github资产与注解open3d utils3d体素化与 PLY 读写utils3d由 voxelize.py、extract_feature.py 等脚本导入来自仓库依赖不在 setup.sh 中单独列出时需确认训练环境已安装open_clip_torch美学评分器LAION aesthetic predictor的特征主干huggingface_hub读取托管在 Hugging Face 上的元数据 CSV。Step 2加载元数据第一步是加载数据集元数据。不同来源的元数据由 datasets 下的独立适配模块提供如 ObjaverseXL.py 直接通过pd.read_csv(hf://datasets/JeffreyXiang/TRELLIS-500K/ObjaverseXL_sketchfab.csv)拉取。python dataset_toolkits/build_metadata.py SUBSET --output_dir OUTPUT_DIR [--source SOURCE]参数说明SUBSET要加载的数据子集取值ObjaverseXL、ABO、3D-FUTURE、HSSD、Toys4kOUTPUT_DIR数据保存目录SOURCE仅当SUBSET为ObjaverseXL时必填取值sketchfab或github。示例——加载 ObjaverseXL (sketchfab) 子集并保存到datasets/ObjaverseXL_sketchfabpython dataset_toolkits/build_metadata.py ObjaverseXL --source sketchfab --output_dir datasets/ObjaverseXL_sketchfab源码级解析build_metadata.py 的合并机制从 build_metadata.py 源码看该脚本远比“加载 CSV”更强大它承担了整条流水线的状态簿记职责若metadata.csv已存在则加载否则调用datasets.SUBSET.get_metadata()获取初始元数据并以sha256作为索引逐类合并各阶段产物自动扫描并合并downloaded_*.csv、rendered_*.csv、aesthetic_scores_*.csv、voxelized_*.csv、cond_rendered_*.csv、feature_model_*.csv、latent_model_*.csv、ss_latent_model_*.csv合并完成后将源文件移动到merged_records/目录以时间戳命名为缺失的列补默认值renderedFalse、voxelizedFalse、num_voxels0、cond_renderedFalse以及各模型的feature_model/latent_model/ss_latent_model布尔列输出metadata.csv与statistics.txt后者统计已下载/渲染/体素化/特征/潜变量/含 caption/含图像条件的资产数量。脚本还支持两个额外参数--field指定要处理的字段逗号分隔默认all与--from_file当某些处理失败但文件已存在时直接扫描文件系统重建记录线程池并发检测renders/sha256/transforms.json、voxels/sha256.ply、各.npz文件的存在性。因此每完成一个处理步骤后都要重新运行一次 build_metadata.py把新产物登记进元数据。Step 3下载 3D 资产元数据就绪后即可下载资产python dataset_toolkits/download.py SUBSET --output_dir OUTPUT_DIR [--rank RANK --world_size WORLD_SIZE]SUBSET同上取值五个子集之一OUTPUT_DIR数据保存目录RANK/WORLD_SIZE多节点并行切分参数见下文“多节点并行”。示例仅作演示设置很大的WORLD_SIZE只会下载极小一部分数据python dataset_toolkits/download.py ObjaverseXL --output_dir datasets/ObjaverseXL_sketchfab --world_size 160000源码级解析download.py 与数据集适配模块从 download.py 源码可见其核心逻辑读取metadata.csv可选--filter_low_aesthetic_score过滤低分资产也可用--instances文件路径或逗号分隔的 sha256 列表只处理指定资产默认只下载local_path为空的资产即未下载的按rank/world_size切分任务区间后调用datasets.SUBSET.download()结果写入downloaded_rank.csv含sha256与local_path两列。以 ObjaverseXL.py 为例下载通过oxl.get_annotations()oxl.download_objects()完成产物保存到raw/目录github 来源以 zip 形式存储仓库快照后续处理时由foreach_instance解压到临时目录再调用处理函数。下载完成后必须重新运行 build_metadata.py 合并downloaded_*.csvpython dataset_toolkits/build_metadata.py ObjaverseXL --output_dir datasets/ObjaverseXL_sketchfab部分数据集可能需要交互式登录 Hugging Face 或手动下载工具包会给出相应提示按提示操作即可。Step 4渲染多视图图像与可选的美学评分多视图渲染是后续特征提取的基础使用 Blender 批量渲染python dataset_toolkits/render.py SUBSET --output_dir OUTPUT_DIR [--num_views NUM_VIEWS] [--rank RANK --world_size WORLD_SIZE]NUM_VIEWS渲染视角数默认150RANK/WORLD_SIZE多节点配置。示例python dataset_toolkits/render.py ObjaverseXL --output_dir datasets/ObjaverseXL_sketchfab源码级解析render.py 的相机与 Blender 调度从 render.py 源码看首次运行会自动下载并解压Blender 3.0.1到/tmp通过wgettar并安装libxrender1 libxi6 libxkbcommon-x11-0 libsm6等运行库相机位姿由sphere_hammersley_sequence见 utils.py生成默认视角数 150radius2、fov40°带随机偏移避免位姿重复调用blender_script/render.py见 blender_script/render.py附带io_scene_usdz.zip用于 USDZ 导入以CYCLES 引擎、512×512 分辨率渲染同时--save_mesh保存网格每个资产产物为renders/sha256/transforms.json含相机内外参多视图图像渲染成功与否以transforms.json是否存在判定支持--max_workers默认 8并发渲染已渲染过的资产存在transforms.json会被自动跳过天然支持断点续跑。可选计算自有渲染数据的美学评分如果要对自己的数据集计算美学评分python dataset_toolkits/calculate_aesthetic_scores.py --output_dir OUTPUT_DIR [--rank RANK --world_size WORLD_SIZE]从 calculate_aesthetic_scores.py 源码看它加载 LAION 的aesthetic-predictorsa_0_4_vit_l_14_linear.pth模型权重自动下载缓存到~/.cache/emb_reader配合 open_clip 的ViT-L-14OpenAI 预训练权重对每个资产的快照图像打分输出每个资产的mean / std / min / max / median五个统计量到aesthetic_scores_rank.csv。评分完成后同样需要重新运行 build_metadata.py 合并分数。Step 5体素化 3D 模型体素化把网格转换成稀疏体素点云供稀疏结构SS建模使用python dataset_toolkits/voxelize.py SUBSET --output_dir OUTPUT_DIR [--rank RANK --world_size WORLD_SIZE]示例python dataset_toolkits/voxelize.py ObjaverseXL --output_dir datasets/ObjaverseXL_sketchfab源码级解析voxelize.py 的 64³ 体素网格从 voxelize.py 源码看输入是 Step 4 渲染时保存的renders/sha256/mesh.ply顶点先被钳制到[-0.5, 0.5]立方体内-0.5 1e-6到0.5 - 1e-6使用 Open3D 的VoxelGrid.create_from_triangle_mesh_within_bounds体素尺寸 1/64即在 64×64×64 网格上体素化体素坐标归一化回[-0.5, 0.5]后写入voxels/sha256.ply并记录体素数num_voxels脚本断言所有体素坐标位于[0, 64)内越界会报错已体素化的资产存在对应.ply自动跳过。完成后更新元数据python dataset_toolkits/build_metadata.py ObjaverseXL --output_dir datasets/ObjaverseXL_sketchfabStep 6提取 DINO 特征这一步为 SLat VAE 准备训练数据从多视图图像提取 DINO 特征并聚合到稀疏体素网格上。python dataset_toolkits/extract_feature.py --output_dir OUTPUT_DIR [--rank RANK --world_size WORLD_SIZE]示例python dataset_toolkits/extract_feature.py --output_dir datasets/ObjaverseXL_sketchfab源码级解析extract_feature.py 的特征聚合过程从 extract_feature.py 源码看特征模型默认DINOv2dinov2_vitl14_reg--model可换通过torch.hub.load(facebookresearch/dinov2, ...)加载并置于 CUDA、关闭梯度每张视图缩放到518×518对应n_patch 518 // 14 37个 patch经 ImageNet 归一化后送入模型读取renders/sha256/transforms.json中的相机位姿c2w经坐标修正求逆得到extrinsicsfov转成intrinsics读取voxels/sha256.ply得到体素坐标将体素坐标通过投影 F.grid_sample双线性采样到 patch token 特征图上再按视图取平均得到每个体素位置上的特征向量fp16 存储产物为features/dinov2_vitl14_reg/sha256.npz内含indices体素整数坐标uint8与patchtokens聚合后的特征脚本只处理rendered True且voxelized True的资产已提取的自动跳过支持--batch_size默认 16控制 GPU 推理批量。完成后更新元数据python dataset_toolkits/build_metadata.py ObjaverseXL --output_dir datasets/ObjaverseXL_sketchfabStep 7编码稀疏结构SS潜变量稀疏结构潜变量用于训练第一阶段的稀疏结构生成器sparse structure Flow Modelpython dataset_toolkits/encode_ss_latent.py --output_dir OUTPUT_DIR [--rank RANK --world_size WORLD_SIZE]示例python dataset_toolkits/encode_ss_latent.py --output_dir datasets/ObjaverseXL_sketchfab源码级解析encode_ss_latent.py 的编码器加载从 encode_ss_latent.py 源码看默认加载预训练编码器microsoft/TRELLIS-image-large/ckpts/ss_enc_conv3d_16l8_fp16与训练配置 configs/vae/ss_vae_conv3d_16l8_fp16.json 对应通过models.from_pretrained加载并.eval().cuda()也可用--enc_model--ckpt加载自己训练的编码器从results/enc_model/config.json读取架构、从ckpts/encoder_ckpt.pt加载权重输入体素点云voxels/sha256.ply转成 64³ 二值稀疏张量后送入编码器sample_posteriorFalse取确定性编码并断言 latent 全为有限值产物为ss_latents/latent_name/sha256.npz保存mean字段--resolution默认 64与体素化分辨率一致。完成后更新元数据python dataset_toolkits/build_metadata.py ObjaverseXL --output_dir datasets/ObjaverseXL_sketchfabStep 8编码 SLatStructured LatentSLat 是 TRELLIS 的核心统一表征用于训练第二阶段的 SLat 生成器python dataset_toolkits/encode_latent.py --output_dir OUTPUT_DIR [--rank RANK --world_size WORLD_SIZE]示例python dataset_toolkits/encode_latent.py --output_dir datasets/ObjaverseXL_sketchfab源码级解析encode_latent.py 的稀疏张量构造从 encode_latent.py 源码看默认加载预训练编码器microsoft/TRELLIS-image-large/ckpts/slat_enc_swin8_B_64l8_fp16对应训练配置 configs/vae/slat_vae_enc_dec_gs_swin8_B_64l8_fp16.json读取 Step 6 的features/dinov2_vitl14_reg/sha256.npz将patchtokens与indices组合成sp.SparseTensorbatch 维补 0坐标取indices送入编码器得到稀疏潜变量产物为latents/feat_model_encoder/sha256.npz保存featsfp32 特征与coordsuint8 坐标去掉 batch 维脚本只处理feature_feat_model True的资产天然衔接 Step 6。完成后更新元数据python dataset_toolkits/build_metadata.py ObjaverseXL --output_dir datasets/ObjaverseXL_sketchfabStep 9渲染图像条件Image Conditions训练图像条件生成器image-to-3D需要带视角增强的图像条件python dataset_toolkits/render_cond.py SUBSET --output_dir OUTPUT_DIR [--num_views NUM_VIEWS] [--rank RANK --world_size WORLD_SIZE]NUM_VIEWS视角数默认24。示例python dataset_toolkits/render_cond.py ObjaverseXL --output_dir datasets/ObjaverseXL_sketchfab源码级解析render_cond.py 的视角增强策略与 Step 4 的固定相机不同render_cond.py 采用随机化增强以提升条件生成模型的泛化能力相机 yaw/pitch 仍由 Hammersley 序列生成但每轮带随机 offsetfov 在 10°–70° 范围内随机采样radius 由公式radius √3/2 / sin(fov/2)反推保证物体完整入镜二者一一对应生成 100 万个候选后随机选取渲染分辨率提升到1024×1024条件图需要更高清晰度不保存网格产物为renders_cond/sha256/transforms.json与图像。完成后更新元数据python dataset_toolkits/build_metadata.py ObjaverseXL --output_dir datasets/ObjaverseXL_sketchfab多节点并行与断点续跑机制数据集规模达 50 万级官方工具包为每个脚本统一设计了--rank/--world_size分布式切分参数download.py、render.py、voxelize.py、extract_feature.py、encode_ss_latent.py、encode_latent.py、render_cond.py、calculate_aesthetic_scores.py均支持。从源码看切分逻辑为标准的均匀分片start len(metadata) * opt.rank // opt.world_size end len(metadata) * (opt.rank 1) // opt.world_size即每个节点只处理自己分到的资产区间各节点把结果写入带rank后缀的 CSV如downloaded_0.csv、rendered_1.csv最终由build_metadata.py统一合并进metadata.csv并归档到merged_records/。此外所有脚本都具备幂等续跑能力处理前先扫描产物目录已存在产物如renders/sha256/transforms.json、voxels/sha256.ply、各.npz文件的资产会被自动跳过并直接登记为完成状态。这意味着中途失败只需重新执行同一命令即可继续无需人工清理。实操注意事项汇总Caption 过滤训练 text-to-3D 模型前务必过滤掉metadata.csv中captions为空的资产训练集约 494,770/500,777 含 caption。美学评分阈值工具包脚本默认不启用--filter_low_aesthetic_score需按官方统计表自行指定ObjaverseXL 用 5.5其余用 4.5以复现 TRELLIS-500K 的构成。Blender 依赖Step 4/9 首次运行会自动下载 Blender 3.0.1 到/tmp并安装系统运行库需要网络与sudo apt权限.blend文件会被直接传给 Blender 打开。Hugging Face 登录ObjaverseXL 等来源的部分数据需要交互式登录或手动下载遵循工具包提示即可。文件名勘误Step 6 的实际脚本名为extract_feature.py文档中写作extract_features.py执行时以仓库实际文件为准。编码器来源Step 7/8 默认加载microsoft/TRELLIS-image-large仓库中的预训练编码器ss_enc_conv3d_16l8_fp16与slat_enc_swin8_B_64l8_fp16也可通过--enc_model/--ckpt切换到自有模型对应配置见 configs/vae/ss_vae_conv3d_16l8_fp16.json 与 configs/vae/slat_vae_enc_dec_gs_swin8_B_64l8_fp16.json。训练衔接完成九步后output_dir下的metadata.csv已包含rendered、voxelized、num_voxels、cond_rendered、各feature_*/ss_latent_*/latent_*状态列可直接作为train.py --data_dir指向的数据集目录用于 TRELLIS 各阶段训练相关训练说明见 README.md。通过以上九步流水线你可以完整复现 TRELLIS-500K 的数据准备过程或基于自有 3D 资产构建满足 TRELLIS 训练要求的同构数据集。赞分享人工智能计算机视觉媒体生成预训练3D渲染【免费下载链接】TRELLISOfficial repo for paper Structured 3D Latents for Scalable and Versatile 3D Generation (CVPR25 Spotlight).项目地址https://gitcode.com/gh_mirrors/trell/TRELLIS点击查看免费下载相关推荐TRELLIS数据集构建TRELLIS-500K完整使用指南TRELLIS数据集构建TRELLIS 500K完整使用指南 TRELLIS 500K是一个包含50万高质量3D资产的大规模数据集专为3D生成任务而设计。该人工智能计算机视觉媒体生成预训练3D渲染如何把一张图片变成视频ComfyUI-WanVideoWrapper 图像转视频实操如何把一张图片变成视频ComfyUI WanVideoWrapper 图像转视频实操手上有一张白底人像或者一张产品图希望它自然地动起来又不想从零搭推理人工智能大模型媒体生成MCP for Beginners用 Java 与 Spring AI 构建基于 SSE 的 MCP 客户端——从工具发现到远程调用实战MCP for Beginners用 Java 与 Spring AI 构建基于 SSE 的 MCP 客户端——从工具发现到远程调用实战导读本指南以 mc教程文档人工智能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

TRELLIS-500K 数据集构建全指南：从元数据加载到稀疏结构/SLat 潜变量编码的完整数据管线

相关推荐

32位ALU的Verilog实现：从补码运算到可综合RTL设计

PyQt5连接MySQL报Driver not loaded的完整解决方案

数字IC验证必备：LEC与Formal Verification调试实战指南

更多资讯

2026 房地产电子沙盘选型完全指南：从 UE5 技术到豪宅项目实战

Django+LSTM舆情分析系统：从零部署到生产实战

FanControl 配置思路：让机箱风扇同时响应 CPU 和显卡负载

MRAM与PIC32组合：工业频繁写入不掉数的SPI存储方案

STM32+MRAM替代SPI Flash：工业频繁写入存储方案详解

基于LLM模型的大学生学业规划智能APP实现研究

今日更新

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？