Introduction
A new way to work with three.js, 3D models and rendering on the web.
Threepipe provides a high-level API over three.js to create 3D model viewers, configurators. editors and other interactive 3D applications on websites.
It can be used to quickly get into production-ready WebGL and 3D web graphics without getting into graphics and shaders. The framework is also fully customisable with an extensive API for experienced programmers to add features and make more cool stuff.
Just want to try it out? Skip to the Quickstart.
Key features include:
- Simple, intuitive API for creating 3D model viewers/configurators/editors on web pages, with many built-in presets for common workflows and use-cases.
- Companion editor to create, edit and configure 3D scenes in the browser.
- Modular architecture that allows you to easily extend the viewer, scene objects, materials, shaders, rendering, post-processing and serialization with custom functionality.
- Plugin system along with a rich library of built-in plugins that allows you to easily add new features to the viewer.
- uiconfig compatibility to automatically generate configuration UIs in the browser.
- Modular rendering pipeline with built-in deferred rendering, post-processing, RGBM HDR rendering, etc.
- Material extension framework to modify/inject/build custom shader code into existing materials at runtime from plugins.
- Extendable asset import, export and management pipeline with built-in support for gltf, glb, obj+mtl, fbx, materials(pmat/bmat), json, zip, png, jpeg, svg, webp, ktx2, ply, 3dm and many more.
- Automatic serialization of all viewer and plugin settings in GLB(with custom extensions) and JSON formats.
- Automatic disposal of all three.js resources with built-in reference management.
Examples
Code samples and demos covering various usecases and test are present in the examples folder.
Try them: https://threepipe.org/examples/
View the source code by pressing the code button on the top left of the example page.
To make changes and run the example, click on the Codepen Button on the top right of the source code.
TUTORIALS
There are some step-by-step tutorials to get you started if you are new to 3D or Threepipe.
- Create an interactive Device Showcase on codrops.
Sample
Here is what a sample threepipe
code looks like -
import {
ContactShadowGroundPlugin,
IObject3D,
LoadingScreenPlugin,
ProgressivePlugin,
SSAAPlugin,
ThreeViewer
} from 'threepipe';
import {TweakpaneUiPlugin} from '@threepipe/plugin-tweakpane';
async function init() {
const viewer = new ThreeViewer({
// The canvas element where the scene will be rendered
canvas: document.getElementById('threepipe-canvas') as HTMLCanvasElement,
// Enable/Disable MSAA (Multi-Sample Anti-Aliasing)
msaa: false,
// Set the render scale automatically based on the device pixel ratio
renderScale: "auto",
// Enable/Disable tone mapping
tonemap: true,
// Add some plugins
plugins: [
// Show a loading screen while the model is downloading
LoadingScreenPlugin,
// Enable progressive rendering and SSAA
ProgressivePlugin, SSAAPlugin,
// Add a ground with contact shadows
ContactShadowGroundPlugin
]
});
// Add a plugin with a debug UI for tweaking parameters
const ui = viewer.addPluginSync(new TweakpaneUiPlugin(true));
// Load an environment map
await viewer.setEnvironmentMap('https://threejs.org/examples/textures/equirectangular/venice_sunset_1k.hdr', {
// The environment map can also be used as the scene background
setBackground: false,
});
// Load a 3D model with auto-center and auto-scale options
const result = await viewer.load<IObject3D>('https://threejs.org/examples/models/gltf/DamagedHelmet/glTF/DamagedHelmet.gltf', {
autoCenter: true,
autoScale: true,
});
// Add some debug UI elements for tweaking parameters
ui.setupPlugins(SSAAPlugin)
ui.appendChild(viewer.scene.uiConfig)
ui.appendChild(viewer.scene.mainCamera.uiConfig)
// Every object, material, etc has a UI config that can be added to the UI to configure it.
const model = result?.getObjectByName('node_damagedHelmet_-6514');
if (model) ui.appendChild(model.uiConfig, {expanded: false});
}
init();
The ThreeViewer
class is used to create a new 3D viewer instance. It includes several components including a Scene
, Camera
(with OrbitControls
), Renderer
, RenderManager
, AssetManager
, and some default plugins(like TonemapPlugin
). It is set up to provide a quickstart to create a three.js app with all the required components.
Additionally plugins like LoadingScreenPlugin
, ProgressivePlugin
, SSAAPlugin
, and ContactShadowGroundPlugin
are added to extend the functionality of the viewer.
Check out this sample on CodePen: threepipe-sample
License
The core framework(src, dist, examples folders) and any plugins without a separate license are under the Free Apache 2.0 license.
Some plugins(in the plugins folder) might have different licenses. Check the individual plugin documentation and the source folder/files for more details.
Status
The project is in beta
stage and under active development. Many features and integrations will be added but the core API will not change significantly in future releases.
API Reference/Docs
Check the list of all functions, classes and types in the API Reference Docs.
Contributing
Contributions to ThreePipe are welcome and encouraged! Feel free to open issues and pull requests on the GitHub repository.