MeshLine
Mesh replacement for THREE.Line
Instead of using GL_LINE, it uses a strip of triangles billboarded. Some examples:
- Demo: play with the different settings of materials
- Graph: example of using
MeshLineto plot graphs - Spinner: example of dynamic
MeshLinewith texture - SVG: example of
MeshLinerendering SVG Paths - Shape: example of
MeshLinecreated from a mesh - Birds: example of
MeshLine.advance()by @caramelcode (Jared Sprague) and @mwcz (Michael Clayton)
How to use
- Include script
- Create an array of 3D coordinates
- Create a MeshLine and assign the points
- Create a MeshLineMaterial
- Use MeshLine and MeshLineMaterial to create a THREE.Mesh
Include the script
Include script after THREE is included
or use npm to install it
npm i three.meshline
and include it in your code (don't forget to require three.js)
const MeshLine = require('three.meshline').MeshLine;
const MeshLineMaterial = require('three.meshline').MeshLineMaterial;
const MeshLineRaycast = require('three.meshline').MeshLineRaycast;
or
import { MeshLine, MeshLineMaterial, MeshLineRaycast } from 'three.meshline';
Create an array of 3D coordinates
First, create the list of numbers that will define the 3D points for the line.
for (let j = 0; j < Math.PI; j += (2 * Math.PI) / 100) {
points.push(Math.cos(j), Math.sin(j), 0);
}
MeshLine also accepts a Geometry or BufferGeometry looking up the vertices in it.
for (let j = 0; j < Math.PI; j += 2 * Math.PI / 100) {
const v = new THREE.Vector3(Math.cos(j), Math.sin(j), 0);
geometry.vertices.push(v);
}
Create a MeshLine and assign the points
Once you have that, you can create a new MeshLine, and call .setPoints() passing the list of points.
line.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.
// ie. point 200 of 250 points, p = 0.8
line.setPoints(geometry, p => 2); // makes width 2 * lineWidth
line.setPoints(geometry, p => 1 - p); // makes width taper
line.setPoints(geometry, p => 2 + Math.sin(50 * p)); // makes width sinusoidal
Create a MeshLineMaterial
A MeshLine needs a MeshLineMaterial:
By default it's a white material of width 1 unit.
MeshLineMaterial has several attributes to control the appereance of the MeshLine:
map- aTHREE.Textureto paint along the line (requiresuseMapset to true)useMap- tells the material to usemap(0 - solid color, 1 use texture)alphaMap- aTHREE.Textureto use as alpha along the line (requiresuseAlphaMapset to true)useAlphaMap- tells the material to usealphaMap(0 - no alpha, 1 modulate alpha)repeat- THREE.Vector2 to define the texture tiling (applies to map and alphaMap - MIGHT CHANGE IN THE FUTURE)color-THREE.Colorto paint the line width, or tint the texture withopacity- alpha value from 0 to 1 (requirestransparentset totrue)alphaTest- cutoff value from 0 to 1dashArray- the length and space between dashes. (0 - no dash)dashOffset- defines the location where the dash will begin. Ideal to animate the line.dashRatio- defines the ratio between that is visible or not (0 - more visible, 1 - more invisible).resolution-THREE.Vector2specifying the canvas size (REQUIRED)sizeAttenuation- makes the line width constant regardless distance (1 unit is 1px on screen) (0 - attenuate, 1 - don't attenuate)lineWidth- float defining width (ifsizeAttenuationis true, it's world units; else is screen pixels)
If you're rendering transparent lines or using a texture with alpha map, you should set depthTest to false, transparent to true and blending to an appropriate blending mode, or use alphaTest.
Use MeshLine and MeshLineMaterial to create a THREE.Mesh
Finally, we create a mesh and add it to the scene:
scene.add(mesh);
You can optionally add raycast support with the following.
Declarative use
THREE.meshline can be used declaritively. This is how it would look like in react-three-fiber. You can try it live here.
import { MeshLine, MeshLineMaterial, MeshLineRaycast } from 'three.meshline'
extend({ MeshLine, MeshLineMaterial })
function Line({ points, width, color }) {
return (
<Canvas>
<mesh raycast={MeshLineRaycast}>
<meshLine attach="geometry" points={points} />
<meshLineMaterial
attach="material"
transparent
depthTest={false}
lineWidth={width}
color={color}
dashArray={0.05}
dashRatio={0.95}
/>
mesh>
Canvas>
)
}
TODO
- Better miters
- Proper sizes
Support
Tested successfully on
- Chrome OSX, Windows, Android
- Firefox OSX, Windows, Anroid
- Safari OSX, iOS
- Internet Explorer 11 (SVG and Shape demo won't work because they use Promises)
- Opera OSX, Windows
References
License
MIT licensed
Copyright (C) 2015-2016 Jaume Sanchez Elias, http://www.clicktorelease.com