MeshLine
A mesh replacement for THREE.Line
. Instead of using GL_LINE, it uses a strip of billboarded triangles. This is a fork of spite/THREE.MeshLine, previously maintained by studio Utsuboco.
How to use
npm install meshline
import * as THREE from 'three'
import { MeshLineGeometry, MeshLineMaterial, raycast } from 'meshline'
const geometry = new MeshLineGeometry()
geometry.setPoints([...])
const material = new MeshLineMaterial({ ... })
const mesh = new THREE.Mesh(geometry, material)
mesh.raycast = raycast
scene.add(mesh)
Assign points
Create a MeshLineGeometry
and pass a list of points into .setPoints()
. Expected inputs are:
Float32Array
THREE.BufferGeometry
Array<THREE.Vector3 | THREE.Vector2 | [number, number, number] | [number, number] | number>
const geometry = new MeshLineGeometry()
const points = []
for (let j = 0; j < Math.PI; j += (2 * Math.PI) / 100)
points.push(Math.cos(j), Math.sin(j), 0)
geometry.setPoints(points)
Note: .setPoints
accepts a second parameter, which is a function to define a variable width for each point along the line. By default that value is 1, making the line width 1 * lineWidth.
// 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
geometry.setPoints(points, (p) => 2 + Math.sin(50 * p)) // makes width sinusoidal
Create a material
const material = new MeshLineMaterial(options)
By default it's a white material of width 1 unit.
MeshLineMaterial
has several attributes to control the appereance:
map
- aTHREE.Texture
to paint along the line (requiresuseMap
set to true)useMap
- tells the material to usemap
(0 - solid color, 1 use texture)alphaMap
- aTHREE.Texture
to use as alpha along the line (requiresuseAlphaMap
set 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)color
-THREE.Color
to paint the line width, or tint the texture withopacity
- alpha value from 0 to 1 (requirestransparent
set 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.Vector2
specifying the canvas size (REQUIRED)sizeAttenuation
- constant lineWidth regardless of distance (1 is 1px on screen) (0 - attenuate, 1 - don't)lineWidth
- float defining width (ifsizeAttenuation
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
.
Form a mesh
const mesh = new THREE.Mesh(geometry, material)
scene.add(mesh)
Raycasting
Raycast can be optionally added by overwriting mesh.raycast
with the one that meshline provides.
import { raycast } from 'meshline'
mesh.raycast = raycast
Declarative use
Meshline can be used declaritively in react-three-fiber. MeshLineGeometry
has a convenience setter/getter for .setPoints()
, points
.
import { Canvas, extend } from '@react-three/fiber'
import { MeshLineGeometry, MeshLineMaterial, raycast } from 'meshline'
extend({ MeshLine, MeshLineMaterial })
function App() {
return (
<Canvas>
<mesh raycast={raycast} onPointerOver={console.log}>
<meshLineGeometry points={[0, 0, 0, 1, 0, 0]} />
<meshLineMaterial lineWidth={1} color="hotpink" />
</mesh>
</Canvas>
)
}
Variable line widths
Variable line widths can be set for each point using the widthCallback
prop.
<meshLineGeometry points={points} widthCallback={(p) => p * Math.random()} />
Types
Add these declarations to your entry point.
import { Object3DNode, MaterialNode } from '@react-three/fiber'
declare module '@react-three/fiber' {
interface ThreeElements {
meshLineGeometry: Object3DNode<MeshLineGeometry, typeof MeshLineGeometry>
meshLineMaterial: MaterialNode<MeshLineMaterial, typeof MeshLineMaterial>
}
}