# Georeferencing RMS is not accuracy
# https://tidyecology.com/posts/georeferencing-rms-is-not-accuracy/
#
# The R code of this Tidy Ecology tutorial, chunk by chunk, in the order of the post.
# Run it top to bottom in a fresh R session. Code the post shows but does not run
# is commented out. The prose, and the numbers it quotes, are in the post itself.
# Post last modified: 2026-11-04

## ---- setup ----
library(ggplot2)
library(terra)

te_pal <- list(forest = "#275139", green = "#2f8f63", sage = "#93a87f",
               clay = "#b5534e", gold = "#cda23f", line = "#dad9ca",
               ink = "#16241d", paper = "#f5f4ee")

theme_te <- function() {
  theme_minimal(base_size = 12) +
    theme(panel.grid.minor = element_blank(),
          panel.grid.major = element_line(colour = "#e7e6dc"),
          plot.background = element_rect(fill = "#f5f4ee", colour = NA),
          panel.background = element_rect(fill = "#f5f4ee", colour = NA),
          plot.title = element_text(face = "bold", colour = te_pal$ink),
          axis.title = element_text(colour = "#2c3a31"))
}

## ---- sheet ----
marks <- read.csv("control-points-truth.csv")
sheet <- rast("scanned-sheet.png")
ref <- vect("reference-layer.gpkg", layer = "landmarks")

cat(sprintf("scan: %d by %d pixels, %d bands\n",
            ncol(sheet), nrow(sheet), nlyr(sheet)))
cat(sprintf("marks with known truth: %d, reference layer CRS EPSG:%s\n",
            nrow(marks), crs(ref, describe = TRUE)$code))
cat(sprintf("truth spans easting %.0f to %.0f, northing %.0f to %.0f\n",
            min(marks$mapX), max(marks$mapX), min(marks$mapY), max(marks$mapY)))
print(head(marks, 3), row.names = FALSE)

## ---- fig-sheet ----
# A PNG carries no geotransform, and GDAL versions disagree about which end of the
# file is the top of the picture, so the orientation is measured rather than assumed.
# The Gulf of Kelbray runs along the bottom of the sheet, so the lower fifth of the
# raster has to be the bluer one; if it is not, the raster is upside down.
blue_share <- function(r) {
  v <- values(r)
  mean(v[, 3] > v[, 1] + 20, na.rm = TRUE)
}
upper <- crop(sheet, ext(0, ncol(sheet), 0.8 * nrow(sheet), nrow(sheet)))
lower <- crop(sheet, ext(0, ncol(sheet), 0, 0.2 * nrow(sheet)))
if (blue_share(upper) > blue_share(lower)) sheet <- flip(sheet, "vertical")

op <- par(bg = te_pal$paper, mar = c(0, 0, 0, 0))
plotRGB(sheet, maxcell = 1.2e6, mar = 0)
par(op)

## ---- distortion ----
W <- 4000
H <- 3000
theta <- 3.2 * pi / 180
sx <- 2.51
sy <- 2.46
x0 <- 512300
y0 <- 5271800

affine_map <- function(px, py)
  list(X = x0 + sx * (cos(theta) * px - sin(theta) * py),
       Y = y0 - sy * (sin(theta) * px + cos(theta) * py))

true_map <- function(px, py) {
  u <- (px - W / 2) / (W / 2)
  v <- (py - H / 2) / (H / 2)
  bx <- 18 * sin(2.1 * u + 0.4) * cos(1.3 * v) +
        12 * exp(-((u + 0.45)^2 + (v - 0.35)^2) / 0.10)
  by <- 15 * sin(1.7 * v - 0.3) - 9 * cos(2.4 * u) * v +
        10 * exp(-((u - 0.50)^2 + (v + 0.40)^2) / 0.12)
  affine_map(px + bx / sx, py + by / sy)
}

fld <- expand.grid(px = seq(0, W, length.out = 60),
                   py = seq(0, H, length.out = 45))
aff <- affine_map(fld$px, fld$py)
tru <- true_map(fld$px, fld$py)
fld$bend <- sqrt((tru$X - aff$X)^2 + (tru$Y - aff$Y)^2)

cat(sprintf("paper deformation: %.1f m median over the sheet, %.1f m at worst\n",
            median(fld$bend), max(fld$bend)))
csv_chk <- true_map(marks$pixelX, marks$pixelY)
cat(sprintf("the CSV reproduces the model to %.0e m\n",
            max(abs(csv_chk$X - marks$mapX), abs(csv_chk$Y - marks$mapY))))

## ---- fig-distortion ----
ggplot(fld, aes(px, py, fill = bend)) +
  geom_raster() +
  scale_y_reverse() +
  coord_equal(expand = FALSE) +
  scale_fill_gradient(low = te_pal$paper, high = te_pal$forest, name = "metres") +
  labs(title = "The paper deformation is not a polynomial",
       subtitle = "distance from the position a pure rotation and scale would give",
       x = "scan column (pixels)", y = "scan row (pixels)") +
  theme_te()

## ---- gdal ----
fit_and_apply <- function(gcp, mode, px, py) {
  args <- paste(sprintf("-gcp %.4f %.4f %.4f %.4f",
                        gcp$px, gcp$py, gcp$X, gcp$Y), collapse = " ")
  fin <- tempfile()
  writeLines(sprintf("%.6f %.6f", px, py), fin)
  raw <- system(sprintf("gdaltransform %s %s < %s", args, mode, fin),
                intern = TRUE, ignore.stderr = TRUE)
  unlink(fin)
  m <- do.call(rbind, lapply(strsplit(trimws(raw), "\\s+"), as.numeric))
  data.frame(X = m[, 1], Y = m[, 2])
}

modes <- c("Polynomial 1" = "-order 1", "Polynomial 2" = "-order 2",
           "Polynomial 3" = "-order 3", "Thin plate spline" = "-tps")

hull_of <- function(px, py)
  vect(cbind(px, py)[chull(px, py), ], type = "polygons")
in_hull <- function(px, py, hp)
  as.vector(relate(vect(cbind(px, py)), hp, "intersects"))

## ---- real-sheet ----
marks$role <- ifelse(rank(sqrt((marks$pixelX - W / 2)^2 +
                               (marks$pixelY - H / 2)^2)) <= 12,
                     "control", "held back")
gcp <- with(marks[marks$role == "control", ],
            data.frame(px = pixelX, py = pixelY, X = mapX, Y = mapY))
held <- marks[marks$role == "held back", ]
held$inside <- in_hull(held$pixelX, held$pixelY, hull_of(gcp$px, gcp$py))

cat(sprintf("control marks: %s\n",
            paste(marks$label[marks$role == "control"], collapse = " ")))
cat(sprintf("held back: %d marks, %d of them inside the control hull\n",
            nrow(held), sum(held$inside)))

sheet_tab <- do.call(rbind, lapply(names(modes), function(nm) {
  g <- fit_and_apply(gcp, modes[[nm]], gcp$px, gcp$py)
  k <- fit_and_apply(gcp, modes[[nm]], held$pixelX, held$pixelY)
  e <- sqrt((k$X - held$mapX)^2 + (k$Y - held$mapY)^2)
  data.frame(transform = nm,
             reported = round(sqrt(mean((g$X - gcp$X)^2 + (g$Y - gcp$Y)^2)), 2),
             held_out = round(sqrt(mean(e^2)), 2),
             worst = round(max(e), 2))
}))
print(sheet_tab, row.names = FALSE)

## ---- sheets ----
draw_sheet <- function(click = 0) {
  g <- data.frame(px = runif(12, 0.18 * W, 0.82 * W),
                  py = runif(12, 0.18 * H, 0.82 * H))
  tr <- true_map(g$px, g$py)
  g$X <- tr$X + rnorm(12, 0, click)
  g$Y <- tr$Y + rnorm(12, 0, click)
  inx <- runif(9, 0.25 * W, 0.75 * W)
  iny <- runif(9, 0.25 * H, 0.75 * H)
  outx <- c(runif(5, 0.02 * W, 0.14 * W), runif(4, 0.86 * W, 0.98 * W))
  outy <- c(runif(5, 0.02 * H, 0.98 * H), runif(4, 0.02 * H, 0.98 * H))
  k <- data.frame(px = c(inx, outx), py = c(iny, outy),
                  where = rep(c("central", "marginal"), c(9, 9)))
  tr <- true_map(k$px, k$py)
  k$X <- tr$X
  k$Y <- tr$Y
  list(gcp = g, chk = k)
}

score_sheet <- function(sh) vapply(modes, function(md) {
  g <- fit_and_apply(sh$gcp, md, sh$gcp$px, sh$gcp$py)
  k <- fit_and_apply(sh$gcp, md, sh$chk$px, sh$chk$py)
  e <- sqrt((k$X - sh$chk$X)^2 + (k$Y - sh$chk$Y)^2)
  c(reported = sqrt(mean((g$X - sh$gcp$X)^2 + (g$Y - sh$gcp$Y)^2)),
    central = sqrt(mean(e[sh$chk$where == "central"]^2)),
    marginal = sqrt(mean(e[sh$chk$where == "marginal"]^2)),
    worst = max(e))
}, numeric(4))

run_sheets <- function(click = 0, reps = 100) {
  set.seed(227)
  acc <- array(NA_real_, c(reps, 4, 4),
               dimnames = list(NULL, names(modes),
                               c("reported", "central", "marginal", "worst")))
  hits <- matrix(0L, reps, 2, dimnames = list(NULL, c("central", "marginal")))
  for (r in seq_len(reps)) {
    sh <- draw_sheet(click)
    acc[r, , ] <- t(score_sheet(sh))
    ok <- in_hull(sh$chk$px, sh$chk$py, hull_of(sh$gcp$px, sh$gcp$py))
    hits[r, ] <- c(sum(ok[1:9]), sum(ok[10:18]))
  }
  list(acc = acc, hits = hits)
}

set.seed(227)
demo <- draw_sheet()
demo$chk$inside <- in_hull(demo$chk$px, demo$chk$py,
                           hull_of(demo$gcp$px, demo$gcp$py))
print(table(drawn = demo$chk$where, in_control_hull = demo$chk$inside))

## ---- fig-hull ----
gcp_d <- demo$gcp
hull_d <- gcp_d[chull(gcp_d$px, gcp_d$py), ]
hull_d <- rbind(hull_d, hull_d[1, ])

ggplot() +
  annotate("rect", xmin = 0, xmax = W, ymin = 0, ymax = H, fill = NA,
           colour = te_pal$ink, linewidth = 0.4) +
  geom_path(data = hull_d, aes(px, py), colour = te_pal$gold,
            linewidth = 0.9, linetype = "dashed") +
  geom_point(data = gcp_d, aes(px, py), colour = te_pal$forest,
             size = 3.2, shape = 17) +
  geom_point(data = demo$chk, aes(px, py, colour = where), size = 2.6) +
  scale_colour_manual(values = c(central = te_pal$green,
                                 marginal = te_pal$clay),
                      name = "check point") +
  scale_y_reverse() +
  coord_equal() +
  labs(title = "Twelve control points, eighteen check points",
       subtitle = "triangles are control points; the dashed line is their convex hull",
       x = "scan column (pixels)", y = "scan row (pixels)") +
  theme_te()

## ---- replicates ----
exact <- run_sheets(click = 0)
print(round(t(apply(exact$acc, c(2, 3), median)), 2))

## ---- fig-compare ----
med <- apply(exact$acc, c(2, 3), median)
cmp_df <- data.frame(
  tf = factor(rep(names(modes), times = 3), levels = rev(names(modes))),
  what = rep(c("reported RMS at the control points",
               "true error at central check points",
               "true error at marginal check points"), each = 4),
  value = c(med[, "reported"], med[, "central"], med[, "marginal"]))

ggplot(cmp_df, aes(value, tf, colour = what)) +
  geom_point(size = 3.6) +
  scale_colour_manual(values = c(te_pal$gold, te_pal$green, te_pal$clay),
                      name = NULL) +
  labs(title = "The number on the screen falls; the error does not",
       subtitle = "median over 100 replicate sheets, 12 control points each",
       x = "metres on the ground", y = NULL) +
  theme_te() +
  theme(legend.position = "bottom") +
  guides(colour = guide_legend(ncol = 1))

## ---- shares ----
cat("central check points inside the control hull:",
    sprintf("%.1f %%\n", 100 * sum(exact$hits[, "central"]) / (100 * 9)))
cat("marginal check points inside the control hull:",
    sprintf("%.1f %%\n", 100 * sum(exact$hits[, "marginal"]) / (100 * 9)))
cat("\nsheets where the reported RMS is below the true central error\n")
for (nm in names(modes))
  cat(sprintf("  %-18s %5.1f %%\n", nm,
              100 * mean(exact$acc[, nm, "reported"] <
                         exact$acc[, nm, "central"])))
cat(sprintf("\nsheets where Polynomial 3 extrapolates worse than Polynomial 1: %.1f %%\n",
            100 * mean(exact$acc[, "Polynomial 3", "marginal"] >
                       exact$acc[, "Polynomial 1", "marginal"])))

## ---- fig-extrap ----
extrap_df <- data.frame(a = exact$acc[, "Polynomial 1", "marginal"],
                        b = exact$acc[, "Polynomial 3", "marginal"])

ggplot(extrap_df, aes(a, b)) +
  geom_abline(slope = 1, intercept = 0, linetype = "dashed",
              colour = te_pal$ink) +
  geom_point(colour = te_pal$clay, alpha = 0.75, size = 2.2) +
  scale_x_log10(breaks = c(8, 10, 12, 15, 18)) +
  scale_y_log10() +
  labs(title = "More freedom, worse extrapolation",
       subtitle = "error at the marginal check points, one point per sheet, log axes",
       x = "Polynomial 1 (metres)", y = "Polynomial 3 (metres)") +
  theme_te()

## ---- clicks ----
noisy <- run_sheets(click = 5)
print(round(t(apply(noisy$acc, c(2, 3), median)), 2))
