Documentation — Sketch Map Analyser

Start here

When you ask someone to draw a map of a place they know, what they produce is not a bad map — it is evidence. A sketch map externalizes a cognitive map: what the person encoded, what they kept, and how they organized it. The problem has always been turning that evidence into numbers you can analyse.

Traditionally this meant a lot of manual work leading to inconsistency in analysis. The Sketch Map Analyser replaces that with a systematic process resulting in reproducible measurements. You give it a base map of the real environment and a participant's sketch map, tell it which drawn features correspond to which real ones, and it measures the completeness and accuracy.

What you do not need: any programming, any command line experience. You work in a web page: load maps, annotate, and match features, press Analyse, and download the results as a zip containing spreadsheets.

The three questions

Everything the tool measures is an answer to one of three questions about a participant's drawing.

What did they remember?

Of everything that exists in the real environment, how much appears in the drawing at all?

Completeness

How much did they simplify?

People collapse a row of shops into one block, or generalize streets. The tool identifies these simplifications so they are not mistaken for incompleteness.

Generalization

Did they get the layout right?

Given what they drew, is it arranged correctly? Measured two ways: whether qualitative relationships hold (is the station 'right' of the street?) and whether distances and angles are accurate.

Accuracy measures

Keeping these three separate is the central design decision. A single accuracy score cannot absorb them. A landmark that was never drawn, a landmark that was merged into its neighbour, and a landmark drawn in the wrong place all register as the same thing — error. Reported separately, each question is answered on its own terms: what was memorized, how it was simplified, and how well what remains is arranged.

Key concepts and vocabulary

A few terms recur throughout the software and this page. They come from geoinformatics rather than psychology, so they are worth defining once.

Base map (or reference map)

The ground truth — a topographic map or study environment.

Sketch map

The participant's drawing, annotated into the software so that each drawn object becomes a separate, countable feature.

Feature

A single object on either map: one building, one street segment, one park. The unit everything is counted in.

Landmark

A point or area feature — a building, monument, square. Distinguished from streets, which are line features and are counted separately.

Alignment

Your judgement about which sketch feature corresponds to which real feature. You make these matches by hand; every measurement depends on them.

Generalization

A simplification the participant made — merging several buildings into one, collapsing a roundabout to a crossing.

Generalized base map

The reference map rebuilt at the participant's level of detail. This — not the original — is what accuracy measures compare against.

Junction

A point where three or more streets meet. Junctions can be analysed instead of buildings, which is useful for route-based or street-dominated sketches.

Why the "generalized" base map matters

Suppose the real environment contains three adjacent shops. Your participant draws one rectangle and labels it "the shops." Scored naively, that is two omissions and one misplaced building.

But that is not a memory failure — it is categorical abstraction, and arguably a sign of well-organized spatial knowledge. So before any accuracy measure runs, the software merges those three shops on the reference map into one, matching what the participant did. The comparison is then like-for-like.

The consequence for interpretation: accuracy is scored against the world at the level of detail the participant drew, not against the base map as a cartographer would draw it. Departures from the reference map are reported elsewhere : missing information in completeness, simplifications in generalization.

Designing a study

What you need before you start

You need	Notes
A defined study area	Bounded and consistent across participants. Everyone should be drawing the same environment.
A base map of that area	Loaded into the software from OpenStreetMap data.
Participants' sketch maps	Drawn on paper and annotated in the app, or drawn directly in the app editor.
Alignment	The manual process of matching sketch map features with base map.
Route	A predefined path marked on the base map, required for qualitative accuracy. A route is an ordered sequence of connected street segments.

Running an analysis

Load your project — the reference map and one or more sketch maps.
Tidy the geometry (optional). Hand-drawn streets often don't quite meet, or one street gets drawn as several strokes. The software can propose fixes — joining near-miss endpoints, merging broken segments — and you approve each one. Nothing is changed without your say-so. Worth doing if you plan to use junction-based measures, since those depend on streets actually connecting.
Align the features — click a sketch feature, then the real feature it corresponds to.
Press Analyse. Choose which measures to run:
- Completeness — always included
- Accuracy — the relational measures
- Buildings GMDA — configural accuracy from landmarks
- Junctions GMDA — configural accuracy from street junctions
Read the results table — one row per sketch map, grouped by measure family.
Download Results — a zip of spreadsheets ready for your statistics software.

Reading your results

Each measure below lists its range, which direction is "better," what it is actually sensitive to, and what to watch out for. Use the tabs to move between measure families.

How much of the environment made it into the drawing.

Landmark completeness

0–100% · higher = more recalled

The percentage of reference landmarks that appear in the sketch.

Interpretation. A memory-quantity measure, closely analogous to free-recall scores: counted against the generalized reference map, so merging several buildings into one does not count as omissions.

Street completeness

0–100% · higher = more recalled

The same calculation for street segments rather than landmarks.

Interpretation. Dissociates from landmark completeness.Tells the 'memory' of the street network. Reporting both separately is usually more informative than the average.

Overall completeness

0–100% · higher = more recalled

The mean of the two measures above.It is an unweighted average. If your environment has 12 landmarks and 90 street segments, both still contribute equally. Check the two components before relying on the composite.

The amount of simplifications done by the participant. Detected automatically from the alignments you made — several base-map features mapped to one sketch feature is a generalization; the type depends on the geometry. Counts are separated for streets and buildings, and every instance is listed in GeneralizationDetailedOutput.csv with its underlying feature ids.

Streets

Omission Merge

count

Two or more real street segments drawn as one sketch segment.

Junction Merge

count

Two or more real junctions collapsed to one in the drawing.

Roundabout Collapse

count

A real roundabout drawn as a plain crossing.

Abstraction to show existence (streets)

count

A number of streets in base map represented by a number of streets in sketch map without having a direct one-one relation.

Buildings

Amalgamation

count

Several adjacent buildings drawn as one building in sketch map.

Collapse

count

A building or area drawn as a point.

Abstraction to show existence (buildings)

count

A group of buildings represented by a group of buildings without having a direct one to one relation between individual buildings of the group.

Totals

Total street / building generalizations

count

Sums of the categories above, separately for streets and buildings.

Overall generalization

count

Sum of both.

Generalization is not treated as error: the accuracy tabs are computed against the generalized base map (see “Why the generalized base map matters”).

Whether the relationships between features (the church still inside the square, the shop still on the left of the road, the streets still crossing in the same order) are preserved, independent of metric precision.

The software extracts every such relationship from both maps and compares them one by one, across six families: landmark topology, street-landmark topology, left/right of a road, relative direction between streets, street connectivity, and order of landmarks along a route. Each family gets its own score; two summary measures aggregate across all of them.

Precision

0–1 · higher = better

Of all the relationships the participant expressed in their drawing, the proportion that match reality.

Interpretation. "When they committed to a spatial relationship, how often were they right?" Insensitive to what they left out — a sparse but correct map scores high.

Recall

0–1 · higher = better

Of all the relationships present in the real environment, the proportion the participant captured correctly.

Interpretation. Penalized by omission. Typically much lower than precision, because the reference environment contains far more relationships than anyone draws.

The metric measures, from the Gardony Map Drawing Analyzer — an established, published method for quantifying sketch map accuracy. It works by taking every pair of features and asking how the drawn relationship between them differs from the true one, then aggregating those pairwise errors.

Available in two variants: Buildings (landmarks) and Junctions (street intersections). Both produce the same six scores.

CanOrg — canonical organization

0–1 · higher = better

Whether features are in the correct broad direction from each other (north/south, east/west), calculated across all pairs in the real environment.

Interpretation. Because the denominator includes pairs the participant never drew, omissions lower this score. It is a combined measure of recall and coarse layout — the closest thing here to a single "overall quality" number.

Watch out: values are often strikingly low (0.1 is common) simply because participants draw a fraction of the environment. This is expected. It is a relative measure — compare conditions, not to 1.0.

CanAcc — canonical accuracy

0–1 · higher = better

The same directional check, but calculated only over the features the participant actually drew.

Interpretation. Layout quality with recall removed. Read alongside CanOrg: a large gap between them means the participant drew little but organized it well. Completeness already measures the recall side, so CanAcc is usually the cleaner dependent variable.

DistAcc — distance accuracy

≤1 · higher = better

How well relative distances between features are preserved, after equalizing for the overall size difference between drawing and reality.

Interpretation. Because it is scale-normalized, drawing a small map does not penalize you — only getting the proportions wrong does. Sensitive to local distortions, such as expanding a familiar neighbourhood relative to its surroundings.

ScaBias — scaling bias

signed · 0 = unbiased

The same distance comparison, but keeping the sign.

Interpretation. Positive means the participant systematically expanded distances; negative means they compressed them. Where DistAcc measures error magnitude, this measures direction.Near-zero can mean either no bias or expansions and compressions cancelling out. Always report it with DistAcc.

AngAcc — angular accuracy

0–1 · higher = better

How well the angles between pairs of features are preserved.

Interpretation. A finer-grained companion to CanAcc. Canonical direction only asks "roughly north?"; this asks "at the right bearing?" A participant can score well on one and poorly on the other.

RotBias — rotational bias

−180° to +180° · 0 = aligned

Whether the whole drawing is systematically rotated relative to reality. Positive is clockwise, negative counterclockwise.

Interpretation. Systematic rotation often reflects an alignment to a reference frame other than north — a dominant street grid, a habitual approach direction, or the orientation the environment was learned from. It is circular data. Do not average rotation across participants with an ordinary mean — +170° and −170° average to 0°, implying no bias when both were rotated nearly half a turn. Use circular statistics.

Bi-dimensional regression is a long-established method for comparing two spatial configurations. Conceptually it is ordinary regression generalized to two dimensions: it finds the single best transformation — one uniform stretch, one rotation, one shift — that maps the real configuration onto the drawn one, then asks how much of the drawing that transformation explains.

r — bidimensional correlation

0–1 · higher = better

How well the configurations correspond once the best transformation is applied.

Interpretation. Read like a correlation coefficient. High values mean the drawing is essentially the real layout scaled, turned and shifted; lower values mean the internal arrangement itself differs.

DI — distortion index

lower = better

The residual distortion, computed directly from r.

Interpretation. Zero is a perfect match. Reports the same information as r on a scale where bigger means worse — report one or the other, not both as independent findings.

phi — scale factor

around 1 = same scale

How much larger or smaller the drawing is than reality, overall.

Interpretation. A parameter driven by paper size.

theta — rotation

degrees

The overall rotation of the drawing relative to the reference.

Interpretation. Conceptually parallel to RotBias, estimated by a different route. The two can be reported as converging evidence — and again, they are circular data.

alpha1, alpha2 — translation

horizontal and vertical shift

How far the fitted configuration is displaced.

Interpretation. It mostly reflects where on the page someone began drawing. Rarely reported.

A general caution on direction. Most measures here are "higher is better," but three are not: DI (lower is better), and ScaBias and RotBias, which are signed biases where zero — not the maximum — is unbiased. Check the direction of every measure before interpreting a correlation table.

A worked example

Suppose one participant's row comes back like this:

Measure	Value
Landmark completeness	35.7%
Street completeness	40.9%
CanOrg	0.10
CanAcc	0.89
DistAcc	0.94
ScaBias	−0.0001
AngAcc	0.79
RotBias	−30.2°

How to read it.

They drew roughly a third of the environment.

The gap between CanOrg (0.10) and CanAcc (0.89) is the story. CanOrg is low almost entirely because two-thirds of the environment is missing from the denominator, not because the layout is poor. CanAcc, restricted to what they actually drew, is high: what they remembered, they organized correctly. This is a selective but well-structured representation, and it would be a serious misreading to describe this participant as spatially inaccurate on the strength of CanOrg alone.

Distances are well preserved (0.94), and scaling bias is essentially zero — no systematic expansion or compression.

The interesting result is RotBias at −30°. Angular accuracy is noticeably lower than distance accuracy (0.79 against 0.94), and this rotation is why: the whole configuration is turned roughly 30° counterclockwise. That is not random error. It suggests the participant encoded the environment relative to some frame other than north — a main street's orientation, or the direction they habitually approach from.

The general habit: never read a single score in isolation. Completeness contextualizes CanOrg; RotBias explains gaps between AngAcc and DistAcc; ScaBias qualifies DistAcc. The measures were designed to be read as a profile.

Getting your data into statistics software

Download Results gives you a zip of CSV files. CSV opens directly in Excel, SPSS, R, JASP and jamovi.

File	What it contains	Use it for
`ResultSummary.csv`	One row per sketch map, every measure as a column	Your main analysis file
`CompletenessDetailedOutput.csv`	The underlying feature counts	Checking what drove a completeness score
`GMDADetailedOutput.csv`	Configural measures plus how many features were matched	Screening for sparse, unstable cases
`BDRDetailedOutput.csv`	Regression parameters per map	Distortion analyses
`QADetailedOutput.csv`	Relationship counts per family	Family-specific hypotheses
`GeneralizationDetailedOutput.csv`	Which features each participant merged or simplified	Studying abstraction itself
`QualitativeRelations/`	The full relationship list for each map	Custom or exploratory relational coding

ResultSummary.csv is already in the shape most analyses want: participants in rows, measures in columns. Add your condition and demographic variables as extra columns and you are ready to analyse.

Before you analyse. Sketch map measures are frequently non-normal — bounded scores pile up near their limits, and completeness is often right-skewed. Inspect distributions before defaulting to parametric tests, and remember that rotation measures require circular statistics.

Data privacy

This tool is designed for the analysis of anonymised sketch maps. No sketch map images are stored on the server; they stay on the user's device. Only the annotated features (the digitised geometry and their alignments) are transmitted for analysis.

Limitations and things to be careful about

The measures are computed reliably; that does not make every interpretation of them safe.

Alignment is a human judgement

Everything downstream rests on your decisions about which drawn feature is which. Reliable in clear cases, genuinely ambiguous in others.

Scores are relative, not absolute

There is no established norm for a "good" CanOrg. These measures are for comparing conditions, groups or time points — not for classifying an individual.

Rotation and bias measures are circular or signed

Ordinary means and standard deviations mislead on RotBias and theta. Signed biases can cancel across participants, hiding real distortion.

Composite measures can obscure

Overall completeness averages landmarks and streets equally regardless of how many of each exist. Check components before interpreting composites.

Generalization handling is a choice

Applying participants' simplifications to the reference map is defensible and deliberate — but it does mean your accuracy scores are not directly comparable to methods that skip this step.

The environment shapes the numbers

A dense city centre and a sparse suburb yield different baseline values for the same participant ability. Do not pool across environments without care.

Research background

The tool was developed at the Spatial Intelligence Lab, Institute for Geoinformatics, University of Münster, building on a line of work concerned with making sketch map analysis systematic rather than manual.

Qualitative foundations

Establishing that sketch and metric maps can be aligned through qualitative spatial relations rather than coordinates — the basis of the relational measures (Schwering et al., 2014).

Classifying sketch maps

A feature-based scheme for distinguishing types of sketch map, informing how drawings are characterized before analysis (Krukar et al., 2018).

Understanding generalization

A systematic classification of how people simplify space when drawing (Manivannan et al., 2022), followed by a method for detecting those simplifications automatically (Manivannan et al., 2024).

Quantitative accuracy measures

Integration of the Gardony Map Drawing Analyzer and bi-dimensional regression, giving metric configural accuracy alongside the relational measures.

Key references

Gardony, A. L., Taylor, H. A., & Brunyé, T. T. (2016). Gardony Map Drawing Analyzer: Software for quantitative analysis of sketch maps. Behavior Research Methods, 48, 151–177. doi:10.3758/s13428-014-0556-x
Manivannan, C., Krukar, J., & Schwering, A. (2024). An algorithmic approach to detect generalization in sketch maps from sketch map alignment. PLOS ONE. doi:10.1371/journal.pone.0304696
Manivannan, C., Krukar, J., & Schwering, A. (2022). Spatial generalization in sketch maps: A systematic classification. Journal of Environmental Psychology. doi:10.1016/j.jenvp.2022.101851
Krukar, J., Münzer, S., Lörch, L., Anacta, V. J., Fuest, S., & Schwering, A. (2018). Distinguishing Sketch Map Types: A Flexible Feature-Based Classification. Springer. doi:10.1007/978-3-319-96385-3_19
Schwering, A., Wang, J., Chipofya, M., Jan, S., Li, R., & Broelemann, K. (2014). SketchMapia: Qualitative Representations for the Alignment of Sketch and Metric Maps. Spatial Cognition & Computation. Link
Bi-dimensional regression as introduced for cognitive-map comparison by Tobler, and formalized by Friedman & Kohler (2003).

Technical reference

You do not need any of this to use the tool. It is here for research software engineers, for anyone installing it locally, and for readers who want to verify exactly how a measure is computed.

How the software is put together

⌄

Each analysis method runs as an independent service with its own address, coordinated by the main web application. This means a method can be updated or added without disturbing the others.

Component	Address	Role
sketchmap_analyser	`:8000`	Editor, alignment, results table, export
generalizations	`:8001`	Builds the generalized reference map
completeness	`:8002`	Recall measures
qualitativerelations	`:8003`	Relational measures
validation	`:8004`	Geometry cleanup (researcher-approved)
gmda	`:8005`	Configural accuracy
bdr	`:8006`	Bi-dimensional regression

The main application calls these services from the browser — directly by port locally, and through a reverse proxy in production.

Installing and running it yourself

⌄

git clone https://github.com/ifgi-sil/SketchMapia-Microservices.git
cd SketchMapia-Microservices
docker-compose up --build

Then open http://localhost:8000/generalizingmaps/.

Production deployment uses prebuilt container images published automatically on each release, updated on the server by Watchtower and served behind an Apache reverse proxy that handles HTTPS.

Programmatic access (API)

⌄

Each service accepts map data as GeoJSON via HTTP POST and returns measures as JSON. Useful for batch processing outside the interface.

Endpoint	Returns
`/generalizations/requestFME/`	The generalized reference map
`/completeness/analyzeCompleteness/`	Completeness measures
`/accuracy/analyzeQualitative/`	Relational measures and full relation lists
`/validation/validate/`	Proposed or applied geometry corrections
`/gmda/calculateGMDA/`	Configural measures (landmarks)
`/gmda/calculateJunctionGMDA/`	Configural measures (junctions)
`/bdr/calculateLandmarksBDR/`	Regression parameters (landmarks)
`/bdr/calculateJunctionsBDR/`	Regression parameters (junctions)

{
  "CanOrg": 0.0962,
  "CanAcc": 0.8917,
  "ScaBias": -0.0001,
  "DistAcc": 0.9358,
  "RotBias": -30.2334,
  "AngAcc": 0.7942,
  "nTL": 14,
  "nDL": 5
}

nTL is the number of reference features; nDL the number drawn.

Exactly how each measure is computed

⌄

Full formulas, derivations and implementation notes live with the source code:

Measure family	Documentation
Completeness	completeness
Relational accuracy	accuracy
Generalization	generalizations
Configural accuracy	gmda
Bi-dimensional regression	bdr
Geometry cleanup	validation
Interface and export	sketchmap_analyser

Source code: github.com/ifgi-sil/SketchMapia-Microservices

Start SKETCHMAPIA View on GitHub Go to HOME