---
updatedAt: 2025-08-31T08:55:11.000Z
agentTools:
projectIndex: https://docs.sparc.science/llms.txt
---
# Map maker
A Python application which combines the anatomical diagrams with the connectivity knowledge to produce the rendered map tiles which form the actual flatmap visualization
## Overview
Mapmaker is the tool which combines the anatomical diagrams with the connectivity knowledge to produce the rendered map tiles which form the actual flatmap visualization. Learn more about how [flatmaps](https://docs.sparc.science/docs/flatmaps#/) are made.
Mapmaker is a Python application that generates Mapbox compatible tilesets from a range of sources (currently including SVG drawings, MBF Biosciences segmented images, and PowerPoint slides; learn more about [Flatmap Sources](https://docs.sparc.science/docs/flatmap-sources#/)). In conjunction with SCKAN, Mapmaker is used to render the flatmaps portraying the anatomy and nerve knowledge of species, as seen on the SPARC Portal Maps page.
Flatmaps can be generated and viewed by using the flatmap maker (mapmaker), server, and viewer. For more information on how these flatmap resources are used together, see the [Flatmaps](https://docs.sparc.science/docs/flatmaps#/) documentation.
## Source Code
Map makerβs source code is hosted on GitHub.
* [Source code](https://github.com/AnatomicMaps/flatmap-maker)
* [Documentation, feature requests, and issues](https://flatmap-maker.readthedocs.io/en/latest/)
* [Versioned releases](https://github.com/AnatomicMaps/flatmap-maker/releases)
## Installation Overview
It is recommended to install and run mapmaker under its own Python virtual environment. Mapmaker can be installed as a python application, or a development version can be set up. The Development Environment section explores how to set up the development version of mapmaker. Further instructions for each OS and/or environment are also provided below.
The mapmaker resources include flatmap-maker, flatmap-server, and flatmap-viewer. Each repository contains documentation regarding installation:
* [Flatmap maker (Mapmaker)](https://github.com/AnatomicMaps/flatmap-maker)
* [Flatmap server](https://github.com/AnatomicMaps/flatmap-server)
* [Flatmap viewer](https://github.com/AnatomicMaps/flatmap-viewer)
## Python Application Installation
Simply install the mapmaker wheel and the flatmap server by following the respective instructions (linked above). [Learn how to install a Python wheel](https://www.geeksforgeeks.org/how-to-install-a-python-package-with-a-whl-file/). Run mapmaker with the appropriate command, and start the flatmap server to view the map.
> π Note:
>
> Be sure to use the latest [release](https://github.com/AnatomicMaps/flatmap-maker/releases) of mapmaker when installing the .whl file. Figure 1 highlights where in the flatmap maker repository to find the mapmaker releases.
## Development Environment Installation
### Prerequisites
The following are required in order to successfully install and generate maps. Links to the packages have been provided, which capture installation instructions.
* Mapmaker:
* Python 3.10
* [Tippecanoe](https://github.com/mapbox/tippecanoe#installation)
* [COIN-OR CBC Solver](https://github.com/coin-or/Cbc#binaries)
* [Poetry](https://python-poetry.org/docs/#installing-with-the-official-installer)
* Miniforge (for ARM based MacOS machines)
* Flatmap viewer
* [Node.js](https://nodejs.org/en/download/)
* Flatmap server
* Python 3.8 (or higher)
* [Poetry](https://python-poetry.org/docs/#installing-with-the-official-installer)
* Libgl1-mesa-glx
### Installation
> π Note:
>
> Examples, including specific commands, for Windows and MacOS can be found in the Installation for various environments section.
The first step is to install the prerequisite packages.
1. 1. make
2. g++
3. sqlite libsqlite3-dev
4. libz-dev
5. coinor-cbc
2. Set up the Tippecanoe package, following the official [instructions](https://github.com/mapbox/tippecanoe/blob/master/README.md).
> π Note:
>
> Several warnings may appear but can be neglected. However, error messages in red may indicate failure.
3. In the root directory, clone the flatmap-maker, -server, and -viewer repositories.
> π Note:
>
> This will clone the head of the main branch of each repository. It is recommended to use the latest released version of mapmaker. Switch to the latest release while in the flatmap-maker directory (shown in Figure 1).
4. As aforementioned, the flatmap resources are reliant on [Poetry](https://python-poetry.org/docs/#installing-with-the-official-installer). Following the link, install Poetry via the instructions provided.
> π Note:
>
> The βpoetryβ command may not be recognized. This can be resolved by adding Poetry to the PATH, as per the official installation instructions.
5. Once this has been done, enter the flatmap-maker directory and set up a Poetry environment. Test the installation by opening a poetry environment.
6. Exit the poetry environment. In the flatmap-server directory, set up another Poetry environment. The mapserver can be started with
```Text terminal
$ poetry run mapserver
```
> π Note:
>
> A warning may appear relating to an undefined SCRICRUNCH\_API\_KEY. This can be ignored as the SciCrunch key will be added via mapmaker.
7. Enter the flatmap-viewer directory and install npm. The output of npm install may mention several vulnerabilities, which can be resolved by following the suggested fix.
> π Note:
>
> As mentioned in the Prerequisites section, node.js must be installed for the flatmap viewer. Click the link provided in the Prerequisites section and follow the instructions.
The flatmap viewer can be started with
```Text terminal
$ npm start
```
> π Note:
>
> The flatmap viewer may fail to start due to the updated version of Nodejs. This can be resolved by using [Node Version Manager](https://github.com/nvm-sh/nvm/blob/master/README.md) to install v12.22.9.\_
8. The flatmap resources have been installed and are ready for use. Flatmaps will require a source, including a set of JSON files and an SVG file (see [Flatmap sources](https://docs.sparc.science/docs/flatmap-sources#/) for more information). For an up-to-date version of the rat flatmap (to be used alongside the developer environment of mapmaker), the repository below should be cloned. The set of sources for the flatmaps of other species found on the SPARC Portal can be found within the [AnatomicMaps](https://github.com/AnatomicMaps) organization, such as the [rat-flatmap](https://github.com/AnatomicMaps/rat-flatmap).
> π Note:
>
> This link is for the latest flatmap resources, not an official release.
Flatmaps should now be ready for generation.
### Using mapmaker
Once the [flatmap sources](https://docs.sparc.science/docs/flatmap-sources#/) have been appropriately created, mapmaker can now generate the flatmap. Mapmaker has various arguments that can be used to generate maps. These arguments, some optional, can allow for different visualizations of the flatmaps, and for debugging purposes.
Mapmaker involves various required and optional arguments (refer to the [documentation](https://github.com/AnatomicMaps/flatmap-maker/blob/main/README.rst) for more information). Table 1 contains the required arguments to generate a map.
| | |
| :--------------------------------- | :-------------------------------------------------------------------- |
| --source *PATH TO SOURCE MANIFEST* | Points mapmaker to the source of flatmap (i.e. the manifest.json) |
| --output *PATH TO DIRECTORY* | Points mapmaker to the directory of the base of the generated flatmap |
*Table 1: The required arguments when running mapmaker. β--sourceβ refers to the path to the directory of the source filesβ manifest.json. β--outputβ should point to the directory to dump the knowledgebase.db file.*
1. Enter the flatmap-maker directory and spawn a poetry shell.
2. The flatmaps utilise the SciCrunch knowledgebase, to use this service a valid SciCrunch API Key must be set. Learn how to [generate a SciCrunch API key](https://docs.sparc.science/docs/accessing-scicrunch-vocabulary-services#/).
```Text terminal
$ export SCICRUNCH_API_KEY=*Enter a valid SciCrunch Key*
```
3. Run mapmaker using the following command (with the appropriate and any desired arguments).
```Text terminal
$ python runmaker.py --source _Enter path to flatmap source_ --output _Enter path to output directory_
```
Given mapmaker runs with no crashes or issues, the flatmap has now been successfully generated. The flatmap can be viewed by setting up the server and viewer.
4. To set up the flatmapβs server, open a new terminal and navigate to the *flatmap-server directory*. The server depends on the *knowledgebase.db* output by mapmaker. Therefore, the directory that has been set up (via the **--output** argument in mapmaker) must be referenced.
In the flatmap-server directory, point to the *knowledgebase.db* file created by mapmaker.
```Text terminal
$ export FLATMAP_ROOT=$HOME/\_Enter path to directory_
```
Start the server.
```Text terminal
$ poetry run mapserver
```
5. With the flatmap server running, the flatmap can be viewed by starting the viewer.
Open another terminal and navigate to the *flatmap-viewer* directory. The viewer can be started with
```Text terminal
$ npm start
```
The flatmap can now be viewed on the local server output by the flatmap viewer. This is typically *localhost:3000*.
Congratulations you made a map!
## Installation for Various Environments
## Developer mapmaker via Ubuntu (WSL)
### Installation
Developer mapmaker can be installed on machines operating WindowsOS via the activation of the Windows Subsystem for Linux (WSL). To set up WSL, open a Windows command prompt as administrator and run the following command:
```Text terminal
$ wsl --install
```
Once installed, reboot and install Ubuntu 22.04 via the [Microsoft Store](https://apps.microsoft.com/store/detail/ubuntu-22041-lts/9PN20MSR04DW?hl=en-nz\&gl=nz). Open Ubuntu 22.04 and enter a desired username and password (Note that the password will be needed upon sudo installations). Upon reboot, an Ubuntu terminal may open to complete the installation. Ubuntu 22.04 must be the environment mapmaker is run in, as Python 3.10 is required. The installation should now complete successfully, and a chevron prompt will appear.
> π Note:
>
> The flatmap resources require Python 3.10. The version of python in use can be found via
>
> ```Text terminal
> $ python3 -V
> ```
The flatmap resources can now be installed. Below are the commands and supplemental information for the respective instructions found in the Installing mapmaker resources section.
> π Note:
>
> Ubuntu may need to be updated via
>
> ```Text terminal
> $ sudo apt-get update && sudo apt-get upgrade
> ```
```Text terminal
$ sudo apt install make
$ sudo apt install g++
$ sudo apt install sqlite libsqlite3-dev
$ sudo apt install libz-dev
$ sudo apt install coinor-cbc
```
```Text terminal
$ git clone
$ cd tippecanoe
$ make -j
$ sudo make install
```
> π Note:
>
> The repositories must be cloned in the root directory.
```Text terminal
$ git clone https://github.com/AnatomicMaps/flatmap-maker
$ git clone https://github.com/AnatomicMaps/flatmap-server
$ git clone https://github.com/AnatomicMaps/flatmap-viewer
```
```Text terminal
$ curl -sSL https://install.python-poetry.org | python3 -
$ PATH=$PATH:$HOME/.local/bin
```
```Text terminal
$ cd flatmap-maker
$ poetry install
```
```Text terminal
$ cd ../flatmap-server
$ sudo apt-get install libgl1-mesa-glx
$ poetry install
$ poetry run mapserver
```
```Text terminal
$ cd ../flatmap-viewer
$ npm install
```
The output of **npm install** may mention several vulnerabilities. Following the recommended instructions, these can be resolved via:
```Text terminal
$ npm audit fix
```
The viewer can be started with
```Text terminal
$ npm start
```
> π Note:
>
> npm start may fail to start the viewer. This may be due to the updated version of Nodejs. This can be resolved by utilizing the Node Version Manager (nvm). Following the GitHub installation instructions, install nvm and run the command to install v12.22.9 of Nodejs. The terminal may need to be restarted.
```Text terminal
$ nvm install 12.22.9
```
This version of node can be run via
```Text terminal
$ nvm run node --12.22.9
```
### Using Mapmaker - Windows
```Text terminal
$ cd flatmap-maker
$ poetry shell
```
```Text terminal
$ export SCICRUNCH_API_KEY= *Enter a valid SciCrunch Key*
```
```Text terminal
$ python runmaker.py --source ../flatmap-sources/rat-flatmap/manifest.json --output ../flatmap-knowledgebase --verbose --background-tiles --authoring --debug
```
In a separate terminal,
```Text terminal
$ cd flatmap-server
$ export FLATMAP_ROOT=$HOME/../flatmap-knowledgebase
$ poetry run mapserver
```
In another separate terminal,
```Text terminal
$ cd flatmap-viewer
$ npm start
```
The generated flatmap can now be viewed on the local host server, on port 3000.
## Developer mapmaker on MacOS
### Installation
To install developer mapmaker on MacOS, following the instructions of the [official installer](https://brew.sh/), install and update Homebrew.
```Text terminal
% /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
% brew update
```
> π Note:
>
> The Homebrew will need to be added to PATH, as recommended by the official installer. This can be done by running the commands provided in the output, as shown in Figure 16.
Install Python3.10, if not already installed.
```Text terminal
% brew install python@3.10
```
```Text terminal
% brew install tippecanoe
```
```Text terminal
% curl -sSL | python3 -
```
The poetry path needs to be added to the shell configuration. If using bash command:
```Text terminal
% echo "export PATH=$PATH:$HOME/.local/bin" >> ~/.bashrc
```
If using zsh command:
```Text terminal
% echo "export PATH=$PATH:$HOME/.local/bin" >> ~/.zshrc
```
```
% git clone https://github.com/AnatomicMaps/flatmap-maker
% git clone https://github.com/AnatomicMaps/flatmap-serve
% git clone https://github.com/AnatomicMaps/flatmap-viewer
```
Switch to the latest release of mapmaker. Note that the command below refers to the latest release in October 2022.
```Text terminal
% cd flatmap-maker
% git checkout v1.5.1
```
The next step is dependent on the processing chip of the MacOS machine.
> π Note:
>
> The processing chip of the MacOS machine affects how mapmaker is run (See the Using Mapmaker - MacOS section).
In the root directory:
**For Intel based machines,** install coin-or cbc.
```Text terminal
% brew tap coin-or-tools/coinor
% brew install coin-or-tools/coinor/cbc
```
**For ARM based machines,** documentation can be found in [mapmaker](https://github.com/AnatomicMaps/flatmap-maker/blob/main/M1MAC.rst).
To install conda, follow the [official conda instructions](https://conda.io/projects/conda/en/latest/user-guide/install/macos.html).
```Text terminal
% curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-arm64.sh"
% sh Miniforge3-MacOSX-arm64.sh
```
Confirm yes when prompted. In a new shell:
```Text terminal
% cd flatmap-maker
% conda env create -f conda/M1Mac.yaml
```
Install Poetry in the flatmap-maker directory.
```Text terminal
% poetry install
```
```Text terminal
% cd ../flatmap-server
% poetry install
```
The mapserver can be started by running
```Text terminal
% poetry run mapserver
```
And shut down by
```Text terminal
% Command + .
```
```Text terminal
% cd ../flatmap-viewer
% npm install
% npm audit fix
```
> π Note:
>
> npm start may fail to start the viewer. This may be due to the updated version of Nodejs. This can be resolved by utilizing the Node Version Manager (nvm). Following the GitHub installation instructions, install nvm and run the command to install v12.22.9 of Nodejs. The terminal may need to be restarted.
>
> ```Text terminal
> % nvm install 12.22.9
> ```
>
> This version of node can be run via
>
> ```Text terminal
> % nvm run node --12.22.9
> ```
The flatmap viewer can then be started with
```Text terminal
% npm start
```
And shut down with
```Text terminal
% Command + .
```
### Using Mapmaker - MacOS
As aforementioned, how mapmaker is run is dependent on the processing chip of the MacOS machine.
Activate the virtual environment.
For intel based machines:
```Text terminal
% cd flatmap-maker
% poetry shell
% export SCICRUNCH_API_KEY= *Enter a valid SCICRUNCH Key*
```
For ARM based machines, with Conda:
```Text terminal
% cd flatmap-maker
% conda activate mapmaker
% export SCICRUNCH_API_KEY= *Enter a valid SCICRUNCH Key*
```
Mapmaker can now be run. Note that the command below is specific to this example case. The paths for the source and output directories are dependent on the set up of the flatmap resources.
```Text terminal
% python runmaker.py --source ../rat-flatmap/manifest.json --output ../flatmaps --verbose --background-tiles --authoring --debug
```
In a separate terminal,
```Text terminal
% cd flatmap-server
% export FLATMAP_ROOT=$HOME/flatmaps
% poetry run mapserver
```
In another separate terminal,
```Text terminal
% cd flatmap-viewer
% npm start
```
The generated flatmap can now be viewed on the local host server, on port 3000.