Goldberg Polyhedra
Goldberg Polyhedron
Within Babylon.js a Goldberg polyhedron (GBP) is formed as a dual of an icosahedron based geodesic polyhedron and its vertices mapped onto a sphere. The two parameters m and n used in forming the geodesic base also determine the arrangement of faces for the GBP.
Fig 1 - The red grid is the dual of the green grid and vice-versa.
On this page we explain how to create a GBP directly. More information about GBP Mathematics and an outline of coding a GBP are available in the documentation workshop.
A GBP can only be created using MeshBuilder
A GBP consists of 12 pentagonal faces and a number of hexagonal faces determined by m and n. The options for a GBP are fewer than those for CreateGeodesic
or for CreatePolyhedron
. However additional properties and methods, to those of a standard mesh, are available for a Goldberg mesh. These allow individual, or groups of pentagonal and hexagonal faces to be colored, textured or built upon giving a hexagon-grid planet shaped world.
The world consists of 12 poles, the pentagonal faces plus a number of hexagonal faces. Around each of the poles there is a group of hexagonal faces that are closer to one pole than the others. These are the unshared faces of the world. Depending on the value of the second parameter, n, there may be zero or more faces that are equidistant from two or even three poles. These are the shared faces.
Fig 2 - Poles are black, unshared faces are colored and shared faces are white.
The faces are stored in the following order
- the poles 0 to 11
- the unshared faces for pole 0, then for pole 1, pole 2 etc
- the shared faces come at the end
MeshBuilder
usage :
const geodesic = BABYLON.MeshBuilder.CreateGeodesic("geodesic", options, scene); //scene is optional and defaults to the current scene
option | value | default value |
---|---|---|
option m | value (number) an integer > 0 | default value 1 |
option n | value (number) a positive or zero integer <= m | default value 0 |
option size | value (number) polyhedron size | default value 1 |
option sizeX | value (number) X polyhedron size, overwrites the size property | default value 1 |
option sizeY | value (number) Y polyhedron size, overwrites the size property | default value 1 |
option sizeZ | value (number) Z polyhedron size, overwrites the size property | default value 1 |
option updatable | value (boolean) true if the mesh is updatable | default value false |
option sideOrientation | value (number) side orientation | default value DEFAULTSIDE |
Additional Properties and Methods
Properties
All the additional properties are read only.
Property | Value |
---|---|
Property nbFaces | Value (number) Total number of faces in the GBP |
Property nbFacesAtPole | Value (number) The pole plus the closest hexagons |
Property nbUnsharedFaces | Value (number) Total number of hexagonal faces closest to the poles |
Property nbSharedFaces | Value (number) Total number of faces equidistant to two poles |
Property adjacentFaces | Value (number[][]) Array of the faces adjacent to a particular face |
Property faceCenters | Value (Vector3[]) Array of centers of each face |
Property faceYaxis | Value (Vector3[]) Array of normals of each face |
Property faceXaxis | Value (Vector3[]) Array of vectors perpendicular to normal for each face |
Property faceZaxis | Value (Vector3[]) Array of vectors perpendicular to normal for each face |
The vectors faceCenters[face], and faceXaxis[face], faceYaxis[face] and faceZaxis[face] can be used as a frame of reference to place meshes on the given face.
Methods
Colors
Groups of faces can be colored using
goldbergMesh.setFaceColors(colorArray) //resets face colors whether the mesh is updatable or not//orgoldbergMesh.updataFaceColors(colorArray) //resets face colors only when the mesh is updatable
where colorArray
is an array of elements of the form [start face, end face, Color4]
For example
const colorArray = [[18, 18, new BABYLON.Color4(1, 0, 0, 1)], // color face 18 red[26, 37, new BABYLON.Color4(0, 1, 0, 1)] //color faces 26 to 37 inclusive green]
Textures
Groups of faces can have their texture changed by using
goldbergMesh.setFaceUVs(uvArray) //resets face UVs whether the mesh is updatable or not//orgoldbergMesh.updataFaceUVs(uvArray) //resets face UVs only when the mesh is updatable
where uvArray
is an array of elements of the form [start face, end face, center, radius, angle]
center is a Vector2 with 0 ≤ x, ≤ 1 and 0 ≤ y ≤ 1 giving the relative center of a pentagon/hexagon, within a image, of given radius and set at the given angle. The image used should be square to prevent distortion of the texture.
For example
const uvArray = [[18, 18, new BABYLON.Vector2(0.25, 0.75), 0.25, 0], // updates the uvs for face 18 to match the vertices of the green hexagon in Fig 3[26, 37, new BABYLON.Vector2(0.625, 0.37), 0.37, Math.PI / 2] //updates the uvs for faces 26 to 37 to match the vertices of the red hexagon in Fig 3]
For the poles pentagons are used to match the uvs.
Fig 3 - Areas of Image to Use as Face Textures
Fig 4 - Texture Map to Apply to Different Faces
In the following playground different areas of the texture map from Fig 4 are applied to the 12 polar regions and to the shared faces
Fig 5 - Same Texture for the Hexagonal Faces In the following playground the same area is applied to all the hexagonal faces and a blank area to the poles.Placing Meshes
A mesh can be placed on a face using
goldbergMesh.placeOnFaceAt(mesh, face, position); //position is a Vector3
The position is relative to the center of the face and the axes, faceXaxis, faceYaxis and faceZaxis
For example placing a box mesh on face 32
const height = 2;const width = 0.1;const depth = 0.08;const box = BABYLON.MeshBuilder.CreateBox("box", {width: width, depth: depth, height: height});const position = new BABYLON.Vector3(0.53, height / 2, 0.34);goldberg.placeOnFaceAt(box, 32, position);
Meshes should be sized accoring to the size of the face. To keep a mesh within a face values for position.x and position.z should be between around ±radius of face * √3
Importing An Exported Goldberg Mesh
As a Goldberg mesh is a very specialized mesh there is no provision within Babylon.js to serialize the additional properties and methods. When exported it is exported as a standard mesh with any additional data stored in its metadata. Any saved file containing a Goldberg mesh will import the Goldberg mesh as a standard mesh. To restore the additional properties and methods use BABYLON.Mesh.ExtendToGoldberg(mesh)
. This can only be applied to imports of a previously exported Goldberg mesh.
Example
A Goldberg mesh is exported to file.babylon.
BABYLON.SceneLoader.ImportMeshAsync("", "PATH TO FOLDER", "file.babylon").then((result) => {const baseMesh = result.meshes[0];const goldbergMesh = BABYLON.Mesh.ExtendToGoldberg(baseMesh);})
All standard mesh properties and methods can be used with baseMesh.