three-projected-material

Three.js Material which lets you do Texture Projection on a 3d Model.

Installation

After having installed three.js, install it from npm with:

npm install three-projected-material

or

yarn add three-projected-material

You can also use it from the CDN, just make sure to put this after the three.js script:

Getting started

You can import it like this

import ProjectedMaterial from 'three-projected-material'

or, if you're using CommonJS

const ProjectedMaterial = require('three-projected-material').default

Instead, if you install it from the CDN, its exposed under

window.projectedMaterial

const ProjectedMaterial = window.projectedMaterial.default

Then, you can use it like this:

const geometry = new THREE.BoxBufferGeometry(1, 1, 1)
const material = new ProjectedMaterial({
  camera, // the camera that acts as a projector
  texture, // the texture being projected
  textureScale: 0.8, // scale down the texture a bit
  textureOffset: new THREE.Vector2(0.1, 0.1), // you can translate the texture if you want
  cover: true, // enable background-size: cover behaviour, by default it's like background-size: contain
  color: '#ccc', // the color of the object if it's not projected on
  roughness: 0.3, // you can pass any other option that belongs to MeshPhysicalMaterial
})
const box = new THREE.Mesh(geometry, material)
webgl.scene.add(box)

// move the mesh any way you want!
box.rotation.y = -Math.PI / 4
// and when you're ready project the texture on the box!
material.project(box)

ProjectedMaterial also supports instanced meshes via three.js' InstancedMesh, and even multiple projections. Check out the examples below for a detailed guide!

Examples

API Reference

new ProjectedMaterial({ camera, texture, ...others })

Create a new material to later use for a mesh.

| Option | Default | Description | | --------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |

camera

texture

textureScale

textureOffset

new THREE.Vector2()

cover

background-size: cover

background-size: contain

...options

color

opacity

envMap

These properties are exposed as properties of the material, so you can change them later.

For example, to update the material texture and change its scale:

material.texture = newTexture
material.textureScale = 0.8

material.project(mesh)

Project the texture from the camera on the mesh. With this method we "take a snaphot" of the current mesh and camera position in space. The After calling this method, you can move the mesh or the camera freely.

| Option | Description | | ------ | ---------------------------------------------------- | |

mesh

ProjectedMaterial

allocateProjectionData(geometry, instancesCount)

Allocate the data that will be used when projecting on an InstancedMesh. Use this on the geometry that will be used in pair with a

ProjectedMaterial

InstancedMesh

This needs to be called before

.projectInstanceAt()

| Option | Description | | ---------------- | ----------------------------------------------------------------------------- | |

geometry

InstancedMesh

instancesCount

InstancedMesh

material.projectInstanceAt(index, instancedMesh, matrix)

Do the projection for an InstancedMesh. Don't forget to call

updateMatrix()

InstancedMesh.setMatrixAt()

To do projection an an instanced mesh, the geometry needs to be prepared with

allocateProjectionData()

dummy.updateMatrix()
projectInstanceAt(i, instancedMesh, dummy.matrix)

Link to the full example about instancing.

| Option | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------ | |

index

instancedMesh

matrix

matrix

.updateMatrix()