Meshes

Back to documentation index.

### new Meshes()

Contains methods that create meshes of various geometric shapes and solids, such as cubes, cylinders, and spheres.

An assortment of shapes: a red box, a blue sphere, a bright green 2D ring, and an orange partial ring on the first row; and a yellow 3D ring, a brown cylinder, a dark green square, and a purple cone on the second row. What are normals? A normal is a set of numbers (usually three numbers) describing a particular direction. Generally, a normal’s direction is perpendicular to a surface’s edges, and points up and away from the surface. For 3D graphics libraries to calculate a mesh buffer’s lighting and shading correctly, that mesh buffer must specify normals for all its vertices.

Normals are important in the lighting and shading model. When light hits an object’s surface, how brightly the surface will be lit depends on how directly the light points to the surface. It will be lit the most brightly if the light is directly opposite to its normal, and not at all if the light is perpendicular to the normal or in the same direction as the normal.

In general, vertex normals are 3-dimensional and are defined for a mesh buffer only if it also contains vertex positions.

What are texture coordinates? If a texture (array of memory units) will be applied to a mesh buffer’s geometry, then texture coordinates need to be specified for each vertex in that mesh buffer. In general, a texture coordinate is one of two numbers, called U and V, that map to a specific point in the texture. Each texture coordinate ranges from 0 to 1.

In most 3D graphics pipelines, U coordinates start at the left of the texture (0) and increase to the right (1). In some graphics pipelines, such as OpenGL, V coordinates start by default at the bottom of the texture (0) and increase to the top (1), while in others, such as WebGL, Vulkan, Metal, and Direct3D, V coordinates start by default at the top of the texture and increase to the bottom. Thus, for example, in OpenGL by default, texture coordinates (0, 1) indicate the top left corner of the texture, and texture coordinates (0.5, 0.5) indicate the center of the texture.

In general, texture coordinates describe 2-dimensional points. However, for such texturing tasks as mapping a square to a trapezoid, trios of 3-dimensional texture coordinates (U, V, and Z) are useful to ensure the texturing remains perspective-correct. In this case, the 3-D texture coordinates are converted to 2-D by dividing the U and V components by the Z component. In a fragment shader or pixel shader, this can look like the following code: texCoord.xy/texCoord.z.

Methods

### (static) Meshes.createBox(xSize, ySize, zSize, [inward])

Creates a mesh of a box (rectangular prism), which will be centered at the origin. Will create texture coordinates such that the same texture is used on each face of the box. Texture coordinates are generated assuming that the coordinate (0,0) is at the lower-left corner of the texture and (1,1) is at the upper-right corner. The resulting mesh buffer will use 36 vertex indices divided into 12 triangles, with each face using two triangles. The faces will be ordered as follows: Negative-X axis-facing face, positive-X axis-facing face, negative-Y axis-facing face, positive-Y axis-facing face, negative-Z axis-facing face, positive-Z axis-facing face.

Parameters

Return Value

The generated mesh. (Type: THREE.BufferGeometry)

### (static) Meshes.createBoxEx(box, [inward])

Creates a mesh of a box (rectangular prism) given the box’s smallest and largest coordinates. Will create texture coordinates such that the same texture is used on each face of the box. Texture coordinates are generated assuming that the coordinate (0,0) is at the lower-left corner of the texture and (1,1) is at the upper-right corner. The resulting mesh buffer will use 36 vertex indices divided into 12 triangles, with each face using two triangles. The faces will be ordered as follows: Negative-X axis-facing face, positive-X axis-facing face, negative-Y axis-facing face, positive-Y axis-facing face, negative-Z axis-facing face, positive-Z axis-facing face.

Parameters

Return Value

The generated mesh. Throws an error if “box” is null or contains negative dimensions along any of its axes. (Type: THREE.BufferGeometry)

Examples

The following example creates a wire-frame box of the given corner coordinates (box) and color (color).

var boxMesh=Meshes.createBoxEx(box)
.setColor(color).wireFrame()

### (static) Meshes.createCapsule([radius], [length], [slices], [stacks], [middleStacks], [flat], [inside])

Creates a mesh of a capsule, centered at the origin. The length of the capsule will run along the Z axis. (If the capsule has a high length and a very low radius, it will resemble a 3D line with rounded corners; see the example.)

Will also generate texture coordinates such that the V (vertical) coordinates start from the bottom of the texture and increase from the negative to positive Z axis, and the U (horizontal) coordinates start from the left of the texture and increase from the positive X to positive Y to negative X to negative Y to positive X axis. Texture coordinates are generated assuming that the coordinate (0,0) is at the lower-left corner of the texture and (1,1) is at the upper-right corner.

If the “length” parameter is 0, the X, Y, and Z coordinates of a point on the solid are as described in Meshes.createSphere. See the “Creating Shapes” tutorial.

Parameters

Return Value

The generated mesh. (Type: THREE.BufferGeometry)

Examples

The following method uses createCapsule to create a thin line-like 3D object.

// point1, point2 - end points of the line
// thickness - thickness of the line in units, default 1
function create3DLine(point1,point2,thickness) {
if(thickness==null)thickness=1
var vector=MathUtil.vec3sub(point1,point2);
var dist=MathUtil.vec3length(vector);
var normVector=MathUtil.vec3norm(vector);
var midPoint=MathUtil.vec3lerp(point1,point2,0.5);
var line=Meshes.createCapsule(thickness/2,dist,6,4);
var matrix=MathUtil.quatToMat4(
MathUtil.quatFromVectors([0,0,1],normVector));
matrix[12]=midPoint[0]
matrix[13]=midPoint[1]
matrix[14]=midPoint[2]
return line.transform(matrix);
}

### (static) Meshes.createClosedCylinder(baseRad, topRad, height, slices, stacks, [flat], [inside])

Creates a mesh of a closed cylinder or closed cone. The cylinder’s base will be centered at the origin and its height will run along the positive Z axis. The base and top will be included in the mesh if their radius is greater than 0. Will generate texture coordinates for the cylinder and for the base and top. The base’s and top’s texture coordinates will be such that the texture will be flat as seen from either. Texture coordinates are generated assuming that the coordinate (0,0) is at the lower-left corner of the texture and (1,1) is at the upper-right corner.

See Meshes.createCylinder for information on how texture coordinates for the cylinder (other than the base and top) are generated and how to find the coordinates of a particular point on the cylinder.

See the “Creating Shapes” tutorial.

Parameters

Return Value

The generated mesh. (Type: THREE.BufferGeometry)

Examples

The following method creates a cone that’s closed at its base. 

function createClosedCone(radius,height,slices) {
return Meshes.createClosedCylinder(radius,0,height,slices,1);
}

### (static) Meshes.createCylinder(baseRad, topRad, height, [slices], [stacks], [flat], [inside])

Creates a mesh of a cylinder or cone. The cylinder’s base will be centered at the origin and its height will run along the positive Z axis. The base and top themselves will not be included in the mesh.

Texture coordinates for the cylinder (other than the base) will be generated such that the V (vertical) coordinates start from the bottom of the texture and increase from the origin to the positive Z axis, and the U (horizontal) coordinates start from the left of the texture and increase from the positive X to positive Y to negative X to negative Y to positive X axis. Texture coordinates are generated assuming that the coordinate (0,0) is at the lower-left corner of the texture and (1,1) is at the upper-right corner.

The X, Y, and Z coordinates of a point on the cylinder are (-R\*cos(λ), -R\*sin(λ), H\*φ), where φ = (π/2 + L)/π, L is the latitude in radians, λ is the longitude in radians, H = height, R = baseRad + (topRad - baseRad) \* φ, and west and south latitudes and longitudes are negative. (The formula for converting latitude and longitude is mentioned here because their meaning depends on exactly how the texture coordinates are generated on the cylinder. It assumes that in the texture, longitudes range from -180° to 0° to 180° from left to right, and latitudes range from 90° to 0° to -90° from top to bottom.)

See the “Creating Shapes” tutorial.

Parameters

Return Value

The generated mesh. (Type: THREE.BufferGeometry)

### (static) Meshes.createDisk(inner, outer, [slices], [loops], [inward])

Creates a mesh of a 2D circular disk or regular polygon, possibly with a hole in the middle, centered at the origin. Assuming the Y axis points up, the X axis right, and the Z axis backward from the “eye”, the first vertex in the outer edge of the 2D disk will be at the 12 o’clock position. Will also generate texture coordinates, assuming that the coordinate (0,0) is at the lower-left corner of the texture and (1,1) is at the upper-right corner. See the “Creating Shapes” tutorial.

Parameters

Return Value

The generated mesh. (Type: THREE.BufferGeometry)

### (static) Meshes.createLathe(points, [slices], [flat], [inside])

Creates a mesh of a figure generated by revolving a path of 2-dimensional points about the Z axis.

Texture coordinates will be generated such that the V (vertical) coordinates start from the bottom of the texture and increase along the Z axis in the direction of the given path, and the U (horizontal) coordinates start from the left of the texture and increase from the positive X to positive Y to negative X to negative Y to positive X axis. Texture coordinates are generated assuming that the coordinate (0,0) is at the lower-left corner of the texture and (1,1) is at the upper-right corner.

Parameters

Return Value

The generated mesh. (Type: THREE.BufferGeometry)

### (static) Meshes.createPartialDisk(inner, outer, [slices], [loops], [start], [sweep], [inward])

Creates a mesh of a 2D circular disk or regular polygon or a part of either, possibly with a hole where the middle of the complete disk or polygon would be; the middle of the complete disk or polygon is placed at the origin. Will also generate texture coordinates, assuming that the coordinate (0,0) is at the lower-left corner of the texture and (1,1) is at the upper-right corner. See the “Creating Shapes” tutorial.

Parameters

Return Value

The generated mesh. (Type: THREE.BufferGeometry)

Examples

This method creates a ring or disk striped in two colors.
Image of a disk striped in red and almost-white

// inner, outer - inner and outer radius of the disk
// color1, color2 - each a color vector or string specifying
// one of the two stripe colors
// sections - number of stripes
// sectionCount - number of sections per stripe
function stripedDisk(inner,outer,color1,color2,sections,sectionCount) {
if(sectionCount==null)sectionCount=4
var firstColor=true
var ret=null
var sweep=360.0/sections;
for(var i=0;i<sections;i++) {
var angle=360.0*(i*1.0/sections);
var mesh=Meshes.createPartialDisk(inner,outer,
sectionCount,1,angle,sweep)
.setColor(firstColor ? color1 : color2)
firstColor=!firstColor
ret=ret ? BufferGeometryUtils.mergeGeometries(
[ret,mesh],false) : mesh;
}
return ret;
}

### (static) Meshes.createPlane([width], [height], [widthDiv], [heightDiv], [inward])

Creates a mesh of a 2D rectangle, centered at the origin. The plane’s Z coordinate will be 0. Will also generate texture coordinates that increase toward the positive X and Y axes. The texture coordinates will range from 0 to 1 on each end of the 2D rectangle. Texture coordinates are generated assuming that the coordinate (0,0) is at the lower-left corner of the texture and (1,1) is at the upper-right corner. See the “Creating Shapes” tutorial.

Parameters

Return Value

The generated mesh. (Type: THREE.BufferGeometry)

### (static) Meshes.createPointedStar(points, firstRadius, secondRadius, [inward])

Creates a mesh in the form of a two-dimensional n-pointed star. Will also generate texture coordinates, assuming that the coordinate (0,0) is at the lower-left corner of the texture and (1,1) is at the upper-right corner.

Parameters

Return Value

The generated mesh. (Type: THREE.BufferGeometry)

### (static) Meshes.createSphere([radius], [slices], [stacks], [flat], [inside])

Creates a mesh of a sphere, centered at the origin.

Will also generate texture coordinates such that the V (vertical) coordinates start from the bottom of the texture and increase from the negative to positive Z axis, and the U (horizontal) coordinates start from the left of the texture and increase from the positive X to positive Y to negative X to negative Y to positive X axis. Texture coordinates are generated assuming that the coordinate (0,0) is at the lower-left corner of the texture and (1,1) is at the upper-right corner.

The X, Y, and Z coordinates of a point on the sphere are (-R\*cos(δ)\*cos(λ), -R\*cos(δ)\*sin(λ), R\*sin(δ)), where δ and λ are the latitude and longitude, respectively, in radians, R is the sphere’s radius, and west and south latitudes and longitudes are negative. (The formula for converting latitude and longitude is mentioned here because their meaning depends on exactly how the texture coordinates are generated on the sphere. It assumes that in the texture, longitudes range from -180° to 0° to 180° from left to right, and latitudes range from 90° to 0° to -90° from top to bottom.)

See the “Creating Shapes” tutorial.

Parameters

Return Value

The generated mesh. (Type: THREE.BufferGeometry)

### (static) Meshes.createTorus(inner, outer, [lengthwise], [crosswise], [flat], [inward])

Creates a mesh of a torus (doughnut shape), centered at the origin. Will also generate texture coordinates, assuming that the coordinate (0,0) is at the lower-left corner of the texture and (1,1) is at the upper-right corner. See the “Creating Shapes” tutorial.

Parameters

Return Value

The generated mesh. (Type: THREE.BufferGeometry)

### (static) Meshes.lineLoopIndices(vertexCount)

Creates an array of vertex indices corresponding to triangles that make up a line loop, a series of vertices that make up a connected line segment path, with the last point also connected to the first.

Parameters

Return Value

Array of vertex indices corresponding to line segments that make up the line loop. Every two indices in the array is a separate line segment. Returns an empty array if ‘vertexCount’ is less than 2. (Type: Array.<number>)

Examples

The following example sets appropriate indices for a mesh buffer with vertices ordered in line loop vertex order.

mesh.setIndices(
Meshes.lineLoopIndices(mesh.vertexCount())
.map(x=>mesh.getIndex(x)));

### (static) Meshes.lineStripIndices(vertexCount)

Creates an array of vertex indices corresponding to triangles that make up a line strip, a series of vertices that make up a connected line segment path.

Parameters

Return Value

Array of vertex indices corresponding to line segments that make up the line strip. Every two indices in the array is a separate line segment. Returns an empty array if ‘vertexCount’ is less than 2. (Type: Array.<number>)

Examples

The following example sets appropriate indices for a mesh buffer with vertices ordered in line strip vertex order.

mesh.setIndices(
Meshes.lineStripIndices(mesh.vertexCount())
.map(x=>mesh.getIndex(x)));

### (static) Meshes.quadStripIndices(vertexCount)

Creates an array of vertex indices corresponding to triangles that make up a strip of quadrilaterals. For a quadrilateral strip, the first 4 vertices make up the first quadrilateral, and each additional quadrilateral is made up of the last 2 vertices of the previous quadrilateral and 2 new vertices.

Parameters

Return Value

Array of vertex indices corresponding to triangles that make up the quadrilateral strip. Every three indices in the array is a separate triangle. Returns an empty array if ‘vertexCount’ is less than 4. If ‘vertexCount’ is not divisible by 2, the excess vertex is ignored. (Type: Array.<number>)

Examples

The following example sets appropriate indices for a mesh buffer with vertices ordered in quadrilateral strip vertex order.

mesh.setIndices(
Meshes.quadStripIndices(mesh.vertexCount())
.map(x=>mesh.getIndex(x)));

### (static) Meshes.quadsIndices(vertexCount)

Creates an array of vertex indices corresponding to triangles that make up a series of quadrilaterals, where every 4 vertices is a separate quadrilateral.

Parameters

Return Value

Array of vertex indices corresponding to triangles that make up the quadrilaterals. Every three indices in the array is a separate triangle. Returns an empty array if ‘vertexCount’ is less than 4. If ‘vertexCount’ is not divisible by 4, any excess vertices are ignored. (Type: Array.<number>)

Examples

The following example sets appropriate indices for a mesh buffer with vertices ordered in quadrilateral vertex order.

mesh.setIndices(
Meshes.quadsIndices(mesh.vertexCount())
.map(x=>mesh.getIndex(x)));

### (static) Meshes.triangleFanIndices(vertexCount)

Creates an array of vertex indices corresponding to triangles that make up a triangle fan or convex polygon. For triangle fans and convex polygons, the first 3 vertices make up the first triangle, and each additional triangle is made up of the last vertex, the first vertex of the first trangle, and 1 new vertex.

Parameters

Return Value

Array of vertex indices corresponding to triangles that make up the triangle fan or convex polygon. Every three indices in the array is a separate triangle. Returns an empty array if ‘vertexCount’ is less than 3. (Type: Array.<number>)

Examples

The following example sets appropriate indices for a mesh buffer with vertices ordered in triangle fan vertex order.

mesh.setIndices(
Meshes.triangleFanIndices(mesh.vertexCount())
.map(x=>mesh.getIndex(x)));

### (static) Meshes.triangleStripIndices(vertexCount)

Creates an array of vertex indices corresponding to triangles that make up a triangle strip. For a triangle strip, the first 3 vertices make up the first triangle, and each additional triangle is made up of the last 2 vertices and 1 new vertex.

Parameters

Return Value

Array of vertex indices corresponding to triangles that make up the triangle strip. Every three indices in the array is a separate triangle. Returns an empty array if ‘vertexCount’ is less than 3. (Type: Array.<number>)

Examples

The following example sets appropriate indices for a mesh buffer with vertices ordered in triangle strip vertex order.

mesh.setIndices(
Meshes.triangleStripIndices(mesh.vertexCount())
.map(x=>mesh.getIndex(x)));

Back to documentation index.