An anatomical flatmap server to provide MapLibre compatible tilesets generated by flatmap-maker. It is intended for use with a browser-based flatmap-viewer application. The server is written in Python using the Flask and FastAPI web frameworks.
- Python 3.10
- poetry
- Under Ubuntu,
sudo apt-get install libgl-mesa-glx
- Download the latest release and extract it to a suitable directory.
- Change to this directory and run
poetry install
.
$ poetry run uvicorn mapserver.main:mapserver
- By default, maps are stored in
./flatmaps
. This can be overridden by setting theFLATMAP_ROOT
environment variable to a directory path. - The server listens at
http://localhost:8000
. Change this by adding options for Uvicorn applications to themapserver
command, e.g.poetry run uvicorn mapserver.main:mapserver --port 4300
.
As an option, the server provides a simple flatmap viewer application. Prerequisites are node
and npm
. To install the viewer give the following commands from the top-level server directory:
$ git clone https://github.com/AnatomicMaps/flatmap-server-viewer.git
$ cd viewer
$ npm install
$ npm run build
$ cd ..
To run the server with the integrated viewer:
$ poetry run uvicorn mapserver.main:mapviewer
and open http://localhost:8000/viewer in a browser.
The flatmap server can also generate maps. This requires a separate installation of mapmaker
; if this is to a location other than ./mapmaker
under the top-level server directory then the MAPMAKER_ROOT
environment variable must be set to point to where mapmaker is installed.
- First install mapmaker's pre-requisites as here.
Then:
$ git clone AnatomicMaps/flatmap-make mapmaker $ cd mapmaker $ poetry install $ cd ..
To generate a map, POST
a request to the /make/map
end-point specifying the URL of a map's manifest file. The server will respond with the id of the maker process. The /make/status/PROCESS_ID
end-point allows the process's status to be queried and /make/log/PROCESS_ID
will return a log of a running process.
SciCrunch is used to lookup attributes (e.g. labels) of anatomical entities when making maps. In order to use these services a valid SciCrunch API key must be provided as the SCICRUNCH_API_KEY
environment variable. (Keys are obtained by registering as a SciCrunch user).
Any publicly accessible map server must control who can generate maps — we use bearer tokens (RFC 6750) for this. To enable, set the BEARER_TOKENS
environment variable to a space separated list of valid tokens, before starting the server. e.g:
$ export BEARER_TOKENS="token1 token2"
$ poetry run uvicorn mapserver.main:mapserver
When BEARER_TOKENS
have been defined, every request to a map generation endpoint must specify a valid token using the HTTP Authorization
header. With curl
this is done using the -H "Authorization: Bearer BEARER_TOKEN"
option.
Request generation:
$ curl -H "Content-Type: application/json" -X POST
-d '{"source":"/Users/dave/build/Flatmaps/new-maker/tests/gradients/manifest.json"}'
http://localhost:8000/make/map
Response:
{"maker":18259,"source":"/Users/dave//build/Flatmaps/new-maker/tests/gradients","status":"started"}
Query build status:
$ curl http://localhost:8000/make/status/18259
Response:
{"maker":18259,"status":"terminated"}
Get log of build:
$ curl http://localhost:8000/make/log/18259
Response:
2021-01-22 09:14:05,925 Mapmaker 1.0.0b1
2021-01-22 09:14:05,928 Adding details...
2021-01-22 09:14:05,928 Outputting GeoJson features...
2021-01-22 09:14:05,928 Layer:gradients
2021-01-22 09:14:05,929 Running tippecanoe...
2021-01-22 09:14:06,020 Generating background tiles (may take a while...)
2021-01-22 09:14:06,021 Tiling gradients_image...
2021-01-22 09:14:06,040 Tiling zoom level 10 for gradients_image
2021-01-22 09:14:08,811 Tiling zoom level 9 for gradients_image
2021-01-22 09:14:08,935 Tiling zoom level 8 for gradients_image
2021-01-22 09:14:08,976 Tiling zoom level 7 for gradients_image
2021-01-22 09:14:08,994 Tiling zoom level 6 for gradients_image
2021-01-22 09:14:09,005 Tiling zoom level 5 for gradients_image
2021-01-22 09:14:09,015 Tiling zoom level 4 for gradients_image
2021-01-22 09:14:09,024 Tiling zoom level 3 for gradients_image
2021-01-22 09:14:09,034 Tiling zoom level 2 for gradients_image
2021-01-22 09:14:09,063 Creating index and style files...
2021-01-22 09:14:09,065 Generated map: gradients
This generates a flatmap showing part of the vagus nerve, from sources held in a publicly accessible PMR workspace:
$ curl -H "Content-Type: application/json"
-X POST
-d '{"source":"https://models.physiomeproject.org/workspace/693/rawfile/aa83dc1b19c03101d6a5306c77d144823fd59ea5/vagus_test.manifest.json"}'
http://localhost:8000/make/map
Response:
{"map":"83f6c97d571b67fb4c273e20287b53b4f0a1f70780d3d6a2a282e66cef5f9473","process":57906,"source":"https://models.physiomeproject.org/workspace/693/rawfile/aa83dc1b19c03101d6a5306c77d144823fd59ea5/vagus_test.manifest.json","status":"started"}
Query build status:
$ curl http://localhost:8000/make/status/57906
Response shows running
:
{"process":57906,"status":"running"}
Get log showing progress:
$ curl http://localhost:8000/make/log/57906
Response:
2021-06-11 13:46:17,386 INFO: Mapmaker 1.2.0b3
2021-06-11 13:46:17,903 INFO: Making map: 83f6c97d571b67fb4c273e20287b53b4f0a1f70780d3d6a2a282e66cef5f9473
2021-06-11 13:46:20,148 WARNING: Unknown anatomical entity: SAO:1770195789
2021-06-11 13:46:20,724 INFO: Adding details...
2021-06-11 13:46:20,728 INFO: Routing paths...
2021-06-11 13:46:20,728 INFO: Outputting GeoJson features...
2021-06-11 13:46:20,728 INFO: Layer: vagus_test
2021-06-11 13:46:20,800 INFO: Layer: vagus_test_routes
2021-06-11 13:46:20,800 INFO: Running tippecanoe...
2021-06-11 13:46:20,996 INFO: Generating background tiles (may take a while...)
2021-06-11 13:46:20,998 INFO: Tiling vagus_test_image...
2021-06-11 13:46:21,019 INFO: Tiling zoom level 10 for vagus_test_image
Check status :
$ curl http://localhost:8000/make/status/57906
Response shows terminated
:
{"process":57906,"status":"terminated"}
Get full log:
$ curl http://localhost:8000/make/log/57906
Response:
2021-06-11 13:46:17,386 INFO: Mapmaker 1.2.0b3
2021-06-11 13:46:17,903 INFO: Making map: 83f6c97d571b67fb4c273e20287b53b4f0a1f70780d3d6a2a282e66cef5f9473
2021-06-11 13:46:20,148 WARNING: Unknown anatomical entity: SAO:1770195789
2021-06-11 13:46:20,724 INFO: Adding details...
2021-06-11 13:46:20,728 INFO: Routing paths...
2021-06-11 13:46:20,728 INFO: Outputting GeoJson features...
2021-06-11 13:46:20,728 INFO: Layer: vagus_test
2021-06-11 13:46:20,800 INFO: Layer: vagus_test_routes
2021-06-11 13:46:20,800 INFO: Running tippecanoe...
2021-06-11 13:46:20,996 INFO: Generating background tiles (may take a while...)
2021-06-11 13:46:20,998 INFO: Tiling vagus_test_image...
2021-06-11 13:46:21,019 INFO: Tiling zoom level 10 for vagus_test_image
2021-06-11 13:46:23,802 INFO: Tiling zoom level 9 for vagus_test_image
2021-06-11 13:46:23,969 INFO: Tiling zoom level 8 for vagus_test_image
2021-06-11 13:46:24,034 INFO: Tiling zoom level 7 for vagus_test_image
2021-06-11 13:46:24,062 INFO: Tiling zoom level 6 for vagus_test_image
2021-06-11 13:46:24,079 INFO: Tiling zoom level 5 for vagus_test_image
2021-06-11 13:46:24,097 INFO: Tiling zoom level 4 for vagus_test_image
2021-06-11 13:46:24,116 INFO: Tiling zoom level 3 for vagus_test_image
2021-06-11 13:46:24,136 INFO: Tiling zoom level 2 for vagus_test_image
2021-06-11 13:46:24,188 INFO: Creating index and style files...
2021-06-11 13:46:24,195 INFO: Generated map: 83f6c97d571b67fb4c273e20287b53b4f0a1f70780d3d6a2a282e66cef5f9473