GeoCanvas.png

What it is.
GeoCanvas is the map itself. Put it on a container and that container becomes a piece of the world: it fetches map tiles from the Viz Maps backend, assembles them into the basemap you see, and — crucially — establishes the geographic frame that everything else hangs off. Child containers positioned by latitude and longitude, GeoJSON shapes, GeoText labels and the GeoCamera all resolve against the GeoCanvas above them. Without one, there is no map and nothing geographic to anchor to.

See chapter Working with Maps for detailed information

Most scenes need to set exactly one thing: the style. Everything else is tuning for on-air reliability.

Parameters

Parameter

What it is for

Style

The map's appearance — the whole cartographic design: which layers are drawn, in what colours, with what labels. Takes a style reference from the Maps backend (vizmaps://api/v1/styles/<id>). This is the one parameter almost every scene sets, and switching it is how you go from a satellite look to a clean political map.

Style ▸ Reload

Re-fetches the current style from the backend without touching anything else. Use it when a designer has published a change to a style you are already pointing at, instead of reassigning the style.

Style ▸ Use reference labels

Draws the style's reference labels — place names and similar text baked into the style. Turn it off when you are supplying your own labelling (GeoText, or a graphic layer) and don't want the style's text competing with it.

Source mask

Selects which of the style's data sources are actually drawn, as a bitmask. Lets one style serve several looks — mask off a source to drop, say, roads or boundaries for a particular scene without authoring a second style.

Mask ▸ Bit

Sets a single bit of that mask on or off by index, rather than writing the whole mask value. The convenient form when you are toggling one source.

Tile prefetch ▸ Rings

How many rings of tiles to load around the visible area. Higher values mean a pan has tiles already in hand instead of loading them mid-move. Costs memory and bandwidth.

Tile prefetch ▸ Child levels

How many zoom levels below the current one to fetch ahead. This is what makes zooming in stay sharp instead of showing a blurred parent tile while it catches up.

Tile prefetch ▸ Parent levels

How many zoom levels above the current one to fetch ahead — the same idea for zooming out.

Tile prefetch ▸ World cover

Fetches enough low-zoom tiles to cover the whole globe, so a fully zoomed-out view is never empty. Worth turning on for a scene that starts wide or cuts to a world shot.

Tile ready timeout

How long to wait for tiles before the canvas reports itself ready anyway. 0 means wait indefinitely. This is the on-air safety valve: it decides whether a slow backend delays your take or lets it go with an incomplete map.

Ready

Read-only. 1 once the tiles for the current view have arrived. This is what you poll before taking the scene to air or grabbing a snapshot — reading it is the difference between capturing a finished map and a half-loaded one.

Active

Whether the canvas draws at all. Switches the basemap off while leaving the geographic frame — and everything anchored to it — in place.