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:
- Left mouse button: Rotating the scene about the current "origin"
- Mouse wheel: Zooms in and out
- Right mouse button: Moves the view relative to the scene, this is done by moving the origin.
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="http://gsp.humboldt.edu/Archive/Libraries/ThreeJS/4.5/build/three.js"></script> <!----------------- Canvas 3D Map Files --------------------------------------> <script src="http://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3Utilities.js"></script> <script src="http://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3Item.js"></script> <script src="http://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3ItemBox.js"></script> <script src="http://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3ItemOrigin.js"></script> <script src="http://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3Text.js"></script> <script src="http://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3LayerTerrain.js"></script> <script src="http://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3LayerVector.js"></script> <script src="http://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3LayerLights.js"></script> <script src="http://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3LayerItems.js"></script> <script src="http://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3LayerSpecial.js"></script> <script src="http://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3Controls.js"></script> <script src="http://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3ControlsOrbit.js"></script> <script src="http://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3Light.js"></script> <script src="http://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3View.js"></script> <script src="http://gsp.humboldt.edu/CanvasMapWebsite/3D/js/CM3Geo.js"></script> <script src="http://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="http://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);
TheLayer.RequestData();
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.