1. SMASH, the free and open source digital field mapping for IOS and Android

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

SMASH is a digital field mapping application developed to perform fast qualitative engineering/geologic surveys and GIS data collection.

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

  • is open source and works both on IOS and Android

  • 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

main view

SMASH on the ipad

The main features available in SMASH are:

  • geo-referenced notes and pictures

  • gps track logging

  • form-based data surveys

  • easy export of collected data

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

  • geopackage (OGC standard) support

2020 03 31 08.19.45

SMASH on the IPhone.

Screenshot 20200331 120554

SMASH on the Android, Pixel 2 XL.

1.1. License

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

1.2. Community

SMASH is stricktly related to the older, more mature and andoird only app Geopaparazzi. For that reason they share the same channels and spaces.

Find out the latest SMASH news.

Join the Geopaparazzi user’s discussion!. Feel free to post also about SMASH.

And there’s a group for Geopaparazzi/SMASH developers too.

You can even contribute to this Geopaparazzi or SMASH manual!

1.3. Need help?

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

We also have a mailinglist for developers.

1.4. 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.5. Need features?

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

1.6. 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, Geopaparazzi and SMASH projects.

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

2. Installation

2.1. IOS

SMASH can be found on the Apple store. Since the word SMASH is used a lot in gaming apps, in order to avoid to have to scroll down many results, it is useful to insert in the search bar the complete name: SMASH Digital field mapping

In that case the right app is the first result in the list, apart of an Ad that in the below case shows a gaming app:

applestore1

The SMASH entry in the Apple store.

By tapping on it it is possible to find a description and some feature screenshots.

applestore2

Details of the SMASH app in the Apple store.

To install the app just push the GET button and follow the usual IOS installation instructions.

2.2. Android

2.2.1. From Google Play

SMASH can be found on the Google Play store. Since the word SMASH is used a lot in gaming apps, in order to avoid to have to scroll down many results, it is useful to insert in the search bar the complete name: SMASH field mapping

playstore1

The SMASH entry in the Google Play store.

By tapping on it it is possible to find a description and some feature screenshots.

playstore2

Details of the SMASH app in the Google Play store.

2.2.2. From the main repository

For people that have no access to Google Play, an apk has been paced under the releases page of SMASH. Under the assets section of each release there is also an apk file. That one can be manualli installed oin Android. Actually, if the link is accessed from within Android, the installation is proposed on clicking the link.

github release

Details of the github release page with the apk to download at the bottom.

3. The Main View

Once you launch SMASH, the main view appears.

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

main view

The main view of SMASH.

From the main view the following primary functions can be accessed:

  • open the GPS info tools

  • take notes and open notes list (for simple notes and form notes)

  • create a GPS log and open the logs list

  • open the layer view

  • open the project information and share dialog

  • open the left side drawer with the main menu

  • open the left side drawer with the tools section

3.1. GPS info button and tools

The central bottom button is the GPS info button.

The icon of the GPS status button can be of the following colors:

  • RED: GPS is not switched on

  • ORANGE: GPS is on but no fix was acquired

  • GREEN: GPS is on and has fix, but no log is being recorded

  • BLUE: GPS is logging.

By tapping on the button, if the GPS has a fix, the map is centered on the GPS position.

By long tapping on the button, the GPS info and tools are opened:

gps tools center on

The GPS info and tools.

From here the user can access the current GPS information and copy the coorinates into the device’s clipboard. It is also possible to enable centering the map on the GPS position.

3.2. Notes

SMASH supports different types of notes:

  • simple notes

    • simple text notes

    • simple picture notes

  • form-based notes

3.2.1. Simple Notes

To create simple notes tap on the first icon of the lower toolbar. The Simple Notes dialog appears, allowing to choose between text or image notes:

notes add

Adding simple notes to the project. The note will be placed in the map center.

The icon at the right of the dialog title tells the user whether the note will be inserted in the current GPS position or in the current map center.

notes add in gps

Adding simple notes to the project. The note will be placed in the current GPS position.

The decision between GPS position and map center can be toggled from the right side drawer.

When the text note entry is selected, the note properties view opens:

notes properties

The notes properties view.

By double tapping on the first table entry, it is possible to enter the text of the note.

Moreover it is possible to select color, size and icon for the note.

When the image note is used instead, the camera opens and allows the user to save a picture to the project.

If a note is tapped on from the map view, a snackbar opens, allowing to share, delete or edit the selected note:

notes snackbar

The quick note info snackbar.

If the note is an image note, a thumbnail of the note is shown.

3.2.2. Simple Notes List

By long tapping on the add note button, the notes list opens:

notes list

The notes list view.

From here notes can be modified or deleted (swipe note to the left).

3.2.3. Form based notes

The second icon from left on the lower toolbar is for form based notes.

notes add form

The add form note dialog. Icons are supported.

Form based notes allow you to take complex notes containing detailed information. Some example forms are included in the installation of SMASH.

The examples entry in particular shows all the possible form widgets available:

form text

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 dedicated section in the geopaparazzi project. The two projects share the exact same project and form format.

There ios only one thing in which SMASH And geopaparazzi forms differ and that is icons. SMASH supports icons in the single note definition but also in the definition of each widget.

To add an icon to the form definition, a tag sectionicon needs to be added to the section. This can be seen in the example forms, ex:

...
  {
    "sectionname": "text note",
    "sectiondescription": "a simple text note",
    "sectionicon": "fileAlt",
    "forms": [
      {
        "formname": "text note",
        "formitems": [
          {
            "key": "title",
            "value": "",
            "icon": "font",
            "islabel": "true",
            "type": "string",
            "mandatory": "no"
          },
          {
            "key": "description",
            "value": "",
            "icon": "infoCircle",
            "type": "string",
            "mandatory": "no"
          }
        ]
      }
    ]
  },
...

The same goes for formitems, that can feature an icon tag.

The icon name itself can be looked up in the [icon section] of SMASH.

3.2.4. Form based notes

Same as for simple notes, when long tapping on the button, the user is led to the list of form notes.

3.3. GPS Logging

To start logging, the user simply has to push the GPS log 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 ).

log start

The new GPS log dialog.

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

log button on

The GPS logging button with its blue (currently logging) color.

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

3.4. The layers list view

The layers list view features the currently visible layers. At the moment it i snot possible to change the layer order and layers on top cover layers below them in the map.

Vector layers are drawn on top of raster layers, no matter the order.

layers list

The layers list view.

From this view it is possible to add new layers using the supported map types.

If a layer features a bonding area (as vector maps or mbtiles layers), long tapping on them will zoom the map on the bounding area.

Sliding the layer to the left, allows to remove the layer.

3.5. Zoom buttons

The zoom buttons don’t need lot of information. They can be used to zoom in and out the map. The same can be done using the pinch destures.

3.6. Project Info

The Project Info button is place on the right top action bar.

It shows the path to the current database and allows the user to share teh file with others.

4. The main drawer

The left drawer contains some of the main operations that a user usually performs while not actively taking notes.

menu left side

The main, or left, drawer.

4.1. New project

When tapping on the New Project action, the user is prompted to insert a new name for the project or accept the default one based on the timestamp.

project new

The main, or left, drawer.

Once Ok has been pushed, a new project will be created inside the application’s folder structure.

4.2. Open project

When tapping the Open Project action, the file browser of SMASH is opened, allowing the user to browse the device’s filesystem it is allowed to see.

file browser projects

The file browser view, showing the content of the SMASH projects folder.

SMASH projects are of the exact same type as those of the geopaparazzi project. That is the reason the extension of the file is gpap.

Once selected, the project is loaded.

4.3. Import

SMASH allows to import data from the Geopaparazzi Survey Server.

import

The import view.

In fact SMASH is currently the suggested tool to sync geopaparazzi and SMASH surveys with the GSS.

When entering the GSS import view, a list of datasets, projects and forms available from the server is presented to the user:

gss import

The gss import view.

Using the left icon data can be downloaded to the device. Once downloaded teh cion will show what datasets are already available.

4.4. Export

SMASH is currently able to export to PDF and to synchronize with the Geopaparazzi Survey Server.

export

The export view.

4.4.1. PDF

When pushing the pdf export button, a pdf is generated and saved to the export folder.

4.4.2. GSS

When pushing the GSS export button, the stats page is presented. It shows what will be uploaded to the server if pushing the upload button.

gss stats

The gss export stats view.

Once the upload button is tapped, the upload begins. A list with the progress for each resource is presented:

gss upload

The upload progress list.

It the device is not registered with the server, the following message will appear, stopping the upload:

gss upload error

The upload error in case of no permission to upload.

4.5. Settings

settings

The settings view.

4.5.1. GPS Settings

settings gps

The gps settings view.

In the gps settings the user can define filters based on distance and time interval.

There is also the possibility to filter out points that "jump" too far away form the previous point.

Last but not least it is possible to simulate a gps log. The device needs to have a gps fix for this to work. This can be handy when in need to demo the application’s logging functionality when sitting indoor, but still having a fix.

4.5.2. Screen Settings

settings screen

The screen settings view.

In the screen settings view it is possible to:

  • toggle the screen-always-on functionality

  • toggle the scalebar visibility

  • style the map center cross

  • change the size of the icons of the toolbar in the main view

4.5.3. Camera Settings

The camera settings allow to choose the pictures resolution between high, medium and low.

4.5.4. Vector Layers Settings

settings features

The vector layers settings view.

This settings part allows the user to:

  • define the amount of data to be loaded. This can be important for large vector datasets that would make the map navigation less smooth.

  • define the radius of the tap of the info query tool.

4.5.5. Device Settings

settings deviceid

The device id view.

The device id can be necessary in various situations. This is the case of the synchronization with the Geopaparazzi Survey Server. In that case the device id is the unique identifier of a surveyor.

It is possible to override that device id for those cases in which a standardized id generation is used inside and organisation.

4.5.6. GSS Settings

settings gss2

The gss setting view.

In this setting view the user can set the server url on which the Geopaparazzi Survey Server to synchronize to resides.

4.5.7. Diagnostics Settings

In the diagnostics settings view it is possible to toggle the presence diagnostics entry in the tools drawer.

5. The tools drawer

The right drawer can be accessed by swiping the right border of the map to teh left side, as if there was an invisible handle. The drawer contains some tools that can come in handy to the user.

menu right side2

The device id view.

5.1. Position of notes

The Notes in GPS position checkbox can be used to toggle the functionality to:

  • insert notes in the current GPS position (checkbox checked)

  • insert notes in the current map center, as shown by the center cross.

5.2. Vector layer queries

The Query vector layers checkbox can be used to enable the vector layer info tool. Once enabled, tapping on the map will query the available layers for information in the tap position.

feature selection

The moment of tapping and loading query data with enabled vector queries.

The big transparent dot shows the tap area queried.

The info tool queries all visible vector layers and opens the feature info view, which presents each selected feature highlighted in the map context and its attributes:

feature detail point

The feature info view showing a point feature.

Screenshot 20200331 120719

The feature info view showing a line feature in portrait mode.

5.3. Go to

The go-to function allows to exploit the devices OS geocoding function to find locations based on an address. It is then possible to move the map to the selected result.

geocoding

The geocoding view.

5.4. Share position

This action allows the user to share the current gps position with the most common social media methods available on the device.

5.5. Available icons

This action opens the icons view:

icons

The icons view.

In this view the user can select from all the icons of the material design icons project, which ones should appear in the notes properties view and therefore used as markers in the map.

The names that appear in the list can also be used to enable icons for form notes, as explained in the forms section.

5.6. Offline maps

SMASH has a builtin function to download mapsforge (see supported map types) map files for the whole world.

offline maps

The icons view.

Once a map is tapped, the download starts. This can take a while when downloading large countries.

At the current time, due to a tecnical issue in the flutter framework, the visualization of mapsforge maps at low zoomlevel leads to freezing of the user interface, sicne the tiles are generated in the main thread. Therefore, after the download, SMASH performs a one-time tile generation for low zoomlevels, freeaing the user interface. It is suggested to let this process finish, in order to later experience a smooth map navigation using mapsforge maps.

6. Supported map types

6.1. Geopackage

SMASH supports the Geopackage format based on sqlite database both raster tiles and vector formats.

At the moment no reprojection is supported and therefore the limitations are:

  • raster tiles need to be in epsg 3857 and follow a GoogleMapsCompatible tiling scheme

  • vector data need to be in epsg 4326

6.2. GPX

GPX files can be loaded as layers. SMASH will create different layers for the waypoint and track information contained.

It is also possible to style the gpx layers. But since the styling information is not saved anywhere (the file format doesn’t support style), it will persist only for the current session.

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

6.4. Mapsforge Format Data

The mapsforge project provides free and open software for the rendering of vector data 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.

Maps are maintained and distributed by the mapsforge team and can be downloaded from their download server.

In their default style they kind of look like:

main view

The standard mapsforge map.

6.5. Mapurls: Map tiles

By default, SMASH is configured to load map Mapnik rendered tiles from OpenStreetMap’s tile server on the Internet.

It is possible to load other online tile source if they are served in the TMS format using mapurl files. A mapurl file looks like the following:

url=http://tile.openstreetmap.org/ZZZ/XXX/YYY.png
minzoom=0
maxzoom=19
center=11.42 46.8
type=google
format=png
defaultzoom=13
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 (typically 0)

  • the maximum zoom level that is supported (likely not more than 19 or 21 depending on the server)

  • 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

7. Application folder structure

By default SMASH interacts with the filesystem using a folder named smash that resides in the main storage. On IOS devices that would be the Documents area of my application, while on android that usually is the internal sdcard.

Inside the smash folder, the following subfolders hold the information by category:

folder structure

The folder structure of the application.

  • config: the folder that contains internal app configurations. For example the debug database is kept here. This can be sent to the developers in case of bugs to help solving them.

  • export: folder into which documents produced from exports are saved.

  • forms: folder for forms. Any form file in there is loaded as form note in SMASH.

  • maps: the folders in which to keep maps. Downloaded and synchronized maps are saved into this folder.

  • projects: folder inside which new projects are created.