threejs-billboard

billboard module for three.js

Demo

Demo page

Getting Started

Install

npm install @masatomakino/threejs-billboard --save-dev
Copy

threejs-billboard depend on three.js and pixi.js.

Import

threejs-billboard is composed of ES6 modules and TypeScript d.ts files.

At first, import classes.

import {
  BillBoard,
  StageBillBoard,
  StagePlaneMesh,
  ScaleCalculator,
} from "@masatomakino/threejs-billboard";
Copy

Show billboard

Add billboard in THREE.Scene.

const billboard = new BillBoard("./map01.png", 0.1);
scene.add(billboard);
Copy

Choosing the Right Class

The library provides different classes for creating billboards and plane meshes, each with distinct characteristics and use cases:

• Image-based Classes (BillBoard, BillBoardPlane): Use image files as source. Simple to use for static images.
• SharedStage Classes (Billboard, PlaneMesh): Utilize a single shared Canvas/Texture, excelling in reducing draw calls. Suitable for scenarios with a fixed number of billboards where performance is critical.
• MultiView Classes (Billboard, PlaneMesh): Each instance has an independent Canvas, offering superior performance for partial updates and flexibility in the number of billboards. Suitable for scenarios with numerous and dynamically changing billboards.

Dot-by-dot display

If you want to display dot-by-dot billboard, get image scale with ScaleCalculator.

const scale = ScaleCalculator.getNonAttenuateScale(
  renderer.getSize(new THREE.Vector2()).height,
  camera,
);
const billboard = new BillBoard("./map01.png", scale);
billboard.material.sizeAttenuation = false;
Copy

Camera Chaser

The CameraChaser utility can be used with SharedStagePlaneMesh, MultiViewPixiPlaneMesh, and BillBoardPlane to make the plane track the camera's rotation. By default, this feature is off. You can enable it to make the plane always face the camera, similar to a billboard but maintaining its plane geometry. Note that unlike a Sprite, the rotation is limited to the Y-axis.

API documents

API documents

License

MIT licensed.