Maintainer: manuelroth
Q locator map is a tool of the Q toolbox which allows to create locator maps. Test it in the demo.
git clone git@github.com:nzzdev/Q-locator-map.git
cd ./Q-locator-map
nvm use
npm install
npm run buildQ locator map is configured by the following env variables and through config passed in toolRuntimeConfig:
Q locator map renders maps using vector tiles. The TILESETS env variable defines one or more tilesets which are used for the map. The TILESETS env variable needs to be defined like this:
{
"openmaptiles": {
"path": "/data/openmaptiles.mbtiles"
},
"contours": {
"path": "/data/contours.mbtiles"
},
"hillshade": {
"url": "https://www.example.com/hillshade/{z}/{x}/{y}.png"
},
"regions": {
"url": "https://www.example.com/regions/{z}/{x}/{y}.pbf"
}
}
A tileset can be defined as path to the mbtiles file or as an url to an endpoint serving tiles.
The tool uses a database to get geodata of countries and states to generate minimaps. The COUCHDB env variable defines the connection parameters to reach the database:
{
"host": "...",
"database": "...",
"user": "...",
"pass": "..."
}
Mapbox is used for the satellite basemap. The MAPBOX_ACCESS_TOKEN env variable defines the access token required to use it.
The tool uses the @hapi/catbox-memory package to cache resources in memory. The MEMORY_CACHE_SIZE env variable allows to configure the size of the memory cache in bytes.
Q locator maps needs configuration passed in toolRuntimeConfig to the /rendering-info/web endpoint. The fonts config is mandatory and all other parameters are optional. See the following example:
toolRuntimeConfig: {
styleConfig: {
// mandatory
fonts: {
fontBaseUrl: "https://www.example.com/fonts/",
fontSansLight: {
name: "Noto-Sans-Light"
},
fontSansRegular: {
name: "Noto-Sans-Regular"
},
fontSansMedium: {
name: "Noto-Sans-Medium"
},
fontSerifRegular: {
name: "Noto-Serif-Regular"
}
},
// optional
colors: {
basic: {
background: "#f0f0f2",
water: "#d0e2ec",
waterText: "#428cb3",
waterway: "#d0e2ec",
forest: "#99c7a3",
road: "#dfe0e5",
railway: "#d8d9db",
building: "#e3e3e8",
text: "#92929e",
boundaryCountry: "#a88ea8",
boundaryState: "#c9c4e0",
boundaryCommunity: "#d4c1ee"
},
minimal: {
background: "#f0f0f2",
water: "#cee1e6",
waterText: "#428cb3",
waterway: "#d6d6d6",
forest: "#e6e9e5",
road: "#f5f5f5",
railway: "#d8d8d8",
building: "#cbcbcb",
text: "#92929e",
boundary: "#cfcfd6"
},
nature: {
background: "#edece1",
water: "#d0e2ec",
waterText: "#428cb3",
waterway: "#d0e2ec",
forest: "#99c7a3",
road: "#dbdad1",
railway: "#d9d9d9",
building: "#dbdad1",
text: "#92929e",
boundary: "#b6b6be",
hillshadeOpacity: 0.2
},
satellite: {
background: "#f0f0f2",
water: "#d0e2ec",
waterText: "#428cb3",
waterway: "#d0e2ec",
forest: "#e6e9e5",
road: "#f5f5f5",
railway: "#d8d8d8",
building: "#cbcbcb",
text: "#92929e",
boundary: "#ffffff"
}
},
markers: {
textHaloWidth: 1,
textBlurWidth: 0.1,
textLetterSpacing: 0.2,
textTransform: "none",
textAnchor: {
stops: [
[7.99, "left"],
[8, "center"]
]
},
textJustify: "left",
textOffset: [0, 0],
iconSize: 1,
iconMarker: {
textColorIconMarker: "#05032d",
textHaloColorIconMarker: "#ffffff",
textSizeIconMarker: 14,
textFontIconMarker: ["{fontSansMedium}"]
},
country: {
textSizeCountry: 14,
textColorCountry: "#6e6e7e",
textTransformCountry: "none"
},
capital: {
textSizeCapital: 15,
textTranslateCapital: [10, 0],
iconImageCapital: {
stops: [
[7.99, "capital"],
[8, ""]
]
}
},
city: {
textSizeCity: 13,
textTranslateCity: [7, 0],
iconImageCity: {
stops: [
[7.99, "city"],
[8, ""]
]
}
},
label: {
textTransformLabel: "uppercase"
},
line: {
colorLine: "#c31906",
widthLine: 2,
opacityLine: 1,
dashedLine: [1, 3]
},
polygon: {
fillColorPolygon: "#c31906",
outlineWidthPolygon: 0,
opacityPolygon: 0.35
}
},
highlightRegion: {
highlightCountryColor: "#ffffff",
highlightRegionColor: "#d7cddc"
},
minimap: {
hasShadow: true,
landColor: "#ffffff",
textColor: "#6e6e7e",
bboxColor: "#000000",
textSize: 12,
globe: {
width: 90,
landOutlineColor: "#b6b6be",
landOutlineWidth: 0.5,
waterColor: "#d0e2ec"
},
region: {
width: 120,
minWidth: 40,
landOutlineColor: "#b6b6be",
landOutlineWidth: 0.5
}
},
scale: {
textSize: 11,
textColor: "#6e6e7e",
textHaloWidth: 1,
borderWidth: 1.5
},
aspectRatioBreakpoint: 450,
hasAttribution: true
}
}
The toolRuntimeConfig is also configured in cli-config.js to be used with Q-CLI
Start the Q dev server:
npx @nzz/q-cli server -c ./dev-config/server-config.js
Run the Q tool:
node dev.js
The testing framework used in this repository is Code.
Run the tests:
npm run test
When changing or implementing...
- A
route, it needs to be tested in thee2e-tests.jsfile - Something on the frontend, it needs to be tested in the
dom-tests.jsfile
We provide automatically built docker images at https://hub.docker.com/r/nzzonline/q-locator-map/. There are three options for deployment:
- use the provided images
- build your own docker images
- deploy the service using another technology
- Deploy
nzzonline/q-locator-mapto a docker environment - Set the ENV variables as described in the configuration section
The tool structure follows the general structure of each Q tool. Further information can be found in Q server documentation - Developing tools.
Q Locator Map uses the svelte framework to render the markup like header and footer on server-side. The map gets rendered on client-side using the Mapbox GL JS framework. The tool uses various other opensource packages like Turf, Vega, Mapshaper and many more to help build a great Locato Map tool. Check the package.json file for more information.
Vector tiles of the basemap are provided by the OpenMapTiles project. The geodata of countries and states used for minimaps and highlighted regions are based on OpenStreetMap and Natural Eath.
This option allows to overwrite the visible area of the map. It is defined based on a bounding box that the user defines. With the option useDefaultAspectRatio it is possible to define a custom aspect ratio of the map. This can be helpful for maps that show very long or wide countries like Chile or Russia.
This option allows to switch between four different basemaps (standard, minimal, nature and satellite). The layers option allows to disable certain layer of the map (labels).
This option defines whether a minimap is shown and which type (globe or region). The position option defines in which corner the minimap is shown. If the minimap is positioned in the bottom left corner the scale is moved to the top left corner.
This option defines one or more regions which should be highlighted on the map.
This option allows to show the labels of the points which the user entered to be shown below the map. labelsBelowMapOneRow option defines whether the labels should be shown on a single row.
This options allows to show the legend. The legend is only shown for linestring and polygon features.
Display options can be set before embedding the graphic in the article.
Allows to hide the title
Copyright (c) 2020 Neue Zürcher Zeitung. All rights reserved.
This software is published under the MIT license.