Features

Threepipe comes packed with a asset manager, render pipeline, serialization setup, material extensions, UI configurations and bundles many plugins, that can be added with a single line of code to provide a variety of features listed below. In a custom application it’s possible to tree-shake the bundle by picking the plugins that are required.

File Formats

ThreePipe Asset Manager supports the import of the following file formats out of the box:

• Models: gltf, glb, obj+mtl, fbx, drc
• Materials: mat, pmat, bmat (json based), registered material template slugs
• Images: webp, png, jpeg, jpg, svg, ico, avif, hdr, exr
• Misc: json, vjson, zip, txt

Plugins can add additional formats:

• Models
  • 3dm - Using Rhino3dmLoadPlugin
  • ply - Using PLYLoadPlugin
  • usdz - Using USDZLoadPlugin
  • stl - Using STLLoadPlugin
  • ktx - Using KTXLoadPlugin
  • ktx2 - Using KTX2LoadPlugin

Plugins to support more model formats are available in the package @threepipe/plugins-extra-importers including .3ds, .3mf, .collada, .amf, .bvh, .vox, .gcode, .mdd, .pcd, .tilt, .wrl, .mpd, .vtk, .xyz

Loading files

All the file formats can be easily loaded using the viewer.load method.

const objectGlb = await viewer.load<IObject3D>('https://example.com/file.glb')
const texture = await viewer.load<ITexture>('https://example.com/texture.png')
const material = await viewer.load<PhysicalMaterial>('https://example.com/material.pmat')
const json = await viewer.load<any>('https://example.com/file.json')

This method internally uses the AssetManager to load files and returns a promise that resolves to the loaded object.

Check the Loading Files guide for more details and how to load different file types.

• 3D models
• Materials
• Images/Textures
• zip files
• txt, json files
• Data URLs
• Local files, File and Blob
• Background, Environment maps
• SVG strings

Exporting files

Threepipe has built-in support for exporting some file types like glb, exr, images(textures, render targets), , materials, json(viewer/scene configuration and plugin configurations).

To export files, several helpers are provided - viewer.export() and viewer.exportScene().

const blob = await viewer.exportScene({viewerConfig: true})
const blob1 = await viewer.export(object, {exportExt: 'glb', embedUrlImages: true})
const blob2 = await viewer.export(material)
const blob3 = await viewer.export(texture)
const blob4 = await viewer.export(dataTexture)
const blob5 = await viewer.export(renderTarget)

Check the Exporting Files guide for more details and how to export different file types.

• Exporting 3D models
• Exporting Materials
• Exporting Canvas Images
• Exporting Images/Textures
• Exporting Render Targets

Plugin System

Threepipe includes a plugin system for adding additional features to the viewer in a modular way.

All plugins follow the same basic structure, independent of the logic, with the API to add and remove plugins being always consistent (and one-liner). This makes it easy to debug, bundle, tree-shake, serialisation/deserialisation and extend functionality to the 3d viewer. It is also recommended to keep individual plugins small and handle one specific functionality.

Plugins can be dependant on other plugins. These dependencies are automatically resolved and added to the viewer at runtime. eg. SSAOPlugin depends on GBufferPlugin to get the depth and normal data. So, when SSAOPlugin is added to the viewer, it automatically adds GBufferPlugin before that (if not added already).

The plugins can be added synchronously or asynchronously using viewer.addPluginSync and viewer.addPlugin methods respectively.

It is recommended to create custom plugins for reusable features, as they provide built-in features for ui configuration, serialization, integration with editors etc and are easy to manage and tree-shake in the code.

Check out the list of plugins in the Core Plugin and @threepipe Packages pages.

To create new plugins, simply implement the IViewerPlugin interface or extend the AViewerPluginSync or AViewerPluginAsync classes.

Read more about the Plugin System on it's page.

Render pipeline

Threepipe includes a RenderManager for managing the composition pipeline, and provides helpers for rendering and render target management.

The RenderManager includes an EffectComposer from three.js for rendering passes and a WebGLRenderer for rendering, but the pass management and sorting is managed by the RenderManager itself. It inherits from RenderTargetManager which provides utilities for creating, tracking and destroying dedicated and temporary render targets.

The main render pipeline supports progressive rendering and is fully configurable. Plugins and applications can add custom passes, effects, and shaders to the pipeline.

By default, the render pipeline includes 2 passes - RenderPass for rendering the scene hierarchy and ScreenPass for rendering the final output on the canvas.

Plugins like GBufferPlugin, SSAOPlugin, TonemapPlugin, etc interact and extend the render pipeline by adding custom passes to the render pipeline and material extensions to the material manager.

Check the Render Pipeline guide for more details about render targets and how to add custom passes.

Material Extension

Threepipe includes a Material extension system along with a material manager. The material manager is used to register materials and material extensions.

The material extensions can extend any material in the scene, or any plugin/pass with additional uniforms, defines, shader snippets and provides hooks.

The material extensions are automatically applied to all materials in the scene that are compatible, when the extension is registered or when the material(the object its assigned to) is added to the scene.

Threepipe includes several built-in materials like PhysicalMaterial, UnlitMaterial, ExtendedShaderMaterial, LegacyPhongMaterial, that include support for extending the material. Any existing three.js material can be made extendable, check the ShaderPass2 class for a simple example that adds support for material extension to three.js ShaderPass.

Several Plugins create and register material extensions to add different kinds of rendering features over the standard three.js materials like ClearcoatTintPlugin, SSAOPlugin, CustomBumpMapPlugin, AnisotropyPlugin, FragmentClippingExtensionPlugin, etc. They also provide uiConfig that can be used to dynamically generate UI or the material extensions.

Some plugins also expose their material extensions to be used by other passes/plugins to access properties like buffers, synced uniforms, defines etc. Like GBufferPlugin, DepthBufferPlugin, NormalBufferPlugin, etc.

Read more and check a sample plugin in the Material Extension guide.

UI Configuration

Almost all of the classes and plugins in Threepipe include uiconfig.js support and can be used to create configuration UIs, 3d configurators and even full-editors. The UIs are automatically generated based on the configuration object under .uiConfig property on all objects. These are of type UiObjectConfig. In some classes, the ui configs are also generated using typescript decorators.

The uiConfig is also added to all three.js objects and materials when they are added to the scene.

The UIs can be generated at runtime using any of the UI plugins like TweakpaneUIPlugin, BlueprintJsUiPlugin

An example showing how to create a UI for a material

const ui = viewer.addPluginSync(TweakpaneUiPlugin)

const object = viewer.scene.getObjectByName('objectName');
const material = object.material as PhysicalMaterial;

ui.appendChild(material.uiConfig)

See it in action: https://threepipe.org/examples/#material-uiconfig/

Check more examples showing Viewer UI, Scene UI, Object UI, Camera UI

INFO

TweakpaneEditorPlugin further uses the Tweakpane configuration panel along with various plugins to create an 3d editor.

Custom UI configuration can be created to generate custom UI for the editor or tweaking. This can be done by using typescript decorators or defining the UI in javascript as a UiObjectConfig object.

Read more and check a sample in the UI Configuration guide.

Serialization

Easy serialization of all threepipe and most three.js objects are supported out of the box using the Asset Manager. Fine control over serialization is also supported using the ThreeSerialization class

Call ThreeSerialization.serialize on any object to serialize it. and ThreeSerialization.deserialize to deserialize the serialized object.

This is done by performing a nested serialization of all the properties of the object. It's possible to implement custom serializers for custom types and classes and is done for three.js primitives, objects and plugins in threepipe

const vec = new Vector3()
const serialized = ThreeSerialization.serialize(vec)
const deserialized = ThreeSerialization.deserialize(serialized)
// deserialized will be an instance of Vector3

TIP

For any high-level usage, don't use the ThreeSerialization class directly. Use the viewer.export and viewer.import methods or other methods to save and load configurations that's available in the plugins and the viewer.

Read more and check samples in the Serialization guide.