threejs-meshline

This fork has now been merged into THREE.meshline 1.3.0

THREE.meshline code will work exactly the same, however, meshline.setVertices and meshline.vertices have been renamed to meshline.setPoints and meshline.points.

Click examples above to view the code and the examples found at THREE.meshline will work with this fork.

npm install threejs-meshline

threejs-meshline is a replacement for THREE.Line, it allows you to create lines with varable widths. It is a fork of Jaume Sanchez Elias THREE.meshline as the repo no longer appears to be maintained.

• Supports BufferGeometry
• Extends THREE.BufferGeometry and can be used in regular meshes as a geometry
• New setVertices and setBufferArray functions so you no longer need to create a geometry prior to a MeshLine
• Raycast is exposed as MeshLineRaycast and can be used like mesh.raycast = MeshLineRaycast
• Raycast accounts for line width
• Extra setters and getters to help with declaritive libraries like react-three-fiber

How to use

Fetch imports

import { MeshLine, MeshLineMaterial, MeshLineRaycast } from 'threejs-meshline'

Create and populate a geometry

First, create the list of vertices that will define the line. MeshLine accepts an array of vertices.

const vertices = []
for (let j = 0; j < Math.PI; j += (2 * Math.PI) / 100)
  vertices.push(new THREE.Vector3(Math.cos(j), Math.sin(j), 0))

Create a MeshLine and set the vertices

Once you have that, you can create a new MeshLine, and call .setVertices() passing the vertices.

const line = new MeshLine()
line.setVertices(vertices)

Note: .setVertices 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
line.setVertices(geometry, p => 2) // makes width 2 * lineWidth
line.setVertices(geometry, p => 1 - p) // makes width taper
line.setVertices(geometry, 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 of width 1 unit.

MeshLineMaterial has several attributes to control the appereance of the MeshLine:

• map - a THREE.Texture to paint along the line (requires useMap set to true)
• useMap - tells the material to use map (0 - solid color, 1 use texture)
• alphaMap - a THREE.Texture to use as alpha along the line (requires useAlphaMap set to true)
• useAlphaMap - tells the material to use alphaMap (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.Color to paint the line width, or tint the texture with
• opacity - alpha value from 0 to 1 (requires transparent set to true)
• alphaTest - cutoff value from 0 to 1
• dashArray - 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.Vector2 specifying 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 (if sizeAttenuation is 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:

const mesh = new THREE.Mesh(line, material)
scene.add(mesh)

You can optionally add raycast support with the following.

mesh.raycast = MeshLineRaycast

Declarative use

threejs-meshline has getters and setters that make declarative usage a little easier. This is how it would look like in react/react-three-fiber. You can try it live here.

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

extend({ MeshLine, MeshLineMaterial })

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