API Docs

Class: GridLines

PD. GridLines

Defines an editable rectangular grid mesh made of just lines.

NOTE: This class is no longer used within the PD framework.

This type of mesh is mainly used to display the ground grid when editing of viewing a building model.

new GridLines( [config])

Creates a new rectangular grid mesh.

Parameters:
Name Type Argument Description
config object <optional>

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

The width of the grid in the X-axis, in model units.
depth number <optional>

The depth of the grid in the Y-axis, in model units.
height number <optional>

The height of the grid in the Z-axis, in model units.
size Array <optional>

Sets the width, depth and height of the grid, in model units.
majorColor number <optional>

The color of major grid lines, as a hexadecimal number.
minorColor number <optional>

The color of minor grid lines, as a hexadecimal number.
majorGrid number <optional>

The distance between major grid lines.
minorGrid number <optional>

The distance between minor grid lines.
Author:
  • drajmarsh

Extends

Members

:THREE.Box3

_extents

The 3D extents of the grid lines.

Type
  • THREE.Box3
:boolean

autoFit

Whether or not the size of the grid should fit the model.

This will be set to false if the grid size is manually set by the user.

Type
  • boolean
: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
Inherited From:
Overrides:
:boolean

dashed

Whether or not to render all lines in the mesh as dashed.

Type
  • boolean
Inherited From:
Overrides:
:THREE.Color

defaultColor

The default colour of mesh triangles, stored as THREE.Color.

If not specified, this value defaults to { r:0.5, g:0.5, b:0.5 }. It can be set at any time using the PD.LineMesh#setColor and PD.LineMesh#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
Inherited From:
Overrides:
:string|Array

defaultColors

A default colour string or an array of color pairs.

When given as a string, the value must match one of the property names in the PD.GridLines.DefaultColors object. When given as an array, it must be in the form [[light_major,light_minor],[dark_major,dark_minor]], where each of the four items is an integer hexadecimal colour value.

Type
  • string | Array
:number

depth

The size of the grid mesh in the Y-axis, in model units.

Type
  • number
:THREE.Box3

extents

The extents of the grid mesh in absolute model coordinates.

Type
  • THREE.Box3
:THREE.BufferGeometry

geometry

Assembles attribute and line buffers as a new THREE geometry object.

Type
  • THREE.BufferGeometry
Inherited From:
Overrides:
:boolean

hasChanged

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

Type
  • boolean
Inherited From:
Overrides:
:boolean

hasColors

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

Type
  • boolean
Inherited From:
Overrides:
:number

height

The size of the grid mesh in the Z-axis, in model units.

Type
  • number
:boolean

isGridLines <readonly>

A flag identifying this object as grid lines.

Type
  • boolean
:boolean

isLineMesh <readonly>

A flag identifying this object as dynamic lines.

Type
  • boolean
Inherited From:
Overrides:
:number

lineCount

Stores the current number of vertices in each mesh.

Type
  • number
Inherited From:
Overrides:
:THREE.Color

majorColor

The color of major lines.

Type
  • THREE.Color
:number

majorGrid

The major grid line increment.

Type
  • number
:number

maxVertices

The maximum addressable vertex attribute index.

Type
  • number
Inherited From:
Overrides:
:THREE.Color

minorColor

The color of minor lines.

Type
  • THREE.Color
:number

minorGrid

The minor grid line increment.

Type
  • number
:number

opacity

The opacity of the line material.

Type
  • number
Inherited From:
Overrides:
:number

outlineOpacity

The opacity of the grid line material.

Type
  • number
:boolean

roughEdges

Whether or not grid lines extend slightly beyond the grid boundary.

Type
  • boolean
:THREE.Mesh

shadowMesh

An optional mesh to receive and display shadows.

Type
  • THREE.Mesh
:number

sizeIncrement

The amount by which mesh buffers should increment when resizing.

Type
  • number
Inherited From:
Overrides:
:object

userData

A map object 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 hidden class optimisations.

Type
  • object
Inherited From:
Overrides:
:number

width

The size of the grid mesh in the X-axis, in model units.

Type
  • number
:object

DefaultColors <static>

Some default colours for major/minor grid lines.

Default colours are stored as an array of color pairs in the form [[light_major,light_minor],[dark_major,dark_minor]],

Type
  • object

Methods

addLine(v1, v2)

Appends a new line to the surface mesh.

Parameters:
Name Type Description
v1 THREE.Vector3 | Array

The position of the first vertex.
v2 THREE.Vector3 | Array

The position of the second vertex.
Inherited From:
Overrides:
Returns:

Returns the index of the new line.

Type
number

addLineLoop(vertices)

Appends a loop of lines joining the given vertex indices.

Parameters:
Name Type Description
vertices Array

Send either an array of vertexes or multiple arguments.
Inherited From:
Overrides:
Returns:

Returns the index of the first added line.

Type
number

addLineStrip(vertices)

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

Parameters:
Name Type Description
vertices Array

Send either an array of vertexes or multiple arguments.
Inherited From:
Overrides:
Returns:

Returns the index of the first added line.

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.
Inherited From:
Overrides:
Returns:

Returns the index of the first triangle line.

Type
number

generateGrid()

Generates the grid mesh.

Returns:

Returns this grid mesh to support method chaining.

Type
PD.GridLines

getColor()

Retrieves the default vertex colour.

Inherited From:
Overrides:
Returns:

Returns the default colour object.

Type
THREE.Color

getLineCount()

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

Inherited From:
Overrides:
Returns:

Returns the current number of shared vertices in the mesh.

Type
number

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 leftover space to expand into (0 to 1), defaults to 0.25.
Inherited From:
Overrides:
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.

Inherited From:
Overrides:
Returns:

Returns this instance to support method chaining.

Type
PD.LineMesh

resizeVertexBuffers(newSize)

Resizes the vertex position, normal and color buffers.

Parameters:
Name Type Description
newSize number

The new size of these arrays.
Inherited From:
Overrides:
Returns:

Returns true if any of the buffers were resized.

Type
boolean

setColor(r, g, b)

Sets the default vertex color to the three components.

Parameters:
Name Type Description
r number

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).
Inherited From:
Overrides:
Returns:

Returns the colour object.

Type
THREE.Color

setExtents(box, padding)

Updates the rectangle geometry from bounding box.

Override this method for subclasses that use more complex geometry.

Parameters:
Name Type Default Description
box THREE.Box3

The new extents of the grid mesh.
padding number 0

An extra border area in model units, defaults to 0.
Returns:

Returns this mesh to support method chaining.

Type
PD.GridLines

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).
Inherited From:
Overrides:
Returns:

Returns the current increment value.

Type
number

update()

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

Inherited From:
Overrides:
Returns:

Returns this instance to support method chaining.

Type
PD.LineMesh

useDarkModeColors(dark)

Allows the grid to be visible on both light and dark backgrounds.

This method sets the colour of grid lines to match either a dark or light canvas background. You can call this manually to override any assigned grid colours and make it responsive to dark-mode events.

Parameters:
Name Type Description
dark boolean

Whether or not to use colours for a dark background.
Returns:

Returns this grid mesh to support method chaining.

Type
PD.GridLines