# ThreeJS Layer

Notice!!!

The vjthree in the documentation below is deprecated. For ThreeJS 3D layer overlay, please use the latest Vijmap 3D Library (opens new window) https://vjmap.com/map3d/

The ThreeJS layer is provided as a plugin.

Can be loaded via

npm  intall vjthree

import { } from 'vjthree'
// vjthree and THREE objects will be exposed as window globals

1
2
3
4

Or load via

vjmap.addScript([{
    src: "js/plugins/vjthree.min.js"
},{
    src: "js/plugins/vjthree.min.css"
}])

1
2
3
4
5

to load its script.

Note

vjthree and THREE objects will be exposed as window global variables

# Getting Started

if (typeof vjThree !== "object") {
    // If the environment is not available
    await vjmap.addScript([{
        src: "js/plugins/vjthree.min.js"
    },{
        src: "js/plugins/vjthree.min.css"
    }])
}
const threeContext = map.createThreeJsContext({
    defaultLights: true
});

const lineOptions = {
    geometry: line,
    color: 0xff0000
}

let lineMesh = threeContext.line(lineOptions);
threeContext.add(lineMesh);

map.addLayer(new vjmap.ThreeLayer({context: threeContext}));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# createThreeJsContext Options

const threeContext = map.createThreeJsContext(options);

The options parameter is optional and can include the following values:

Option	Required	Default	Type	Description
`defaultLights`	no	false	boolean	Whether to add default lighting to the scene. Without lighting, most objects will render as black
`realSunlight`	no	false	boolean	Sets simulated sunlight based on map center (`map.getCenter`) and local date/time (`new Date()`). Can be updated via `threeContext.setSunlight`. Uses suncalc module internally.
`realSunlightHelper`	no	false	boolean	Whether to show the light helper when `realSunlight` is true.
`passiveRendering`	no	true	boolean	Line color. Unlike other objects, this color is rendered exactly as specified on screen, independent of scene lighting
`enableSelectingFeatures`	no	false	boolean	Enable mouse hover and selection for fill-extrusion features. Triggers event `SelectedFeatureChange`
`enableSelectingObjects`	no	false	boolean	Enable mouse hover and selection for 3D objects. Triggers event `SelectedChange`. Sets `options.bbox` for created objects.
`enableDraggingObjects`	no	false	boolean	Enable dragging 3D objects. Triggers event `ObjectDragged` where `draggedAction = 'translate'` or `draggedAction = 'altitude'`
`enableRotatingObjects`	no	false	boolean	Enable rotating 3D objects. Triggers event `ObjectDragged` where `draggedAction = 'rotate'`
`enableToltips`	no	false	boolean	Enable default tooltips for fill-extrusion features and 3D objects
`multiLayer`	no	false	boolean	Enable multi-layer pages with an internal default layer to manage `threeContext.update` calls
`orthographic`	no	false	boolean	Use `THREE.OrthographicCamera`
`fov`	no	threeContextConstants.FOV_DEGREES	number	FOV for default `THREE.PerspectiveCamera` (opens new window). Invalid when `orthographic: true`
`sky`	no	false	boolean	Sets built-in atmosphere layer. Auto-updates when `realSunlight` is true, or can be updated via `threeContext.updateSunSky(threeContext.getSunSky())`.
`terrain`	no	false	boolean	Sets built-in terrain layer. Auto-updates when `realSunlight` is true, or can be updated via `threeContext.updateSunSky(threeContext.getSunSky())`.

# Loading 3D Models

3D models can be loaded from external files in different formats (OBJ/MTL, GLTF/GLB, FBX, DAE). After loading and adding to threeContext, objects support methods, interactions, events, and animations.

Objects loaded and added to threeContext can be selectable, draggable, and rotatable (on z-axis) when enableSelectingObjects, enableDraggingObjects, and enableRotatingObjects are set to true.

To drag an object: select it, then hold SHIFT and move the mouse to change lnglat position, or hold CTRL to change altitude.
To rotate an object: select it, then hold ALT and move the mouse. The object rotates around its defined center.

When threeContext.enableTooltips is true, all 3D objects (including fill-extrusion extrusions) show tooltips.

# Methods

# add

threeContext.add(obj [, layerId, sourceId])

Adds an object to the threeContext scene. It is appended to threeContext.world.children.

# clear

async threeContext.clear([layerId, dispose])

Removes all children from threeContext.world. If layerId is provided, only that layer is affected. If true is passed as the second parameter, it also calls obj.dispose to release resources.

# createSkyLayer

threeContext.createSkyLayer()

Creates a new sky atmosphere layer, used internally by threeContext.sky.

# createTerrainLayer

threeContext.createTerrainLayer()

Creates a new terrain layer, used internally by threeContext.terrain.

# defaultLights

threeContext.defaultLights()

Creates default lighting for the threeContext scene. Creates THREE.AmbientLight and two THREE.DirectionalLight instances. These can be overridden by adding custom lights to the scene.

# dispose

threeContext.dispose() : Promise (async)

Call dispose when the threeContext instance is no longer needed, or before navigating away from a page that uses it, to avoid memory leaks from Map and Three.js internals.

This method disposes all Three.js objects, geometries, materials, textures, and Map resources including WebGLRenderingContext and the threeContext instance itself.

After calling this method, the threeContext and Map instances are fully released. Use only when navigating away from the page.

# findParent3DObject

threeContext.findParent3DObject(mesh) : Object3D

Finds the parent Object3D in the threeContext scene from a mesh. Used with threeContext.queryRenderedFeatures, which returns THREE.Raycaster (opens new window) intersection results.

# getFeatureCenter

threeContext.getFeatureCenter(feature, model, level): lnglat

Computes the center of a feature geometry in meters, including altitude. Supports GeoJson features with or without loaded 3D models. Used for fill-extrusion and point features.

# getObjectHeightOnFloor

threeContext.getObjectHeightOnFloor(feature, obj, level) : number

Computes the height of a GeoJson feature in meters, with or without a loaded 3D model. Used for fill-extrusion and point features.

# getSunPosition

threeContext.getSunPosition(date, coords)

Gets sun position (azimuth, elevation) from the suncalc.js module for the given date, time, lng, and lat.

# getSunSky

threeContext.getSunSky(date, sunPos)

Gets sun sky layer position [azimuth, elevation] from suncalc.js. Uses date if provided, otherwise new Date(). Uses sunPos if provided, otherwise computes via threeContext.getSunPosition with map.getCenter().

# getSunTimes

threeContext.getSunTimes(date, coords)

Gets sun times (sunrise, sunset, etc.) from suncalc.js for the given date, time, lng, lat, and alt. Used to adjust map style by day/night. Returns an object with date properties for each phase.

# loadObj

async threeContext.loadObj(options, callback(obj));

Loads 3D models from external files in various formats. Caches the first loaded object per URL for reuse via obj.duplicate. This method is async and passes the loaded object to the callback.

Uses THREE.OBJLoader (opens new window), THREE.FBXLoader (opens new window), THREE.GLTFLoader (opens new window), or THREE.ColladaLoader (opens new window). THREE.FBXLoader (opens new window) depends on Zlib (opens new window) for compressed FBX files.

Option	Required	Default	Type	Description
`type`	yes	"mtl"	string (`"mtl"`, `"gltf"`, `"fbx"`, `"dae"`)	Model format type
`obj`	yes	NA	string	URL path to .obj file for OBJ models
`mtl`	no	NA	string	URL path to .mtl file for OBJ models
`bin`	no	NA	string	URL path to .bin files for GLTF models
`units`	no	scene	string (`"scene"` or `"meters"`)	Units for vertex interpretation. Use "meters" for precision. threeContext rescales objects by latitude when using meters.
`rotation`	no	0	number or {x, y, z}	Rotate object along axes before alignment. Future rotations apply on top. Example: `rotation: {x: 90, y: 0, z: 0}` for 90° on x
`scale`	no	1	number or {x, y, z}	Scale object along axes. Future scaling applies on top. Example: `scale: {x: 1, y: 1, z: 3}` for 3× height
`anchor`	no	`bottom-left`	string	3D model anchor point. Values: `top`, `bottom`, `left`, `right`, `center`, `top-left`, `top-right`, `bottom-left`, `bottom-right`. Default `bottom-left`. `auto` uses model-defined anchor.
`adjustment`	no	1	{x, y, z}	3D models are often off-center. Provide per-axis units (e.g. `adjustment: {x: 0.5, y: 0.5, z: 0}`) to correct center.
`normalize`	no	true	bool	Normalize highlight values for some 3D models
`feature`	no	1	GeoJson (opens new window) feature	GeoJson feature instance: e.g. `height`, `base_height`, `color`
`tooltip`	no	false	bool	Enable or disable tooltip. Defaults to `threeContext.enableTooltips`
`bbox`	no	false	bool	Enable or disable bounding box. Defaults to `threeContext.enableSelectingObjects`
`raycasted`	no	true	bool	Exclude object from raycasting
`clone`	no	true	bool	Clone loaded object by default. `clone: false` uses more memory but may be needed when animation/textures don't clone well.
`defaultAnimation`	no	0	number	Default animation index. Ignored if animation not present
`callback`	yes	NA	function	Called after load. First argument is the loaded object. Use to configure and add via `threeContext.add()`

Objects can listen for these events for UI updates. Add them in the threeContext.loadObj callback:

	threeContext.loadObj(options, function (model) {

		soldier = model.setCoords(origin);

		soldier.addEventListener('SelectedChange', onSelectedChange, false);
		soldier.addEventListener('Wireframed', onWireframed, false);
		soldier.addEventListener('IsPlayingChanged', onIsPlayingChanged, false);
		soldier.addEventListener('ObjectDragged', onDraggedObject, false);
		soldier.addEventListener('ObjectMouseOver', onObjectMouseOver, false);
		soldier.addEventListener('ObjectMouseOut', onObjectMouseOut, false);

		threeContext.add(soldier);
	})

1
2
3
4
5
6
7
8
9
10
11
12
13

See the onSelectedChange example below for using map.flyTo(options[, eventData]):

// Method to enable/disable UI buttons.
// This example uses jQuery
// Requires GeoJson feature in threeContext.loadObj(options)
function onSelectedChange(e) {
	let selected = e.detail.selected; // Whether object is selected after event
	$('#deleteButton')[0].disabled = !selected; // Find delete button with jQuery

	// if selected
	if (selected) {
		selectedObject = e.detail; //
		// Fly to selected object
		map.flyTo({
			center: selectedObject.userData.feature.properties.camera,
			zoom: selectedObject.userData.feature.properties.zoom,
			pitch: selectedObject.userData.feature.properties.pitch,
			bearing: selectedObject.userData.feature.properties.bearing
		});
	}
	threeContext.update();
	map.repaint = true;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# 3D Formats and MIME Types

Most 3D formats (.glb, .gltf, .fbx, .dae, ...) are not standard MIME types. Configure your web server to serve these extensions, or downloads may fail with HTTP errors.
For IIS (ASP.Net), add to web.config under <system.webServer>:

<system.webServer>
	  ...
	  <staticContent>
		  <remove fileExtension=".mtl" />
		  <mimeMap fileExtension=".mtl" mimeType="model/mtl" />
		  <remove fileExtension=".obj" />
		  <mimeMap fileExtension=".obj" mimeType="model/obj" />
		  <remove fileExtension=".glb" />
		  <mimeMap fileExtension=".glb" mimeType="model/gltf-binary" />
		  <remove fileExtension=".gltf" />
		  <mimeMap fileExtension=".gltf" mimeType="model/gltf+json" />
		  <remove fileExtension=".fbx" />
		  <mimeMap fileExtension=".fbx" mimeType="application/octet-stream" />
		  <remove fileExtension=".dae" />
		  <mimeMap fileExtension=".dae" mimeType="application/vnd.oipf.dae.svg+xml" />
	  </staticContent>
</system.webServer>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

For ASP.NET Core, add to Configure in Startup:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    ...

    // Set up custom content types - associating file extension to MIME type
    var provider = new FileExtensionContentTypeProvider();
    // Add new mappings
    provider.Mappings[".mtl"] = "model/mtl";
    provider.Mappings[".obj"] = "model/obj";
    provider.Mappings[".glb"] = "model/gltf-binary";
    provider.Mappings[".gltf"] = "model/gltf+json";
    provider.Mappings[".fbx"] = "application/octet-stream";
    provider.Mappings[".dae"] = "application/vnd.oipf.dae.svg+xml";

    app.UseStaticFiles(new StaticFileOptions 
    {
        ContentTypeProvider = provider
    });

    ...
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

For nginx, add to http in nginx.conf:

http {
	include /etc/nginx/mime.types;
	types {
		model/mtl mtl;
		model/obj obj;
		model/gltf+json gltf;
		model/gltf-binary glb;
		application/octet-stream fbx;
		application/vnd.oipf.dae.svg+xml dae;
	}
	...
}

1
2
3
4
5
6
7
8
9
10
11
12

For Apache, add to mime.types:

model/mtl mtl
model/obj obj
model/gltf+json gltf
model/gltf-binary glb
application/octet-stream fbx
application/vnd.oipf.dae.svg+xml dae

1
2
3
4
5
6

# memory

threeContext.memory() : Object

Returns the memory member from THREE.WebGLRenderer.info.

# programs

threeContext.programs() : int

Returns the length of the programs member from THREE.WebGLRenderer.info.

# projectToWorld

threeContext.projectToWorld(lnglat) : THREE.Vector3

Converts lnglat to THREE.Vector3. Inverse of threeContext.unprojectFromWorld.

# queryRenderedFeatures

threeContext.queryRenderedFeatures(point) : Array

Uses THREE.Raycaster to find objects intersecting the pick ray. Returns an array of threeContext objects sorted by distance. Input is {x: number, y: number} in screen coordinates (e.g. e.point from Map mouse events).

# realSunlight

threeContext.realSunlight([helper = true])

Creates simulated sunlight for the scene. Uses suncalc.js and map.getCenter + new Date(). Calls threeContext.setSunlight internally. If helper is true, shows a helper.

# remove

threeContext.remove(obj)

Removes an object from the threeContext scene and threeContext.world.children.

# removeByName

threeContext.removeByName(name)

Removes from the scene and threeContext.world.children by searching the object and its children for the first matching name.

# removeLayer

threeContext.removeLayer(layerId)

Removes a layer from the map, including all 3D objects in the threeContext scene and threeContext.world.children.

# setLayerHeigthProperty

threeContext.setLayerHeigthProperty(layerId, level)

Sets height for all objects in a layer. Only applies when objects have a GeoJson feature with a "level" property.

# setLayerZoomRange

threeContext.setLayerZoomRange(layerId, minZoomLayer, maxZoomLayer)

Custom layers use this method instead of minzoom/maxzoom. Sets zoom range and manages 3D object and CSS2D label visibility for the layer.

# setLayerZoomVisibility

threeContext.setLayerZoomVisibility(layerId)

Sets or resets layer visibility based on current zoom.

# setLayoutProperty

threeContext.setLayoutProperty(layerId, name, value)

Mirrors map.setLayoutProperty for custom layers. Can be used for any layer type.

# setObjectsScale

threeContext.setObjectsScale()

Scales all fixedZoom objects in threeContext.world.children.

# setStyle

threeContext.setStyle(styleId[, options])

Mirrors map.setStyle and removes 3D objects from threeContext.world. Internally calls threeContext.clear(true) to dispose resources.

# setSunlight

threeContext.setSunlight(newDate = new Date(), coords)

Updates sunlight position from suncalc.js for the given date, time, lng, lat. Uses map.getCenter and new Date() when not provided.

# toggleLayer

threeContext.toggleLayer(layerId, visible)

Toggles layer visibility. Useful for custom layers as a replacement for map.setLayoutProperty(layerId, 'visibility', visible).

# update

threeContext.update()

One of the most important methods. Calls THREE.WebGLRenderer.render(scene, camera). Required when using threeContext.loadObj(options, callback(obj)).

# updateLightHelper

threeContext.updateLightHelper()

Updates threeContext.lights.dirLightHelper position. Call when the light moves to keep the helper correct.

# updateSunGround

threeContext.updateSunGround(sunPos)

When threeContext.realSunlight is true, updates lighting on satellite style (if applied) based on sun elevation.

# updateSunSky

threeContext.updateSunSky(sunPos)

When threeContext.sky is true, updates the sky atmosphere layer with the given sun position.

# unprojectFromWorld

threeContext.unprojectFromWorld(Vector3): lnglat

Converts THREE.Vector3 to lnglat. Inverse of threeContext.projectToWorld.

# versions

threeContext.version() : string

Returns the threeContext version.

# threeContext Properties

In the examples below, the threeContext instance is referred to as "tb".

# altitudeStep

threeContext.altitudeStep : Number

Step size in meters for vertical dragging. Default 0.1 (10cm).

# defaultCursor

threeContext.defaultCursor : string

Default cursor for the map canvas container (this.getCanvasContainer().style.cursor). Initial value 'default'.

# enableDraggingObjects

threeContext.enableDraggingObjects : Boolean

Enables horizontal or vertical dragging of 3D objects. Requires threeContext.enableSelectingFeatures to be true. When true and an object is selected: hold [Shift] + mouse to move on x-y; hold [Ctrl] + mouse to move on z. Triggers ObjectDragged event:

obj.addEventListener('ObjectDragged', onDraggedObject, false)

Does not affect map fill-extrusion layers.

# enableRotatingObjects

threeContext.enableRotatingObjects : Boolean

Enables rotating 3D objects. Requires threeContext.enableSelectingFeatures to be true. When true and an object is selected: hold [Alt] + mouse to rotate around z-axis. Triggers ObjectDragged event:

obj.addEventListener('ObjectDragged', onDraggedObject, false)

Does not affect map fill-extrusion layers.

# enableSelectingFeatures

threeContext.enableSelectingFeatures : Boolean

Enables selecting features from fill-extrusion layers. Triggers SelectedFeatureChange on select/unselect:

obj.addEventListener('SelectedFeatureChange', onSelectedFeatureChange, false)

# enableSelectingObjects

threeContext.enableSelectingObjects : Boolean

Enables selecting 3D objects created with threeContext. Triggers SelectedChange on select/unselect:

obj.addEventListener('SelectedChange', onSelectedChange, false)

Does not affect map fill-extrusion layers.

# enableTooltips

threeContext.enableTooltips : Boolean

Enables tooltips (custom or default) on objects. Requires threeContext.enableSelectingFeatures to be true. When true, tooltips show on hover or selection.

# fov

threeContext.fov : Number (degrees)

Default threeContextConstants.FOV_DEGREES. Field of view for the camera. Only applies when threeContext.orthographic is false (i.e. when using THREE.PerspectiveCamera).

# gridStep

threeContext.gridStep : Number(integer)

Step size for horizontal dragging (decimal precision). Default 6 decimals ≈ 11.1cm. Set to 7 for ≈ 1.1cm. Map FOV minimum is 0.01; 0 is converted to 0.01.

# lights

threeContext.lights : Object

Set of lights applied to the scene.

threeContext.lights.ambientLight – THREE.AmbientLight from threeContext.defaultLights(), can be overridden.
threeContext.lights.dirLight – THREE.DirectionalLight from threeContext.defaultLights() or threeContext.setSunlight. Avoid overriding when using realSunlight.
threeContext.lights.dirLightHelper – THREE.DirectionalLightHelper from threeContext.setSunlight.
threeContext.lights.hemiLight – THREE.HemisphereLight from threeContext.setSunlight.
threeContext.lights.pointLight – Not initialized by default.

# multiLayer

threeContext.multiLayer : Boolean

Default false. Enables multiple 3D layers with an internal default layer for threeContext.update calls. Takes effect on style change via threeContext.setStyle. Initialize with multiLayer: true if the page may have multiple 3D layers.

# orthographic

threeContext.orthographic : Boolean

Default false. Whether to use orthographic camera.

# rotationStep

threeContext.rotationStep : Number

Step size in degrees for dragging and rotating objects. Default 5.

# sky

threeContext.sky: Boolean

Default false. Set by init param sky: true. Enables built-in atmosphere layer. Auto-updates when realSunlight is true, or via threeContext.updateSunSky(threeContext.getSunSky()). Setting to false after creation removes the layer.

# terrain

threeContext.terrain: Boolean

Default false. Set by init param terrain: true. Enables built-in terrain layer. Auto-updates when realSunlight is true, or via threeContext.updateSunGround(threeContext.getSunPosition()). Setting to false after creation removes the layer.

# Objects

threeContext provides helpers to build various mesh types and 3D models. They use subclasses of THREE.Object3D. Objects fall into two categories: static (fixed after placement, for background or geographic features, geometry in lnglat) and dynamic (positioned by a single lnglat point, geometry in local scene units or from external OBJ files).

# Static objects

# Line

threeContext.line(options);

Adds a line to the map in 3D space. Color is independent of scene lighting. Uses a custom line shader.

Option	Required	Default	Type	Description
`geometry`	yes	NA	lineGeometry	Array of lnglat coordinates for the line
`color`	no	black	color	Line color. Rendered exactly as specified, independent of scene lighting
`width`	no	1	number	Line width in display pixels (not meters or scene units).
`opacity`	no	1	Number	Line opacity

# Dynamic objects

# Extrusion

threeContext.extrusion(options);

Adds an extruded shape to the map.

Option	Required	Default	Type	Description
`coordinates`	no	[[[]]] or Vector2 array	nested array	GeoJson-style nested array. Geometry as "Polygon" or coordinate array.
`geometryOptions`	no	{}	Object	Options for `ExtrudeGeometry`
`height`	no	100	Number	Extrusion height.
`units`	no	`scene`	string ("scene" or "meters")	Units for vertices. "meters" rescales by latitude.
`scale`	no	1	number or {x, y, z}	Scale along axes. Future scaling applies on top. Example: `scale: {x: 1, y: 1, z: 3}`
`rotation`	no	0	number or {x, y, z}	Rotate along axes. Future rotation applies on top. Example: `rotation: {x: 90, y: 0, z: 0}`
`materials`	no	`THREE.MeshPhongMaterial({ color: 0x660000, side: THREE.DoubleSide })`	threeMaterial or threeMaterials array	`THREE.Material` instance or string.
`anchor`	no	`bottom-left`	string	Anchor point. Values: top, bottom, left, right, center, top-left, top-right, bottom-left, bottom-right. Default bottom-left.
`adjustment`	no	1	{x, y, z}	Center offset in normalized units. Example: `adjustment: {x: -0.5, y: -0.5, z: 0}` to shift center. For a cube centered at ground level: `adjustment: {x: -0.5, y: -0.5, z: 0.5}`.
`tooltip`	no	false	bool	Enable tooltip. Defaults to `threeContext.enableTooltips`
`bbox`	no	false	bool	Enable bounding box. Defaults to `threeContext.enableSelectingObjects`
`raycasted`	no	true	bool	Include in raycasting

# Label

threeContext.label(options);

Creates an HTML label positioned via obj.setCoords(coords) and added with threeContext.add(obj). Uses THREE.CSS2DRenderer and CSS2DObject.

Option	Required	Default	Type	Description
`htmlElement`	yes	null	htmlElement	HTMLElement rendered as `CSS2DObject`
`cssClass`	no	" label3D"	string	CSS class for label styling.
`alwaysVisible`	no	false	number	Number of width and height segments. Higher = smoother sphere.
`topMargin`	no	-0.5	int	Vertical offset in units (1 = object height). Default -0.5 = vertical center.
`feature`	no	null	`GeoJson` feature	GeoJson feature for dynamic positioning.

# Object3D

threeContext.Object3D(options)

Adds any geometry as THREE.Object3D or THREE.Mesh.

Option	Required	Default	Type	Description
`obj`	yes	null	`THREE.Mesh`	Object to enrich with new properties.
`units`	no	`scene`	string ("scene" or "meters")	Units for vertices. "meters" rescales by latitude.
`anchor`	no	`bottom-left`	string	Anchor point. Values: top, bottom, left, right, center, top-left, top-right, bottom-left, bottom-right. Default bottom-left.
`adjustment`	no	1	{x, y, z}	Center offset. Example: `adjustment: {x: -0.5, y: -0.5, z: 0}`. For ground-level cube: `adjustment: {x: -0.5, y: -0.5, z: 0.5}`.
`tooltip`	no	false	bool	Enable tooltip. Defaults to `threeContext.enableTooltips`
`bbox`	no	false	bool	Enable bounding box. Defaults to `threeContext.enableSelectingObjects`
`raycasted`	no	true	bool	Include in raycasting

# Sphere

threeContext.sphere(options);

Adds a sphere to the map. Uses THREE.SphereGeometry and THREE.Mesh, wrapped with Object3D(options).

Option	Required	Default	Type	Description
`radius`	no	50	number	Sphere radius.
`units`	no	`scene`	string ("scene" or "meters")	Units for vertices. "meters" rescales by latitude.
`sides`	no	8	number	Width and height segments. Higher = smoother.
`color`	no	black	color	Sphere color.
`material`	no	MeshLambertMaterial	`THREE.Material`	Material instance or string.
`anchor`	no	`bottom-left`	string	Anchor point. Default bottom-left.
`adjustment`	no	1	{x, y, z}	Center offset. Example: `adjustment: {x: -0.5, y: -0.5, z: 0}`.
`tooltip`	no	false	bool	Enable tooltip. Defaults to `threeContext.enableTooltips`
`bbox`	no	false	bool	Enable bounding box. Defaults to `threeContext.enableSelectingObjects`
`raycasted`	no	true	bool	Include in raycasting

threeContext.tooltip(options);

Creates a browser-like tooltip positioned via obj.setCoords(coords) and added with threeContext.add(obj). Uses THREE.CSS2DRenderer and CSS2DObject.

Option	Required	Default	Type	Description
`text`	yes	""	string	Text rendered as `CSS2DObject`
`cssClass`	no	"toolTip text-xs"	string	CSS class for tooltip styling.
`mapStyle`	no	false	int	If true, use same style as Map popup.
`topMargin`	no	0	int	Vertical offset (1 = object height). Default 0 = top.
`feature`	no	null	`GeoJson` feature	GeoJson feature for dynamic positioning.

# Tube

threeContext.tube(options);

Extrudes a tube along a line geometry with an equilateral polygon cross-section. Uses custom tube geometry and Object3D(options).

Option	Required	Default	Type	Description
`geometry`	yes	NA	lineGeometry	Line coordinates for the tube axis
`radius`	no	20	number	Tube cross-section radius (half of tube width).
`sides`	no	8	number	Faces along the tube. Higher = smoother cylinder.
`material`	no	MeshLambertMaterial	threeMaterial	THREE.Material (opens new window). String or instance.
`color`	no	black	color	Tube color. Ignored if material is predefined.
`opacity`	no	1	Number	Tube opacity
`anchor`	no	`bottom-left`	string	Anchor point. Default bottom-left.
`adjustment`	no	1	{x, y, z}	Center offset. Example: `adjustment: {x: -0.5, y: -0.5, z: 0}`.
`tooltip`	no	false	bool	Enable tooltip. Defaults to `threeContext.enableTooltips`
`bbox`	no	false	bool	Enable bounding box. Defaults to `threeContext.enableSelectingObjects`
`raycasted`	no	true	bool	Include in raycasting

# mapToWorld

mapToWorld(coords);

Convert map geometry coordinates to ThreeJS world coordinates.

# worldToMap

worldToMap(coords);

Convert ThreeJS world coordinates to map geometry coordinates.

# mapToWorldLength

mapToWorldLength(coords);

Convert map geometry length to ThreeJS world coordinate length.

# worldToMapLength

worldToMapLength(coords);

Convert ThreeJS world coordinate length to map geometry length.

# getWorldSize

getWorldSize();

Total length of ThreeJS world coordinates.

# loadTexture

loadTexture(img, defaultImg);

Load texture. Use base64 image. Returns THREE.Texture object.

# coneMesh

Create a quadrangular pyramid

/**
 * Create a quadrangular pyramid
 **/
coneMesh(co: GeoPoint, opts?:  {
    size?: number /* Size, default 1024 */
    height?: number /* Height, default 4096 */
    color?: string | number /* Color, default 0xffcc00 */
    animation?: boolean /* Whether to animate, default true */
    animationUpDown?: boolean /* Whether to have up/down animation. Default true if z value exists */
    obj3dOpts?: object /* Object3D options */
}): any

1
2
3
4
5
6
7
8
9
10
11

Option parameter list:

Option	Required	Type	Description
`size`	no	number	Size, default 1024
`height`	no	number	Height, default 4096
`color`	no	string, number	Color, default 0xffcc00
`animation`	no	boolean	Whether to animate, default true
`animationUpDown`	no	boolean	Whether to have up/down animation. Default true if z value exists
`obj3dOpts`	no	object	Object3D options

# wall

Create a 3D light wall

/**
 * Create a 3D light wall
 **/
wall(pts: GeoPoint[], opts?:  {
    height?: number /* Light wall height, default 10000 */
    flyline?: boolean /* Fly line effect beside light wall, default on */
    repeatX?: number /* Light wall fly line texture X repeat count, default 3 */
    repeatY?: number /* Light wall fly line texture Y repeat count, default 3 */
    offsetX?: number /* Light wall fly line texture X animation offset per frame, default 0.02 */
    offsetY?: number /* Light wall fly line texture Y repeat count, default 0 */
    color1?: string | number /* Light wall fly line color, default 0xffff00 */
    texture1?: string /* Light wall fly line texture image */
    color2?: string | number /* 3D light wall color, default 0x00ffff */
    texture2?: string /* 3D light wall texture image */
    opacity?: number /* 3D light wall opacity, default 0.5 */
    obj3dOpts?: object /* Object3D options */
}): any

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

Option parameter list:

Option	Required	Type	Description
`height`	no	number	Light wall height, default 10000
`flyline`	no	boolean	Fly line effect beside light wall, default on
`repeatX`	no	number	Light wall fly line texture X repeat count, default 3
`repeatY`	no	number	Light wall fly line texture Y repeat count, default 3
`offsetX`	no	number	Light wall fly line texture X animation offset per frame, default 0.02
`offsetY`	no	number	Light wall fly line texture Y repeat count, default 0
`color1`	no	string, number	Light wall fly line color, default 0xffff00
`texture1`	no	string	Light wall fly line texture image
`color2`	no	string, number	3D light wall color, default 0x00ffff
`texture2`	no	string	3D light wall texture image
`opacity`	no	number	3D light wall opacity, default 0.5
`obj3dOpts`	no	object	Object3D options

# wave

Create a wave ring

 /**
 * Create a wave ring
 **/
wave(co: GeoPoint, opts?:  {
    size?: number /* Size, default 3413 */
    color?: string | number /* Color, default 0x22ffcc */
    texture?: string /* Wave ring texture image */
    speed?: number /* Speed, default 0.4 */
}): any

1
2
3
4
5
6
7
8
9

Option parameter list:

Option	Required	Type	Description
`size`	no	number	Size, default 3413
`color`	no	string, number	Color, default 0x22ffcc
`texture`	no	string	Wave ring texture image
`speed`	no	number	Speed, default 0.4

# radialGradient

Create a radial gradient sphere

  /**
 * Create a radial gradient sphere
 **/
radialGradient(co: GeoPoint, opts?:  {
    size?: number /* Size, default 10240 */
    color?: string | number | any/* Color, default new THREE.Vector3(0.0,1.0,1.0) */
    speed?: number /* Speed, default 0.02 */
}): any

1
2
3
4
5
6
7
8

Option parameter list:

Option	Required	Type	Description
`size`	no	number	Size, default 10240
`color`	no	string, number	Color, default new THREE.Vector3(0.0,1.0,1.0)
`speed`	no	number	Speed, default 0.02

# radar

Create a scan radar

/**
 * Create a scan radar
 **/
radar(co: GeoPoint, opts?:  {
    size?: number /* Size, default 20480 */
    color1?: string | number /* Radar scan color, default 0x00ffff */
    texture1: string /* Radar scan texture image */
    color2?: string | number /* Radar scale color, default 0x00cccc */
    texture2: string /* Radar scale texture image */
    speed?: number /* Speed, default 0.02 */
}): any

1
2
3
4
5
6
7
8
9
10
11

Option parameter list:

Option	Required	Type	Description
`size`	no	number	Size, default 20480
`color1`	no	string, number	Radar scan color, default 0x00ffff
`texture1`	yes	string	Radar scan texture image
`color2`	no	string, number	Radar scale color, default 0x00cccc
`texture2`	yes	string	Radar scale texture image
`speed`	no	number	Speed, default 0.02

# waveWall

Create a wave wall

 /**
 * Create a wave wall
 **/
waveWall(co: GeoPoint, opts?:  {
    size?: number /* Size, default 10240 */
    height?: number /* Height, default 2000 */
    color?: string | number /* Color, default 0x00ffff */
    texture?: string /* Texture image */
    speed?: number /* Speed, default 0.1 */
    opacity?: number /* Opacity, default 0.5 */
}): any

1
2
3
4
5
6
7
8
9
10
11

Option parameter list:

Option	Required	Type	Description
`size`	no	number	Size, default 10240
`height`	no	number	Height, default 2000
`color`	no	string, number	Color, default 0x00ffff
`texture`	no	string	Texture image
`speed`	no	number	Speed, default 0.1
`opacity`	no	number	Opacity, default 0.5

# flyline

Create a fly line

 /**
 * Create a fly line
 **/
flyline(opts:  {
    source: GeoPoint, /* Start point */
    target: GeoPoint /* End point */
    height?: number /* Height at interpolated midpoint */
    size?: number /* Particle size, default 3 */
    color: string | number /* Color */
    color2?: string | number /* Set for gradient color */
    count?: number /* Total particle count, default 1000 */
    range?: number /* Particle display range, default 500 */
    opacity?: number /* Opacity, default 1.0 */
    speed?: number /* Speed, default 1 */
}): any

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Option parameter list:

Option	Required	Type	Description
`source`	yes	GeoPoint	Start point
`target`	yes	GeoPoint	End point
`size`	no	number	Particle size, default 30
`height`	no	number	Height at interpolated midpoint
`color`	yes	string, number	Color
`color2`	no	string, number	Set for gradient color
`count`	no	number	Total particle count, default 1000
`range`	no	number	Particle display range, default 500
`speed`	no	number	Speed, default 1
`opacity`	no	number	Opacity, default 1.0

# Object Methods

# addCSS2D

obj.addCSS2D(element, objName [, center = obj.anchor, height = 0])

Generic method to render a DOM HTMLElement on screen relative to the containing object. objName identifies the object and may replace a previous one. center is the label position (default obj.anchor). height is vertical offset: 0 = bottom, 1 = top (default 0).

# addHelp

obj.addHelp(helpText [,objName = helpName, mapSyle = false, center = obj.anchor, height = 0])

Creates a browser-like help tooltip accessible via obj.help. Visible only when dragging for translate, rotate, or altitude. If mapStyle is true, uses Map popup style. center defaults to obj.anchor. height: 0 = bottom, 1 = top (default 0).

# addLabel

obj.addLabel(HTMLElement [, visible, center = obj.anchor, height = 0.5])

Renders a DOM HTMLElement on screen relative to the containing object. If visible is true, the label is always visible; otherwise it shows on mouse over. center defaults to obj.anchor. height: 0 = bottom, 1 = top (default 0.5 = middle).

# addTooltip

obj.addTooltip(tooltipText [, mapSyle = false, center = obj.anchor, custom = true, height = 1])

Creates a browser-like tooltip for the object. If mapStyle is true, uses Map popup style. center defaults to obj.anchor. custom is true for user-added tooltips (not auto-generated). height: 0 = bottom, 1 = top (default 1).

# copyAnchor

obj.copyAnchor(anchor)

Copies the anchor property used internally by obj.duplicate.

# drawBoundingBox

obj.drawBoundingBox

Creates two bounding boxes with THREE.Box3Helper (opens new window). The first is assigned to obj.boundingBox, the second to obj.boundingBoxShadow.

# drawLabelHTML

obj.drawLabelHTML(HTMLElement [, visible = false, center = obj.anchor])

Renders a DOM HTMLElement (opens new window) on screen relative to the containing object. If visible is true, always visible; otherwise shows on mouse over. center is the position/rotation center defined by options.adjustment. Position is relative to the object and re-rendered when the label is visible. Uses THREE.CSS2DRenderer (opens new window) and CSS2DObject, assigned to obj.label.

# duplicate

obj.duplicate()

Returns a clone of the object. Reuses materials and geometry for ~95% performance improvement when adding many identical objects.

# removeCSS2D

obj.removeCSS2D(objName)

Removes the CSS2DObject instance by objName and disposes its resources.

# removeHelp

obj.removeHelp()

Removes the CSS2DObject stored in obj.help. Calls obj.removeCSS2D internally.

# removeLabel

obj.removeLabel()

Removes the CSS2DObject stored in obj.label. Calls obj.removeCSS2D internally.

# removeTooltip

obj.removeTooltip()

Removes the CSS2DObject stored in obj.tooltip. Calls obj.removeCSS2D internally.

# set

obj.set(options)

Updates position, rotation, and scale in one call. Calls obj._setObject(options) internally. If options.duration is set, animates the object. See types section for details.

options object on animations (duration > 0)

option	required	default	type	description
`coords`	no	NA	`lnglat`	Target position
`rotation`	no	NA	`rotationTransform`	Rotation in degrees
`scale`	no	NA	`scaleTransform`	Scale (1 = default)
`duration`	no	1000	number	Animation duration in ms. 0 or undefined = no animation.

options object without animations (duration == 0)

option	required	default	type	description
`position`	no	NA	`lnglat`	Target position
`rotation`	no	NA	`rotationTransform`	Rotation in degrees
`scale`	no	NA	`scaleTransform`	Scale (1 = default)
`worldCoordinates`	no	NA	`Vector3`	World position
`quaternion`	no	NA	[`Vector3`, `radians`]	Rotation by axis and angle in radians
`translate`	no	NA	`lnglat`	Incremental position change
`worldTranslate`	no	NA	`Vector3`	Incremental world position change

# setAnchor

obj.setAnchor(anchor)

Sets position and key anchor from a string. anchor values: top, bottom, left, right, center, top left, top right, bottom left, bottom right. Default: bottom-left.

# setBoundingBoxShadowFloor

obj.setBoundingBoxShadowFloor()

Called from obj.setCoords when the object receives new coordinates. Positions obj.boundingBoxShadow at floor height so the shadow stays on the ground when height changes, making drag/position/rotate easier to see.

# setCoords

obj.setCoords(lnglat)

Positions the object at lnglat. Resizes appropriately if instantiated with units: "meters". Can be called before adding to the map.

# setFixedZoom

obj.setFixedZoom(scale)

Sets scale for object transformation based on fixedZoom. scale should equal map.transform.scale. Called from obj.setScale and load methods; usually not called directly from UI.

# setObjectScale

obj.setObjectScale(scale)

Sets scale for object transformation using obj.unitsPerMeter and scene or meters units. scale should equal map.transform.scale. Calls obj.setScale(scale), obj.setBoundingBoxShadowFloor(), obj.setReceiveShadowFloor() internally.

# setRotation

obj.setRotation(xyz)

Rotates the object on all 3 axes around its defined center. Value in degrees, as number (all axes) or {x, y, z}. Applied on top of rotation from loadObj(options).

# setRotationAxis

obj.setRotationAxis(xyz)

Rotates the object around a bottom corner on the z-axis. Value in degrees, as number or {x, y, z}. Applied on top of rotation from loadObj(options).

# setScale

obj.setScale(scale)

Sets scale for object transformation using obj.unitsPerMeter and scene or meters units. scale should equal map.transform.scale, or obj.userData.mapScale if null. Calls obj.setFixedZoom internally.

# setTranslate

obj.setTranslate(lnglat)

Moves the object from its current position by adding lnglat. Different from obj.setCoords. Must be called after the object is added to the map.

# Object Properties

In the examples below, the threeContext object instance is referred to as "obj".

# boundingBox

obj.boundingBox : THREE.Box3Helper

THREE.Box3Helper with the object's initial size. Visible on MouseOver (yellow) or Selected (green). Hidden from THREE.Raycaster by design.

# boundingBoxShadow

obj.boundingBoxShadow : THREE.Box3Helper

THREE.Box3Helper with initial size but height 0, projected on the map floor. Acts as a shadow. Visible on MouseOver or Selected (black). Hidden from THREE.Raycaster by design.

# castShadow

obj.castShadow : boolean

Whether the object casts shadows. Creates a plane with THREE.PlaneBufferGeometry and THREE.ShadowMaterial() centered on the object, sized to the longest dimension, scaled to fit the full shadow.

# color

obj.color : integer hex

Gets/sets color from hex value. Calls color.setHex.

# help

obj.help : CSS2DObject

CSS2DObject created by obj.addHelp, showing rotate, translate, or altitude values during drag. Internal; visible only during drag operations.

# hidden

obj.hidden : boolean

Object hidden state. Overrides obj.visibility.

# fixedZoom

obj.fixedZoom : Number

Zoom level below which the object keeps a fixed scale. Above it, the object rescales normally. Useful for models that must stay visible at low zoom (e.g. aircraft). fixedZoom uses scene units, not meters.

# label

obj.label : CSS2DObject

CSS2DObject created by obj.addLabel. Can show on hover or always. Used for object attributes or state; can contain any HTMLElement.

# modelHeight

obj.modelHeight : Number

Object height in meters.

# raycasted

obj.raycasted : boolean

If false, hides the object from THREE.Raycaster. Default true. Can be set via threeContext.loadObj or threeContext.Object3D.

# receiveShadow

obj.receiveShadow : boolean

Whether the object receives shadows.

obj.tooltip : CSS2DObject

CSS2DObject created by obj.addTooltip. Default text is object uuid. Visible only when threeContext.enableTooltips is true.

# unitsPerMeter

obj.unitsPerMeter : Number

Conversion factor for units per meter at the object's current latitude.

# visibility

obj.visibility : boolean

Overrides THREE.Object3D.visible. Also applied to obj.label and obj.tooltip. Overridden by obj.hidden.

# wireframe

obj.wireframe : boolean

Switches the object between wireframe and textured mode. When in wireframe, hidden from THREE.Raycaster by design.

# Object Events

In the examples below, the threeContext object instance is referred to as "obj".

# IsPlayingChanged

obj.addEventListener('IsPlayingChanged', onIsPlayingChanged, false)

Fired when the object's animation play state changes (start or stop). Listen after threeContext.loadObj callback. Changed object in eventArgs.detail.

map.addLayer({
	...
	threeContext.loadObj(options, function (model) {

		soldier = model.setCoords(origin);

		soldier.addEventListener('IsPlayingChanged', onIsPlayingChanged, false);

		threeContext.add(soldier);
	})

	...
});
...
function onIsPlayingChanged(eventArgs) {
	if (e.detail.isPlaying) {
		//do something in the UI such as changing a button state
	}
	else {
		//do something in the UI such as changing a button state
	}
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

# ObjectChanged

obj.addEventListener('ObjectChanged', onObjectChanged, false)

Fired when the object changes (including via animation). Listen after threeContext.loadObj callback. Changed object in eventArgs.detail. Possible actions: position (lnglat + alt), rotation (Vector3 radians), scale (Vector3).

map.addLayer({
	...
	threeContext.loadObj(options, function (model) {
		model.setCoords(origin);
		model.addEventListener('ObjectChanged', onObjectChanged, false);
		threeContext.add(model);
	})

	...
});
...
function onObjectChanged(e) {
	let object = e.detail.object; // the object that has changed
	let action = e.detail.action; // the action that defines the change
	//do something in the UI such as changing a button state or updating the new position and rotation
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# ObjectDragged

obj.addEventListener('ObjectDragged', onDraggedObject, false)

Fired once when an object is dragged to a new position, on map.once('mouseup') and map.once('mouseout'). Listen after threeContext.loadObj callback. In eventArgs.detail: draggedAction may be "rotate" (rotated), "translate" (moved), or "altitude" (height changed).

map.addLayer({
	...
	threeContext.loadObj(options, function (model) {

		soldier = model.setCoords(origin);

		soldier.addEventListener('ObjectDragged', onDraggedObject, false);

		threeContext.add(soldier);
	})

	...
});
...
function onDraggedObject(e) {
	let draggedObject = e.detail.draggedObject; // the object dragged
	let draggedAction = e.detail.draggedAction; // the action during dragging

	//do something in the UI such as changing a button state or updating the new position and rotation
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# ObjectMouseOver

obj.addEventListener('ObjectMouseOver', onObjectMouseOver, false)

Fired when the mouse pointer hovers over the object. Listen after threeContext.loadObj callback. Object in eventArgs.detail.

map.addLayer({
	...
	threeContext.loadObj(options, function (model) {

		soldier = model.setCoords(origin);

		soldier.addEventListener('ObjectMouseOver', onObjectMouseOver, false);

		threeContext.add(soldier);
	})

	...
});
...
function onObjectMouseOver(e) {
	//do something in the UI such as adding help or showing this object attributes
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# ObjectMouseOut

obj.addEventListener('ObjectMouseOut', onObjectMouseOut, false)

Fired when the mouse pointer leaves an object that was hovered. Listen after threeContext.loadObj callback. Object in eventArgs.detail.

map.addLayer({
	...
	threeContext.loadObj(options, function (model) {

		soldier = model.setCoords(origin);

		soldier.addEventListener('ObjectMouseOut', onObjectMouseOut, false);

		threeContext.add(soldier);
	})

	...
});
...
function onObjectMouseOut(e) {
	//do something in the UI such as removing help
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# SelectedChange

obj.addEventListener('SelectedChange', onSelectedChange, false)

Fired when the object's selection state changes (selected or unselected). Listen after threeContext.loadObj callback. Object in eventArgs.detail.

map.addLayer({
	...
	threeContext.loadObj(options, function (model) {

		soldier = model.setCoords(origin);

		soldier.addEventListener('SelectedChange', onSelectedChange, false);

		threeContext.add(soldier);
	})

	...
});
...
function onSelectedChange(e) {
	let selectedObject = e.detail; //we get the object selected/unselected
	let selectedValue = selectedObject.selected; //we get if the object is selected after the event
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# SelectedFeature

map.on('SelectedFeature', onSelectedFeature)

Fired by threeContext using the same feature-state pattern as the map (select and hover). Object in eventArgs.detail.

map.addLayer({
	'id': 'room-extrusion',
	'type': 'fill-extrusion',
	'source': 'floorplan',
	'paint': {
	// See the map Style Specification for details on data expressions.
 
	// Get the fill-extrusion-color from the source 'color' property.
	'fill-extrusion-color':
		[
			'case',
			['boolean', ['feature-state', 'select'], false],
			'#ffff00',
			['boolean', ['feature-state', 'hover'], false],
			'#0000ff',
			['get', 'color']
		],
 
	// Get fill-extrusion-height from the source 'height' property.
	'fill-extrusion-height': ['get', 'height'],
 
	// Get fill-extrusion-base from the source 'base_height' property.
	'fill-extrusion-base': ['get', 'base_height'],
 
	// Make extrusions slightly opaque for see through indoor walls.
	'fill-extrusion-opacity': 0.5
}
});
//selected extrusion feature event
map.on('SelectedFeature', onSelectedFeature);
...
function onSelectedFeature(e) {
	let selectedObject = e.detail; //we get the object selected/unselected
	let selectedValue = selectedObject.selected; //we get if the object is selected after the event
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

# Wireframed

obj.addEventListener('Wireframed', onWireframed, false)

Fired when the object's wireframe state changes. Listen after threeContext.loadObj callback. Object in eventArgs.detail.

map.addLayer({
	...
	threeContext.loadObj(options, function (model) {

		soldier = model.setCoords(origin);

		soldier.addEventListener('Wireframed', onWireframed, false);

		threeContext.add(soldier);
	})

	...
});
...
function onWireframed(e) {
	if (e.detail.wireframe) {
		//do something in the UI such as changing a button state
	}
	else {
		//do something in the UI such as changing a button state
	}
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

# Object Animations

# playDefault

obj.playDefault(options)

Plays the default embedded animation of the loaded 3D model.

options object

Option	Required	Default	Type	Description
`duration`	no	1000	number	Animation duration in ms
`speed`	no	1	number	Time scale for animation (1 = default, <1 slower, >1 faster)

# playAnimation

obj.playAnimation(options)

Plays one embedded animation of the loaded 3D model. Set animation index in options.animation.

options object

option	required	default	type	description
`animation`	yes	NA	number	Animation index in the 3D model. Use `obj.animations` for full array.
`duration`	no	1000	number	Animation duration in ms
`speed`	no	1	number	Time scale (1 = default, <1 slower, >1 faster)

# followPath

obj.followPath(options [, callback] )

Translates the object along a path. Optional callback when animation ends.

Option	Required	Default	Type	Description
`path`	yes	NA	lineGeometry	Path for the object to follow
`duration`	no	1000	number	Duration in ms
`trackHeading`	no	true	boolean	Rotate object to align with movement direction during animation

# stop

obj.stop()

Stops all current animations on the object.

# threeContext Types

# pointGeometry

[longitude, latitude(, meters altitude)]

Array of 2–3 numbers: longitude, latitude, optional altitude in meters. Altitude 0 if omitted. From GeoJson point: point.geometry.coordinates. threeContext accepts altitude for z-axis positioning.

# lineGeometry

[pointGeometry, pointGeometry ... pointGeometry]

Array of at least two lnglat points forming a line. From GeoJson LineString: line.geometry.coordinates.

# rotationTransform

number or {x: number, y: number, z: number}

Rotation in degrees. Object form: x parallel to equator, y parallel to meridian, z perpendicular to ground. Number form: rotation around z-axis, equivalent to {z: number}.

# scaleTransform

number or {x: number, y: number, z: number}

Scale factor (1 = default). Same axes as rotationTransform. Number form scales all three axes.

# threeMaterial

string or instance of THREE.Material()

Material for the object. Can be customized with color and opacity. opacity can be a string for the material type (e.g. 'MeshPhysicalMaterial' for THREE.MeshPhysicalMaterial()), or a pre-built THREE material.

# Performance Considerations

Use obj.duplicate() when adding many identical objects. If the object has collections not in obj.children, those must be cloned as well.

For ThreeJS usage details, refer to the ThreeJS (opens new window) official documentation

# Example

亲手试一试

#

(async () => {
    // --ThreeJS 3D line--
    // Map service object
    let svc = new vjmap.Service(env.serviceUrl, env.accessToken)
    // Open map
    let res = await svc.openMap({
        mapid: env.exampleMapId, // Map ID
        mapopenway: vjmap.MapOpenWay.GeomRender, // Open with geometry data rendering
        style: vjmap.openMapDarkStyle() // Use dark background style when div has dark background
    })
    if (res.error) {
        // If open fails
        message.error(res.error)
    }
    // Get map bounds
    let mapExtent = vjmap.GeoBounds.fromString(res.bounds);
    // Create geometric projection coordinate system from map bounds
    let prj = new vjmap.GeoProjection(mapExtent);

    // Map object
    let map = new vjmap.Map({
        container: 'map', // DIV container ID
        style: svc.rasterStyle(), // Style, raster style here
        center: prj.toLngLat(mapExtent.center()),
        zoom: 2,
        pitch: 60,
        antialias:true,
        renderWorldCopies: false // Do not show multi-world map
    });

    // Attach service object and projection
    map.attach(svc, prj);
    // Fit map to full extent
    //map.fitMapBounds();
    await map.onLoad();

    const mapBounds = map.getGeoBounds(0.6);

    if (typeof vjThree !== "object") {
        // If the environment is not available
        await vjmap.addScript([{
            src: "js/plugins/vjthree.min.js"
        },{
            src: "js/plugins/vjthree.min.css"
        }])
    }

    const threeContext = map.createThreeJsContext({
        defaultLights: true
    });
    const arcSegments = 25;
    const lineQuantity = 50;

    for (let i = 0; i < lineQuantity; i++){
        const line = [];
        const destination = [300*(Math.random()-0.5), 140*(Math.random()-0.5)];
        const maxElevation = Math.pow(Math.abs(destination[0]*destination[1]), 0.5) * 80000;

        const increment = destination.map(function(direction){
            return direction/arcSegments;
        })

        for (let l = 0; l<=arcSegments; l++){
            const waypoint = increment.map(function(direction){
                return direction * l
            })

            const waypointElevation = Math.sin(Math.PI*l/arcSegments) * maxElevation;

            waypoint.push(waypointElevation);
            line.push(waypoint);
        }

        const lineOptions = {
            geometry: line,
            color: (line[1][1]/180) * 0xffffff, // color based on latitude of endpoint
            width: Math.random() + 1 // random width between 1 and 2
        }

        let lineMesh = threeContext.line(lineOptions);
        threeContext.add(lineMesh)
    }
    map.addLayer(new vjmap.ThreeLayer({context: threeContext}));
})();

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

← VJMap Visualization L7 Layer →

# ThreeJS Layer

# Getting Started

# createThreeJsContext Options

# Loading 3D Models

# Methods

# add

# clear

# createSkyLayer

# createTerrainLayer

# defaultLights

# dispose

# findParent3DObject

# getFeatureCenter

# getObjectHeightOnFloor

# getSunPosition

# getSunSky

# getSunTimes

# loadObj

# 3D Formats and MIME Types

# memory

# programs

# projectToWorld

# queryRenderedFeatures

# realSunlight

# remove

# removeByName

# removeLayer

# setLayerHeigthProperty

# setLayerZoomRange

# setLayerZoomVisibility

# setLayoutProperty

# setObjectsScale

# setStyle

# setSunlight

# toggleLayer

# update

# updateLightHelper

# updateSunGround

# updateSunSky

# unprojectFromWorld

# versions

# threeContext Properties

# altitudeStep

# defaultCursor

# enableDraggingObjects

# enableRotatingObjects

# enableSelectingFeatures

# enableSelectingObjects

# enableTooltips

# fov

# gridStep

# lights

# multiLayer

# orthographic

# rotationStep

# sky

# terrain

# Objects

# Static objects

# Line

# Dynamic objects

# Extrusion

# Label

# Object3D

# Sphere

# Tooltip

# Tube

# mapToWorld

# worldToMap

# mapToWorldLength

# worldToMapLength

# getWorldSize

# loadTexture

# coneMesh

# wall

# wave

# radialGradient

# radar

# waveWall

# flyline