API Docs

Class: PolyMesh

PD. PolyMesh

A mesh for rendering surfaces and outlines with reusable shared attributes that can dynamically expand and contract as the geometry changes.

In THREE, Mesh objects can only be rendered exclusively as TRIANGLES, LINES or POINTS. To render both the surfaces (TRIANGLES) and edge outlines (LINES) of an object requires maintaining two separate meshes. This class essentially does that, but ensures that both meshes share the same vertex attribute buffers but have separate index buffers.

Dynamic Allocation

This class also manages the dynamic re-allocation of ArrayBuffers. THREE uses TypedArrays to store vertices, normals, colors, texture coordinates and indices in its buffered meshes. Each of these arrays must be re-allocated if the number of vertices or indices changes. When interactively dragging a point or line within a model, this could happen up to 60 times a second, and for several different meshes at once.

For example, interactively dragging a wall junction that defines a curve could significantly expand or contract the number of vertices in its path line on each update. This would also affect the number of vertices in the internal and external offset lines that define the outline of the wall in plan, as these are dependant on the path line. In a 3D model, this would in turn affect both the number of vertices and the number of triangle/line indices in the shell object that defines all the wall surfaces. With three (3) vertex attribute buffers (position, normal and color) and one index buffer per mesh, and up to six (6) meshes needing to be updated, this is certainly worth trying to optimise.

Fortunately, this can be dealt with by pre-allocating a reasonably large amount of memory for each TypedArray so that it can tolerate some reasonable variation without needing to be resized. The THREE.BufferGeometry.setDrawRange() method is then used to limit rendering to only the current content of the buffer and ignore any leftover. If the content expands over the limit and more space is required, then the arrays will be expanded in large enough chunks to meet the requirements only once or twice per interactive event. These arrays can then be reduced to a more optimal size later when the application becomes idle. This approach can significantly reduce or even eliminate the need for garbage collection during highly dynamic interactions.

Also, to help dynamically construct geometry, this class also provides methods for creating primitives such as quads, line strips, line loops, triangle strips and triangle fans. To reuse the mesh with new geometry, simply call reset() first, then add the geometry, and then call update() to refresh the buffers.

new PolyMesh( [config])

Creates a new dynamic mesh.

Parameters:
Name Type Argument Description
config object <optional>

An optional configuration object.
Properties of config:
Name Type Argument Description
name number <optional>

A human-readable name for the mesh.
sizeIncrement number <optional>

An amount by which dynamic buffers incrementally expand their capacity, defaults to 4096.
maxVertices number <optional>

An initial size for the vertex attribute buffers, defaults to 4096 (48KB).
maxTriangles number <optional>

An initial size for the triangle index buffer, defaults to 4096 (48KB).
maxLines number <optional>

An initial size for the lines index buffer, defaults to 4096 (32KB).
surfaceMaterial THREE.Material <optional>

An optional material to use for rendering triangulated surfaces.
surfaceOpacity number <optional>

An opacity for mesh surfaces if using the default material (0-1), defaults to 1.
outlineMaterial THREE.Material <optional>

An optional material to use for rendering outlines.
outlineOpacity number <optional>

An opacity for mesh outlines if using the default material (0-1), defaults to 1.
hasNormals boolean <optional>

Whether or not to include a buffer for vertex normals.
hasColors boolean <optional>

Whether or not to include a buffer for vertex colors.
hasUV boolean <optional>

Whether or not to include a buffer for UV texture coordinates.
lineNormals boolean <optional>

Whether or not to include vertex normal attributes with line segment geometry.
lineColors boolean <optional>

Whether or not to include vertex color attributes with line segment geometry.
renderOrder number <optional>

Sets the order in which this mesh will be rendered in the scene (0 to Infinity), defaults to 1.
matrixAutoUpdate boolean <optional>

Whether or not the world transformation matrix for the mesh is calculated each frame, defaults to false.
visible boolean <optional>

Whether or not the mesh will be rendered in subsequent frames, defaults to true.
userData object <optional>

An object that can be used to store custom data about the mesh, available via the userData property.
Author:
  • drajmarsh
Examples
// Emulating immediate mode.
const mesh1 = new PD.PolyMesh({ hasColors: true, hasUV: true });
mesh1.begin(PD.PRIMITIVE.QUADS)
     .normal(0, 0, 1)
     .color(1.0, 0.0, 0.0, 1.0)
     .uv(0, 0)
     .vertex(0, 0, 0)
     .uv(1, 0)
     .vertex(10, 0, 0)
     .uv(1, 1)
     .vertex(10, 10, 0)
     .uv(0, 1)
     .vertex(0, 10, 0)
     .end()
     ;

/// ...

mesh1.update();
// With outline example.
const mesh2 = new PD.PolyMesh();

/// ...

mesh2.reset();

/// ...

mesh2.setNormal(0, 0, 1);
mesh2.setColor(1.0, 0.0, 0.0);
let v1 = mesh2.addVertex(0, 0, 0);
let v2 = mesh2.addVertex(10, 0, 0);
let v3 = mesh2.addVertex(10, 10, 0);
let v4 = mesh2.addVertex(0, 10, 0);
mesh2.addTriangle(v1, v2, v3);
mesh2.addTriangle(v1, v3, v4);
mesh2.addLine(v1, v2);
mesh2.addLine(v2, v3);
mesh2.addLine(v3, v4);
mesh2.addLine(v4, v1);

/// ...

mesh2.update();
// Example with colors and texture coordinates.
const mesh3 = new PD.PolyMesh({ hasColors: true, hasUV: true });
const normal3 = [ 0, 0, 1 ];

/// ...

mesh3.reset();

/// ...

mesh3.addQuad(
    mesh3.addVertexFromArrays([ 0,  0, 0], [1.0, 0.0, 0.0, 1.0], normal3, [0, 0]),
    mesh3.addVertexFromArrays([10,  0, 0], [0.0, 1.0, 0.0, 1.0], normal3, [1, 0]),
    mesh3.addVertexFromArrays([10, 10, 0], [0.0, 0.0, 1.0, 1.0], normal3, [1, 1]),
    mesh3.addVertexFromArrays([ 0, 10, 0], [1.0, 0.0, 1.0, 1.0], normal3, [0, 1])
);

let index = mesh3.vertexCount();
mesh3.addLineLoop(index - 4, index - 3, index - 2, index - 1);

/// ...

mesh3.update();
// Example using a data object.
const mesh4 = new PD.PolyMesh({ hasColors: true, hasNormals: true, hasUV: true });

/// ...

mesh4.reset();

/// ...

const vtx_data = {};
vtx_data.pos = [0, 0, 0];
vtx_data.normal = [-1, -1, 1];
vtx_data.color = [1.0, 0.0, 0.0, 1.0];
vtx_data.uv = [0, 0];
mesh4.addVertexFromObject(vtx_data);

vtx_data.pos = [10, 0, 0];
vtx_data.normal = [1, -1, 1];
vtx_data.color = [0.0, 1.0, 0.0, 1.0];
vtx_data.uv = [1, 0];
mesh4.addVertexFromObject(vtx_data);

vtx_data.pos = [10, 10, 0];
vtx_data.normal = [1, 1, 1];
vtx_data.color = [0.0, 0.0, 1.0, 1.0];
vtx_data.uv = [1, 1];
mesh4.addVertexFromObject(vtx_data);

vtx_data.pos = [0, 10, 0];
vtx_data.normal = [-1, 1, 1];
vtx_data.color = [1.0, 0.0, 1.0, 1.0];
vtx_data.uv = [0, 1];
mesh4.addVertexFromObject(vtx_data);

let index = mesh4.vertexCount();
mesh4.addQuad(index - 4, index - 3, index - 2, index - 1);
mesh4.addLineLoop(index - 4, index - 3, index - 2, index - 1);

/// ...

mesh4.update();

Extends

  • THREE.Mesh

Members

:THREE.Box3

boundingBox

Store a reference to the geometry bounding box when it is created.

This is a direct reference to this.geometry.boundingBox.

Type
  • THREE.Box3
:number

defaultAlpha

The default opacity to associate with vertex colors, defaults to 1.

Type
  • number
:THREE.Color

defaultColor

The default colour of mesh triangles, stored as an {r,g,b} color array.

If not specified, this value defaults to {0.8, 0.8, 0.8}. It can be set at any time using the PD.PolyMesh#setColor and PD.PolyMesh#color methods.

If the mesh has a colors attribute buffer, the current value of this property is added as the default for each new vertex. If not, it is used as a uniform by the shader that renders the mesh as well as during ray tracing and other types of mesh analysis.

Type
  • THREE.Color
:THREE.Vector3

defaultNormal

The default surface normal stored as an {x,y,z} vector object.

If not specified, this value defaults to {0, 0, 1}. It can be set at any time using the PD.PolyMesh#setNormal and PD.PolyMesh#normal methods.

If the mesh has a normals attribute buffer, the current value of this property is added as an attribute for each new vertex. If not, it is used as a uniform by the shader that renders the mesh as well as during ray tracing and other types of mesh analysis.

Type
  • THREE.Vector3
:THREE.Vector2

defaultUV

The default texture coordinate of the vertex, stored as a {u,v} array.

If not specified, this value defaults to {0.0, 0.0}. It can be set at any time using the PD.PolyMesh#setUV and PD.PolyMesh#uv methods.

If the mesh has a uvs attribute buffer, the current value of this property is added as an attribute for each new vertex.

Type
  • THREE.Vector2
:THREE.BufferGeometry

geometry

Assembles attributes index buffers for triangles.

Type
  • THREE.BufferGeometry
:boolean

hasAlpha

Whether or not to use an RGBA buffer instead of RGB for vertex color attributes.

Type
  • boolean
:boolean

hasChanged

Whether or not the geometry has recently changed and the buffer attributes need regeneration.

Type
  • boolean
:boolean

hasColors

Whether or not to include a buffer for vertex color attributes.

Type
  • boolean

hasNormals

Whether or not to include a buffer for vertex normal attributes. {boolean}

:boolean

hasUV

Whether or not to include a buffer for vertex texture coordinates.

Type
  • boolean
:boolean

isPolyMesh <readonly>

A flag identifying this object as a dynamic mesh.

Type
  • boolean
:boolean

lineColors

Whether or not to include colors in outline buffer geometry.

Type
  • boolean
:number

lineCount

Stores the number of lines in the outline mesh.

Type
  • number
:boolean

lineNormals

Whether or not to include normals in outline buffer geometry.

Type
  • boolean
:THREE.Material

material

The material for rendering surfaces.

Type
  • THREE.Material
:number

maxVertices

The maximum addressable vertex attribute index.

Type
  • number
:THREE.LineSegments

meshOutline

The line segments used to display the edge outlines of the object.

This line segments object is stored as the first child of this mesh, so that all transformations are automatically applied.

Type
  • THREE.LineSegments
:THREE.Color

outlineColor

The color of the outline material.

In THREE, material colors act as a global tint that affects all vertices in the mesh when rendering its outline, regardless of their individually assigned vertex color.

Type
  • THREE.Color
:THREE.BufferGeometry

outlineGeometry

Assembles attributes index buffers for lines.

Type
  • THREE.BufferGeometry
:THREE.Material

outlineMaterial

The material for rendering outlines.

Type
  • THREE.Material
:number

outlineOpacity

The opacity of the outline material.

Type
  • number
:number

sizeIncrement

The amount by which mesh buffers should increment when resizing.

Type
  • number
:THREE.Color

surfaceColor

The color of the surface material.

In THREE, material colors act as a global tint that affects all vertices in the mesh when rendering its surface, regardless of their individually assigned vertex color.

Type
  • THREE.Color
:number

surfaceOpacity

The opacity of the surface material.

Type
  • number
:number

triangleCount

Stores the current number of triangles in the surface mesh.

Type
  • number
:object

userData

An simply POJO for holding arbitrary data or attributes.

Use this property to add any additional properties or attributes that you need to be associated with this mesh. Do not add them to the object itself to maintain any system class optimisations.

Type
  • object
:number

vertexCount

Stores the current number of vertices in each mesh.

Type
  • number
:THREE.BufferGeometry

placeholderGeometry <static>

Use this as a placeholder for subclasses of THREE.Mesh when you need to create geometry from a configuration object, so don't want the super class constructor to do it yet.

We can't use null in such a situation as THREE.Mesh#updateMorphTargets() requires a valid geometry.

Type
  • THREE.BufferGeometry
Example
MyObject = class extends THREE.Mesh {

    constructor() {

        super(PD.PolyMesh.placeholderGeometry, PD.PolyMesh.placeholderMaterial);

        /// ...

    };

    /// ...

};
:THREE.BufferGeometry

placeholderMaterial <static>

Use this as a placeholder for subclasses of THREE.Mesh when you need to create a material from a configuration object.

We shouldn't use null in such situations as THREE.Mesh#updateMorphTargets() already requires a valid geometry, and future THREE versions may also require a valid material.

Type
  • THREE.BufferGeometry
Example
MyObject = class extends THREE.Mesh {

    constructor() {

        super(PD.PolyMesh.placeholderGeometry, PD.PolyMesh.placeholderMaterial);

        /// ...

    };

    /// ...

};

Methods

addArrowInLocalCoords(coords, size [, width] [, wings])

Adds a new line with an arrowhead.

     :     size     :
   - + - - - - - - -+ -
     :              :
     :              _.-'/
     :          _.-'.  /
     :      _.-'    : /
     '  _.-'        '/       :
     +' -  -  -  -  +  - - - + -
     .   '-._        \       :
     :       '-._     \      : width * size
     :           '-._  \     :
     :               '-.\  - + -
     :                  .    :
   - + - - - -  - - - - + -
     :   wings * size   :
Parameters:
Name Type Argument Default Description
coords PD.LocalCoordinates

The local coordinates system to use.
size number

The size of the arrow head, in model coordinates.
width number <optional>
 0.25

The width of the arrow head relative to its length.
wings number <optional>
 1

The extension of arrow head corners relative to its length.
Returns:

Returns the starting index of the first of 3 newly added lines.

Type
number

addArrowLine(v1, v2, size [, ratio])

Adds a new line with an arrowhead.

                         ''--..__
       ----------------------------+
                         __..--''
Parameters:
Name Type Argument Default Description
v1 number

The attribute index of the vertex that starts the line.
v2 number

The attribute index of the vertex that ends the line.
size number

The size of the arrow head extension, in model coordinates.
ratio number <optional>
 0.25

The ratio between the half the width of the arrow head and its length.
Returns:

Returns the starting index of the first of 3 newly added lines.

Type
number

addBox(box)

Adds the specified box as a quad mesh.

Parameters:
Name Type Description
box THREE.Box3

The bounding box to add.
Returns:

Returns the index of the first new triangle.

Type
number

addBoxDashedDraftingOutline(box, pointSize [, expand])

Adds the specified box edges to this mesh.

Parameters:
Name Type Argument Description
box THREE.Box3

The bounding box containing the face.
pointSize number

The reference size of a small object, in model coordinates.
expand number <optional>

An optional amount to expand the box in the X and Y axis, in model coordinates.
Returns:

Returns the index of the first new line.

Type
number

addBoxDashedOutline(box, pointSize [, expand])

Adds the specified box edges to this mesh.

Parameters:
Name Type Argument Description
box THREE.Box3

The bounding box containing the face.
pointSize number

The reference size of a small object, in model coordinates.
expand number <optional>

An optional amount to expand the box in the X and Y axis, in model coordinates.
Returns:

Returns the index of the first new line.

Type
number

addBoxFaceAsDashedDraftingLineLoop(box, pointSize [, face] [, expand])

Adds the specified box face as a line loop to this mesh.

Parameters:
Name Type Argument Description
box THREE.Box3

The bounding box containing the face.
pointSize number

The reference size of a small object, in model coordinates.
face PD.AXIS <optional>

The axis of the face, defaults to PD.AXIS.Z_NEG.
expand number <optional>

An optional amount to expand the box in the X and yY axis, in model coordinates.
Returns:

Returns the index of the first new line.

Type
number

addBoxFaceAsDashedLineLoop(box, pointSize [, face] [, expand])

Adds the specified box face as a line loop to this mesh.

Parameters:
Name Type Argument Description
box THREE.Box3

The bounding box containing the face.
pointSize number

The reference size of a small object, in model coordinates.
face PD.AXIS <optional>

The axis of the face, defaults to PD.AXIS.Z_NEG.
expand number <optional>

An optional amount to expand the box in the X and yY axis, in model coordinates.
Returns:

Returns the index of the first new line.

Type
number

addBoxFaceAsLineLoop(box, face)

Adds the specified box face as a line loop to this mesh.

Parameters:
Name Type Default Description
box THREE.Box3

The bounding box containing the face.
face PD.AXIS 0

The axis of the face, defaults to PD.AXIS.Z_NEG.
Returns:

Returns the index of the first new line.

Type
number

addBoxFaceAsQuad(box, face)

Adds the specified box face as a quad to this mesh.

Parameters:
Name Type Description
box THREE.Box3

The bounding box containing the face.
face PD.AXIS

The axis of the face, defaults to PD.AXIS.Z_NEG.
Returns:

Returns the index of the first new triangle.

Type
number

addCircle(center, radius)

Adds a new filled circle to this mesh.

Parameters:
Name Type Description
center number | THREE.Vector3

The position of the circle center, as a vertex index or 3D point.
radius number

The outer or external radius of the circle.
Returns:

Returns the index of the first new triangle.

Type
number

addCircleInLocalCoords(coords, radius)

Adds a new filled circle to this mesh using local coordinates.

Parameters:
Name Type Description
coords PD.LocalCoordinates

The position and orientation of the circle.
radius number

The outer or external radius of the circle.
Returns:

Returns the index of the first new triangle.

Type
number

addCircleOutline(center, radius)

Adds a new circle line to this mesh.

Parameters:
Name Type Description
center number | THREE.Vector3

The position of the circle center, as a vertex index or 3D point.
radius number

The outer or external radius of the circle.
Returns:

Returns the index of the first new lne.

Type
number

addDashedDraftingLine(v1, v2, size)

Adds a new architectural-style extended dashed line.

Dashed drafting lines are normal dashed lines with their end points extended out by a given distance to clearly delineate intersection points.

Parameters:
Name Type Description
v1 number

The index of the first vertex.
v2 number

The index of the second vertex.
size number

The size of the extended overrun, in model coordinates.
Returns:

Returns the index of the new line, or -1 if zero length.

Type
number

addDashedDraftingLines(vertices, size [, closed])

Appends a sequence of dashed drafting lines joining the given vertex indices.

If the closed argument is true, the last point will be connected back to the first.

Parameters:
Name Type Argument Default Description
vertices Array

An array of vertex indices or THREE.Vector3 objects.
size number

The size of each dash in model units.
closed boolean <optional>
 false

Whether or not to close the loop.
Returns:

Returns the index of the first added line.

Type
number

addDashedLine(v1, v2, size)

Adds a new dashed line.

Parameters:
Name Type Description
v1 number

The index of the vertex that starts the line.
v2 number

The index of the vertex that ends the line.
size number

The size of each dash in model units.
Returns:

Returns the index of the first added line.

Type
number

addDashedLineWithVariableGap(v1, v2, size [, gap])

Adds a new dashed line with separately specified gap width.

Parameters:
Name Type Argument Default Description
v1 number

The index of the vertex that starts the line.
v2 number

The index of the vertex that ends the line.
size number

The size of each dash, in model units.
gap number <optional>
 1

An optional gap width, given as a fractional value to be multiplied by size.
Returns:

Returns the index of the first added line.

Type
number

addDashedLines(vertices, size [, closed])

Appends a sequence of lines joining the given vertex indices.

If the closed argument is true, the last point will be connected back to the first.

Parameters:
Name Type Argument Default Description
vertices Array

An array of vertex indices or THREE.Vector3 objects.
size number

The size of each dash in model units.
closed boolean <optional>
 false

Whether or not to close the loop.
Returns:

Returns the index of the first added line.

Type
number

addDraftingLine(v1, v2, size)

Adds a new architectural-style extended line.

Drafting lines are normal lines with their end points extended out by a given distance to clearly delineate intersection points.

Parameters:
Name Type Description
v1 number

The index of the first vertex.
v2 number

The index of the second vertex.
size number

The size of the extended overrun, in model coordinates.
Returns:

Returns the index of the new line.

Type
number

addDraftingLines(vertices, size [, closed])

Appends a sequence of architectural-style extended lines joining the given vertex indices.

Drafting lines are normal lines with their end points extended out by a given distance to clearly delineate intersection points.

If the closed argument is true, the last point will be connected back to the first.

Parameters:
Name Type Argument Default Description
vertices Array

An array of vertex indices or THREE.Vector3 objects.
size number

The size of the extended overrun, in model coordinates.
closed boolean <optional>
 false

Whether or not to close the loop.
Returns:

Returns the index of the first added line.

Type
number

addHilightBox(box, pointSize)

Adds a new highlighted bounding box to this mesh.

Parameters:
Name Type Description
box THREE.Box3

The bounding box to highlight.
pointSize number

The reference size of a small object, in model coordinates.
Returns:

Returns the index of the first new triangle.

Type
number

addHilightLine(v1, v2, pointSize [, extension])

Adds a triangulated line made from two quads in an cross-section.

             +
            /|
        +--/ +----+
       /  + /    /
      /   |/    /
     +----+----+
          |/
          +
Parameters:
Name Type Argument Description
v1 number

The index of the first vertex.
v2 number

The index of the second vertex.
pointSize number

The reference size of a small object, in model coordinates.
extension number <optional>

The size of the extended overrun, in model coordinates.
Returns:

Returns the index of the new line.

Type
number

addHilightMarker(v1, pointSize)

Adds a 3D diamond shaped marker at the given position and size.

Parameters:
Name Type Description
v1 number

The index of the first vertex.
pointSize number

The reference size of a small object, in model coordinates.
Returns:

Returns the index of the new line.

Type
number

addHilightMarkerInLocalCoords(coords, pointSize)

Adds a 3D diamond shaped marker in the given local coordinates.

Parameters:
Name Type Description
coords PD.LocalCoordinates

The position and orientation of the circle.
pointSize number

The reference size of a small object, in model coordinates.
Returns:

Returns the index of the new line.

Type
number

addHilightRect(box, pointSize)

Adds a new highlighted rectangle to this mesh.

Parameters:
Name Type Description
box THREE.Box3

The bounding box to highlight.
pointSize number

The reference size of a small object, in model coordinates.
Returns:

Returns the index of the first new triangle.

Type
number

addIcosohedron(center, radius)

Adds a diamond shaped marker at the given position and size.

Parameters:
Name Type Description
center THREE.Vector3 | number

The position or vertex index of the center point.
radius number

The radius of the icosohedron.
Returns:

Returns the index of first triangle.

Type
number

addJitteredLine(v1, v2, size [, jitter])

Adds a new jittered or hand-drawn line.

Parameters:
Name Type Argument Description
v1 number

The index of the vertex that starts the line.
v2 number

The index of the vertex that ends the line.
size number

The increment between jittered points in model units.
jitter number <optional>

The amount of jitter in model units, defaults to half size.
Returns:

Returns the index of the first added line.

Type
number

addLevelIndicator(center, radius [, axis])

Adds a new circular level indicator circular to this mesh.

                    |
              , - ~ | ~ - ,
          , '       | * * * ' ,
        ,           | * * * * * ,
       ,            | * * * * * *,
      ,             | * * * * * * ,
    --,-------------x-------------,---------------------
      , * * * * * * |             ,
       ,* * * * * * |            ,
        , * * * * * |           ,
          , * * * * |         ,
            ' - , _ | _ , - '
                    |
Parameters:
Name Type Argument Description
center THREE.Vector3

The position of the indicator circle center.
radius number

The outer or external radius of the indicator.
axis PD.AXIS <optional>

The axis to draw the indicator in. defaults to XY plane (Z_POS).
Returns:

Returns the index of the first new triangle.

Type
number

addLine(v1, v2)

Appends a new line to the surface mesh.

Parameters:
Name Type Description
v1 number

The index of the first vertex.
v2 number

The index of the second vertex.
Returns:

Returns the index of the new line.

Type
number

addLineLoop(indices)

Appends a loop of lines joining the given vertex indices.

Parameters:
Name Type Description
indices Array

Send either an array of indexes or multiple arguments.
Returns:

Returns the index of the first added line.

Type
number

addLineStrip(indices)

Appends a sequence of one or more lines joining the given vertex indices.

Parameters:
Name Type Description
indices number | Array

Send either an array of indexes or multiple arguments.
Returns:

Returns the index of the first added line.

Type
number

addMarkerDiamond(v1, pointSize)

Adds a flat diamond shaped marker at the given position and size.

Parameters:
Name Type Description
v1 number

The index of the first vertex.
pointSize number

The reference size of a small object, in model coordinates.
Returns:

Returns the index of the new line.

Type
number

addMarkerPlus(v1, size)

Adds an orthographic cross indicator at the given position.

Parameters:
Name Type Description
v1 number

The index of the vertex.
size number

The size of the cross lines in model units.
Returns:

Returns the index of the first of two new lines.

Type
number

addNorthArrow(center, radius, angle)

Appends a loop of lines creating a circle and direction arrow at the given point.

                    :
              , - ~ : ~ - ,
          , '      .:.      ' ,
        ,         .*: .         ,
       ,         .**:  .         ,
      ,         .***|   .         ,
    - , - - - -.****x - -.- - - - , -
      ,       .*****|     .       ,
       ,     .******:      .     ,
        ,   .***_.-':'-._   .   ,
          ,._.-'    :    '-._.,
            ' - , _ : _ , - '
                    :
Parameters:
Name Type Description
center THREE.Vector3

The position of the center in model space.
radius number

The radius of the north arrow in model units.
angle number

The angle of north clockwise from _Y, in radians.
Returns:

Returns the index of the first added line.

Type
number

addPrimitive(mode, vertices)

Adds a new primitive with the given primitive type and vertex positions.

Internally, this method surrounds the geometry with calls to the begin() and end() methods for creating immediate-mode geometry. Refer to those methods for more details.

The minimum number of vertices for each primitive is 1 for a point, 2 for a line and 3 for a triangle. Modes that require certain multiples of vertices are gl.LINES (2) and gl.TRIANGLES (3).

Parameters:
Name Type Description
mode PD.PRIMITIVE

Specifies the primitive type to be generated.
vertices Array

An array of {x,y,z} objects or [x,y,z] arrays.
Throws:

Occurs if mode is invalid or vertices is not an array of acceptable vertices.

Type
TypeError
Returns:

Returns the index of the first added triangle.

Type
number

addQuad(x, y, z)

Appends a new vertex to each mesh's attribute buffers.

Parameters:
Name Type Description
x number

The position of the vertex in the X-axis.
y number

The position of the vertex in the Y-axis.
z number

The position of the vertex in the Z-axis.
Returns:

Returns the index of the first added triangle.

Type
number

addShape(shape, position, scale [, outline])

Adds a shape such as a font glyph to the mesh.

Parameters:
Name Type Argument Description
shape THREE.Shape

The shape to add to the mesh.
position THREE.Vector3

The position of the shape in model coordinates.
scale THREE.Vector3 | number

The scale factor to apply to the shape.
outline boolean <optional>

Whether or not to add the shape outline, defaults to false.
Returns:

Returns the index of the first triangle line.

Type
number

addThickCircle(center, radius, thickness)

Adds a new thick lined horizontal circle to this mesh.

Parameters:
Name Type Description
center THREE.Vector3

The position of the circle center.
radius number

The outer or external radius of the circle.
thickness number

The width of the outline of the circle.
Returns:

Returns the index of the first new triangle.

Type
number

addThickCircleInLocalCoords(coords, radius, thickness)

Adds a new thick lined horizontal circle to this mesh.

Parameters:
Name Type Description
coords PD.LocalCoordinates

The position and orientation of the circle.
radius number

The outer or external radius of the circle.
thickness number

The width of the outline of the circle.
Returns:

Returns the index of the first new triangle.

Type
number

addThickClipperPathLoop(path, size [, Z])

Adds a thick line from a ClipperLib path by creating each segment as a triangulated quad.

Parameters:
Name Type Argument Default Description
path Array

An array of two or more ClipperPath points.
size number

The width of the line, in model coordinates.
Z number <optional>
 0

An optional position of the path in the Z-axis, defaults to zero.
Returns:

Returns the index of the first triangle added.

Type
number

addThickLine(v1, v2, pointSize [, extension])

Adds a triangulated line made from a quad and two end triangles.

Parameters:
Name Type Argument Description
v1 number

The index of the first vertex.
v2 number

The index of the second vertex.
pointSize number

The reference size of a small object, in model coordinates.
extension number <optional>

The size of the extended overrun, in model coordinates.
Returns:

Returns the index of the first added triangles.

Type
number

addThickLines(vertices, size [, endcap])

Adds a thick line by creating each segment as a triangulated quad.

Parameters:
Name Type Argument Description
vertices Array

An array of two or more THREE.Vector3 or similar.
size number

The width of the line, in model coordinates.
endcap PD.ENDCAP <optional>

How to start/end the line, defaults to PD.ENDCAP.CLOSED.
Returns:

Returns the index of the first triangle added.

Type
number

addThickRect(box, thickness)

Adds a new thick lined rectangle to this mesh.

Parameters:
Name Type Description
box THREE.Box3

The bounding box to highlight.
thickness number

The width of the outline of the box.
Returns:

Returns the index of the first new triangle.

Type
number

addTriangle(v1, v2, v3)

Appends a new triangle to the surface mesh.

Parameters:
Name Type Description
v1 number

The index of the first vertex.
v2 number

The index of the second vertex.
v3 number

The index of the third vertex.
Returns:

Returns the index of the new triangle.

Type
number

addVertex(x, y, z)

Appends a new vertex position.

This method adds a new vertex, setting its positions and using the previously set normal, color and/or uv attribute values.

Parameters:
Name Type Description
x number | THREE.Vector3

The position of the vertex in the X-axis, a vector or an array.
y number

The position of the vertex in the Y-axis.
z number

The position of the vertex in the Z-axis.
Returns:

Returns the index of the new vertex.

Type
number

addVertexFromArrays(pos_array [, color_array] [, normal_array] [, uv_array])

Appends a new vertex from a [x,y,z] array with optional color, normal and uv.

The pos_array argument must be an array with three value in the form [x,y,z].

The color_array argument must be an array with three value in the form [r,g,b] with each component being a value between zero and on (0 to 1).

The normal_array argument must be an array with three value in the form [nx,ny,nz] representing a unit normal (magnitude of 1) with each component being a value between zero and on (0 to 1).

The uv_array argument must be an array with two value in the form [u,v] with each component being a value between zero and on (0 to 1).

Parameters:
Name Type Argument Description
pos_array Array

This must be given as a [x,y,z] coordinate array.
color_array Array <optional>

An optional color value given as a [r,g,b,a] color array, otherwise defaultColor is used.
normal_array Array <optional>

An optional vertex normal given as a [x,y,z] vector array, otherwise defaultNormal is used.
uv_array Array <optional>

An optional texture coordinate given as a [u,v] array, otherwise defaultUV is used.
Returns:

Returns the index of the new vertex.

Type
number

addVertexFromObject(data)

Adds a new vertex based on properties of the given object.

NOTE: The arrays given for each property are stored directly, not copied. This allows you to share the same positions, normals, colors and texture coordinates across multiple vertices without creating many copies of the same array. This can be very memory efficient as complex rectilinear meshes often require a large number of vertices which all share a relatively small number of positions, normals, colors and uvs.

However, this means that you should take great care when altering any of the vertex data arrays themselves after they have been assigned as that data will also change for every other vertex assigned that same array. Instead, it is usually safer to assign new data arrays when modifying a vertex.

Parameters:
Name Type Description
data object

An object containing pos, normal, color and/or uv properties.
Properties of data:
Name Type Argument Description
pos Array

A 3D position given as a [x,y,z] coordinate array in model units.
normal Array <optional>

An optional vertex normal given as a normalised [x,y,z] array in the range 0 to 1, otherwise this.defaultNormal is used.
color Array <optional>

An optional color value given as a [r,g,b,a] array in the range 0 to 1, otherwise this.defaultColor is used.
uv Array <optional>

An optional texture coordinate given as a [u,v] array in the range 0 to 1, otherwise this.defaultUV is used.
Throws:

Throws an error if data.pos property is not an array.

Type
TypeError
Returns:

Returns the index of the newly added vertex, or -1 if not successfully added.

Type
number

addVertexWithAttribs(vertex)

Appends a new vertex from a [x,y,z] array with optional color, normal and uv.

The pos_array argument must be an array with three value in the form [x,y,z].

The normal_array argument must be an array with three value in the form [nx,ny,nz] representing a unit normal (magnitude of 1) with each component being a value between zero and on (0 to 1).

The uv_array argument must be an array with two value in the form [u,v] with each component being a value between zero and on (0 to 1).

The color_array argument must be an array with three value in the form [r,g,b] with each component being a value between zero and on (0 to 1).

Parameters:
Name Type Description
vertex Array.<number>

An array with [x,y,z[, nx, ny, nz, u, v, r, g, b, a]] values.
Returns:

Returns the index of the new vertex.

Type
number

addVerticesInBulk(pos_arrays [, color_arrays] [, normal_arrays] [, uv_arrays] [, face_arrays])

Appends an array of new vertices with optional colors, normals and uvs.

Whilst the position array is required, the color, normal, uv and face arrays are entirely optional. If colors, normals and/or uvs are given, then the number of items in each array must match the number of items in pos_arrays, otherwise the default value will be used.

Each item in pos_arrays must be an array with three values in the form [x,y,z].

Each item in color_arrays must be an array with three values in the form [r,g,b] with each component being a value between zero and on (0 to 1).

Each item in normal_arrays must be an array with three values in the form [nx,ny,nz] representing a unit normal (magnitude of 1) with each component being a value between zero and on (0 to 1).

Each item in uv_arrays must be an array with two values in the form [u,v] with each component being a value between zero and on (0 to 1).

Each item in face_arrays must be an array with either three or four ordinal index values in the form [1,2,3[,4]] with each component being the zero-based index of vertices in the accompanying arrays.

Parameters:
Name Type Argument Description
pos_arrays Array

This must be given as a [x,y,z] coordinate array.
color_arrays Array <optional>

Optional color values given as an array of [r,g,b,a] color arrays, otherwise defaultColor is used.
normal_arrays Array <optional>

Optional vertex normals given as an array of [x,y,z] vector arrays, otherwise defaultNormal is used.
uv_arrays Array <optional>

Optional texture coordinates given as an array of [u,v] arrays, otherwise defaultUV is used.
face_arrays Array <optional>

Optional array of faces given as [1,2,3[,4]] array indexing the vertex arrays.
Returns:

Returns the new number of vertices in the mesh.

Type
number

assignImageAsTexture(image)

Assigns an img element to texture map the rectangle.

Parameters:
Name Type Description
image object

The DOM img element to use.
Returns:

Returns this mesh to support method chaining.

Type
PD.PolyMesh

begin(mode)

Starts the vertices that define a primitive or a group of like primitives.

The single argument specifies one of the many ways vertices will be interpreted. Taking n as an integer count starting at one, and N as the total number of vertices specified, the interpretations are as follows:

PD.PRIMITIVE.LINES:
Treats each pair of vertices as an independent line segment.

    0               1
    +---------------+

    +__
    3  ''--__
             ''-+
                2

Vertices n - 1 and n define line n. N/2 lines are drawn.

PD.PRIMITIVE.LINE_STRIP:
Draws a connected group of line segments from the first vertex to the last.

    0               1
    +---------------+
                   /
    +__           /
    3  ''--__    /
             ''-+
                2

Vertices n and n + 1 define line n. N-1 lines are drawn.

PD.PRIMITIVE.LINE_LOOP:
Draws a connected group of line segments from the first vertex to the last, then back to the first.

    0               1
    +---------------+
    |              /
    +__           /
    3  ''--__    /
             ''-+
                2

Vertices n and n + 1 define line n. The last line, however, is defined by vertices N and 1. N lines are drawn.

PD.PRIMITIVE.TRIANGLES:
Treats each triplet of vertices as an independent triangle.

    1     3     5
    +     +--<--+         A: 0,1,2
    |\_    \_ B |         B: 3,4,5
    |  \_    \_ |
    | A  \     \|
    +--<--+     +
    0     2     4

Vertices n, n + 1 and n + 2 define triangle n. N/3 triangles are drawn.

PD.PRIMITIVE.TRIANGLE_STRIP:
Draws a connected group of triangles. One triangle is defined for each vertex presented after the first two vertices.

    1     3     5     7
    +-->--+-->--+---  +   A: 0,1,2
    |\_ B |\_ D |\_       B: 2,1,3
    |  \_ |  \_ |  \      C: 2,3,4
    | A  \| C  \|         D: 4,3,5
    +--<--+--<--+---  +
    0     2     4     6

For even n, vertices n + 1, n and n + 2 define triangle n. For odd n, vertices n, n + 1 and n + 2 define triangle n. N-2 triangles are drawn.

PD.PRIMITIVE.TRIANGLE_FAN:
Draws a connected group of triangles. One triangle is defined for each vertex presented after the first two vertices.

    2     3     4
    +-->--+-->--+         A: 0,1,2
    |\_ B | C _/|         B: 0,2,3
    |  \_ | _/  |         C: 0,3,4
    | A  \|/  D |         D: 0,4,5
    +--<--+--<--+
    1     0     5

Vertices 0, n + 1, and n + 2 define triangle n. N-2 triangles are drawn.

Lines and triangles that are incompletely specified are not drawn. Incomplete specification results when either too few vertices are provided to specify even a single primitive or when an incorrect multiple of vertices is specified. The incomplete primitive is ignored, the rest are drawn.

The minimum number of vertices for each primitive is 1 for a point, 2 for a line and 3 for a triangle. Modes that require a certain multiple of vertices are gl.LINES (2) and gl.TRIANGLES (3).

Parameters:
Name Type Description
mode PD.PRIMITIVE

Specifies the primitive type to be generated from vertices added between gl.begin() and gl.end().
Throws:

Occurs if begin() is called again before end().

Type
Error
Returns:

Returns this mesh object to support method chaining.

Type
PD.PolyMesh

color(r, g, b)

Sets the default color for all subsequent vertices from red, green and blue components.

This is the value used when the vertex() method is called, or when the addVertex() or addVertexFromObject() methods are called without a specific color attribute.

NOTE: All the color*() methods are designed to be as fast as possible and do not do any argument checking. Thus, this method MUST ALWAYS be called with three floating point values as its arguments. If you want to use a number/string, array or object, use the colorFromHex(), colorFromArray(), colorFromXYZ() or colorFromRGB() methods instead.

Color values should always be given in floating-point format between 0 and 1. The use of values outside this range will likely exhibit some weird behaviour but is permitted as color components are clamped to this range before they are interpolated or written into a color buffer.

Parameters:
Name Type Description
r number

The red component of the color (0 to 1).
g number

The green component of the color (0 to 1).
b number

The blue component of the color (0 to 1).
Returns:

Returns this mesh object to support method chaining.

Type
PD.PolyMesh

colorFromArray(array)

Sets the default color for all subsequent vertices from an [r,g,b] array.

This is the value used when the vertex() method is called, or when the addVertex() or addVertexFromObject() methods are called without a specific color attribute.

NOTE: All the color*() methods are designed to be as fast as possible and do not do any argument checking. Thus, this method MUST ALWAYS be called with a single [r,g,b] color array as its argument. If you want to use components, number/string or object, use the color(), colorFromHex(), colorFromXYZ() or colorFromRGB() methods instead.

Color values should always be given in floating-point format between 0 and 1. The use of values outside this range will likely exhibit some weird behaviour but is permitted as color components are clamped to this range before they are interpolated or written into a color buffer.

Parameters:
Name Type Description
array Array

A [r,g,b] color array with values in the range 0 to 1.
Returns:

Returns this mesh object to support method chaining.

Type
PD.PolyMesh

colorFromHex(color)

Sets the default color for all subsequent vertices from a hexadecimal string or number.

This is the value used when the vertex() method is called, or when the addVertex() or addVertexFromObject() methods are called without a specific color attribute.

NOTE: All the color*() methods are designed to be as fast as possible and do not do any argument checking. Thus, this method MUST ALWAYS be called with a single string or number value as its argument. If you want to use components, an array or object, use the color(), colorFromArray(), colorFromXYZ() or colorFromRGB() methods instead.

Color values should always be given in floating-point format between 0 and 1. The use of values outside this range will likely exhibit some weird behaviour but is permitted as color components are clamped to this range before they are interpolated or written into a color buffer.

Parameters:
Name Type Description
color string | number

A color value as a HEX string in the form 'AARRGGBB' or a number in the form 0xRRGGBB.
Returns:

Returns this mesh object to support method chaining.

Type
PD.PolyMesh

colorFromRGB(obj)

Sets the default color for all subsequent vertices from an {r,g,b} object, typically a THREE.Color.

This is the value used when the vertex() method is called, or when the addVertex() or addVertexFromObject() methods are called without a specific color attribute.

NOTE: All the color*() methods are designed to be as fast as possible and do not do any argument checking. Thus, this method MUST ALWAYS be called with a single {r,g,b} color object as its argument. If you want to use components, a number/string, an array or {x,y,z} object, use the color(), colorFromHex(), colorFromArray() or colorFromXYZ() methods instead.

Color values should always be given in floating-point format between 0 and 1. The use of values outside this range will likely exhibit some weird behaviour but is permitted as color components are clamped to this range before they are interpolated or written into a color buffer.

Parameters:
Name Type Description
obj THREE.Color

A color object with r, g and b properties with values in the range 0 to 1.
Returns:

Returns this mesh object to support method chaining.

Type
PD.PolyMesh

colorFromXYZ(obj)

Sets the default color for all subsequent vertices from an {x,y,z} object, typically a THREE.Vector3.

This is the value used when the vertex() method is called, or when the addVertex() or addVertexFromObject() methods are called without a specific color attribute.

NOTE: All the color*() methods are designed to be as fast as possible and do not do any argument checking. Thus, this method MUST ALWAYS be called with a single {x,y,z} vector object as its argument. If you want to use components, a number/string, an array or {r,g,b} object, use the color(), colorFromHex(), colorFromArray() or colorFromRGB() methods instead.

Color values should always be given in floating-point format between 0 and 1. The use of values outside this range will likely exhibit some weird behaviour but is permitted as color components are clamped to this range before they are interpolated or written into a color buffer.

Parameters:
Name Type Description
obj THREE.Vector3

A vector object with x, y and z properties with values in the range 0 to 1.
Returns:

Returns this mesh object to support method chaining.

Type
PD.PolyMesh

createExportableMesh(exporter)

Creates a new THREE.Mesh instance that is better suited for export using standard THREE.JS exporters.

This method is detected and used by the PD.File.exportGeometry method to replace this object with the returned mesh when exporting the model.

PolyMesh instances are not well suited for export via THREE as the standard exporters do not respect the 'drawRange' setting in indexed buffer geometries. Thus, they will export the entire buffer and all indices outside the draw range, which can result in unnecessarily large files and degenerate geometry. Thus, we need to create two new temporary meshes that only contain the currently visible surface and or outline geometry.

This means creating new buffer attributes with trimmed arrays and a similarly trimmed index buffer for the triangles and lines. Also, GLTF/GLB and some other exporters do not yet support MeshPhongMaterial, so we need to use a MeshStandardMaterial for the exported meshes.

Parameters:
Name Type Description
exporter PD.File.ExportOptions

The exporter settings.
Returns:

Returns a new mesh that can be exported or null if empty.

Type
THREE.Mesh | null

dispose()

Removes the surface and outline geometry and materials from the GPU.

NOTE: Only call this method when the mesh is no longer needed and you wish to free all its resources and remove it from the GPU.

Returns:

Returns this mesh instance to support method chaining.

Type
PD.PolyMesh

disposeAndRecreateGeometries()

Clean up and (re)create outline and surface geometries.

Returns:

Returns this mesh to support method chaining.

Type
PD.PolyMesh

end()

Finalises and generates the primitive from the vertices.

Returns:

Returns this mesh object to support method chaining.

Type
PD.PolyMesh

getAlpha()

Retrieves the default vertex opacity.

Returns:

Returns the default opacity.

Type
number

getColor()

Retrieves the default vertex colour.

Returns:

Returns the default colour object.

Type
THREE.Color

getLineCount()

Retrieves the current number of lines in the outline mesh.

Returns:

Returns the current number of lines in the mesh.

Type
number

getNormal()

Retrieves the default vertex normal.

Returns:

Returns the default normal object.

Type
THREE.Vector3

getTriangleCount()

Retrieves the current number of triangles in the surface mesh.

Returns:

Returns the current number of triangles in the surface mesh.

Type
number

getUV()

Retrieves the default vertex texture coordinate.

Returns:

Returns the default texture coordinate.

Type
THREE.Vector2

getVertexColor(index)

Retrieves the color of an existing vertex within the surface mesh.

NOTE: This method allows access to the entire vertex buffer, so it is up to you to either check or reset the vertex count as appropriate.

Parameters:
Name Type Description
index number

The ordinal index within the vertex attribute buffer.
Returns:

Returns a color object, or null if out of range.

Type
THREE.Color | null

getVertexCount()

Retrieves the current number of shared vertices stored in the mesh.

Returns:

Returns the current number of shared vertices in the mesh.

Type
number

getVertexNormal(index)

Retrieves the normal of an existing vertex within the surface mesh.

NOTE: This method allows access to the entire vertex buffer, so it is up to you to either check or reset the vertex count as appropriate.

Parameters:
Name Type Description
index number

The ordinal index within the vertex attribute buffer.
Returns:

Returns a vector object, or null if out of range.

Type
THREE.Vector3 | null

getVertexPos(index)

Retrieve the position of an existing vertex within each mesh.

NOTE: This method allows access to the entire vertex buffer, so it is up to you to either check or reset the vertex count as appropriate to ensure that you are not retrieving data that hasn't yet been set.

Parameters:
Name Type Description
index number

The ordinal index within the vertex attribute buffer.
Returns:

Returns a vector object, or null if out of range.

Type
THREE.Vector3 | null

getVertexUV(index)

Retrieves the UV texture coordinates of an existing vertex within the surface mesh.

NOTE: This method allows access to the entire vertex buffer, so it is up to you to either check or reset the vertex count as appropriate.

Parameters:
Name Type Description
index number

The ordinal index within the vertex attribute buffer.
Returns:

Returns a texture coordinate, or null if out of range.

Type
THREE.Vector2 | null

hasContent()

Determines whether or not the mesh has valid content.

Returns:

Returns true if the facet has a boundary and/or triangles.

Type
boolean

invertColor()

Inverts the default vertex color.

Returns:

Returns the inverted colour object.

Type
THREE.Color

loadTexture(imageurl, callback)

Loads in an image file to texture map the rectangle.

Parameters:
Name Type Description
imageurl string

The url of the image to load.
callback function

The callback function once loaded.
Returns:

Returns this mesh to support method chaining.

Type
boolean

movePosition(dx [, dy] [, dz])

Increments the position of the mesh in the scene and sets update world matrices flag.

Parameters:
Name Type Argument Description
dx number | THREE.Vector3

The X axis component to add to scene position or an {x,y,z} vector.
dy number <optional>

The Y axis component to add to scene position.
dz number <optional>

The Z axis component to add to scene position.
Returns:

Returns this mesh instance to support method chaining.

Type
PD.PolyMesh

moveVerticesInAxis(dist [, startIndex] [, endIndex] [, axis])

Moves the position of a range of vertices by the given amount in the given axis.

NOTE: You can use positive and negative axis values to move in different directions. For example, if you use a positive distance and the PD.AXIS.X_POS axis, the vertices will move upwards in the positive X direction. However, if you use a positive distance and the PD.AXIS.X_NEG axis, the vertices will move downwards in the negative X direction.

Parameters:
Name Type Argument Description
dist number

The distance to move in the given axis.
startIndex number <optional>

The starting vertex index, defaults to zero.
endIndex number <optional>

The ending vertex index (exclusive), defaults to the current vertex count.
axis PD.AXIS <optional>

The axis to move the vertices in, defaults to positive Z axis.
Returns:

Returns this mesh instance to support method chaining.

Type
PD.PolyMesh

moveZ( [dz])

Increments the Z-axis position of the mesh in the scene and sets update world matrices flag.

Parameters:
Name Type Argument Description
dz number <optional>

The Z axis component to add to scene position.
Returns:

Returns this mesh instance to support method chaining.

Type
PD.PolyMesh

normal(x, y, z)

Sets the surface normal for all subsequent vertices from axial components.

This is the value used when the vertex() method is called, or when the addVertex() or addVertexFromObject() methods are called without a specific normal attribute.

Surface normals are stored as x, y and z components and should always be of unit length with a total magnitude of 1.0. Normals that are not of unit length may not be lit appropriately depending on the shader/material used to render them.

Parameters:
Name Type Description
x number

The X-axis component normalised direction vector (0 to 1).
y number

The Y-axis component normalised direction vector (0 to 1).
z number

The Z-axis component normalised direction vector (0 to 1).
Returns:

Returns this mesh object to support method chaining.

Type
PD.PolyMesh

normalFromArray(vector)

Sets the surface normal for all subsequent vertices from an array.

This is the value used when the vertex() method is called, or when the addVertex() or addVertexFromObject() methods are called without a specific normal attribute.

Surface normals are stored as x, y and z components and should always be of unit length with a total magnitude of 1.0. Normals that are not of unit length may not be lit appropriately depending on the shader/material used to render them.

Parameters:
Name Type Description
vector Array

A [x,y,z] vector array defining a normalised direction with values in the range 0 to 1.
Returns:

Returns this mesh object to support method chaining.

Type
PD.PolyMesh

normalFromObject(obj)

Sets the surface normal for all subsequent vertices from a vector object.

This is the value used when the vertex() method is called, or when the addVertex() or addVertexFromObject() methods are called without a specific normal attribute.

Surface normals are stored as x, y and z components and should always be of unit length with a total magnitude of 1.0. Normals that are not of unit length may not be lit appropriately depending on the shader/material used to render them.

Parameters:
Name Type Description
obj object

An object with x, y and z properties defining a normalised direction vector with values in the range 0 to 1.
Returns:

Returns this mesh object to support method chaining.

Type
PD.PolyMesh

optimize( [fraction])

Checks the data in each geometry buffer and resizes them based on the given fraction.

The optional fraction parameter allows the caller to control how much optimisation is done. It basically allows for some amount of space at the end of each buffer to allow its content to expand into if more vertices or indexes are added during an interactive event.

Parameters:
Name Type Argument Description
fraction number <optional>

The fraction of leftover space to expand into (0 to 1), defaults to 0.25.
Returns:

Returns true if any of the buffers changed size as a result.

Type
boolean

reset()

Resets internal indices so that you can reuse the buffer geometry.

The aim of this method is to maintain all existing buffer arrays whilst allowing new values to be inserted at the beginning. In most highly dynamic situations, the overall size of the mesh doesn't change much, if at all, so this is useful for avoiding unnecessary build-up of garbage collection.

NOTE: You must always call the update() method to finalise each mesh and update the GPU with the new buffers.

Returns:

Returns this instance to support method chaining.

Type
PD.PolyMesh

resizeOutlineBuffer(newSize)

Resizes the lines index buffers.

The given size is the actual array size rather than the number of lines. As each line uses two entries, this should be two times the required number of lines.

Parameters:
Name Type Description
newSize number

The new size of the outline buffer.
Returns:

Returns true if the buffer was resized.

Type
boolean

resizeSurfaceBuffer(newSize)

Resizes the triangle index buffers.

The given size is the actual array size rather than the number of triangles. As each triangle uses three entries, this should be three times the required number of triangles.

Parameters:
Name Type Description
newSize number

The new size of the surface buffer.
Returns:

Returns true if the buffer was resized.

Type
boolean

resizeVertexBuffers(newSize)

Resizes the vertex position, normal and color buffers.

The given size is the actual array size rather than the number of vertices. As each vertex uses three entries, this should be three times the required number of vertices.

Parameters:
Name Type Description
newSize number

The new size of the vertex and attribute buffers.
Returns:

Returns true if any of the buffers were resized.

Type
boolean

restoreDefaultColor()

Reverts to the previously stored default vertex colour.

Returns:

Returns this mesh instance to support method chaining.

Type
PD.PolyMesh

setAlpha(alpha)

Sets the default vertex opacity.

Parameters:
Name Type Description
alpha number

The new opacity value (0-1).
Returns:

Returns the new opacity value.

Type
number

setColor(r, g, b)

Sets the default vertex color to the three components.

Parameters:
Name Type Description
r number | string | Array.<number> | THREE.Color

The fractional red component (0-1), or a color string/array[rgb]/object{x,y,z} to set.
g number

The fractional green component (0-1).
b number

The fractional blue component (0-1).
Returns:

Returns the colour object.

Type
THREE.Color

setDoubleSided(state)

Sets whether or not the mesh surface should be double sided or just front-sided.

Parameters:
Name Type Description
state boolean

Whether or not the mesh surface is double sided.
Returns:

Returns this instance to support method chaining.

Type
PD.PolyMesh

setNormal(dx, dy, dz)

Sets the default vertex normal given the three components.

Parameters:
Name Type Description
dx number | object

The X-Axis vector component (0-1), or an object with x, y and z properties.
dy number

The Y-Axis vector component (0-1).
dz number

The Z-Axis vector component (0-1).
Returns:

Returns the normal object.

Type
THREE.Vector3

setOutlineColor(r, g, b)

Sets the color of the outline material as a whole.

NOTE: This is very different to the setColor() method and its variants in that this sets the color of the actual THREE outline material. In THREE, this acts as a global tint that affects all vertices in the mesh when rendering its outline, regardless of their individually assigned vertex color.

Parameters:
Name Type Description
r number | object

The red component (0-1), or an object with r, g and b properties.
g number

The green component (0-1).
b number

The blue component (0-1).
Returns:

Returns the colour object.

Type
THREE.Color

setPosition(x [, y] [, z])

Sets the new position of the mesh in the scene and sets update world matrices flag.

Parameters:
Name Type Argument Description
x number | THREE.Vector3

The X axis scene position or an {x,y,z} vector.
y number <optional>

The Y axis scene position.
z number <optional>

The Z axis scene position.
Returns:

Returns this mesh instance to support method chaining.

Type
PD.PolyMesh

setScale(sx [, sy] [, sz])

Sets the new scale of the mesh and sets update world matrices flag.

Parameters:
Name Type Argument Description
sx number | THREE.Vector3

The X axis scene scale or an {x,y,z} vector.
sy number <optional>

The Y axis scene scale.
sz number <optional>

The Z axis scene scale.
Returns:

Returns this mesh instance to support method chaining.

Type
PD.PolyMesh

setSizeIncrement(increment)

Sets the size increment for vertex and index buffers when they need to change size.

The increment is given as the number of elements to add/remove as different buffers can contain a different number of bytes per element.

Parameters:
Name Type Description
increment number

The new buffer increment value (1 to 65535).
Returns:

Returns the current increment value.

Type
number

setSurfaceColor(r, g, b)

Sets the color of the surface material as a whole.

NOTE: This is very different to the setColor() method and its variants in that this sets the color of the actual THREE surface material. In THREE, this acts as a global tint that affects all vertices in the mesh when rendering its surface, regardless of their individually assigned vertex color.

Parameters:
Name Type Description
r number | object

The red component (0-1), or an object with r, g and b properties.
g number

The green component (0-1).
b number

The blue component (0-1).
Returns:

Returns the colour object.

Type
THREE.Color

setTexture(texture)

Loads in an image file to texture map the rectangle.

Parameters:
Name Type Description
texture THREE.Texture

The texture to assign to the mesh.
Returns:

Returns this mesh to support method chaining.

Type
PD.PolyMesh

setUV(x, y)

Sets the default vertex texture coordinate to the two components.

Parameters:
Name Type Description
x number | object

The U component (0-1), or an object with x and y properties.
y number

The V component (0-1) of the texture coordinate.
Returns:

Returns the texture coordinate.

Type
THREE.Vector2

setVertexColor(index, r [, g] [, b])

Changes the color of an existing vertex within the surface mesh.

NOTE: This method allows access to the entire vertex buffer, so it is up to you to either check or reset the vertex count as appropriate.

Parameters:
Name Type Argument Description
index number

The ordinal index within the vertex attribute buffer.
r number | THREE.Color

The new red component (0-1), or a THREE.Color object.
g number <optional>

The new green component (0-1).
b number <optional>

The new blue component (0-1).
Returns:

Returns true if the color was updated or false if index was out of range.

Type
boolean

setVertexCount()

Sets the number of shared vertices in the mesh, up to maxVertices.

NOTE: Using this method with care as it completely subverts a large part of the mesh management process. However, it does allow you to use the setVertex...() methods to randomly access vertex attributes without having to add them all individually first.

Returns:

Returns the current number of vertices in the each mesh.

Type
number

setVertexNormal(index, dx [, dy] [, dz])

Changes the normal of an existing vertex within the surface mesh.

NOTE: This method allows access to the entire vertex buffer, so it is up to you to either check or reset the vertex count as appropriate.

Parameters:
Name Type Argument Description
index number

The ordinal index within the vertex attribute buffer.
dx number | THREE.Vector3

The new X-Axis vector component, or a THREE.Vector3 object.
dy number <optional>

The new Y-Axis vector component.
dz number <optional>

The new Z-Axis vector component.
Returns:

Returns true if the normal was updated or false if index was out of range.

Type
boolean

setVertexPos(index, x [, y] [, z])

Changes the position of an existing vertex within each mesh.

NOTE: This method allows access to the entire vertex buffer, so it is up to you to either check or reset the vertex count as appropriate.

Parameters:
Name Type Argument Description
index number

The ordinal index within the vertex attribute buffer.
x number | THREE.Vector3

The position of the vertex in the X-axis, or a THREE.Vector3 object.
y number <optional>

The position of the vertex in the Y-axis.
z number <optional>

The position of the vertex in the Z-axis.
Returns:

Returns true if the vertex was updated or false if index was out of range.

Type
boolean

setVertexUV(index, u [, v])

Changes the UV texture coordinates of an existing vertex within the surface mesh.

NOTE: This method allows access to the entire vertex buffer, so it is up to you to either check or reset the vertex count as appropriate.

Parameters:
Name Type Argument Description
index number

The ordinal index within the vertex attribute buffer.
u number | THREE.Vector2

The first texture coordinate value (0-1), or a THREE.Vector2 object.
v number <optional>

The second texture coordinate value (0-1)
Returns:

Returns true if the texture coordinates was updated or false if index was out of range.

Type
boolean

setZ(z)

Sets the new Z-axis position of the mesh in the scene and sets update world matrices flag.

Parameters:
Name Type Description
z number

The Z axis scene position.
Returns:

Returns this mesh instance to support method chaining.

Type
PD.PolyMesh

storeDefaultColor()

Stores the current default vertex colour.

Returns:

Returns this mesh instance to support method chaining.

Type
PD.PolyMesh

update()

Finalises the buffer geometry in each mesh and updates them on the GPU.

Make sure to call this method after you have called reset() or added any geometry to the mesh. It updates the buffers on the GPU, sets the drawing range and clears the hasChanged flag.

Returns:

Returns this instance to support method chaining.

Type
PD.PolyMesh

uv(u, v)

Sets the texture coordinate for all subsequent vertices from u and v components.

This is the value used when the vertex() method is called, or when the addVertex() or addVertexFromObject() methods are called without a specific UV attribute.

Parameters:
Name Type Description
u number

The U component of the normalised texture coordinate (0 to 1).
v number

The V component of the normalised texture coordinate (0 to 1).
Returns:

Returns this mesh object to support method chaining.

Type
PD.PolyMesh

uvFromArray(array)

Sets the texture coordinate for all subsequent vertices from an [u,v] array.

This is the value used when the vertex() method is called, or when the addVertex() or addVertexFromObject() methods are called without a specific UV attribute.

Parameters:
Name Type Description
array Array

A [u,v] texture coordinate array with values in the range 0 to 1.
Returns:

Returns this mesh object to support method chaining.

Type
PD.PolyMesh

uvFromUV(obj)

Sets the texture coordinate for all subsequent vertices from a {u,v} UV object.

This is the value used when the vertex() method is called, or when the addVertex() or addVertexFromObject() methods are called without a specific UV attribute.

Parameters:
Name Type Description
obj object

An object with u and v properties with values in the range 0 to 1.
Returns:

Returns this mesh object to support method chaining.

Type
PD.PolyMesh

uvFromXY(obj)

Sets the texture coordinate for all subsequent vertices from a [x,y] vector object.

This is the value used when the vertex() method is called, or when the addVertex() or addVertexFromObject() methods are called without a specific UV attribute.

Parameters:
Name Type Description
obj THREE.Vector3 | THREE.Vector2

An object with x and y properties with values in the range 0 to 1.
Returns:

Returns this mesh object to support method chaining.

Type
PD.PolyMesh

vertex(x, y, z)

Adds a new vertex to the mesh together with default color, normal and texture attributes.

Parameters:
Name Type Description
x number

The X-axis position of the vertex, in model units.
y number

The Y-axis position of the vertex, in model units.
z number

The Z-axis position of the vertex, in model units.
Returns:

Returns this mesh object to support method chaining.

Type
PD.PolyMesh

vertexFromArray(array)

Adds a new vertex to the mesh together with default color, normal and texture attributes.

Parameters:
Name Type Description
array Array

An [x,y,z] coordinate array defining the position of the vertex in model units.
Returns:

Returns this mesh object to support method chaining.

Type
PD.PolyMesh

vertexFromXYZ(obj)

Adds a new vertex to the mesh together with default color, normal and texture attributes.

Parameters:
Name Type Description
obj object

An object with x, y and z properties defining the position of the vertex in model units.
Returns:

Returns this mesh object to support method chaining.

Type
PD.PolyMesh