ThreePresenter

A framework-agnostic 3D viewer library built on Three.js for Cultural Heritage and scientific web applications.

Features: Multi-format model loading (GLB, PLY, OBJ, NXS/Nexus) • Point annotations • Camera controls • HDRI lighting • Ground plane with scale indicator • Multi-resolution streaming

API Documentation • Live Examples

Quick Start

npm install three-presenter three

import { ThreePresenter, StaticBaseUrlResolver } from 'three-presenter';

const viewer = new ThreePresenter({ 
  mount: 'viewer',  // or HTMLDivElement
  fileUrlResolver: new StaticBaseUrlResolver('./assets')
});

await viewer.loadScene({
  models: [{ id: 'model', file: 'model.glb' }],
  environment: { showGround: true }
});

Optional UI Controls:

import { DefaultUI } from 'three-presenter';
const ui = new DefaultUI(viewer);
ui.setButtonVisible('home', true);
ui.setButtonVisible('screenshot', true);

Development

Once you have cloned the repository, install dependencies and start the development server with:

npm install
npm run dev      # Watch src/ + auto-rebuild + serve at localhost:8080

Other available commands:

npm run build    # Build library for npm
npm run deploy   # Build everything for GitHub Pages

View examples at http://localhost:8080/docs/ while npm run dev is running.

Deployment to GitHub Pages

It is done automatically by GitHub Action on push to the main branch.

Deployment to npm

Make sure to update the version in package.json before publishing.

npm run build    # Build library for npm
npm publish       # Publish to npm registry

Folder Structure

• src/: Source code for the ThreePresenter library.
• docs/: root of the website deployed onto github.io by github actions; it contains the generated API documentation (docs/api) and the sources of the examples ( docs/examples/ that will appear on the website).
• dist/: Compiled library for npm and GitHub Pages (gitignored).
• assets/: Sample models and textures for examples.

License

MIT • Developed by CNR-ISTI Visual Computing Lab