mapgen is a tool (written in Python 3) which generates interactive maps with
customizable markers. It takes a YAML file containing map settings and marker
data as input and generates an HTML page as output. This page contains all
in a web browser (without the need for a web server), shared with others (e.g.
via e-mail), or added to an existing webpage through an
Below is an example of what a typical input YAML file looks like:
map settings: title: Largest capital cities of the European Union markers: - coordinates: [51.5073219, -0.1276474] popup contents: London, United Kingdom (8.83 million) - coordinates: [52.5170365, 13.3888599] popup contents: Berlin, Germany (3.75 million) - coordinates: [40.4167047, -3.7035825] popup contents: Madrid, Spain (3.23 million) - coordinates: [41.894802, 12.4853384] popup contents: Rome, Italy (2.87 million) - coordinates: [48.8566101, 2.3514992] popup contents: Paris, France (2.15 million)
The resulting page can be seen here. Clicking on a marker will open a popup showing its associated city name and estimated population.
Here are some more interesting examples:
Files from the Leaflet library are licensed under the 2-clause BSD license.
Icons from Flaticon were produced by Google, Freepik and Smashicons. Those are all licensed under the CC BY 3.0 license.
All Python modules needed by
mapgen are listed in the
file. You can install them with the following command:
pip3 install -r requirements.txt
For an input file
input.yaml containing map settings and marker data,
running the following command will generate the desired HTML
page and store it on
./mapgen -i input.yaml -o output.html
If you omit
-o output.html on the command above, the generated HTML will be
printed on the standard output (
Each marker has two possible states: "normal" and "selected". Different icons can be displayed for a marker depending on whether it is selected or not. This allows the user to create maps which are more fun to interact with by making the icon of a selected marker look different from the icons of the unselected (normal) markers. Only one marker can be selected at a time.
NOTE: When running
mapgen, relative paths to icons files appearing on
the input YAML file will be resolved from the current working directory, not
from the location of the YAML file!
popup contents is defined for a marker, a popup will be shown when it is
selected. Markers with no
popup contents defined are assumed to be
non-selectable and are therefore always displayed with their normal icons.
The input YAML file is divided into three main sections:
default marker settings: Style settings (e.g. icon dimensions) which are applied to all markers by default. These settings can be overridden at the definition of each marker.
map settings: Global map settings such as the language used to display labels on the map (e.g. country names) as well as external resources to inline into the generated HTML page with the intent of modifying the map's style and behavior.
markers: List of markers to be displayed on the map. Each marker must have a pair of coordinates specifying its location. A marker is not required to have a popup (
popup contentsis an optional attribute).
default marker settings:
icon: Path to an icon file (an image) or the name of a built-in icon to be used as the default icon for markers in both "normal" and "selected" states. Built-in icons are located in the
template/iconsdirectory, and their names must be given without the
house). Defaults to
icon color: Default icon color assigned to all icons of all markers (both in "normal" and "selected" states). Applicable only to built-in icons. Any CSS color is allowed.
icon dimensions: Default icon dimensions (in pixels) expressed as an array of form
[width, height]. Defaults to
normal icon: Accepts the same values as
icon, but only affects the icons shown for markers when they are not selected. Has higher precedence than
icon, i.e., if both
normal iconare specified, the default normal icon will be set to the one specified in
normal icon color: Accepts the same values as
icon color, but only affects the icons shown for markers when they are not selected. Has higher precedence than
icon color, i.e., if both
normal icon colorare specified, the default color for normal icons will be set to the one specified in
normal icon color. Defaults to
normal icon dimensions: Accepts the same values as
icon dimensions, but only affects the icons shown for markers when they are not selected. Has higher precedence than
icon dimensions, i.e., if both
normal icon dimensionsare specified, the default dimensions for normal icons will be set to those specified in
normal icon dimensions.
selected icon: Equivalent of
normal iconfor selected icons.
selected icon color: Equivalent of
normal icon colorfor selected icons. Defaults to
selected icon dimensions: Equivalent of
normal icon dimensionsfor selected icons.
external css files: List of CSS files to be inlined into the generated HTML page. CSS styles defined in these files will override the default CSS styles from
mapproperty of the global
language: Language used to display labels on the map (e.g. country, city and street names). Valid values are
local(to have labels in each country be displayed in the country's official language) and short language codes such as
de(to have all labels be displayed in a specific language). Valid language codes are listed in this article, but not all labels are guaranteed to exist in every available language. Defaults to
show zoom control: Whether zoom controls (
-buttons) should be displayed or not. Valid values are
yes. Defaults to
title: Title to be displayed when the generated HTML page is opened in a web browser.
zoom control position: Location on the map where zoom controls must be displayed, if applicable. Valid values are
top right. Defaults to
Marker entries in
All markers must be entered as a list under the
markers section of the YAML
file. Every marker accepts the same attributes as the ones from
default marker settings, but those will only be applied to the marker being
defined, i.e., values for attributes specified on a marker have higher
precedence than those for attributes with the same names specified under
default marker settings.
Additional attributes for markers:
coordinates: Marker position on the map expressed as an array of form
[latitude, longitude]. Latitude and longitude values must fall within the value ranges
[-180, 180]respectively. Every marker needs to have
popup contents: HTML contents to be shown on the popup displayed for a marker when it is selected.
Contributors & contact information
Diego Assencio / firstname.lastname@example.org