Mapmaker

Overview

Mapmaker 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 mapmaker is run in a Conda environment on a Linux or macOS system. This includes Windows Subsystem for Linux (WSL) for Microsoft Windows systems.

Prerequisites

Install a miniforge environment 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

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 mapmaker:

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

Setup the environment

• Change into the mapmaker directory and install dependencies using Conda:

  $ conda env create -f envs/mapmaker.yaml

Running

• Activate mapmaker's Conda environment:

  $ conda activate mapmaker

• From the mapmaker 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 mapmaker installation directory.

• With the Conda environment active, and within the mapmaker directory:

  $  conda env update -f envs/mapmaker.yaml

Command line help

$ python runmaker.py --help

usage: mapmaker [-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] [--publish SPARC_DATASET] [--sckan-version {production,staging}]
                [--authoring] [--debug]
                [--only-networks] [--save-drawml] [--save-geojson] [--tippecanoe]
                [--initial-zoom N] [--max-zoom N]
                [--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
  --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-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

mapmaker uses poetry for dependency management and packaging. To create a development environment:

$ git clone https://github.com/AnatomicMaps/flatmap-maker.git mapmaker
$ cd mapmaker
$ poetry install

Building documentation

In development mode, and within the Python virtual environment:

$ cd docs
$ make html