Class: map

geo. map

new geo.map(arg){geo.map}

Creates a new map object.

Name Type Description
arg geo.map.spec

Map specification

Returns:
Type Description
geo.map

Extends

Type Definitions

geo.map.createSpecgeo.map.spec

Specification used with map.create.

Properties:
Name Type Argument Default Description
data Array.<object> <optional>
[]

The default data array to apply to each feature if none exists.

layers Array.<geo.layer.spec> <optional>
[]

Layers to create.

geo.map.specobject

Map specification.

Properties:
Name Type Argument Default Description
node string

DOM selector for the map container.

gcs string | geo.transform <optional>
'EPSG:3857'

The main coordinate system of the map (this is often web Mercator).

ingcs string | geo.transform <optional>
'EPSG:4326'

The default coordinate system of interface calls (this is often latitude and longitude).

unitsPerPixel number <optional>
156543

GCS to pixel unit scaling at zoom 0 (i.e., meters per pixel or degrees per pixel). The actual default is maxBounds.right - maxBounds.left converted to gcs and then divided by 256.

maxBounds object <optional>

The maximum visible map bounds.

Properties
Name Type Argument Default Description
left number <optional>
-180

The left bound.

right number <optional>
180

The right bound.

bottom number <optional>
-85.06

The bottom bound. The default is actually the left value transformed to the map's gcs coordinate system.

top number <optional>
85.06

The top bound. The default is actually the right value transformed to the map's gcs coordinate system.

gcs number <optional>
ingcs

The coordinate system for the bounds.

zoom number <optional>
4

Initial zoom.

center object <optional>

Initial map center.

Properties
Name Type Default Description
x number 0
y number 0
rotation number <optional>
0

Initial clockwise rotation in radians.

width number <optional>

The map width (default node width).

height number <optional>

The map height (default node height).

min number <optional>
0

Minimum zoom level (though fitting to the viewport may make it so this is smaller than the smallest possible value).

max number <optional>
16

Maximum zoom level.

discreteZoom boolean <optional>
false

If true, only allow integer zoom levels. false for any zoom level.

allowRotation boolean | function <optional>
true

false prevents rotation, true allows any rotation. If a function, the function is called with a rotation (angle in radians) and returns a valid rotation. This can be used to constrain the rotation to a range or specific values.

camera geo.camera <optional>

The camera to control the view.

interactor geo.mapInteractor <optional>

The UI event handler. If undefined, a default interactor is created and used. If null, no interactor is attached to the map.

animationQueue array <optional>

An array used to synchronize animations. If specified, this should be an empty array or the same array as passed to other map instances.

autoResize boolean <optional>
true

Adjust map size on window resize.

clampBoundsX boolean <optional>
false

Prevent panning outside of the maximum bounds in the horizontal direction.

clampBoundsY boolean <optional>
true

Prevent panning outside of the maximum bounds in the vertical direction.

clampZoom boolean <optional>
true

Prevent zooming out so that the map area is smaller than the window.

Members

inherited idle

Getter for the idle state. Read only.

Properties:
Name Type Description
idle boolean

true if the object is idle (onIdle would call a handler immediately).

Static Methods

staticgeo.map.create(spec){geo.map|null}

Create a map from an object. Any errors in the creation of the map will result in returning null.

Name Type Description
spec geo.map.createSpec

The map creation specification.

Returns:
Type Description
geo.map | null

Methods

inherited addChild(child){this}

Add a child (or an array of children) to the object.

Name Type Description
child geo.object | Array.<geo.object>

A child object or array of child objects.

Returns:
Type Description
this

inherited addPromise(promise){this}

Add the promise here and also propagate up the scene tree.

Name Type Description
promise Promise

A promise object.

Returns:
Type Description
this

allowRotation(allowRotation){boolean|function|this}

Get/set the allowRotation setting. If changed, adjust the map as needed.

Name Type Description
allowRotation boolean | function optional

The new allowRotation value. false prevents rotation, true allows any rotation. If a function, the function is called with a rotation (angle in radians) and returns a valid rotation (this can be used to constrain the rotation to a range or to specific values).

Returns:
Type Description
boolean | function | this

animationQueue(queue){array|this}

Get/set the animation queue. Two maps can share a single animation queue to ensure synchronized animations. When setting, the animation queue will merge values from the existing queue into the new queue.

Name Type Description
queue array optional

The animation queue to use.

Returns:
Type Description
array | this The current animation queue or the current map.

autoResize(autoResize){boolean|this}

Get/set the autoResize flag.

Name Type Description
autoResize boolean optional

Truthy to automaticaly resize the map when the size of the browser window changes.

Returns:
Type Description
boolean | this The current state of autoResize or the current map.

bounds(bds, gcs){geo.geoBounds}

Get/set the locations of the current map edges. When set, the left-top and right-bottom corners are transformed to the map's gcs and then used to set the bounds.

Name Type Description
bds geo.geoBounds optional

The requested map bounds.

gcs string | geo.transform | null optional

undefined to use the interface gcs, null to use the map gcs, or any other transform. If setting the bounds, they are converted from this gcs to the map projection. The returned bounds are converted from the map projection to this gcs.

Returns:
Type Description
geo.geoBounds The actual new map bounds.

boundsFromZoomAndCenter(zoom, center, rotation, gcs, ignoreDiscreteZoom, ignoreClampBounds){geo.geoBounds}

Get the bounds that will be displayed with the given zoom and center.

Note: the bounds may not have the requested zoom and center due to map restrictions.

Name Type Description
zoom number

The requested zoom level.

center geo.geoPosition

The requested center.

rotation number

The requested rotation in clockwise radians.

gcs string | geo.transform | null optional

undefined to use the interface gcs, null to use the map gcs, or any other transform.

ignoreDiscreteZoom boolean

If true, ignore the discreteZoom option when determining the new view.

ignoreClampBounds boolean optional

If true and clampBoundsX or clampBoundsY is set, allow the bounds to be less clamped. The map's maxBounds can be shifted so that they lie no further than the center of the bounds (rather than being forced to be at the edge).

Returns:
Type Description
geo.geoBounds

Get the camera.

Returns:
Type Description
geo.camera

center(coordinates, gcs, ignoreDiscreteZoom, ignoreClampBounds){geo.geoPosition|this}

Set center of the map to the given geographic coordinates, or get the current center. Uses bare objects {x: 0, y: 0}.

Name Type Description
coordinates geo.geoPosition

If specified, the new center of the map.

gcs string | geo.transform | null optional

undefined to use the interface gcs, null to use the map gcs, or any other transform. If setting the center, it is converted from this gcs to the map projection. The returned center is converted from the map projection to this gcs.

ignoreDiscreteZoom boolean optional

If true, ignore the discreteZoom option when determining the new view.

ignoreClampBounds boolean | 'limited' optional

If true ignore the clampBoundsX and clampBoundsY options when determining the new view. When 'limited', the clampBoundsX and clampBoundsY options are selectively enforced so that the map will not end up more out of bounds than its current state.

Fires:
Returns:
Type Description
geo.geoPosition | this

Get an array of the child objects.

Returns:
Type Description
Array.<geo.object> A copy of the array of child objects.

clampBoundsX(clamp){boolean|this}

Get/set the clampBoundsX setting. If changed, adjust the bounds of the map as needed.

Name Type Description
clamp boolean optional

The new clamp value.

Returns:
Type Description
boolean | this

clampBoundsY(clamp){boolean|this}

Get/set the clampBoundsY setting. If changed, adjust the bounds of the map as needed.

Name Type Description
clamp boolean optional

The new clamp value.

Returns:
Type Description
boolean | this

clampZoom(clamp){boolean|this}

Get/set the clampZoom setting. If changed, adjust the bounds of the map as needed.

Name Type Description
clamp boolean optional

The new clamp value.

Returns:
Type Description
boolean | this

createLayer(layerName, arg){geo.layer}

Add a layer to the map.

Name Type Description
layerName string

The type of layer to add to the map.

arg object

Parameters for the new layer.

Fires:
Returns:
Type Description
geo.layer

deleteLayer(layer){geo.layer}

Remove a layer from the map.

Name Type Description
layer geo.layer nullable

Layer to remove from the map.

Fires:
Returns:
Type Description
geo.layer

discreteZoom(discreteZoom){boolean|this}

Get/set the discrete zoom flag. If true, the map will snap to integer zoom levels.

Name Type Description
discreteZoom boolean optional

If specified, the new discrete zoom flag.

Returns:
Type Description
boolean | this The current discrete zoom flag or the map object.

displayToGcs(c, gcs){geo.geoPosition|Array.<geoPosition>}

Convert from display to gcs coordinates. This is identical to calling displayToWorld and then worldToGcs.

Name Type Description
c geo.screenPosition | Array.<geo.screenPosition>

The input display coordinate to convert.

gcs string | geo.transform | null optional

Output gcs. undefined to use the interface gcs, null to use the map gcs, or any other transform.

Returns:
Type Description
geo.geoPosition | Array.<geoPosition> GCS space coordinates.

displayToWorld(c){geo.worldPosition|Array.<geo.worldPosition>}

Convert from display coordinates to world coordinates using the attached camera.

Name Type Description
c geo.screenPosition | Array.<geo.screenPosition>

The input coordinate to convert.

Returns:
Type Description
geo.worldPosition | Array.<geo.worldPosition> World space coordinates.

draw(){this}

Redraw the map and all its layers.

Fires:
Returns:
Type Description
this The map object.

exit()

Exit this map. This removes all layers, destroys current interactor, and empties the associated DOM node.

fileReader(readerOrName, opts){geo.fileReader|this}

Get, set, or create and set a file reader to a layer in the map to be used as a drop target.

Name Type Description
readerOrName string | object optional

undefined to get the current reader, an instance of a file reader to set the reader, or a name to create a file reader.

opts object optional

options Parameters for creating a file reader when the reader is specified by name. If this includes layer, use that layer, otherwise create a layer using these options.

Returns:
Type Description
geo.fileReader | this

gcs(arg){string|this}

Get or set the map gcs. This is the coordinate system used in drawing the map.

Name Type Description
arg string optional

If undefined, return the current gcs. Otherwise, a new value for the gcs.

Returns:
Type Description
string | this A string used by geo.transform.

gcsToDisplay(c, gcs){geo.screenPosition|Array.<geo.screenPosition>}

Convert from gcs coordinates to display coordinates. This is identical to calling gcsToWorld and then worldToDisplay.

Name Type Description
c geo.geoPosition | Array.<geo.geoPosition>

The input coordinate to convert.

gcs string | geo.transform | null optional

Input gcs. undefined to use the interface gcs, null to use the map gcs, or any other transform.

Returns:
Type Description
geo.screenPosition | Array.<geo.screenPosition> Display space coordinates.

gcsToWorld(c, gcs){geo.worldPosition|Array.<geo.worldPosition>}

Convert from gcs coordinates to map world coordinates.

Name Type Description
c geo.geoPosition | Array.<geo.geoPosition>

The input coordinate to convert.

gcs string | geo.transform | null optional

Input gcs. undefined to use the interface gcs, null to use the map gcs, or any other transform.

Returns:
Type Description
geo.worldPosition | Array.<geo.worldPosition> World space coordinates.

inherited geoIsOn(event, handler){boolean}

Report if an event handler is bound to this object.

Name Type Description
event string | Array.<string>

An event or list of events to check.

handler function optional

A function that might be bound. If undefined, this will report true if there is any handler for the specified event.

Returns:
Type Description
boolean true if any of the specified events are bound to the specified handler.

inherited geoOff(event, arg){this}

Remove handlers from one event or an array of events. If no event is provided all handlers will be removed.

Name Type Description
event string | Array.<string> optional

An event or a list of events from geo.event or defined by the user, or undefined to remove all events (in which case arg is ignored).

arg function | Array.<function()> optional nullable

A function or array of functions to remove from the events or a falsy value to remove all handlers from the events.

Returns:
Type Description
this

inherited geoOn(event, handler){this}

Bind an event handler to this object.

Name Type Description
event string

An event from geo.event or a user-defined value.

handler function

A function that is called when event is triggered. The function is passed a geo.event object.

Returns:
Type Description
this

inherited geoTrigger(event, args, childrenOnly){this}

Trigger an event (or events) on this object and call all handlers.

Name Type Description
event string

The event to trigger.

args object

Arbitrary argument to pass to the handler.

childrenOnly boolean optional

If truthy, only propagate down the tree.

Returns:
Type Description
this

ingcs(arg){string|this}

Get or set the map interface gcs. This is the coordinate system used when getting or setting map bounds, center, and other values.

Name Type Description
arg string optional

If undefined, returtn the current interface gcs. Otherwise, a new value for the interface gcs.

Returns:
Type Description
string | this A string used by geo.transform.

interactor(arg){geo.mapInteractor|this}

Get or set the map interactor.

Name Type Description
arg geo.mapInteractor optional

If specified, the map interactor to set.

Returns:
Type Description
geo.mapInteractor | this The current map interactor or the map object.

layers()

Get the layers contained in the map. Alias of geo.sceneObject#children.

listSceneObjects(objects){Array.<geo.sceneObject>}

Get a sorted list of geo.sceneObject including all children. The list always includes specified objects. Children immediately follow their parents. Siblings may be separated by children of preceding siblings.

Name Type Description
objects Array.<geo.sceneObject> optional

A list of objects for which the a combined list of dependents is generated. If not specified, the sorted list of layers is used.

Returns:
Type Description
Array.<geo.sceneObject> A list of object and dependents.

maxBounds(bounds, gcs){geo.geoBounds|this}

Get/set the maximum view area of the map. If the map wraps, this is the unwrapped area.

Name Type Description
bounds geo.geoBounds optional

The map bounds.

gcs string | geo.transform | null optional

undefined to use the interface gcs, null to use the map gcs, or any other transform. If setting the bounds, they are converted from this gcs to the map projection. The returned bounds are converted from the map projection to this gcs.

Returns:
Type Description
geo.geoBounds | this The map maximum bounds or the map object.

inherited modified(){this}

Update the timestamp to the next global timestamp value.

Returns:
Type Description
this

node(){object}

Get root DOM node of the map.

Returns:
Type Description
object

inherited onIdle(handler){this}

Bind a handler that will be called one time when all internal promises are resolved. If there are no outstanding promises, this is invoked synchronously.

Name Type Description
handler function

A function taking no arguments.

Returns:
Type Description
this

Get the map's world coordinate origin in gcs coordinates.

Returns:
Type Description
geo.geoPosition

pan(delta, ignoreDiscreteZoom, ignoreClampBounds){this}

Pan the map by a number of display pixels.

Name Type Description
delta object

Amount to pan in display pixels.

Name Type Description
x number

Horizontal distance on the display.

y number

Vertical distance on the display.

ignoreDiscreteZoom boolean optional

If true, ignore the discreteZoom option when determining the new view.

ignoreClampBounds boolean | 'limited' optional

If true ignore the clampBoundsX and clampBoundsY options when determining the new view. When 'limited', the clampBoundsX and clampBoundsY options are selectively enforced so that the map will not end up more out of bounds than its current state.

Fires:
Returns:
Type Description
this

Get/set parent of the object.

Name Type Description
arg geo.sceneObject optional

The new parant or undefined to get the current parent.

Returns:
Type Description
this | geo.sceneObject

inherited removeChild(child){this}

Remove a child (or array of children) from the object.

Name Type Description
child geo.object | Array.<geo.object>

A child object or array of child objects.

Returns:
Type Description
this

rotatedSize(){geo.screenSize}

Get the rotated size of the map. This is the width and height of the non-rotated area necessary to enclose the rotated area in pixels.

Returns:
Type Description
geo.screenSize The size that fits the rotated map.

rotation(rotation, origin, ignoreRotationFunc){number|this}

Get/set the map rotation. The rotation is performed around the current view center. Rotation mostly ignores clampBoundsX, as the behavior feels peculiar otherwise.

Name Type Description
rotation number

Absolute angle in radians (positive is clockwise).

origin object optional

If specified, rotate about this origin.

Name Type Description
geo geo.geoPosition

The gcs coordinates of the rotation center.

map geo.screenPosition

The display coordinates of the rotation center.

ignoreRotationFunc boolean optional

If true, don't constrain the rotation.

Fires:
Returns:
Type Description
number | this

scheduleAnimationFrame(callback, action){number}

Instead of each function using window.requestAnimationFrame, schedule all such frames through this function. This allows the callbacks to be reordered or removed as needed and reduces overhead in Chrome a small amount. Also, if the animation queue is shared between map instances, the callbacks will be called in a single time slice, providing better synchronization.

Name Type Default Description
callback function

Function to call during the animation frame. It is called with an animation epoch, exactly as requestAnimationFrame.

action boolean | 'remove' false optional

Falsy to only add the callback if it is not already scheduled. 'remove' to remove the callback (use this instead of cancelAnimationFrame). Any other truthy value moves the callback to the end of the list.

Returns:
Type Description
number An integer as returned by window.requestAnimationFrame.

screenshot(layers, type, encoderOptions, opts){deferred}

Get a screen-shot of all or some of the canvas layers of map. Note that webGL layers are rerendered, even if window.overrideContextAttributes.preserveDrawingBuffer = true; is set before creating the map object. Chrome, at least, may not keep the drawing buffers if the tab loses focus (and returning focus won't necessarily rerender).

Name Type Default Description
layers geo.layer | Array.<geo.layer> | false | object optional

Either a layer, a list of layers, falsy to get all layers, or an object that contains optional values of layers, type, encoderOptions, and additional values listed in the opts parameter (this last form allows a single argument for the function).

type string 'image/png' optional

See canvas.toDataURL. Use 'canvas' to return the canvas element (this can be used to get the results as a blob, which can be faster for some operations but is not supported as widely).

encoderOptions number optional

See canvas.toDataURL.

opts object optional

Additional screenshot options.

Name Type Default Description
background false | string | CanvasRenderingContext2D.fillStyle 'white' optional

If false or null, don't prefill the background. Otherwise, a css color or CanvasRenderingContext2D.fillStyle to fill the initial canvas. This could match the background of the browser page, for instance.

wait boolean | 'idle' false optional

If 'idle', wait for the map to be idle and one additional animation frame to occur. If truthy, wait for an animation frame to occur. Otherwise, take the screenshot as soon as possible.

attribution boolean | null null optional

If null or unspecified, include the attribution only if all layers are used. If false, never include the attribution. If true, always include it.

Fires:
Returns:
Type Description
deferred A jQuery Deferred object. The done function receives either a data URL or an HTMLCanvasElement with the result.

size(arg){geo.screenSize|this}

Get or set the size of the map.

Name Type Description
arg geo.screenSize optional

Size in pixels.

Fires:
Returns:
Type Description
geo.screenSize | this The size in pixels or the map object.

sortedLayers(){Array.<geo.layer>}

Get the layers contained in the map sorted by zIndex. If two layers have the same zIndex, they are returned in creation order.

Returns:
Type Description
Array.<geo.layer>

inherited timestamp(){number}

Get time.

Returns:
Type Description
number The timestamp. This is 0 if the timestamp has never been modified.

transition(opts, gcs, animTime){geo.map}

Get the current transition or start an animated zoom/pan/rotate. If a second transition is requested while a transition is already in progress, a new transition is created that is functionally from wherever the map has moved to (possibly partway through the first transition) going to the end point of the new transition.

Name Type Description
opts object optional

Options for a transition, or undefined to get the current transition.

Name Type Default Description
center geo.geoPosition optional

A new map center.

zoom number optional

A new map zoom level.

zoomOrigin geo.geoPosition optional

An origin to use when zooming to a new zoom level.

rotation number optional

A new map rotation.

duration number 1000 optional

Transition duration in milliseconds.

ease function optional

Easing function for the transition. This is in the style of a d3 easing function.

interp function optional

Function to use when interpolating between values. This gets passed two arrays, the start and end values for [x, y, z or zoom, rotation], and returns a function that, when passed a time value returns an array of the interpolated [x, y, z or zoom, rotation] values.

zCoord boolean optional

If true, convert zoom values to z values for interpolation.

done function optional

If specified, call this function when a transition completes. The function is called with an object that contains cancel: a boolean if the transition was canceled, source: a value based on what canceled a transition, transition: the current transition that just completed, next: a boolean if another transition follows immediately.

gcs string | geo.transform | null optional

Input gcs. undefined to use the interface gcs, null to use the map gcs, or any other transform. Applies only to opts.center and to converting zoom values to height, if specified.

animTime number optional

The animation frame time (from a window.requestAnimationFrame callback). Used if a new transition is requested because the current transition has completed to keep things synchronized.

Fires:
Returns:
Type Description
geo.map

transitionCancel(source){boolean}

Cancel any existing transition. The transition will send a cancel event at the next animation frame, but no further activity occurs.

Name Type Description
source string optional

Optional cause of the cancel. This can be any value, but something like (method name).(action) is recommended to allow other functions to determine the source and cause of the transition being canceled.

Fires:
Returns:
Type Description
boolean true if a transition was in progress.

unitsPerPixel(zoom, unit){number|this}

Get/set the number of world space units per display pixel at the given zoom level.

Name Type Default Description
zoom number 0 optional

The target zoom level.

unit number optional nullable

If present, set the unitsPerPixel at the specified zoom level. Otherwise return the current value.

Returns:
Type Description
number | this

updateAttribution(){this}

Update the attribution notice displayed on the bottom right corner of the map. The content of this notice is managed by individual layers. This method queries all of the visible layers and joins the individual attribution notices into a single element. By default, this method is called on each of the following events:

In addition, layers should call this method when their own attribution notices have changed. Users, in general, should not need to call this.

Returns:
Type Description
this Chainable.

Convert from world coordinates to display coordinates using the attached camera.

Name Type Description
c geo.worldPosition | Array.<geo.worldPosition>

The input coordinate to convert.

Returns:
Type Description
geo.screenPosition | Array.<geo.screenPosition> Display space coordinates.

worldToGcs(c, gcs){geo.geoPosition|Array.<geo.geoPosition>}

Convert from map world coordinates to gcs coordinates.

Name Type Description
c geo.worldPosition | Array.<geo.worldPosition>

The input coordinate to convert.

gcs string | geo.transform | null optional

output gcs. undefined to use the interface gcs, null to use the map gcs, or any other transform.

Returns:
Type Description
geo.geoPosition | Array.<geo.geoPosition> GCS space coordinates.

zoom(val, origin, ignoreDiscreteZoom){number|this}

Get/Set zoom level of the map.

Name Type Description
val number optional

If undefined, return the current zoom level. Otherwise, the new zoom level to set.

origin object optional

If present, specifies the center of the zoom; otherwise the map's display center is used.

Name Type Description
geo geo.geoPosition

The gcs coordinates of the zoom center.

map geo.screenPosition

The display coordinates of the zoom center.

ignoreDiscreteZoom boolean optional

If true, ignore the discreteZoom option when determining the new view.

Fires:
Returns:
Type Description
number | this

zoomAndCenterFromBounds(bounds, rotation, gcs){geo.zoomAndCenter}

Get the center zoom level necessary to display the given bounds.

Name Type Description
bounds geo.geoBounds

The requested map bounds. right must be greater than left and bottom must be greater than top in the map's gcs (after conversion from the provided gcs).

rotation number

Rotation in clockwise radians.

gcs string | geo.transform | null optional

undefined to use the interface gcs, null to use the map gcs, or any other transform.

Returns:
Type Description
geo.zoomAndCenter

zoomRange(arg, noRefresh){object|this}

Get or set the min/max zoom range.

Name Type Description
arg object optional

The zoom range.

Name Type Description
min number optional

The minimum zoom level.

max number optional

The maximum zoom level.

noRefresh boolean optional

If true, don't update the map if the zoom level has changed.

Returns:
Type Description
object | this The current zoom range or the map object. The min value is the minimum value that the map can go to based on the current dimensions and settings, the origMin value is the value that was specified via this function or when the map was created.

innerlayerZIndexSort(a, b){number}

Comapare two layers by zIndex. If the zIndex is the same, the order in the parent element is used. If the two layers don't have the same parent (for instance, one layer isn't attached to the map), layers in the map are sorted below detached layers.

Name Type Description
a geo.layer

First layer to compare.

b geo.layer

Second layer to compare.

Returns:
Type Description
number Positive if a is above b.