search

lume / three-meshline

Mesh-based replacement for `THREE.Line` to allow lines thicker than 1 pixel and other features.
https://docs.lume.io/three-meshline/
MIT License
42 stars 4 forks source link

readme

@lume/three-meshline

Provides a Mesh-based replacement for THREE.Line from Three.js, allowing line thicknesses of any size (THREE.Line is limited to 1 pixel width), and other features.

Note This is forked from three.meshline, as that project has been dormant. The version of this starts at 2.0 because it modernizes the code base in ways that make it a breaking change, and removes deprecated features.

Instead of using GL_LINE, it uses a strip of triangles billboarded. Some examples:

Demos

Demo
Play: play with the different mesh line options 		Graph
Graph: example of using `MeshLine` to plot graphs 		Spinner
Spinner: example of dynamic `MeshLine` with texture
SVG
SVG: example of `MeshLine` rendering SVG Paths 		Shape
Shape: example of `MeshLine` created from an OBJ file 		Birds
Birds: example of `MeshLine.advance()` by @caramelcode (Jared Sprague) and @mwcz (Michael Clayton)

How to use

Install

With self-hosted dependencies installed locally:

First install @lume/three-meshline:

npm i @lume/three-meshline

Add the importmap to your HTML if you are using native JavaScript modules (if you have a build step handling your modules, you'd skip this):

<script src="https://github.com/lume/three-meshline/raw/main/node_modules/@lume/three-meshline/importmap.js"></script>

If your browser doesn't support importmaps natively yet, you can load an importmap polyfill then embed the importmap manually in your HTML like so:

<script defer src="https://ga.jspm.io/npm:es-module-shims@1.6.3/dist/es-module-shims.js"></script>
<script src="https://github.com/lume/three-meshline/raw/main/node_modules/@lume/three-meshline/importmap.js"></script>

Finally import APIs into your JavaScript code:

import {MeshLine, MeshLineGeometry, MeshLineMaterial} from '@lume/three-meshline'

Create an array of 3D coordinates

First, create the list of numbers that will define the 3D points for the line.

const points = []
for (let j = 0; j < Math.PI; j += (2 * Math.PI) / 100) {
    points.push(Math.cos(j), Math.sin(j), 0)
}

Create a MeshLineGeometry and assign the points

Once you have that, you can create a new MeshLineGeometry, and call .setPoints() passing the list of points.

const geometry = new MeshLineGeometry()
geometry.setPoints(points)

Note: .setPoints accepts a second parameter, which is a function to define the width in each point along the line. By default that value is 1, making the line width 1 * lineWidth in the material.

// p is a decimal percentage of the number of points
// ie. point 200 of 250 points, p = 0.8
geometry.setPoints(points, p => 2) // makes width 2 * lineWidth
geometry.setPoints(points, p => 1 - p) // makes width taper from the beginning
geometry.setPoints(points, p => 1 - (1 - p)) // makes width taper from the end
geometry.setPoints(points, p => 2 + Math.sin(50 * p)) // makes width sinusoidal

Create a MeshLineMaterial

A MeshLine needs a MeshLineMaterial:

const material = new MeshLineMaterial(options)

By default it's a white material with line width 1 unit.

MeshLineMaterial accepts options to control the appereance of the MeshLine:

If you're rendering transparent lines or using a texture with alpha map, you may consider setting depthTest to false, transparent to true and blending to an appropriate blending mode, or use alphaTest.

Use MeshLineGeometry and MeshLineMaterial to create a MeshLine

Finally, we create a mesh and add it to the scene:

const line = new MeshLine(geometry, material)
scene.add(line)

Note that MeshLine extends from THREE.Mesh and adds raycast support:

const raycaster = new THREE.Raycaster()
// Use raycaster as usual:
raycaster.intersectObject(line)

Declarative use

react-three-fiber

MeshLine can be used declaritively. This is how it would look like in react-three-fiber. You can try it live here.

react-three-fiber confetti react-three-fiber sine wave 

import {extend, Canvas} from 'react-three-fiber'
import {MeshLine, MeshLineMaterial, MeshLineRaycast} from '@lume/three-meshline'

extend({MeshLine, MeshLineGeometry, MeshLineMaterial})

function Line({points, width, color}) {
    return (
        <Canvas>
            <meshLine>
                <meshLineGeometry attach="geometry" points={points} />
                <meshLineMaterial
                    attach="material"
                    transparent
                    depthTest={false}
                    lineWidth={width}
                    color={color}
                    dashArray={0.05}
                    dashRatio={0.95}
                />
            </meshLine>
        </Canvas>
    )
}

Dynamic line widths can be set along each point using the widthCallback prop.

<meshLineGeometry attach="geometry" points={points} widthCallback={pointWidth => pointWidth * Math.random()} />

TODO

Support

Tested successfully on

References

License

MIT licensed