While we are watching FAIMS3 emerge, a number of old 2.6 modules are still being created. As the developing team has little capacity to support new projects, project directors follow a do-it-yourself approach from design to deployment. Adela, who has used and administered FAIMS before for landscape archaeology, has never developed a module from scratch but used her software-carpentry-level skillset to repurpose a module from the FAIMS Github library.
FAIMS 2.6 will not die
It is 2021, FAIMS3 is not quite ready and in April I unexpectedly needed to collect data on Cold War bunkers in Aarhus. I decided to reuse an existing FAIMS 2.6 module1. Here is my experience:
There are three different ways one can create or edit a FAIMS 2.6 module fit to one's needs:
Write a module definition packet from scratch.
Edit an existing module’s definition files (existing definitions are published on Github).
Edit a module instantiated on the FAIMS server via the server web application’s graphic user interface.
Setting aside the first and third approaches for now, I decided to take the second approach. Editing the module’s definition files requires intermediate computational skills, as the module creator needs to locate the existing module on Github, then download and edit the four XML / text files that comprise the definition packet (contained in the module folder on GitHub). In my case, I changed the names of tabs and attributes to correspond to my own project. One needs only find and replace skills, but attention to detail is necessary as well as the audacity to edit XML.
Knowing this, and being no programmer, I still choose option two when I want to mashup a new module from pieces of existing modules on Github. Once fieldwork is going, I use option 3 to add new elements (maps and vector data) or make urgent in-field changes (like adding forgotten terms to controlled vocabularies).
Aarhus Cold-War Bunkers
In April 2021 as Denmark was coming out of its second lockdown, my colleague Petra Hermankova and I were looking for an outdoors activity to engage Spatial Analytics undergraduate students. We decided to adapt one of the modules designed for citizen science in Bulgaria — burial mound monitoring — for documenting civil defences around Aarhus. Upon arrival to Aarhus two years ago, it struck us how ubiquitous shelters, bunkers, and other military installations are in this urban environment. Their density resembles military installations on the Bulgarian-Turkish-Greek border where we worked in 2018 — yet that is a former Cold-War border zone and now a closely monitored EU border. We knew little about Cold-War bunkers, but found an article about them by Rosanna Farbøl, a historian who researches Danish civil defense. She noted the lack of spatial information on the civil defenses and so we decided to remedy the situation. I would create a prototype module for documenting the bunkers, one that we could jointly test and then pass on to History or Spatial Analytics students to use for research projects.
Adapting an existing module
FAIMS Github library has several modules which allow for user self-registration and login and are thus suitable for lightweight citizen-science or self-selected student projects. To document bunkers we needed to collect spatial points and visualise them on a basemap of Aarhus, fill out some structured data attributes (mostly using controlled vocabularies), and attach photos. All of these features were in the burial-mounds-community module and so I chose it as the starting point.
The adaptation process itself had two stages:
Edit the definition packet to update the entities, plus their attributes and controlled vocab terms, from burial mounds to Cold-War bunkers.
Find and prepare basemaps and configure the FAIMS mobile GIS to support our spatial reference system.
Editing the definition packet
In the first stage, I downloaded burial-mounds-community from Github, opened the module folder and edited three files in the definition packet (the data_schema.xml, ui_schema.xml, and properties.txt) using my favorite text editor software. I replaced every instance of 'mound' with 'bunker' or 'shelter', and updated all field names and vocabs to relate to civil defense rather than mortuary archaeology. I also edited html files in the ‘data’ folder which contain the module’s landing page (with project-level metadata) and in-app help text.
These changes took about an hour, because I was figuring out the replacements on the fly, and I had to be absolutely consistent. For example, FAIMS allows separate manipulation of the data schema and user interface (UI), but the two must be kept consisent. When I changed the drop-down list associated with ‘Feature type’ (containing 'bunker', 'shelter', 'depo', and 'trench') in data_schema.xml, I had to make exactly the same changes in the ui_schema.xml, all the while being careful not to introduce any blank spaces or other intrusive characters. Such manual changes are tedious and risky because a lapse of attention will make a change in the data schema not render properly in the UI of the final app.
When I had made some changes, I saved the files and instantiated the module on the public FAIMS server (add Footnote to Instantiation). Then I downloaded the module to my phone and tested it, paying special attention to the items I changed. I continued to download, edit, save, and instantiate the definition files until I was satisfied with the look of the customised app.
It took me two iterations and 1.5 hours to have a workable app with meaningful terminology. There were several things in the original module I did not need, but that was OK (I left them in the app where they could be ignored). What I needed next was the basemaps.
Anybody who wants to collect and display spatial data faces a second stage of customisation, spatial data preparation. Finding and pre-processing rasters and vectors for use in FAIMS can be done in desktop GIS or on the command line. I downloaded a satellite image of Aarhus from a local provider at kortforsyningen.dk. Processing this 4-band, 1m resolution, 20Gb ortophoto (.ecw) image into nine downsampled geotiffs of ca 100MB each was the most time-consuming part of the whole adaptation.
After the initial splitting of the image in desktop GIS, I followed the raster-processing guidelines to define the projection, tile, and add pyramids to the map files with three one-line commands in git bash2. The mobile GIS engine in FAIMS 2.6 (an older version of Nutiteq, now owned by Carto) is 3D and uses the web-Mercator 3857 reference system. Tiles and pyramids accelerate the display of rasters on mobile devices. I did not need to prepare any vector data, but when I have shapefiles I also project them into EPSG 3857 and bundle them up in a spatialite database following these guidelines.
After my basemaps were prepared, I viewed them in a GIS viewer to test their rendering. I then put them in a ‘Map’ folder on the server and added this to ‘data’ folder3, where I kept images associated with the app (e.g, ‘picture dictionaries’)4, and zipped them up into an compressed file named data.tar.gz5.
In my next post, I’ll talk about the experience of “spinning up” a module and collecting data in the city. Here is what our points looked like midway through data collection:
A user needs a definition packet - a collection of five text files that define the data schema, user interface, and behaviour of the final data collection app - to instantiate a module on a FAIMS server. The ‘server’ is a web application that synchronises connected mobile devices, does exports, allows limited editing of module elements; it can run offline (on local hardware) or ‘in the cloud’.
Git bash is a powerful command line environment for Windows, Mac, and Linux. The raster transformations specified in FAIMS guidelines also require installation of GDAL tools in bash.
For error-free, off-the-shelf file display, it is best to replicate the file structure of the ‘data’ folder in the original module on Github. If the structure or folder and file names are not consistent, images may not render as expected.
‘Picture dictionaries’ are images displayed to help users choose values in a controlled vocabulary. For example, instead of asking a user if a bunker is in a forest, ploughed field, etc., we can show a picture of each type of land use, and when a user clicks the picture, the associated vocab term is saved.
This type of archival file (.tar.gz) can be created on Windows using archiving software like 7-zip. It may take two passes, one to create an archive (.tar), the second to compress it (.tar.gz).
For more news, subscribe!