Properties and options | UNL Map JS Docs

UNL Map JS's global properties and options that you can access while initializing your map or accessing information about its status.

workerCount

Gets and sets the number of web workers instantiated on a page with GL JS maps. By default, it is set to half the number of CPU cores (capped at 6). Make sure to set this property before creating any map instances for it to have effect.

Returns

number: Number of workers currently configured.

Example

UnlSdk.workerCount = 2;

maxParallelImageRequests

Gets and sets the maximum number of images (raster tiles, sprites, icons) to load in parallel, which affects performance in raster-heavy maps. 16 by default.

Returns

number: Number of parallel requests currently configured.

Example

UnlSdk.maxParallelImageRequests = 10;

supported

Test whether the browser supports UNL Map JS.

Parameters

options(Object?)

Name	Description
options.failIfMajorPerformanceCaveat `boolean` default: `false`	If `true` , the function will return `false` if the performance of UNL Map JS would be dramatically worse than expected (e.g. a software WebGL renderer would be used).

Returns

boolean:

Example

// Show an alert if the browser does not support UNL Map JS
if (!UnlSdk.supported()) {
alert('Your browser does not support UNL Map JS');
}

Check for browser support

setRTLTextPlugin

Sets the map's RTL text plugin. Necessary for supporting the Arabic and Hebrew languages, which are written right-to-left.

Parameters

pluginURL(string)URL pointing to the map RTL text plugin source.

callback(Function)Called with an error argument if there is an error.

lazy(boolean)If set to true , map will defer loading the plugin until rtl text is encountered, rtl text will then be rendered only after the plugin finishes loading.

Add support for right-to-left scripts

getRTLTextPluginStatus

Gets the map's RTL text plugin status. The status can be unavailable (i.e. not requested or removed), loading, loaded or error. If the status is loaded and the plugin is requested again, an error will be thrown.

Example

const pluginStatus = UnlSdk.getRTLTextPluginStatus();

clearStorage

Clears browser storage used by this library. Using this method flushes the Unl Map Js tile cache that is managed by this library. Tiles may still be cached by the browser in some cases.

This API is supported on browsers where the Cache API is supported and enabled. This includes all major browsers when pages are served over https://, except Internet Explorer and Edge Mobile.

When called in unsupported browsers or environments (private or incognito mode), the callback will be called with an error argument.

Parameters

callback(Function)Called with an error argument if there is an error.

Example

UnlSdk.clearStorage();

addProtocol

Sets a custom load tile function that will be called when using a source that starts with a custom url schema. The example below will be triggered for custom:// urls defined in the sources list in the style definitions. The function passed will receive the request parameters and should call the callback with the resulting request, for example a pbf vector tile, non-compressed, represented as ArrayBuffer.

Parameters

customProtocol(string)the protocol to hook, for example 'custom'

loadFn(Function)the function to use when trying to fetch a tile specified by the customProtocol

Example

// this will fetch a file using the fetch API (this is obviously a non iteresting example...)
UnlSdk.addProtocol('custom', (params, callback) => {
fetch(`https://${params.url.split("://")[1]}`)
.then(t => {
if (t.status == 200) {
t.arrayBuffer().then(arr => {
callback(null, arr, null, null);
});
} else {
callback(new Error(`Tile fetch error: ${t.statusText}`));
}
})
.catch(e => {
callback(new Error(e));
});
return { cancel: () => { } };
});
// the following is an example of a way to return an error when trying to load a tile
UnlSdk.addProtocol('custom2', (params, callback) => {
callback(new Error('someErrorMessage'));
return { cancel: () => { } };
});

removeProtocol

Removes a previusly added protocol

Parameters

customProtocol(string)the custom protocol to remove registration for

Example

UnlSdk.removeProtocol('custom');

AnimationOptions

Options common to map movement methods that involve animation, such as Map#panBy and Map#easeTo, controlling the duration and easing function of the animation. All properties are optional.

Properties

duration(number): The animation's duration, measured in milliseconds.

easing(Function): A function taking a time in the range 0..1 and returning a number where 0 is the initial state and 1 is the final state.

offset(PointLike): of the target center relative to real map container center at the end of animation.

animate(boolean): If false , no animation will occur.

essential(boolean): If true , then the animation is considered essential and will not be affected by prefers-reduced-motion .

CameraOptions

Options common to Map#jumpTo, Map#easeTo, and Map#flyTo, controlling the desired location, zoom, bearing, and pitch of the camera. All properties are optional, and when a property is omitted, the current camera value for that property will remain unchanged.

Properties

center(LngLatLike): The desired center.

zoom(number): The desired zoom level.

bearing(number): The desired bearing in degrees. The bearing is the compass direction that is "up". For example, bearing: 90 orients the map so that east is up.

pitch(number): The desired pitch in degrees. The pitch is the angle towards the horizon measured in degrees with a range between 0 and 60 degrees. For example, pitch: 0 provides the appearance of looking straight down at the map, while pitch: 60 tilts the user's perspective towards the horizon. Increasing the pitch value is often used to display 3D objects.

around(LngLatLike): If zoom is specified, around determines the point around which the zoom is centered.

padding(PaddingOptions): Dimensions in pixels applied on each side of the viewport for shifting the vanishing point.

Example

// set the map's initial perspective with CameraOptions
var map = new UnlSdk.Map({
container: 'map',
center: [-73.5804, 45.53483],
pitch: 60,
bearing: -60,
zoom: 10
});

PaddingOptions

Options for setting padding on calls to methods such as Map#fitBounds, Map#fitScreenCoordinates, and Map#setPadding. Adjust these options to set the amount of padding in pixels added to the edges of the canvas. Set a uniform padding on all edges or individual values for each edge. All properties of this object must be non-negative integers.

Properties

top(number)

bottom(number)

right(number)

left(number)

Example

var bbox = [[-79, 43], [-73, 45]];
map.fitBounds(bbox, {
padding: {top: 10, bottom:25, left: 15, right: 5}
});

var bbox = [[-79, 43], [-73, 45]];
map.fitBounds(bbox, {
padding: 20
});

Static Members

RequestParameters

A RequestParameters object to be returned from Map.options.transformRequest callbacks.

Properties

url(string): The URL to be requested.

headers(Object): The headers to be sent with the request.

method(string): Request method 'GET' | 'POST' | 'PUT' .

body(string): Request body.

type(string): Response body type to be returned 'string' | 'json' | 'arrayBuffer' .

credentials(string): 'same-origin'|'include' Use 'include' to send cookies with cross-origin requests.

collectResourceTiming(boolean): If true, Resource Timing API information will be collected for these transformed requests and returned in a resourceTiming property of relevant data events.

Example

// use transformRequest to modify requests that begin with `http://myHost`
transformRequest: function(url, resourceType) {
if (resourceType === 'Source' && url.indexOf('http://myHost') > -1) {
return {
url: url.replace('http', 'https'),
headers: { 'my-custom-header': true },
credentials: 'include'  // Include cookies for cross-origin requests
}
}
}

StyleImageInterface

Interface for dynamically generated style images. This is a specification for implementers to model: it is not an exported method or class.

Images implementing this interface can be redrawn for every frame. They can be used to animate icons and patterns or make them respond to user input. Style images can implement a StyleImageInterface#render method. The method is called every frame and can be used to update the image.

Example

var flashingSquare = {
width: 64,
height: 64,
data: new Uint8Array(64 * 64 * 4),
 
onAdd: function(map) {
this.map = map;
},
 
render: function() {
// keep repainting while the icon is on the map
this.map.triggerRepaint();
 
// alternate between black and white based on the time
var value = Math.round(Date.now() / 1000) % 2 === 0  ? 255 : 0;
 
// check if image needs to be changed
if (value !== this.previousValue) {
this.previousValue = value;
 
var bytesPerPixel = 4;
for (var x = 0; x < this.width; x++) {
for (var y = 0; y < this.height; y++) {
var offset = (y * this.width + x) * bytesPerPixel;
this.data[offset + 0] = value;
this.data[offset + 1] = value;
this.data[offset + 2] = value;
this.data[offset + 3] = 255;
}
}
 
// return true to indicate that the image changed
return true;
}
}
}
 
map.addImage('flashing_square', flashingSquare);

Instance Members

Add an animated icon to the map.

CustomLayerInterface

Interface for custom style layers. This is a specification for implementers to model: it is not an exported method or class.

Custom layers allow a user to render directly into the map's GL context using the map's camera. These layers can be added between any regular layers using Map#addLayer.

Custom layers must have a unique id and must have the type of "custom". They must implement render and may implement prerender, onAdd and onRemove. They can trigger rendering using Map#triggerRepaint and they should appropriately handle Map.event:webglcontextlost and Map.event:webglcontextrestored.

The renderingMode property controls whether the layer is treated as a "2d" or "3d" map layer. Use:

"renderingMode": "3d" to use the depth buffer and share it with other layers
"renderingMode": "2d" to add a layer with no depth. If you need to use the depth buffer for a "2d" layer you must use an offscreen framebuffer and CustomLayerInterface#prerender

Example

// Custom layer implemented as ES6 class
class NullIslandLayer {
constructor() {
this.id = 'null-island';
this.type = 'custom';
this.renderingMode = '2d';
}
 
onAdd(map, gl) {
const vertexSource = `
uniform mat4 u_matrix;
void main() {
gl_Position = u_matrix * vec4(0.5, 0.5, 0.0, 1.0);
gl_PointSize = 20.0;
}`;
 
const fragmentSource = `
void main() {
gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0);
}`;
 
const vertexShader = gl.createShader(gl.VERTEX_SHADER);
gl.shaderSource(vertexShader, vertexSource);
gl.compileShader(vertexShader);
const fragmentShader = gl.createShader(gl.FRAGMENT_SHADER);
gl.shaderSource(fragmentShader, fragmentSource);
gl.compileShader(fragmentShader);
 
this.program = gl.createProgram();
gl.attachShader(this.program, vertexShader);
gl.attachShader(this.program, fragmentShader);
gl.linkProgram(this.program);
}
 
render(gl, matrix) {
gl.useProgram(this.program);
gl.uniformMatrix4fv(gl.getUniformLocation(this.program, "u_matrix"), false, matrix);
gl.drawArrays(gl.POINTS, 0, 1);
}
}
 
map.on('load', function() {
map.addLayer(new NullIslandLayer());
});

Instance Members

prewarm

Initializes resources like WebWorkers that can be shared across maps to lower load times in some situations. UnlSdk.workerUrl and UnlSdk.workerCount, if being used, must be set before prewarm() is called to have an effect.

By default, the lifecycle of these resources is managed automatically, and they are lazily initialized when a Map is first created. By invoking prewarm(), these resources will be created ahead of time, and will not be cleared when the last Map is removed from the page. This allows them to be re-used by new Map instances that are created later. They can be manually cleared by calling UnlSdk.clearPrewarmedResources(). This is only necessary if your web page remains active but stops using maps altogether.

This is primarily useful when using GL-JS maps in a single page app, wherein a user would navigate between various views that can cause Map instances to constantly be created and destroyed.

Example

UnlSdk.prewarm()

clearPrewarmedResources

Clears up resources that have previously been created by UnlSdk.prewarm(). Note that this is typically not necessary. You should only call this function if you expect the user of your app to not return to a Map view at any point in your application.

Example

UnlSdk.clearPrewarmedResources()