[](https://github.com/ropensci/mapscanner/actions?query=workflow%3AR-CMD-check)
[](https://cran.r-project.org/package=mapscanner/)
[](https://cran.r-project.org/package=mapscanner)
[](https://app.codecov.io/gh/ropensci/mapscanner)
[](https://www.repostatus.org/#active)
[](https://github.com/ropensci/software-review/issues/330)
## What does this package do for me?
`mapscanner` is an **R** package that enables lines drawn by hand on
maps to be converted to spatial objects. The package has two primary
functions: one for producing maps, and one for rectifying hand-drawn
lines to the coordinate system of the original map. The package is
intended for use in social surveys and similar endeavours in which
hand-drawn markings on maps need to be converted to spatial objects.
Maps can be either paper- or screen-based. Markings on paper maps need
to be scanned, photographed, or otherwise digitised, while maps with
screen-based markings need to be saved as `.png`-format images.
## Installation
The current stable version can be installed from CRAN with:
``` r
install.packages ("mapscanner")
```
Alternatively, the development version can be installed via [rOpenSci’s
r-universe](https://ropensci.r-universe.dev/) by running the following
prior to calling `install.packages()`:
``` r
options (repos = c (
ropensci = "https://ropensci.r-universe.dev",
CRAN = "https://cloud.r-project.org"
))
```
The package can then be loaded for usage in a R session with
``` r
library (mapscanner)
```
## Usage
The package is designed to enable the following workflow:
1. Generate a map with the
[`ms_generate_map()`](https://docs.ropensci.org/mapscanner/reference/ms_generate_map.html)
function, which automatically produces both `.pdf` and `.png`
versions;
2. Either print the `.pdf` version to use as desired in any kind of
survey environment, or use either the `.pdf` or `.png` versions in
digital form for screen-based surveys.
3. Draw on the map;
4. For paper maps, digitise the drawn-on (from here on, “modified”)
map, converting it to either `.pdf` or `.png` format; and
5. Rectify the modified version against the original via the
[`ms_rectify_map()`](https://docs.ropensci.org/mapscanner/reference/ms_rectify_map.html)
function, which distinguishes individual annotations, and converts
each one to a spatial object able to be analysed in any desired
manner.
### Practical tips
The `mapscanner` package is intended to aid a *practical* workflow, and
so a few practical tips may be recommended here to ensure best results:
1. The original digital files generated with
[`ms_generate_map()`](https://docs.ropensci.org/mapscanner/reference/ms_generate_map.html)
are necessary to rectify subsequently drawn-on and scanned maps, and
so must be retained at all times.
2. Marks drawn on maps should be *coloured* – any black or grey
markings will be ignored. This has the advantage that individual
annotations *not* intended to be converted to spatial objects (such
as unique identification or participant codes) may be made on maps
in black or grey.
3. For drawings of areas, best results will be achieved through
ensuring that all lines form closed polygons. While the default
`type = "hulls"` argument should work even when lines are not
closed, the `type = "polygons"` argument will generally produce more
accurate results, yet should only be used when all lines form closed
polygons (see below for details on how these two differ).
4. Digitised versions of paper maps should contain *white* borders, so
do not, for example, photograph modified maps lying on dark
surfaces. If maps are to be photographed, then best results can be
achieved by simply placing them on a larger, enclosing sheet of
white paper.
The following two sections describe the two primary functions of the
`mapscanner` package, corresponding to the two primary steps of
producing maps to be used in surveys (or other activities), and
rectifying modified maps against these originals in order to extract
spatial objects. The second of these sections also describes the kinds
of markings able to be recognised, and the kinds of spatial objects to
which these may be converted.
### Mapbox API tokens
Map generation with `mapscanner` requires a personal token or key from
[`mapbox`](https://www.mapbox.com/), which can be obtained by following
the links from
[https://docs.mapbox.com/api](https://docs.mapbox.com/api/#access-tokens-and-token-scopes/).
If you already have a token, the easiest way to use it with `mapscanner`
is to create (or edit) a file `~/.Renviron`, and insert a line,
``` bash
MAPBOX_TOKEN=
mpadge |
mdsumner |
maelle |
potterzot |
ThomasDier |
khondula |
tomroh |
SantoshSrinivas79 |
asitemade4u |
espinielli |
dcooley |
sckott |
jeroen |