FlatmapMaker

Overview

FlatmapMaker is a Python application for generating MapLibre compatible tilesets from a range of sources, currently Powerpoint slides, SVG diagrams, and segmented image files from MBF Biosciences.

Documentation

• https://flatmap-maker.readthedocs.io/en/latest/

Installation

We recommend that FlatmapMaker is run in a Python environment on a Linux or macOS system. This includes Windows Subsystem for Linux (WSL) for Microsoft Windows systems.

Prerequisites

Install the uv Python package manager as descibed here.

macOS

Apple macOS users may first have to install the XCode command line tools. Check if the command line tools are installed by running:

$ xcode-select -p

and if they are not, install them by running:

$ xcode-select --install

Linux

Debian/Ubuntu:

$ apt-get install libfontconfig1 libgl1-mesa-glx libgl1-mesa-dri

Ubuntu 24:

$ apt-get install libfontconfig1 libegl1 libgl1

RHEL/Fedora:

$ yum install fontconfig mesa-libGL mesa-dri-drivers

Installation

• At a CLI prompt, and in a suitable directory, download the latest release in tar.gz format and extract it, renaming the top-level directory in the archive to flatmapmaker:

  $ curl -L https://github.com/AnatomicMaps/flatmap-maker/archive/refs/tags/v1.26.1.tar.gz \
  | tar xz -s /v1.26.1.tar.gz/flatmapmaker/

Setup the environment

• Change into the flatmapmaker directory and install dependencies using uv:

  $ uv sync

Running

• Activate flatmapmaker's Python environment:

  $ source .venv/bin/activate

• From the flatmapmaker directory use python to execute runmaker.py:

  $ python runmaker.py ARGUMENTS

• SciCrunch is used to lookup attributes (e.g. labels) of anatomical entities. 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).

Updating

• Download and extract the archive of the latest release as above, overwriting the existing flatmapmaker installation directory.

• Within the flatmapmaker directory:

  $ uv sync

Command line help

$ python runmaker.py --help

usage: runmaker [-h] [-v]
[--log LOG_FILE] [--silent] [--verbose]
[--background-tiles] [--clean-connectivity] [--disconnected-paths] [--force]
[--id ID] [--ignore-git] [--ignore-sckan] [--invalid-neurons] [--no-path-layout]
[--path-arrows] [--publish SPARC_DATASET] [--sckan-version {production,staging}]
[--authoring] [--debug]
[--only-networks] [--save-drawml] [--save-geojson] [--tippecanoe]
[--initial-zoom N] [--max-zoom N]
[--export-bondgraphs] [--export-features EXPORT_FILE] [--export-neurons EXPORT_FILE]
[--export-svg EXPORT_FILE] [--single-file {celldl,svg}]
--output OUTPUT --source SOURCE
Generate a flatmap from its source manifest.
options:
-h, --help show this help message and exit
-v, --version show program's version number and exit
Logging:
--log LOG_FILE Append messages to a log file
--silent Suppress all messages to screen
--verbose Show progress bars
Map generation:
--background-tiles Generate image tiles of map's layers (may take a
while...)
--clean-connectivity Refresh local connectivity knowledge from SciCrunch
--disconnected-paths Include paths that are disconnected in the map
--force Generate the map even if it already exists
--id ID Set explicit ID for flatmap, overriding manifest
--ignore-git Don't check that sources are committed into git
--ignore-sckan Don't check if functional connectivity neurons are known
in SCKAN. Sets `--invalid-neurons` option
--invalid-neurons Include functional connectivity neurons that aren't known
in SCKAN
--no-path-layout Don't do `TransitMap` optimisation of paths
--path-arrows Render arrows at the terminal nodes of paths
--publish SPARC_DATASET
Create a SPARC Dataset containing the map's sources and the generated map
--sckan-version {production,staging}
Overide version of SCKAN specified by map's manifest
Diagnostics:
--authoring For use when checking a new map: highlight incomplete
features; show centreline network; no image tiles; no
neuron paths; etc
--debug See `log.debug()` messages in log
--only-networks Only output features that are part of a centreline
network
--save-drawml Save a slide's DrawML for debugging
--save-geojson Save GeoJSON files for each layer
--tippecanoe Show command used to run Tippecanoe
Zoom level:
--initial-zoom N Initial zoom level (defaults to 4)
--max-zoom N Maximum zoom level (defaults to 10)
Miscellaneous:
--export-bondgraphs
Export functional modelling components as CellDL bondgraphs
--export-features EXPORT_FILE
Export identifiers and anatomical terms of labelled features as JSON
--export-neurons EXPORT_FILE
Export details of functional connectivity neurons as JSON
--export-svg EXPORT_FILE
Export Powerpoint sources as SVG
--single-file {celldl,svg}
Source is a single file of the designated type, not a
flatmap manifest
Required arguments:
--output OUTPUT Base directory for generated flatmaps
--source SOURCE URL or path of a flatmap manifest

Manifest files

The sources of a flatmap are specified using a JSON file, usually called manifest.json. See :ref:`manifest-files` for details.

Anatomical map file

TODO...

Properties file

TODO...

Shape markup

TODO...

Integration

TODO...

• Python wheel available.

Development

flatmapmaker uses uv for dependency management and packaging. To create a development environment:

$ git clone https://github.com/AnatomicMaps/flatmap-maker.git flatmapmaker
$ cd flatmapmaker
$ uv sync --dev
$ source .venv/bin/activate

Building documentation

In development mode, and within the Python virtual environment:

$ cd docs
$ make html