Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Mapeo was built to be highly customizable and allow users to adapt its interface to meet the needs of specific projects. This section covers both translation of the application and the development of custom configurations and base maps in the pages below:
Translating Mapeo & default configurations (novice, intermediate)
Custom configurations(advanced)
Custom background maps (advanced)
Please note that the customization process for configurations and base maps currently requires significant technical knowledge and will not be accessible to all users.
When collecting or creating data with Mapeo, each observation or element on the map is assigned a category. Users must select a single category when creating a new observation or map element. Categories can be broad or specific, depending on your context and project needs.
Categories list in the Filters panel of Mapeo Desktop (using the default configuration):
For each category you choose to include in your configuration, you'll need to determine the following:
Name The label users will see in Mapeo when viewing or selecting the category
Geometry
Each element on the map will be marked as a
point
, line
(eg. a path), or area
(eg. a zone or lake). You will need to determine which of these geometries users will be able to use for each category.
All data collected with Mapeo Mobile will be points. If you are using Mapeo Mobile, you should include point
as a geometry for every category.
If you are using Mapeo Desktop Territory mode as part of your project, you can also include line
or area
for categories where relevant.
Color (optional) You have the option of setting a custom color for the map dots or markers for each category in Mapeo Mobile and Mapeo Desktop Observations mode.
Sort order (optional) You have the option of determining the order in which you would like categories to appear on the Mapeo Mobile Categories screen (pictured above). If no order is added, categories will appear alphabetically by name.
Categories are one of the key ways data can be filtered in Mapeo. Thinking through how you will view and use data once it has been created offers useful perspective when defining categories.
As a general rule, categories should not overlap - users should see only one option that fits when making a selection.
Categories and what would fall within them should be clear to those who will be collecting data. Training and information sessions may be critical for ensuring that project participants know how to gather data in consistent ways, but clarity and simplicity in configuration authoring goes a long way.
The space available to display category names is limited, especially in Mapeo Mobile, so names should be generally be brief.
All information you define for categories will be formatted in JSON
in the Coding configuration process, detailed in the following section.
If you are not comfortable working with JSON, this information can be be passed off to someone with technical skills to complete the steps in Coding configuration.
Categories list in Mapeo Mobile (using the default configuration):
Though some key steps of coding configurations require technical skills, initial planning and consultation with project participants is essential to designing effective data structures and does not require coding skills.
To start the customization process, project participants should reflect on the project goals, what kind of data will be needed, and what properties might be required for data outputs.
If you have not already done so, work through the What information to collect? section of this guide as a first step.
When planning your configuration, you will need to think through what to include for each of the key customizable areas of Mapeo. The pages that follow will walk you through some considerations when determining content for each area:
Categories When collecting or creating data with Mapeo, users assign a top-level category to each observation or element on the map.
Icons Each category you include must have an icon, or a small graphic to display to users when selecting a category.
Details fields (optional) For each category in your configuration, you can include one or more structured data fields (like a mini form or questionnaire) that users can optionally fill out when creating a new observation or map element with that category.
Configurations can and often will evolve over time. As you begin collecting data, you will likely find categories, details fields and options you would like to add or modify. Unlike some other survey or data collection tools, Mapeo allows a lot of flexibility for changing configurations over time and does not require that the database be wiped when changes are made.
In order to create a Mapeo configuration file, the information you map out for the above areas will need to be translated into JSON
files and .svg
image files and then compiled. The details of this process will be covered in Coding configuration.
If you do not have the technical skills required to code the configuration yourself, the information you define in the following pages for for Categories, Icons and Details fields can be documented and passed off to a developer or individual with technical skills to code and compile the configuration file.
Please note that creating custom configurations currently requires significant technical knowledge and will not be accessible to all users.
There are several steps to creating a custom configuration that will require different skills and the involvement of different actors within a project. You should leave plenty of time prior to the intended start of data collection to allow for community consultation, testing, and iterations of your configuration.
While data structures in Mapeo can be modified during the course of a project, many changes over time can result in messy data outputs. It is worthwhile to test and refine your configuration to the extent possible before putting it into use for data collection.
Once you have completed this process, you will have a Mapeo configuration file (.mapeosettings
) that can be imported and used in Mapeo Mobile and Destop.
The pages that follow will walk you through the key steps for authoring a custom configuration:
Planning configuration & data structure This section will outline the key customizable elements in a configuration and some considerations when mapping out each area. *No technical knowledge is required.
Coding configuration
This section will guide you through translating the planned data structure into the required format and compiling the Mapeo configuration file.
*Editing JSON
files, generating .svg
files and working with command line or GitHub is required.
For instructions on how to import a configuration file (.mapeosettings
) into Mapeo, see:
Mapeo configuration files (.mapeosettings
) are compiled from a set of files and folders that contain all the information Mapeo needs to display the categories, icons and details fields you want users to see when collecting and viewing data. This section will walk you through translating all of the information you've defined in Planning configuration & data structure into a Mapeo configuration file.
To begin preparing your files, you can download or clone our default configuration repository or this empty configuration repository from GitHub. These repositories contain the core files and folders you will need for editing.
When authoring custom configurations, you will edit files within the following configuration folders:
icons
fields
presets
(categories)
And the following configuration files:
metadata.json
defaults.json
package.json
Download the default configuration repository or empty configuration repository.
Unzip the contents to a new folder using a program like 7zip.
Rename the folder from "mapeo-default-settings" to use your own project name, "mapeo-config-projectname".
Custom configurations are a powerful tool for customization in Mapeo, allowing users to define specific categories, icons, and questionnaires for their projects. Custom category and questionnaire text can be written in any language that can be typed, ensuring that key parts of the Mapeo data collection interface can appear in the native language of the groups using it.
In the current version of Mapeo, configurations also contain a project key that allows participants of the same Mapeo project to synchronize data with each other and prevents synchronization with other devices. ​
If you have determined that Mapeo's Default configuration will not suit the needs of your project, you have the option of authoring a custom configuration.
Creating custom configurations currently requires significant technical knowledge and will not be accessible to all users.
The customization process, detailed in Creating custom configurations, requires comfort editing JSON
files, generating SVG
image files, and using GitHub Actions or installing and using node
packages via the command line.
Each of the categories you include in your configuration needs to be assigned an icon, or a small graphic to display to users when selecting a category. You can assign the same icon to various cateogries, or each category can have it's own icon.
Examples of the icon files from our default configuration can be found here.
Though creating the .svg
icon files requires some knowledge of image editing tools, sketching and brainstorming ideas for icons can be a great way to involve community members and project participants who may not have technical skills. With paper and pencils, groups can come up with ideas for icons to represent each category in your project.
If you're not up for designing your own icon images, there are libraries of images online with Creative Commons licenses that you can draw from.
Icons are displayed as very small images in Mapeo Mobile (24x24px) and Mapeo Desktop (100x100px). Very simple designs with minimal detail will render more clearly to users.
When thinking about size and scale, imagine drawing your icons with a marker on a dime.
Bold and solid-color lines and shapes will be most clearly visible.
Once you've settled on the design or concept for your icons, you'll need to generate .svg
files required to include as part of the Coding configuration process.
To do so, you can use our online Mapeo Icons Generator, here.
Or, jump to Creating and exporting SVG files using Adobe Illustrator or Creating and exporting SVG files using Inkscape for technical guidelines in generating your own suitable SVG files.
If you do not have skills to prepare the digital icon files, paper sketches can be passed off to someone with technical skills to complete the steps of generating icon files, outlined in Coding configuration.
Once you've settled on the design or concept for your icons, you'll need to generate .svg
files for each one to be saved in the icons directory. Icons should be created as 100x100 pixel graphics that are clear when viewing at 100%.
We have also documented two workflows to generate Mapeo-compatible .svg
files using software, one using a commercial product (Adobe Illustrator) and another using a open-source product (Inkscape).
Icons need to be read by MAPEO in two sizes: 100 pixels and 24 pixels. For that reason there is a specific file naming convention:
icon-name-100px.svg
icon-name-24px.svg
Each icon can be duplicated and renamed so that there is one of each size. They are opened and read by the .json
files in the presets folder. Verify that name
is correctly entered where needed (more on this in the next section). The build script will process the pixel size suffix.
To begin translating, visit the project page for the area you would like to translate.
On the project home page you can view all languages currently available for the project and how complete translations are.
If the language you wish to translate is not available on the project home page, contact the Project Owner (listed on the bottom right of the page) to request an addition to the list.
To start translating, create an account with Crowdin, visit the relevant project home page, and select the target language. Click on Translate All to bring up all relevant text strings.
For each category in your configuration, you can include one or more structured data fields (like a mini form or questionnaire) that users can optionally fill out when creating a new observation or map element with that category. Details fields can be text fields (type in your own answer) or multiple choice (select one or select many from a set of pre-defined answers).
Details field screen displayed during data collection with Mapeo Mobile:
When planning your data structure, you should think through which (if any) details fields you would like to include for each category. The same details field can be used for many categories.
For each details field you would like to include, you'll need to define the following:
Label The primary text to be displayed to users ("Name" in the above image).
Placeholder A hint or subtext that can clarify the field to users or provide guidance on how to use it ("Common name of this place" in the above image).
Field type How users will be able to enter information for the field or question.
Text
or type in your own answer (Pictured in the image above)
Select one
from a list of options
Select multiple
from a list of options
Options
For Select one
and Select multiple
fields, you will need to define a list of possible answers to display.
It can be very challenging for users to type in detailed information when collecting data in the field. Users may be under significant stress, in risky situations, or interacting with the Mapeo screen in bright sun or rain. When creating Text
fields, keep in mind the conditions users will be facing and have reasonable expectations for the amount of detail and work required to fill out your details fields.
If there are a consistent set of answers you can anticipate for a field or question, it can be much faster or easier for users to select from a list as part of a Select one
or Select multiple
field. Please note that there is no automatic option for typing in information for "Other" or an option not included in the list.
It may be very clear to you when authoring your configuration what each details field means or intends to communicate. Keep in mind, however, who will be collecting data as part of your project and how they might read or interpret each field. Very clear and explicit language can go a long way towards ensuring your configuration is used as intended.
Mapeo Desktop currently allows you to filter observations by options in Select one
fields. To filter by options in Select multiple
or Text fields
, you will need to export your data and view it in another software tool.
A common workflow for generating Mapeo icons is to find photos or other raster images, and turn them into vector images, simplifying them until they will render well at a small size. In Adobe Illustrator, this can be done using the Image Trace
tool.
In Inkscape, this can be done using the Trace Bitmap
tool found in the Path menu. There are some options to manipulate like Smoothing corners, Optimizing corners, and setting the number of colors.
.svg
files with the right size and Viewbox in Document PropertiesOnce you have a vector image that is to your satisfaction (and in a square format), you need to set the correct width & height and Viewbox size before saving the .svg
file. You can do this in Document Properties
(File menu).
First, set the Display units
to pixels (px). This dropdown is located at the very top of the Document Properties menu.
Locate the "Custom Size" and "Scale" boxes in Document Properties.
First, you may need to set the unit of measurement for the Custom size, if it is not in pixels. If Units
is in a format like milimeters (mm), change this to px.
Set the Width
and Height
to 100 each.
Next, the Viewbox needs to be set to 100 as well. The easiest way to do this — once you've set the Display units and Custom size units to pixels — is to set the Scale x
to 1. It should copy over the Width and Height values from the Custom Size to the Viewbox. If that didn't do the trick, manually enter 100 for both Width
and Height
here.
Once you've done this, you may need to resize the art to match the full size of the Viewbox:
The easiest way to do this is to use the sizing and placement parameters right above the Viewbox, as shown in the screenshot above. Set W
and H
to 100 (px), and make sure X
and Y
are set to 0 (px). The image will then fill the entire Viewbox:
You can now save the .svg
file by going to File → Save / Save As / Save A Copy.
If you want to verify that the parameters in your .svg
file are correct, open it in a text editor like Visual Studio Code or Notepad++.
It should have an initial <svg>
tag with width and height set to 100, and viewBox set to "0 0 100 100."
After some tags like <defs>
, <sodipodi:namedview>
, <metadata>
, which don't matter for the purposes of creating icons for Mapeo, you should see tags like <g>
with layer properties, and a series of <path>
with vertices and style properties, which constitute your vectors.
If your .svg
file looks like this, the Mapeo configurations builder script should process your icons just fine.
.svg
files with the right propertiesWhen you're ready to export a vector graphic file into a Mapeo-compatible .svg
file format, the process is as follows:
On the Adobe Illustrator top menu, click on File and then select Export, followed by Export As.
Ensure that Use Artboards is checked.
Save your .svg
file in the correct directory (icons
for Mapeo configurations) and with your desired filename, and click Export.
In the following window, ensure that the following properties are set, and then click OK:
presets
directory, customize the .json
filesIn the presets directory, each .json
file needs:
icon
must mach the name of an icon in the icons
folder - use prefix only, excluding the size refernce and file extension (eg. for fishing-24px.svg/fishing-100px.svg
use fishing
).
name
will be the human-readable label shown to the user
geometry
must be an array of point
,area
, and/or line
(All categories for use in Mapeo Mobile must include point
.)
sort
(optional) is an integer that will determine the order in which categories are displayed on the Categories screen of Mapeo Mobile. If no sort
is included, categories will be listed alphabetically by name
.
an array of fields
(optional) which should match the key
created in the fields directory. Fields will be displayed to users in the order they are listed in the fields
array.
fishing-site.json
):Compiling your configuration into a .mapeosettings
file is the final step for testing and using your configuration in Mapeo Mobile and Desktop.
Building a configuration can be done in two ways:
The defaults.json
file is currently used by Mapeo Desktop to determine which categories (presets) to list for each type of map geometry (point
, line
, area
).
Before building your configuration, ensure that defaults.json
includes an array of presets for each geometry that corresponds to the geometries you've listed in your preset files.
defaults.json
file:fields
directory customize the .json
filesEach .json
file in the fields directory needs a key
, type
, label
, and placeholder.
type
can be one of select_multiple
, select_one
, or text
.
For select_one
and select_multiple
fields, you will need to define an array of answer options.
name.json
):sample-type.json
):Categories list with icons in Mapeo Mobile (using the default configuration):
To review key information on designing icons, see .
To generate .svg
icons for Mapeo, there is an online Mapeo Icons Generator tool accessible .
Mapeo aims to be accessible to a wide range of communities in their native languages, and to facilitate the process of translating the app and the into new languages as needed.
While currently requires significant technical knowledge, the process of translating Mapeo and the default configuration into a new local language can be an easier way to customize the tool for use in your project.
Translations for Mapeo are handled through the platform. It is free to create an account on Crowdin and anyone can contribute translations to Mapeo for new or existing languages.
Text and titles for screens and buttons in the mobile app
Text and titles for screens and buttons in the dekstop app
Names of data collection categories, and details fields
All information you define for details fields will be formatted in JSON
in the process, detailed in the following section.
If you are not comfortable working with JSON, this information can be be passed off to someone with technical skills to complete the steps in .
is a free and open-source vector graphics editor used to create vector images, primarily in Scalable Vector Graphics (.svg
) format. Inkscape is an alternative to the commercial software Adobe Illustrator, and can be used to generate .svg
files that work in Mapeo.
Your .svg
file should now be ready to be used by Mapeo. See for more information on how to name the files and where to place them in the configuration directory.
is a vector graphics editor and design program developed by Adobe Inc. Although it is a commercial, licensed product, it is very commonly used to put together vector graphics, and many users utilize this tool for creating icons for Mapeo as well.
Your .svg
file should now be ready to be used by Mapeo. See for more information on how to name the files and where to place them in the configuration directory.
To review key information on defining categories, see .
color
(optional) determines the color of observation dots on the map. (Dots fall back to orange if no color is defined.) Value can be a hex code, CSS color name or any string supported by .
(with Node.js and mapeo-settings-builder)
To review key information on defining details fields, see .
The package.json
file stores the name and version information users will see in Mapeo when using the configuration.
Edit the name
and version
properties when creating a new configuration. Additional information on incrementing versions will be covered in Building configuration file.
You can also add description
, author
, and license
information to this file but these properties will not be rendered in the Mapeo interface.
package.json
file:In the metadata.json
file in your Mapeo configuration, you can include a projectKey
, which is a random cryptographic string of characters to prevent unwanted devices from getting access to the data.
Once a Mapeo Mobile or Mapeo Desktop device has imported a configuration with a project key, it can only sync with another Mapeo Mobile or Mapeo Desktop device that has the same project key.
You can edit the project key (for example, if you want to make first 4 characters identifiable to a project) but it can only contain letters a-f
and numbers 0-9
.
It can also only be 64 characters long -- no more, no less.
To create a projectKey
, first open the Terminal.
For instructions on how to install mapeo-settings-builder, see Building configuration file Via the command line.
Copy and paste the following command into the terminal
You'll see something like this (but with x replaced with real characters and numbers)
Copy this string and add it to the metadata.json
file so it looks like this:
Notice that there are double quotes "
around each value.
Once you've compiled your custom configuration, you will have a .mapeosettings
file that can be imported into Mapeo Mobile and Desktop for testing and use.
.mapeosettings
file?A .mapeosettings
file is a tar file, similar to a zip file. For debugging purposes you can see the contents of the file by changing the file extension to .tar
and using any application that can extract tar files.
For instructions on how to import a configuration file (.mapeosettings
) into Mapeo, see:
Importing configurations into Mapeo Mobile
Importing configurations to Mapeo Desktop
It's worthwhile to thoroughly kick the tires of your new configuration prior to introducing it into your project and beginning formal data collection.
Icons Do icons render clearly? Check how icons appear, especially in Mapeo Mobile on devices with smaller screens.
Categories
Do categories appear in a logical order on the Categories screen of Mapeo Mobile? Changes can be made via the sort
property in Creating categories.
Details fields
Are text labels and placeholders easy to understand? Do details fields appear in a logical order? Fields will be displayed to users in the order they are listed in the fields
array in Creating categories.
Colors
If you added color
to category map markers, are they distinguishable from one another and visible on your map background?
Name and version Does the name and version of your configuration appear as desired on the Project configuration screen of Mapeo Mobile or the Synchronize screen of Mapeo Desktop?
Changes can easily be made to your configuration via steps in the Coding configurationsection. We often test, modify, recompile and retest several times before releasing a new config version.
As noted in Planning configuration & data structure, configurations can and often will evolve over time. As you begin collecting data, you will likely find categories, details fields and options you would like to add or modify.
Unlike some other survey or data collection tools, Mapeo allows a lot of flexibility for changing configurations over time and does not require that the database be wiped when changes are made. While changes to icons or color
, name
, label
, or placeholder
fields will be minor, more significant modifications like removing a category will impact how existing data is displayed in Mapeo and data exports. Regardless of these changes, no previous data will be lost or unviewable.
We are currently working on a new user interface to simplify the process of generating and adding custom background maps to Mapeo. This page covers the generation of custom map files for both for the current (non-experimental) map server AND for the new experimental Background maps feature in Mapeo Mobile.
For creating custom background maps that work with the current (non-experimental) map server, you can view documentation of the existing process here.
For instructions on how to add these maps to Mapeo, see: Adding custom background maps to Mapeo Mobile Adding custom background maps to Mapeo Desktop
For generating map files in .mbtiles
format to test out the new experimental Mapeo Mobile Background Maps feature, see here.
For instructions on how to add these maps to Mapeo, see: Background Maps
Mapeo is built with JavaScript programming language. To get started, you'll need to install Node.js development environment. If you already have Node.js installed you can skip this section.
You need to be at least on Node.js version 8 (or higher) for the mapeo-settings-builder to work properly. Head over to Node.js download page and select installer for your operating system.
Alternatively you can also use NVM (Node Version Manager) to install and manage multiple versions of Node.js on your computer.
Then close terminal and open again
If you are using Windows Subsystem for Linux (WSL) to build a configuration, you need to install some dependencies for puppeteer.
https://docs.npmjs.com/cli/install
You'll see output on the terminal, but this is OK
If your computer is ready to create configurations, type
You should see output that looks something like
Now you're ready to move to build your configuration!
Type, 'cd`, then a space, then drag and drop the folder where the prepared assets are and press enter. It will look something like this
You will then be ready to run scripts directly in the folder.
This -s tells npm to be silent, so that you only see errors that are meaningful to you.
You will see something like the following output. Errors will be highlighted in RED with hopefully some helpful description so that you can remedy the issue.
You'll also see a .mapeosettings
file inside of the build
directory.
A .mapeosettings
file is a tar file, similar to a zip file. You can see the contents of the file by changing the file extension to .tar
and using any application that can extract tar files (such as 7zip, mentioned above).
Type the following into the terminal
You need to be at least on Node version 8 for the mapeo-settings-builder to work properly. If you need help, review the 'Preparing Computer' section and ensure you're on the latest version of mapeo-settings-builder.
You also may want to delete node_modules and install updated versions of the dependencies.
In Mac or Linux, in the terminal:
If you're having more issues, please open an issue on the GitHub repository or e-mail our support hotline.
It's important to increment the version when releasing new changes to your configuration. When you are ready to release a new version, you can use standard-version in the command line to automatically increment your config version and update the CHANGELOG.md
file in your repository.
For more on versions with standard-version, see #use-conventional-commit-messages-to-increment-your-configuration-version
Generating custom background maps currently requires significant technical knowledge and will not be accessible to all users.
mbtiles
format for the new Background Maps featureFor creating custom background maps that work with the current (non-experimental) map server, you can view documentation of the existing process here.
Mapeo Mobile 5.5.0 introduces a new Map Manager user interface for importing and managing multiple background maps. The Background Maps feature is currently experimental and needs to be activated in Experiments; once that has been done, Mapeo Mobile will start to use the new user interface. To find out more about the new feature, see Background Maps.
The Background Maps feature comes with a new map server that uses a tile format called mbtiles
. This is a different format than what Mapeo was using before, so if you've added your own custom map tiles (either in .asar
or in a directory format), they will not work with the new map server. You will need to convert these to mbtiles
, or make new tiles in the mbtiles
format. This applies to both raster and vector map tiles.
Note: the Background Maps map server is able to load both raster and vector tiles; however, the experimental version can only import an unstyled vector mbtiles
file. This means that the geometries in your mbtiles
map tiles can be shown as a background map, but instead of being styled by means a style.json
file, the Map Manager will use randomized colors to visualize the different geometries.
In future releases of Mapeo, we will make it possible to add a vector map style as well.
mbtiles
using QGISOne easy and free way to have access to use mbtiles
with the new Background Maps feature, which does not require using any command line tools or scripts, is to generate them using QGIS.
QGIS is a free and open-source cross-platform desktop geographic information system application that supports viewing, editing, printing, and analysis of geospatial data. It is often used in tandem with Mapeo; for example, once a lot of data has already been collected, and the next step is to visualize that data or create cartographic maps.
QGIS has extensive documentation for use of the tool, accessible at https://docs.qgis.org/.
QGIS can also be used to generate both raster and vector mbtiles
using an easy user interface.
First, ensure that you have some map data loaded on your QGIS map canvas. This can be either vector data (such as Esri shapefiles) or raster data, such as satellite imagery or XYZ tiles loaded through a source on the internet.
In what follows, we will be creating raster mbtiles
using XYZ tiles (raster) from Bing maps, loaded through the internet. At the end of this section, some information on generating vector mbtiles
is provided.
This page has guidance on how to add a number of different XYZ tile sources to QGIS, including Bing maps, OpenStreetMaps, Google Terrain, and more.
Next, open the Processing menu and select Toolbox. Search for mbtiles in the search box of the sidebar that opens up.
In what follows, we are going to generate Raster mbtiles
. However, the process is the same if you have Vector data to generate as mbtiles
.
Double click on Generate XYZ Tiles and enter the following values in the modal box that opens up. Leave all of the other values (such as DPI, metatile size) be, there is no need to change these.
Extent: This is the extent at which your map tiles will be downloaded. At lower zoom levels, it will actually exceed this extent as it will download very large areas as one tile, which intersect with that extent; but as you get to higher zoom levels, only map tiles within that extent will be downloaded. This field takes four coordinates, and the easiest way to set them is to either use the current map canvas extent, or to drawn them directory on the map. You could also use a vector geometry to set the coordinates.
Minimum zoom: Best practice is to set this to 0, which is the whole world. Lower zoom levels do not take up much space at all, and it's a good user experience to be able to see more of the world at lower levels.
Maximum zoom: As with all background map tiles, this is an important thing to get right, and there are trade-offs between level of detail (zoom level) and file size. Each zoom level increases your mbtiles
file size by 4. It is recommended to do some calculations on how big your file will be in advance, for example using Mapbox's offline tile estimator tool.
It can also be handy to consider OpenStreetMap's guide on Zoom Levels for considering an optimal zoom level for your map data. Depending on the m / pixel of your data, you may not need to go very high. For example, PlanetScope data from Planet is only 3m in resolution, and so using either zoom level 13 or 14 is sufficient to capture the full detail of the imagery. This will also depend on your use case, and what kind of detail is helpful for your mapping scenario.
Tile format: It is recommended to change this to JPG because JPG files take up less space.
Output: Here, you want to define the path and name of your mbtiles
file.
When you are finished inputting the values, you can click Run at the bottom, and the tile generation script should commence. Depending on your extent and maximum zoom level, it may take quite a while, but you should see at least the first zoom levels (0 to 8 or so) be generated rather quickly in the Log tab which opens up automatically when you clicked Run.
When the process is finished, you should see messaging that the "Algorithm 'Generate XYZ tiles (MBTiles)' finished," and you should find your mbtiles
file in the directory that you specified.
For generating vector mbtiles, the process is even more straightforward. The only thing you need to set in the Write Vector Tiles (MBTiles) are minimum zoom level and maximum zoom level; and, you need to select the vector input layers on your map canvas that you want to generate tiles from. For vector tiles, extent is optional. The other thing worth adding is Metadata: name. Your background map will inherit this name when added to Mapeo, so it will be good to provide a specific name to distinguish it from other background maps.
mbtiles
formatThis workflow involves running command-line tools such as Python and Node. While it's possible to follow this workflow without familiarity of these tools, you should at least be familiar with the basics of working in a Unix terminal. You may also encounter difficulties that require additional troubleshooting. Some technical experience is therefore recommended.
If you have existing map tiles in asar
or directory (xyz
) format, there is a command-line tool called mbutil you can use to convert those to mbtiles
. The workflow for using this tool is as follows.
Make sure you have Python installed (ideally 3, but 2 works too).
You need to have npm installed if your vector tiles are in a .vector.pbf
format.
First, ensure that your tiles are in xyz
format. If they are still compressed as an asar
file, first unpack the file through the command:
asar extract [filename].asar [directory name]
Navigate to the root of the tile directory in the terminal:
cd path/to/directory
Identify what format your tiles are in by opening up one of the zoom level directories (e.g. 0
, 1
, 2
...) and then going one directory deeper, until you see files ending in pbf
.
If your files end in .pbf
, you may proceed to step 4.
If your files end in .vector.pbf
, first follow to the next section #extra-step-for-vector-tiles-if-they-are-in-.vector.pbf-format on renaming .vector.pbf
to .pbf
, before proceeding to step 4.
Create a virtual Python environment. NAME_OF_ENV
can be an arbitrary name.
python3 -m venv NAME_OF_ENV
Activate the virtual environment. You need to run this whenever working in this project. This ensures dependencies and other project-specific tooling are properly referenced.
source ./NAME_OF_ENV/bin/activate
Install dependencies, which will include the mbutil tool:
python3 -m pip install -r requirements.txt
Use the installed mb-util
executable to create the mbtiles file:
./env/bin/mb-util DIRECTORY OUTPUT.mbtiles
DIRECTORY
points to the path containing the tiles directory you wish to convert. It's relative to where the command is run.
OUTPUT
can be any name that you want your mbtiles
file to be called.
See mbutil
documentation for additional relevant flags related to tile scheme, image format, etc.
When you're done, you can deactivate the virtual environment by running:
deactivate
.vector.pbf
formatIf your vector tiles end in .vector.pbf
, you need to first run a script to change the suffix to just .pbf
instead. In the future, we will make it easier to handle this when importing tiles, so you won't have to do anything. However, for now you have to use a node tool called recursive-rename
.
In the terminal, navigate to the directory containing your XYZ tile directory, and install the tool npm install recursive-rename
.
Run the following command: rename vector.pbf pbf
. This will batch rename all of the individual tile files in each of the subdirectories per zoom level (0, 1, 2, ...).
Now you are ready to use mbutil to convert the XYZ directory to mbtiles
.
For instructions on how to import your .mbtiles
file into Mapeo for use in the experimental Background Maps feature, see:
Custom background maps allow Mapeo users to incorporate a wide range of geographical datasets and relevant elements into the maps used for displaying current position and data collected. Once added to Mapeo, custom background maps are available completely offline within the application.
Creating custom background maps currently requires significant technical knowledge and will not be accessible to all users.
The first step will be to set up your configuration as a repository on github.com, with the requisite build script files that will trigger a GitHub Actions Workflow to generate your .mapeosettings
file. There are a few ways to do this.
If you do not have your own custom configuration already, and are starting from scratch:
Make sure that you have the .github/workflows
directory in your configuration repository.
If you already have your own custom configuration:
Create a repository on GitHub for your custom configuration.
Commit your existing configuration content to the repository.
Commit these files to your repository on Github.com. (Github may ask you for additional permissions to add these files, by confirming via the browser.)
NOTE: Depending on your operating system and setup, it is possible that you do not see a .github/
directory anywhere. You may need to enable viewing hidden files in your system file manager.
On MacOS, you can do so by pressing Command + Shift + . (period) in your Finder window.
Navigate to the Actions screen, and Click "I understand my workflows, go ahead and enable them."
This will bring you to a view of your Workflows. You should see a message "There are no workflow runs yet" if you just enabled Workflows for the first time. You are now ready to start building .mapeoconfig
files.
Once you have enabled Action Workflows on your configuration repository, GitHub will generate a Workflow to build a new version of your configuration every single time that you commit a change to your repository.
Once you have committed a change to your repository, and navigate to the Actions tab, you should see your commit message listed as a workflow.
You can click on your commit message to find out more about the status of your build. For example, if your build has encountered an error, there will be a log that can give you an idea of what went wrong. You can commit a change to fix the error, and return to the Actions screen to see if a new Workflow successfully bypasses the problem.
feat
: this will increase your version to 1.2.0. This commit prefix could be used for major configuration updates.
fix
: this will increase your version to 1.1.1. This commit prefix could be used for small updates like changing an icon, or adding a field to a category.
chore
: this will not increase your version. This commit prefix could be used for correcting typos or fixing errors.
You can also manually update the first number in your 1.1.0 version in your package.json
file, but Digital Democracy's convention is to only do so to indicate breaking changes. That said, you are free to choose a versioning convention that makes the most sense to you.
Navigate to the Actions tab for your GitHub repository. You should see all of your Workflows again.
On the left sidebar, click on the Build & Release link.
You should now see a box with the text "This workflow has a workflow_dispatch
event trigger" and a button Run workflow. Click the button, and then click Run workflow again in the popup that will appear.
Doing so will trigger another Workflow titled "Build and Release."
Click on the release to download the versioned .mapeosettings
file.
The current process, detailed in , requires comfort installing and using node
packages via the command line.
It is possible to build a Mapeo configuration file using GitHub Actions. This requires setting up your custom configuration directory as a repository on , adding a /.github/workflows/build.yml
script to your repository, and committing changes to that repository.
If you haven't already used GitHub, you may want to study the of how GitHub works before proceeding.
Note that since this process relies on using github.com, that you will need internet access to run the build action and download the .mapeosettings
configuration file. Hence, unlike building a configuration , this process will not work in an offline context.
You can fork or upload either the or the template to your own GitHub account. The choice you make will depend on how you will go about creating your own configuration, as detailed in .
Download either the or the , and copy over the .github
directory to the root directory of your custom configuration.
a circular check indicates that the build has completed successfully.
a yellow circle indicates that the build is in process.
a red circle with an X indicates that the build has encountered an error.
This is the same log that you would see when building a configuration .
By opening the Workflow with your commit message, you can also download a .zip
file of your configuration, which includes a temporary .mapeosettings
file. This is helpful for testing out your configuration before building a versioned file to distribute to users, as described in .
The Mapeo GitHub Actions Workflow is set up to dynamically bump the version of your configuration per each workflow. It does so using of adding feat:
, fix:
, or chore:
before your commit message. For example, if you have a configuration with version 1.1.0, the specific version bumps are as follows:
To see a few examples of configuration conventional commit messaging, see the screenshot above in , or check out the commit history on the repository.
Once you are done making changes, have tested your configuration using a temporary .mapeosettings
file (as described in ) and in accordance to the process described in , you can generate a versioned release of your configuration. The way to do so is as follows:
When that finished with a green check mark, your versioned build release will be ready. On the top navigation bar, click on Code and your release should appear under the Releases panel in the right sidebar.