Mapeo is a set of digital tools, designed to support collaborative data collection and mapping in offline environments.

There are two highly-customizable Mapeo apps that can be used together or individually, depending on your goals:

• Mapeo Mobile

• Mapeo Desktop

Mapeo Mobile and Desktop are built on top of Mapeo Core, an embedded peer-to-peer database that allows users to own their own data, directly on their devices, without the need for an internet connection or to share information with a centralized server.

Mapeo Mobile

Mapeo Mobile is a smartphone application (currently for Android only) that allows you to collect and map information. Using your phone's GPS, you can mark points on a map for your current location and add photos, notes and other details about what is happening. Information can be shared with collaborators who are using Mapeo, or with external contacts via email or other messaging apps.

Mapeo Mobile can be translated into local languages, customized to use offline maps, and tailored to collect specific types of information.

Mapeo Desktop

Mapeo Desktop is a computer application that allows you to aggregate, view and manage data collected with Mapeo Mobile. Data from Mapeo Desktop can be shared with collaborators who are using Mapeo or exported to PDF reports, CSV files, GeoJSON files or published to the web using Mapeo Webmaps.

Mapeo Desktop also offers a simple interface for adding or creating territory information for making maps. It provides a basic set of mapping features that are more accessible to new tech users than other available geographic information tools, but exporting maps requires knowledge of other software.

Like Mapeo Mobile, Mapeo Desktop can be translated into local languages, customized to use offline maps, and tailored to collect specific types of information.

Mapeo Core

Mapeo Mobile and Mapeo Desktop are both built on top of Mapeo Core to securely store the geographic data, details and media created by users. Mapeo Core is an offline-first, peer-to-peer embedded database that allows users to own their own data, directly on their devices, without the need for an internet connection or to share information with a centralized server.

Mapeo Core is built upon Hypercore, which is an append-only log of actions (create, edit, delete data). Data is secured by cryptographic proofs -- every record written has a signature that also references the signature of every previous record/row in the log -- so you can never change or edit anything already written to the log. For more on Mapeo Core and data integrity, see here.

Mapeo is a free, easy-to-use, open source set of tools for collecting and mapping information.

About this Guide

This site provides an introduction to the Mapeo tools and a collection of training & technical resources to support Mapeo users.

The site is divided into the following sections:

• Overview Basic information about the Mapeo tools

• Quick Start Guide Instructions for installing and testing Mapeo's default functionality

• Complete Reference Guide A complete collection of resources on planning & implementing projects using Mapeo and customization of the tools

Use of this guide

Open Source Development

Mapeo is a free, easy-to-use set of tools for collecting and mapping information.

Mapeo is open source software that benefits from continued feedback from our users across the world.

Key features of Mapeo

• Simple to use and learn Even if you have never used a smartphone phone before, you can learn to collect data, GPS points and photos with Mapeo Mobile in a few hours. Mapeo Desktop does require some computer skills, but has a simple interface with a limited number of features. For more complex analysis or mapping work you can export your data to other tools. The simplicity of the tools helps support wide community involvement and ownership of projects.

• Works in completely offline environments All data collected or created with Mapeo is stored directly on your device in Mapeo's embedded database, without the need for an internet connection or centralized server. Users of Mapeo Mobile and Desktop can synchronize or exchange data over a local Wi-Fi network. The data never leaves your local Wi-Fi network and does not require an internet connection. Mapeo Desktop can also exchange information via a file using a USB drive.

• Uses a peer-to-peer database All the data you collect using Mapeo is stored locally on your device, not on a server or on the internet. When you synchronize with other Mapeo users in your project, you each get a copy of the data that each person has collected, so every device ends up with a complete copy of all the data in the project.

• Highly customizable You can customize the language, maps and information you collect. You can add detailed offline maps of your area, and change the icons and questions used for data collection. Mapeo has been translated into a number of languages already and anyone can add more.

• Secure, unfalsifiable data All data collected with Mapeo has encrypted logs that can be verified for authenticity. Similar to a blockchain, data is secured by cryptographic proofs, so you can verify that no record in the log has been changed or tampered with. Private projects can be created using secure project keys which limit who one can synchronize data with.

Mapeo is currently being used by a variety of communities around the globe to support territory mapping and monitoring efforts. Below are a few examples. For more detailed case studies, partner stories and information about other tool for mapping and monitoring, check out our Earth Defenders Toolkit website.

Environmental Monitoring in Peru

Indigenous Community monitors working within ECA Amarakaeri in South East Peru are using Mapeo Mobile and Desktop as part of a co-management program of a Reserved area. Together with park rangers, they collect data on illegal gold mining and other impacts to the Reserve and use these for internal decision making and action as well as sharing with the authorities for any illegalities to be addressed.

Territory Mapping in Kenya

The Ogiek Indigenous People of Mount Elgon are using Mapeo Mobile and Desktop to map important sites on their lands as part of a historical land claim.

Ancestral Mapping in Ecuador

The Siekopai people of Northern Ecuador used Mapeo Desktop in their villages to explore satellite imagery of their ancestral lands with the elders, and document stories associated with lakes and old settlements. Watch video.

Disaster-Risk Management for Climate-Vulnerable Populations in Thailand

Village health volunteers in coastal Thailand are using Mapeo to collect data on vulnerable people, to ensure they can receive immediate and targeted help in case of natural disaster.

Mapeo's peer-to-peer database

Unlike traditional apps where all the data is stored on a central server (in the cloud or in an office), the Mapeo database is integrated into the application on your device, and every device (smartphone or computer) participating in your project can have a copy of all the data. This is called a peer-to-peer database. We made this choice so that Mapeo can work entirely offline and does not require the user to set up any database or machine for storing data.

This peer-to-peer database allows users to transfer data to other users in the field without internet, and several users with computers or smartphones can all work on the same dataset and share edits.

Main characteristics:

• Data ownership and control Data collected with Mapeo is stored directly on the devices used for data collection and can be shared with other smartphones or computers that participate in the same project. This way, the information does not exist solely on one device. No one else, not even us, has access to this data. Mapeo users are the owners of the information collected and have total control over it. In other words, your data stays in your team, in your community. To learn more about the embedded database Mapeo is built on, see the Mapeo Core section.

• Peer-to-peer data sharing All devices connected to a peer-to-peer network can have the same hierarchical position within the network. Information is shared directly between different devices using a synchronization process in which each device receives and shares data. Two Mapeo devices can sync with each other at a time, and devices must be part of the same project (ie. using same configuration) to sync with one another. All devices that synchronize end up having the same information, and changes made on one device will be reflected on the other devices after syncing.

• Requires a sync protocol We strongly encourage having a methodical synchronization protocol for devices within your project to guarantee that all data is included in the shared database and no data is lost along the way. For all the information collected in a project to be present on the different devices, it is essential to plan how, when, and where the synchronization process between devices will occur. This is especially important in projects where participants work in distant places and do not coincide with other members of their team on a regular basis.

The Quick Start Guide is intended to help you install and test the basic, out-of-the-box functionality of Mapeo in order to evaluate whether it will be a good fit. This section will not touch on all features or customization of the tools.

The Complete Reference Guide below includes critical information about how to design and implement a project using Mapeo as well as detailed guides for setup and customization of the tools. We recommend using it for starting a new initiative or as a training reference.

In the pages below you'll find a collection of resources to support in getting a Mapeo project started.

• Planning a Mapeo project

• Security & risk assessment (Coming soon)

• Creating user protocols (Coming soon)

Additional information on running trainings in Mapeo can be found in Mapeo trainings.

Welcome land defenders, community mappers, resource and impact monitors, data collectors, students, scientists - whoever you are, we hope you have enjoyed playing around with Mapeo using the Quickstart guide above.

If you think that Mapeo might be the right tool for your project, this Complete Reference Guide is designed to provide you with learning and training materials, suggested workflows, and some examples of real projects in order to help get you set up and using Mapeo in the best possible way for your needs.

There is a LOT of information in the sections below, and there are many different ways of using Mapeo. We don't expect users to make use of every Mapeo feature nor need to read every section, but we do hope that what we are providing here can help users be well informed about technical details that will impact your projects.

So you want to start collecting information, perhaps you are going to be making a map, or perhaps you want to collect evidence of impacts on your land or gather other data or information. The first question to clearly ask of yourself or your community is WHY? What is it that you hope to gain or change or learn through the project?

The more detailed an answer you can give to this question the better set up you can get; making sure anyone involved in the project is working towards the same goal and being able to determine the best methodology for meeting it.

For example, if you want to make a map – what is your map for, what impact do you want it to have for you, your team, in the world, etc. Perhaps the map is the end product, or perhaps just one step in a longer process, or maybe the main aim is building relationships, and the map is the means to bring people a focus for working together.

What if you don't know yet? Perhaps you know you want to gather data about something that interests you but are not yet sure how you are going to use it. Don't worry, you can refine your aim and build on your project as you go along and learn more.

And remember - all plans change and it is impossible to predict everything in advance. There will be unforeseen outcomes, some beneficial, some possibly challenging, of your project. However having your main goal in mind as you begin to plan your methodology and define what information you are going to collect sets you up to meet any challenges, and welcome any positive changes, in the best way.

Install

Download Mapeo Desktop from the Mapeo website and double click the file to launch the installer. For more on installation, see Installing Mapeo Desktop.

Mapeo Desktop for managing Mapeo Mobile data (Observations mode)

Observations mode in Mapeo Desktop is designed for viewing, managing and exporting data collected with Mapeo Mobile. The steps below will cover the basics for testing Observations mode.

Synchronize Mapeo Mobile data

To get started, synchronize collected data from a Mapeo Mobile device. To synchronize via Wi-Fi, as detailed below, the Mapeo Mobile and Mapeo Desktop devices must be near each other.

Connect to Wi-Fi

Enter Synchronize mode

Start synchronization

View observations

To view synchronized data, click on Observations in the Mapeo modes panel.

Map view

By default, observations are displayed as dots on a map. Click on an individual dot to view the details of that observation.

Media view

To view observations as a gallery of images, click on Media in the Toolbar above the map. Click on an individual image to view the details of that observation.

Report view

To view observations in the form of a report, click on Report in the Toolbar.

Filter observations

To look at a subset of your observations in Map, Media or Report view, use the Filter panel to select a specific data range, a subset of categories, or specific data values from details fields.

Edit observations

With the observation details open, click on a field to add or edit information. Click SAVE to save changes.

Delete observations

Export data

Data can be exported to multiple formats from Observations mode in Mapeo Desktop. Basic export instructions are included below.

• Save as PDF Report

• Export to GeoJSON, CSV, or SMART CSV

• Export as Web Map (In Complete Reference Guide)

Save as PDF Report

Export to GeoJSON, CSV, or SMART CSV

Select Export Observations... then select the desired data format and options in the Export Observations pop-up window. Click SAVE to name the export file and choose the location on your computer where it will be saved.

Install

To install Mapeo Mobile on your Android device, download the latest version on Google Play​. ​You can also download the app as an APK and install it manually on your phone. ​For more on installation, see Installing Mapeo Mobile.

Collect data

You collect data with Mapeo Mobile in the form of observations. An observation is based on a geographic location (a point on the map) and can have associated photos, notes and details.

View observations

Tap on an observation from the map or list to view its details.

Edit an observation

Share data externally

Delete an observation

Synchronize data

Mapeo Mobile allows you to synchronize data with other Mapeo users that are participants of the same project. During synchronization, ALL data from one device will be sent to the other device and vice versa. For more on synchronization, see: Peer-to-peer & Mapeo sync.

To synchronize data between 2 Mapeo Mobile devices that are near each other:

1. Connect both devices to the same Wi-Fi network. (You do not need to have an internet connection.)

3. On the Synchronize screen, identify the device you wish to synchronize with in the list and tap the Sync button beside its name.

4. Keep the Synchronize screen open on both devices until the synchronization has completed.

You may be keen to jump in and get started with data collection, however spending a bit of time upfront thinking through how the project will run, the methodology, team set-up, logistics of gathering data, and how the data collected or created with Mapeo will be used can save you a lot of time and avoid problems and issues later on.

This guide does not aim to give you a blueprint of how to run your project. There are so many different uses of Mapeo, some of these we (Digital Democracy) can imagine, some of them we can't, and each one has its own particular needs, priorities and local contexts. What works in one place might need to be set up very differently for another place, even if the desired outcome is very similar. And likewise what works somewhere at one time, might have to be adjusted for another time as local situations, politics, etc. change.

Hopefully spending time thinking through the questions below will enable you to create a process tailored to your needs and project, and give it the best possible chance of success.

We are going to run through the following questions:

Provisos

Mapeo was co-developed with community land defenders in the Amazon. We have tested, piloted and received feedback on it from people around the world using it for a variety of purposes, and we hope it can serve a wide range of needs. However it is built with the needs of land and rights defenders at its heart, and therefore this guide, and many of the materials produced for Mapeo are also built with these needs at the forefront.

In part because of its design process, and the partners with whom Digital Democracy has worked, we often refer to community and collaborative processes. Mapeo can definitely also be used by individuals, and a variety of different teams, but many of our partners are using it in local, frontline community contexts, and so the language of this guide centers them. We also understand that communities are not homogenous and mean different things in different places, and hope that you can read between the lines where necessary to extract the useful parts of this guide for whatever it means to you.

This guide draws on work from our team over the last two decades in indigenous and community land rights and defense. However indigenous and marginalized communities have been defending their land for centuries. There are many projects and initiatives from which the development of Mapeo and the methodologies suggested here have been guided, received inspiration and learned. This reference guide does not aim to provide an exhaustive list of such projects, but at the end of the guide there is a Reference Section which highlights some materials from other sources and initiatives which may be of help to you in planning your project.

All the examples included in the guide are just that, examples. We hope they are helpful and provide some context and illustration to the processes described, but are not intended to be taken and copied as 'out of the box' methodologies. As we hope this planning section will describe, context is everything, and methodology should be carefully considered and adapted to best fit the needs of the project and particular community context.

No two Mapeo projects will look the same even if they have the same aims and are using the same configuration. There are so many factors which will influence how a project is run including timeline; budget; technology; landscape; seasons; climate; culture; social and political context; etc.

Whilst we can provide some ideas here, any project should be tailored to your particular context taking into account answers to the following questions. Thinking through these questions in advance will also be useful if you ask for help to put together a mapping project from an ally or other organisation.

What is your timeline?

Is there a particular urgency for the work, a date you need to produce a map or collect data by? If there isn't an internal deadline, are there significant dates external to the project that you might want to work towards or include within your calendar (eg. visits by authorities to the area, International meetings such as COP or UN Working Groups, World Social Forums etc.).

What does the geographical landscape look like? What accessibility issues are there?

Think about what the land looks like and how you plan to travel around. Some projects might be focused on a small area in town, where people can just travel around on foot on paved roads, other projects might cover tens of thousands of hectares and require travel by river, up steep hills, into swamps etc. Perhaps there are areas you want to access that are off limits (eg. National borders or Industrial installations can have no-go zones around them, or have rules about using GPS or drones etc) Drawing a quick sketchmap of the the area you plan to work within, and marking any significant landmarks, access routes, barriers etc. can help you plan out how you or your team is going to get around and how long this will take, and help identify any challenges you might encounter ahead of time.

Do the seasons affect your work?

If you plan to collect data at a particular time of year consider how the season or climate might affect this. For example the dry / rainy seasons might impact how easily you can move around the land, and might also impact the type of data you can collect (for example travel by river might be easier in the rainy season, but travel by road or foot might be harder); likewise some operations or activities you want to map or monitor might only occur at certain times of year (eg. illegal logging is linked to seasons, as are fruiting trees and fish/animal movements).

Do you have a budget?

Do you have or need a budget, and if so how much? Do you intend to pay people to take part or is it volunteer-led? If you don't already have a budget are there parts of the work that are going to need funds such as for purchasing equipment, travelling around or for any meetings you intend to hold.

Do you have or need equipment for your project?

Mapeo Mobile works on Android phones & tablets and Mapeo Desktop on Windows/Mac/Linux operating systems. Whilst essentially you might just need one smart phone for your project (which you might already have in your back pocket!), depending upon your plan, and particularly if you are going to work with teams in complicated environments you might need to think about other equipment such as spare battery packs if you are doing multi-day trips in remote areas; usb or hard drives for backups; trekking and medical kits for teams; waterproofing for tech that might be exposed to the elements etc., large sheets of paper, marker pens and notebooks for community workshops.

See equipment list for a list of things partners we have worked with have found useful.

What is the security situation?

Unfortunately, many frontline defenders are targeted for their work, often risking their lives to defend their peoples rights, lands and futures. Please consider your own safety and that of anyone else involved in the project and take what measures you can to identify risks ahead of time and mitigate them where possible, whilst doing the work that you need to do.

For example:

• Do you need to keep team members, or the names of people interviewed or otherwise involved in the project, or would it be better to involve the media and ensure there is a spotlight on the work?

• Are there places you can avoid going to and questions can avoid asking so as to not trigger dangerous responses?

• Do your teams need some kind of backup to keep them safe, a satellite phone, tracker or civil society accompaniment?

Data security

Sometimes it is not people that are at risk but data - consider therefore if you are collecting data that could be valuable to others and how you can best keep it safe.

Information can be sensitive in other ways too: perhaps only certain members of a community normally have access to it (but still want it documented) or perhaps it is information that the community does not want to make public.

Mapeo does not make any of your data public unless you choose to share it, you can create reports or export data which is filtered to exclude sensitive places or pieces of information, and you can share information with team members without it going online.

However there are other measures you can take to protect your information if needed, creating passwords for your devices ... what else?

There are two types of data that Mapeo stores in its database located on devices.

Mapping data is meant for generating data for map making or baseline territory information. Mapeo Mapping data can only be viewed, edited and exported with Mapeo Desktop in Territory view. Data collected using Mapeo mobile of GPS devices can be used as precise references for creating new mapping objects. Mapeo mapping data It stores the following information

• Geometry: Determines if the map object is a point, a line, or an area.

• Coordinates: (specific formate?)

• Category: A user selects from a list of categories each with a predefined name, icon, predefined tags and details fields

  • Icons: Visible in Mapeo Desktop Territory when creating and viewing Mapping data.

  • Tags: These are additional values to the predefined tags packaged in each category

  • Details (optional): User filled fields that relate specifically to a category that may help with consistant quality of information

• Date time of last edit: This information is appended to each object as a log of changes that get's saved a the end of a mapping editing session for decentralized data consolidation.

Observation Data is meant to capture time based information at a specific coordinate with options to add photos and details captured in the field. Observations can only be created using Mapeo Mobile. Observation data can only be viewed, and edited in both Mapeo Mobile and Mapeo Desktop Observations, and each tool offers unique share and export options to output observation data. Mapeo Observation data stores the following information:

• Geometry: Observations are always captured as points, to replicate objective human observation when visiting a point of interest.

• Coordinates: Available in various formats for data collection. on Mapeo Mobile coordinates are captures automatically using the devices location detection hardware. Mapeo Mobile features include capturing the most precise GPS reading possible when device location is turned on. There is also a manual coordinate entry option is GPS precicion is low or unavailable. Coordinates cannot be edited after capture.

• GPS metadata: For forensic varilfication, GPS metadata including altutudem velocity and precision is in each observation captured with the devices GPS features. This information is currently not visible in the user interface.

• Category: A user selects from a list of categories each with a predefined name, icon, tags and details fields. These elements are packaged in each category and bases on common user needs. These can be customized [link]

  • Icons: Visible in Mapeo Mobile when creating observations and on observation viewing screens. Visible on Mapeo Desktop Observations in Report view

  • Tags: These are predefined tags packaged in each category. This information is currently not visible in the user interface.

  • Details (optional): User filled fields that relate specifically to a category that may help with consistant quality of information. In customized configurations add any number of questionscan be added for field surveys to collect quantitative information or evidence. Your questions can be text fields for open descriptions; select one or select multiple from a predefined list of options.

• Date time of creation: This information is fundamental to an observation and differenciates it from mapping data as time based data. In both Mapeo Mobile and Mapeo desktop observation data will displayed by Date/time of creation with newest first.

• Date time of last edit: This information is appended to each observation as a log of changes for decentralized data consolidation.

• Photos: (optional) Stil images can be captured by the Mapeo Mobile camera which automatically links the media files to the observation. [is any GPS or camera metadata attached to photos?]

It might be too early to start thinking about outputs, but if you already have a sense of what these might be then they might give some useful direction to your planning process. By output we don't mean the goal or results of your project, although these might overlap, we are referring particularly to concrete materials that result from your Mapeo project.

For example these could be:

• Printed map / maps: These might be for an external audience such as the government or a legal body, or they might be for the community itself to use for other purposes. If you are planning on creating a map then consider what information you can show on the map - perhaps you spend a long time collecting stores which then are hard to find space for, or you collect so much information that the map is hard to read.

• Data reports: You might want to produce regular reports on the data you collect, or wait until the end of your project and then produce a report with all the data or the highlights. Do your reports include quantitative data that you want to analyse and present in a particular way or is it mainly qualitative data that will need editing or compiling before presentation. Thinking about these can help you to organise your teams and data collection so that you have the data when you need it, in the right format.

• Alerts: If you are collecting evidence of something that needs fast action then having an alert system built into your methodology could help. Mapeo Mobile can export datapoints to WhatsApp and other apps so you could potentially send alerts of illegalities straight to law enforcers for immediate action.

• Interactive webmap: This could be a good output if you are hoping to build a campaign and want to share some of the project with the public or media - or even for your own community such as for an educational or storytelling resource. It also enables different kinds of information to be present than on a printed map as you can include videos and audio more easily. However it may involve a level of technical expertise or budget beyond the scope of your project, and it is definitely not the right output for every goal.

The answer to this question of who should be involved could vary wildly. Perhaps it is just you and your mobile phone, or perhaps it is going to involve thousands of people across multiple countries working together to compile a mass of data. Most of the partners we have worked with directly are somewhere in between, often a community or group of communities with a dedicated team of collaborating to collect data.

However even the projects we have partnered on directly, which might look superficially very similar, have set up their project structures in very different ways, sometimes out of need and sometimes out of preference. So here are some things to consider.

Are there any traditional or other authorities that should be consulted before you start, or who should be involved in some role? This is particularly relevant if you are collecting data from indigenous lands (your own or belonging to others) and/or might be collecting potentially sensitive data.

Who is your project accountable to and how can you ensure you meet their needs? The answer to this might be the traditional authorities mentioned above, or it could be particular sectors of your community, funders, the future generations or others. Consider how to keep them up to date with project progress if relevant and how to produce materials they will find accessible and useful.

Do different members of your community hold different knowledge that you want to ensure is represented. How can you honour and involve these people and their knowledge? Think here about women, elders and young people in particular, and how to ensure they are involved in the work and that they are not simply used to extract information from. Then depending upon the details of your project other groups might arise: traditional healers; skilled artisans; storytellers; health workers etc.

Consider the ownership of the project: If the project is meeting needs identified by your community, or collecting data intrinsic to them or their future consider how to ensure the community feels involved in the work and feels ownership over any results. Mapeo was built to try and facilitate community ownership of both projects and data by having a simple interface that could be explained to people without data collection training and people who might be non-literate or unused to computers or smartphones. Involving people at different stages of the project, including the planning phase can help increase this feeling of ownership, as can keeping the data locally, providing frequent feedback and reports back on what is happening, and creating outputs that people can use themselves or see at work.

What other stakeholders or people with interest or authority do you want to involve? Perhaps there are people who it would be useful to involve because they could help the project reach its goal such as local authorities, law enforcement, press, park rangers. Think about what role they might have in the project, whether they are consulted about things in advance or are simply informed and kept up to date with project progress. Consider too if there are people you want to keep the work and data secret from due to security or other considerations.

Who is going to collect your data? Unless yours is a solo project you are going to need to work with a team or teams of people to collect your data. This will be particularly necessary if you need to cover a large area of land, have time constraints or need different skills on your team. Think about the composition of the team and how you are going to build it - is it something people will volunteer for or will they be asked? Do you need to ensure diverse representation and if so how will you do this? Do you want to involve as many people as possible or have a small team that moves around?

What other roles do you need? If you are working with a team or teams of data collectors or mappers you are likely to need someone to coordinate them, help plan trips, collate the data they collect, analyse it and prepare any reports or outputs. This might be the role of a single coordinator, or you might need multiple ones due to the number of people involved or because of cultural or political sensitivities or the way the project ownership is set up. You might also have people involved in training, decision making, liaising with external bodies, helping with legal and communications work etc.

What skills do people need? We hope Mapeo is to learn and use, but if you are working in a team and want to collect comparable data people will need some training in how to use the app, and how to use it in the way your project needs. There might be other trainings necessary such as training in basic smartphone usage if people aren't accustomed to it; training in taking good photographs that illustrate what you want to show; training in gps; drones; video; audio recording; oral history recording; GIS software etc. conflict resolution, de-escalation etc depending on the details of your project.

Create a project protocol: Writing a protocol, if possible in a collaborative manner, which lays out any different roles within the project, their relationship to the data, agreements about use and ownership of data, any payments that are being made, what will happen to equipment and data at the end of a project etc. can be a way to keep things transparent and accountable and help avoid issues during and after the work.

When you have clarified the main goal for the project, the next step is to think through carefully what data you want to collect or create. This will not just be dependent upon the final goal, but also on other factors such as the time and funding available, the security situation, and any legal guidelines. So it may be a good idea to read this section again after reading the "What are your parameters" section.

Depending on your needs and capacity you may find that the default configuration and categories that come with Mapeo do the job well enough, or you might want to set up a custom configuration with your own icons and questions tailored to your specific needs. For more on how to do this, see Creating custom configurations. Perhaps, if your project is new and you are still figuring out what is needed, you may want to start collecting data using the default configurations, and learn from that process about what categories and questions you really need.

The simple answer to the question of what information to collect is probably quite obvious from your goal, but when you dig down the answer isn't always that easy. So if you need a territory map for a land claim then you probably need to collect information about territory use, as well as the territory boundaries or limits - but exactly what information do you need, what format should it be in, how much detail do you need, etc. And if you want to collect evidence of illegal gold mining, then you may want to collect georeferenced photos and answer a series of questions about the scale and nature of any impacts found, but what is the best way of framing questions to get you the answers your community and perhaps legal team need to evaluate what is going on and how to take action, and what should you be taking photos of exactly?

Collecting data can be a time-consuming and expensive process, and can raise expectations about outcomes. So thinking this through carefully in advance will help ensure you are a) not wasting your own or others time and resources collecting information that isn't going to be useful and b) not in the situation where you realize at the end of a month-long trip that you need to go back to all the places again because you forgot to collect a crucial bit of data.

Think about the following questions to further clarify exactly what data you should be gathering and how to set up any custom configurations:

• First think about your goal and what you know of your needs. Brainstorm with any other team members or with the community about all the possible things you could collect information about, categories and questions, and then start organizing and refining.

• If possible do some research by talking to allies, or looking online to see how other similar projects were set up and what data they collected.

• Are there any rules, restrictions or guidelines that might determine the kind of information you collect and how to ensure it is usable. For example some governments/authorities might require data to be collected in a particular GPS format, or follow a particular information template, in order to be accepted or easily acted upon.

• Might the data need to be used in a legal process, if so there may be specific ways of collecting it, or additional questions you ask, which will enable it to be used more effectively. If possible get local legal advice about this, as it will differ depending on the type of data and the country you are in.

• Knowing how much information is too much. Once you start making a map or collecting information it quite fun... maybe a little too fun 🙂. If you have all the time in the world then this may not be a problem, but if people or lands are being threatened you may need to make compromises in terms limiting the data you collect to that which is urgently needed.

About background maps

Mapeo uses background maps to show users their current location in the mobile app and as a background for displaying data collected or created with Mapeo.

Mapeo's default background map

By default, when the device has access to the internet, Mapeo Mobile and Mapeo Desktop in Observations mode use a detailed background map that includes geographic elements such as rivers and mountains, as well as some political and urban elements such as borders, cities, roads, and others.

If the device is not connected to the internet, the background map shown by default is much less detailed. In Mapeo Mobile, the offline background map shows country borders and the main water bodies. In Mapeo Desktop, there is currently no default offline background map.

Online background map example:

Offline background map example:

Beyond the default background map

Mapeo offers the option to add a custom background map for use both offline and online. For more on creating and adding custom background maps, see Custom background maps.

When you install Mapeo, it comes with default options that can be used right away, without any customization. In the following pages, this section details what is automatically included with Mapeo so you can determine whether the app will meet your needs out-of-the-box.

Mapeo offers many options for customizing categories, icons, questions and background maps but the current customization process requires significant technical knowledge and will not be accessible to all users.

There are many tools and pieces of software that you could use for making maps and collecting data. Mapeo was designed to meet the needs of specific users, who:

• are collecting data in primarily offline environments

• often have limited previous experience with technology

• are working collaboratively on mapping or monitoring projects and using shared data sets

• want ownership over their data and the power to decide if and when data is shared with external actors or centralized servers

• have specific data collection requirements

• want to view and gather information in their native languages

• need a tool that is free to use

Mapeo may not be the right tool for all projects. When evaluating whether Mapeo will be a good choice, we encourage you to try out the tools (see the Quick Start Guide) and please keep in mind the following:

• Equipment requirements Mapeo Mobile is currently available for Android only. (An iOS version is in development for 2022.) Mapeo Desktop works on Windows, Mac and Linux machines. Mapeo Mobile uses Wi-Fi networks to synchronize data between devices. To synchronize data with Mapeo Mobile in offline areas, you will need a portable router (this does not require an internet connection) or a third device capable of creating a local network offline or hotspot.

• Peer-to-peer architecture The Mapeo tools are based on a peer-to-peer database, which means there is no centralized server aggregating information collected by users. Two devices that are participating in the same Mapeo project can synchronize or exchange data at a time. Synchronized devices have identical copies of the Mapeo database and can serve as backups if a device is lost or damaged. Please note that data that has not been synchronized will not have a backup. For more details on peer-to-peer architecture and syncing, see Peer-to-peer & Mapeo sync. It is important to think through in advance how the participating users or devices in your project will share information, as there are a variety of possible synchronizing patterns. For more on this, see Creating user protocols.

• Customization and required technical skills Mapeo comes with out-of-the box options that can be used right away, without any customization. To learn more about whether these default options will work for your project, see Will Mapeo work out-of-the-box for me? Mapeo was also built to be highly customizable and allow users to adapt its interface to meet the needs of specific projects. Mapeo is currently available in many languages and can easily be translated into new ones. Adapting Mapeo to use custom categories, icons, questions and background maps currently requires significant technical knowledge and will not be accessible to all users. If you believe customization will be necessary for your project, please consult the section on Customization options to determine whether your team has the required technical skills.

• Security As an offline-first, peer-to-peer set of tools, Mapeo can offer a path for data collection and exchange with fewer technological vulnerabilities than other available tools. However, the use of any technology can introduce new security concerns and risks. Before choosing to use Mapeo or other alternatives, we strongly encourage reviewing the section on Security & risk assessment.

Alternative tools

If Mapeo doesn't seem like the right fit for your needs, check out the Toolfinder on our Earth Defenders Toolkit site to learn more about other tools for territory mapping and monitoring.

• Who made Mapeo?

• Is Mapeo free to use?

• What kind of data can Mapeo collect?

• What languages is Mapeo available in?

• Is Mapeo Mobile available for iOS?

• Do I need to customize Mapeo to use it?

• How does Mapeo work offline?

• Does Mapeo use a Blockchain?

• Who will have access to my data?

• Does Mapeo collect information on users?

• What happens if Mapeo loses financial support? Will my data be inaccessible?

• Can you help me deploy Mapeo?

• How can I report bugs or problems using Mapeo?

Who made Mapeo?

Mapeo was built by Digital Democracy in close collaboration with Indigenous partners in the Amazon who are on the front lines of defending their rights and territories. Digital Democracy is a non-profit organization that works in solidarity with marginalized communities to use technology to defend their rights. For more information on Digital Democracy and our partners, visit our website.

Is Mapeo free to use?

Yes, all Mapeo tools and features are free to install and use.

What kind of data can Mapeo collect?

For more on Mapeo's default categories and details fields, see Default configuration. To learn about customizing these options, see Custom configurations.

What languages is Mapeo available in?

Mapeo is currently available in over 8 languages, including:

• English

• Spanish

• Portuguese

Mapeo can be translated into additional languages on Crowdin. For more information, see Translating Mapeo & default configurations

Is Mapeo Mobile available for iOS?

Mapeo Mobile is currently available for Android only. It is on our roadmap to release a version for iOS in the future.

Do I need to customize Mapeo to use it?

When you install Mapeo, it comes with default options that can be used right away, without any customization. To learn more about whether these options will work for you, see Will Mapeo work out-of-the-box for me?

Some projects may require customization of data fields or background maps in order to best meet the needs of the project or context. Customization currently requires some technical skills. For more on customization options and technical requirements, see Customization options.

How does Mapeo work offline?

Mapeo is built on an embedded peer-to-peer database, so all data collected with Mapeo is stored directly on your device, with no need for an internet connection or centralized server. Users of Mapeo Mobile and Mapeo Desktop can synchronize or exchange data over a local Wi-Fi network. The data never leaves your local Wi-Fi network and does not require an internet connection. Mapeo Desktop can also exchange information via a synchronization file using a USB drive.

For more on how Mapeo stores and synchronizes data, see Peer-to-peer & Mapeo sync.

Does Mapeo use a Blockchain?

Mapeo uses secure peer-to-peer technology with a distributed ledger, which does not include a public blockchain or consensus.

Public blockchains are designed for a scenario where public transactions must be mediated between participants which are all potentially malicious. These “trustless” transactions are the key assumption of a blockchain that distinguishes it from peer-to-peer technology.

Applications like Mapeo assume that data is managed by the community generating it - and some of that data may never be publicly accessible. Mapeo's approach, in contrast, creates a closed group, where data creators are also data stewards, managing their own data and controlling who has access. We take security seriously and maintain protections from third-party attacks such as targeted hacks and surveillance by third-parties. For users of Mapeo, privacy is critical for protecting their ancestral knowledge and environmental monitoring information until it’s ready to be shared with trusted partners.

For more information, read this blog post and this paper from Article 19 about why blockchain is not a recommended tool for human rights and freedom of expression.

Who will have access to my data?

Mapeo was designed to be an offline-first set of tools that centers data sovereignty for its users. That means that the data you collect with Mapeo will only exist on the device it is collected or created with until you choose to share it with other Mapeo project participants or external actors. The data you create will never be stored on external servers or shared with app maintainers or other actors, unless you choose to send it or enable and use Web sync options through Mapeo.

Does Mapeo collect information on users?

Mapeo collects only basic, anonymized statistics for debugging, designing and understanding to what extent the applications are being used.

What happens if Mapeo loses financial support? Will my data be inaccessible?

Mapeo is built with long-term sustainability as a focus. This goes beyond financial sustainability - we ensure that no single entity or technology is responsible for data storage or access.

Mapeo does not lock your data into a particular data format. You can easily move your data around, and it is kept in its original form. Mapeo Desktop can export data to SMART, Shapefile, CSV, and GeoJSON. You'll never be locked into using Mapeo software. For more on export options, see Exporting data & sharing externally.

Can you help me deploy Mapeo?

There is a community of active users and maintainers of Mapeo that participate in our public chat channel on Discord and on our Earth Defenders Toolkit Forum. We encourage you to consult these spaces for additional tips and ideas on how people are using Mapeo.

Digital Democracy's core team is very small and we have limited capacity to provide direct accompaniment for implementing Mapeo outside of our existing partnerships. In some cases we are able to offer support. To read more about the way we work with partners and different levels of support, see here.

How can I report bugs or problems using Mapeo?

There is community of active users and maintainers of Mapeo that participate in our public chat channel on Discord. To join the conversation or seek help on technical issues, you can access the channel here.

About configurations

Mapeo uses configurations to determine which categories, icons and questions users see when they are collecting data. For each data point collected with Mapeo, users select a category to classify the point, and may answer questions or respond to prompts to provide more detail about what is being documented.

Mapeo's default configuration

When you install Mapeo, it comes with a default configuration that includes general categories and questions for territory mapping and monitoring.

Categories

The default configuration includes the following data collection categories:

Observations that do not fit these categories can always be collected using the New point category.

Questions

To review all fields included in the default configuration, install Mapeo and explore the Add Details section for each category.

Beyond the default configuration

Mapeo offers the option to create custom configurations to fit the needs of specific projects. For more information on customization, see Custom configurations.

About custom configurations

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. ​

Creating custom configurations

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.

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.

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 default configuration into new languages as needed.

While developing custom configurations 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.

Translation using Crowdin

Translations for Mapeo are handled through the Crowdin platform. It is free to create an account on Crowdin and anyone can contribute translations to Mapeo for new or existing languages.

To begin translating, visit the project page for the area you would like to translate.

• Mapeo Mobile Text and titles for screens and buttons in the mobile app

• Mapeo Desktop Text and titles for screens and buttons in the dekstop app

• Mapeo's default configuration Names of data collection categories, and details fields

Viewing available languages

On the project home page you can view all languages currently available for the project and how complete translations are.

Adding a new language

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.

Contributing translations

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.

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)

What are categories?

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.

How categories are viewed in Mapeo

Categories list in the Filters panel of Mapeo Desktop (using the default configuration):

Considerations when defining categories

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.

When defining categories, keep in mind the following:

• 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.

Generating category files

All information you define for categories will be formatted in JSON in the Coding configuration process, detailed in the following section.

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.

Data structure

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:

Documenting data structure

Overview of the process

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.

What is an icon?

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.

How icons are viewed in Mapeo

Examples of the icon files from our default configuration can be found here.

Considerations when designing icons

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.

When designing icons, keep in mind the following:

• 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.

Generating icon files

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.

What are details fields?

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).

How details fields are viewed in Mapeo

Details field screen displayed during data collection with Mapeo Mobile:

Considerations when defining details fields

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.

When defining details fields, keep in mind the following:

• 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.

Generating details field files

All information you define for details fields will be formatted in JSON in the Coding configuration process, detailed in the following section.

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.

Configuration folder structure

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

Prepare folder structure

Using the file explorer

1. Download the default configuration repository or empty configuration repository.

2. Unzip the contents to a new folder using a program like 7zip.

3. Rename the folder from "mapeo-default-settings" to use your own project name, "mapeo-config-projectname".

Using the terminal (linux and mac)

wget https://github.com/digidem/mapeo-default-settings/archive/v2.1.0.zip 
unzip v2.1.0.zip 
mv mapeo-default-settings-v2.1.0 mapeo-settings-myprojectname

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%.

To generate .svg icons for Mapeo, there is an online Mapeo Icons Generator tool accessible here.

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).

• Creating and exporting SVG files using Adobe Illustrator

• Creating and exporting SVG files using Inkscape

Naming icon files

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.

Additional resources

• Troubleshooting SVG image errors in Mapbox Studio

In the presets directory, customize the .json files

In 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.

• 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 validate-color.

Example preset file (fishing-site.json):

{
    "icon": "fishing",
    "name": "Fishing Site",
    "sort": 10,
    "color": "#13D5CF",
    "fields": [
        "name"
    ],
    "geometry": [
        "point",
        "area"
    ]
}

In fields directory customize the .json files

Each .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.

Example fields file (name.json):

{
    "key": "name",
    "type": "text",
    "label": "Name",
    "placeholder": "Common name of this place"
}

Example fields file (sample-type.json):

{
    "key": "sample-type",
    "type": "select_one",
    "label": "Sample type",
    "placeholder": "Select the type of testing",
    "options": [
    	"Meteorological",
    	"Air",
    	"Soil",
    	"Water",
    	"Mineral",
        "Forestry/vegetation",
    	"Other"
	]
}

Adobe Illustrator 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.

Exporting .svg files with the right properties

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

Your .svg file should now be ready to be used by Mapeo. See Naming icon files for more information on how to name the files and where to place them in the configuration directory.

Inkscape 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.

Using Inkscape to vectorize images

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.

Saving .svg files with the right size and Viewbox in Document Properties

Once 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.

Your .svg file should now be ready to be used by Mapeo. See Naming icon files for more information on how to name the files and where to place them in the configuration directory.

Verify that your SVG file is built correctly

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.

Additional resources

• Troubleshooting SVG image errors in Mapbox Studio

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.

Example package.json file:

{
  "name": "project-config",
  "version": "1.0.0",
  "description": "Mapeo configuration",
  "dependencies": {
    "mapeo-settings-builder": "^3.0.0",
    "mkdirp": "^0.5.1"
  },
  "devDependencies": {},
  "scripts": {
    "build": "basename=\"${npm_package_name}-v${npm_package_version}\"; mkdirp build/${basename}; mapeo-settings build -l 'en' -o build/${basename}.mapeosettings && tar -C \"build/${basename}\" -xf build/${basename}.mapeosettings",
    "test": "mapeo-settings lint"
  },
  "author": "Your Name",
  "license": "UNLICENSED",
  "private": true
}

What is a Project Key?

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.

Creating a Project Key

To create a projectKey, first open the Terminal.

Using mapeo-settings-builder

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.

It is possible to build a Mapeo configuration file using GitHub Actions. This requires setting up your custom configuration directory as a repository on Github.com, adding a /.github/workflows/build.yml script to your repository, and committing changes to that repository.

Setting up a configuration repository on GitHub

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:

1. You can fork or upload either the Mapeo Default Configuration or the Empty Mapeo Configuration 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 Planning configuration & data structure.

2. Make sure that you have the .github/workflows directory in your configuration repository.

If you already have your own custom configuration:

1. Create a repository on GitHub for your custom configuration.

2. Commit your existing configuration content to the repository.

3. Download either the Mapeo Default Configuration or the Empty Mapeo Configuration, and copy over the .github directory to the root directory of your custom configuration.

4. 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.)

Getting ready to build

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.

How it works

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.

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 Testing and iterating.

Use conventional commit messages to increment your configuration version

The Mapeo GitHub Actions Workflow is set up to dynamically bump the version of your configuration per each workflow. It does so using conventional commit messaging 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:

• 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.

Compile a final, versioned release of your configuration

Once you are done making changes, have tested your configuration using a temporary .mapeosettings file (as described in How it works) and in accordance to the process described in Testing and iterating, you can generate a versioned release of your configuration. The way to do so is as follows:

• 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 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.

Example defaults.json file:

{
    "area": [
        "area", 
        "airstrip",
        "animal",
        "community",
        "fishing-site",
        "gathering-site",
        "hills",
        "hunting-site",
        "lake",
        "palm",
        "special-site",
        "swidden",
        "threat",
        "tree",
        "plant"
    ],
    "line": [
	"line",
	"boundary-line",
	"river",
	"path",
	"stream",
	"threat"
    ],
    "point": [
        "point",
        "airstrip",
        "animal",
        "boundary-line",
        "building",
        "camp",
        "clay",
        "community",
        "fishing-site",
        "gathering-site",
        "house",
        "hunting-site",
        "palm",
        "cave",
        "plant",
        "salt-lick",
        "waterfall",
        "special-site",
        "swidden",
        "threat",
        "tree"
    ],
    "vertex": [
    ],
    "relation": [
    ]
}

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:

• Via the command line(with Node.js and mapeo-settings-builder)

• Using GitHub Actions

Prepare computer for building the configuration

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.

Install nvm

touch ~/.bash_profile

curl -o- <https://raw.githubusercontent.com/creationix/nvm/v0.32.1/install.sh> | bash

Then close terminal and open again

Install homebrew (macOS)

http://brew.sh/

Install puppeteer dependencies (Windows Subsystem for Linux)

If you are using Windows Subsystem for Linux (WSL) to build a configuration, you need to install some dependencies for puppeteer.

sudo apt install libgtk-3-dev libnotify-dev libgconf-2-4 libnss3 libxss1 libasound2

Install npm

https://docs.npmjs.com/cli/install

Install and use node 12

nvm install 12
nvm alias default 12

Install Mapeo Settings Builder

You'll see output on the terminal, but this is OK

npm install -g mapeo-settings-builder

Is your computer ready?

If your computer is ready to create configurations, type

mapeo-settings-builder

You should see output that looks something like

→ Using version x.x.x of mapeo-settings-builder
Usage: mapeo-settings-builder [options] [command]

Options:
  -h, --help                   display help for command

Commands:
  build [options] [sourceDir]  Build config from presets in current working dir
  lint [sourceDir]             Lint preset files for errors
  extract-messages [options]   Extract messages for translation
  generate-key                 Generate a random project key
  help [command]               display help for command

Now you're ready to move to build your configuration!

Package Config Assets for MAPEO

Prep folder and build

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

cd /Users/jen/Documents/Dd_LOCAL_project-files/Dd-Tools/Mapeo/Presets/CREATION\\ LAB/Strathcona-KX-v1.0.0

You will then be ready to run scripts directly in the folder.

npm install

npm run -s build

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.

→ Using version x.x.x. of mapeo-settings-builder
! Warning: no category json files found in /home/okdistribute/node_modules/mapeo-default-settings/mapeo-default-settings-2.1.0/categories
✓ Built presets and categories (37ms)
✓ Generated svg sprite for iD (544ms)
✓ Generated png sprite for Mapbox (81ms)
✓ Generated png icons for Mapeo Mobile (607ms)
✓ Successfully created file 'build/mapeo-default-settings-v2.1.0.mapeosettings' (total 1299ms)

You'll also see a .mapeosettings file inside of the build directory.

What is a .mapeosettings file?

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).

Troubleshooting Checklist

Type the following into the terminal

node -v

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.

npm install -g mapeo-settings-builder@latest

You also may want to delete node_modules and install updated versions of the dependencies.

In Mac or Linux, in the terminal:

npm install

If you're having more issues, please open an issue on the GitHub repository or e-mail our support hotline.

Versioning

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.

About custom background maps

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

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.

Current (non-experimental) workflow

New experimental Background Maps feature

Generating custom background maps in mbtiles format for the new Background Maps feature

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.

Generating new mbtiles using QGIS

One 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 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.

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.

• 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.

Converting your existing Mapeo tiles into mbtiles format

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.

Dependencies:

• 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.

Steps to follow:

1. 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]

2. Navigate to the root of the tile directory in the terminal: cd path/to/directory

3. 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.
4. Create a virtual Python environment. NAME_OF_ENV can be an arbitrary name. python3 -m venv NAME_OF_ENV

5. 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

6. Install dependencies, which will include the mbutil tool: python3 -m pip install -r requirements.txt

7. 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.

8. When you're done, you can deactivate the virtual environment by running: deactivate

Extra step for vector tiles if they are in .vector.pbf format

If 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.

1. In the terminal, navigate to the directory containing your XYZ tile directory, and install the tool npm install recursive-rename.

2. 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, ...).

3. Now you are ready to use mbutil to convert the XYZ directory to mbtiles.

In this section, you will find all the needed resources to learn how to install and set up Mapeo Mobile:

• Installing Mapeo Mobile

• Choosing Mapeo Mobile settings

  • Language

  • GPS coordinate format

• Importing configurations into Mapeo Mobile

• Adding custom background maps to Mapeo Mobile

• Updating Mapeo Mobile

Before you start, make sure that:

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.

What is a .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.

Importing a configuration into Mapeo

For instructions on how to import a configuration file (.mapeosettings) into Mapeo, see:

Testing out your configuration

It's worthwhile to thoroughly kick the tires of your new configuration prior to introducing it into your project and beginning formal data collection.

A few things to look for when testing configurations:

• Icons Do icons render clearly? Check how icons appear, especially in Mapeo Mobile on devices with smaller screens.

• 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?

Making changes

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.

The following settings can be easily changed in Mapeo Mobile:

Language

To change the language of Mapeo Mobile:

2. On the Language screen, select the language you would like to use for Mapeo Mobile. The language of the application will change automatically.

GPS coordinate format

Mapeo Mobile supports three GPS coordinate formats: Universal Transverse Mercator (UTM), Degrees/Minutes/Seconds (DMS), and Decimal Degrees (DD).

To change the coordinate format used:

2. On the Coordinate Format screen, click on the format you would like to use and it will automatically change inside the application.

Experiments

The Experiments screen contains new, experimental features that are in ongoing development.

There are 2 ways to install Mapeo Mobile on your smartphone:

Install from Play Store

Before you start, make sure that:

• You have enough space available on your smartphone for the Mapeo application and data you will collect - we recommend that you have at least 1 GB (gigabyte) available.

To install Mapeo Mobile on your smartphone from the Google Play Store:

4. On the Mapeo Mobile screen in the Play Store application, click on Install.

5. When the installation process is complete, click on Open.

6. When Mapeo Mobile opens, you will be prompted to allow Mapeo access to your phone's camera and GPS for proper functioning of the app. After that, the Mapeo Mobile home screen will open automatically.

Install from APK file

You can install Mapeo Mobile on a smartphone that does not have an internet connection using a previously downloaded installation file (.apk).

Download the installation file

Install from APK file

1. Locate the Mapeo installation file (.apk) on the device.

2. Tap on the installation file (.apk) to open it.

3. In the pop-up window, click on INSTALL. The installation process may take several minutes.

4. Once the installation is complete, click on OPEN in the pop-up window.

5. When Mapeo Mobile opens, you will be prompted to allow Mapeo access to your phone's camera and GPS for proper functioning of the app. After that, the Mapeo Mobile home screen will open automatically.

The new Directional Arrow feature uses your smartphone’s digital compass to provide information about which direction your phone is facing. Close proximity to large metal objects or strong magnetic field can affect the precision of the compass.

If your smartphone doesn’t have a compass, the Directional Arrow may still be able to determine direction based on movement. Direction based on movement may be less accurate.

Turn on Directional Arrow

To activate the Directional Arrow feature:

2. Select Directional Arrow, then click the checkbox to Use Directional Arrow.

Peer-to-peer (P2P) App Updates is an experimental feature that allows you to share and receive newer versions of the Mapeo app by connecting to other Mapeo devices via Wi-Fi (no internet connection required).

When updating the Mapeo app version in this way, NONE of your Mapeo data (observations, configurations, or maps) is shared between devices.

To search for and share Mapeo app updates between Mapeo Mobile devices, both smartphones must:

• have the P2P App Updates feature enabled

• have Mapeo open to the Synchronize screen

• be connected to the same Wi-Fi network

Turn on the P2P App Updates feature

Check for available updates

If a newer version of the app is available from another Mapeo device on the network, the update will be automatically downloaded.

(If your device has a newer version than other devices the network, you will see the message "Sharing app updates with other devices.")

Install app update

To install the newer version of Mapeo, wait until the download completes, then tap INSTALL on the Synchronize screen.

Allow installs from Mapeo

After tapping INSTALL, you may see a security pop-up window saying that your phone is not allowed to install apps from this source.

To enable Mapeo to install updates, tap Settings in the pop-up window and toggle the switch to Allow from this source in the following Android Settings screen.

Reopen Mapeo

When the installation is complete, Mapeo will close automatically. When you re-open Mapeo, you will see an update confirmation window. Tap OK to close the window and start using the new version of Mapeo.

Mapeo Mobile 5.5.0 introduces a new Map Manager user interface for importing and managing multiple background maps. The new experimental Background Maps feature allows you to add your own custom maps and switch between multiple maps.

Turn on Background Maps

To activate the Background Maps feature:

2. Select Background Maps, then click the checkbox to Use Background Maps.

3. Click on Background Maps below Try it now and again on Background Maps to enter the map manager.

5. A progress bar indicating the file is loading will appear. This could take several minutes depending on the mbtiles file size and the phone's processing power.

Experiments

The Experiments screen within the Settings menu contains new, experimental features that are in ongoing development. They can be activated and used in their current state and will be improved and moved out of the Experiments section in future app updates.

The features currently available in Experiments are:

The following features introduce options for further layers of security to protect Mapeo data:

• App Passcode

• Obscure Passcode

App Passcode allows you

To start using a custom configuration, you'll need to import the new configuration file into Mapeo Mobile. For more on configurations, see Custom configurations.

Locate the configuration file

Download or copy the configuration file (eg. example_project.mapeosettings) onto your Android device. Note which folder the file was saved in.

Go to Settings

Import configuration file

Select Project configuration, then tap Import config.

Navigate to the folder that contains your configuration file and tap on the file.

Confirm import

Click OK on the import confirmation window and verify that the Project configuration screen now displays the name of the new configuration.

▶ Video available: How to identify which configuration is Mapeo Mobile using

▶ Video available: How to import a custom configuration to Mapeo Mobile

This section provides step-by-step guidance on the use of the main features of Mapeo Mobile:

By default, Mapeo Mobile uses a background map that shows some geographic elements such as rivers and mountains, as well as some political and urban elements such as borders, cities, roads, etc.

If you have a custom background map prepared, you can add it and use it in Mapeo Mobile without affecting the data you have collected. (For more on creating custom background maps, see Custom background maps.)

Adding a background map using a computer

Connect your smartphone to a computer

Unlock the screen of the smartphone and connect the device to a computer using a USB cable. Tap the Charging this device via USB notification. Under "Use USB for," select File Transfer.

On your computer, locate and copy the contents of the Mapeo background map package

Mapeo background maps will often be shared as a compressed file(.zip). If your background map is a .zip file, double-click the file to unzip it.

A Mapeo background map consists of several folders and files that need to be copied into the file system of Mapeo Mobile. Standard vector background maps for Mapeo will contain the file elements listed below - 3 folders and 2 files.

Select and copy all of the elements found inside your background map folder.

Paste the background map elements onto your smartphone

Once you have copied the contents of the background map folder, use the computer to browse through your smartphone to the correct folder within the Mapeo Mobile file system.

Click on Internal Shared Storage, then on Android, data, com.mapeo. Then click on files, then on styles, and finally on default. Paste the background map elements into the default folder.

The complete path of the default folder where you will paste the map elements is Internal Shared Storage/Android/data/com.mapeo/files/styles/default

Restart Mapeo Mobile

Restart the Mapeo Mobile app. The new background map will appear on the home Map screen.

Like most existing apps, Mapeo Mobile is in continuous development. We frequently release new versions of the application to fix technical issues or add new functionality. When you update Mapeo Mobile, you do not lose data you have collected or synchronized using a previous version.

The process to update Mapeo Mobile is very similar to the installation process and there are 3 ways to do it:

Other content related to Mapeo updates

Mapeo versions - information and naming conventions

Mapeo uses a numerical system to name versions ( for example v.5.4.0). The numbers are labeled as follows: v.MAJOR.MINOR.PATCH.

• The MAJOR number indicates a breaking change - a change in this number could be related to how the software work or a change in how you use it. The MAJOR number increases if features that were previously part of the app are now removed.

• The MINOR number increases when new features have been added to Mapeo.

• The PACTH number increases if there are small updates or fixes that don’t introduce any new behavior or features.

If the MAJOR number increases, the MINOR and PATCH numbers are reset to 0. If the MINOR number increases, the PATH number is reset to 0.

Installation files for older versions of Mapeo Mobile

Updating Mapeo Mobile via P2P (peer-to-peer) App Updates

Peer-to-peer (P2P) App Updates is an experimental feature that allows you to share and receive newer versions of the Mapeo app by connecting to other Mapeo devices via Wi-Fi (no internet connection required).

When updating the Mapeo app version in this way, NONE of your Mapeo data (observations, configurations, or maps) is shared between devices.

View observations on the map

To view the details of an observation, tap on the orange dot marking the observation to open the View observation screen.

View observations in a list

To view the details of an observation, tap on any observation in the list to open the View observation screen.

You collect data with Mapeo Mobile in the form of observations. An observation is based on a geographic location (a point on the map) and can have associated photos, notes, and details.

Create a new observation

Select a category

Select the category that best represents what you are documenting in the observation. Mapeo comes with a default set of categories and associated icons that can be used for collecting and classifying data.

Add a description

Tap on the placeholder What is happening here? to add a description of what you are documenting.

Add photos

To confirm deletion, tap Delete Image in the confirmation window. Please note that once deleted, images cannot be recovered.

Add details

Tap NEXT to move to the next question and tap DONE once you have answered the last one.

Save observation

* Note on GPS precision

If the GPS signal at the moment of saving the observation has an accuracy worse than ± 10 m, Mapeo will automatically offer you three options:

1. Tap CONTINUE WAITING to wait until the GPS signal improves.

2. Tap SAVE to use the current GPS data, even if the accuracy is worse than ± 10 m.

Enable GPS on your device

Mapeo Mobile uses the GPS of your device, so before you start using the application make sure that GPS or Location on your smartphone is enabled.

It will be different on each smartphone, but GPS or Location services can generally be found in the Quick Settings menu, which can be accessed by swiping down from the top of your screen.

Confirm GPS access in Mapeo Mobile

On the home screen of Mapeo Mobile, you will be able to see if Mapeo is successfully accessing your device's GPS.

View GPS details in Mapeo Mobile

Viewing your current location

By default, Mapeo Mobile will mark your current position with a blue dot at the center of the map and adjust the map as you move.

Edit details

In the Edit observation screen, you can change the category of the point, edit the description and details, or add additional photos.

Save changes

Delete observations

This section will cover all the necessary steps to install and set up Mapeo Desktop on your computer:

Before you start, make sure that:

Changing the language of Mapping Desktop is a simple step and does not affect the data collected or the categories used to create observations. Mapeo Desktop should open initially in the current language you have selected for your computer's operating system. To change the Mapeo Desktop language:

2. On the Top menu bar, click on View and select Change language.

3. Select the desired language and click on SUBMIT. You may see a white screen for a few seconds as the interface language changes.

About Mapeo Sync

Mapeo Mobile allows you to synchronize the data you have collected with other Mapeo users that are members of the same project. Syncing data does not require an internet connection and can be done in entirely offline areas.

Connect to WiFi

Connect both devices to the same Wi-Fi network. Wi-Fi settings can generally be found in the Quick Settings menu, which can be accessed by swiping down from the top of your screen.

Enter Synchronize mode

The Synchronize screen will show whether you are connected to a Wi-Fi network. If connected, you will be able to see the name of the network you are connected to in the top left of the navy blue bar. You will also be able to see the unique identification number of your device on the right side of the navy bar.

Synchronize data

Once available devices appear in the list, confirm the identity of the device you plan to synchronize with by consulting the unique identification number on the other user's phone.

Click on the Sync button beside the device name to begin the exchange of data.

View synced observations

In the Observations list screen, observations collected by other devices will appear with a blue bar on the left side.

Download the installation file

Once you have the installation file downloaded, follow the detailed steps in the sections below to install Mapeo Desktop on the appropriate operating system for your computer:

Install on Windows

2. Find the Mapeo installation file (.exe) on your computer and double click on it to install. If you get a security message from your operating system, click on Execute anyway.\

Install on macOS ​

2. Find the Mapeo installation file (.dmg) on your computer and double click on it to open.

Install on Linux

Download installation file

Enable executable permissions

In order to install from the .AppImage file, you'll need to ensure that the file has permissions to run as a program. Find where the installation file was saved on your computer and right-click the file. Select Properties from the menu.

Click on the Permissions tab at the top of the Properties window, then click the checkbox to Allow this file to run as a program.

Install

Double click the .AppImage file and Mapeo Desktop should open automatically.

Installing offline

Now that you have pasted the installation file onto another computer, follow these steps to install Mapeo:

Locate the configuration file

Download or copy the custom configuration file (eg. example_project.mapeosettings) onto your computer. Note which folder the file was saved in.

Import the configuration

2. On the Top menu bar, click File and select Import Configuration.

3. In the pop-up window, navigate to the folder on the computer where you saved the configuration file (.mapeosettings) you want to import. Click on the file, then click Open. You may see a white screen for a few seconds while the configuration changes.

To add a background map to Mapeo Desktop, follow the instructions below for your operating system:

Windows computer

Locate and copy the contents of the Mapeo background map package

Mapeo background maps will often be shared as a compressed file(.zip). If your background map is a .zip file, double click the file to unzip it.

Standard vector background maps for Mapeo will contain the file elements listed below: 3 folders and 2 files.

Select and copy all of the elements found inside your background map folder.

Paste the copied elements into the Mapeo/styles/default folder

1. In the Windows search engine, type %APPDATA% , and open the folder that appears with this name.

2. Inside the AppData folder, click on the Mapeo subfolder, then click on the styles subfolder.

3. If there is not already a default folder inside your styles folder, you will need to create one. To do so, right-click inside the styles folder and create a new folder named default.

4. Paste the background map elements you copied into the default folder.

Reload Mapeo Desktop

macOS computer

Locate and copy the contents of the Mapeo background map package

Mapeo background maps will often be shared as a compressed file(.zip). If your background map is a .zip file, double click the file to unzip it.

A Mapeo background map consists of several folders and files that need to be copied into the file system of Mapeo Desktop. Standard vector background maps for Mapeo will contain the file elements listed below - 3 folders and 2 files.

Select and copy all of the elements found inside your background map folder.

Navigate to the Mapeo/styles folder

1. Click on Finder on your computer.

2. In the top menu bar, click on Go, then select Go to Folder...

3. Type in ~/Library/Application Support/Mapeo/styles in the address bar and click on Go.

Paste the copied elements into the Mapeo/styles/default folder

If there is not already a default folder inside your styles folder, you will need to create one. To do so, control-click inside the styles folder and create a new folder named default.

Paste the background map elements you copied into the default folder.

Restart Mapeo Desktop

This section explores how to use Mapeo Desktop to view and manage Mapeo Mobile data, as well as the available options for exporting data into different formats. The information is contained in the following pages:

• Synchronizing data

• Viewing observations

• Editing and deleting observations

• Exporting data & sharing externally

Mapeo Desktop is a computer application that can be used for two different purposes:

• Mapeo Desktop for managing Mapeo Mobile data (Observations mode) Mapeo Desktop allows you to aggregate, view, and manage data collected with Mapeo Mobile. Observations mode offers options to filter and export data into multiple formats, such as GeoJSON, CSV, and PDF, and also allows the publication of online interactive maps containing data collected with Mapeo Mobile.

• Mapeo Desktop for creating territory data (Territory mode) Mapeo Desktop also offers an interface for adding or creating territory data directly within the Desktop application. Territory mode provides a basic toolkit for mapping features that are more accessible to new tech users than other available geographic information systems (GIS) tools. It also offers the option to import geographic information from an external source, and export map data in a .GeoJSON file format. Further manipulation or visualization of exported map data requires knowledge of other software.

Like most existing apps, Mapeo Desktop is in continuous development. We frequently release new versions of the application to fix technical issues or add new functionality.

When you update Mapeo Desktop, you do not lose data you have collected or synchronized using a previous version.

Mapeo versions - information and naming conventions

For details on Mapeo version numbers and naming conventions, see:Mapeo versions - information and naming conventions

Installation files for older versions of Mapeo Desktop

To view all previous versions of Mapeo Desktop, including release notes for changes made in each version, see the Mapeo Desktop Releases page on GitHub.

Synchronizing via Wi-Fi

Requirements:

• Both devices must be using the same configuration It is only possible to synchronize with devices that use the same configuration. For more on how to import configurations, see Importing configurations to Mapeo Desktop.

To synchronize, follow the steps below:

Connect to Wi-Fi

Enter Synchronize mode

In order to synchronize, both devices must have the Synchronize screen open.

Devices available for syncing will be listed on the Synchronize screen.

Start synchronization

Once available devices appear in the list, confirm the identity of the device you plan to synchronize with by consulting the unique identification number on the other user's device.