@lume/three-projected-material v0.3.1

@lume/three-projected-material

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

Recommended Installation

This method supports TypeScript.

If you're familiar with Node.js and managing dependencies with npm, and have a build setup in place or know how to serve ES modules to a browser, then install three and @lume/three-projected-material from NPM,

npm install three @lume/three-projected-material

then import ProjectedMaterial and you'll be on your way. If you're writing ES modules, import like this:

import {ProjectedMaterial} from '@lume/three-projected-material/dist/ProjectedMaterial.js'

const mat = new ProjectedMaterial(/*...*/)
// ...

If you're writing old-school CommonJS modules (consider migrating already!) you can use dynamic import() as long as your version of Node or your build tools are new enough to support it:

import('@lume/three-projected-material/dist/ProjectedMaterial.js').then(({ProjectedMaterial}) => {
	const mat = new ProjectedMaterial(/*...*/)
	// ...
})

Alternative Installation

These methods do not support TypeScript, only plain JavaScript.

If you don't have a build setup or you are only familiar with plain HTML files, import @lume/three-projected-material from a CDN such as https://unpkg.com, like so:

<script type="module">
	import {ProjectedMaterial} from 'https://unpkg.com/@lume/three-projected-material@^3.0.0/dist/ProjectedMaterial.js'

	const mat = new ProjectedMaterial(/*...*/)
	// ...
</script>

If you're still loading libraries as global variables using old-school script tags (f.e. you have a global THREE object), you can use the .global.js file, although we recommend using ES Modules as per above. Make sure to put the global script after the three.js script:

<script src="..../three.js"></script>
<script src="https://unpkg.com/@lume/three-projected-material@^3.0.0/dist/ProjectedMaterial.global.js"></script>
<script>
	const {ProjectedMaterial} = window.projectedMaterial

	const mat = new ProjectedMaterial(/*...*/)
	// ...
</script>

Usage

Use ProjectedMaterial like so:

// ... get the ProjectedMaterial class as per above ...

const geometry = new THREE.BoxGeometry(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.

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, updateWorldMatrices)

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.

material.updateFromCamera()

Call this any time the camera passed into ProjectedMaterial has had its parameters updated.

const camera = new PerspectiveCamera(...)
const mat = new ProjectedMaterial({camera})

// then later if you modify the camera:
camera.fov = 40
camera.updateProjectionMatrix()
mat.updateFromCamera() // don't forget to update the material too

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 when initializing InstancedMesh.

This needs to be called before .projectInstanceAt().

material.projectInstanceAt(index, instancedMesh, matrix)

Do the projection for an InstancedMesh. Don't forget to call updateMatrix() like you do before calling InstancedMesh.setMatrixAt().

To do projection on an instanced mesh, the geometry needs to be prepared with allocateProjectionData() beforehand.

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

Link to the full example about instancing.