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.22.2.tar.gz \
  | tar xz -s /v1.22.2.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