Name

HTML::OSM - Generate an interactive OpenStreetMap with Leaflet.js

Version

Version 0.19

Synopsis

use HTML::OSM;

my $map = HTML::OSM->new(
    coordinates => [
        [37.7749, -122.4194, 'San Francisco'],
        [undef,   undef,     'Paris'],
    ],
    zoom => 10,
);
my ($head, $body) = $map->onload_render();

Description

HTML::OSM builds an interactive map from OpenStreetMap tiles and the Leaflet.js library. Give it points as latitude and longitude, as place names, or as geocoder result objects. It can also draw GeoJSON shapes, heatmaps, GPX tracks and choropleth (colour-filled region) layers, and can group nearby markers into clusters. A named GeoJSON layer gets a checkbox on the map, so the reader can turn it on and off.

Place names are turned into coordinates by an injected geocoder or, without one, by the Nominatim service. The answers are cached, and requests can be spaced out with min_interval.

onload_render() returns two HTML fragments: one for the page's <head> and one for its <body>. The interface follows HTML::GoogleMaps::V3, so code written for that module needs few changes.

Scale and Key

my $map = HTML::OSM->new(
    scale        => 1,
    legend_title => 'Country',
    legend       => [
        { label => 'England', colour => '#e41a1c', group => 'en' },
        { label => 'France',  colour => '#377eb8', group => 'fr' },
        { label => '100 people', colour => '#888888', radius => 14 },
    ],
);
$map->add_marker([51.5074, -0.1278], html => 'London', group => 'en');
$map->add_circle_marker([48.8566, 2.3522], html => 'Paris', group => 'fr',
    colour => '#377eb8');

scale => 1 adds Leaflet's scale bar, in kilometres and miles, to the bottom left corner. It is redrawn whenever the map moves or zooms. The default is no scale bar.

legend draws a key in a corner of the map: legend_position is topright (the default), topleft, bottomright or bottomleft. legend_title is printed above the entries. Each entry is a hashref:

When no entry is listed, the key says legend_empty, by default "Nothing in this view". When every entry is left out for a layer that is shown (unless_layer), the key is not drawn at all.

new() croaks on an entry it cannot use, and on an unknown position. Values from a config file or a clone skip that check, so onload_render() checks them again. It leaves out a bad entry and uses topright for a bad position, with a warning.

Subroutines/Methods

New

Construct a new HTML::OSM object.

my $map = HTML::OSM->new(%params);
my $map = HTML::OSM->new(\%params);

Both method-style (HTML::OSM->new(...)) and function-style (HTML::OSM::new(...)) calls are supported. Calling $existing_obj->new(%overrides) performs a shallow clone, merging %overrides onto the existing object's state without re-validating.

Api Specification

Input
{
  cache                   => { type => object, can => [get, set], optional },
  cluster                 => { type => boolean,                   optional },
  cluster_css_url         => { type => string,                    optional },
  cluster_default_css_url => { type => string,                    optional },
  cluster_js_url          => { type => string,                    optional },
  config_file             => { type => string,                    optional },
  coordinates             => { type => arrayref,                  optional },
  css_url                 => { type => string,                    optional },
  email                   => { type => string,                    optional },
  fit                     => { type => boolean,                   optional },
  geocoder                => { type => object, can => geocode,    optional },
  gpx_js_url              => { type => string,                    optional },
  heatmap_js_url          => { type => string,                    optional },
  height                  => { type => string,                    optional },
  host                    => { type => string,                    optional },
  js_url                  => { type => string,                    optional },
  legend                  => { type => arrayref,                  optional },
  legend_empty            => { type => string,                    optional },
  legend_position         => { type => string, enum => [topright, topleft, bottomright, bottomleft], optional },
  legend_title            => { type => string,                    optional },
  logger                  => { type => object,                    optional },
  max_zoom                => { type => integer, min => 0, max => 28, optional },
  min_interval            => { type => number,  min => 0,         optional },
  nonce                   => { type => string, matches => qr/\A[A-Za-z0-9+\/_=-]+\z/, optional },
  scale                   => { type => boolean,                   optional },
  search                  => { type => boolean,                   optional },
  tile_attribution        => { type => string,                    optional },
  tile_url                => { type => string,                    optional },
  ua                      => { type => object,                    optional },
  width                   => { type => string,                    optional },
  zoom                    => { type => integer, min => 0, max => 19, optional },
}
Output
{ type => object, isa => 'HTML::OSM' }

Messages

| Message                                        | Meaning / Resolution                          |
|------------------------------------------------|-----------------------------------------------|
| (validation error from Params::Validate::Strict) | A param has the wrong type or is out of range |
| new(): invalid legend_position: VALUE          | Not one of topright, topleft, bottomright, bottomleft |
| new(): legend entry N: ...                     | An entry of legend is unusable; see L</Scale and key> |

Pseudocode

1. If $class is neither a package name nor a blessed ref, treat as
   function-style call: prepend $class back onto @_ and use __PACKAGE__.
2. If $class is a blessed ref (clone call): merge override params onto a
   shallow copy and return immediately, bypassing schema validation.
3. Validate all supplied args against the declared schema.
4. Merge config-file settings via Object::Configure.
5. Resolve the cache: caller-supplied object, or in-memory CHI instance.
6. Bless and return with Readonly CDN constants as defaults.

Add_Marker

Add a point marker to the map.

$map->add_marker([51.5074, -0.1278], html => 'London');
$map->add_marker('Paris, France',    html => 'Paris');
$map->add_marker($geo_coder_result);

Returns 1 on success, 0 if the point cannot be resolved or is out of range. An empty address, or an arrayref that does not hold exactly two elements, also returns 0.

Api Specification

Input
point : arrayref [lat, lon] | string address | object with latitude()/longitude()
html  : string   (optional popup label)
icon  : string   (optional icon URL)
group : string   (optional; the key entry this marker belongs to, see L</Scale and key>)
Output
{ type => integer, enum => [0, 1] }

Messages

| Message                                 | Meaning / Resolution                        |
|-----------------------------------------|---------------------------------------------|
| add_marker(): unknown point type: TYPE | Point is a ref type with no lat/lon methods |
| add_marker(): group must be a string    | group is a reference                        |
| Skipping invalid coordinate: (LAT, LON) | Warning: the point is not numeric or is out of range; 0 is returned |

Examples

# Coordinate array with a popup label
$map->add_marker([51.5074, -0.1278], html => 'London');

# String address geocoded via the injected geocoder or Nominatim
$map->add_marker('Paris, France', html => 'Paris');

# Custom icon URL with a popup
$map->add_marker(
    [40.7128, -74.0060],
    html => 'New York',
    icon => 'https://example.com/pin.png',
);

# Geo::Coder result object that implements latitude()/longitude()
my $result = $geocoder->geocode('Berlin, Germany');
$map->add_marker($result, html => 'Berlin');

# Accumulate several markers, warn on geocode failure
for my $city (@cities) {
    $map->add_marker($city->{coords}, html => $city->{name})
        or warn "Could not place $city->{name}";
}

Add_Circle_Marker

Add a filled circle whose size in pixels can show a quantity, such as the population of a town.

$map->add_circle_marker([51.5074, -0.1278],
    html   => 'London',
    radius => 12,
    colour => '#e45c3a',
);

The point may be anything add_marker() accepts. The radius is in screen pixels, so a circle stays the same size as the reader zooms in and out. With cluster => 1, circles join the same cluster group as the pin markers.

Returns 1 on success, 0 if the point cannot be resolved or is out of range.

Api Specification

Input
point  : arrayref [lat, lon] | string address | object with latitude()/longitude()
html   : string   (optional popup label)
radius : number > 0 and < 1e6   (optional, default 8)
colour : string   hex #rrggbb or #rgb, any case   (optional, default '#3388ff')
group  : string   (optional; the key entry this circle belongs to, see L</Scale and key>)
Output
{ type => integer, enum => [0, 1] }

Messages

| Message                                             | Meaning / Resolution                        |
|-----------------------------------------------------|---------------------------------------------|
| add_circle_marker(): radius must be a positive number | radius is 0, negative, 1e6 or more, or not a plain number |
| add_circle_marker(): invalid colour: VALUE          | colour is not a #rgb or #rrggbb hex string  |
| add_circle_marker(): unknown point type: TYPE       | Point is a ref type with no lat/lon methods |
| add_circle_marker(): group must be a string         | group is a reference                        |
| Skipping invalid coordinate: (LAT, LON)             | Warning: the point is not numeric or is out of range; 0 is returned |

Examples

# Bubble whose area shows the population
$map->add_circle_marker([$lat, $lon],
    html   => "$city ($pop)",
    radius => sqrt($pop / $max_pop) * 30,
    colour => '#e45c3a',
);

# Mixed map: pins for offices, circles for market size
$map->add_marker([$lat1, $lon1], html => 'HQ');
$map->add_circle_marker([$lat2, $lon2], html => 'Market A', radius => 20);

Add_Geojson

Add a GeoJSON layer to the map.

$map->add_geojson(\%data, style => { color => '#ff0000' }, popup => 'name');

The first argument may be a hashref/arrayref (GeoJSON structure) or a JSON string. Give it a name and the reader can hide and show it (see "LAYER CONTROL"). Returns 1 on success.

Api Specification

Input
data  : hashref | arrayref | string (JSON)
style : hashref   Leaflet path-style options (color, weight, fillColor, fillOpacity)
popup : string    Feature property name whose value becomes the popup text
name  : string    Label of the layer's checkbox in the map's layer control
show  : boolean   Whether a named layer is drawn when the map opens (default 1)
key   : hashref   A key to the layer's colours, shown while the layer is
                  (see L</LAYER KEY>):
                  { entries => [ { label, colour }, ... ], title?, position?,
                    shape? }
bands : string    Feature property holding a list of colours, each drawn
                  as a line of its own just inside the outline, side by side
                  (see L</BANDS>)
Output
{ type => integer, value => 1 }

Messages

| Message                                   | Meaning / Resolution            |
|-------------------------------------------|---------------------------------|
| (JSON parse error)                        | data string is not valid JSON   |
| add_geojson: name must be a string        | name is a reference or empty    |
| add_geojson: show must not be a reference | show is a reference             |
| add_geojson: key ...                      | key is unusable; the message    |
|                                           | says which part                 |
| add_geojson: bands must be a string       | bands is a reference or empty   |

Layer Control

Give a layer a name and the map gains Leaflet's layer control, a box of checkboxes in its top right corner, one for each name, so the reader can hide and show that layer. show => 0 starts it hidden: the reader turns it on. As with search, the strings false, no and off are false.

Layers given the same name share one checkbox, which is ticked when any of them has show on. A layer with no name is always drawn, whatever show says, because nothing could turn it on. The control is written once, after the last GeoJSON layer, and is left open (not collapsed into an icon), so the reader can see what can be turned on.

The name is shown as text: Leaflet writes it into the page as HTML, so it is escaped first, and <b> is shown as written.

Layer Key

$map->add_geojson(\%busy,  style => { color => '#d73027' }, name => 'Counties',
    key => {
        title   => 'Population',
        entries => [
            { label => '100,000 or more', colour => '#d73027' },
            { label => 'under 100,000',   colour => '#1a9850' },
        ],
    });
$map->add_geojson(\%quiet, style => { color => '#1a9850' }, name => 'Counties');

key draws a key to a layer's colours in a corner of the map: a short line of each colour, as an outline is drawn, beside its label. It is shown while the layer is: unticking the layer's checkbox hides the key too, and ticking it shows it again. A layer with no name is always drawn, so its key always shows.

Layers that share a name share one key: the first key given for that name. Every text reaches the page as text, never as HTML.

Bands

# Kent's outline is red with blue inside it; Surrey's is all green
$kent->{properties}{colours}   = [ '#d73027', '#4575b4' ];
$surrey->{properties}{colours} = [ '#1a9850' ];
$map->add_geojson({ type => 'FeatureCollection', features => [ $kent, $surrey ] },
    style => { weight => 2, fill => 0 }, bands => 'colours');

bands names a feature property that holds a list of colours (#rrggbb). A polygon's outline is then drawn just inside its edge, not along the middle of it, in a line of the width style gives. So where two polygons share a border, each one's colour is on its own side: the border reads as a line twice as wide, a different colour either side, and neither hides the other.

A polygon with several colours, for an area that belongs to more than one group, gets a line of each, side by side: the first against the edge, each further one further inside. A feature without the property, or with no colour that can be used, is drawn as style says. Only polygons are banded; a line or point takes the first colour.

The lines are cut to the inside of the polygon, which needs Leaflet's default SVG drawing. A map drawn on a canvas shows them uncut, along the middle of the edge, the first colour on top. A popup opens from the outline as before. Neighbours' lines meet exactly only where their shared border is the same in both polygons; outlines simplified one at a time leave small gaps or overlaps.

Examples

# Pre-parsed GeoJSON structure with style and popup property
$map->add_geojson(
    { type => 'FeatureCollection', features => \@features },
    style => { color => '#ff0000', weight => 2, fillOpacity => 0.4 },
    popup => 'name',
);

# Raw JSON string - decoded automatically
$map->add_geojson('{"type":"FeatureCollection","features":[]}');

# Multiple GeoJSON layers with different styles on the same map
$map->add_geojson(\%country_borders, style => { color => '#333333', fillOpacity => 0 });
$map->add_geojson(\%river_data,      style => { color => '#0099ff', weight => 1    });

# County outlines the reader can turn on: hidden at first
$map->add_geojson(
    { type => 'FeatureCollection', features => \@counties },
    style => { color => '#555555', weight => 1, fill => 0 },
    popup => 'name',
    name  => 'County boundaries',
    show  => 0,
);

Add_Heatmap

Add a heatmap layer to the map.

$map->add_heatmap([[51.5, -0.1, 0.8], [51.6, -0.2, 0.5]], radius => 25);

Each point is [$lat, $lon] or [$lat, $lon, $intensity] (intensity: 0-1). Requires the Leaflet.heat plugin (heatmap_js_url). Returns 1 on success.

Api Specification

Input
points : arrayref of ([lat, lon] | [lat, lon, intensity])
radius : number  default 25 (a value that is not a positive number uses the default)
blur   : number  default 15 (a value that is not a positive number uses the default)
Output
{ type => integer, value => 1 }

Messages

| Message                                 | Meaning / Resolution              |
|-----------------------------------------|-----------------------------------|
| add_heatmap: points must be an arrayref | First argument is not an arrayref |

Examples

# Basic heatmap - [lat, lon] per point
$map->add_heatmap([
    [51.5074, -0.1278],
    [51.6000, -0.2000],
    [51.4000,  0.0000],
]);

# With intensity values (0..1) and custom radius/blur
$map->add_heatmap(
    [ [51.5, -0.1, 0.9], [51.6, -0.2, 0.5], [51.4, 0.0, 0.2] ],
    radius => 30,
    blur   => 20,
);

Add_Gpx

Add a GPX track to the map from a URL.

$map->add_gpx('https://example.com/track.gpx');

The map view is auto-fitted to the track bounds after loading. Requires the leaflet-gpx plugin (gpx_js_url). Returns 1 on success.

Api Specification

Input
url : string  URL of the GPX file (required)
Output
{ type => integer, value => 1 }

Messages

| Message                  | Meaning / Resolution     |
|--------------------------|--------------------------|
| add_gpx: url is required | No URL argument supplied |

Examples

# Add a GPX track from a public URL; the map auto-fits to its bounds
$map->add_gpx('https://example.com/route.gpx');

# Multiple tracks on the same map
$map->add_gpx('https://example.com/morning-run.gpx');
$map->add_gpx('https://example.com/evening-walk.gpx');

Add_Choropleth

Add a choropleth (data-driven colour fill) layer to the map.

$map->add_choropleth(
    \@geojson_features,
    { England => 100, Scotland => 80, Wales => 60 },
    key   => 'name',
    scale => ['#ffffcc', '#a1dab4', '#41b6c4', '#2c7fb8', '#253494'],
);

Colours are pre-computed in Perl and baked into the emitted JavaScript. No extra browser plugin is required. Returns 1 on success.

Api Specification

Input
features : arrayref of GeoJSON Feature hashrefs  (required)
values   : hashref  { feature_property_value => numeric_value }  (required)
key      : string   feature property to match against values  (default: 'name')
scale    : arrayref hex-colour strings low-to-high  (default: 5-step YlGnBu)
Output
{ type => integer, value => 1 }

Messages

| Message                                     | Meaning / Resolution              |
|---------------------------------------------|-----------------------------------|
| add_choropleth: features must be an arrayref | First argument is not an arrayref |
| add_choropleth: values must be a hashref     | Second argument is not a hashref  |

Examples

# Default 5-step YlGnBu scale, key property "name"
$map->add_choropleth(
    \@geojson_features,
    { England => 100, Scotland => 80, Wales => 60 },
);

# Custom 3-step scale and a different GeoJSON property as the key
$map->add_choropleth(
    \@geojson_features,
    { England => 100, Scotland => 80, Wales => 60 },
    key   => 'country',
    scale => ['#f7fbff', '#6baed6', '#08519c'],
);

# choropleth-only map - center() must be called explicitly
$map->center([54.0, -2.0]);
$map->add_choropleth(\@uk_features, \%population_by_region);
my ($head, $body) = $map->onload_render();

Center

Set the map centre to a given point.

$map->center([40.7128, -74.0060]);
$map->center($geo_object);
$map->center('Berlin, Germany');

Returns 1 on success, 0 if the point cannot be resolved or is out of range. An empty address also returns 0.

Api Specification

Input
point : arrayref [lat, lon] | object with latitude()/longitude() | string address
Output
{ type => integer, enum => [0, 1] }

Messages

| Message                                            | Meaning / Resolution            |
|----------------------------------------------------|---------------------------------|
| center(): usage: point => [ latitude, longitude ]  | No point argument supplied      |
| center(): point must have latitude and longitude   | Arrayref has != 2 elements      |
| center(): unknown point type: TYPE                 | Ref type has no lat/lon methods |
| Skipping invalid coordinate: (LAT, LON)            | Warning: point is not numeric or is out of range; 0 is returned |

Examples

# Coordinate array
$map->center([40.7128, -74.0060]);

# Object that implements latitude()/longitude() (e.g. a Geo::Coder result)
$map->center($geocoder->geocode('Berlin, Germany'));

# String address resolved via the injected geocoder or Nominatim
$map->center('Eiffel Tower, Paris, France');

# Required when rendering without point markers (GeoJSON-only, choropleth, etc.)
$map->center([54.0, -2.0]);
$map->add_geojson(\%uk_regions, popup => 'name');
my ($head, $body) = $map->onload_render();

Zoom

Get or set the zoom level (0 = world, 19 = building).

$map->zoom(10);
my $z = $map->zoom();

Api Specification

Input
{ zoom => { type => integer, min => 0, max => 19, optional => 1 } }
Output
{ type => integer, min => 0, max => 19 }

Messages

| Message                      | Meaning / Resolution                      |
|------------------------------|-------------------------------------------|
| (Params::Validate::Strict)   | zoom is not an integer or is out of range |

Examples

# Setter: store the zoom level
$map->zoom(14);

# Getter: retrieve the current level
my $level = $map->zoom();
print "Current zoom: $level\n";    # 14

# Setter return value equals the new level
my $confirmed = $map->zoom(10);
die 'unexpected' unless $confirmed == 10;

# Chain: set via new(), read back via zoom()
my $m = HTML::OSM->new(zoom => 6);
$m->zoom($m->zoom() + 2);   # nudge up by 2

Onload_Render

Render the map and return a two-element list suitable for embedding in HTML.

my ($head_html, $body_html) = $map->onload_render();

$head_html contains the Leaflet CSS, JavaScript, and plugin assets. Place it inside <head>...</head>.

$body_html contains the search box (unless search => 0), control buttons, map <div>, and the initialisation <script>. Place it inside <body>...</body> where the map should appear.

The rendered page provides:

Values that reach the object without going through new()'s checks (from a config file or a clone) are checked again here. A zoom that is not an integer from 0 to 19 is replaced by 12, and a width or height that is not a CSS length (such as 600px, 100% or auto) is replaced by the default. A max_zoom that is not an integer from 0 to 28 is ignored. Each replacement gives a warning.

Api Specification

Input
(none - uses object state)
Output
{ type => list, elements => [string, string] }

Messages

| Message                                          | Meaning / Resolution                        |
|--------------------------------------------------|---------------------------------------------|
| No map data provided                             | No markers, circle markers, GeoJSON, heatmap, GPX, or choropleth added yet |
| center() must be called when no point markers are provided | Non-marker-only render needs explicit centre |
| Skipping invalid coordinate: (LAT, LON)          | Warning: a marker is not numeric or out of range; it is left off the map |
| onload_render: invalid nonce                     | nonce from a config file or clone is not base64 or base64url |
| onload_render: invalid zoom 'Z', using 12        | Warning: zoom from a config file or clone is out of range |
| onload_render: invalid max_zoom 'Z', ignoring it | Warning: max_zoom from a config file or clone is not an integer from 0 to 28 |
| onload_render: invalid width 'W', using 600px    | Warning: width is not a CSS length |
| onload_render: invalid height 'H', using 400px   | Warning: height is not a CSS length |
| onload_render: invalid legend_position 'P', using topright | Warning: legend_position from a config file or clone is not a corner |
| onload_render: legend entry N: ...; leaving it out of the key | Warning: a legend entry from a config file or clone is unusable |
| onload_render: legend must be an arrayref; leaving it out of the key | Warning: legend from a config file or clone is not an arrayref; no key is drawn |
| _fetch_coordinates: failed to decode Nominatim response: ERROR | Warning: Nominatim returned something that is not JSON; the marker is skipped |
| _fetch_coordinates: unrecognised geocoder result type: TYPE | Warning: the injected geocoder returned an unknown type; the marker is skipped |

Examples

# Minimal: one marker, embed in a CGI response
use HTML::OSM;
my $map = HTML::OSM->new(zoom => 12);
$map->add_marker([51.5074, -0.1278], html => 'London');
my ($head, $body) = $map->onload_render();
print "Content-Type: text/html\n\n";
print "<html><head>$head</head><body>$body</body></html>\n";

# Mixed layers: markers + GeoJSON, explicit center
$map->center([51.5, -0.1]);
$map->add_geojson(\%borough_data, popup => 'name', style => { color => '#333' });
$map->add_marker([51.5074, -0.1278], html => 'City of London');
my ($head_html, $body_html) = $map->onload_render();

# Template Toolkit integration
$tt->process('map.tt', {
    map_head => scalar(($map->onload_render())[0]),
    map_body => scalar(($map->onload_render())[1]),
});

Pseudocode

1. Gather all data layers; croak if none populated.
2. Geocode/validate each coordinate tuple; discard invalids with a warning.
   A tuple with no coordinates and no address is discarded.
   Check circle markers the same way.
   Re-check zoom, max_zoom, width and height; fall back with a warning.
3. Determine map centre: caller-supplied > computed midpoint of the bounds
   of the pin and circle markers.  With fit and no caller centre, also
   fit the view to those bounds, at most at zoom, on load and on reset.
   Croak if neither is available.
4. Build <head>: Leaflet CSS + JS; inject cluster/heatmap/GPX plugin assets
   only when the corresponding layer type is present.
5. Build <body>: search box and clear-search button (when search is on),
   reset button, map <div>.
6. Initialise Leaflet map, tile layer (with maxZoom when max_zoom is set),
   and the searchMarkers array when search is on.
7. Emit JS for each pin and circle marker (via one clusterGroup when
   cluster is set), then the scale bar when scale is set, then the key
   when legend has entries: its entries, the groups and where each
   grouped marker is, redrawn on every moveend.
8. Emit JS for each GeoJSON, heatmap, GPX, and choropleth layer.
9. Attach event listeners: reset-view, and when search is on,
   clear-search-markers and search-on-Enter.
10. Return ($head, $body).

Limitations

Author

Nigel Horne, <njh at nigelhorne.com>

Bugs

Please report bugs at https://github.com/nigelhorne/HTML-OSM/issues.

See Also

Support

This module is provided as-is without any warranty.

Please report problems and ask questions at https://github.com/nigelhorne/HTML-OSM/issues.

You can find documentation for this module with the perldoc command.

perldoc HTML::OSM

You can also look for information at MetaCPAN: https://metacpan.org/dist/HTML-OSM.

Todo

Allow per-marker removal via clicking on a marker.

Formal Specification

New

HTML_OSM
  coordinates     : iseq (ℝ x ℝ x S x S x (S ∪ {∅}))
  zoom            : Z
  cluster         : B
  scale           : B
  legend          : iseq LegendEntry
  legend_position : {topright, topleft, bottomright, bottomleft}
----------------------------------------
  ZOOM_MIN <= zoom <= ZOOM_MAX

LegendEntry
  label  : S | label ≠ ''
  colour : HexColour
  radius : ℝ ∪ {∅} | radius = ∅ ∨ 0 < radius < 10^6
  group  : S ∪ {∅}

new ≙
  params? : Params
  osm!    : HTML_OSM
----------------------------------------
  osm!.zoom     = params?.zoom     ∨ 12
  osm!.cluster  = params?.cluster  ∨ false
  osm!.scale    = params?.scale    ∨ false
  osm!.fit      = params?.fit      ∨ false
  osm!.legend_position = params?.legend_position ∨ topright

Add_Marker

AddMarker
  ΔHTML_OSM
  point? : (ℝ x ℝ) ∪ S ∪ GeoObject
  result! : {0, 1}
-----------------------------------------
  result! = 1 ⟺ point? resolves to (lat, lon) ∈ ValidCoord
  result! = 1 ⟹ coordinates' = coordinates ⌢ ⟨(lat, lon, label, icon, group)⟩

Add_Geojson

AddGeoJSON
  ΔHTML_OSM
  data?  : GeoJSONStruct ∪ S
  style? : StyleMap ∪ {∅}
  popup? : S ∪ {∅}
  name?  : S ∪ {∅}
  show?  : 𝔹 ∪ {∅}
  key?   : LayerKey ∪ {∅}
-----------------------------------------
  name? ≠ ∅ ⇒ name? ≠ ""
  key? ≠ ∅ ⇒ #key?.entries ≥ 1 ∧ key?.position ∈ Corner
  geojson' = geojson ⌢ ⟨{data, style, popup, name, show, key}⟩

Add_Heatmap

AddHeatmap
  ΔHTML_OSM
  points? : iseq (ℝ x ℝ x [0,1])
-----------------------------------------
  heatmap_layers' = heatmap_layers ⌢ ⟨{points, radius, blur}⟩

Add_Gpx

AddGPX
  ΔHTML_OSM
  url? : S | url? ≠ ''
-----------------------------------------
  gpx_tracks' = gpx_tracks ⌢ ⟨url?⟩

Add_Choropleth

AddChoropleth
  ΔHTML_OSM
  features? : iseq GeoFeature
  values?   : S --> ℝ
  key?      : S
  scale?    : iseq S
-----------------------------------------
  Let min = min(ran values?), max = max(ran values?) ∪ {min+1}
  ∀ k ∈ dom values? •
    color(k) = scale?[floor((values?(k)-min)/(max-min) * (#scale?-1))]
  choropleth_layers' = choropleth_layers ⌢ ⟨{features, values, colors, key}⟩

Center

Center
  ΔHTML_OSM
  point? : (ℝ x ℝ) ∪ S ∪ GeoObject
  result! : {0, 1}
-----------------------------------------
  result! = 1 ⟺ point? resolves to (lat, lon) ∈ ValidCoord
  result! = 1 ⟹ center' = (lat, lon)

Zoom

Zoom
  ΔHTML_OSM
  zoom? : Z ∪ {∅}
  zoom! : Z
-----------------------------------------
  zoom? ≠ ∅ ⟹ ZOOM_MIN <= zoom? <= ZOOM_MAX
  zoom! = (zoom? ≠ ∅ ∧ zoom' = zoom?) ∨ zoom

Onload_Render

OnloadRender
  HTML_OSM
  head! : S
  body! : S
-----------------------------------------
  (#coordinates + #geojson + #heatmap_layers + #gpx_tracks + #choropleth_layers) > 0
  center ≠ ∅  ∨  ∃ valid ∈ coordinates • valid ∈ ValidCoord
  Let InView(b) = { m.group | m ∈ coordinates ∪ circle_markers • (m.lat, m.lon) ∈ b }
  fit ∧ center = ∅ ⟹ the initial view contains every (m.lat, m.lon), at zoom ≤ zoom
  ∀ bounds b reached by a move or zoom •
    listed(b) = ⟨ e ∈ legend | e.group = ∅ ∨ e.group ∈ InView(b) ⟩

Copyright 2025-2026 Nigel Horne.

This program is released under the following licence: GPL2 If you use it, please let me know.