API Docs

Class: Meshes

BIM. Meshes

This is a set of PD.PolyMesh objects used by each building level to render the elements and entities that belong to it and its spaces.

In large building projects, potentially containing tens of thousands of elements, it is simply not feasible for each of them to have their own render meshes and either draw them all at once or dynamically merge them together. Rather, individual element geometry is created and stored in their own internal PD.Shell objects and these are added to a render mesh whenever the level is rebuilt.

Also, levels often need to be faded in/out, scaled and moved up and down independently of each other. Thus, each level really needs their own separate render meshes so that this can be done by simply setting mesh-level properties or applying transforms rather than having to update vertex attributes.

In addition to model geometry, a level must render transparent glazing, annotations, indicators, thick black lines and other drawing elements. It is desirable that these not cast and receive shadows, or change color due to incident light angles. Thus, each level needs a number of render meshes with different properties and materials in order to accommodate these requirements.

Thus, there are three primary render meshes that are always available on each level, and three dynamic ones that are generated on-demand:

Primary Meshes

  • default
    This mesh is used to display building surfaces and their outlines. Each surface can have a different color, but the outline is always controlled by global settings and changes with light/dark mode.

  • transparent
    This is used to display transparent surfaces such as glazing in windows, door panels or glass railings. Each glazed surface can have a different color, but the overall opacity value and outline colour is controlled by global settings.

  • black
    This is used to display thick lines, text, annotations and indicators within the model. Both its surface and outline colors are always controlled by global settings and changes with light/dark mode.

On-Demand Meshes

  • getImageMesh()
    When first called on a level, this creates a PD.RectMesh for rendering trace images or terrain texture maps. Trace images are imported bitmaps that show the plan of a storey, building or site that can be scaled to the right size and then traced over to create the geometry of a level. Terrain textures are either map or satellite imagery showing the site context and are useful when loaded into levels within BIM.Site structures. This requires a separate mesh due to the need for UV texture coordinates and the ability to interactively drag and scale it relative to other geometry on the level.

  • getSiteMesh()
    When first called on a level, this creates a PD.PolyMesh with a Lambertian material for rendering vegetation and other landscaping elements such as rocks, paving, grass, tarmac and other ground surfaces. Such meshes are primarily used by landscaping levels within BIM.Site structures, however levels in Buildings or Structures may also have pot plants, balcony vegetation, living walls and/or built-in flowerbeds that use such a mesh. This requires a separate mesh due to the different type of material required and potentially huge mesh sizes if individual leaves within the foliage of each plant have to be generated.

  • getDataMesh()
    When first called on a level, this creates a special PD.PolyMesh for rendering semi-transparent data grids, flow indicator arrows, sun-path bands and other analysis information overlays. This requires a separate mesh as analysis data should not cast or receive shadows, and so that its transparency can be quickly and independently changed to suit different display scenarios and visualisation effects.

As this is a subclass of THREE.Group, additional meshes can be added and removed dynamically by elements. For example, some sensor types use THREE.Sprite meshes to represent themselves. As these dynamically update to always face the current camera position, they each have to be a separate render mesh and are added and removed by each sensor instance in their mounted() and unmounted() methods. Another example is realistic trees that need their own specific texture map for different types of foliage, which use mounted() and unmounted() in the same way.

new Meshes(renderable)

Creates three meshes that elements can use to render themselves.

Parameters:
Name Type Description
renderable BIM.Renderable

The renderable drawing/level to create meshes for.
Author:
  • drajmarsh

Extends

  • THREE.Group

Members

:PD.PolyMesh

black

The dynamic mesh used to render black text and lines.

Type
:PD.PolyMesh

default

The dynamic mesh used to render 3D surfaces and lines.

Type
:PD.PolyMesh

transparent

The dynamic mesh used to render transparent surfaces and coloured lines.

Type
:number

darkOutlineColor <static>

The color for making outlines dark.

Type
  • number

Methods

addAnalysisMesh(mesh)

Adds an analysis mesh to the level meshes.

Parameters:
Name Type Description
mesh THREE.Object3D

The mesh/group/object to add.
Returns:

Returns true if mesh is a valid Mesh, Group or Object3D and was added.

Type
boolean

addCustomMesh(mesh)

Adds a custom mesh to the level meshes.

Parameters:
Name Type Description
mesh THREE.Object3D

The mesh/group/object to add.
Returns:

Returns true if mesh is a valid Mesh, Group or Object3D and was added.

Type
boolean

clear()

Clears all meshes other than core meshes from the level.

Returns:

Returns this meshes instance to support method chaining.

Type
BIM.Meshes

clearAnalysisMeshes()

Clears all analysis meshes added to the level.

Returns:

Returns this meshes instance to support method chaining.

Type
BIM.Meshes

clearCustomMeshes()

Clears all custom meshes added to the level.

Returns:

Returns this meshes instance to support method chaining.

Type
BIM.Meshes

getAnalysisMeshes()

Retrieves the list of analysis meshes added to the level meshes.

Returns:

Returns an array of analysis meshes.

Type
Array.<THREE.Object3D>

getCustomMeshes()

Retrieves the list of custom meshes added to the level meshes.

Returns:

Returns an array of custom meshes.

Type
Array.<THREE.Object3D>

getDataMesh()

A dynamically created mesh for rendering analysis data on this level.

Analysis data includes 3D grids, flow indicator arrows, sun-path bands and other information overlay geometry. This needs to be separate from other level meshes so that its transparency can be independently changed to suit different display scenarios and visualisation effects.

getImageMesh()

Retrieves a dynamically created mesh for rendering the trace image.

Trace images are imported bitmaps that show the plan of a building or structure that can nbe scaled to the right size and then raced over to create the geometry of a level. This method creates a new rectangular image mesh if not already created.

Returns:

Returns the level image mesh.

Type
PD.PolyMesh

getSiteMesh()

Retrieves a dynamically created mesh for rendering landscaping and vegetation.

The surfaces of vegetation, rocks, grass and other landscaping elements are typically more Lambertian in nature than specular, so need to be represented by a separate and more suitable material. This method creates a new Lambertian site mesh if not already created.

Returns:

Returns the level site mesh.

Type
PD.PolyMesh

hasDataMesh()

Checks if there is an active level data mesh.

Returns:

Returns true if there is an active level data mesh.

Type
boolean

hasImageMesh()

Checks if there is an active level image mesh.

Returns:

Returns true if there is an active level image mesh.

Type
boolean

hasSiteMesh()

Checks if there is an active level site mesh.

Returns:

Returns true if there is an active level site mesh.

Type
boolean

removeAnalysisMesh(mesh)

Removes an analysis mesh from the level meshes.

Parameters:
Name Type Description
mesh THREE.Object3D

The mesh/group/object to remove.
Returns:

Returns true if mesh was removed.

Type
boolean

removeCustomMesh(mesh)

Removes a custom mesh from the level meshes.

Parameters:
Name Type Description
mesh THREE.Object3D

The mesh/group/object to remove.
Returns:

Returns true if mesh was removed.

Type
boolean

setClippingPlane( [plane])

Adds a clipping plane to the modelling meshes.

Parameters:
Name Type Argument Description
plane THREE.Plane <optional>

An optional plane to clip to.
Returns:

Returns this meshes instance to support method chaining.

Type
BIM.Meshes

showDataMeshIfActive( [show])

Sets the visibility of the active level data mesh if there is one.

Parameters:
Name Type Argument Description
show boolean <optional>

The visibility state to set the level data mesh, defaults to true.

showShadows(state)

Sets the display of shadows within these meshes.

Parameters:
Name Type Description
state boolean

Whether or not to show shadows.
Returns:

Returns this meshes instance to support method chaining.

Type
BIM.Meshes

showSiteMeshIfActive( [show])

Sets the visibility of the active level site mesh if there is one.

Parameters:
Name Type Argument Description
show boolean <optional>

The visibility state to set the level site mesh, defaults to true.

updateName(owner)

Updates the name of the meshes object based on its owner.

Parameters:
Name Type Description
owner BIM.Renderable

The level or drawing that owns these meshes.

createAnalysisMesh( [name] [, hasColors] [, lineColors] [, hasAlpha]) <static>

Creates an analysis mesh for rendering (semi)transparent analysis data.

Analysis meshes are a little different to standard model meshes as they should not cast or receive shadows, and their opacity and outline colors are set by the analysis display settings rather than model view opacities.

Transparency is not handled that well in THREE.js when multiple transparent surfaces overlap each other. This is particularly noticeable when a semi-transparent data grid is rendered inside a semi-transparent building model. If the grid is rendered before the model, the grid surface will set the depth buffer, meaning that any model geometry behind it will not be rendered. If the grid is rendered after the model, model surfaces will have already set the depth buffer, so any grid geometry behind it will not be visible even though the model is semi-transparent.

To solve this, the framework renders analysis meshes twice, once before the model and once after. This requires creating two objects that share the same geometry and material. The first object is rendered before the model and is set to not write to the WebGL depth buffer. This means that it will be visible through semi-transparent model surfaces, but will also be overwritten by model geometry that is behind it. The second object is then rendered after the model in order fill in those areas of the analysis mesh inadvertently obscured by model geometry.

This adds an extra draw call to each level render, but the geometry buffers are only created once on the GPU and shared between both objects. This is a reasonable compromise to ensure that transparent analysis data is properly visible within the model.

Parameters:
Name Type Argument Default Description
name string <optional>

An optional name for the mesh.
hasColors boolean <optional>
 true

Whether or not the mesh has per-vertex surface colors.
lineColors boolean <optional>
 false

Whether or not the mesh has per-vertex outline colors.
hasAlpha boolean <optional>
 false

Whether or not the mesh has per-vertex opacity.
Returns:

Returns a new analysis mesh.

Type
PD.PolyMesh

createImageMesh() <static>

Creates a mesh for rendering the trace image for this level.

Returns:

Returns a new image mesh.

Type
PD.PolyMesh

createSiteMesh() <static>

Creates a mesh for rendering landscaping and vegetation.

Returns:

Returns a new site mesh.

Type
PD.PolyMesh