Installation and Running¶

Flatmap Server¶

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 Litestar ASGI web framework.

Documentation¶

https://flatmap-server.readthedocs.io/en/latest/

Prerequisites¶

Python 3.12
The uv Python package manager
Under Ubuntu < 24: sudo apt-get install libgl-mesa-glx
Ubuntu 24: sudo apt-get install libfontconfig1 libegl1 libgl1
RHEL/Fedora: yum install fontconfig mesa-libGL mesa-dri-drivers

Installation¶

Download the latest release and extract it to a suitable directory.
Change to this directory and run uv install.

Running¶

$ uv run python -m mapserver

By default, maps are stored in ./flatmaps. This can be overridden by setting the FLATMAP_ROOT environment variable to a directory path.
By default, the server listens at http://127.0.0.1:8000. This can be changed by setting the SERVER_INTERFACE and SERVER_PORT envirinment variables before starting the server.
Access and error logs are stored in ./logs, with map-making logs in ./logs/mapmaker.

Debugging¶

Need to have dev dependencies installed, in particular uvicorn and the Python virtual environment activated.

$ litestar --app mapserver.__main__:app run --debug

N.B. Can use --reload option but then exception tracebacks aren’t shown.

Optional map viewer¶

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/dbrnz/flatmap-viewer.git viewer
$ cd viewer
$ npm install
$ npm run build
$ cd ..

Running¶

To run the server with the integrated viewer:

$ uv run python -m mapserver viewer

and open http://localhost:8000/viewer in a browser.

Map generation¶

The server includes the ability to generate flatmaps – to generate a map, POST a request to the /make/map end-point specifying the path of a local manifest file or the URL of a Git repository containing a manifest and the relative path of the manifest within the repository, optionally with a specific commit identifier. 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).

Authentication¶

Any publicly accessible map server must control who can generate maps — we use bearer tokens (RFC 6750) for this. To enable, set the MAPMAKER_TOKENS environment variable to a space separated list of valid tokens, before starting the server. e.g:

$ export MAPMAKER_TOKENS="token1 token2"
$ uv run python -m mapserver

When MAPMAKER_TOKENS have been defined, every request to a map generation endpoint must specify a valid bearer token using the HTTP Authorization header. With curl this is done using the -H "Authorization: Bearer TOKEN" option.

Examples¶

A local map source¶

Request generation:

$ curl -H "Content-Type: application/json" -X POST \
       -d '{"source":"/Users/dave/build/Flatmaps/new-maker/tests/gradients/manifest.json"}' \
       -H "Authorization: Bearer 123" \
       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

A remote map source¶

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://github.com/AnatomicMaps/test-flatmap", "manifest": "manifest.json"}' \
       -H "Authorization: Bearer 123" \
       http://localhost:8000/make/map

Response:

{"manifest":"manifest.json","process":94908,"source":"https://github.com/AnatomicMaps/test-flatmap","status":"started"}

Query build status:

$  curl http://localhost:8000/make/status/94908

Response shows running:

{"process":94908,"status":"running"}

Get log showing progress:

$ curl http://localhost:8000/make/log/94908

Response:

2024-05-01 09:00:02,426 INFO: Mapmaker 1.8.0
2024-05-01 09:00:03,697 INFO: Making map: test-flatmap       .
   .
   .

Check status

$  curl http://localhost:8000/make/status/94908

Response shows terminated:

{"process":94908,"status":"terminated"}

Get full log:

$ curl http://localhost:8000/make/log/94908

Response:

   .
   .
   .
INFO: Generated map: id: test-flatmap, uuid: 906489ed-0600-5382-810d-95449064c5a6, models: NCBITaxon:1, output: ...