
## Vertex Normals

Each triangular facet of a mesh comprises three vertices. Besides a position each vertex has another important vector3 called a normal. These vertex normals are used by the [shader code](/features/featuresDeepDive/materials/shaders/introToShaders) in calculating how the mesh is lit. Unlike a mathematical normal there is no necessity for them to be set at right angles and for curved shapes such as a sphere they may not be. In the case of a sphere they are set as the mathematical normal of the sphere surface rather than that of the flat facets of the mesh that create the sphere.

At first the vertex normals are calculated as the mathematical normals for the facet. It then depends whether you want to view the facets as flat surfaces or as part of curve. For flat surfaces the vertex normals remain as the mathematical normals. To enhance the curve when viewed under light where triangular facets share vertices with the same positions each shared vertex normal is recalculated to be the average of the mathematical normals of the shared vertex normals.


These effects are explored below.

In the following two playgrounds see how the changing directions within the normals array affect how it is lit:

<Playground id="#VKBJN#18" title="Vertex Normals Varying In Unison" description="Simple example of vertex normals varying in unison."/>

<Playground id="#VKBJN#19" title="Showing Normals Varying" description="Simple example of showing vertex normal variation."/>

##Normals and Minimum Vertices

![Wireframe](/img/how_to/Mesh/box1.jpg)

The box above has 8 vertices. If we want to keep the indices to the minimum they will be 0, 1, 2, 3, 4, 5, 6, 7.

Facets 0, 3, 7 and 3, 7, 6 and 0, 3, 2 all have vertex 3 in common and vertex 3 can only have one
entry in the normals array associated with it.

How doesBabylon.js calculate the `normal` for vertex 3?

The diagram below shows that the average of the three mathematical normals at each vertex is used:

![Normals](/img/how_to/Mesh/box4.jpg)

Besides minimising the number of vertices needed there are other advantages as will be seen when creating a sphere.

Keeping the indices to a minimum the normals at each corner are an average of the mathematical normals of the three faces that meet at that corner. So 8 corners and 8 unique vertex normals.

## Table of Unique Indices, Positions and Normals for Box with Minimum Vertices

| index | position         | normal                                                              |
| ----- | ---------------- | ------------------------------------------------------------------- |
| 0     | ( -1 , 1 , -1 )  | ( -0.5773502691896258 , 0.5773502691896258 , -0.5773502691896258 )  |
| 1     | ( 1 , 1 , -1 )   | ( 0.8164965809277261 , 0.4082482904638631 , -0.4082482904638631 )   |
| 2     | ( 1 , -1 , -1 )  | ( 0.4082482904638631 , -0.4082482904638631 , -0.8164965809277261 )  |
| 3     | ( -1 , -1 , -1 ) | ( -0.4082482904638631 , -0.8164965809277261 , -0.4082482904638631 ) |
| 4     | ( -1 , 1 , 1 )   | ( -0.4082482904638631 , 0.4082482904638631 , 0.8164965809277261 )   |
| 5     | ( 1 , 1 , 1 )    | ( 0.4082482904638631 , 0.8164965809277261 , 0.4082482904638631 )    |
| 6     | ( 1 , -1 , 1 )   | ( 0.5773502691896258 , -0.5773502691896258 , 0.5773502691896258 )   |
| 7     | ( -1 , -1 , 1 )  | ( -0.8164965809277261 , -0.4082482904638631 , 0.4082482904638631 )  |

## Normals and Flat Shaded Meshes.

There are times, such as needing each face of a box to be covered in a [different material](/features/featuresDeepDive/mesh/facetData),
when it is better to have the box constructed from separate faces each of which are constructed by two facets and no two faces
sharing a vertex indices. They will of course share vertex positions.

![Seperate Faces](/img/how_to/Mesh/box3.jpg)

In Babylon.js this can be achieved using the `convertToFlatShadedMesh` function. The results are shown below:

![Flat Shaded Normals](/img/how_to/Mesh/box5.jpg)

For a flat shaded mesh each of the triangular facets making a face of the box has mathematical normals as their vertex normals. For simplicity of illustration we will only consider the six faces making up the box than the full range of triangular facets used in the mesh construction. Each face has 4 corners, each corner has a unique normal at right angles to the face. There are 6 faces on a box and so 24 unique corner normals.

## Table of Faces, Corners, Positions and Normals for Flat Shaded Box

| Face  | corner | position         | normal           |
| ----- | ------ | ---------------- | ---------------- |
| Front | 0      | ( -1 , 1 , -1 )  | ( 0 , 0 , -1 )   |
| Front | 1      | ( 1 , -1 , -1 )  | ( 0 , 0 , -1 )   |
| Front | 2      | ( 1 , 1 , -1 )   | ( 0 , 0 , -1 )   |
| Front | 3      | ( -1 , 1 , -1 )  | ( 0 , 0 , -1 )   |
| Back  | 4      | ( -1 , 1 , 1 )   | ( 0 , 0 , 1 )    |
| Back  | 5      | ( 1 , -1 , 1 )   | ( 0 , 0 , 1 )    |
| Back  | 6      | ( -1 , -1 , 1 )  | ( 0 , 0 , 1 )    |
| Back  | 7      | ( -1 , 1 , 1 )   | ( 0 , 0 , 1 )    |
| Right | 8      | ( 1 , 1 , -1 )   | ( 1 , -0 , 0 )   |
| Right | 9      | ( 1 , -1 , 1 )   | ( 1 , -0 , 0 )   |
| Right | 10     | ( 1 , 1 , 1 )    | ( 1 , -0 , 0 )   |
| Right | 11     | ( 1 , 1 , -1 )   | ( 1 , 0 , 0 )    |
| Left  | 12     | ( -1 , 1 , -1 )  | ( -1 , 0 , 0 )   |
| Left  | 13     | ( -1 , -1 , 1 )  | ( -1 , 0 , 0 )   |
| Left  | 14     | ( -1 , -1 , -1 ) | ( -1 , 0 , 0 )   |
| Left  | 15     | ( -1 , 1 , -1 )  | ( -1 , -0 , -0 ) |
| Top   | 16     | ( -1 , 1 , -1 )  | ( 0 , 1 , 0 )    |
| Top   | 17     | ( 1 , 1 , 1 )    | ( 0 , 1 , 0 )    |
| Top   | 18     | ( -1 , 1 , 1 )   | ( 0 , 1 , 0 )    |
| Top   | 19     | ( 1 , 1 , -1 )   | ( 0 , 1 , -0 )   |
| Base  | 20     | ( -1 , -1 , -1 ) | ( 0 , -1 , -0 )  |
| Base  | 21     | ( 1 , -1 , 1 )   | ( 0 , -1 , -0 )  |
| Base  | 22     | ( 1 , -1 , -1 )  | ( 0 , -1 , -0 )  |
| Base  | 23     | ( -1 , -1 , 1 )  | ( 0 , -1 , 0 )   |

## Playground Showing Box Normals

<Playground id="#1H7L5C#113" title="Box Normals" description="Simple example of box normals."/>

## Advantage of Shared Normals

Sharing normals means that the shader produces a rounder looking sphere since the vertex normals are the mathematical normals of the sphere surface.

Applying the function `converToFlatShadedMesh` shows the individual faces making up the sphere. For a flat shaded sphere the normals of each facet are the mathematical normals of the facet.

<Playground id="#1H7L5C#38" title="Comparing Shading of Spheres" description="Simple example comparing shading of spheres."/>



## Transformations
Transformations are the actions that change an object's position, rotation and scale. Although this section largely covers transformations applied to meshes some can also apply to other Babylon.js objects.

Applying transformations can seem straightforward and in many cases they are, such as changing position. Others aspects may appear easy but in practice can be difficult either in concept, execution or both. In 3D something as simple as a rotation can prove tricky, once you have rotated a mesh about x and y then its z axis may not be where you think it should be since a mesh's local frame of reference rotates with it.

Frames of reference, in 3D, are formed by an origin and three mutually perpendicular axes through the origin. When created in Babylon.js objects are placed using a frame of reference in **World Space** where there are two horizontal axes, x and z, and a vertical y axis in a left handed system.

Each mesh also has its own **Local Space**.  Meshes built within Babylon.js are created with their local space origin at the world space origin and with their local space axes x, y and z aligned with the x, y and z axes of the world space. The local origin acts as the center of transformation unless pivots or parents are added to the mesh. Both of these cases will be described.

Meshes created in other packages and imported may use different frames of reference.





## How To Update Vertices

## Vertex Data

The data contained in each of a mesh's vertices can be obtained from the vertex buffer. This data includes the position of and normal at the vertex 
as well as color and/or uv values. You can also obtain the indices for each vertex. 

```javascript
var positions = mesh.getVerticesData(BABYLON.VertexBuffer.PositionKind);
var normals = mesh.getVerticesData(BABYLON.VertexBuffer.NormalKind);
var colors = mesh.getVerticesData(BABYLON.VertexBuffer.ColorKind);
var uvs = mesh.getVerticesData(BABYLON.VertexBuffer.UVKind);

var indices = mesh.getIndices();
```
Each set of data is an array of numbers as detailed in [Creating Custom Meshes](/features/featuresDeepDive/mesh/creation/custom/custom). 

For example positions will be an array such as [-5, 2, -3, -7, -2, -3, -3, -2, -3, 5, 2, 3, 7, -2, 3, 3, -2, 3] and the  
indices array such as [0, 1, 2, 3, 4, 5] giving the following table.

index|position
-----|----
0| (-5, 2, -3)
1| (-7, -2, -3)
2| (-3, -2, -3)
3| (5, 2, 3)
4| (7, -2, 3)
5| (3, -2, 3)

## Updating the Data

Make sure that the mesh has been set as updatable on creation. Then this is just a matter of altering any of the data in the positions, normals, colors and uvs arrays to suit the project followed updating the vertex data 

```javascript
mesh.updateVerticesData(BABYLON.VertexBuffer.PositionKind, positions);
mesh.updateVerticesData(BABYLON.VertexBuffer.NormalKind, normals);
mesh.updateVerticesData(BABYLON.VertexBuffer.ColorKind, colors);
mesh.updateVerticesData(BABYLON.VertexBuffer.UVKind, uvs);
```

*Note: * When creating your own custom mesh to make it updatable you need to add a second parameter with value true when applying the mesh to  the vertex data.

When a mesh is created, the normal for each face is created smoothly to match the intended shape such as a sphere. To flatten the normals to make the mesh flatly shaded convertToFlatShadedMesh can be used.
```javascript
sphere.convertToFlatShadedMesh()
```
<Playground id="#H05E9H" title="Updating Vertex Data" description="Simple example of updating vertex data."/>

```javascript
vertexData.applyToMesh(customMesh, true);
```
## Adding to the Data

What happens if you want to add to vertexData after creating a mesh? For example many of the set and parametric meshes are created without the ColorKind array so it is not possible to use

```javascript
mesh.updateVerticesData(BABYLON.VertexBuffer.ColorKind, colors);
```

since _mesh.getVerticesData(BABYLON.VertexBuffer.ColorKind)_ will return _null_.

In this case after creating a color for each vertex in a color array use

```javascript
mesh.setVerticesData(BABYLON.VertexBuffer.ColorKind, colors);
```
 as an example 

 ```javascript
var colors = mesh.getVerticesData(BABYLON.VertexBuffer.ColorKind);
if(!colors) {
    colors = [];

    var positions = mesh.getVerticesData(BABYLON.VertexBuffer.PositionKind);

    for(let p = 0; p < positions.length / 3; p++) {
        colors.push(Math.random(), Math.random(), Math.random(), 1);
    }
}

mesh.setVerticesData(BABYLON.VertexBuffer.ColorKind, colors);
 ```

## Examples

Scaling Positions: <Playground id="#VE6GP#4" title="Scaling Positions" description="Simple example of updating vertex data with scaled positions."/>
Playing Around with Positions: <Playground id="#VE6GP#2" title="Playing With Positions" description="Simple example of updating vertex data and playing with positions."/>
Adding Color to Vertices: <Playground id="#ZRZIIZ#2" title="Adding Colors To Vertices" description="Simple example of adding colors to vertices."/>