MapOptions
Contents
MapOptions:
object
The Map options object.
Type declaration
antialias?
optional
antialias:boolean
If true
, the gl context will be created with MSAA antialiasing, which can be useful for antialiasing custom layers.
Disabled by default as a performance optimization.
attributionControl?
optional
attributionControl:false
|AttributionControlOptions
If set, an AttributionControl will be added to the map with the provided options.
To disable the attribution control, pass false
.
Note: showing the logo of TrimbleMaps is not required for using TrimbleMaps.
Default Value
compact: true, customAttribution: "TrimbleMaps ...".
bearing?
optional
bearing:number
The initial bearing (rotation) of the map, measured in degrees counter-clockwise from north. If bearing
is not specified in the constructor options, TrimbleMaps JS will look for it in the map’s style object. If it is not specified in the style, either, it will default to 0
.
Default Value
0
bearingSnap?
optional
bearingSnap:number
The threshold, measured in degrees, that determines when the map’s
bearing will snap to north. For example, with a bearingSnap
of 7, if the user rotates
the map within 7 degrees of north, the map will automatically snap to exact north.
Default Value
7
bounds?
optional
bounds:LngLatBoundsLike
The initial bounds of the map. If bounds
is specified, it overrides center
and zoom
constructor options.
boxZoom?
optional
boxZoom:boolean
If true
, the “box zoom” interaction is enabled (see BoxZoomHandler).
Default Value
true
cancelPendingTileRequestsWhileZooming?
optional
cancelPendingTileRequestsWhileZooming:boolean
Determines whether to cancel, or retain, tiles from the current viewport which are still loading but which belong to a farther (smaller) zoom level than the current one.
- If
true
, when zooming in, tiles which didn’t manage to load for previous zoom levels will become canceled. This might save some computing resources for slower devices, but the map details might appear more abruptly at the end of the zoom. - If
false
, when zooming in, the previous zoom level(s) tiles will progressively appear, giving a smoother map details experience. However, more tiles will be rendered in a short period of time.
Default Value
true
center?
optional
center:LngLatLike
The initial geographical centerpoint of the map. If center
is not specified in the constructor options, TrimbleMaps JS will look for it in the map’s style object. If it is not specified in the style, either, it will default to [0, 0]
Note: TrimbleMaps JS uses longitude, latitude coordinate order (as opposed to latitude, longitude) to match GeoJSON.
Default Value
[0, 0]
clickTolerance?
optional
clickTolerance:number
The max number of pixels a user can shift the mouse pointer during a click for it to be considered a valid click (as opposed to a mouse drag).
Default Value
3
collectResourceTiming?
optional
collectResourceTiming:boolean
If true
, Resource Timing API information will be collected for requests made by GeoJSON and Vector Tile web workers (this information is normally inaccessible from the main Javascript thread). Information will be returned in a resourceTiming
property of relevant data
events.
Default Value
false
container
container:
HTMLElement
|string
The HTML element in which TrimbleMaps JS will render the map, or the element’s string id
. The specified element must have no children.
cooperativeGestures?
optional
cooperativeGestures:GestureOptions
If true
or set to an options object, the map is only accessible on desktop while holding Command/Ctrl and only accessible on mobile with two fingers. Interacting with the map using normal gestures will trigger an informational screen. With this option enabled, “drag to pitch” requires a three-finger gesture. Cooperative gestures are disabled when a map enters fullscreen using FullscreenControl.
Default Value
false
crossSourceCollisions?
optional
crossSourceCollisions:boolean
If true
, symbols from multiple sources can collide with each other during collision detection. If false
, collision detection is run separately for the symbols in each source.
Default Value
true
doubleClickZoom?
optional
doubleClickZoom:boolean
If true
, the “double click to zoom” interaction is enabled (see DoubleClickZoomHandler).
Default Value
true
dragPan?
optional
dragPan:boolean
|DragPanOptions
If true
, the “drag to pan” interaction is enabled. An Object
value is passed as options to DragPanHandler#enable.
Default Value
true
dragRotate?
optional
dragRotate:boolean
If true
, the “drag to rotate” interaction is enabled (see DragRotateHandler).
Default Value
true
fadeDuration?
optional
fadeDuration:number
Controls the duration of the fade-in/fade-out animation for label collisions after initial map load, in milliseconds. This setting affects all symbol layers. This setting does not affect the duration of runtime styling transitions or raster tile cross-fading.
Default Value
300
failIfMajorPerformanceCaveat?
optional
failIfMajorPerformanceCaveat:boolean
If true
, map creation will fail if the performance of TrimbleMaps JS would be dramatically worse than expected
(i.e. a software renderer would be used).
Default Value
false
fitBoundsOptions?
optional
fitBoundsOptions:FitBoundsOptions
A FitBoundsOptions options object to use only when fitting the initial bounds
provided above.
hash?
optional
hash:boolean
|string
If true
, the map’s position (zoom, center latitude, center longitude, bearing, and pitch) will be synced with the hash fragment of the page’s URL.
For example, http://path/to/my/page.html#2.59/39.26/53.07/-24.1/60
.
An additional string may optionally be provided to indicate a parameter-styled hash,
e.g. http://path/to/my/page.html#map=2.59/39.26/53.07/-24.1/60&foo=bar, where foo
is a custom parameter and bar is an arbitrary hash distinct from the map hash.
Default Value
false
interactive?
optional
interactive:boolean
If false
, no mouse, touch, or keyboard listeners will be attached to the map, so it will not respond to interaction.
Default Value
true
keyboard?
optional
keyboard:boolean
If true
, keyboard shortcuts are enabled (see KeyboardHandler).
Default Value
true
language?
optional
language:LanguageEnum
map’s Language if not set default would EN
localIdeographFontFamily?
optional
localIdeographFontFamily:string
|false
Defines a CSS
font-family for locally overriding generation of glyphs in the ‘CJK Unified Ideographs’, ‘Hiragana’, ‘Katakana’ and ‘Hangul Syllables’ ranges.
In these ranges, font settings from the map’s style will be ignored, except for font-weight keywords (light/regular/medium/bold).
Set to false
, to enable font settings from the map’s style for these glyph ranges.
The purpose of this option is to avoid bandwidth-intensive glyph server requests. (See Use locally generated ideographs.)
Default Value
'sans-serif'
locale?
optional
locale:any
A patch to apply to the default localization table for UI strings, e.g. control tooltips. The locale
object maps namespaced UI string IDs to translated strings in the target language; see src/ui/default_locale.js
for an example with all supported string IDs. The object may specify all UI strings (thereby adding support for a new translation) or only a subset of strings (thereby patching the default translation table).
Default Value
null
logoPosition?
optional
logoPosition:ControlPosition
A string representing the position of the TrimbleMaps wordmark on the map. Valid options are top-left
,top-right
, bottom-left
, or bottom-right
.
Default Value
'bottom-left'
maplibreLogo?
optional
maplibreLogo:boolean
If true
, the TrimbleMaps logo will be shown.
maxBounds?
optional
maxBounds:LngLatBoundsLike
If set, the map will be constrained to the given bounds.
maxCanvasSize?
optional
maxCanvasSize: [number
,number
]
The canvas’ width
and height
max size. The values are passed as an array where the first element is max width and the second element is max height.
You shouldn’t set this above WebGl MAX_TEXTURE_SIZE
.
Default Value
[4096, 4096].
maxPitch?
optional
maxPitch:number
|null
The maximum pitch of the map (0-85). Values greater than 60 degrees are experimental and may result in rendering issues. If you encounter any, please raise an issue with details in the TrimbleMaps project.
Default Value
60
maxTileCacheSize?
optional
maxTileCacheSize:number
|null
The maximum number of tiles stored in the tile cache for a given source. If omitted, the cache will be dynamically sized based on the current viewport which can be set using maxTileCacheZoomLevels
constructor options.
Default Value
null
maxTileCacheZoomLevels?
optional
maxTileCacheZoomLevels:number
The maximum number of zoom levels for which to store tiles for a given source. Tile cache dynamic size is calculated by multiplying maxTileCacheZoomLevels
with the approximate number of tiles in the viewport for a given source.
Default Value
5
maxZoom?
optional
maxZoom:number
|null
The maximum zoom level of the map (0-24).
Default Value
22
minPitch?
optional
minPitch:number
|null
The minimum pitch of the map (0-85). Values greater than 60 degrees are experimental and may result in rendering issues. If you encounter any, please raise an issue with details in the TrimbleMaps project.
Default Value
0
minZoom?
optional
minZoom:number
|null
The minimum zoom level of the map (0-24).
Default Value
0
pitch?
optional
pitch:number
The initial pitch (tilt) of the map, measured in degrees away from the plane of the screen (0-85). If pitch
is not specified in the constructor options, TrimbleMaps JS will look for it in the map’s style object. If it is not specified in the style, either, it will default to 0
. Values greater than 60 degrees are experimental and may result in rendering issues. If you encounter any, please raise an issue with details in the TrimbleMaps project.
Default Value
0
pitchWithRotate?
optional
pitchWithRotate:boolean
If false
, the map’s pitch (tilt) control with “drag to rotate” interaction will be disabled.
Default Value
true
pixelRatio?
optional
pixelRatio:number
The pixel ratio.
The canvas’ width
attribute will be container.clientWidth * pixelRatio
and its height
attribute will be container.clientHeight * pixelRatio
. Defaults to devicePixelRatio
if not specified.
preserveDrawingBuffer?
optional
preserveDrawingBuffer:boolean
If true
, the map’s canvas can be exported to a PNG using map.getCanvas().toDataURL()
. This is false
by default as a performance optimization.
Default Value
false
refreshExpiredTiles?
optional
refreshExpiredTiles:boolean
If false
, the map won’t attempt to re-request tiles once they expire per their HTTP cacheControl
/expires
headers.
Default Value
true
region?
optional
region:RegionEnum
map’s region if not set default would be NA
renderWorldCopies?
optional
renderWorldCopies:boolean
If true
, multiple copies of the world will be rendered side by side beyond -180 and 180 degrees longitude. If set to false
:
- When the map is zoomed out far enough that a single representation of the world does not fill the map’s entire container, there will be blank space beyond 180 and -180 degrees longitude.
- Features that cross 180 and -180 degrees longitude will be cut in two (with one portion on the right edge of the map and the other on the left edge of the map) at every zoom level.
Default Value
true
satelliteProvider?
optional
satelliteProvider:SatelliteProviderEnum
This option is used for Satellite styles to decide the source provider for satellite styles.
scrollZoom?
optional
scrollZoom:boolean
|AroundCenterOptions
If true
, the “scroll to zoom” interaction is enabled. AroundCenterOptions are passed as options to ScrollZoomHandler#enable.
Default Value
true
style?
optional
style:StyleSpecification
|string
The map’s TrimbleMaps style. This must be a JSON object conforming to the schema described in the TrimbleMaps Style Specification, or a URL to such JSON. When the style is not specified, calling Map#setStyle is required to render the map.
touchPitch?
optional
touchPitch:boolean
|AroundCenterOptions
If true
, the “drag to pitch” interaction is enabled. An Object
value is passed as options to TwoFingersTouchPitchHandler#enable.
Default Value
true
touchZoomRotate?
optional
touchZoomRotate:boolean
|AroundCenterOptions
If true
, the “pinch to rotate and zoom” interaction is enabled. An Object
value is passed as options to TwoFingersTouchZoomRotateHandler#enable.
Default Value
true
trackResize?
optional
trackResize:boolean
If true
, the map will automatically resize when the browser window resizes.
Default Value
true
transformCameraUpdate?
optional
transformCameraUpdate:CameraUpdateTransformFunction
|null
A callback run before the map’s camera is moved due to user input or animation. The callback can be used to modify the new center, zoom, pitch and bearing. Expected to return an object containing center, zoom, pitch or bearing values to overwrite.
Default Value
null
transformRequest?
optional
transformRequest:RequestTransformFunction
|null
A callback run before the Map makes a request for an external URL. The callback can be used to modify the url, set headers, or set the credentials property for cross-origin requests.
Expected to return an object with a url
property and optionally headers
and credentials
properties.
Default Value
null
validateStyle?
optional
validateStyle:boolean
If false, style validation will be skipped. Useful in production environment.
Default Value
true
zoom?
optional
zoom:number
The initial zoom level of the map. If zoom
is not specified in the constructor options, TrimbleMaps JS will look for it in the map’s style object. If it is not specified in the style, either, it will default to 0
.
Default Value
0