1. Because not all paparazzis are evil!

If you are looking for the source code of this project, jump right to this link.

Geopaparazzi is a tool developed to do very fast qualitative engineering/geologic surveys and GIS data collection.

Even if the main aim is in the field of GIS data collection, it contains tools that can be of great use also to OpenStreetMappers as well as tourists that want to keep a geo-diary.

01 nexus5
Figure 1. Geopaparazzi on a nexus 5

The main aim of Geopaparazzi is to have a tool that:

  • fits in any pocket and can be always at hand, when needed

  • gives the possibility to take geo-referenced and possibly orientated pictures during a survey, with further possibility to import them into GIS applications like gvSIG

  • is able to easily exploit an Internet connection, if available

  • is extremely easy to use and intuitive, providing just few important functions

The main features available in Geopaparazzi are:

  • geo-referenced notes

  • geo-referenced and oriented pictures

  • gps track logging

  • form-based data surveys

  • easy export of collected data

  • a map view for navigation with support for raster tiles and spatialite vector data

Geopaparazzi is available only for the Android Operating System.

1.1. License

Geopaparazzi source code is licensed under the GNU General Public License, Version 3

1.2. Community

And there’s a group for Geopaparazzi developers too.

You can even contribute to this Geopaparazzi manual!

1.3. Translations

Geopaparazzi has already been translated in several languages.

Do you want to see Geopaparazzi in your language? With transifex it is a simple task.

Check out the translation page and send us your contributions.

1.4. Need help?

Subscribe to the mailinglist, we are here to help you!

We also have a mailinglist for developers.

1.5. Found bugs?

If you found a bug, please report it in our issue tracker. We will check it and work on it as soon as we can.

1.6. Need features?

If you would like to see new features in geopaparazzi, you have a few ways to get there:

1.7. Donations

If you find this application useful for your job, please consider to donate to support the development. Donations to this project support the development of the Hortonmachine and Geopaparazzi projects.

Thanks for helping to keep this development free and open source.

2. Installation

2.1. From Google Play

  • connect your Android device to Internet

  • open the Play Store

  • type geopaparazzi within the Search textbox

02 google play
Figure 2. Google Play Store presents 2 versions of Geopaparazzi.
  • select the first app (not Geopaparazzi 3)

03 geopaparazzi4
Figure 3. The right choice: Geopaparazzi (not Geopaparazzi3)
  • follow installation procedures

2.2. Manual Installation

The following example explains how to install version 4.4.0. We suggest to always use the latest version available.

  • from your devices visit the geopaparazzi releases page making sure to load the desktop site (not the mobile site).

  • select the releases tab and pick the last available release:

04 github
Figure 4. Geopaparazzi github page.
  • select the latest release apk download link:

05 github releases
Figure 5. The releases panel.
  • the apk installation file will download on the device:

06 github download
Figure 6. The download dialog.
  • and the user will be prompted to open the file:

07 github open
Figure 7. The download dialog.
  • opening the file will propose the installation:

08 install
Figure 8. The download dialog.
  • select install and follow the installation procedure.

3. The Main View

Once you launch Geopaparazzi, the dashboard appears.

All the features that need to be quickly accessed, such as toggling GPS on and off, creating a note or taking a picture, as well as visualizing the current position on a map, are accessible from the dashboard.

00 dashboard
Figure 9. The dashboard of geopaparazzi.

From the dashboard the following primary functions can be accessed:

  • the action bar functions

  • take notes

  • view or modify the project metadata

  • take a GPS Track

  • switch to Map View

  • import Data

  • export Data

3.1. Action Bar

The action bar, from right to left, presents the following functions:

  • the main menu

  • the general settings button

  • the GPS and map information button

The info button shows information about the current selected map and the status of the GPS. If the GPS has acquired a fix, information about the position is given:

10 info button
Figure 10. Information shown when tapping the info button.
The GPS status icon can be of the following colors: RED if the GPS is not switched on, ORANGE if the GPS is on but no fix was acquired, GREEN if the GPS is on and has fix, but no log is being recorded and BLUE if the GPS is logging.

3.2. The panic button

At the bottom of the view the orange Panic Button is visible. Once pushed it leads to the panic! view, which presents two buttons:

  • the PANIC! button

  • the just send position button

20 panic
Figure 11. The panic panel.

The panic button sends a request for help SMS with the last available GPS position to a phone number that can be configured in the [settings] of geopaparazzi.

If no number is configured, the system SMS dialog opens up with a precompiled message and the user will have to select the contact to which to send the message:

21 panic sms
Figure 12. The system SMS dialog

The just send position button opens up the SMS dialog directly filling in the position without any request for help message. It is meant for quick sending the current position via SMS so that it can be opened from Geopaparazzi.

3.3. The dashboard buttons

3.3.1. Notes

Geopaparazzi supports 4 different types of notes:

  • text notes

  • picture notes

  • sketch notes

  • form-based notes

To access them you can tap on the first icon of the dashboard, the take notes icon. Once you tap on it, the take notes dialog appears:

03 notes
Figure 13. The view from which notes are taken.

The switch button at the top of the view gives the possibility to choose whether the note will be recorded with the current GPS position (in case GPS is on) or at the current center of the Map View (the crosshair).

At the right end of the actionbar the quick note buttons are placed. From left to right:

  • The Quick text note button, which opens a simple dialog, inside which the text note can be written. Want to save the note? Tap on the ok button. Want to trash it? Tap on the cancel button.

The position of the note is taken when the note view is opened, not closed, in order to have all the time needed to insert the text while moving.
04 textnotes
Figure 14. The simple text note dialog.
  • The Quick picture note button, which will launch the camera application that comes with your android system which gives lots of possibilities of customization of the images size, focus and so on. This has one drawback, which is the fact that we are not able to pick the azimuth of the camera shot at the exact moment it is taken. The azimuth is therefore recorded at the moment the camera application is closed. That means that to have a realistic azimuth, you need to take the picture and stay with the device in the same position of the snapshot until you have closed the camera app.

  • The Menu button, which allows you to select Simple Sketch to draw on a small panel or select Layout Settings to change the Notes button layout and text size.

05 note menu
Figure 15. The simple text note dialog.

Selecting Simple Sketch, you can change stroke style, color, and width. The sketch panel comes from the open source app Acrylic Paint.

05 sketchnotes
Figure 16. An example of taking sketch note.
Once a simple note has been saved, it can’t be modified.

Selecting Layout Settings allows you to change the text size on the Note buttons and the number of columns. This can be useful to make the dialog easy to read while in the field.

05 note large
Figure 17. The Notes List with one column and large text.
Form based notes

Form based notes are complex notes that allow for better surveys. Some example forms are included in the base installation of geopaparazzi.

The example button in particular shows all the possible form widgets available:

06 form based notes
Figure 18. An example of form based notes.

The notes can be saved and modified at any time.

To understand how to create forms, have a look at the section dedicated to [forms].

3.3.2. Project Information

The project view shows information about the project database.

It shows:

  • the database file name

  • the project name

  • the project description

  • project notes

  • creation and last closing date

  • the user that created the project

  • the user that last modified the project

Apart from the dates, that are set by the system, all data can be changed and saved through the save button.

07 project info
Figure 19. The project metadata view.

It is also possible to add additional metadata to the project information. The plus button at the right side of the actionbar opens an input dialog that allows the user to define a key, a label and a value for the new metadata entry:

07 project info plus
Figure 20. The new metadata entry dialog.

3.3.3. GPS Logging

To start logging, the user simply has to push the logging button.

Once it is tapped, the user is prompted to insert a name for the log or to accept the one generated based on the current date and time ( log_YYYYMMDD_HHMMSS ).

It is also possible to attach the new log to the last created log by checking the box: Continue last log. In that case the proposed name of the log (or any user inserted) is ignored, since no new log is created.

08 start logging
Figure 21. The new log dialog. From here it is possible to continue the last log.

Once logging has started, the logging button will turn orange and the GPS status icon blue.

09 logging on
Figure 22. The stop logging button with its orange color.

To stop logging, the same button is used. Once tapped, the user is prompted to verify the action.

3.3.4. Map View

The map view presents a map and a set of tools that can be used to navigate the map, make measurements or edit datasets. The various tools are presented in the section dedicated to the Map View.

12 map view
Figure 23. The map view.

3.3.5. Import

13 import
Figure 24. The import view.

Geopaparazzi supports the import of:

  • GPX datasets

  • bookmarks

  • WMS

  • default Spatialite databases

  • geopaparazzi cloud projects

  • geopaparazzi Cloud Profiles


By tapping on the GPX icon, the user is taken to a simple file browser.

16 import gpx
Figure 25. The simple geopaparazzi file browser.

The browser only shows folders and files with gpx extensions. On selection, the file is imported.


Bookmarks can be imported from csv files that must be placed in the root of the sdcard and the name of which has to start with the part bookmarks and to end with the extension .csv.

Geopaparazzi will let the user select the files to import if more than one are available and load the bookmarks from there and import only those that do not exist already.

The format of the csv is: NAME, LATITUDE, LONGITUDE as for example:

Uscita Vicenza Est, 45.514237, 11.593432
Le Bistrot, 46.070037, 11.220296
Ciolda, 46.024756, 11.230184
Hotel Trieste, 45.642043,13.780791
Grassday Trieste,45.65844,13.79320

It is possible to import basemap configurations from WMS getCapabilities URLs.

16 import wms
Figure 26. The WMS dialog.

Once the getCapabilities URL is inserted and the refresh button is tapped, the list of available layers is presented. The selected layer is then imported in the list of available tile sources.

Default databases

When tapping the default database import button, the user is asked to name the new Spatialite database to create. Let’s use the default name proposed based on the current date and time:

19 mapsforge
Figure 27. Creating A Default Spatialite Database

The newly created database is editing ready and contains a layer of each type geomotry type (points, lines, polygon). Since it is a template db, the attributes table have been created as generic fields with names from field1 to field20. It is very generic and simple, but still of use when you have to quickly collect some data with attributes and have no database prepared..

Cloud Projects

Geopaparazzi Project files can be downloaded from a Geopaparazzi Project server. To enable the import of projects from the Cloud, make sure you enter the settings in the Cloud Projects Sync Settings

Cloud Profiles

Profiles are a convenient way to group basemaps, overlays, note forms, and a project file. Geopaparazzi Cloud Profiles must be downloaded from a Geopaparazzi Profile server (standard Profiles can be created on your device). To enable the import of Profiles from the Cloud, make sure you enter the settings in the Cloud server Settings.

Once your Cloud server Settings are set, and you press the Cloud Profiles button on the Import view, the server will send a list of Profiles available for download.

22 import profiles1
Figure 28. Cloud Profiles List
package download

Select a Profile for download by pressing on the icon of the Profile. This will start the download of the Profile and the files associated with the Profile. The download may take some time depening on the size of the files.

When the download is completed, you can activate the Profile by using the Profile view from the Main View menu, selecting the Profile Info tab, and sliding the Activate profile switch.

3.3.6. Export

18 export
Figure 29. The export view.

Geopaparazzi supports the export to the following formats:

  • KMZ

  • GPX

  • bookmarks

  • images

  • Project Forms to PDF

  • geopaparazzi cloud projects


It is possible to export all collected data to KMZ format.

KMZ is well known as it can be visualized in the 3D viewer Google Earth.

In the export:

  • the notes are placed as red pins having the first letters of the text content as label

  • the images are placed as yellow pins

  • the GPS logs are visualized as tracks


The lines and notes data are exported to GPX, creating tracks and waypoints.


Bookmarks can be exported to a csv file that has to be called bookmarks.csv and are placed in the root of the sdcard.

Geopaparazzi will write to the file only those bookmarks that do not exist already in the csv.


Since images are kept inside the database, this export is handy if the user needs to use the images inside a different software. In this case all the images of the project are exported inside a folder and a popup message shows the folder path.

Project Forms to PDF

You can export your notes to a simple PDF document. After pressing the "Project Forms to PDF" button you can select which notes you would like to include in the PDF file. The PDF file created will be a the root of the device’s file system and named "geopaparazzi_projectexport_" with a timestamp and a .pdf extension in the file name.

Cloud Projects

Geopaparazzi Project files can be uploaded to a Geopaparazzi Project server. To enable the upload of projects to the Cloud, make sure you enter the settings in the Cloud Projects Sync Settings.

4. The Main View Menu

The main view menu presents the following options:

  • Select tile source: allows the selection of a map tile source to be used as a basemap

  • Create new project: creates a new project on the sdcard. A timestamp based name is proposed to the user

  • Load existing project: allows the browsing of the filesystem to select an existing geopaparazzi project file to load it

  • GPS Status: opens a GPS status application to check on satellite visibility

  • Advanced: shows some advanced user options such as the application log or custom database queries

  • Profiles: allow creation and editing of Profiles.

  • About: shows the about page, which contains info, links and acknowledgments

  • Exit: shuts down geopaparazzi properly. This is important, because geopaparazzi is meant to continue logging also in background. Therefore, if one uses the android home button to exit the app, it will continue to work in background, most probably draining the battery through GPS use.

01 menu
Figure 30. The main view menu.

4.1. Select tile source

From the main menu, when pushing the tile source button, the list of available tile sources (and other types of Basemaps) are presented, organized by folder:

02 select tiles
Figure 31. The basemaps view.

Each map source has a name and a type description between brackets.

At the current time four types are supported:

  • Mapsforge Map

  • Mapurl

  • MBTiles

  • RasterLite2

The supported datasets section lists and describes all supported map types.

Through the button at the top of the view the user can filter the source types to show.

03 select tiles
Figure 32. The map type filter dialog, set to only show MBTiles sources.

which makes searching simpler when a lot of sources are present on the device.

04 select tiles
Figure 33. List of Available Basemaps

Basemaps can be added to the list from the device storage through the two buttons at the bottom of the view. The right one allows to pick a single file to add it as a basemap, while the left one allows to bulk load a complete folder of maps. Once the basemap has been added to the list, tap the basemap on the list to use in the Map View.

4.2. Create a new project

When a new project is created, the user is prompted to give a file name for the new project file. This is the name that will be given to the database file that contains all data collected in Geopaparazzi.

05 new project
Figure 34. The new project input dialog.

Once the name is defined, an new empty database is created and Geopaparazzi is restarted and opened loading the new created project.

4.3. Load an existing project

Existing projects can be loaded using a simple file browser from within Geopaparazzi. The Geopaparazzi project files are shown with an icon to help the user to choose the proper files.

4.4. GPS Status

The GPS status entry launches the open source application GPS test. The app shows the current status of the satellites fix and a skymap. This often helps to understand why the GPS is not working.

4.5. Advanced


4.6. Profiles

Profiles enable you to configure the Geopaparazzi environment by grouping specific basemaps, overlays, a notes form, and a project file into a Profile. You can configure many different profiles and easily switch between them in Geopaparazzi.

4.6.1. Creating a Profile

To create a new profile simply push the orange button on the lower right of the view.

08 profiles
Figure 35. An Empty Profile List

Once pushed, the main profile info dialog will pop-up. There you can insert a profile name and some description about the profile:

09 profiles new
Figure 36. Creating a Profile

Once OK is pressed, an empty profile is created:

09 profiles new2
Figure 37. Profile List

The profile’s cardview gives information about its content, listing the number of basemaps, spatialite database overlays, Note forms, and project file.

4.6.2. Deleting a Profile

Pressing the Profile’s Trashcan icon will delete the Profile. You will be prompted to make sure the Profile is not deleted by error:

10 profiles delete
Figure 38. Deleting a Profile

4.6.3. Styling a Profile

It is possible to apply a color to the Profile cardview. Setting a color uniquely identifies a Profile while running Geopaparazzi. If a Profile has aproject attached, you will know a particular Profile is active because it uses the color to set the background color in the Main View.

11 profiles color
Figure 39. Profile Style

Once you press the OK button, the profile cardview will appear colored with the color you selected:

12 profiles new
Figure 40. Profile List

4.6.4. Adding data to a Profile

To add data to a profile, press the settings icon (gear-like icon in the upper right of the Profile’s cardview).

13 profiles info
Figure 41. Profile Settings

The view the opens is divided in different tabs, namely:






Profile Info

The Profile Info tab shows the main information about the Profile:

  • Profile Name

  • Profile Description

  • Creation Date

  • Activate Profile

13 profiles info2
Figure 42. A Profile’s Information

Name and description can be modified from this view, while the creation date is read-only.

From this view it is also possible to activate the profile through the switch at the bottom of the view. Activating the Profile means the various files will be automatically attached to Geopaparazzi. Since only one Profile can be active at a time, the activation of a Profile automatically disables the previously active Profile, if there had been one.

Once a Profile is active, in the Profiles view it is marked with two red lines in the top and bottom part of the Profile’s card:

13 profiles active
Figure 43. An Active Profile

The Basemaps tab allows you to add background basemaps to the Profile configuration. Currently supported extensions are:

  • map: mapsforge maps

  • mbtiles

  • sqlite: sqlite databases containing rasterlite2 data

  • mapurl: mapurl files that can contain configurations for local or on-line (TMS or WMS) mapping services.

Press the orange plus button on the top right part of the view to browse the device’s filesystem and select the basemap files to add.

14 profiles base1
Figure 44. Adding A Basemap
Importing Basemaps from WMS

It is possible to import mapurl definitions directly from WMS GetCapabilities URL. When the Basemaps tab is selected, "ADD WMS" text appears on the right side of the Profiles Settings action bar.


  • copy your WMS URL to your device clipboard

  • press the ADD WMS button on the right side of the action bar

  • a dialog will open. Paste the URL into the text field

15 profiles base wms2
Figure 45. Adding a Basemap from a WMS Server
  • push the refresh button at the left of the text field to retrieve the available layers

15 profiles base wms3
Figure 46. Selecting Layers from a WMS Server
  • select the desired layer and press OK. The mapurl file will be created and added directly to the list of basemaps

16 profiles base
Figure 47. A Basemap Added to a Profile
Spatialite Databases

The Spatialite Databases tab allows you to add Spatialite vector databases to the Profile configuration.

The database has to be a valid spatialite database with the extension sqlite.

Press the orange plus button on the top right part of the view to browse the device’s filesystem and select the Spatialite databases to add.

17 profiles spatial1
Figure 48. Adding a Spatialite Database
17 profiles spatial2
Figure 49. A Spatialite Database Added to a Profile

The Forms tab allows you to add a JSON file of forms definitions to use in the Profile.

Once the file is added (through the upper right plus button), basic information and the names of the forms contained in the file are shown:

18 profiles forms
Figure 50. A Form Added to a Profile

It is also possible to bind a single Geopaparazzi project file to a Profile. In that case, from within geopaparazzi it will no longer be possible to open an existing project or create a new one.

19 profiles project
Figure 51. A Project Added to a Profile

4.6.5. Importing, Exporting and Deleting Profiles

It is possible to import, export, and delete all Profiles. The menu in the main Profiles view allows access to:

  • Import Profiles

  • Export Profiles

  • Delete all Profiles

20 profiles menu
Figure 52. The Profile Menu

When you press the Export Profiles menu entry, the Profile definitions are exported into a file in the path:


21 profiles export
Figure 53. Exporting A Profile List

When you press the Import Profiles menu entry, the Profile definitions are imported from the fixed file in the path:


The imported profiles are added to the profiles already present in Geopaparazzi.

22 profiles import
Figure 54. Importing A Profile List

In order to support sharing of data and profile configurations, the path of the data contained in the imported files are adapted to the sdcard path of the current device. This way relative paths in the sdcard are maintained and datasets can be loaded. In that case you download and import data that someone else prepared, but they will work in your device, even if the paths of the data refer to a different sdcard path.

4.7. Exit

The exit button closes Geopaparazzi and stops any ongoing logging and sensor activity.

This might seem obvious, but it is important to note that this is the only way to properly close Geopaparazzi. Pushing the home button of the device will not close Geopaparazzi, which will continue any activity started. This is important, because it makes very long loggings possible even if interrupted by phone calls or other uses of the device.

Often users that ignore this, after pushing the home screen and thinking that Geopaparazzi has been closed, experience a faster battery drop, because of the active application in the background.

5. The Map View

The map view is the central view of the application. It can be used to view the current GPS position overlaid on maps and vector datasets.

01 mapview
Figure 55. The map view.

The map engine comes from the mapsforge project.

The supported datasets section lists and describes all supported map types. Just to cite a few, one can view:

  • OpenStreetMap raster tile maps both when on-line (downloading new tiles) and off-line (visualizing those that were cached during online mode)

  • mbtiles databases

  • local and remote TMS tiles

  • mapsforge vector files

5.1. Map View tools

The Map View has a set of tools that can be used to interact with the map.

When first launched, the tools are already visible on the map. To have a cleaner Map View, the user can long-tap on the upper right menu button to toggle the visibility of the tools.

02 mapview tools off
Figure 56. The map view with disabled tools.

Available tools are:

  • Left screen side

    • add note (the same that is accessed from the dashboard) and list notes (long tap)

    • add bookmark and list bookmarks (long tap)

    • activate the GPS log analyzer

    • activate the measure tool

  • Right screen side

    • the context menu button

    • the zoom in and out buttons

  • Lower center

    • battery status

    • center screen on GPS position and GPS status button

    • editing tools

01 mapview
Figure 57. The map view with all map tools visible.

5.2. Map navigation

The navigation of the map is probably the most basic and important part.

  • pan: panning of the map, i.e. moving the map around is simply done by dragging the map with a finger. While panning, the current longitude and latitude of the map center are displayed.

29 pan coords
  • zoom: zoom in and out can be done in different ways. There are the zoom in/out buttons at the lower right part of the map. It is also possible to zoom in by double-tapping on the map. Zoom in and out can also be achived through pinch-zoom gestures.

If you have trouble reading small text on some basemaps, you can "magnify" the map display by doing a long press on the "zoom in" button. You can magnify multiple times if needed. Don’t forget to demagnify (long press on the "zoom out" button) before you do other Map View operations such as measure or feature ID.
  • center on GPS: through the lower center button it is possible to center the map on the GPS position. The button also shows the status of the GPS the same way as the icon on the main view’s action bar.

5.3. Add Notes

03 notes
Figure 58. The view from which notes are taken.

The add notes button opens the same notes view as the button on the dashboard. There is only once difference. Since notes can be added both in the GPS position and in the middle of the map, to open the add note view from the dashboard, the GPS is required to have a fix.

From the map view the user can open the add note view even without GPS signal, in which case notes will only be inserted at the map center position.

For further information about taking notes, visit the notes section.

5.4. The Notes List

A long press on the Notes icon will show the Notes List. The notes list shows all the available notes, both text and image notes.

03 noteslist1
Figure 59. The notes list view.

The icon on the right side of the actionbar allows the user to sort the notes by different modes:

  • None: insertion order

  • By Name and inverse: sorts the notes by their name

  • By Map center distance and inverse: sorts the notes by the distance from the current map center position

04 noteslist sortorder
Figure 60. The notes sort order dialog.

In the upper part of the view there is a textbox that helps to filter out a particular note based on its name.

04 noteslist filter
Figure 61. Notes can be filtered by text.

At the right side of the list two icons are available. The left one positions the map on the selected note’s position while the right one opens a menu:

05 note menu
Figure 62. The note menu.

From the note menu the user is able to:

  • edit form based notes or view simple notes

  • share the note through social networks

  • delete the note

  • use the current note as a filter. All notes with the same name will be visible.

  • access the submenu related to all notes

07 notes all menu
Figure 63. The submenu that considers all notes.

From the all-notes submenu the user can:

  • select all notes

  • invert the current selection

  • delete the selected notes

The pallet icon on the Notes List view allows you to change the graphic properties of the notes.

07 notes properties
Figure 64. The Notes Properties.

5.5. Add Bookmark

Bookmarks are in a layer on their own, that contains saved settings of the current map view. When a bookmark is added, the user is prompted to insert a name for the bookmark or leave the generated name based on the current time and date.

08 add bookmark
Figure 65. The add bookmark dialog.

When a bookmark is added, a small star is added on the map in the center of the screen.

Also the map bounds and zoom are saved. That way one can return to the scenario that the bookmark represents in any moment.

It is possible to tap on the bookmark to read its label.

10 bookmark open
Figure 66. A tapped bookmark.

5.6. The Bookmarks List

The bookmarks list shows all the saved bookmarks.

In the upper part there is a textbox that helps to filter out a particular bookmark based on its name.

The user has 4 options, as the icons on each bookmark entry shows:

  • go to the bookmark location (left icon)

  • edit the bookmark

  • delete the bookmark

11 bookmarks list
Figure 67. The list of bookmarks.

5.7. GPS log analysis tool

The log analysis tool allows to analyze the various positions of a GPS log.

Once enabled, one can simply touch the screen near a GPS log and information about the nearest log point will be shown. Also the color of the text will be the one of the currently queried log:

28 gps log analysis
Figure 68. The GPS log analysis tool.

5.8. Measure tool

Activating the measure tool disables the ability to pan the map while enabling the possibility to draw a line on the map and measure the line drawn.

The approximate (the distance is calculated without considering elevation deltas and with the coordinate picking precision of a finger on a screen) distance is shown in the upper part of the map view.

When active, the measure tool has a red colored icon, when inactive the icon is green instead.

12 measure tool
Figure 69. An example of qualitative measurement on the map.

6. The Map View Menu

The map menu provides access to some additional map tools:

  • access the GPS data list

  • access the Spatialite data list.

  • toggle the scalebar

  • open the compass

  • toggle automatic centering on the GPS position

  • center the view on the current base map (if possible)

  • go to a location

  • share the current position

  • view the data visible in the viewport in Mixare

  • import data from the underlying mapsforge map

13 map menu
Figure 70. The map menu.

6.1. GPS data list

The GPS data list shows the data surveyed, both points and tracks.

14 gpsdatalist
Figure 71. The GPS data view.

In the actionbar there are possibilities to select all, unselect all and merge selected logs. The first icon from left is the notes properties button. From there some properties of the notes can be set.

Notes can be shown on the Map View as icons or as circular shapes. The size, color and opacity can be customized by the user. This can be useful in those cases in which many notes have to coexist in a small space for better readability.

It is also possible to show the label for the note and customize its size and halo.

15 notes properties
Figure 72. The notes properties view.

The list of GPS logs gives the possibility to customize the logs. It is possible to change the visibility of the single track using the checkbox. The icon on the right side of each entry opens the GPS log properties panel:

16 log properties
Figure 73. The GPS log properties panel.

From the properties panel it is possible to:

  • change the name of the track

  • check the start and end date and time

  • update and read the track length

  • enter the track style panel to change stroke and fill

  • zoom to the first or last point of the track in the map view

  • chart the track. The chart has two axes, speed [km/h] on the left and elevation [m.s.l.] on the right.

17 chart log
Figure 74. The GPS log chart.
  • remove the track

6.2. Spatialite data list

The Spatialite data list view holds the list of loaded Spatialite databases. For each database its spatial tables are shown and each table can be made visible or hidden through the checkbox on each entry.

The rendering order can be changed through a combobox at the left side of each entry.

New databases can be added through the 2 buttons at the bottom of the view, by single file or folder.

To remove a database longtap on its entry.

18 spatialite data list
Figure 75. The list of spatialite based data.

At the right part of each entry a menu is available, which allows the user to change the style and labeling of the features in the layer, as well as its stroke dash and zoom level visibility. It is also possible to zoom to a given layer extent.

6.3. Go to

The go to function has two possibilities:

  • go to coordinate

  • use geocoding and/or routing

19 goto1

In the go to coordinate panel it is possible to insert lat/long coordinates and navigate to the inserted point on the map view:

20 goto coord

Through geocoding it is possible to insert some address and find its location (uses Google Maps geocoding service).

21 goto point

From the same panel it is possible to create a route from the current position to the inserted location.

The routing service used is OSRM.

Once the Routing button is tapped, the route is calculated by the service starting from the current map center to the destination point. The route is then downloaded and placed in the GPS logs tracks.

24 route rome
Figure 76. The fresh downloaded route from Bolzano to Rome.

6.4. Share position

The share position entry opens the usual sharing dialog of Android:

If for example telegram is chosen, the sent link will look like:

26 telegram

6.5. Import mapsforge data

The mapsforge tiles are generated on the device from a particular vector format. This means that there are information available in the database. Problem is that, very very simply put, the information contained is extracted differently at different zoom levels, because in fact the library and the format have been done that way to allow best rendering performance.

But still it is possible to extract almost everything we see, which is nice.

Let’s see how this works. For this to work it is mandatory that the loaded background map is of type "map". Assume you have a job to do, are out in the field and want view information overlaid on the orthophoto images from the local WMS service.

Well, the map file you get from mapsforge looks like the following:

27 mapsforge1

Once the import mapsforge data has been chosen, its panel appears:

27 mapsforge2

From the view you can see that 2 types of data can be imported: points and ways.

6.5.1. Points

Since the points are often visible on a different zoomlevel then the current, also 3 zoomlevels below the current are investigated to extract data and double points are not considered. So if you start this at zoomlevel 16, you will also get 17, 18, 19. Since the same are at a different zoomlevel will have many more tiles, about 10000 tiles are read to import the data.

You can add a filter text to import only tags containing a given text or exclude all those containing the text.

Points are imported in the current project database and saved as forms notes containing all the values Openstreetmap has. As such they can also be edited.

All imported notes have a (MF) in their name. That is done so one can quickly select and remove them. Believe us, that is a feature you want to have since such imports can generate very crowded notes lists.

27 mapsforge10
Figure 77. The notes list after a mapsforge import.

6.5.2. Ways

Many types of ways are stored in the mapsforge map files and many of them are actually related to areas.

The user can choose to import:

  • ways: roads, railways, cableways and similar

  • waterways: lines that represent water

  • contours: contour lines if they are available

Since these data are large, the data are imported into a dedicated Spatialite database. A database for mapsforge extracted data is automatically created if there is none present. You will find a database named mapsforge_extracted.sqlite always present in your maps folder. And you will find 3 layers always present in the Spatialite data layers: osm_waterlines, osm_roads and osm_contours.

27 mapsforge3
Figure 78. The mapsforge database and layer that host imported data.

Just select the data you want to import and push the start button. In the case you selected all data types, you should see first an import dialog like this:

27 mapsforge4
Figure 79. The mapsforge import dialog.

and then something like this:

27 mapsforge5

Depending on what has been imported first, the labels might not be coming from the right field. In that case it can be simply changed in the spatialite layer settings. Refer to the spatialite data list section.

7. Vector Editing

03 03 box
Figure 80. Vector Editing with Geopaparazzi

In the Map View you can create, view, and edit the geometry and attributes of point, line and polygon features held in a Spatialite database. You cannot edit geographic features in a Basemap. Editing a Project’s Notes, Bookmarks, and GPS logs are covered elsewhere in this manual.

If you need to create a Spatialite database, press the Import button on the Main View dashboard, and press Default Database (take note of the file name of your new database).

You can use your existing Spatialite databases by attaching them to the Map View by using the Map View menu item Spatialite data list.

7.1. Viewing Feature Attributes

After attaching a Spatialite database in the Map View, turn on the viewing of layers by checking the box next to the layer name.

02 spatialite
Figure 81. Displaying a layer

Back on the Map View, you will see the features (you may need to pan and zoom to them). To view the attribute values of features, press the Edit Tool button (it looks like a pencil) on the lower right of the Map View. That will cause the Feature Select button to appear on the lower left.

03 01 view
Figure 82. Feature Select Tool

Press the Select button then press and drag on the Map View to make a box surrounding the features you are interested in.

03 03 box
Figure 83. Selecting a Feature
To exit the Map View the Edit Tool button must be un-selected.

If there are any features in the box a Features dialog will appear showing the attribute names and values. If you’ve selected more than one feature, you can show their attributes by swiping on the Features dialog.

03 04 features
Figure 84. Feature Attributes

If there are any resource files (for example, images, PDFs ) associated with the feature, a camera icon will appear in the left of the Features Action Bar. Pressing on the camera icon will show a list of resources.

03 05 resources
Figure 85. Feature Resources

Pressing on the resource thumbnail image will show the full resolution of the resource.

03 06 photo
Figure 86. File Viewing

7.2. Editing Features

In addition to just viewing the features, you can edit the geometry and attribute values of features stored in a Spatialite database.

7.2.1. Select a Layer for Editing

To edit, attach a Spatialite database in the Map View and turn on the layer for viewing. Back at the Map View screen, do a long tap on edit button to show the list of layers available. Note if the layer is not turned on for viewing, the [pencil] edit button on the layer list will be black and unavailable to select for editing. Select the green edit button to indicate which layer you want to edit. The pencil icon will turn red showing the layer is ready for editing. Return to the Map View to start editing features.

Back on the Map View press the edit tool button. Depending on the geometry type of the editing layer various editing buttons will appear.

8. Settings & Preferences

The preferences page is divided into main categories:

01 settings
Figure 87. The settings view.

8.1. GPS Settings

02 gps
Figure 88. The GPS settings view.

In the GPS preferences it is possible to

  • define the time interval for taking a point when in logging mode

  • define the minimum distance in meters, within the taken GPS point is not added to the GPS log. This is useful for example in the case in which the user stops during logging and the GPS continues to supply points (due to the inaccuracy), while instead the user stands still in a point.

  • have the Map View re-centered on the GPS position when the position reaches the screen border (useful while driving)

  • use network based position instead of GPS position. This can be useful for testing purposes. The network based position is by no means precise!

8.2. SMS Settings

03 sms
Figure 89. The SMS settings view.

It is possible to activate an SMS catcher. If activated, the phone listens to incoming short messages containing the word:


If such a message comes in, the phone answers with an SMS to the incoming number by sending the last known position.

From here it is also possible to insert the panic numbers(s), i.e. the numbers to which a status update is sent when the panic button is pushed.

8.3. Screen Settings

04 screen
Figure 90. The screen settings view.

In the screen preferences it is possible to

  • change the map center cross properties (size, color, stroke width)

  • change the Mapsforge map text size factor (normal is 1. To make text bigger, increase the value)

  • enable the always screen on mode

  • toggle the use of metric/imperial units

  • enable settings to optimize rendering for high density displays

8.4. Spatialite Settings

05 spl recovery
Figure 91. The Spatialite settings view.

In the Spatialite preferences it is possible to enable the Spatialite Recovery Mode

When should Spatialite Recovery Mode be used?

When a new Database has been added and the geometry does not show up, the preference needs to be activated and Geopaparazzi restarted.

On restart faulty entries in the databases will be PERMANENTLY corrected where possible. Since the process might be time consuming, after a recovery, the settings is switched off again.

8.5. Force Locale

The locale of Geopaparazzi can be changed regardless of the locale used for Android.

This setting opens a menu in which a locale can be chosen between the available ones:

06 locale
Figure 92. The force locale dialog.

After that, each newly loaded view will be in the new locale.

8.6. Cloud server Settings

These settings allows you to set a Geopaparazzi Cloud Project server URL, Cloud Profile server URL, and optionally add a username and password. A Geopaparazzi Cloud Project server allows you to download and upload Geopaparazzi projects. A Geopaparazzi Cloud Profile server allows you to download Profiles along with the file they reference such as basemaps, Spatialite overlays, and project files.

Known Geopaparazzi Cloud Project servers are:

  • gvSIG Desktop with the hydrologis4gvsig plugins installed

  • gvSIG Online

Known Geopaparazzi Cloud Profile servers are:

9. Supported datasets

Geopaparazzi’s Map View supports several map types: vector or raster, editable or static. Also, maps can be pulled live from an Internet server, or be generated locally from a map data file for off-line operation. You can switch between these modes in settings.

There are two types of maps in Geopaparazzi:

  • basemaps: the background map in the map view

  • overlay maps: vector maps that can be shown on top of the basemaps

The following sections will detail various map source types. In case you want to prepare tailored map datasets as map sources in one of below map formats, please refer to the data preparation section.

9.1. A word about "external" storages

From Android version 4.4 (codename KitKat) it is no longer allowed for applications to write to userinstalled MicroSD cards. Instead applications can still write to internal memory (often seen as sdcard also).

An external user-installed sdcard appears to geopaparazzi as readonly. Datasets copied on the sdcard on a pc can therefore only be accessed in readonly mode and will create crashes if the user tries for example to modify a feature attribute.

One less known thing is that if the data are kept inside the application’s data folder, they can be accessed in read/write mode.

So for example, if one puts the dataset in the folder:


it will be handled as if it was in the internal memory.

9.2. Basemaps

Basemaps can be of 4 different types:

  • mapurls

  • mbtiles

  • Mapsforge maps

  • rasterlite2

9.2.1. Mapurls: Custom tiles based maps

Mapurl files are simple text files containing definitions of tile sources, either local or remote. A mapurl file must have the file extension/suffix .mapurl to be recognized by Geopaparazzi.

Remote Tile sources

By default, Geopaparazzi is configured to load map Mapnik rendered tiles live from the Internet, from OpenStreetMap’s tile server. Compare the contents of the included mapnik.mapurl file for how this is done. You can exchange the OSM tile server with any other tile server as long as it adheres to the Mapurl URL conventions. The basics are:

center=11.42 46.8
description=Mapnik - OpenStreetMap and contributors, ODbL.

The mandatory information is:

  • the url of the tile server, having:

    • ZZZ instead of the zoom level

    • XXX instead of the tile column number

    • YYY instead of the tile row number

This information can be tested also in a browser http://tile.openstreetmap.org/9/271/182.png has ZZZ=9, XXX=271 and YYY=182
  • the minimum zoom level that is supported

  • the maximum zoom level that is supported

  • the center of the tile source

  • the type of tile server. Currently both standard TMS and Google Maps based numbering of the tiles is supported by the line:

    • type=tms

    • type=google

  • the backup mbtiles path. This one is used to save downloaded tiles in the local mbtiles database

The user needs to make sure that the backup mbtiles path is in a writable folder (see a word about "external" storages) or else crashes might occur.

Also WMS works as remote source, as long as it can be accessed through an EPSG:4326 projection.

An example for the URL part is

Important here are:

  • SRS=EPSG:4326


Geopaparazzi will cache/store downloaded Mapurl tiles in a local MBTiles SQLite file, so pre-fetched tiles will remain viewable when Geopaparazzi is operated disconnected from a remote Mapurl source (in off-line operation).

Local Tile sources

Just like your mapurl configuration may reference an on-line/remote tile sources, your mapurl setting may reference a local tile source for off-line use. This way it’s possible to load on any smart phone complex maps as for example the following map that has a technical basemap with shapefiles overlaid in transparency

To be able to load such maps, one needs to prepare the tiles properly. This can be done via in several ways as explained in the data preparation section.

The tile folder have then to be loaded in the same folder as the description of the tile source:

center=11.40553 46.39478

Nothing changes against the description for the remote source apart of the URL. The URL in this case represents the relative path of the tiles folder.

Filesystems are known to have problems in handling large amounts of very small files. This the exact case of local tile sources. If the dataset is large, it gets very hard to move the data from and to the device. Therefore this method, even if still supported, is flagged as deprecated. The MBTiles datasource, explained in the next section, should be used instead.

9.2.2. MBTiles

MBTiles is a file format for storing map tiles in a single file. It is, technically, a SQLite database. See the openstreetmap wiki for more information.

9.2.3. Mapsforge maps

The mapsforge project provides free and open software for the rendering of maps based on OpenStreetMap. It developed an efficient binary format for storage of OSM map data (usually with file extension .map), and is offering country specific .map files for download. Geopaparazzi is able to render map tiles locally from .map files and will cache rendered tiles in a local MBTiles store.

Apart from Mapsforge itself, openandromaps is also offering .map files but with a different data bias and different render theme.


These are the standard maps generated, maintained and distributed by the mapsforge team and can be downloaded from their server.

In their default style they kind of look like:

01 mapsforge maps
Figure 93. The standard mapsforge map.

Openandromaps generates maps following the opencycle theme, with isolines and more hiking related stuff. The map files are larger but worth every byte. Their download area is here.

With the Oruxmaps theme that is available from the download area, the maps look like:

02 cycle maps
Figure 94. The openandro styled mapsforge map.
Apply a render theme

When rendering mapsforge tiles locally, Geopaparazzi applies render themes if they are found on the disk. In order to be found, the render theme XML file needs to have the same name as the map file. Ex, the above cycle map example has a:


and a:


render theme file in the same folder as the map file itself.

9.2.4. RasterLite2

RasterLite2 is a raster format implemented in the spatialite database.

At the time of writing it is released as development version and supported in Geopaparazzi for testing.

9.3. Overlay maps

The only datasets that can be overlaid on top of basemaps are vector maps coming from a spatialite database.

10. Handling datasets from and for Geopaparazzi

Several applications can be used to prepare and evaluate datasets for Geopaparazzi. The current ones known are:

  • gvSIG


  • QGIS

  • Spatialite GUI

  • GDAL

10.1. STAGE 0.7

STAGE (Spatial Toolbox And Geoscripting Environment) is a standalone application dedicated to spatial analyses.

Related to Geopaparazzi, it contains functionalities to:

  • Create mbtiles files from raster and vector sources.

  • Export geopaparazzi projects (version 3 or 4) to shapefiles, notes, profiles, and other details.

  • Convert geopaparazzi projects from version 3 to version 4.

10.1.1. Installation

STAGE can be downloaded from the github releases page.


  • copy the zip file in a folder:

    • stage_0.7_win64.zip for 64 bits Windows operating systems

    • stage_0.7_win32.zip for 32 bits Windows operating systems

    • stage_0.7_lin64.zip for 64 bits Linux operating systems

  • unzip the file in a folder

  • enter the unzipped folder

  • run the Stage application (ex. stage.exe for windows)

01 stage
Figure 95. The Stage application on windows.

The mobile section contains modules related to Geopaparazzi.

02 stage
Figure 96. The mobiles section.

10.1.2. MBTiles creation

For the creation of an MBTiles file from a set of GIS data, as shapefiles and tiff rasters, select the module: GeopaparazziMapsCreator

03 stage

The user will be able to add:

  • up to 2 raster tiff or asc maps

  • up to 5 vector shapefiles

  • define the name of the new mbtiles dataset

  • define the minimum and maximum wanted zoomlevel (zoomlevels > 18 start to take long time to build because of the large number of tiles generated)

  • the image type to use:

    • jpg: this should be used when photographic data are used (ex. aerial images)

    • png: this should be used when images are used (ex. technical maps)

  • the output folder, inside which the database will be created

Once the parameters are set, the module can be launched by pushing the green play button in the top right toolbar.

In case of big data the user should consider to set the memory put available to the run module. This is done in the lower left combobox labeled Memory [MB]. The number to set is considered to be MegaBytes. A safe value to use is a bit less than the amount of RAM available on the computer.

For windows 32bit machines it is not possible to use more than 1000 MB due to technical limitations of Java itself.

10.1.3. Conversion of Geopaparazzi data to GIS data

Through the module Geopaparazzi4Converter it is possible to export data from a Geopaparazzi project database.

04 stage

The only parameter to set are the input Geopaparazzi database path and the output folder. It is also possible to toggle the creation of some of the data contained in the database.

To run the module, refer to the mbtiles section.

How are the data are exported from the Geopaparazzi database? The following is created:

  • point shapefiles for each type of note also complex forms

  • point shapefiles with reference to pictures taken and sketches

  • all pictures are exported to a media folder

  • line and points shapefiles for log lines and points

  • profile charts and csv of log data

  • a simple text project metadata file

10.2. QGIS

Using plugins, QGIS can import Geopaparazzi databases and create mbtile base maps. At the time of writing (July 2018), QGIS 3 is newly released and most of the plugins that work with Geopaparazzi files have not been ported over from QGIS 2.

10.2.1. Importing Data with QGIS 2

ExportGeopaparazzi Plugin

Install the ExportGeopaparazzi plugin from the QGIS repository. As this plugin is experimental, go to Settings in the Manage and Install Plugins dialog and check the Show also experimental plugins checkbox, or the plugin will not be displayed in the list of available plugins. The plugin actually mainly imports data from gpap files and displays the data in memory layers. Separate layers are created for bookmarks, gpslogs, image positions and notes. Memory layers are not saved by default when the project closes so important data will need to be saved as another format. Additionally the notes layer includes all types of note. A single SVG symbol is used for all types of note. To generate different symbols for different types of note, the symbol type will need to be changed as the SVG symbol used comes in only one color. As all types of note are listed in the same layer, the attribute table does not have separate columns for each form field. All form data is presented in the style column in JSON format. Information imported this was is only useful for viewing.

GPAP to Vector Files Process

Algorithms for importing or export to Geopaparazzi can be added to the processing toolbox. The GPAP to Vector Files algorithm creates separate layers for each type of note, and creates layers for bookmarks, image positions and tracklogs. The algorith also saves images embedded in the gpap file to disk. Attribute tables for each type of note have columns for each data field collected by the note. If these layers are persisted, by saving them or dragging into a database (or saving as a shapefile), they can be used for GIS mapping and analysis. Geopackages are the current standard data format for QGIS and have the advantage of not truncating the names of forms or form fields, so save in this format if possible. The algorithms are installed with the ExportGeopaparazzi plugin, however the algorithms are not made visible by default. To make the tools visible, open the Procession\Options menu, click providers option and then open the Import/Export to/from Geopaparazzi option and activate the algorithms.

01 qgis

10.2.2. Viewing Data in QGIS 3

QGIS 3 does not at the time of writing (July 2018) have any gpap file importers. A workaround is to change the extension of the gpap file to sqlite3. The sqlite file can then be dragged and dropped onto the map window. The ‘Select Vector Layers to Add’ dialog will appear and all of the data tables will be displayed, including tables that are irrelevant from a GIS perspective such as the raw photo data table. Only the bookmarks, gpslogsdata, images and notes table contain data with coordinates. Select these tables and OK the dialog to add them to the Layers pane as non-spatial tables. Non-spatial tables can only be viewed as attribute tables and cannot be used as map layers.

To convert non-spatial tables to GIS layers, use the Create Points Layer from Table tool in the processing toolbox. Even the gpslogsdata must first be converted to points. To create a gps trail, the point layer created from the gpslogsdata can be processed with the Points to Paths algorithm. Currently, there are no tools for creating separate layers for each form type. Form data, is encoded in json format in the Forms field and there is no way to format the data to make it easily readable. However the various types of form can be symbolised differently using the form name, which is stored in the ‘text’ field. This method is useful for seeing gps trails and where various form notes were created.

02 qgis

QGIS 3 can also be used as viewer for kmz files produced by Geopaparazzi although is it not quite as good as GoogleEarth. Add the kmz file to QGIS 3 and use map tips to display the data associated with each point in a popup. If the map tips are based on the description field, which contains html, then the map tips will render the html and present a formatted report for the current data point.

10.2.3. Other Alternative Import Methods

QGIS users can also install GV-SIG and use the Horton Machine spatial toolbox to convert gpap files to shapefiles which can be used in QGIS.

10.2.4. Making Base Maps in QGIS

The QTiles plugin in QGIS 2 can be used to create base maps in mbtiles format. Base maps with as many as 30 000 tiles (~3 GB file size) work well in Geopaparazzi.

10.3. Spatialite GUI

The Spatialite GUI can be used to create spatialite databases from shapefiles.

You can find the application on the spatialite homepage, at the time of writing a good version for windows is version 1.7.1 available in this download area.

Open it and find yourself with:

01 spl

We now create a new empty database in which to load the shapefile data:

02 spl

You will be asked to save the database somewhere on disk. Once done, you should find yourself with something like this, but with different path:

03 spl

To then load a shapefil, locate the Load Shapefile icon:

04 spl

In this example I will import a set of shapefiles from the Natural Earth dataset, in particular the following ones:

05 spl

The import dialog is the important one to fill the right way:

06 spl

The really important things to take care of, are underlined in red:

  • the SRID, i.e. the EPSG code of the data projection. If that one is not right, then you will not be able to see the data in geopaparazzi. Don’t even hope in miracles!

  • the Charset Encoding. Make sure to choose the right one. For example Japanese people might want to choose SHIFT_JIS if they want to see the labels rendered properly

  • force the creation of the spatial index

If you then the push the ok button, you should find yourself with an ok message like this after the import:

07 spl

You are almost there, one last step to go.

Right-click on the database name and select the Update Layer Statistics command.

08 spl

Depending on the amount of data it should keep your harddisk working for a bit. Don’t think it finished unless you see a result like the following:

09 spl

Once this result appears to you, you are good to go.

Move the spatialite database to your device, fire up geopaparazzi and go directly to the spatialite data view and load the database.

10.4. OGR

OGR2OGR can be used to create Spatialite databases supported by geopaparazzi using different datasources.

The command that can be used is similar to:

ogr2ogr -f "SQLite" -t_srs "EPSG:3857" -dsco SPATIALITE=YES output_ortrans.sqlite ORTrans_public.gdb
More info available here

10.5. GDAL

Geopaparazzi does not support reprojecting raster data sources on-the-fly, so the file must be warped to the proper projection before using it. To do it you can use gdalwarp command.

The target projection must be Google Web Mercator (EPSG code 3857); you must know also the source projection of the raster you are converting. As an example, if you have a WGS 84 projected (EPSG code 4326) input file, you will run this kind of command:

gdalwarp -s_srs EPSG:4326 -t_srs EPSG:3857 -r bilinear input.tif output.tif
To create the tiles you can use gdal2tiles.py script, using as input your Google Web Mercator projected raster file
gdal2tiles.py output.tif

It generates directory with TMS tiles, that you can use in Geopaparazzi. In the root of the this directory you will find "tilemapresource.xml" file which contains all the information to build the .mapurl file:

    <?xml version="1.0" encoding="utf-8"?>
    <TileMap version="1.0.0" tilemapservice="http://tms.osgeo.org/1.0.0">
      <BoundingBox minx="46.39742402665929" miny="11.28858223249814" maxx="46.45081836101696" maxy="11.37616698902041"/>
      <Origin x="46.39742402665929" y="11.28858223249814"/>
      <TileFormat width="256" height="256" mime-type="image/png" extension="png"/>
      <TileSets profile="mercator">
        <TileSet href="12" units-per-pixel="38.21851413574219" order="12"/>
        <TileSet href="13" units-per-pixel="19.10925706787109" order="13"/>
        <TileSet href="14" units-per-pixel="9.55462853393555" order="14"/>
        <TileSet href="15" units-per-pixel="4.77731426696777" order="15"/>
        <TileSet href="16" units-per-pixel="2.38865713348389" order="16"/>
        <TileSet href="17" units-per-pixel="1.19432856674194" order="17"/>
        <TileSet href="18" units-per-pixel="0.59716428337097" order="18"/>

Note that the BoundingBox and Origin values created by gdal2tiles are have x and y values switched against how we need them:


11. Synchronization of Geopaparazzi datasets in the cloud

This section is dedicated to workflows/methodologies and applications that allow to synchronize geopaparazzi data in the cloud.

Only free and open source applications are listed here with a description on how to install and configure them.

If you know of any applications that is not yet listed, please let us know.

11.1. Cloud Profiles

Cloud Profiles are a great way of easing Geopaparazzi’s data handling tasks. When a web server is configured to serve Cloud Profiles, Geopaparazzi can automatically download Projects, Basemaps, Spatialite Overlays, forms for Notes, and other files. When a user activates a downloaded Profile, Basemaps are made available, Overlays are attached to the Map View and layers are set to display.

The Geopaparazzi workflow is:

11.1.1. Cloud Profile JSON

Shown below is a sample Cloud Profile JSON file containing two Profiles: Vienna and Bolzano.

{"formatVersion": 1.1,
  "profiles": [
      "name": "Vienna",
      "description": "Map Demo",
      "creationdate": "2017-07-24 14:16:28",
      "modifieddate": "2018-04-09 13:00:00",
      "color": "#FBC02D",
      "active": true,
      "sdcardPath": "MAINSTORAGE",
      "mapView": "48.2129,16.3663,15.0",
      "project": {
        "path": "/geopaparazzi/data/demo/vienna/geopaparazzi_trip_vienna.gpap",
        "modifieddate": "2018-01-24 13:00:00",
        "url":       "http://MyServer/download/geopaparazzi/data/demo/vienna/geopaparazzi_trip_vienna.gpap",
      "basemaps": [
          "path": "/geopaparazzi/data/demo/vienna/orthofoto_vienna.mapurl",
          "modifieddate": "2018-01-24 13:00:00",
          "size": "267"
      "spatialitedbs": [
          "path": "/geopaparazzi/data/demo/vienna/wfs_vienna_db_3857.sqlite",
          "modifieddate": "2018-04-09 13:00:00",
          "url":       "http://MyServer/download/geopaparazzi/data/demo/vienna/wfs_vienna_db_3857.sqlite",
          "size": "9797632",
          "visible": ["monumfountain"]
      "otherfiles": [
          "path": "/geopaparazzi/data/demo/vienna/Josefstadt_isis_brunnen.JPG",
          "modifieddate": "2018-01-24 13:00:00",
          "url": "http://MyServer/download/geopaparazzi/data/demo/vienna/Josefstadt_isis_brunnen.JPG"
      "name": "Bolzano",
      "description": "Notes Demo",
      "creationdate": "2017-07-24 14:16:28",
      "modifieddate": "2018-04-09 13:00:00",
      "color": "#296139",
      "active": false,
      "sdcardPath": "MAINSTORAGE",
      "mapView": "46.661,11.437,9.0",
      "project": {
        "path": "/geopaparazzi/data/demo/bolzano/geopaparazzi_trip_bolzano.gpap",
        "modifieddate": "2018-01-24 13:00:00",
        "url":       "http://MyServer/download/geopaparazzi/data/demo/bolzano/geopaparazzi_trip_bolzano.gpap",
      "tags": {
        "path": "/geopaparazzi/data/demo/bolzano/bolzano_field_survey_en.json",
        "modifieddate": "2018-01-24 13:00:00",
        "url": "http://MyServer/download/geopaparazzi/data/demo/bolzano/bolzano_field_survey_en.json"
      "basemaps": [
          "path": "/geopaparazzi/data/demo/bolzano/mapnik.mapurl",
          "modifieddate": "2018-01-24 13:00:00",
          "url": "http://MyServer/download/geopaparazzi/data/demo/bolzano/mapnik.mapurl"
      "spatialitedbs": [
          "path": "/geopaparazzi/data/demo/bolzano/wfs_bz_db.sqlite",
          "modifieddate": "2018-01-24 13:00:00",
          "url": "http://MyServer/download/geopaparazzi/data/demo/bolzano/wfs_bz_db.sqlite",
          "visible": ["administrativeunit"]

11.1.2. Cloud Profile Server

If you look at the sample Cloud Profiles in the previous section, you will see that the URLs for the files are fairly simple. This allow the Cloud Profile server to a generic files server or your own web server with more sophisticated features such as username/pasword access, URL re-writing, spatial database creation and more.

Using Generic Cloud Servers

You can set up your own Cloud Profile server by putting your files on a generic cloud file server like Dropbox or Google Drive, and editing a Cloud Profiles list like the one above and putting it on the cloud file server as well.

Geopaparazzi Cloud Server

A pre-configured Open Source Geopaparazzi Cloud Server is available. Have a look at A reference server for geopaparazzi cloud profiles

11.2. The Geopaparazzi Survey Server

The Geopaparazzi Survey Server (GSS) is a web application with a companion Android/Desktop utility application that allows users to synchronize geopaparazzi survey projects. Notes, GPS Logs and Media are sent to a central server using the ID of the device.

Read more about GSS in this section of the documentation.

12. Geopaparazzi & gvSIG

The most updated tools for geopaparazzi inside a GIS are the ones that are found in the open source GIS gvSIG, since they are maintained by the same team that develops geopaparazzi.

A quickstart guide about the installation of the right plugins and the available functionalities can be found on the plugin’s website.

13. Using form based notes

Geopaparazzi supports complex notes called form based notes. To use them, a tags.json file needs to be created and placed inside the geopaparazzi folder inside the sdcard. In that file a json format description of the wanted tags and forms needs to be placed.

By default, to help the user to start, a sample tags.json is created in the Geopaparazzi installation. It contains form samples and examples to show all supported form widgets.

01 tags

Currently no tool is available to create forms in an interactive way, they have to be created manually.

A good online tool to at least validate your json form is the Json Lint Validator. Make sure it passes that test before putting it on the device and test it in geopaparazzi.

13.1. Supported tags (via the example form)

The example form that is available by default shows all the possible options available.

13.1.1. Text

      "formname": "text",
      "formitems": [
              "key": "some text",
              "value": "",
              "type": "string"
02 text

13.1.2. Multiple Text

      "formname": "multiple text",
      "formitems": [
              "key": "some text",
              "value": "text1; text2; text3",
              "type": "dynamicstring"
03 text multi

13.1.3. Text with key and label

In simple forms the key element is also used as label for the widget (ex. some text in the text note). Some character sets are not suitable to be used as keys for a database, so in that cases the user should consider to define both the key (ex. in English) and the label (in the own language). Here an example:

"formname": "text example with key and label",
"formitems": [
        "key": "the_key_used_to_index",
        "label": "the label used to describe",
        "value": "",
        "type": "string"
03 text key

13.1.4. Numbers

"formname": "numeric text",
"formitems": [
        "key": "a number",
        "value": "",
        "type": "double"
        "key": "an integer number",
        "value": "",
        "type": "integer"
04 numeric

To use one of the values as label in the map view add the islabel tag:

"formname": "numeric text used as label in map",
"formitems": [
        "key": "a number",
        "value": "",
        "islabel": "true",
        "type": "double"
        "key": "an integer number",
        "value": "",
        "type": "integer"

13.1.5. Date

"formname": "date",
"formitems": [
        "key": "a date",
        "value": "",
        "type": "date"
05 date

13.1.6. Time

"formname": "time",
"formitems": [
        "key": "a time",
        "value": "",
        "type": "time"
06 time

13.1.7. Labels

"formname": "labels",
"formitems": [
        "value": "a simple label of size 20",
        "size": "20",
        "type": "label"
        "value": "a underlined label of size 24",
        "size": "24",
        "type": "labelwithline"
        "value": "a label with link to the geopaparazzi homepage",
        "url": "http://www.geopaparazzi.eu",
        "size": "20",
        "type": "labelwithline"
07 labels

13.1.8. Checkbox

"formname": "boolean",
"formitems": [
        "key": "a boolean choice",
        "value": "",
        "type": "boolean"
08 boolean

13.1.9. Combos

"formname": "combos",
"formitems": [
        "key": "a single choice combo",
        "values": {
            "items": [
                {"item": ""},
                {"item": "choice 1"},
                {"item": "choice 2"},
                {"item": "choice 3"},
                {"item": "choice 4"},
                {"item": "choice 5"}
        "value": "",
        "type": "stringcombo"
        "key": "a multiple choice combo",
        "values": {
            "items": [
                {"item": ""},
                {"item": "choice 1"},
                {"item": "choice 2"},
                {"item": "choice 3"},
                {"item": "choice 4"},
                {"item": "choice 5"}
        "value": "",
        "type": "multistringcombo"
        "key": "two connected combos",
        "values": {
            "items 1": [
                {"item": ""},
                {"item": "choice 1 of 1"},
                {"item": "choice 2 of 1"},
                {"item": "choice 3 of 1"},
                {"item": "choice 4 of 1"},
                {"item": "choice 5 of 1"}
            "items 2": [
                {"item": ""},
                {"item": "choice 1 of 2"},
                {"item": "choice 2 of 2"},
                {"item": "choice 3 of 2"},
                {"item": "choice 4 of 2"},
                {"item": "choice 5 of 2"}
        "value": "",
        "type": "connectedstringcombo"
        "key": "two connected combos, default selected",
        "values": {
            "items 1": [
                {"item": ""},
                {"item": "choice 1 of 1"},
                {"item": "choice 2 of 1"},
                {"item": "choice 3 of 1"},
                {"item": "choice 4 of 1"},
                {"item": "choice 5 of 1"}
            "items 2": [
                {"item": ""},
                {"item": "choice 1 of 2"},
                {"item": "choice 2 of 2"},
                {"item": "choice 3 of 2"},
                {"item": "choice 4 of 2"},
                {"item": "choice 5 of 2"}
        "value": "items 2#choice 4 of 2",
        "type": "connectedstringcombo"
09 combos

13.1.10. Pictures

"formname": "pictures",
"formitems": [
        "key": "a picture archive",
        "value": "",
        "type": "pictures"
10 pictures

13.1.11. Sketches

"formname": "sketches",
"formitems": [
        "key": "a sketches archive",
        "value": "",
        "type": "sketch"
11 sketches

13.1.12. Map screenshot

"formname": "map",
"formitems": [
        "key": "an image of the last seen map",
        "value": "",
        "type": "map"

13.2. Other supported tags

13.2.1. hidden

Not shown in the gui, but useful for the application to fill in info like the GPS position:

    {"key":"LONGITUDE", "value":"", "type":"hidden"}

13.2.2. primary_key

An item of particular importance, can be used by the application to link to particular info:

    {"key":"tourism", "value":"", "type":"primary_key"}

13.2.3. Constraints

Constraints are conditions that are checked when the OK button of the form is pushed.


To make an item mandatory, just add:

    "mandatory": "yes"

To peform a range check on a numeric field you can add something like:


which would check that the inserted number is between 0 (inclusive) and 10 (exclusive).

13.3. Create a simple form to map fountains

As an exercise we will now create a simple form to map fountains.

13.3.1. Sections

Every form is composed of sections, each of which create a button in the add notes view. We want to create a form for a fountain, so one section is enough. The blueprint for such a form, i.e. the empty button shell starts with:

        "sectionname": "fountain",
        "sectiondescription": "fountain",
        "forms": [

and ends with:


13.3.2. Form subsections

Each section can contain several sub-forms, that will create a tab each.

A sub-form starts with:

                "formname": "General data",
                "formitems": [

and ends with:


Note that the comma at the end is only needed if more than one sub-form is added.

13.3.3. Form elements

To add content to the sub-forms, any of the tags described in the supported tags section can be used.

For example lets add two text fields to prompt the user for a name and street. Also the name should then be the label rendered in the map view.

                        "key": "name",
                        "value": "",
                        "islabel": "true",
                        "type": "string",
                        "mandatory": "yes"
                        "key": "street",
                        "value": "",
                        "type": "string",
                        "mandatory": "no"

13.3.4. Finalize the form

This is everything that needs to be done. Let’s also add some technical data in a dedicated tab and also a tab for media, inside which it is possible to take pictures.

We leave the exercise to the reader.

The complete tags.json file can be found in the appendix section.

14. Geopaparazzi Tables

14.1. Geopaparazzi Project Database Tables

The Geopaparazzi Project Database is a plain SQLite v3 database with the extension .gpap. It contains all the data collected during a Geopaparazzi session, such as GPS tracks, notes (including images), and bookmarks.

All coordinate data are saved in WGS84 horizontal spatial reference system. The elevation data saved by Geopaparazzi is as reported by the GPS library for the device and is likely the height relative to the WGS84 ellipsoid and not a vertical datum or some other spatially varying surface like Mean Sea Level.

database diagram
Figure 97. Overview diagram of database tables

14.1.1. Using Geopaparazzi Timestamps

Geopaparazzi stores timestamps (e.g. columns named "ts" in the tables below) as long integers and represent Unix Epoch, but instead of seconds the value is in milliseconds.

To make the values more readable, they can be decoded in SQLite like so (note the dividing by 1000 to change the milliseconds into seconds):

  SELECT _id, ts, datetime("ts"/1000, "unixepoch") timestamp FROM notes;

results in:






2014-12-23 00:03:46

Typically the values must be decoded into a standard format like ISO 8601 to be used in other applications. The values can be decoded in SQLite like so (note the dividing by 1000 to change the milliseconds into seconds):

SELECT ROWID, ts, strftime( '%Y-%m-%dT%H:%M:%SZ',datetime("ts"/1000, 'unixepoch')) timestamp FROM notes;

results in:







You can also create SQL Views to persist the above query in the database.

  SELECT *, strftime( '%Y-%m-%dT%H:%M:%SZ',datetime("ts"/1000, 'unixepoch')) timestamp FROM notes;

SELECT * FROM v_notes;

14.1.2. Geopaparazzi Table Descriptions

Table 1. The metadata Table


key for the record


text for dialog label


value for the record

This table holds 7 standard rows of the various Project information such as the Project name. You can add your own metadata rows using the Project Info dialog in Geopaparazzi or using SQL.

Table 2. The notes Table


unique id


longitude of the note, decimal degrees


latitude of the note, decimal degrees


elevation, meters


timestamp, "unixepoch" in milliseconds


description of the note


text/type of the note


the form data, JSON


is dirty field (0 = false, 1 = true) (not used)


style of the note (not used)

Style and isdirty are currently unused.
Table 3. The images Table


unique id


longitude of the image, decimal degrees


latitude of the image, decimal degrees


elevation, meters


azimuth, decimal degrees


foreign key to _id of the imagedata table


timestamp, "unixepoch" in milliseconds


file name of the image


optional foreign key to _id of the notes table


is dirty field (0 = false, 1 = true)

Table 4. The imagedata Table


unique id


the image data as a BLOB containing an JPEG image


the image thumbnail data as a BLOB containing an JPEG image

Table 5. The bookmarks Table


unique id


longitude of the bookmark, decimal degrees


latitude of the bookmark, decimal degrees


the zoom of the bookmark, Tile zoom levels


the north bound of the bookmark, decimal degrees


the south bound of the bookmark, decimal degrees


the west bound of the bookmark, decimal degrees


the east bound of the bookmark, decimal degrees


the name of the bookmark

Table 6. The gpslogs Table


unique id


log start timestamp, "unixepoch" in milliseconds


log end timestamp , "unixepoch" in milliseconds


the length in meters


is dirty field (0 = false, 1 = true)


name of the log

Table 7. The gpslogsdata Table


unique id


longitude of the log point, decimal degrees


latitude of the log point, decimal degrees


elevation of the log point, meters


timestamp of the log point, "unixepoch" in milliseconds


foreign key to _id of the gpslogs table

Table 8. The gpslogsproperties Table


unique id


foreign key to _id of the gpslogs table


the color to use to draw the log, text like "red", etc


the width to use to draw the log, in pixels


flag that defines if the log is visible at the time given

Table 9. The log Table


unique id


row timestamp in milliseconds


log message

The log table contains rows created by Geopaparazzi as you use its various functions, primarily for troubleshooting any problems. You can view the log table in Geopaparazzi by selecting the menu in the main dashboard view and selecting Advanced, the select "Analyze log". By default it shows the "Error" class messages.

14.2. Additional Geopaparazzi tables in Spatialite Databases

If these tables are present in a Spatialite database used as a map overlay, they can supply additional properties to the Spatialite data.

Table 10. The dataproperties Table


unique id


source of the geometry, format: database_path#table#column



fill color in HTML-friendly form: e.g. red, #FBC02D, etc


outline color


0.0 to 1.0 value of opacity (0=fully transparent, 1=not transparent)


0.0 to 1.0 value of opacity (0=fully transparent, 1=not transparent)


allowed values: "square","cross",triangle","circle","star","X"


width of line


size of label in scaled pixels


field in feature table to get label text


is the label shown? 0=no, 1=yes




dashWidth, dashGap, dashWidth2, dashGap2, …​ in scaled pixels, e.g. 10,20


don’t show if current zoom level is less than this (see Tile zoom levels for values)


don’t show if current zoom level is greater than this



The dataproperties table is useful for providing persistent styling of features stored in the Spatialite database.

An example of a "name" value in the dataproperties table:

Table 11. The geopap_resource Table


unique id


feature table name containing the feature


foreign key value of the row in the feature table


Geopaparazzi data type of resource (e.g. BLOB_IMAGE, EXTERNAL_IMAGE, BLOB_PDF, EXTERNAL_PDF)


file name of resource. For labeling if resource is "BLOB_*"


path of resource file


if resource is "BLOB_*", contains the resource data as binary


contains a BLOB of a thumbnail of the resource to use as an icon

The geopap_resource table is used to relate resources like images, PDFs, etc to records in the Spatialite tables. See Viewing Feature Attributes

15. Use case: Use of Geopaparazzi in Egypt to create a map to improve the management of small wastewater treatment plants.

15.1. Introduction

Have you ever tried to type in google: sanitation maps, sanitation coverage, sanitation or inventory tracking?

It is interesting to note that the agencies managing the wastewater treatment plants in the United States and Canada monitor and continuously update the inventory of small delocalized plants in order to optimize their management, while the numerous development agencies that deal with sanitation in developing countries express and declare the state of inadequacy of the system of waste treatment but do not quantify the state of art.

The management of small treatment plants of domestic sewage in decentralized communities is an issue with different perspectives. In any place on earth it involves many actors, linking technical to cultural, environmental, educational and health services. It is a topic that often touches critical as well as hidden issues. Experts in this field are well aware of that!

When you think of a small village, a rural setting with a few houses and lots of animals, or a peri-urban area that grew quickly and without any planning or again neighboring communities linked by a waterway that carries waste from upstream to valley, it is not immediate to think that all these places (due to the presence of man and animal) are a source of biomass. They are a sources of waste and organic material that often brings a high and invisible pathogenic charge.

Many projects related to developing countries today focus the attention on the proper disposal of the waste and on prevention as fundamental for the health of the inhabitants. Numerous agencies and associations dedicated to development cooperation have shown that untreated wastewater spilled into the surrounding environment without any attention is the primary vector of diseases and therefore often of epidemics in areas with deficits at levels of hygiene and public health (see the Water, Sanitation and Hygiene and the Joint Monitoring Programme).

The target C of the seventh Millennium Development Goal aimed to halve by 2015 the proportion of people without sustainable access to safe water and basic health services. The assessment tool implemented in recent years has been the count of the percentage of population using the health service.


  • What is the scenario in terms of plants?

  • Where are they?

  • What do they produce?

  • How much?

  • What is the trend?

  • What are the possible risk factors?

  • What are the environmental characteristics of their location?

  • And the social context?

  • The cultural?

  • How many and which animals contribute?

  • What are the types of installations in operation?

It is clear that to get a complete picture of this kind takes time, lots of data collection, laboratory tests, and then hypothesis, correlations, ideas and possible strategies.

It is now well known that from a technical standpoint there are no prepackaged solutions exportable in contexts with very different boundary conditions. Some causes may seem trivial, but if underestimated they end up affecting the efficiency of the treatment.

It should be enough to say that there are places in the world where the toilet paper is not thrown into the toilet; there are places where after defecation you clean up with your hand; others where even plastic, cloth and diapers are thrown into the toilet and places in which under the sink there is a shredder and everything ends up into the sewer system.

These are information that decide the diameter of the pipes even before the type of treatment and planting. And if the diameter of the tubes is wrong the whole system becomes meaningless.

How many socio-cultural aspects exist in the various regions of the world that we do not know, that we can’t even imagine, that can make you smile or frighten, but that in the construction of a plant have the same weight as the distribution of BOD5?

There is no doubt that a tool that allows you to collect data of this kind, to catalog them, and most important geotag them to make them visible on a map and return the state of the existing as well as facilitates the correlation is crucial in the whole process of planning and improvement of health services in developing contexts.

15.2. Monitoring activities

During fall of 2010 Geopaparazzi has been used in the monitoring of small waste water treatment plants in decentralized communities of the Nile Delta, in a thesis project in Environmental Engineering within a larger project of technical development cooperation (ESRISS project).

The idea was to be able to do an effective analysis and mapping of the plants in the area of the Nile Delta to compare different types of treatment and analyze the parameters that contribute to the success or failure of a solution. The result of this campaign suggested the usefulness of this application and the need to widen its use to build the existing maps that consider all the complexity of the factors involved in the search for solutions to improve the health conditions of the contexts under analysis. Only in this way it is possible to build an updated database on the basis of which appropriate solutions can be proposed.

The main goal has been to integrate missing plants data.

To give an idea, information about the available data are shown for some of the plants:

07 plant1
Figure 98. The El Moufty plant, the one with most available information.
08 plant2
Figure 99. The OM SEN plant, with no lab information available and some general information missing.
09 plant3
Figure 100. The EL KOLEAAH plant, with no lab information available and some general information missing.

15.3. Technical background

Based on the available data a dedicated form has been designed to collect in a standardized way as much data as possible.

Once the form has been loaded into Geopaparazzi, it has been possible to access it from the add notes view.

01 tags
Figure 101. The add noves view, in an older version of geopaparazzi.

The form has been divided into 5 main sections to make it easier to read:

  • General data

02 general
  • Construction info

03 construction
  • Technical data

04 technical
  • Lab data: this section has been added even if it is quite impossible to gather lab data in the field. But since the form based notes can be opened and modified at any time, the section has been added for further update

05 lab
  • Media

06 media

The complete tags.json file can be found in the appendix section.

15.4. Acknowledgement


Focus has been put only on the data collection and form creation. It is beyond the scope of this document to describe or comment any other of the contents of Vania’s thesis.

Vania’s thesis also won the scolarship prize by ABL Premio Giovanni Lorenzin.

16. Projects that base on Geopaparazzi

16.1. gvSIG Mobile

gvSIG Mobile is completely based on geopaparazzi and extends its capabilities with enterprise level functionalities to connect to the services of gvSIG Online to allow synchronization of data between teams of surveyors.

gvsig mobile

16.2. Geomobi

Geomobi is a mobile GIS developed by team developer of Embasa (Empresa Baiana de Águas e Saneamento of State Bahia Brazil). The mobile app has maps with streets, water consumers, water supply network, and sewer network layers. These maps can be used in field services for various queries.

rede agua

16.3. Gasdroide - Natural Gas Emission Flux Measurements on Android platform

Checkout the homepage here


16.4. Disaster Management Information System

The Disaster Management Information System of the city of Osaka is mainly meant for collecting information about water-supply infrastructure to promote post-disaster recovery for water supply.


The same team has also been responsible for the Japanese translation of Geopaparazzi. Kudos!

16.4.1. TrashMapper

The TrashMapper is a tool used to keep information about the waste management of a town. Through it it is possible to sample and update information out in the field and then syncronize the data with a central database/webgis.


16.4.2. Trackoid

Trackoid is a mobile system for the geolocalization of small/medium fleets and teams of people (rescue). It is a realtime system with a mobile and server side.

trackoid mobile

trackoid 01

trackoid server

trackoid 02

16.4.3. Your app here

If you are using Geopaparazzi in any flavor we would be happy to list it here with some screenshot. Just drop us a note!

17. A small handbook for developers

17.1. Introduction

17.1.1. Getting the code

The whole source code of the Geopaparazzi project is available at its github site.

It can be downloaded into a local git repository with the following command from commandline:

git clone --recursive https://github.com/geopaparazzi/geopaparazzi.git

17.1.2. Building and developing Geopaparazzi

The authors suggest to use Android Studio for the build and development of the application.

Geopaparazzi is developed in pure java. The only native C libraries referenced in the project are th elibraries of spatialite. They are contained as libraries and therefore all development is done in pure java. Android currently supports all Java 7 language features and a subset of Java 8 language features that vary by platform version. At the time of writing the Geopaparazzi codebase only uses java 7 languagefeatures.

The project uses gradle as its build tool. The commandline can be used to assemble an installation package:

./gradlew assemble

In the case of building from commandline, it is necessary to insert the keystore informations to sign the installation package in a file named:


The format is the one of a simple key-value properties file:


17.2. Description of the Geopaparazzi Architecture

The Geopaparazzi application has been split in different modules, that contain functionalities that have been isolated.

The root source folder contains the main modules:

Contents of Geopaparazzi git root folder

While the folders extra, build and gradle are accessory folders, the other folders are all part of the application.

17.2.1. Modules dependencies diagram

The diagram shows the dependencies of the various modules:

modules diagram
Figure 102. Diagram of the main modules dependencies.
plugins diagram
Figure 103. The official Geopaparazzi plugins

17.2.2. geopaparazzilibrary

The Geopaparazzi Library module contains all the code that can be reused across applications. The different packages contained have been named to explain their content.

Many of the packages are not used in the geopaparazzi application, but have been contributed during several customizations that have been done during the years.

Below a short description of the most important packages:

  • bluetooth: bluetooth pairing and data transfer classes

  • camera: classes for taking pictures

  • chart: charting utilities

  • core: main activities and fragments that can be reused in different contexts

  • database: database helper classes

  • features: classes related to the vector editing engine

  • forms: package containing the form based notes classes

  • gps: the gps service package

  • gps: conversion from and to gpx

  • images: image utilities

  • kml: conversion from and to kml/kmz

  • locale: utilities to handle locale switch

  • network: network related utilities

  • nfc: near field communication package

  • permissions: classes to help with the android >6 permission system

  • plugin: package that contains the plugin engine classes

  • routing: classes that connect to online routing engines

  • sensors: utilities related to motion sensors

  • share: sharing utilities for social network or similar

  • sketch: outdated sketch support. Substituted by acrylicpaint

  • sms: utilities to send or intercept sms

  • style: style support classes

  • util: many utilities classes related to projection, debug, data types and similar

  • webproject: classes that support up/downloading geopaparazzi projects from and to a server

17.2.3. geopaparazzi_core

The core module contains all that is visible in Geopaparazzi. All the activities, views and fragments and all logic behind the user interaction.

This module is very specific to Geopaparazzi and us such contains the structure of the application, its preferences, the map view and database related code.

The main packages are:

  • database: database management classes

  • maptools: tools to work with vector editing

  • mapview: the map view and all its functionalities and overlayes

  • preferences: the preferences system

  • ui: all the core activities and fragments

This module is the visible heart of geopaparazzi. It makes large use of the geopaparazzi libraries as well as the other modules.

17.2.4. geopaparazzi.app

The geopaparazzi.app module has been created to create easily branded versions of Geopaparazzi. It is a thin wrapper around the Geopaparazzi Core module.

In fact it simply extends the core module by defining an empty main activity in its release package (the one then used in google play for example):

public class GeopaparazziActivity extends GeopaparazziCoreActivity {

By doing this it is simple to change the style (speak color and appearence) and the name of the application by just changing/extending the xml files in the resources folder.

17.2.5. geopaparazzimapsforge

Mapsforge is the mapping engine used in Geopaparazzi. While the project is going towards the release of version 0.8.0 at the current time, Geopaparazzi still bases on a customized version of the 0.3.1 version of mapsforge. The reasons for the lack of update is both technical and due to missing resources dedicated to this activity. The upgrade to version 0.8.0 would take a significand amount of time and huge code refactoring.

The module contains also the original mapsforge code on which several bug fixes have been backported and some customizations have been applied by HydroloGIS. As such this module is mandatory to allow Geopaparazzi to work with a map view.

The module also contains:

  • the classes to handle tiles. This means reading and writing of mbtiles, online TMS services through mapurl files.

  • the user interface classes to load mapsforge, mbtile, rasterlite2 and mapurl datasets. These are basically activities to browse the filesystem and load data and keep them ordered in a simple catalog.

17.2.6. geopaparazzispatialitelibrary

The Spatialite Library module contains several important pieces necessary to the main application.

As the name already describes, the spatialite vector part is handled in this module. It contains all the classes that define spatial tables and its geometries and attributes.

Data Access Objects are present for the different tabel types, as normal spatialite vector tables but also rasterlite2 and geopackage tables.

The same package also contains activities to browse and select spatialite databases and load them into the map view. Views are also available to change the order of the database layers visualized and change their properties in terms of style and labeling.

The spatialite module contains also 2 very important projects: jsqlite and jts

android-spatialite (jsqlite)

The package jsqlite contains the android-spatialite project, which exposes a simple API to load spatialite extensions and query a spatialite database using spatial queries.

This API is used in geopaparazzi to access any spatialite/rasterlite2 database.


The Java Topology Suite is a geometric java library very well known in the geospatial world. It could be said, that it is the first and only one used in the open source geospatial business, since the counterpart GEOS, which is used in most of the geospatial applications (gdal, postgis, spatialite), is an almost straight port from the java to the C++ language.

The JTS package in this module has been adapted by HydroloGIS in order to be usable in android. In particular all the AWT related classes have been replaced or removed, depending on the needs.

17.2.7. geopaparazzi_acrylicpaint

Acrylic Paint is the new choice for the drawing of sketches in Geopaparazzi. It is a very nifty and tiny project, well written and maintained in few classes. It makes the perfect fit to be used in Geopaparazzi.

This module contains the original classes of the Acrylic Paint project. They have been customized by HydroloGIS only to answer properly to the intent launched by Geopaparazzi and return the image drawn by the user the way Geopaparazzi needs it. Also teh style has been adapted to be aligned with the one of Geopaparazzi.

17.2.8. wms_nww

The WMS is a standard mapping service and is supported in Geopaparazzi using this module. The module is an adapted code from an older version of the Nasa World Wind Android application. It allows to query the getCapabilities of the Service and list the available layers, which allows th user to easily select a layer to visualize in Geopaparazzi.

Since the original code is releasesd under the Apache License, this module has been kept outside of the Geopaparazzi codebase. That is also the reason the git clone --recursive is necessary when checking out the project’s source code.

17.2.9. plugins

It is now possible to use plugins with Geopaparazzi. They ar enot dynamic plugins that can be installed aside of Geopaparazzi and then loaded into it. But it is possible to compile an custom version of Geopaparazzi with certain plugins enabled.

The official codebase of Geopaparazzi currently uses the plugins for all its import and export options.

Inside the plugins folder, at the time of writing 4 plugins are available:

Contents of plugins folder
  • geopaparazzi_default_export_plugins: Contains the export actions (and menu entries of the export view) that take care of bookmarks, gps, images and kmz

  • geopaparazzi_default_import_plugins: Contains the import actions (and menu entries in the import view) that take care of bookmarks, default databases, gps, wms and mapurls

  • geopaparazzi_projects_export_plugins: Contains the export action that allows to upload the current geopaparazzi project to a serverside application

  • geopaparazzi_projects_import_plugins: Contains the import action that allows to list geopaparazzi projects available on a server and then download a selected project to the device

The plugin system is very handy if, for example, it comes to data synchronization. A developer could implement his/her own version of data synchronization with an own servide application and create a set of plugins that take care of it inside geopaparazzi.

That developer could then create a custom build of Geopaparazzi (or whatever the name would be), remove the projects import/export plugins and add instead his/her own. The custom version would then present in the import/export views the new actions to synchronize with the selected server application. This brings to a very smooth integration.

18. Appendix

18.1. The finalized tags.json of the Forms section

        "sectionname": "fountain",
        "sectiondescription": "fountain",
        "forms": [
                "formname": "General data",
                "formitems": [
                        "key": "name",
                        "value": "",
                        "islabel": "true",
                        "type": "string",
                        "mandatory": "yes"
                        "key": "street",
                        "value": "",
                        "type": "string",
                        "mandatory": "no"
                "formname": "Technical data",
                "formitems": [
                        "key": "protected",
                        "value": "true",
                        "type": "boolean",
                        "mandatory": "no"
                        "key": "type",
                        "values": {
                            "items": [
                                    "item": ""
                                    "item": "manual"
                                    "item": "electrical"
                                    "item": "gravity"
                        "value": "manual",
                        "type": "stringcombo",
                        "mandatory": "no"
                        "key": "PH",
                        "values": {
                            "items": [
                                    "item": ""
                                    "item": "PH < 5"
                                    "item": "5 < PH < 7"
                                    "item": "PH > 7"
                        "value": "PH < 5",
                        "type": "stringcombo",
                        "mandatory": "no"
                        "key": "number of served people",
                        "value": "",
                        "type": "double",
                        "mandatory": "no"
                        "key": "is working",
                        "value": "true",
                        "type": "boolean",
                        "mandatory": "no"
                        "key": "needs",
                        "values": {
                            "items": [
                                    "item": ""
                                    "item": "nothing"
                                    "item": "maintainance"
                                    "item": "rehabilitation"
                        "value": "nothing",
                        "type": "stringcombo",
                        "mandatory": "no"
                "formname": "Media",
                "formitems": [
                        "key": "Images",
                        "value": "",
                        "type": "pictures",
                        "mandatory": "no"

18.2. Complete tag.json for the Egypt use case


        "sectionname": "WWT-plant",
        "sectiondescription": "WWT-plant",
        "forms": [

            "formname": "General data",
            "formitems": [

             "key": "Plant name",
             "value": "El Moufty Plant",
             "islabel": "true",
             "type": "string",
             "mandatory": "yes"
             "key": "Local Responsible Admin",
             "value": "Kafr el Sheikh",
             "type": "string",
             "mandatory": "no"
             "key": "District",
             "value": "Sidi Salim",
             "type": "string",
             "mandatory": "no"
             "key": "Village",
             "value": "El Moufty",
             "type": "string",
             "mandatory": "no"
            "formname": "Construction info",
            "formitems": [

             "key": "WWTP technology",
             "values": {
                 "items": [
                     {"item": ""},
                     {"item": "Stabilization ponds (GTZ model)"}                 ]
             "value": "",
             "type": "stringcombo",
             "mandatory": "no"
             "key": "Designed by",
             "value": "Prof M.Abdel Azeem",
             "type": "string",
             "mandatory": "no"
             "key": "Year of construction",
             "value": "",
             "type": "date",
             "mandatory": "no"
             "key": "Startup",
             "value": "",
             "type": "date",
             "mandatory": "no"
            "formname": "Technical data",
            "formitems": [

             "key": "Served population [inhab]",
             "value": "3000.0",
             "type": "double",
             "mandatory": "no"
             "key": "Plant capacity [m3/d]",
             "value": "450.0",
             "type": "double",
             "mandatory": "no"
             "key": "Surface [m2]",
             "value": "6000.0",
             "type": "double",
             "mandatory": "no"
             "key": "Pro capita inflow [m3/inhab d]",
             "value": "0.066",
             "type": "double",
             "mandatory": "no"
             "key": "Pro capita water use [l/inhab d]",
             "value": "111.0",
             "type": "double",
             "mandatory": "no"
             "key": "Inflow [m3/d]",
             "value": "200.0",
             "type": "double",
             "mandatory": "no"
             "key": "Outflow quality analysis",
             "values": {
                 "items": [
                     {"item": ""},
                     {"item": "monthly"},
                     {"item": "yearly"}                 ]
             "value": "",
             "type": "stringcombo",
             "mandatory": "no"
            "formname": "Lab data",
            "formitems": [

             "key": "PH",
             "values": {
                 "items": [
                     {"item": ""},
                     {"item": "PH < 5"},
                     {"item": "5 < PH < 7"},
                     {"item": "PH > 7"}                 ]
             "value": "PH < 5",
             "type": "stringcombo",
             "mandatory": "no"
             "key": "BOD in [mg/l]",
             "value": "",
             "type": "double",
             "mandatory": "no"
             "key": "BOD out [mg/l]",
             "value": "",
             "type": "double",
             "mandatory": "no"
             "key": "Coliforms in [mg/l]",
             "value": "",
             "type": "double",
             "mandatory": "no"
             "key": "Coliforms out [mg/l]",
             "value": "",
             "type": "double",
             "mandatory": "no"
             "key": "COD in [mg/l]",
             "value": "",
             "type": "double",
             "mandatory": "no"
             "key": "COD out [mg/l]",
             "value": "",
             "type": "double",
             "mandatory": "no"
             "key": "Suspended solids in [mg/l]",
             "value": "",
             "type": "double",
             "mandatory": "no"
             "key": "Suspended solids out [mg/l]",
             "value": "",
             "type": "double",
             "mandatory": "no"