threepp README

项目的 README,来自 github.com/markaren/threepp。合并为一个 markdown 文件:README.md。

threepp

Build License: MIT Conan Center PyPI

A cross-platform C++20 3D library with the high-level API of three.js, and two backends behind one scene graph: portable OpenGL, and a deferred Vulkan renderer with ray-traced shadows, reflections, AO and GI.

On top of that: a scene editor, PhysX robot simulation, simulated sensors with ground-truth labels for synthetic data, hardware-in-the-loop flight with ArduPilot, and Python bindings on PyPI.

An Otter X sea drone in a digital twin of a waterfront in Ålesund
An Otter X sea drone under way in a digital twin of a real waterfront in Ålesund, Norway, modelled from Kartverket lidar and sea charts and rendered by the Vulkan backend: the water reflects the moored boats and the buildings ashore (the scene is not in the repository)

New here? Getting started walks through the concepts the library is built from: the scene graph, ownership and lifetimes, geometry and materials, lights, the frame loop, loaders and the two backends. The examples folder is the de-facto reference.

Features

three.js parity. The API follows three.js r129, with selected features from r186 on the OpenGL path (shadow filtering, environment and background controls, material fixes, the newer post-processing passes).

Rendering beyond three.js

Simulation and perception

Content and tooling

Applications

The threepp scene editor

Both build alongside the library in a top-level build (THREEPP_BUILD_EDITOR).

Project status

threepp is built for research, prototyping and teaching, not as a production engine. APIs change, so pin a tag or commit if you need reproducibility.

The three.js port is the mature layer, and the one most users touch. The simulation layer on top (the Vulkan renderer, sensors, PhysX, the editor and Python) is where development goes, and it moves fastest. Limits worth knowing:

Example

#include "threepp/threepp.hpp"

using namespace threepp;

int main() {

    Canvas canvas{"Demo"};
    GLRenderer renderer{canvas};

    auto scene = Scene::create();
    auto camera = PerspectiveCamera::create(75, canvas.aspect(), 0.1f, 100.f);
    camera->position.z = 5;

    OrbitControls controls{*camera, canvas};

    scene->add(HemisphereLight::create());

    auto material = MeshPhongMaterial::create();
    material->color = Color::green;
    auto box = Mesh::create(BoxGeometry::create(), material);
    scene->add(box);

    canvas.onWindowResize([&](WindowSize size) {
        camera->aspect = size.aspect();
        camera->updateProjectionMatrix();
        renderer.setSize(size);
    });

    Clock clock;
    canvas.animate([&] {
        box->rotation.y += 1.f * clock.getDelta();
        renderer.render(*scene, *camera);
    });
}

Swap GLRenderer for VulkanRenderer and the scene code stays the same. Math classes are value types; everything else is created through a static ::create that returns a std::shared_ptr, and GPU resources are released when the last reference goes. threepp/threepp.hpp covers the three.js core; extras/, postprocessing/, splats/ and the newer objects are included explicitly.

Python

pip install threepp

Wheels for CPython 3.10 to 3.14 on Windows x64 and manylinux x86_64 carry the OpenGL and Vulkan renderers and CPU PhysX; the Windows wheels also carry the FSR 3.1 upscaler. macOS builds from source (OpenGL only). Releases are named by date; pin the one you tested.

import threepp as tp

canvas = tp.Canvas("offscreen", width=800, height=600, headless=True)
renderer = tp.GLRenderer(canvas)

scene = tp.Scene()
camera = tp.PerspectiveCamera(75, 800 / 600, 0.1, 100)
camera.position.z = 5

mat = tp.MeshStandardMaterial()
mat.color = 0x00aaff
scene.add(tp.Mesh(tp.BoxGeometry(), mat))
scene.add(tp.HemisphereLight())

renderer.render(scene, camera)
pixels = renderer.read_pixels()   # (H, W, 3) uint8 NumPy array
renderer.save_frame("out.png")

The module also exposes the Vulkan labels as NumPy arrays, PhysX articulations, CUDA interop and threepp.rl, a GPU-vectorized PPO stack. A headless canvas needs no display, so the same code runs on Colab and cloud GPUs. python/README.md is the full guide, with the extras (threepp[rl], threepp[editor]) and the Python examples.

Building

All core dependencies are bundled. CMakePresets.json holds the configurations CI builds:

Preset What you get
gl OpenGL backend, with examples, tests and the editor (start here)
gl-debug as gl, unoptimised and with debug info
vulkan the deferred Vulkan renderer (Vulkan SDK on PATH, or the vcpkg vulkan feature)
vulkan-aaa as vulkan, plus the FSR 3.1 and DLSS upscalers (Windows)
python the pybind11 threepp module
no-glfw build check only: no GLFW frontend, so no rendering
wasm Emscripten/WebGL2 examples (needs an activated emsdk)
cmake --preset gl
cmake --build --preset gl
ctest --preset gl

Each preset builds into build/<preset>. cmake --list-presets also lists the ci-* presets the GitHub workflow runs, and machine-specific presets belong in an untracked CMakeUserPresets.json that inherits from these. Without presets, cmake -B build and cmake --build build work as usual; add -DTHREEPP_USE_EXTERNAL_GLFW=ON to use a system GLFW.

A subset of the examples runs in the browser: try them online.

Some headers need extra packages when you consume them:

Header Dependency Notes
AssimpLoader assimp Import a wide range of 3D formats
ImguiContext imgui Dear ImGui utility
Physx*, ConvexDecomposition physx, v-hacd Physics simulation and concave colliders
Vulkan*, Ocean, ParticleField, SonarSensor, and others Vulkan SDK Linked only under THREEPP_WITH_VULKAN, which the threepp target propagates

Using threepp in your project

CMake FetchContent is the recommended and tested route:

include(FetchContent)
FetchContent_Declare(
        threepp
        GIT_REPOSITORY https://github.com/markaren/threepp.git
        GIT_TAG tag_or_branch
        GIT_SHALLOW TRUE
)
FetchContent_MakeAvailable(threepp)
target_link_libraries(main PUBLIC threepp::threepp)

Consumed this way only the library builds, and the example assets in threepp_data are never downloaded. A complete setup is in tests/threepp_fetchcontent_test, and threepp_wxwidgets embeds threepp in a wxWidgets window. threepp is also on Conan Center, which xmake can consume too; see doc/package_managers.md for both and their caveats.

Why?

Because C++ deserves nice things too. Also, because fun.

It also turns out to suit AI-assisted development: a three.js API that models already know, few dependencies, first-party source all the way down to the Vulkan shaders, and a short loop from code to a rendered image that can be captured headless and judged.

A drone light show writes threepp over the Stigfossen waterfall at Trollstigen
Vulkan and Warp: a drone light show writes the name at dusk over Stigfossen, in a digital twin of Trollstigen, Norway; the drones are a ParticleField and the waterfall is GPU parcels (the scene is not in the repository)
A drone flying low through a pine forest
Vulkan: a Norwegian pine forest, scanned trees placed by a stand simulation as instanced meshes, grass and heath on the floor, and a drone low over the ground (the scene is not in the repository)
Rover on a sand slope
Vulkan and Warp: a rover climbs loose sand in GPU grains, with slip plotted against tilt-bed data (rover)
OpenGL showpiece
OpenGL: room lighting, glass, soft shadows, GTAO, bloom and outline in one frame (showpiece)
Spot RL gait, procedural forest
Vulkan: an RL-trained Spot walks a procedural forest while its depth camera builds a live SLAM surface (spot_slam.py)
OpenGL studio scene
OpenGL from Python: soft shadows, ambient occlusion and a selection outline (gl_studio.py)
GPU particle field
Vulkan: a campfire ParticleField, marched as participating media (vulkan_fire)
Franka FR3 with a depth camera
OpenGL: a depth camera on a Franka FR3, placed by IK, scans a tray (lesson part 2, depth_map.py)
Sphero RVR following a ball
OpenGL: a Sphero RVR follows a ball by what its own camera sees, driven through the real robot's two drive commands (SpheroControl)
SVG loader
OpenGL and Vulkan: the SVG loader (svg_loader)

License

threepp is MIT-licensed. It ports the API and shaders of three.js (MIT) and bundles or fetches a number of third-party libraries and assets; see THIRD_PARTY.md for the full index, including the parts that are not MIT (the optional NVIDIA DLSS SDK, and the Boston Dynamics Spot model in threepp_data).

threepp (markaren/threepp)

正在搜索数据库…

1.2K ·GitHub
这是什么?threepp 是一个跨平台的 C++20 三维库,带有 Python 绑定,其高层 API 与 three.js 保持一致。它用于在代码中构建三维场景和仿真。
它是框架、引擎,还是只是一个库?它是一个库,你可以链接到自己的 C++ 程序中,也可以在 Python 中导入使用。场景编辑器和无界面播放器作为基于它构建的独立应用一并提供。
我该如何把它加入我的项目?推荐且经过测试的方式是使用 CMake FetchContent。你也可以运行 cmake -B build,然后运行 cmake --build build;如果使用 Python,则从 PyPI 安装 threepp 的 wheel 包。
开始之前我需要准备什么?所有核心依赖都已内置,因此 OpenGL 构建只需要 C++20 编译器和 CMake。Vulkan 后端需要 Vulkan SDK;Python wheel 包支持 Windows x64 和 manylinux x86_64 平台上的 CPython 3.10 至 3.14。
Vulkan 渲染器能在我的 Mac 上运行吗?不能。Vulkan 后端需要 MoltenVK 不提供的光线追踪扩展,因此在 macOS 上应使用 OpenGL 渲染器(GLRenderer)。
应该先从哪个后端开始?先从 OpenGL 后端开始,它支持 Windows、Linux、macOS,以及通过 Emscripten/WebGL2 在浏览器中运行。之后如需光线追踪阴影、反射和 GI(全局光照),再选择 Vulkan。
可以免费用于商业用途吗?该库采用 MIT 许可证。部分内置或可选的组件不是 MIT 许可,尤其是 NVIDIA DLSS SDK,以及 threeppdata 中的 Boston Dynamics Spot 模型,因此发布前请查阅 THIRDPARTY.md。
没有 GPU 的情况下能在 CI 中运行吗?可以。README 中说明 CI 环境没有 GPU,Vulkan 后端会在那里使用 lavapipe 配合验证层运行。它检查的是规范的正确性,而不是渲染出的像素。
我能加载现有的 three.js 场景和三维模型吗?可以。three.js 编辑器的文档可以原样加载。加载器支持 glTF/GLB、OBJ/MTL、STL、COLLADA、SVG、URDF/xacro、PNG/JPEG、HDR 和 EXR,另外可选支持 USD 和 FBX(需手动启用)。
除了渲染,仿真部分还能做什么?它增加了 PhysX 刚体、关节体、软体和载具,以及模拟的激光雷达、深度、IMU 和相机传感器,并可为合成数据提供真值标注。它还能以锁步方式驱动未修改的 ArduPilot 机体飞行。
有没有可以先试用的现成应用?有。threepp editor 提供视口、层级面板、属性检查器、撤销/重做功能,以及由 PhysX 驱动的播放模式,并且已为 Windows 预先构建,可通过 pip install threepp-editor 安装。场景可保存为普通的 three.js JSON 格式。
作者为什么说它适合 AI 辅助开发?three.js 的 API 对模型来说已经很熟悉,依赖项很少,而且源代码可以深入到 Vulkan 着色器层面。这使得从代码到渲染图像的循环很短,并且可以无界面地捕获和检查结果。
作者
markaren
大小
309.5 MB
星标
1.2K
时长
5年
提交 · 90 天