Namespace: Geomap

Geomap

A map: the Earth on a sheet, with a projection that can be exchanged while it is running. Created with `board.create('geomap', [corner, size], attributes)`.
Source:

Members

addGeoLayer

Public layer factory. The source is a function so a moving marker only has to invalidate its cached clip, not rebuild the map.
Source:

Methods

addFeatureLayer(layer, styleopt, optsopt) → {Object}

Draw a feature layer, culled to the viewport. The layer is re-read on every refresh, so changing the viewport changes what is drawn — which is the point: at country scale nothing outside the view is clipped, projected or drawn. `minRank` leaves out what the scale does not justify.
Parameters:
Name Type Attributes Description
layer Object A feature layer, as `G.asLayer` returns.
style Object <optional>
 Curve attributes.
opts Object <optional>
 `kind` "rings" or "lines"; `minRank` leaves out what the scale does not justify; `cull: false` draws every feature whatever the viewport says.
Source:
Returns:
The layer, with `features` reporting what survived the culling and `at(lon, lat)` naming what lies at a position.
Type
Object

centre() → {Array.<number>}

The map centre.
Source:
Returns:
A copy, as [lon, lat] in degrees.
Type
Array.<number>

clearSelection() → {Object}

Empty the selection. Announces once, and only if it was not empty.
Source:
Returns:
The map, for chaining.
Type
Object

clipState() → (nullable) {Object}

The shared clip state this map is using. Two maps with the same centre share one, and with it the work of clipping. Of interest mainly to a test that wants to check they do.
Source:
Returns:
The state, or null after `destroy`.
Type
Object

deselect(id) → {Object}

Take a country out of the selection. Deselecting what is not selected changes nothing and announces nothing.
Parameters:
Name Type Description
id string A country id.
Source:
Returns:
The map, for chaining.
Type
Object

extent() → (nullable) {Array.<Array.<number>>}

The viewport in force, or null when the whole sheet is shown.
Source:
Returns:
[[lonW, latS], [lonE, latN]] in degrees.
Type
Array.<Array.<number>>

fromGeo(lon, lat) → (nullable) {Object}

Where a position lands on the board.
Parameters:
Name Type Description
lon number Longitude in degrees.
lat number Latitude in degrees.
Source:
Returns:
Board coordinates, or null once the map has been destroyed and given its clip state back.
Type
Object

pixelRadius() → {number}

Half the width the projection occupies, in device pixels. What the sampling functions need: how large the thing is actually drawn, at the resolution the screen has rather than in CSS pixels. The globe answers the same question the same way, so both hosts sample by size on screen.
Source:
Returns:
Device pixels.
Type
number

projection() → {Object}

The projection in force.
Source:
Returns:
The projection object, not its name.
Type
Object

select(id) → {Object}

Add a country to the selection. A click goes through this same method, so both routes agree about what `selectMode` means: 'single' replaces, 'multiple' accumulates. An id nothing answers to is refused rather than carried along unseen, and selecting what is already selected changes nothing and announces nothing.
Parameters:
Name Type Description
id string A country id from the dataset.
Source:
Returns:
The map, for chaining.
Type
Object

selectMode() → {string}

The selection mode in force.
Source:
Returns:
'none', 'single' or 'multiple'.
Type
string

selected() → {Array.<string>}

The current selection.
Source:
Returns:
Country ids, in the order they were added.
Type
Array.<string>

setCenter(lon, latopt) → {Object}

Move the map centre. A viewport is given in geographic coordinates and rotated with everything else, so moving the centre moves where it lands; the fit is taken again when one is set.
Parameters:
Name Type Attributes Description
lon number New centre longitude in degrees.
lat number <optional>
 New centre latitude; unchanged when omitted.
Source:
Returns:
The map, for chaining.
Type
Object

setClickTolerance(px) → {Object}

How far the pointer may travel between press and release and still count as a click rather than a drag.
Parameters:
Name Type Description
px number Distance in pixels.
Source:
Returns:
The map, for chaining.
Type
Object

setExtent(boxnullable) → {Object}

Show only this box, given in longitude and latitude, or the whole sheet again with null. The clipping does not change — a viewport is a matter of what is fitted into the rectangle, not of what is computed.
Parameters:
Name Type Attributes Description
box Array.<Array.<number>> <nullable>
 [[lonW, latS], [lonE, latN]] in degrees, or null for the whole sheet.
Source:
Returns:
The map, for chaining.
Type
Object

setHoverCountries(on) → {Object}

Whether moving the pointer sends countryover and countryout. Switching it off says goodbye to the country under the pointer first, so a listener is not left believing the pointer never moved away.
Parameters:
Name Type Description
on boolean Whether to report hovering.
Source:
Returns:
The map, for chaining.
Type
Object

setLayer(name, on) → {Object}

Switching a layer off empties its arrays and redraws it once, so no stale geometry can survive in the renderer: a curve that keeps its old points would still be drawn even though the layer reports none.
Parameters:
Name Type Description
name string A layer name: ocean, land, coast, countries, capitals, graticule, or one returned by addGeoLayer.
on boolean Whether to draw it.
Source:
Returns:
The map, for chaining.
Type
Object

setOblique(on) → {Object}

Tilt the axis, or put it back on the equator. Only an oblique-capable projection can take a tilted axis; asking any other for one warns and leaves the map upright.
Parameters:
Name Type Description
on boolean Whether the centre's latitude tilts the axis.
Source:
Returns:
The map, for chaining.
Type
Object

setPicking(on) → {Object}

Whether a click looks up which country was hit at all. With it off the map still reports geoclick, but neither countryclick nor the selection.
Parameters:
Name Type Description
on boolean Whether to identify countries.
Source:
Returns:
The map, for chaining.
Type
Object

setProjection(name, animateopt) → {Object}

Change the projection, optionally morphing into it. The morph interpolates point for point, so the two coordinate sets have to match. Anything that changes the clipping changes the point counts — the kind of cut, and its radius — and those switches are made outright. A morph already running is cancelled first, or the frame that arrives afterwards undoes the switch.
Parameters:
Name Type Attributes Description
name string | Object A registered projection, or its name.
animate boolean <optional>
 Morph into it, if `morph.enabled` allows.
Source:
Returns:
The map, for chaining.
Type
Object

setSelectMode(mode) → {Object}

How a click builds a selection: 'none', 'single' or 'multiple'.
Parameters:
Name Type Description
mode string One of the three; anything else warns and is ignored.
Source:
Returns:
The map, for chaining.
Type
Object

setSelection(ids) → {Object}

Replace the whole selection in one step, then announce it once.
Parameters:
Name Type Description
ids Array.<string> Country ids. Unknown ones are refused, and under `selectMode: single` the last one named wins.
Source:
Returns:
The map, for chaining.
Type
Object

setSmallCountries(on) → {Object}

Show or hide the stand-in circles for countries with no outline. They are symbols at the wrong size and shape, so a map meant to be measured from should not carry them.
Parameters:
Name Type Description
on boolean Whether to draw them.
Source:
Returns:
The map, for chaining.
Type
Object

showDistortion(mode) → {Object}

Show what the projection does to shape and size. 'tissot' draws circles of equal angular radius on a lattice: whatever the projection does to them, it does to everything there. 'none' clears.
Parameters:
Name Type Description
mode string 'tissot' or 'none'.
Source:
Returns:
The map, for chaining.
Type
Object

showFeatures(list) → {Object}

Draw a set of named features: equator, tropics, polar circles, the prime meridian, the date line, the nominal time zones, the terminator. They replace whatever was shown before, so an empty list clears them.
Parameters:
Name Type Description
list Array.<string> Keys of `G.features`.
Source:
Returns:
The map, for chaining.
Type
Object

tapState() → {Object}

What the tap detector has seen: counts of down, move and up, whether it is reading pointer events or board events, and how far the last gesture travelled. For diagnosis. A tap that does not register is nearly impossible to investigate from the outside, and on touch devices the board's own 'up' carries no coordinates at all.
Source:
Returns:
A live view of the counters.
Type
Object

toGeo(x, y) → (nullable) {Array.<number>}

What lies at a board position — the inverse of `fromGeo`. A pointer may sit a few pixels outside the sheet and still count as on the map; `hitTolerance` says how many, and it is converted through the current scale so it means the same on a phone and on a large screen.
Parameters:
Name Type Description
x number Board x.
y number Board y.
Source:
Returns:
[lon, lat] in degrees, or null when the point is off the sheet or the map has been destroyed.
Type
Array.<number>

zoomTo(rings, marginopt) → {Object}

Fit the view to a group of rings, with a margin in degrees.
Parameters:
Name Type Attributes Default Description
rings Array.<Array.<Array.<number>>> Rings of [lon, lat].
margin number <optional>
 2 Room around them, in degrees.
Source:
Returns:
The map, for chaining.
Type
Object