-
Notifications
You must be signed in to change notification settings - Fork 0
/
doc.html
360 lines (354 loc) · 20.5 KB
/
doc.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<meta name="description" content="Fieldwork toolbox for the collection of geotagged data.">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>FieldMapper</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<link href="https://fonts.googleapis.com/css?family=Nunito+Sans:300,400,600,700,800,900" rel="stylesheet">
<link rel="stylesheet" href="scribbler-global.css">
<link rel="stylesheet" href="scribbler-doc.css">
<link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
<link rel="icon" href="/favicon.ico" type="image/x-icon">
</head>
<body>
<div class="doc__bg"></div>
<nav class="header">
<h1 class="logo">FieldMapper</h1>
<ul class="menu">
<div class="menu__item toggle"><span></span></div>
<li class="menu__item"><a href="index.html" class="link link--dark"><i class="fa fa-home"></i> Home</a></li>
<li class="menu__item"><a href="https://github.com/FieldMapperApp" class="link link--dark"><i
class="fa fa-github"></i> Github</a></li>
</ul>
</nav>
<div class="wrapper">
<aside class="doc__nav">
<ul>
<li class="js-btn selected">Overview</li>
<li class="js-btn">Use Cases</li>
<li id="settings-btn">Settings</li>
<li class="js-btn" style="padding-left: 7px;">Variable Management</li>
<li class="js-btn" style="padding-left: 7px;">Options</li>
<li class="js-btn" style="padding-left: 7px;">Layer Management</li>
</li>
<li class="js-btn">Data Handling</li>
</ul>
</aside>
<article class="doc__content">
<section class="js-section" id="overview">
<h3 class="section__title">Overview</h3>
<p>
FieldMapper is a Cordova-powered Android app that facilitates the collection of geo-referenced data in
fieldwork contexts. Essentially, FieldMapper's interface lets you create objects with
user-generated attributes on a map. The data can then be exported into GIS software and further processed.
FieldMapper offers the opportunity of creating either point objects or
freehand-drawn line objects, which enables users to utilize the app in all contexts where place-specific
information needs to be transformed into a computer-processable data set. On top of that, you can import your
own layers and fine-tune the user experience with a variety of options.
</p>
<p>
The documentation covers all relevant topics from importing layers to post-processing the data.
Before jumping right into it, I recommend familiarising yourself with the map interface first.
You can find a clickable screenshot of the app with explanations on the <a href="index.html">landing page</a>.
</p>
<p>
<a href="https://github.com/FieldMapperApp/FieldMapper/blob/master/CONTRIBUTING.md">Contributions</a> to the
project are most welcome. If you think the app lacks an important feature or its scope
should be broadened to render different use cases possible, I'd be happy to make this work. Also, if you
encounter bugs or struggle with the usage of the app, just <a href="mailto:felix-schott@gmx.de">drop me a
line</a>. I'm eager to hear from you if you
have used the app in your project. Please provide reference to FieldMapper where possible.
</p>
<hr />
</section>
<section class="js-section" id="use-cases">
<h3 class="section__title">Use Cases</h3>
<p>FieldMapper comes in handy when it matters to you where the phenomena you are trying to capture take place.
Two general use cases come to mind:</p>
<ol>
<li>
<p><strong>Observation of spatially bounded systems</strong><br>I developed the prototype of the app in
preparation for my Bachelor's dissertation research project where I conducted fieldwork in a
neighbourhood park. Among other things, I used the app to count visitors and the frequency of certain
demographic variables. Because all data gathered through FieldMapper is tagged with coordinates, one
can easily detect spatial patterns and clusters of phenomena with it. Users can add custom buttons to the
map UI,
which makes it possible to work with custom variables. Another feature that appears to be
especially useful in the study of social networks is the "group" functionality which enables
users
to mark interaction between actors.
Yet, usage of the app is not limited to social research as it would be possible to as well survey abiotic
components of systems.<sup><a href="#footnote1" id="ref1">[1]</a></sup> </p>
</li>
<li>
<p><strong>Mapping social routines and perception of place in social research</strong><br>Apart from
observing visitors, I also employed the app in the context of interviews. Visitors were asked to mark
their home,
areas they consider to be unsafe or their preferred spot under certain circumstances.
With FieldMapper, I was able to quantify the share of visitors living nearby and to calculate mean
distances
from their homes to the park surveyed and other places of interest.
In contexts like
this, the
ability to draw polylines freehand (which can be transformed into polygons using GIS software) proves
especially useful. Color codes, timestamps and free text comments are on hand for metadata tagging. </p>
</li>
</ol>
<hr />
</section>
<section class="js-section" id="variable-management">
<h3 class="section__title">Variable Management</h3>
<h4>Overview</h4>
<p>As your aim is to collect data that suits your research question, you probably want to work with a custom set
of variables tailored to your case.
These variables will actually determine the attributes of objects that you add to the map. Once you have
clicked on <em>Variable Management</em> in the settings tab, you are prompted to add a variable.
Now just enter the name of the new variable and press enter. The variable shows up in the list below.
Next to its name you can see three buttons: by pressing and dragging the left button, you can re-order the list of
variables. Changes will also affect the order of buttons added to the map UI.
The middle button lets you <em>edit</em> the variable values and change the appearance of the corresponding
button.
The right button will delete the variable. You can delete all variables at once by clicking on the three dots
in
the upper right corner and choosing "Clear variables". Note that, if you do not edit the variable,
it
will be operationalized as a boolean variable by default (see below).</p>
<h4>Choosing the right type</h4>
<p>If you click on the edit button, a page opens up that allows you to change the type, value and icon of the
variable (button).
First decide which kind of data you want to encode. Type <em>Boolean</em> generates a single button that can
be activated and deactivated.
Of these two button states, active means "true" and inactive means "false".
This kind of button makes most sense when the attribute only has two possible states (dichotomous
variable) and state 1 is the negation of state 2, for instance "wears hat/doesn't wear hat"
(if you are only interested whether someone wears a hat and not which kind of hat). If you name the variable
"Hat" or "Wears hat" and choose Boolean as the variable type, "Hat" can be
either "true" or "false".
If "true"/"false" does not make sense but you still want to operationalize the attribute
as a dichotomous variable, you can choose <em>Custom binary</em>.
Now enter two comma-separated values. The first value will correspond to an inactive button.
As with most things, you can operationalize an attribute in more than one way. Instead of the following
configuration ...</p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Values</th>
</tr>
</thead>
<tbody>
<tr>
<td>Hat</td>
<td>Boolean</td>
<td>(true, false)</td>
</tr>
</tbody>
</table>
<p>... you could also encode the same information with this configuration:</p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Values</th>
</tr>
</thead>
<tbody>
<tr>
<td>Hat</td>
<td>Custom Binary</td>
<td>doesn't wear one, wears one</td>
</tr>
</tbody>
</table>
<p>In most cases, working with boolean variables (where reasonable) will make things easier.</p>
<p>Aside from these, you can also encode information that does not fit a binary scheme.
Imagine you are interested in the type of hat a person is wearing. As there are more than two kinds
of
hats, both other variable types do not work.
Therefore, we need to choose type <em>Non-dichotomous</em> and enter all possible attribute states we are
interested in.
In our case those could be "Sombrero", "Beanie" and "Kippah". Unlike the binary
types, this will generate not a single button with two states (active and inactive) but a bar of length n =
number of states/values.</p>
<h4>Using custom icons</h4>
<p>Enable the <i>Use SVG/PNG icon</i> option to upload your own icons.
If the option is disabled, the first two letters of the variable name (if boolean or binary) or values
(if non-dichotomous) will show up as the button icon (which will suffice for most purposes if you do not have
a
couple of variables that share the same initial letters or care much about a visual representation of the
attributes.)</p>
<p>You can find free SVG icons in icon libraries such as <a href="https://fontawesome.com/">FontAwesome</a> or
<a href="https://ionicons.com/">Ionicons</a>. Download them to your device and upload them using the dedicated
function in the edit menu of the variable.</p>
<hr />
</section>
<section class="js-section" id="options">
<h3 class="section__title">Options</h3>
<h4>Toolbars</h4>
<p>Configure which toolbars you want to have in the map interface by switching on and off the different toolbar options.
Have a look at the interface guide on the <a href="index.html">landing page</a> to
find out about the purpose of the different controls.</p>
<h4>Other</h4>
<p>Some options may only appear after you enable/disable particular toolbars.</p>
<ul>
<li>Allow deletion of imported objects:
<p>If you have <a href="#layer-management">imported</a> your own layers, here you can
determine
whether you want those to be affected when you delete objects on the map (for example with the clear
button).</p>
</li>
<li>Include imported layers in export:
<p>Similarly, here you can decide whether you want to include imported layers when you save the map state as
GeoJSON. (Imported layers will be saved as a separate file anyway.)</p>
</li>
<li>Enable comments:
<p>Choose whether you want to have a prompt pop up which asks you to add additional information on the
object
after you add an object to the map.</p>
</li>
<li>Only group objects of same geometry type:
<p>If you have enabled the "group" functionality, you can determine whether the algorithm should
distinguish between points and lines when automatically assigning group membership to objects.
If enabled, points and lines can't be in the same group (which leads to groups like p/number/ and
l/number/), if disabled they can be (/number/ without l or p).</p>
</li>
<li>Automatically choose random color for groups:
<p>If enabled, the color bar disappears from the map interface and the app will iterate over the colors (see
below) and automatically colorize objects belonging to the same group with the same color.</p>
</li>
</ul>
<h4>Colors</h4>
<p>Choose which colors you want to have in the game. Will affect both automatic (see above) and manual coloring
of objects.</p>
<hr />
</section>
<section class="js-section" id="layer-management">
<h3 class="section__title">Layer Management</h3>
<h4>Overview</h4>
<p>FieldMapper allows you to import your own layers. It accepts both GeoJSON layers and image overlays.
The basic process of adding and editing layers is the same as for variables, so have a look at the <a
href="#variable-management">Variable Management section</a> if you struggle with the basics.</p>
<h4>GeoJSON and Image Overlay</h4>
<p>FieldMapper can handle two types of layers: GeoJSON and Image Overlay.
GeoJSON is based on the JSON format and looks as follows:</p>
<code>
<pre class="code">
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"color": "green"
},
"geometry": {
"type": "Point",
"coordinates": [
13.38778495788574,
52.515803012883595
]
}
}
]
}
</pre>
</code>
<p>If your imported GeoJSON objects have a color attribute in their properties, FieldMapper will automatically
style them accordingly.</p>
<p>FieldMapper can also handle images as layers which you might want to import to account for more complex
stylings that GeoJSON is not
capable of capturing. If you want to import an image overlay, you need to provide the bounds of the area the
image is meant to represent.</p>
<p>QGIS has an "export as image" function. If you want to export a layers as an image so it can be
imported into FieldMapper, follow these
steps (tested with QGIS 3.8):</p>
<ol>
<li>
<p>Draw on top of a OSM layer or create your custom layers a different way.</p>
</li>
<li>
<p>Create a extent layer enclosing all relevant layers (in a spatial sense) and extract the layer extent
(<code>Vector > Research Tools > Extract Layer Extent...</code>).</p>
</li>
<li>
<p>Go to the attribute table of the resulting layer. You can now extract a pair of coordinates representing
two diagonally opposite corners of the image layer that you will be asked to provide in the edit menu of
FieldMapper:
<code><MINX>, <MINY></code> and <code><MAXX>, <MAXY></code>. Make sure the
coordinates are in WGS84 decimal degree format.</p>
</li>
<li>
<p>Select <code>File > Import/Export > Export Map to Image</code>. Calculate the extent using your
extent layer and click save.</p>
</li>
</ol>
<hr />
</section>
<section class="js-section" id="data-handling">
<h3 class="section__title">Data Handling</h3>
<p>FieldMapper exports GeoJSON files which can be accessed under
<code>data/io.github.fieldmapperapp/files/exports</code>.
All the attributes added via the <a href="#variable-management">Variable Management</a>
interface are stored as properties of the exported objects.
You can access these attributes in the attribute table of the layer after importing the layers into GIS
software (e.g. QGIS).
After loading the export layers into GIS software, you can perform all kinds of queries on the data, for
example calculating the mean distance between or Moran's I for points or rendering a heat
map.<sup><a href="#footnote2" id="ref2">[2]</a></sup>
With FieldMapper you can only create points and lines. Lines can be transformed into polygons really easy with
the help of GIS software.
In QGIS (tested with v3.8), just use the Polygonize function which can be accessed via
<code>Vector > Geometry Tools > Lines to Polygons</code>.</p>
<p>Every object added to the map has a timestamp which serves as a unique ID (if you prefer a numerical ID you
can easily generate it from the timestamps with Excel, Python or whichever software/language you use). All
exported layers also have a timestamp in their file name.
The layer timestamp is helpful in integrating FieldMapper outputs with other timecoded datasets such as those
generated by digital questionnaires.
If FieldMapper plays a part in an interview procedure where you gather textual data (with a questionnaire) and
geodata (with FieldMapper), you can computationally establish
cross-dataset object reference on the basis of the timestamps.
You can further link questionnaire items to FieldMapper objects either with color codes (establish
conventions where
you define that the item "Where do your live?" corresponds to blue objects beforehand) or by using
the comments function and providing an textual item reference (code).
If you have a fixed interview procedure and the same number of objects per item in every iteration of the
procedure you could also use the timetags to get item reference.</p>
<hr>
<section>
<p><strong><sub><a name="footnote1">[1]</a>:</sub></strong><sub>
Note that the app has difficulty mapping
processes such as the movement of actors in space. If you repeat surveying the same place, you can of
course
record changes in the number and location of actors. Every object placed on the map has a timestamp that
acts as its unique ID. Accordingly, you will have trouble identifying object A at place B in dataset 2 as
the same object A that was located 5 m left of B in dataset 1. If you're dealing with a multitude of
moving actors, it is unlikely that you are able to map (even discrete) movement anyway. If your survey
only
covers a limited number of (hardly mobile) actors you might be able to keep track of change in a system by
re-importing a layer depicting a prior state and moving markers manually and deleting/adding markers where
necessary.<a href="#ref1" title="Jump back to footnote 1 in the text."> ↩</a></sub>
</p>
<p><strong><sub><a name="footnote1">[2]</a>:</sub></strong><sub>
You can style point layers as heat maps in QGIS (tested with v3.8) by choosing "heat map" in the
Symbology section of the Layer Properties menu.
If the input layers are polygons and you want to calculate the heat from the degree of overlapping,
generate
random points in the polygons first
(<code>Vector > Research Tools > Random Points inside Polygons</code>).
<a href="#ref2" title="Jump back to footnote 1 in the text."> ↩</a></sub>
</p>
</section>
</article>
</div>
<footer class="footer">FieldMapper | © Felix Schott 2020 | <a href="mailto:felix-schott@gmx.de"
style="color: white">Get in
touch!</a></footer>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js"></script>
<script>hljs.initHighlightingOnLoad();</script>
<script src="scribbler.js"></script>
</body>
</html>