CanvasMap
Getting Started Tutorials 3D Reference

Getting Started with 3D Mapping

3D Mapping is similar to 2D but with some changes and some additions. First, checkout the Minimal 3D Map example and familiarize yourself with moving around in 3D space. You'll see that many of the controls are the same in CanvasMap but moving around is more complicated. The mouse controls are:

This is the "Orbit" controls and there are other types of controls available that are similar to a helicopter or an airplane.

Including the 3D Libraries

To create a 3D scene , you'll need to include the CanvasMap 3D Libraries and some libraries from THREE.js. The CanvasMap 3D files rely upon the 2D version of CanvasMap so the includes below will need to be after your include(s) for CanvasMap. There is no minified version of the 3D libraries for CanvasMap but expect one to be released within the year. 

<!------------------ THREE.js files -------------------------------------->
<script src="https://gsp.humboldt.edu/Archive/Libraries/ThreeJS/4.5/build/three.js"></script>
<!----------------- Canvas 3D Map Files -------------------------------------->

<script src="https://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3Utilities.js"></script>
<script src="https://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3Item.js"></script>
<script src="https://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3ItemBox.js"></script>
<script src="https://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3ItemOrigin.js"></script>
<script src="https://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3Text.js"></script>
<script src="https://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3LayerTerrain.js"></script>
<script src="https://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3LayerVector.js"></script>
<script src="https://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3LayerLights.js"></script>
<script src="https://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3LayerItems.js"></script>
<script src="https://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3LayerSpecial.js"></script>
<script src="https://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3Controls.js"></script>
<script src="https://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3ControlsOrbit.js"></script>
<script src="https://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3Light.js"></script>
<script src="https://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3View.js"></script>
<script src="https://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3Geo.js"></script>
<script src="https://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3Scene.js"></script>

Setting up the Scene

To create a 3D scene, just passin a CM3View object when you initialize the MainContainer. This will create a CM3Scene object within the MainContainer. The code below will also get a reference to the scene as we'll need it for adding lights. 

var TheView=new CM3View( );
TheMainContainer.Initialize(TheView); // initialize the scene with a 3D view
var TheScene=TheMainContainer.GetScene(); // get the scene

Adding An Ambient Light

Without lights, a 3D scene will be completely black. You'll want to add an ambient light so you can see the scene. Ambient lights are added directly to a CM3Scene object. Typically, the ambient light will be a fairly bright gray (red, green and blue are equal). This lights up your scene but allows spot lights to highlight objects in your scene. Late, you'll want to play with lowering the ambient light and even turning if off for dramatic effects with spot lights. For now, try changing the color of the ambient light in the sample and see what happens to your scene! 

//************************************************************************
// add ambient light to the scene

var TheAmbientLight=new CM3Light();

TheAmbientLight.SetSetting("Style","fillStyle","rgb(120,120,120)");

TheScene.AddChild(TheAmbientLight); // add the light to the scene

TheAmbientLight.SetVisible(true); // make the light visible

Note that the ambient light is added to the scene. There is also only one ambient light.

Adding Vector Layers

In the code below you'll see that adding spatial data to a 3D scene is very similar to adding data to a 2D map. The major difference is in the settings. The "Extrude depth" setting changes the height of the shapes in the scene. The code below adds a set of polygons for the countries of the earth. Try changing the Extrude depth value and see what happens. 

var URL="https://gsp.humboldt.edu/Archive/GISData/2019/WGS84_Geographic/GeoJSON/10m-admin-0-countries_simplified1_addedpoints.js";

var TheLayer=new CM3LayerVector();
TheLayer.SetSetting("Item","Name","Countries");

TheLayer.SetSetting("Style","fillStyle","rgba(200,120,20,1)");
TheLayer.SetSetting("Extrusion","depth",30); // height of the shapes

TheMainContainer.AddLayer(TheLayer);

TheLayer.SetSetting("Dataset","URL",URL);

Take a look at the code that ads the cities point file and you'll see that there is a setting for the Mark used for the points and then the Extrusion is set based on an attribute in the data file. This allows you to create thematic maps with the height of the 3D items representing a wide range of values. 

 TheLayer.SetSetting("Style","fillStyle","rgb(244,0,230)");
 TheLayer.SetSettingAttribute("Extrusion","depth","scalerank"); // get height from attribute
 TheLayer.SetSetting("Mark","Size",2);

Starting the Map

The last few lines of the OnLoad() function are a little different from 2D. A 3D map can be quite complicated to position just the way we want. The first function below sets the position of the view (the "camera" in Three.js terms) and then uses a three.js function to have the camera "look at" the center of the scene. 

TheView.SetSetting("Position","Translations",[0,-120,320]; //(x,y,z) left and right(x), up and down(z), in and out but always looking at same spot(y)
TheView.LookAt(0,0,0); // left and rihgt, in and out, down

This tutorial provided you with an introduction to 3D map creation with CanvasMap. We do recommend you go through a few of the other tutorials before trying to make your first 3D map. We'll also be warning you periodically that if you take a complicated spatial data set such as a road layer or stream layer, do not be surprised if you crash your browser trying to render it. The 3D capabilities of browsers are pretty amazing but they do have their limits.

Looking a Little Flat

At this point we only have an ambient light which means everything is lit by the same light shining in all directions. To make things more interesting, we need to add a point light. Before we do that, we need to learn about coordinates in the 3D world.