Chapter 02Spheres

Using the CreateSphere method of the MeshBuilder class, we can make spheres, ellipses, arcs, and slices.

let sphere = BABYLON.MeshBuilder.CreateSphere("name", {options}, scene);

The first argument of CreateSphere() is a String that we can use to retrieve the entire sphere mesh and data about the sphere later. The second argument is an object that specifies various properties of the sphere. The last argument is a reference to the scene in which the sphere will be inserted into.

<script>
var canvas = document.getElementById("renderCanvas");
var engine = new BABYLON.Engine(canvas, true);

function createScene(canvas, engine){
    let scene = new BABYLON.Scene(engine);
    scene.clearColor = new BABYLON.Color3(1, 1, 1);
    let camera = new BABYLON.ArcRotateCamera("Camera", Math.PI / 4, Math.PI / 4, 1.5, BABYLON.Vector3.Zero(), scene);
    camera.attachControl(canvas, true);
    let light = new BABYLON.HemisphericLight("light", new BABYLON.Vector3(1, 1, 0), scene);

    let mat = new BABYLON.StandardMaterial("mat", scene);
    mat.diffuseColor = new BABYLON.Color3(0, 1, 0);

    let sphere = BABYLON.MeshBuilder.CreateSphere("sphere", {}, scene);
    sphere.material = mat;
    
    return scene;
};

var scene = createScene(canvas, engine);

engine.runRenderLoop(function(){
    scene.render();
});

window.addEventListener("resize", function(){
    engine.resize();
});
</script>

<canvas id="renderCanvas"></canvas>
Figure 1. Default Babylon.js sphere.

Properties

Segments

The segments property can be used to specify the number of horizontal segments of the sphere. The default value is 32. The more segments we have, the smoother the sphere will be.

<script>
var canvas1 = document.getElementById("renderCanvas1");
var engine1 = new BABYLON.Engine(canvas1, true);

function createScene1(canvas, engine){
    let scene = new BABYLON.Scene(engine);
    scene.clearColor = new BABYLON.Color3(1, 1, 1);
    let camera = new BABYLON.ArcRotateCamera("Camera", Math.PI, Math.PI / 2, 1.5, BABYLON.Vector3.Zero(), scene);
    camera.attachControl(canvas, true);
    let light = new BABYLON.HemisphericLight("light", new BABYLON.Vector3(1, 1, 0), scene);

    let mat = new BABYLON.StandardMaterial("mat", scene);
    mat.diffuseColor = new BABYLON.Color3(0, 1, 0);
    mat.wireframe = true;

    let sphere = BABYLON.MeshBuilder.CreateSphere("sphere", {segments: 2}, scene);
    sphere.material = mat;
    
    return scene;
};

var scene1 = createScene1(canvas1, engine1);

engine1.runRenderLoop(function(){
    scene1.render();
});

window.addEventListener("resize", function(){
    engine1.resize();
});
</script>

<canvas id="renderCanvas1"></canvas>
Figure 2. The segments property is set to value 2.

Diameter

The diameter of the sphere is the distance from one side to the other through the origin. The default value is 1.

We can change the overall diameter of the sphere, or we can change the individual diameters along the x, y, and z axes using diameterX, diameterY, diameterZ. Changing these values allows us to create an Ellipsoid.

<script>
var canvas2 = document.getElementById("renderCanvas2");
var engine2 = new BABYLON.Engine(canvas2, true);

function createScene2(canvas, engine){
    let scene = new BABYLON.Scene(engine);
    scene.clearColor = new BABYLON.Color3(1, 1, 1);
    let camera = new BABYLON.ArcRotateCamera("Camera", Math.PI / 4, Math.PI / 4, 4, BABYLON.Vector3.Zero(), scene);
    camera.attachControl(canvas, true);
    let light = new BABYLON.HemisphericLight("light", new BABYLON.Vector3(1, 1, 0), scene);

    let mat = new BABYLON.StandardMaterial("mat", scene);
    mat.diffuseColor = new BABYLON.Color3(0, 1, 0);

    let sphere = BABYLON.MeshBuilder.CreateSphere("sphere", {diameterY: 2, diameterX: 4}, scene);
    sphere.material = mat;
    
    return scene;
};

var scene2 = createScene2(canvas2, engine2);

engine2.runRenderLoop(function(){
    scene2.render();
});

window.addEventListener("resize", function(){
    engine2.resize();
});
</script>

<canvas id="renderCanvas2"></canvas>
Figure 3. The diameterY property is set to value 2 along the y-axis and the diameterX property is set to value 4 along the x-axis.

Arc

The arc property allows us to decide how much of the sphere is visible vertically in the scene. The default value is 1. If we enter a number between 0 and 1, only a vertical arc of the proportion specified will be visible.

<script>
var canvas3 = document.getElementById("renderCanvas3");
var engine3 = new BABYLON.Engine(canvas3, true);

function createScene3(canvas, engine){
    let scene = new BABYLON.Scene(engine);
    scene.clearColor = new BABYLON.Color3(1, 1, 1);
    let camera = new BABYLON.ArcRotateCamera("Camera", Math.PI /2, Math.PI / 4, 5, BABYLON.Vector3(3, 0, 0), scene);
    camera.attachControl(canvas, true);
    let light = new BABYLON.HemisphericLight("light", new BABYLON.Vector3(1, 1, 0), scene);

    let mat = new BABYLON.StandardMaterial("mat", scene);
    mat.diffuseColor = new BABYLON.Color3(0, 1, 0);

    let sphere1 = BABYLON.MeshBuilder.CreateSphere("sphere", {arc: 0.25, sideOrientation: BABYLON.Mesh.DOUBLESIDE}, scene);
    sphere1.material = mat;
    sphere1.position = new BABYLON.Vector3(-3, 0, 0);

    let sphere2 = BABYLON.MeshBuilder.CreateSphere("sphere", {arc: 0.5, sideOrientation: BABYLON.Mesh.DOUBLESIDE}, scene);
    sphere2.material = mat;
    sphere2.position = new BABYLON.Vector3(-1, 0, 0);

    let sphere3 = BABYLON.MeshBuilder.CreateSphere("sphere", {arc: 0.75, sideOrientation: BABYLON.Mesh.DOUBLESIDE}, scene);
    sphere3.material = mat;
    sphere3.position = new BABYLON.Vector3(1, 0, 0);

    let sphere4 = BABYLON.MeshBuilder.CreateSphere("sphere", {arc: 1, sideOrientation: BABYLON.Mesh.DOUBLESIDE}, scene);
    sphere4.material = mat;
    sphere4.position = new BABYLON.Vector3(3, 0, 0);

    return scene;
};

var scene3 = createScene3(canvas3, engine3);

engine3.runRenderLoop(function(){
    scene3.render();
});

window.addEventListener("resize", function(){
    engine3.resize();
});
</script>

<canvas id="renderCanvas3"></canvas>
Figure 4. The arc property for the spheres, in order, is set to values 1, 0.75, 0.5, and 0.25.

Slice

The slice property allows us to decide how much of the sphere is visible horizontally. The default value is 1. If we enter a number between 0 and 1, only a horizontal slice from the sphere will be visible.

<script>
var canvas4 = document.getElementById("renderCanvas4");
var engine4 = new BABYLON.Engine(canvas4, true);

function createScene4(canvas, engine){
    let scene = new BABYLON.Scene(engine);
    scene.clearColor = new BABYLON.Color3(1, 1, 1);
    let camera = new BABYLON.ArcRotateCamera("Camera", -Math.PI /2, 2 * Math.PI / 3, 5, BABYLON.Vector3(3, 0, 0), scene);
    camera.attachControl(canvas, true);
    let light = new BABYLON.HemisphericLight("light", new BABYLON.Vector3(1, 1, 0), scene);

    let mat = new BABYLON.StandardMaterial("mat", scene);
    mat.diffuseColor = new BABYLON.Color3(0, 1, 0);

    let sphere1 = BABYLON.MeshBuilder.CreateSphere("sphere", {slice: 0.25, sideOrientation: BABYLON.Mesh.DOUBLESIDE}, scene);
    sphere1.material = mat;
    sphere1.position = new BABYLON.Vector3(-3, 0, 0);

    let sphere2 = BABYLON.MeshBuilder.CreateSphere("sphere", {slice: 0.5, sideOrientation: BABYLON.Mesh.DOUBLESIDE}, scene);
    sphere2.material = mat;
    sphere2.position = new BABYLON.Vector3(-1, 0, 0);

    let sphere3 = BABYLON.MeshBuilder.CreateSphere("sphere", {slice: 0.75, sideOrientation: BABYLON.Mesh.DOUBLESIDE}, scene);
    sphere3.material = mat;
    sphere3.position = new BABYLON.Vector3(1, 0, 0);

    let sphere4 = BABYLON.MeshBuilder.CreateSphere("sphere", {slice: 1, sideOrientation: BABYLON.Mesh.DOUBLESIDE}, scene);
    sphere4.material = mat;
    sphere4.position = new BABYLON.Vector3(3, 0, 0);

    return scene;
};

var scene4 = createScene4(canvas4, engine4);

engine4.runRenderLoop(function(){
    scene4.render();
});

window.addEventListener("resize", function(){
    engine4.resize();
});
</script>

<canvas id="renderCanvas4"></canvas>
Figure 5. The slice property for the spheres, in order, is set to values 0.25, 0.5, 0.75, and 1.

Side Orientation

The sideOrientation property allows us to make our sphere double-sided, which is especially useful when we have an arc or a slice. The default value is FRONTSIDE.

The different values for the sideOrientation property are:

Updatable

If we want the sphere to be able to have its internal geometry changed after creation, we can set the Boolean parameter updatable equal true. The default value is false.

FrontUVs and BackUVs

If the sphere is double-sided, we can choose what parts of a texture to crop and stick on the front and back sides of our mesh with the frontUVs and backUVs properties, respectively. The default value for both is Vector4(0, 0, 1, 1), which is the entire texture.

<script>
var canvas5 = document.getElementById("renderCanvas5");
var engine5 = new BABYLON.Engine(canvas5, true);

function createScene5(canvas, engine){
    let scene = new BABYLON.Scene(engine);
    scene.clearColor = new BABYLON.Color3(1, 1, 1);
    let camera = new BABYLON.ArcRotateCamera("Camera", Math.PI / 4, Math.PI / 4, 1.5, BABYLON.Vector3.Zero(), scene);
    camera.attachControl(canvas, true);
    let light = new BABYLON.HemisphericLight("light", new BABYLON.Vector3(1, 1, 0), scene);

    let front = new BABYLON.Vector4(0, 0, 1/6, 1);
    let back = new BABYLON.Vector4(1/6, 1, 1/3, 0);
    
    let mat = new BABYLON.StandardMaterial("mat", scene);
    mat.diffuseTexture = new BABYLON.Texture("https://assets.babylonjs.com/environments/numbers.jpg", scene);
    mat.diffuseColor = new BABYLON.Color3(0, 1, 0);

    let sphere = BABYLON.MeshBuilder.CreateSphere("sphere", {arc: 0.5, sideOrientation: BABYLON.Mesh.DOUBLESIDE, frontUVs: front, backUVs: back}, scene);
    sphere.material = mat;
    
    return scene;
};

var scene5 = createScene5(canvas5, engine5);

engine5.runRenderLoop(function(){
    scene5.render();
});

window.addEventListener("resize", function(){
    engine5.resize();
});
</script>

<canvas id="renderCanvas5"></canvas>
Figure 6. We apply 0 to the frontal side of the sphere using frontUV. We apply the 1 to the back side of the sphere using backUV.

References