Mergin Maps Project

• Creating project
• Packaging QGIS project
  • Mergin Maps project folder
• Adding a layer to the project

What is a Mergin Maps project?

It is basically a folder that contains data (such as vector layers, tables, rasters or photos), a QGIS project, and some extra Mergin Maps files needed to ensure everything works.

When Mergin Maps project is created, it is saved to Mergin Maps cloud. From the cloud, it can be downloaded to various devices, used by different team members in both QGIS and the mobile app. Changes they made are tracked and synchronised back to the cloud.

Creating project

TIP

Different ways of how a Mergin Maps project can be created are described in How to Create a New Project

In general, projects are prepared and managed in QGIS, where you can get the most of the functionality, such as set up survey layers and their properties (symbology, forms, etc.), background maps, or other project settings.

Typically, especially if your project is rather complex, you would:

1. Create a QGIS project with all necessary datasets and settings to fit your needs
2. Package it using Mergin Maps QGIS plugin to create a Mergin Maps project that is saved to the cloud
3. Check that everything works as expected in the mobile app. If not, fix the issues in QGIS. Don't forget to save and sync the project. Repeat this step as necessary.
4. Share the project with your team members. Now you can collaborate safely and effectively.

TIP

QGIS Project Preparation will guide you the project preparation steps. We also recommend following our Best Practice Tips for Layers and Forms.

If you need to make changes in the data schema of survey layers, please follow How to Deploy Revised Projects to avoid synchronisation issues.

Packaging QGIS project

When using the QGIS plugin to create a Mergin Maps project, there is an option to Package current project. This is what you will choose if you want to transform your QGIS project into Mergin Maps project.

There are three options for handling layers:

• package - layers will be copied and saved in the new Mergin Maps project folder: by default, each vector layer will be saved as a GeoPackage, rasters (if possible) will be saved as GeoTIFF and local vector and raster MBTiles will be copied to the folder.
• keep as is - the layer will be referenced "as is" in the new project. The location of the file will stay the same, it will not be copied to the new Mergin Maps project folder. This is the default for some rasters and web services (e.g. WMS/WMTS, WFS, online vector and XYZ tiles).
• ignore - the layer will not be included in the new project.

After the layers for the new project are selected, you just need to enter the project's name and choose where to save it on your computer. It will also be saved on the Mergin Maps server in the selected workspace.

WARNING

Your project should be saved on a local drive. Using shared network drives and cloud storage (such as OneDrive or Google Drive) is not supported.

Mergin Maps project folder

The project folder on your computer will contain the QGIS project and all layers that were selected to be packaged. These are the files that are referenced in the project - and only they will be updated when the project is synchronised! The original data can be archived as they will not be used or needed by Mergin Maps project anymore.

Layers that were kept as is are not stored in the project folder.

There are also some extra folders and files:

• .mergin folder contains the Geodiff files that are used to keep the project history and versions and diagnostic log in a file named client-log.txt
• proj folder contains, if needed, custom projections files
• conflict files may appear if changes could not be properly synchronised
  

And this is how the same project looks in app.merginmaps.com

Adding a layer to the project

If you want to add an additional layer to your existing Mergin Maps project:

• a new layer: create a new GeoPackage layer and save it to the project's folder
• an existing layer: copy the layer to the project's folder and then add it to the project

Save and sync the project. When syncing, you will see in the Project status that a new layer was added.

If you used keep as is option when packaging the project or add a layer that is not stored in the project's folder, the project will reference the relative path to its location. When opening the project on another computer, QGIS will try to load the file using the relative path. If this folder doesn't exist or is located elsewhere, the project will not be able to load the layer. The same applies for Mergin Maps mobile app.

Only the content in the project's folder is synchronised!

It is best to store all survey layers and relevant datasets in the project's folder to avoid issues with synchronisation or availability of the layers.

TIP

It is possible to use files that are stored in other folders in Mergin Maps mobile app. However, these folders have to be manually transferred.

This can be useful when working with very large datasets such as large rasters or background maps.