2026/9/18 18:50:42
FEATURED · 精选文章 
F3D 架构解析从 Application 到 libf3d、插件与语言绑定的模块化设计【免费下载链接】f3dFast and minimalist 3D viewer.项目地址: https://gitcode.com/GitHub_Trending/f3/f3dF3D 是一款快速且极简的 3D 查看器其代码库被清晰地划分为多个相互协作的模块application应用层、librarylibf3d 核心库、plugins格式读取插件、vtkextVTK 扩展层以及 C/Python/Java/WebAssembly 等多语言绑定与 Windows 缩略图扩展。本文基于 doc/dev/08-ARCHITECTURE.md 展开结合仓库源码系统讲解各模块的职责边界、调用关系、核心类与构建安装细节帮助读者理解 F3D 的模块化架构并掌握在此基础上进行二次开发编写插件、使用语言绑定的路径。模块全景目录即架构F3D 的架构理念是目录结构直接反映架构仓库根目录下的每一个顶层目录都对应一个独立的功能单元彼此通过明确的依赖关系协作目录职责applicationF3D 应用程序本体承载全部应用逻辑cmakeCMake 宏与函数供构建系统复用doc项目文档exampleslibf3d 与插件框架在 C、C、Python、Java、JavaScript 中的示例external直接内嵌于代码库中的第三方依赖clip、cxxopts、dmon、imgui、nlohmann_json、tinyfiledialogslibrarylibf3d 本身plugins各类格式读取插件resources非代码、非文档资源图标、配置等testing与测试相关的全部资源测试本身不在此目录vtkext对 VTK 的扩展及相应测试cC 语言绑定及测试pythonPython 绑定及测试javaJava 绑定及测试webassemblyWebAssembly/JavaScript 绑定及测试winshellextWindows Shell 扩展为 Windows 资源管理器提供缩略图模块间的调用关系原文档给出了一张清晰的模块交互图示意如下┌────────────────┐ ┌───────────────┐ │ │ │ │ │ application │◄──uses─┤ winshellext │ │ │ │ │ ┌──────────┐ └───────┬────────┘ └───────────────┘ │ │ │ ┌────┤ python │ │ │ │ │ depends on │ └──────────┘ │ │ ┌──────────┐ │ │ │ │ │ ├────┤ java │ │ ┌───────────┐ │ │ │ └────────►│ │ │ └──────────┘ │ library │◄─wraps─┤ ┌──────────┐ ┌───loads──────┤ │ │ │ │ │ └─────┬─────┘ ├────┤ wasm │ ▼ │ │ │ │ ┌───────────┐ │ │ └──────────┘ │ │ depends on │ ┌──────────┐ │ plugins │ │ │ │ │ │ │ ▼ └────┤ c │ └─────┬─────┘ ┌──────────────────┐ │ │ │ │ vtkext │ └──────────┘ │ ├────────┬─────────┤ depends─on──►│ public │ private │ └────────┴─────────┘从图中可以提炼出四条核心依赖链application 依赖 library应用层不直接实现渲染与文件读取而是调用 libf3d 完成全部核心功能library 加载 pluginslibf3d 通过动态/静态加载插件获得各文件格式的读取能力library 与 plugins 都依赖 vtkextvtkext 是对 VTK 的功能扩展其中public部分随plugin_sdk一起安装供包括外部插件使用五种语言绑定C、Python、Java、WASM都是对 library 的包装wraps不重复实现核心逻辑。vtkext两个 VTK 模块一个对外一个对内vtkext目录下包含两个 VTK 模块其构建入口见 vtkext/CMakeLists.txt仅add_subdirectory(public)与add_subdirectory(private)两行分别服务于不同受众。public 模块插件开发者的工具箱vtkext/public是一个 VTK 模块其中的类与工具会作为plugin_sdk的一部分被安装可供包括外部插件在内的所有插件使用。核心类如下vtkF3DImportervtkext/public/module/vtkF3DImporter.h专门为插件开发者设计的通用 importer 基类插件中的自定义 importer 可以继承它。其价值在于屏蔽了不同 VTK 版本之间的 API 差异——从源码头文件可以看到大量VTK_VERSION_NUMBER VTK_VERSION_CHECK(...)的条件编译例如对vtkResourceStream、GetTemporalInformation等接口在不同 VTK 版本下的差异做了适配开发者只需针对当前版本实现必要的方法即可。vtkF3DGLTFImporter自定义 glTF importer支持 armature骨架适合开发基于 glTF 扩展的插件。vtkF3DFaceVaryingPointDispatcher将点数据转换为 F3D 可显示的面变化face-varying数据的 VTK 过滤器被 usd 插件使用。vtkF3DBitonicSort在 GPU 上执行 Bitonic Sort 算法的 VTK 类用于半透明点精灵point sprites渲染算法。F3DUtils公共工具函数集合。private 模块libf3d 内部能力的基础vtkext/private是另一个 VTK 模块包含大量被 libf3d 用来实现 F3D 全部特性渲染、交互、UI的类与工具仅在 libf3d 内部使用。最值得关注的是vtkF3DRenderervtkext/private/module/vtkF3DRenderer.h它负责向 3D 场景中添加各类 actor。从头文件可以看到它管理着非常广泛的功能面通用 actorShowAxis坐标轴、ShowGrid网格、ShowAxesGrid、ShowEdge边线、ShowTimer帧率计时、ShowMetaData元数据、ShowFilename、ShowCheatSheet快捷键速查表、ShowConsole、ShowDropZone、ShowNotification、ShowBindings等渲染管线render passesSetUseRaytracing光线追踪、SetUseSSAOPass环境光遮蔽、SetAntiAliasingModeFXAA/SSAA/TAA 抗锯齿、SetUseToneMappingPass色调映射、SetUseBlurBackground背景虚化、SetDisplayDepth深度显示等材质与着色粗糙度、金属度、折射率、表面颜色、自发光因子、各种纹理MatCap/BaseColor/Material/Emissive/Normal、final shader 等科学可视化SetEnableColoring、SetArrayNameForColoring、SetColormap、SetOpacityMap、SetScalarBarRange以及CycleFieldForColoring/CycleArrayForColoring/CycleComponentForColoring等循环切换着色数组的方法对应交互式切换着色的功能HDRI 环境ConfigureHDRI、ConfigureHDRITexture、ConfigureHDRILUT、ConfigureHDRISphericalHarmonics、ConfigureHDRISpecular等一整套 HDRI 处理流程点云渲染SetPointSpritesTypeSphere/Gaussian/Circle 等、SetUsePointSprites、SetUseVolume、SetUseNormalGlyphs等。private模块中还有vtkF3DMetaImporter多文件/多 importer 的统一管理、vtkF3DGenericImporter、vtkF3DInteractorStyle交互风格、vtkF3DImguiActor基于 ImGui 的界面、vtkF3DObjectFactory等类共同构成 F3D 渲染与交互的底层支撑。各自的测试目录两个模块各自在Testing目录下包含测试。public 模块的测试位于 vtkext/public/module/Testing如TestF3DBitonicSort.cxxprivate 模块的测试位于 vtkext/private/module/Testing如TestF3DRendererWithColoring.cxx、TestF3DGenericImporter.cxx、TestF3DEXRReader.cxx、TestF3DInteractorEventRecorder.cxx等这些测试验证了 vtkext 层的各项功能详见 doc/dev/06-TESTING.md 中关于 vtkext 层的说明。plugins让文件格式真正可选plugins目录包含 F3D 官方包中默认提供的 libf3d 插件。每个插件对应一个特定依赖并以该依赖命名alembic、assimp、draco、hdf、native、occt、pdal、usd、vdb、webifc等。插件的核心价值在于没有插件F3D 和 libf3d 打不开任何文件——文件读取能力完全由插件提供。由于插件可以被静态加载或动态加载因此每个插件背后的依赖Assimp、Open CASCADE、USD、PDAL 等都可以真正做到按需可选不需要某种格式支持时可以不编译对应插件从而保持 F3D 的轻量。以 plugins/native 为例它对应 VTK 原生支持的格式其 module 目录中包含针对 VTK 各类格式的读取实现与.inl内联文件vtk.inl、obj.inl、stl.inl、ply.inl、glb.inl、3ds.inl、mdl.inl、xml.inl、image.inl.in等并配套f3d-vtk-formats.xml、f3d-image-formats.xml、f3d-3d-formats.xml三个格式注册文件以及configs目录下的 JSON 配置。关于插件机制本身如何用f3d_plugin_declare_reader声明 reader、如何用f3d_plugin_build构建插件、生成的 JSON 元数据格式、如何通过--load-plugins或f3d::engine::loadPlugin加载等详见 doc/libf3d/05-PLUGINS.md插件如何被 libf3d 在启动时装载见 library/src/factory.cxx.in 的工厂机制。librarylibf3d——小而公开的 API 面library目录是 libf3d 本体一个 C 库公开 API 面非常有限而私有实现相对庞大这与 F3D 极简的定位一致。其构建定义见 library/CMakeLists.txt。公有/私有的类拆分约定libf3d 的大多数类都被拆分成两部分公有部分主要包含公开 API头文件位于 library/publiccamera.h、engine.h、image.h、interactor.h、log.h、mesh_view.h、options.h.in、scene.h、types.h、utils.h、window.h等全部会被安装私有部分以_impl后缀命名如camera_impl.h、interactor_impl.h、scene_impl.h、window_impl.h、options_tools.h位于 library/private实现公有 API并包含用于类间通信的隐藏方法——尤其是涉及 VTK 符号的部分例如camera_impl.h内部持有vtkCamerawindow_impl.h内部持有vtkRenderWindow这些 VTK 类型不出现在公有头文件中从而对外隐藏了 VTK 依赖源码文件位于 library/src包含所有类公有与私有的实现如engine.cxx、scene_impl.cxx、interactor.cxx、interactor_impl.cxx、window_impl.cxx、camera_impl.cxx、animationManager.cxx、statefile.cxx、log.cxx、utils.cxx、types.cxx、options.cxx等。从 library/CMakeLists.txt 可以看出 libf3d 的构建特性C20 标准、输出名f3d、默认启用 SOVERSION、通过generate_export_header生成导出宏、通过vtk_module_autoinit自动初始化 VTK 模块并链接VTK::CommonSystem、VTK::IOImage、VTK::InteractionWidgets、f3d::vtkext、f3d::vtkextPrivate等模块启用光线追踪时还会链接VTK::RenderingRayTracing。options.json一份 JSON 生成全部选项代码libf3d 的另一个重要设计是options.jsonlibrary/options.json所有选项options的代码都由这份 JSON 文件生成。构建时通过f3d_generate_optionsCMake 宏以options.json为输入、public/options.h.in与private/options_generated.h.in为模板生成最终的options.h与options_generated.h。这保证了选项定义、文档、CLI 解析和默认值之间的单一事实来源。options.json中的每个选项都带有类型与默认值例如{ scene: { up_direction: { type: direction, default_value: 0,1,0 }, animation: { autoplay: { type: bool, default_value: false }, indices: { type: int_vector, default_value: 0 }, speed_factor: { type: ratio, default_value: 1.0, domain: { style: range, min: 0.0, max: 2.0, increment: 0.1 } } } } }所有选项的完整说明见 doc/libf3d/03-OPTIONS.md。独立的 testing 目录library/testing目录包含 libf3d 的单元测试与功能测试如TestSDKEngine.cxx、TestSDKScene.cxx、TestSDKOptions.cxx、TestSDKStatefile.cxx、TestSDKTriggerInteractions.cxx等详见 doc/dev/06-TESTING.md 中关于 library 层的说明。使用 libf3d 的最小示例libf3d 的公开 API 极小且易学。渲染一个文件并开始交互只需要几行代码#include f3d/engine.h #include f3d/interactor.h #include f3d/scene.h // 加载 VTK 原生 reader 插件 f3d::engine::autoloadPlugins(); // 创建 f3d::engine f3d::engine eng f3d::engine::create(); // 将文件加入场景 eng.getScene().add(path/to/file.ext); // 开始渲染与交互 eng.getInteractor().start();也支持一次性加载多个文件、从内存 buffer 创建网格、通过mesh_view零拷贝展示内存数据以及离屏渲染到图片#include f3d/engine.h #include f3d/image.h #include f3d/scene.h #include f3d/window.h // 创建离屏 engine f3d::engine eng f3d::engine::create(true); // 加载几何体 eng.getScene().add(path/to/file.ext); // 设置窗口尺寸并渲染为图片 f3d::image img eng.getWindow().setSize(300, 300).renderToImage(); // 保存图片 img.save(/path/to/img.png);更完整的用法示例见 examples/libf3d 下的 cpp、c、python、java 等子目录。通过 CMake 使用 libf3d在 CMake 项目中链接 libf3d 非常简单需安装sdk组件例如cmake --install build_dir --component sdk且以共享库方式构建为佳find_package(f3d REQUIRED COMPONENTS library) target_link_libraries(your_target f3d::libf3d)find_package(f3d)支持三种组件组件提供的 target/能力applicationf3d::f3dtargetlibraryf3d::libf3dtarget 与头文件目录plugin_sdk创建插件的 CMake 宏、f3d::vtkexttarget 与头文件目录applicationF3D 应用本体application目录包含 F3D 应用程序本身的代码。它当然依赖 libf3d 来实现所有应用逻辑自身主要负责命令行解析、文件组管理、状态文件statefile、事件循环等顶层流程。F3DStarter应用逻辑的中枢F3DStarterapplication/F3DStarter.h是应用层最重要的类承载了大部分顶层逻辑Start(int argc, char** argv)解析选项并配置f3d::scene是应用的入口流程AddFile/LoadFileGroup/LoadRelativeFileGroup文件组管理多文件模式、相对索引切换文件组SaveScreenshot/SaveStatefile/LoadStatefile截图输出与状态文件statefile的保存/恢复——状态文件可序列化当前 engine 状态选项、文件、相机、窗口尺寸并支持通过-读写标准输入输出SaveStatefileToClipboard/LoadStatefileFromClipboard将状态文件存入/读取系统剪贴板需要启用 clip 模块构建EventLoop内部事件循环处理渲染与文件重载等事件。应用层还有F3DConfigFileTools配置文件读取、F3DSystemTools系统相关、F3DPluginsTools插件路径/加载管理、F3DColorMapTools颜色映射文件等工具类入口在 application/main.cxx。F3DOptionsTools命令行选项的翻译官F3DOptionsToolsapplication/F3DOptionsTools.h处理大部分命令行选项逻辑。其核心设计是把 CLI 选项名映射到 libf3d 选项名DefaultAppOptions应用专属 CLI 选项及其字符串默认值input、output、no-render、rendering-backend、load-plugins、watch、multi-file-mode、resolution、screenshot-filename、reference、interaction-test-record等。这些选项不翻译成 libf3d 选项而是直接驱动应用层代码LibOptionsNamesCLI 选项到 libf3d 选项名的映射表。例如--ambient-occlusion→render.effect.ambient_occlusion、--anti-aliasing→render.effect.antialiasing.mode、--coloring-array→model.scivis.array_name、--hdri-file→render.hdri.file、--raytracing→render.raytracing.enable、--up→scene.up_direction等ParseCLIOptions从 argc/argv 解析出OptionsDictGetClosestOption在选项名拼写错误时通过最小编辑距离levenshtein给出最接近的选项建议这也是 F3D 命令行did you mean提示的实现基础。应用层测试application/testing目录包含 F3D 应用层的全部应用测试以及大量 libf3d 的功能测试如tests.features.cmake、tests.interaction.cmake、tests.screenshot.cmake、tests.watch.cmake等按功能组织的测试集详见 doc/dev/06-TESTING.md 中关于 application 层的说明。语言绑定与 Windows 缩略图扩展四种语言绑定同一套 libf3d 的包装C、Python、Java、WebAssembly 四种绑定都是对 libf3d 的包装wrap不包含任何核心渲染或读取逻辑C 绑定c基于F3D_BINDINGS_CCMake 选项生成使用方式示例见 doc/libf3d/04-LANGUAGE_BINDINGS.md例如f3d_engine_autoload_plugins()、f3d_engine_create(0)、f3d_scene_add(scene, file.vtu)、f3d_interactor_start(interactor, 1.0/30.0)CMake 侧通过find_package(f3d REQUIRED COMPONENTS c_api)与f3d::c_api链接其实现位于 c/*_c_api.cxx 等文件Python 绑定python基于 pybind11 实现F3DPythonBindings.cxx并提供py.typed与generate_stubs.py类型桩生成Java 绑定java通过 JNIF3DJavaBindings.h及F3D*Bindings.cxx包装配套Camera.java、Engine.java、Scene.java等 Java 类WebAssembly 绑定webassembly通过F3DEmscriptenBindings.cxx提供 JavaScript 调用能力。winshellextWindows 文件管理器缩略图winshellext 是 Windows Shell 扩展F3DShellExtension.cxx、F3DThumbnailProvider.cxx等为 Windows 资源管理器提供 3D 文件缩略图预览在安装 F3D 后可直接在文件管理器中看到模型缩略图。它与 application 的关系是使用uses关系——缩略图渲染复用 F3D 的应用能力相关说明见 doc/user/12-DESKTOP_INTEGRATION.md。F3D 生态中的其他仓库虽然几乎全部代码都收拢在 f3d-app/f3d 这一个仓库中但 f3d-app 组织下的其他仓库负责 F3D 生态中的特定任务f3d-superbuild负责打包与发布页二进制产物的生成f3d-website存放由本项目文档生成的官网与 Web 查看器CI 辅助 Actionssccache-setup、lfs-data-cache、install-mesa-windows 等供 CI 使用f3d-docker-images用于生成 CI 所需的 Docker 镜像。对于本项目而言理解 F3D 架构最直接的入口仍是本仓库应用逻辑在application核心库在library格式支持在pluginsVTK 扩展在vtkext绑定在c/python/java/webassembly。掌握这条分层链路后无论是为 F3D 贡献新的文件格式插件还是在自己的项目中集成 libf3d都能快速定位到正确的代码位置。【免费下载链接】f3dFast and minimalist 3D viewer.项目地址: https://gitcode.com/GitHub_Trending/f3/f3d创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
F3D 架构解析：从 Application 到 libf3d、插件与语言绑定的模块化设计
F3D 架构解析从 Application 到 libf3d、插件与语言绑定的模块化设计【免费下载链接】f3dFast and minimalist 3D viewer.项目地址: https://gitcode.com/GitHub_Trending/f3/f3dF3D 是一款快速且极简的 3D 查看器其代码库被清晰地划分为多个相互协作的模块application应用层、librarylibf3d 核心库、plugins格式读取插件、vtkextVTK 扩展层以及 C/Python/Java/WebAssembly 等多语言绑定与 Windows 缩略图扩展。本文基于 doc/dev/08-ARCHITECTURE.md 展开结合仓库源码系统讲解各模块的职责边界、调用关系、核心类与构建安装细节帮助读者理解 F3D 的模块化架构并掌握在此基础上进行二次开发编写插件、使用语言绑定的路径。模块全景目录即架构F3D 的架构理念是目录结构直接反映架构仓库根目录下的每一个顶层目录都对应一个独立的功能单元彼此通过明确的依赖关系协作目录职责applicationF3D 应用程序本体承载全部应用逻辑cmakeCMake 宏与函数供构建系统复用doc项目文档exampleslibf3d 与插件框架在 C、C、Python、Java、JavaScript 中的示例external直接内嵌于代码库中的第三方依赖clip、cxxopts、dmon、imgui、nlohmann_json、tinyfiledialogslibrarylibf3d 本身plugins各类格式读取插件resources非代码、非文档资源图标、配置等testing与测试相关的全部资源测试本身不在此目录vtkext对 VTK 的扩展及相应测试cC 语言绑定及测试pythonPython 绑定及测试javaJava 绑定及测试webassemblyWebAssembly/JavaScript 绑定及测试winshellextWindows Shell 扩展为 Windows 资源管理器提供缩略图模块间的调用关系原文档给出了一张清晰的模块交互图示意如下┌────────────────┐ ┌───────────────┐ │ │ │ │ │ application │◄──uses─┤ winshellext │ │ │ │ │ ┌──────────┐ └───────┬────────┘ └───────────────┘ │ │ │ ┌────┤ python │ │ │ │ │ depends on │ └──────────┘ │ │ ┌──────────┐ │ │ │ │ │ ├────┤ java │ │ ┌───────────┐ │ │ │ └────────►│ │ │ └──────────┘ │ library │◄─wraps─┤ ┌──────────┐ ┌───loads──────┤ │ │ │ │ │ └─────┬─────┘ ├────┤ wasm │ ▼ │ │ │ │ ┌───────────┐ │ │ └──────────┘ │ │ depends on │ ┌──────────┐ │ plugins │ │ │ │ │ │ │ ▼ └────┤ c │ └─────┬─────┘ ┌──────────────────┐ │ │ │ │ vtkext │ └──────────┘ │ ├────────┬─────────┤ depends─on──►│ public │ private │ └────────┴─────────┘从图中可以提炼出四条核心依赖链application 依赖 library应用层不直接实现渲染与文件读取而是调用 libf3d 完成全部核心功能library 加载 pluginslibf3d 通过动态/静态加载插件获得各文件格式的读取能力library 与 plugins 都依赖 vtkextvtkext 是对 VTK 的功能扩展其中public部分随plugin_sdk一起安装供包括外部插件使用五种语言绑定C、Python、Java、WASM都是对 library 的包装wraps不重复实现核心逻辑。vtkext两个 VTK 模块一个对外一个对内vtkext目录下包含两个 VTK 模块其构建入口见 vtkext/CMakeLists.txt仅add_subdirectory(public)与add_subdirectory(private)两行分别服务于不同受众。public 模块插件开发者的工具箱vtkext/public是一个 VTK 模块其中的类与工具会作为plugin_sdk的一部分被安装可供包括外部插件在内的所有插件使用。核心类如下vtkF3DImportervtkext/public/module/vtkF3DImporter.h专门为插件开发者设计的通用 importer 基类插件中的自定义 importer 可以继承它。其价值在于屏蔽了不同 VTK 版本之间的 API 差异——从源码头文件可以看到大量VTK_VERSION_NUMBER VTK_VERSION_CHECK(...)的条件编译例如对vtkResourceStream、GetTemporalInformation等接口在不同 VTK 版本下的差异做了适配开发者只需针对当前版本实现必要的方法即可。vtkF3DGLTFImporter自定义 glTF importer支持 armature骨架适合开发基于 glTF 扩展的插件。vtkF3DFaceVaryingPointDispatcher将点数据转换为 F3D 可显示的面变化face-varying数据的 VTK 过滤器被 usd 插件使用。vtkF3DBitonicSort在 GPU 上执行 Bitonic Sort 算法的 VTK 类用于半透明点精灵point sprites渲染算法。F3DUtils公共工具函数集合。private 模块libf3d 内部能力的基础vtkext/private是另一个 VTK 模块包含大量被 libf3d 用来实现 F3D 全部特性渲染、交互、UI的类与工具仅在 libf3d 内部使用。最值得关注的是vtkF3DRenderervtkext/private/module/vtkF3DRenderer.h它负责向 3D 场景中添加各类 actor。从头文件可以看到它管理着非常广泛的功能面通用 actorShowAxis坐标轴、ShowGrid网格、ShowAxesGrid、ShowEdge边线、ShowTimer帧率计时、ShowMetaData元数据、ShowFilename、ShowCheatSheet快捷键速查表、ShowConsole、ShowDropZone、ShowNotification、ShowBindings等渲染管线render passesSetUseRaytracing光线追踪、SetUseSSAOPass环境光遮蔽、SetAntiAliasingModeFXAA/SSAA/TAA 抗锯齿、SetUseToneMappingPass色调映射、SetUseBlurBackground背景虚化、SetDisplayDepth深度显示等材质与着色粗糙度、金属度、折射率、表面颜色、自发光因子、各种纹理MatCap/BaseColor/Material/Emissive/Normal、final shader 等科学可视化SetEnableColoring、SetArrayNameForColoring、SetColormap、SetOpacityMap、SetScalarBarRange以及CycleFieldForColoring/CycleArrayForColoring/CycleComponentForColoring等循环切换着色数组的方法对应交互式切换着色的功能HDRI 环境ConfigureHDRI、ConfigureHDRITexture、ConfigureHDRILUT、ConfigureHDRISphericalHarmonics、ConfigureHDRISpecular等一整套 HDRI 处理流程点云渲染SetPointSpritesTypeSphere/Gaussian/Circle 等、SetUsePointSprites、SetUseVolume、SetUseNormalGlyphs等。private模块中还有vtkF3DMetaImporter多文件/多 importer 的统一管理、vtkF3DGenericImporter、vtkF3DInteractorStyle交互风格、vtkF3DImguiActor基于 ImGui 的界面、vtkF3DObjectFactory等类共同构成 F3D 渲染与交互的底层支撑。各自的测试目录两个模块各自在Testing目录下包含测试。public 模块的测试位于 vtkext/public/module/Testing如TestF3DBitonicSort.cxxprivate 模块的测试位于 vtkext/private/module/Testing如TestF3DRendererWithColoring.cxx、TestF3DGenericImporter.cxx、TestF3DEXRReader.cxx、TestF3DInteractorEventRecorder.cxx等这些测试验证了 vtkext 层的各项功能详见 doc/dev/06-TESTING.md 中关于 vtkext 层的说明。plugins让文件格式真正可选plugins目录包含 F3D 官方包中默认提供的 libf3d 插件。每个插件对应一个特定依赖并以该依赖命名alembic、assimp、draco、hdf、native、occt、pdal、usd、vdb、webifc等。插件的核心价值在于没有插件F3D 和 libf3d 打不开任何文件——文件读取能力完全由插件提供。由于插件可以被静态加载或动态加载因此每个插件背后的依赖Assimp、Open CASCADE、USD、PDAL 等都可以真正做到按需可选不需要某种格式支持时可以不编译对应插件从而保持 F3D 的轻量。以 plugins/native 为例它对应 VTK 原生支持的格式其 module 目录中包含针对 VTK 各类格式的读取实现与.inl内联文件vtk.inl、obj.inl、stl.inl、ply.inl、glb.inl、3ds.inl、mdl.inl、xml.inl、image.inl.in等并配套f3d-vtk-formats.xml、f3d-image-formats.xml、f3d-3d-formats.xml三个格式注册文件以及configs目录下的 JSON 配置。关于插件机制本身如何用f3d_plugin_declare_reader声明 reader、如何用f3d_plugin_build构建插件、生成的 JSON 元数据格式、如何通过--load-plugins或f3d::engine::loadPlugin加载等详见 doc/libf3d/05-PLUGINS.md插件如何被 libf3d 在启动时装载见 library/src/factory.cxx.in 的工厂机制。librarylibf3d——小而公开的 API 面library目录是 libf3d 本体一个 C 库公开 API 面非常有限而私有实现相对庞大这与 F3D 极简的定位一致。其构建定义见 library/CMakeLists.txt。公有/私有的类拆分约定libf3d 的大多数类都被拆分成两部分公有部分主要包含公开 API头文件位于 library/publiccamera.h、engine.h、image.h、interactor.h、log.h、mesh_view.h、options.h.in、scene.h、types.h、utils.h、window.h等全部会被安装私有部分以_impl后缀命名如camera_impl.h、interactor_impl.h、scene_impl.h、window_impl.h、options_tools.h位于 library/private实现公有 API并包含用于类间通信的隐藏方法——尤其是涉及 VTK 符号的部分例如camera_impl.h内部持有vtkCamerawindow_impl.h内部持有vtkRenderWindow这些 VTK 类型不出现在公有头文件中从而对外隐藏了 VTK 依赖源码文件位于 library/src包含所有类公有与私有的实现如engine.cxx、scene_impl.cxx、interactor.cxx、interactor_impl.cxx、window_impl.cxx、camera_impl.cxx、animationManager.cxx、statefile.cxx、log.cxx、utils.cxx、types.cxx、options.cxx等。从 library/CMakeLists.txt 可以看出 libf3d 的构建特性C20 标准、输出名f3d、默认启用 SOVERSION、通过generate_export_header生成导出宏、通过vtk_module_autoinit自动初始化 VTK 模块并链接VTK::CommonSystem、VTK::IOImage、VTK::InteractionWidgets、f3d::vtkext、f3d::vtkextPrivate等模块启用光线追踪时还会链接VTK::RenderingRayTracing。options.json一份 JSON 生成全部选项代码libf3d 的另一个重要设计是options.jsonlibrary/options.json所有选项options的代码都由这份 JSON 文件生成。构建时通过f3d_generate_optionsCMake 宏以options.json为输入、public/options.h.in与private/options_generated.h.in为模板生成最终的options.h与options_generated.h。这保证了选项定义、文档、CLI 解析和默认值之间的单一事实来源。options.json中的每个选项都带有类型与默认值例如{ scene: { up_direction: { type: direction, default_value: 0,1,0 }, animation: { autoplay: { type: bool, default_value: false }, indices: { type: int_vector, default_value: 0 }, speed_factor: { type: ratio, default_value: 1.0, domain: { style: range, min: 0.0, max: 2.0, increment: 0.1 } } } } }所有选项的完整说明见 doc/libf3d/03-OPTIONS.md。独立的 testing 目录library/testing目录包含 libf3d 的单元测试与功能测试如TestSDKEngine.cxx、TestSDKScene.cxx、TestSDKOptions.cxx、TestSDKStatefile.cxx、TestSDKTriggerInteractions.cxx等详见 doc/dev/06-TESTING.md 中关于 library 层的说明。使用 libf3d 的最小示例libf3d 的公开 API 极小且易学。渲染一个文件并开始交互只需要几行代码#include f3d/engine.h #include f3d/interactor.h #include f3d/scene.h // 加载 VTK 原生 reader 插件 f3d::engine::autoloadPlugins(); // 创建 f3d::engine f3d::engine eng f3d::engine::create(); // 将文件加入场景 eng.getScene().add(path/to/file.ext); // 开始渲染与交互 eng.getInteractor().start();也支持一次性加载多个文件、从内存 buffer 创建网格、通过mesh_view零拷贝展示内存数据以及离屏渲染到图片#include f3d/engine.h #include f3d/image.h #include f3d/scene.h #include f3d/window.h // 创建离屏 engine f3d::engine eng f3d::engine::create(true); // 加载几何体 eng.getScene().add(path/to/file.ext); // 设置窗口尺寸并渲染为图片 f3d::image img eng.getWindow().setSize(300, 300).renderToImage(); // 保存图片 img.save(/path/to/img.png);更完整的用法示例见 examples/libf3d 下的 cpp、c、python、java 等子目录。通过 CMake 使用 libf3d在 CMake 项目中链接 libf3d 非常简单需安装sdk组件例如cmake --install build_dir --component sdk且以共享库方式构建为佳find_package(f3d REQUIRED COMPONENTS library) target_link_libraries(your_target f3d::libf3d)find_package(f3d)支持三种组件组件提供的 target/能力applicationf3d::f3dtargetlibraryf3d::libf3dtarget 与头文件目录plugin_sdk创建插件的 CMake 宏、f3d::vtkexttarget 与头文件目录applicationF3D 应用本体application目录包含 F3D 应用程序本身的代码。它当然依赖 libf3d 来实现所有应用逻辑自身主要负责命令行解析、文件组管理、状态文件statefile、事件循环等顶层流程。F3DStarter应用逻辑的中枢F3DStarterapplication/F3DStarter.h是应用层最重要的类承载了大部分顶层逻辑Start(int argc, char** argv)解析选项并配置f3d::scene是应用的入口流程AddFile/LoadFileGroup/LoadRelativeFileGroup文件组管理多文件模式、相对索引切换文件组SaveScreenshot/SaveStatefile/LoadStatefile截图输出与状态文件statefile的保存/恢复——状态文件可序列化当前 engine 状态选项、文件、相机、窗口尺寸并支持通过-读写标准输入输出SaveStatefileToClipboard/LoadStatefileFromClipboard将状态文件存入/读取系统剪贴板需要启用 clip 模块构建EventLoop内部事件循环处理渲染与文件重载等事件。应用层还有F3DConfigFileTools配置文件读取、F3DSystemTools系统相关、F3DPluginsTools插件路径/加载管理、F3DColorMapTools颜色映射文件等工具类入口在 application/main.cxx。F3DOptionsTools命令行选项的翻译官F3DOptionsToolsapplication/F3DOptionsTools.h处理大部分命令行选项逻辑。其核心设计是把 CLI 选项名映射到 libf3d 选项名DefaultAppOptions应用专属 CLI 选项及其字符串默认值input、output、no-render、rendering-backend、load-plugins、watch、multi-file-mode、resolution、screenshot-filename、reference、interaction-test-record等。这些选项不翻译成 libf3d 选项而是直接驱动应用层代码LibOptionsNamesCLI 选项到 libf3d 选项名的映射表。例如--ambient-occlusion→render.effect.ambient_occlusion、--anti-aliasing→render.effect.antialiasing.mode、--coloring-array→model.scivis.array_name、--hdri-file→render.hdri.file、--raytracing→render.raytracing.enable、--up→scene.up_direction等ParseCLIOptions从 argc/argv 解析出OptionsDictGetClosestOption在选项名拼写错误时通过最小编辑距离levenshtein给出最接近的选项建议这也是 F3D 命令行did you mean提示的实现基础。应用层测试application/testing目录包含 F3D 应用层的全部应用测试以及大量 libf3d 的功能测试如tests.features.cmake、tests.interaction.cmake、tests.screenshot.cmake、tests.watch.cmake等按功能组织的测试集详见 doc/dev/06-TESTING.md 中关于 application 层的说明。语言绑定与 Windows 缩略图扩展四种语言绑定同一套 libf3d 的包装C、Python、Java、WebAssembly 四种绑定都是对 libf3d 的包装wrap不包含任何核心渲染或读取逻辑C 绑定c基于F3D_BINDINGS_CCMake 选项生成使用方式示例见 doc/libf3d/04-LANGUAGE_BINDINGS.md例如f3d_engine_autoload_plugins()、f3d_engine_create(0)、f3d_scene_add(scene, file.vtu)、f3d_interactor_start(interactor, 1.0/30.0)CMake 侧通过find_package(f3d REQUIRED COMPONENTS c_api)与f3d::c_api链接其实现位于 c/*_c_api.cxx 等文件Python 绑定python基于 pybind11 实现F3DPythonBindings.cxx并提供py.typed与generate_stubs.py类型桩生成Java 绑定java通过 JNIF3DJavaBindings.h及F3D*Bindings.cxx包装配套Camera.java、Engine.java、Scene.java等 Java 类WebAssembly 绑定webassembly通过F3DEmscriptenBindings.cxx提供 JavaScript 调用能力。winshellextWindows 文件管理器缩略图winshellext 是 Windows Shell 扩展F3DShellExtension.cxx、F3DThumbnailProvider.cxx等为 Windows 资源管理器提供 3D 文件缩略图预览在安装 F3D 后可直接在文件管理器中看到模型缩略图。它与 application 的关系是使用uses关系——缩略图渲染复用 F3D 的应用能力相关说明见 doc/user/12-DESKTOP_INTEGRATION.md。F3D 生态中的其他仓库虽然几乎全部代码都收拢在 f3d-app/f3d 这一个仓库中但 f3d-app 组织下的其他仓库负责 F3D 生态中的特定任务f3d-superbuild负责打包与发布页二进制产物的生成f3d-website存放由本项目文档生成的官网与 Web 查看器CI 辅助 Actionssccache-setup、lfs-data-cache、install-mesa-windows 等供 CI 使用f3d-docker-images用于生成 CI 所需的 Docker 镜像。对于本项目而言理解 F3D 架构最直接的入口仍是本仓库应用逻辑在application核心库在library格式支持在pluginsVTK 扩展在vtkext绑定在c/python/java/webassembly。掌握这条分层链路后无论是为 F3D 贡献新的文件格式插件还是在自己的项目中集成 libf3d都能快速定位到正确的代码位置。【免费下载链接】f3dFast and minimalist 3D viewer.项目地址: https://gitcode.com/GitHub_Trending/f3/f3d创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
