Repository navigation
Expand file tree
/
Copy pathreference.rs
More file actions
565 lines (519 loc) · 27.4 KB
/
Copy pathreference.rs
File metadata and controls
565 lines (519 loc) · 27.4 KB
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
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
//! The reference archive: pooled bare-earth height on the OBCT lattice, as GeoTIFF tiles that a
//! bake streams one at a time. A max archive holds `int16` metres; a mean archive, the `mean/`
//! part of a prepared version, holds `int32` decimetres.
//!
//! A country-sized reference does not fit in memory, so the archive is addressed rather than
//! loaded. Its lattice is the OBCT lattice at `2^6` µdeg (≈ 7.1 × 4.9 m at 47 °N) and its tiles are
//! `2^16` µdeg squares of 1024 × 1024 pixels, so a tile id is arithmetic on a coordinate and a bake
//! asks for the hundred tiles one cell's rule reads and nothing else.
//!
//! Two properties of the format make a 7 m archive usable as the reference:
//!
//! * A pixel is a maximum, not a sample. Ingest keeps the largest source height whose pixel centre
//! falls inside the pixel's square, so a rock tower one source pixel wide survives the pooling.
//! `−32768` means no source pixel reached the square, and the contract permits no other nodata.
//! * The transform is the lattice, exactly. There is no reprojection and no resampling here:
//! [`ReferenceTile`] holds every tile to the transform its id implies, to `1e-9`°, and refuses
//! the file by name otherwise.
//!
//! `index.json` says which tiles the archive has, who contributed to each of them, the digest of
//! each one's pixels and what every source must be credited as. A mirror of one box carries the
//! whole index and only its own tiles, so a tile the index names and the disk does not hold is
//! absent, not an error; a tile that is on disk but broken is an error.
//!
//! The digests and the credits are what a bakery needs on top of a bake. The terrain bakery keys
//! its per-cell skip decision on the digests of the tiles one cell reads
//! ([`held_digests`](ReferenceArchive::held_digests)), so an archive update re-bakes the cells
//! whose window holds a changed tile and nothing else; and it carries every source's credit into
//! the published catalog ([`credits`](ReferenceArchive::credits)).
//!
//! Nothing here is mutated after [`ReferenceArchive::open`], so an archive is `Sync` and a bakery
//! may read one from several threads. A lookup reports what it found and the caller keeps the
//! tally, which is also the only way attribution can be honest, since only a tile that was actually
//! decoded contributed to a container.
use std::collections::BTreeMap;
use std::fs::File;
use std::io::BufReader;
use std::path::{Path, PathBuf};
use obc_formats::obct::{GRID_ORIGIN, WORLD_SIDE};
use tiff::decoder::{Decoder, DecodingResult};
use tiff::tags::Tag;
use crate::geotiff::{read_north_up, RasterType};
/// Archive lattice step as `log2(µdeg)`: `2^6` µdeg on both axes.
pub const STEP_LOG2: u8 = 6;
/// Archive tile side as `log2(µdeg)`: `2^16` µdeg, which is 1024 pixels.
pub const TILE_LOG2: u8 = 16;
/// Pixels along one tile edge.
pub const TILE_PIXELS: usize = 1 << (TILE_LOG2 - STEP_LOG2);
/// "No source pixel reached this square" — the one nodata value of a max archive.
pub const NO_PIXEL: i16 = i16::MIN;
/// The one nodata value of a mean archive.
const NO_MEAN: i32 = i32::MIN;
pub(crate) const STEP: i64 = 1 << STEP_LOG2;
pub(crate) const TILE_UDEG: i64 = 1 << TILE_LOG2;
pub(crate) const ORIGIN: i64 = GRID_ORIGIN as i64;
/// Tiles along one axis of the world box, so a tile id is bounded before it becomes a path.
const TILES_PER_AXIS: i64 = WORLD_SIDE as i64 >> TILE_LOG2;
/// Transform tolerance in degrees, as the tile contract states it. A microdegree is `1e-6`, so this
/// admits floating-point noise and nothing an operator could have meant.
const TRANSFORM_EPS: f64 = 1e-9;
/// A half-open µdeg box: the archive pixels one bake reads.
///
/// Half-open because it is a union of half-posting node cells, which partition the plane the same
/// way the archive's own pixels do — a pixel centre on the box's high edge belongs to the next node,
/// and so to the next bake.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Window {
pub lat_lo: i64,
pub lat_hi: i64,
pub lon_lo: i64,
pub lon_hi: i64,
}
impl Window {
/// The tiles this window intersects, tile-major (`ti` then `tj`) so a bake's pass over them is
/// one fixed order. Tiles outside the world box are not named: the lattice does not wrap, so a
/// window that reaches past the antimeridian or a pole simply reads fewer tiles.
pub fn tiles(&self) -> impl Iterator<Item = (u32, u32)> + Clone {
let rows = tile_span(self.lat_lo, self.lat_hi);
let cols = tile_span(self.lon_lo, self.lon_hi);
rows.flat_map(move |ti| cols.clone().map(move |tj| (ti, tj)))
}
}
/// The tile indices a half-open µdeg span touches, clipped to the world box.
fn tile_span(lo: i64, hi: i64) -> std::ops::Range<u32> {
if hi <= lo {
return 0..0;
}
let first = (lo - ORIGIN).div_euclid(TILE_UDEG).max(0);
let last = (hi - 1 - ORIGIN).div_euclid(TILE_UDEG).min(TILES_PER_AXIS - 1);
first as u32..(last + 1).max(first) as u32
}
/// What a pixel of an archive is.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Pool {
/// The maximum of the source pixel centres in the square, as `int16` metres.
Max,
/// Their mean, as `int32` decimetres.
Mean,
}
/// One archive tile, decoded: 1024 × 1024 metres with `r` counting north, NaN where no source
/// pixel reached the square.
///
/// The GeoTIFF stores rows north-up; the flip happens here, once, exactly as `DemTile` does it, so
/// no index downstream of this module has to decide which way is north.
pub struct ReferenceTile {
ti: u32,
tj: u32,
pixels: Vec<f32>,
}
impl std::fmt::Debug for ReferenceTile {
/// The heights are two million numbers, so a tile prints as what it is: an id.
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "ReferenceTile({}/{})", self.ti, self.tj)
}
}
impl ReferenceTile {
/// The south-west corner of pixel `(0, 0)`, in µdeg — this tile's place on the lattice.
pub fn origin_udeg(&self) -> (i64, i64) {
(ORIGIN + i64::from(self.ti) * TILE_UDEG, ORIGIN + i64::from(self.tj) * TILE_UDEG)
}
/// Every pixel of this tile that has a height and whose centre lies in `window`, as
/// `(lat, lon, metres)` in µdeg, row-major with `r` counting north.
pub fn centres_in(&self, window: Window, mut visit: impl FnMut(i64, i64, f32)) {
let (lat0, lon0) = self.origin_udeg();
let rows = centre_span(window.lat_lo, window.lat_hi, lat0);
let cols = centre_span(window.lon_lo, window.lon_hi, lon0);
for r in rows {
let lat = lat0 + r as i64 * STEP + STEP / 2;
let row = &self.pixels[r * TILE_PIXELS..(r + 1) * TILE_PIXELS];
for c in cols.clone() {
let height = row[c];
if !height.is_nan() {
visit(lat, lon0 + c as i64 * STEP + STEP / 2, height);
}
}
}
}
/// The metres of pixel `(r, c)`, `r` counting north, or `None` where no source pixel reached it.
pub fn height(&self, r: usize, c: usize) -> Option<f32> {
Some(self.pixels[r * TILE_PIXELS + c]).filter(|height| !height.is_nan())
}
/// Decode and validate the tile at `path`, which must be the tile the id names.
pub fn open(path: &Path, ti: u32, tj: u32, pool: Pool) -> Result<ReferenceTile, String> {
let north_up = decode(path, (ti, tj), 1, pool)?;
Ok(ReferenceTile::flipped(ti, tj, &north_up, 0, 0, TILE_PIXELS))
}
/// Decode the block of a prepared version of `terrain` at `path`, 4 × 4 tiles in one raster, and
/// give its tile `(ti, tj)`.
pub fn open_in_block(path: &Path, ti: u32, tj: u32, pool: Pool) -> Result<ReferenceTile, String> {
let side = BLOCK_TILES * TILE_PIXELS;
let north_up = decode(path, (ti / BLOCK_TILES as u32, tj / BLOCK_TILES as u32), BLOCK_TILES, pool)?;
let row = (BLOCK_TILES - 1 - ti as usize % BLOCK_TILES) * TILE_PIXELS;
let col = tj as usize % BLOCK_TILES * TILE_PIXELS;
Ok(ReferenceTile::flipped(ti, tj, &north_up, row, col, side))
}
/// The tile whose north-up pixels start at `(row, col)` of a raster `side` pixels wide.
fn flipped(ti: u32, tj: u32, north_up: &[f32], row: usize, col: usize, side: usize) -> ReferenceTile {
let mut pixels = vec![0f32; TILE_PIXELS * TILE_PIXELS];
for r in 0..TILE_PIXELS {
let start = (row + TILE_PIXELS - 1 - r) * side + col;
pixels[r * TILE_PIXELS..(r + 1) * TILE_PIXELS].copy_from_slice(&north_up[start..start + TILE_PIXELS]);
}
ReferenceTile { ti, tj, pixels }
}
}
/// Tiles along one side of a block of a prepared version of `terrain`.
const BLOCK_TILES: usize = 4;
/// The north-up heights of the raster at `path`: `tiles` × `tiles` archive tiles whose south-west
/// tile is `tiles × (i, j)`, held to the lattice and to the nodata of `pool`.
fn decode(path: &Path, (i, j): (u32, u32), tiles: usize, pool: Pool) -> Result<Vec<f32>, String> {
let name = || path.display().to_string();
let side = tiles * TILE_PIXELS;
let file = File::open(path).map_err(|e| format!("{}: {e}", name()))?;
// The `tiff` crate's default limits allow a 256 MiB decoding buffer; a block of the mean is
// 64 MiB, so the archive never approaches them.
let mut dec = Decoder::new(BufReader::new(file)).map_err(|e| format!("{}: not a readable TIFF ({e})", name()))?;
let (width, height) = dec.dimensions().map_err(|e| format!("{}: no dimensions ({e})", name()))?;
if (width as usize, height as usize) != (side, side) {
return Err(format!("{}: {width}×{height} — the raster is {side}²", name()));
}
if let Ok(bands) = dec.get_tag_u32(Tag::SamplesPerPixel) {
if bands != 1 {
return Err(format!("{}: {bands} bands — an archive tile has one", name()));
}
}
let (ti, tj) = (i * tiles as u32, j * tiles as u32);
expect_lattice(&mut dec, (ti + tiles as u32 - 1, tj), &name)?;
let nodata = match pool {
Pool::Max => f64::from(NO_PIXEL),
Pool::Mean => f64::from(NO_MEAN),
};
if let Ok(text) = dec.get_tag_ascii_string(Tag::GdalNodata) {
let declared = text.trim().trim_end_matches('\0').parse::<f64>().ok();
if declared != Some(nodata) {
return Err(format!("{}: nodata {text:?} — the archive's nodata is {nodata}", name()));
}
}
let north_up: Vec<f32> = match (pool, dec.read_image().map_err(|e| format!("{}: decode failed ({e})", name()))?) {
(Pool::Max, DecodingResult::I16(values)) => {
values.into_iter().map(|v| if v == NO_PIXEL { f32::NAN } else { f32::from(v) }).collect()
}
(Pool::Mean, DecodingResult::I32(values)) => {
values.into_iter().map(|v| if v == NO_MEAN { f32::NAN } else { v as f32 / 10.0 }).collect()
}
(Pool::Max, _) => return Err(format!("{}: not int16 — a max archive stores whole metres", name())),
(Pool::Mean, _) => return Err(format!("{}: not int32 — a mean archive stores decimetres", name())),
};
if north_up.len() != side * side {
return Err(format!("{}: decoded {} samples for a {side}² raster", name(), north_up.len()));
}
Ok(north_up)
}
/// The pixel indices of a tile whose centres lie in a half-open µdeg span, given the tile's own
/// origin on that axis.
fn centre_span(lo: i64, hi: i64, origin: i64) -> std::ops::Range<usize> {
let index = |bound: i64| ceil_div(bound - origin - STEP / 2, STEP).clamp(0, TILE_PIXELS as i64) as usize;
let (first, last) = (index(lo), index(hi));
first..last.max(first)
}
fn ceil_div(a: i64, b: i64) -> i64 {
a.div_euclid(b) + i64::from(a.rem_euclid(b) != 0)
}
/// Hold a raster's georeferencing to the lattice, with the north-west corner of tile `(ti, tj)` as
/// its own, and refuse the file by name.
///
/// [`read_north_up`] has already refused anything that is not a north-up WGS 84 grid. What is left
/// is what an archive tile adds: the grid must be this tile's square of the lattice, and a pixel
/// must be an area. Each of those moves ground rather than losing it — a wrong scale stretches the
/// tile, a wrong tie point slides it, `PixelIsPoint` shifts it half a pixel.
fn expect_lattice<R: std::io::Read + std::io::Seek>(
dec: &mut Decoder<R>,
(ti, tj): (u32, u32),
name: &impl Fn() -> String,
) -> Result<(), String> {
let north_up = read_north_up(dec, name)?;
if north_up.raster_type != RasterType::Area {
return Err(format!("{}: GTRasterTypeGeoKey is point — an archive pixel is an area (1)", name()));
}
// A `PixelIsArea` tie point names the raster's north-west corner, which for tile (ti, tj) is the
// lattice line the id puts it on.
let step = STEP as f64 / 1e6;
let want_lat = (ORIGIN + (i64::from(ti) + 1) * TILE_UDEG) as f64 / 1e6;
let want_lon = (ORIGIN + i64::from(tj) * TILE_UDEG) as f64 / 1e6;
for (what, actual, want) in [
("pixel scale (lon)", north_up.step_lon_deg, step),
("pixel scale (lat)", north_up.step_lat_deg, step),
("origin lon", north_up.tie_lon_deg, want_lon),
("origin lat", north_up.tie_lat_deg, want_lat),
] {
if (actual - want).abs() > TRANSFORM_EPS {
return Err(format!("{}: {what} {actual} — tile {ti}/{tj} is {want} on the lattice", name()));
}
}
Ok(())
}
/// What a published map owes one reference source: `index.json`'s `sources` entry.
///
/// A bakery copies these into the catalog verbatim, because a map derived from a source carries
/// that source's licence obligation and a consumer must read the wording from the document rather
/// than hard-code it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SourceCredit {
/// The source key, as `tiles` and `contributors` name it — `"ch"`.
pub key: String,
pub product: String,
pub attribution: String,
pub licence: String,
}
/// What the index says about one tile: who is in it, and what its pixels hash to.
struct IndexedTile {
/// Every source with a surviving pixel in the tile, best first — `index.json`'s `contributors`,
/// which is what attribution reads.
sources: Vec<String>,
/// The index's digest of the tile's pixels. Opaque here: a bakery keys its skip on it.
sha256: String,
}
/// An archive root, or a mirror of one: its `index.json` read, its tiles left on disk.
pub struct ReferenceArchive {
root: PathBuf,
pool: Pool,
/// Every tile the index names.
tiles: BTreeMap<(u32, u32), IndexedTile>,
/// Every source the index declares, sorted by key.
credits: Vec<SourceCredit>,
/// The `glo30_bias_m` of each source that states one.
biases: BTreeMap<String, f64>,
}
/// What an archive holds for one tile id.
///
/// The three cases are different facts, and a caller needs all three: only a tile it actually
/// decoded may be credited in the attribution, only a tile the index promised and the disk lacked
/// is worth telling an operator about, and a tile no index names is simply outside the archive.
/// Keeping them apart is also what lets [`ReferenceArchive`] stay immutable, and so `Sync`.
pub enum TileLookup<'a> {
/// Decoded, with every source that contributed a pixel to it, best first.
Held { tile: ReferenceTile, sources: &'a [String] },
/// The index names it and this root does not hold it — which is what a mirror of one box looks
/// like, and also what a copy that stopped half way looks like.
Absent,
/// No index entry: not in the archive at all.
Unknown,
}
impl ReferenceArchive {
/// Read an archive's index. The tiles stay on disk until [`tile`](Self::tile) asks for one.
pub fn open(root: &Path) -> Result<ReferenceArchive, String> {
let path = root.join("index.json");
let text = std::fs::read_to_string(&path).map_err(|e| format!("{}: {e}", path.display()))?;
let index: serde_json::Value =
serde_json::from_str(&text).map_err(|e| format!("{}: not readable JSON ({e})", path.display()))?;
let name = || path.display().to_string();
for (field, want) in
[("schema", 1u64), ("step_log2", u64::from(STEP_LOG2)), ("tile_log2", u64::from(TILE_LOG2))]
{
match index.get(field).and_then(serde_json::Value::as_u64) {
Some(value) if value == want => {}
Some(value) => return Err(format!("{}: {field} {value} — this reader reads {want}", name())),
None => return Err(format!("{}: no {field} — not a reference archive index", name())),
}
}
// An index written before the mean pool names no pool.
let pool = match index.get("pool").map(|pool| pool.as_str()) {
None | Some(Some("max")) => Pool::Max,
Some(Some("mean")) => Pool::Mean,
Some(other) => return Err(format!("{}: pool {other:?} — this reader reads max and mean", name())),
};
let tiles = index
.get("tiles")
.and_then(serde_json::Value::as_object)
.ok_or_else(|| format!("{}: no `tiles` map", name()))?;
// `contributors` lists every source with a surviving pixel in a tile; `tiles` names only the
// best-priority one. An index written before `contributors` existed has just the one, and a
// one-source tile is the common case anyway.
let listed = index.get("contributors").and_then(serde_json::Value::as_object);
let digests = index.get("sha256").and_then(serde_json::Value::as_object);
let credits = read_credits(&index, &name)?;
let sources = index["sources"].as_object().into_iter().flatten();
let biases =
sources.filter_map(|(key, entry)| Some((key.clone(), entry.get("glo30_bias_m")?.as_f64()?))).collect();
let mut held = BTreeMap::new();
for (id, best) in tiles {
let key = tile_id(id).ok_or_else(|| format!("{}: `{id}` is not a tile id", name()))?;
let sources: Vec<String> = match listed.and_then(|map| map.get(id)).and_then(serde_json::Value::as_array) {
Some(array) => array.iter().filter_map(|v| v.as_str()).map(str::to_string).collect(),
None => best.as_str().map(str::to_string).into_iter().collect(),
};
if let Some(unknown) = sources.iter().find(|source| !credits.iter().any(|c| &c.key == *source)) {
return Err(format!(
"{}: tile `{id}` credits source `{unknown}`, which `sources` does not declare — a map derived \
from it could not be attributed",
name()
));
}
// The digest is what a bakery's per-cell skip decision is keyed on, so an index without
// one is refused here rather than silently making every terrain bake a full one.
let sha256 = digests
.and_then(|map| map.get(id))
.and_then(serde_json::Value::as_str)
.ok_or_else(|| format!("{}: tile `{id}` has no `sha256` — a bakery keys its skip on it", name()))?;
if sha256.len() != 64 || !sha256.bytes().all(|b| b.is_ascii_digit() || b.is_ascii_lowercase() && b <= b'f')
{
return Err(format!("{}: tile `{id}`'s sha256 `{sha256}` is not 64 lowercase hex digits", name()));
}
held.insert(key, IndexedTile { sources, sha256: sha256.to_string() });
}
Ok(ReferenceArchive { root: root.to_path_buf(), pool, tiles: held, credits, biases })
}
pub fn pool(&self) -> Pool {
self.pool
}
/// Tiles the index names.
pub fn len(&self) -> usize {
self.tiles.len()
}
pub fn is_empty(&self) -> bool {
self.tiles.is_empty()
}
/// Every source this archive declares, sorted by key — the credits a map derived from it owes.
pub fn credits(&self) -> &[SourceCredit] {
&self.credits
}
/// The best source of tile `(ti, tj)` and its `glo30_bias_m`, `None` where the index states
/// none: the bias of GLO-30 next to the tile.
pub fn bias(&self, ti: u32, tj: u32) -> Option<(&str, Option<f64>)> {
let best = self.tiles.get(&(ti, tj))?.sources.first()?;
Some((best, self.biases.get(best).copied()))
}
/// The pixel digests the index states for the tiles of `window` this root holds, in the window's
/// own tile order.
///
/// This is what a bakery keys one cell's skip decision on, so it names the tiles the bake will
/// read and nothing else: a tile the index promises and this mirror lacks contributes no digest,
/// because it will contribute no pixel either, and one that arrives later therefore changes the
/// key and re-bakes the cell. Held is decided by the tile being a file rather than by decoding
/// it — a skip decision must not cost a hundred tile decodes.
pub fn held_digests(&self, window: Window) -> Vec<(u32, u32, &str)> {
window
.tiles()
.filter_map(|(ti, tj)| {
let tile = self.tiles.get(&(ti, tj))?;
self.tile_path(ti, tj).is_file().then_some((ti, tj, tile.sha256.as_str()))
})
.collect()
}
fn tile_path(&self, ti: u32, tj: u32) -> PathBuf {
self.root.join(format!("{TILE_LOG2}/{ti:04}/{tj:04}.tif"))
}
/// Look tile `(ti, tj)` up, decoding it if this archive holds it.
///
/// A tile the index names but the disk does not hold is [`TileLookup::Absent`], not an error:
/// that is what a mirror of one box looks like. A tile that is on disk and does not hold the
/// contract is an error naming the file.
pub fn tile(&self, ti: u32, tj: u32) -> Result<TileLookup<'_>, String> {
let Some(tile) = self.tiles.get(&(ti, tj)) else {
return Ok(TileLookup::Unknown);
};
let path = self.tile_path(ti, tj);
if !path.is_file() {
return Ok(TileLookup::Absent);
}
Ok(TileLookup::Held { tile: ReferenceTile::open(&path, ti, tj, self.pool)?, sources: &tile.sources })
}
}
/// `index.json`'s `sources` block as the credits a map owes, sorted by key.
///
/// Sorted rather than left in the document's own order, because a bakery copies these into a
/// published catalog: two archives that declare the same sources must produce the same list, or the
/// catalog would differ by which order an ingest happened to write.
///
/// Every field is required and non-empty. A source that cannot state its product, its credit and
/// its licence must not be published beside a map derived from it, and the archive is the only
/// place that knows the wording.
fn read_credits(index: &serde_json::Value, name: &impl Fn() -> String) -> Result<Vec<SourceCredit>, String> {
let sources = index
.get("sources")
.and_then(serde_json::Value::as_object)
.ok_or_else(|| format!("{}: no `sources` map", name()))?;
let mut credits: Vec<SourceCredit> = sources
.iter()
.map(|(key, entry)| {
let field = |field: &str| -> Result<String, String> {
entry
.get(field)
.and_then(serde_json::Value::as_str)
.map(str::trim)
.filter(|text| !text.is_empty())
.map(str::to_string)
.ok_or_else(|| {
format!("{}: source `{key}` has no `{field}` — a map derived from it owes it", name())
})
};
Ok(SourceCredit {
key: key.clone(),
product: field("product")?,
attribution: field("attribution")?,
licence: field("licence")?,
})
})
.collect::<Result<_, String>>()?;
credits.sort_by(|a, b| a.key.cmp(&b.key));
Ok(credits)
}
/// `"<ti>/<tj>"` as a tile id, or `None` when it names no square of the world box.
fn tile_id(text: &str) -> Option<(u32, u32)> {
let (ti, tj) = text.split_once('/')?;
let index = |part: &str| part.parse::<u32>().ok().filter(|&t| i64::from(t) < TILES_PER_AXIS);
Some((index(ti)?, index(tj)?))
}
#[cfg(test)]
mod tests {
use super::*;
/// A tile id is arithmetic on a coordinate, and the Engelberg archive's own ids are the pin: the
/// tile holding 46.75 N 8.30 E is `4809/4222`, and its transform is what the reader demands.
#[test]
fn a_tile_id_is_the_coordinate_shifted_onto_the_lattice() {
let lat = 46_750_000i64;
let lon = 8_300_000i64;
assert_eq!(((lat - ORIGIN) >> TILE_LOG2, (lon - ORIGIN) >> TILE_LOG2), (4809, 4222));
// …and the window of a µdeg box holds exactly the tiles that box touches.
let one = Window { lat_lo: lat, lat_hi: lat + 1, lon_lo: lon, lon_hi: lon + 1 };
assert_eq!(one.tiles().collect::<Vec<_>>(), vec![(4809, 4222)]);
// A box that ends exactly on a tile line does not reach the next tile: the box is half-open.
let line = ORIGIN + 4810 * TILE_UDEG;
let upto = Window { lat_lo: line - 1, lat_hi: line, lon_lo: lon, lon_hi: lon + 1 };
assert_eq!(upto.tiles().collect::<Vec<_>>(), vec![(4809, 4222)]);
let across = Window { lat_lo: line - 1, lat_hi: line + 1, lon_lo: lon, lon_hi: lon + 1 };
assert_eq!(across.tiles().collect::<Vec<_>>(), vec![(4809, 4222), (4810, 4222)]);
}
/// The lattice does not wrap and it does not go past the world box, so neither does a window.
/// This is what keeps a cell at the antimeridian from reading ground on the far side of the
/// world, and a negative coordinate from naming a tile the archive cannot hold.
#[test]
fn a_window_outside_the_world_box_names_no_tile() {
let past = ORIGIN + TILES_PER_AXIS * TILE_UDEG;
assert_eq!(Window { lat_lo: past, lat_hi: past + 1, lon_lo: 0, lon_hi: 1 }.tiles().count(), 0);
assert_eq!(Window { lat_lo: 0, lat_hi: 1, lon_lo: past, lon_hi: past + 1 }.tiles().count(), 0);
// A window straddling the east edge keeps the tiles inside it and drops the rest.
let edge = Window { lat_lo: 0, lat_hi: 1, lon_lo: past - 1, lon_hi: past + TILE_UDEG };
assert_eq!(edge.tiles().collect::<Vec<_>>(), vec![(4096, (TILES_PER_AXIS - 1) as u32)]);
// Far below the origin is not a tile either — µdeg there are negative on both axes.
assert_eq!(Window { lat_lo: ORIGIN - 10, lat_hi: ORIGIN - 1, lon_lo: 0, lon_hi: 1 }.tiles().count(), 0);
// …and a negative µdeg inside the world box is an ordinary tile.
assert_eq!(tile_id("0/0"), Some((0, 0)));
assert_eq!(tile_id(&format!("{TILES_PER_AXIS}/0")), None, "past the world box is not a tile id");
assert_eq!(tile_id("16/4809/4222"), None);
assert_eq!(tile_id("ch"), None);
}
/// Pixel centres sit half a step inside the tile's own edges, so the first and last pixel of a
/// window are decided by a centre and never by a boundary.
#[test]
fn a_window_selects_the_pixels_whose_centres_it_holds() {
let origin = ORIGIN + 4809 * TILE_UDEG;
// The first centre is at origin + 32 µdeg: a box that stops there holds nothing.
assert_eq!(centre_span(origin, origin + STEP / 2, origin), 0..0);
assert_eq!(centre_span(origin, origin + STEP / 2 + 1, origin), 0..1);
// Exactly one node cell of the v1 posting, centred on the tile's 8th pixel boundary.
assert_eq!(centre_span(origin + 8 * STEP, origin + 16 * STEP, origin), 8..16);
// A window wider than the tile is clipped to it, on both sides.
assert_eq!(centre_span(origin - TILE_UDEG, origin + 2 * TILE_UDEG, origin), 0..TILE_PIXELS);
}
}