new geo.tileLayer(arg){geo.tileLayer}
This method defines a tileLayer, an abstract class defining a layer
divided into tiles of arbitrary data. Notably, this class provides the
core functionality of geo.osmLayer
, but hooks exist to render
tiles more generically. When multiple zoom levels are present in a given
dataset, this class assumes that the space occupied by tile (i, j)
at
level z
is covered by a 2x2 grid of tiles at zoom level z + 1
:
(2i, 2j), (2i, 2j + 1)
(2i + 1, 2j), (2i + 1, 2j + 1)
The higher level tile set should represent a 2x increase in resolution.
Name | Type | Description |
---|---|---|
arg |
geo.tileLayer.spec |
optional
Specification for the layer. |
Returns:
Type | Description |
---|---|
geo.tileLayer |
Extends
Type Definitions
-
geo.tileLayer.specgeo.layer.spec
-
Object specification for a tile layer.
Properties:
Name Type Argument Default Description minLevel
number <optional>
0 The minimum zoom level available.
maxLevel
number <optional>
18 The maximum zoom level available.
tileOverlap
object <optional>
Pixel overlap between tiles.
Properties
Name Type Argument Description x
number <optional>
Horizontal overlap.
y
number <optional>
Vertical overlap.
tileWidth
number <optional>
256 The tile width without overlap.
tileHeight
number <optional>
256 The tile height without overlap.
tilesAtZoom
function <optional>
null A function that is given a zoom level and returns
{x: (num), y: (num)}
with the number of tiles at that zoom level.cacheSize
number <optional>
600 The maximum number of tiles to cache. The default is 200 if keepLower is false.
queue
geo.fetchQueue <optional>
A fetch queue to use. If unspecified, a new queue is created.
queueSize
number <optional>
6 The queue size. Most browsers make at most 6 requests to any domain, so this should be no more than 6 times the number of subdomains used.
initialQueueSize
number <optional>
0 The initial queue size.
0
to use the queue size. When querying a tile server that needs to load information before serving the first tile, having an initial queue size of 1 can reduce the load on the tile server. After the initial queue of tiles are loaded, thequeueSize
is used for all additional queries unless theinitialQueueSize
is set again or the tile cache is reset.keepLower
boolean <optional>
true When truthy, keep lower zoom level tiles when showing high zoom level tiles. This uses more memory but results in smoother transitions.
wrapX
boolean <optional>
true Wrap in the x-direction.
wrapY
boolean <optional>
false Wrap in the y-direction.
url
string | function <optional>
null A function taking the current tile indices
(x, y, level, subdomains)
and returning a URL or jquery ajax config to be passed to the {geo.tile} constructor. Example:(x, y, z, subdomains) => "http://example.com/z/y/x.png"
If this is a string, a template url with {x}, {y}, {z}, and {s} as template variables. {s} picks one of the subdomains parameter and may contain a comma-separated list of subdomains.
subdomains
string | Array.<string> <optional>
"abc" Subdomains to use in template url strings. If a string, this is converted to a list before being passed to a url function.
baseUrl
string <optional>
null If defined, use the old-style base url instead of the url parameter. This is functionally the same as using a url of
baseUrl/{z}/{x}/{y}.(imageFormat || png)
. If the specified string does not end in a slash, one is added.imageFormat
string <optional>
'png' This is only used if a
baseUrl
is specified, in which case it determines the image name extension used in the url.animationDuration
number <optional>
0 The number of milliseconds for the tile loading animation to occur. Only some renderers support this.
attribution
string <optional>
An attribution to display with the layer (accepts HTML).
tileRounding
function <optional>
Math.round This function determines which tiles will be loaded when the map is at a non-integer zoom. For example,
Math.floor
, will use tile level 2 when the map is at zoom 2.9.tileOffset
function <optional>
This function takes a zoom level argument and returns, in units of pixels, the coordinates of the point (0, 0) at the given zoom level relative to the bottom left corner of the domain.
tilesMaxBounds
function <optional>
null This function takes a zoom level argument and returns an object with
x
andy
in pixels which is used to crop the last row and column of tiles. Note that if tiles wrap, only complete tiles in the wrapping direction(s) are supported, and this max bounds will probably not behave properly.topDown
boolean <optional>
false True if the gcs is top-down, false if bottom-up (the ingcs does not matter, only the gcs coordinate system). When falsy, this inverts the gcs y-coordinate when calculating local coordinates.
idleAfter
string <optional>
'view' Consider the layer as idle once a specific set of tiles is loaded. 'view' is when all tiles in view are loaded. 'all' is when tiles in view and tiles that were once requested have been loaded (this corresponds to having all network activity finished).
baseQuad
object <optional>
A quad feature element to draw before below any tile layers. If specified, this uses the quad defaults, so this is a
geo.quadFeature.position
object with, typically, animage
property added to it. The quad positions are in the map gcs coordinates.nearestPixel
boolean | number <optional>
If true, image quads are rendered with near-neighbor sampling. If false, with interpolated sampling. If a number, interpolate at that zoom level or below and nearest neighbor at that zoom level or above.
id
number <optional>
The id of the layer. Defaults to a increasing sequence.
map
geo.map <optional>
null Parent map of the layer.
renderer
string | geo.renderer <optional>
Renderer to associate with the layer. If not specified, either
annotations
orfeatures
can be used to determine the renderer. If ageo.renderer
instance, the renderer is not recreated; not all renderers can be shared by multiple layers.autoshareRenderer
boolean | string <optional>
true If truthy and the renderer supports it, auto-share renderers between layers. Currently, auto-sharing can only occur for webgl renderers and adjacent layers. If
true
, sharing will only occur if the layers have the same opacity and it is 1 or 0 and any tile layers are below non-tile layers. If"more"
, sharing will occur for any adjacent layers that have the same opacity. Shared renderers has slightly different behavior than non-shared renderers: changing z-index may result in rerendering and be slightly slower; only one DOM canvas is used for all shared renderers. Some features have slight z-stacking differences in shared versus non-shared renderers.canvas
HTMLElement <optional>
If specified, use this canvas rather than a canvas associaied with the renderer directly. Renderers may not support sharing a canvas.
annotations
Array.<string> | object <optional>
A list of annotations that will be used on this layer, used to select a renderer. Instead of a list, if this is an object, the keys are the annotation names, and the values are each a list of modes that will be used with that annotation. See
featuresForAnnotations
more details. This is ignored ifrenderer
is specified.features
Array.<string> <optional>
A list of features that will be used on this layer, used to select a renderer. Features are the basic feature names (e.g.,
'quad'
), or the feature name followed by a required capability (e.g.,'quad.image'
). This is ignored ifrenderer
orannotations
is specified.active
boolean <optional>
true Truthy if the layer has the
active
css class and may receive native mouse events.opacity
number <optional>
1 The layer opacity on a scale of [0-1].
name
string <optional>
'' A name for the layer for user convenience. If specified, this is also the
id
property of the containing DOM element.selectionAPI
boolean <optional>
true Truthy if the layer can generate selection and other interaction events.
sticky
boolean <optional>
true Truthy if the layer should navigate with the map.
visible
boolean <optional>
true Truthy if the layer is visible.
zIndex
number <optional>
The z-index to assign to the layer (defaults to the index of the layer inside the map).
Static Members
-
staticgeo.tileLayer.baseQuad
-
Get/set the baseQuad.
Properties:
Name Type Argument Description baseQuad
object <optional>
A quad feature element to draw below any tile layers. If specified, this uses the quad defaults, so this is a
geo.quadFeature.position
object with, typically, animage
property added to it. The quad positions are in the map gcs coordinates. -
staticgeo.tileLayer.defaults
-
This object contains the default options used to initialize the tileLayer.
Members
-
activeTiles
-
Readonly accessor to the active tile mapping. This is an object containing all currently drawn tiles (hash(tile) => tile).
Properties:
Name Type Description activeTiles
object The keys are
hash(tile)
and the values are tiles. -
cache
-
Readonly accessor to the tile cache object.
Properties:
Name Type Description cache
geo.tileCache The tile cache object.
-
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). -
inherited protectednewLayerId
-
Gets a new id number for a layer.
-
options
-
Readonly accessor to the options object.
Properties:
Name Type Description options
object A copy of the options object.
-
queue
-
Get/set the queue object.
Properties:
Name Type Description queue
geo.fetchQueue The current queue.
-
queueSize
-
Get/set the queue size.
Properties:
Name Type Description size
number The queue size.
-
queueSize
-
Get/set the initial queue size.
Properties:
Name Type Description size
number The initial queue size.
0
to use the queue size. -
reference
-
Get/set the tile reference value.
Properties:
Name Type Description reference
string A reference value to distinguish tiles on this layer.
Methods
-
Get/Set whether or not the layer is active. An active layer will receive native mouse when the layer is on top. Non-active layers will never receive native mouse events.
Name Type Description arg
boolean optional If specified, the new
active
value.Returns:
Type Description boolean | this -
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 addFeature(feature){this}
-
Add a feature to the layer if it is not already present.
Name Type Description feature
object the feature to add.
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 -
Get or set the attribution html content that will displayed with the layer. By default, nothing will be displayed. Note, this content is not html escaped, so care should be taken when rendering user provided content.
Name Type Description arg
string nullable An html fragment
Returns:
Type Description string | this Chainable as a setter -
Get the setting of autoshareRenderer.
Returns:
Type Description boolean | string -
Get canvas of the layer.
Returns:
Type Description HTMLCanvasElement The canvas element associated with the layer. -
inherited children(){Array.<geo.object>}
-
Get an array of the child objects.
Returns:
Type Description Array.<geo.object> A copy of the array of child objects. -
clear(){Array.<geo.tile>}
-
Remove all active tiles from the canvas.
Returns:
Type Description Array.<geo.tile> The array of tiles removed. -
inherited createFeature(featureName, arg){geo.feature}
-
Create a feature by name.
Name Type Description featureName
string The name of the feature to create.
arg
object Properties for the new feature.
Returns:
Type Description geo.feature The created feature. -
inherited dataTime(){geo.timestamp}
-
Return last time data got changed.
Returns:
Type Description geo.timestamp The data time. -
inherited deleteFeature(feature){this}
-
Delete feature.
Name Type Description feature
geo.feature The feature to delete.
Returns:
Type Description this -
displayToLevel(pt, zoom){object}
-
Convert display pixel coordinates (where (0,0) is the upper left) to layer pixel coordinates (typically (0,0) is the center of the map and the upper-left has the most negative values). By default, this is done at the current base zoom level.
Name Type Description pt
object optional The point to convert with
x
andy
. Ifundefined
, use the center of the display.zoom
number optional If specified, the zoom level to use.
Returns:
Type Description object The point in level coordinates with x
andy
. -
inherited draw(){this}
-
Draw. If the layer is visible, call the parent class's draw function and the renderer's render function.
Returns:
Type Description this -
drawTile(tile)
-
Draw the given tile on the active canvas .
Name Type Description tile
geo.tile The tile to draw.
-
inherited features(val){Array.<geo.feature>|this}
-
Get/Set drawables.
Name Type Description val
Array.<geo.feature> optional A list of features, or unspecified to return the current feature list. If a list is provided, features are added or removed as needed.
Returns:
Type Description Array.<geo.feature> | this The current features associated with the layer or the current layer. -
fromLevel(coord, level){object}
-
Convert a coordinate from pixel coordinates at the given zoom level to world coordinates.
Name Type Description coord
object Name Type Description x
number The offset in pixels (level 0) from the left edge.
y
number The offset in pixels (level 0) from the bottom edge.
level
number The zoom level of the source coordinates.
Returns:
Type Description object World coordinates with x
andy
. -
fromLocal(pt, zoom){object}
-
Compute world coordinates from the given local coordinates. The tile layer uses units of pixels relative to the world space coordinate origin.
Name Type Description pt
object A point in world space coordinates with
x
andy
.zoom
number | undefined If unspecified, use the map zoom.
Returns:
Type Description object Local coordinates with x
andy
. -
gcs(arg){string|this}
-
Get or set the layer gcs. This defaults to the map's gcs.
Name Type Description arg
string optional If
undefined
, return the current gcs. Otherwise, a new value for the gcs. Ifnull
, use the map's gcs.Returns:
Type Description string | this A string used by geo.transform
. -
inherited gcsFeatures(val){string|this}
-
Get or set the gcs for all features. For features, the default is usually the map's ingcs.
Name Type Description val
string optional nullable If
undefined
, return the current gcs. Ifnull
, use the map's interface gcs. Otherwise, set a new value for the gcs. When getting the current gcs, if not all features have the same gcs,undefined
will be returned.Returns:
Type Description string | this A string used by geo.transform
. If the map interface gcs is in use, that value will be returned. If the gcs is set, return the current class instance. -
gcsTileBounds(indexOrTile, gcs){object}
-
Returns a tile's bounds in a gcs.
Name Type Description indexOrTile
object | geo.tile Either a tile or an object with {x, y, level}` specifying a tile.
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 object The tile bounds in the specified gcs. -
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 reporttrue
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. -
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, orundefined
to remove all events (in which casearg
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 -
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 ageo.event
object.Returns:
Type Description this -
Bind an event handler to this object that will fire once and then deregister itself.
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 ageo.event
object.Returns:
Type Description function The actual bound handler. This is a wrapper around the handler that was passed to the function. -
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 -
Return the height of the layer in pixels.
Returns:
Type Description number The height of the parent map in pixels. -
Get/Set id of the layer.
Name Type Description val
string | null optional If
null
, generate a new layer id. Otherwise, if specified, the new id of the layer.Returns:
Type Description string | this -
Get/Set if the layer has been initialized.
Name Type Description val
boolean optional If specified, update the initialized value. Otherwise, return the current instance.
Returns:
Type Description boolean | this Either the initialized value or this. -
isValid(index){boolean}
-
Returns
true
if the given tile index is valid:- min level <= level <= max level
- 0 <= x <= 2^level - 1
- 0 <= y <= 2^level - 1 If the layer wraps, the x and y values may be allowed to extend beyond these values.
Name Type Description index
object The tile index.
Name Type Description x
number y
number level
number Returns:
Type Description boolean -
Get the map associated with this layer.
Returns:
Type Description geo.map The map associated with the layer. -
inherited modified(){this}
-
Update the timestamp to the next global timestamp value.
Returns:
Type Description this -
Bring the layer below the given number of layers. This will rotate the current z-indices for this and the previous
n
layers.Name Type Default Description n
number 1 optional The number of positions to move.
Returns:
Type Description this -
Bring the layer to the bottom of the map layers.
Returns:
Type Description this -
Bring the layer to the top of the map layers.
Returns:
Type Description this -
Bring the layer above the given number of layers. This will rotate the current z-indices for this and the next
n
layers.Name Type Default Description n
number 1 optional The number of positions to move.
Returns:
Type Description this -
Get/Set name of the layer.
Name Type Description val
string optional If specified, the new name of the layer.
Returns:
Type Description string | this -
nearestPixel(val, skipUpdate){boolean|number|this}
-
Get/Set nearestPixel value.
Name Type Description val
boolean | number optional If not specified, return the current value. If true, image quads are rendered with near-neighbor sampling. If false, with interpolated sampling. If a number, interpolate at that zoom level or below and nearest neighbor at that zoom level or above.
skipUpdate
boolean optional If specifying val and this value is truthy, don't update the layer or mark it as modified.
Returns:
Type Description boolean | number | this -
Get root node of the layer.
Returns:
Type Description HTMLDivElement -
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 or set the current layer opacity. The opacity is in the range [0-1]. An opacity of 0 is not the same as setting
visible(false)
, as interactions can still occur with the layer.Name Type Description opacity
number optional If specified, set the opacity. Otherwise, return the opacity.
Returns:
Type Description number | this The current opacity or the current layer. -
inherited parent(arg){this|geo.sceneObject}
-
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 -
prefetch(level, bounds){jQuery.Deferred}
-
Prefetches tiles up to a given zoom level around a given bounding box.
Name Type Description level
number The zoom level.
bounds
geo.geoBounds The map bounds.
Returns:
Type Description jQuery.Deferred resolves when all of the tiles are fetched. -
remove(tile){geo.tile}
-
Remove the given tile from the canvas and the active cache.
Name Type Description tile
geo.tile | string The tile (or hash) to remove.
Returns:
Type Description geo.tile The tile removed from the active layer. -
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 -
inherited removeFeature(feature){this}
-
Remove a feature without destroying it.
Name Type Description feature
geo.feature The feature to remove.
Returns:
Type Description this -
inherited removePromise(promise){this}
-
Remove the promise here and also propagate up the scene tree.
Name Type Description promise
Promise A promise object.
Returns:
Type Description this -
inherited renderer(){geo.renderer}
-
Get the renderer for the layer.
Returns:
Type Description geo.renderer The renderer associated with the layer or null
if there is no renderer. -
Get the name of the renderer.
Returns:
Type Description string -
reset(){this}
-
Reset the layer to the initial state, clearing the canvas and resetting the tile cache.
Returns:
Type Description this -
inherited selectionAPI(val){boolean|this}
-
Get/Set selectionAPI of the layer.
Name Type Description val
boolean optional If specified change the selectionAPI state of the layer, otherwise return the current state.
Returns:
Type Description boolean | this The selectionAPI state or the current layer. -
Get whether or not the layer is sticky (navigates with the map).
Returns:
Type Description boolean -
subdomains(subdomains){string|Array.<string>|this}
-
Get or set the subdomains used for templating.
Name Type Description subdomains
string | Array.<string> optional A comma-separated list, a string of single character subdomains, or a list.
Returns:
Type Description string | Array.<string> | this -
tileAtPoint(point, level){object}
-
Returns the tile indices at the given point.
Name Type Description point
object The coordinates in pixels relative to the map origin.
Name Type Description x
number y
number level
number The target zoom level.
Returns:
Type Description object The tile indices. This has x
andy
properties. -
tileCropFromBounds(tile){object}
-
Get the crop values for a tile based on the tilesMaxBounds function. Returns undefined if the tile should not be cropped.
Name Type Description tile
object The tile to compute crop values for.
Returns:
Type Description object Either undefined
or an object withx
andy
values which is the size in pixels for the tile. -
tilesAtZoom(level){object}
-
The number of tiles at the given zoom level. The default implementation just returns
Math.pow(2, z)
.Name Type Description level
number A zoom level.
Returns:
Type Description object The number of tiles in each axis in the form {x: nx, y: ny}
. -
tilesMaxBounds(level){object}
-
The maximum tile bounds at the given zoom level, or null if no special tile bounds.
Name Type Description level
number A zoom level.
Returns:
Type Description object The maximum tile bounds in pixels for the specified level, or null if none specified ( {x: width, y: height}
). -
inherited timestamp(){number}
-
Get time.
Returns:
Type Description number The timestamp. This is 0 if the timestamp has never been modified. -
toLevel(coord, level){object}
-
Convert a coordinate from layer coordinates to pixel coordinates at the given zoom level.
Name Type Description coord
object Name Type Description x
number The offset in pixels (level 0) from the left edge.
y
number The offset in pixels (level 0) from the bottom edge.
level
number The zoom level of the new coordinates.
Returns:
Type Description object The pixel coordinates with x
andy
. -
toLocal(pt, zoom){object}
-
Compute local coordinates from the given world coordinates. The tile layer uses units of pixels relative to the world space coordinate origin.
Name Type Description pt
object A point in world space coordinates with
x
andy
.zoom
number optional If unspecified, use the map zoom.
Returns:
Type Description object Local coordinates with x
andy
. -
inherited updateTime(){geo.timestamp}
-
Return the modified time for the last update that did something.
Returns:
Type Description geo.timestamp The update time. -
url(url){string|function|this}
-
Get or set the tile url string or function. If changed, load the new tiles.
Name Type Description url
string | function optional The new tile url.
Returns:
Type Description string | function | this -
visible(val){boolean|this}
-
Get/Set visibility of the layer.
Name Type Description val
boolean optional If unspecified, return the visibility, otherwise set it.
Returns:
Type Description boolean | this Either the visibility (if getting) or the layer (if setting). -
Return the width of the layer in pixels.
Returns:
Type Description number The width of the parent map in pixels. -
Get or set the z-index of the layer. The z-index controls the display order of the layers in much the same way as the CSS z-index property.
Name Type Description zIndex
number optional The new z-index, or undefined to return the current z-index.
allowDuplicate
boolean optional When setting the z index, if this is truthy, allow other layers to have the same z-index. Otherwise, ensure that other layers have distinct z-indices from this one.
Returns:
Type Description number | this