F3D：轻量3D预览，全格式即开即看

F3D：轻量3D预览，全格式即开即看

【免费下载链接】f3dFast and minimalist 3D viewer.项目地址: https://gitcode.com/GitHub_Trending/f3/f3d

F3D 要解决的问题很具体：任何一个 3D 文件，几秒内看到它的 3D 预览。它由 F3D-APP Foundation 维护，C++ 编写、基于 VTK 渲染，文档列出的格式条目有 55 个，从 glTF、STL 到 STEP、Alembic，旁边还带一个可直接集成的渲染库 libf3d。当你手头有一份几百 MB 的 CAD 文件，只想花 10 秒确认结构对不对的时候，F3D 就是拿来干这个的。打开文件，直接看模型。

🚀 5分钟跑通 F3D：从安装到第一次打开模型

最直接的路径是二进制发行包：到 F3D 官网下载页选对应平台的包，装完终端里直接有f3d命令。纯 Python 脚本场景也可以pip install f3d拿到 Python 绑定。源码编译是备选路径，依赖 CMake ≥ 3.21、C++20 编译器和已装好的 VTK ≥ 9.4.0，仓库自带 CMake preset，cmake --preset=vcpkg可以直接用 vcpkg 拉依赖。

克隆仓库后配置、编译，就两步：

git clone https://gitcode.com/GitHub_Trending/f3/f3d cd f3d cmake -B build # 需要系统已安装 VTK >= 9.4.0 cmake --build build --parallel

这一步只构建f3d可执行文件和 libf3d，各格式插件是可选依赖，没装 Assimp、OCCT 之类的库就只是少了对应格式支持，不影响主程序。编译成功后，第一次运行就一行：

f3d /path/to/model.stl

跑对的标志很明确：弹出一个 3D 窗口，模型自动居中取景，灰底，没有菜单也没有按钮。用f3d --list-readers能确认当前构建带哪些读取器，f3d --version看版本号。文件打开后按 F1 弹出 Cheatsheet，全部热键都列在那张表里。

🔧 能力拆解：四类高频任务

预览任意模型文件

F3D 的格式覆盖面从 VTK 系列、glTF、USD、FBX，一直排到 LAS、PCD 这类激光点云。glTF、OBJ、FBX 这些"full scene"格式会保留文件里的灯光、相机和材质，其余格式走默认场景：灰色基色加 PBR 光照参数。一次传多个文件时，按 ↑ / ↓ 键切换文件组，F5 重载当前文件，加--watch可以让文件在磁盘上被修改后自动重新加载。

批量出图：命令行一次渲染一批

--output指定 PNG 路径后不弹窗口，直接渲染到文件。文件名支持模板变量：{model}是模型名，{frame}是帧号，配 for 循环就能一次出一批预览图：f3d "$f" --output=thumbs/{model}.png --no-background。生成文件管理器缩略图时再加--max-size=256，大文件直接跳过。--output-video则把渲染过程写成视频文件。

把 F3D 嵌进你的应用

仓库里的 libf3d 是 C++17 API，另有 C、Python、Java、JavaScript 四套绑定，格式全部以插件形式组织，用--load-plugins按需加载。examples/libf3d/ 目录里每个语言都有可直接编译的示例，最常用的是离屏渲染路径：Engine.create(True)建引擎，scene.add加模型，window.render_to_image拿图像，全程不弹窗。

按自己的习惯配置

命令行能控的选项几乎都能写进 JSON 配置文件，match字段按文件名正则给不同格式分配不同默认值，bindings字段把自定义按键绑到命令上。--list-bindings查看当前绑定，--config=xxx换一份配置。

这是 F3D 内置的默认环境天空图，PBR 光照用它计算环境光，也可以换一张自己的，命令是--hdri-file。

⚙️ 工作流嵌入：放进你的日常

CI 里批量出缩略图。背景：CI 产物页要给每个模型挂一张预览图。操作：循环执行f3d "$f" --output=thumbs/{model}.png --no-background --rendering-backend=osmesa。结果：透明背景 PNG 直接上页面，沙箱里没有 X 环境也能跑。

Python 平台生成资产缩略图。背景：数据平台要给每个资产出一张 512px 缩略图。操作：参考官方示例 examples/libf3d/python/offscreen-thumbnail/ 里的 offscreen_thumbnail.py，十几行配置关 UI、调光照、开 SSAA。结果：render_to_image拿图落盘，窗口从头到尾不出现。

远程协作分享同一视角。背景：你和同事各看各的角度，讨论对不上。操作：你这边f3d model.glb --save-statefile=view.json把状态文件发过去，对方f3d model.glb --load-statefile=view.json打开。结果：相机、选项、文件组完全一致。

🔍 F3D 配置项速查与高频坑

最常调的五个选项，格式统一为"配置项 → 默认值 → 推荐值 → 理由"：

• --axis（角落坐标轴三轴架）→ 关 → 开 → 转模型时知道朝向
• --grid（地面网格）→ 关 → 开 → 给模型一个距离和位置参照
• --edges（面边线）→ 关 → 看 STL / CAD 时开 → 轮廓细节清晰
• --hdri-ambient（HDRI 环境光）→ 关 → 开 → 材质光照更真实
• --coloring-mode（着色模式）→ material → 看科学数据时改 scivis → 场量按数值着色

Linux 上配置文件放在~/.config/f3d/config.json（即${XDG_CONFIG_HOME}/f3d/config.json），命令行选项永远覆盖配置文件。下面第一块对所有文件生效，第二块只命中 STEP 文件，第三块是自定义按键，行尾 # 是讲解注释，真实 JSON 文件里不含 #：

[ { "options": { "axis": true, "grid": true, "edges": true, "hdri-ambient": true } }, # 全局默认 { "match": ".*\\.(step|stp)$", # 按文件名正则匹配 "options": { "coloring-mode": "material" } }, { "bindings": { "O": "set_camera isometric", "Any+3": "roll_camera -90" } } # 按键 → 命令 ]

⚠️ 高频坑

• 高斯泼溅 .ply 显示不对：.ply 是通用格式，F3D 不会默认按 3DGS 处理，补上--point-sprites-size=1 --point-sprites=gaussian --coloring-mode=direct -k，或写进配置的 match 块。
• STEP 文件不认--color：OCCT 插件默认走标量着色，追加--coloring-mode=material颜色才生效。
• 无头环境跑不起来：文件管理器生成缩略图的沙箱场景用--rendering-backend=osmesa（或 egl）；Windows 下命令行执行--version等无窗口命令不显示输出，换f3d-console.exe。

📬 适合谁，下一步去哪

适合需要快速核验 3D 模型结构、不想打开重型 DCC 软件的用户。适合要在脚本或 CI 里批量生成预览图的用户。适合想在产品里嵌入一个 3D 渲染组件的开发者。

下一步：doc/user/目录从 Quickstart 开始读，选项、配置、交互都有专页；集成 libf3d 看doc/libf3d/01-OVERVIEW.md；构建细节看doc/dev/05-BUILD.md。生态侧，VTK 是 F3D 的渲染底座，格式读取能力基本都来自 VTK 的 IO 模块和上面那些插件。

下次那个几百 MB 的 CAD 文件再出现在收件箱里，你只需要一行：f3d，打开，看一眼。

【免费下载链接】f3dFast and minimalist 3D viewer.项目地址: https://gitcode.com/GitHub_Trending/f3/f3d