Proposal: YAZA Atlas Maps Engine

Status: Draft proposal — awaiting owner review
Proposed engine name: YAZA Atlas
Scope: YAZA-owned geospatial kernel, map data pipeline, renderer, offline packs, and later search/routing services

1. Goal

YAZA Atlas is the proposed map engine for YAZA web, server, and mobile applications. The implementation should be authored in YAZA and its native runtime, integrated with YAZA's compiler, async scheduler, UI, data modules, and Pulse events. It should render and query map data efficiently while preserving interoperability with published geospatial formats and services.

“YAZA-owned engine” means YAZA owns and reviews its geometry algorithms, parsers, indexes, tile pipeline, render planning, labels, cache, and service APIs. It does not mean YAZA owns the underlying map data. Geographic datasets have separate providers, licenses, update schedules, and attribution requirements. OpenStreetMap data, for example, is licensed under ODbL and requires attribution and license notices; each dataset and tile source must be reviewed independently.

The goal is a strong, useful mapping platform, not a promise to be faster or more complete than existing products. Speed, memory, battery use, coverage, and correctness must be measured against equivalent features and data.

2. Product shape

The proposed public packages are:

The names are proposals. Module boundaries should be finalized after the language has package versioning, capability declarations, and independently linkable runtime modules.

3. Engine architecture

3.1 Geospatial kernel

The kernel should provide typed Longitude, Latitude, projected coordinates, Bounds, Point, LineString, Polygon, and Multi* geometry values. APIs must distinguish coordinate order and coordinate reference system (CRS); conversion cannot silently reinterpret coordinates. The first supported geodetic model should be WGS 84, with a clearly enumerated projection set beginning with geographic coordinates and Web Mercator. More CRS transformations require published control-point fixtures and an explicit accuracy budget. Grid-based datum transformations should be a later capability with separately versioned grid data.

Use Float64 for geodetic calculations, robust predicates around boundaries, and explicit handling for antimeridian wrapping, poles, invalid rings, self-intersections, and degenerate geometry. The kernel should include haversine/geodesic distance, point-in-polygon, segment intersection, bounds intersection, clipping, and simplification as independently tested operations. Do not substitute approximate planar math for geodesic behavior without an explicit API name.

3.2 Spatial index and feature store

Implement a static packed Hilbert R-tree for immutable datasets and a separately bounded dynamic index for edits and moving features. Index entries refer to stable feature IDs and may carry a generation number so stale query results can be detected after updates. Query APIs should support bounding-box, point-radius, and exact geometry predicates; broad-phase index matches must not be reported as exact geometry matches.

Large source files must be processed as bounded streams. Geometry count, coordinate count, nesting, properties, index size, and query work all receive explicit limits. Cancellation should interrupt parsing and query loops promptly. Index construction should be deterministic for identical input and options.

3.3 Tile and data pipeline

Separate logical data from transport: a layer consumes typed features; a tile source provides vector, raster, elevation, or terrain chunks; a tile matrix set maps world coordinates to tile keys. Support ordinary XYZ addressing and OGC tile-matrix metadata, including alternate matrix sets and CRS definitions. Tile requests need bounded concurrency, deduplication, deadlines, cancellation, stale-response rejection, and a byte-budgeted cache.

Interoperability is a first-class requirement. Implement YAZA-owned readers/writers for GeoJSON and OGC API Features first, then documented vector-tile and raster profiles. OGC API - Tiles is the preferred web-service contract because it describes tile retrieval through tile matrix sets and supports vector, map, coverage, and other tile content. Keep format adapters separate from the YAZA feature model. A future YAZA offline pack may use a versioned .ymap container, but it must have a public binary specification, integrity checks, atomic update/recovery rules, and import/export tools before being treated as a stable format. Do not make a private format the only way to use the engine.

GeoPackage is a valuable interchange target, but it is a SQLite-based container. It should be scheduled only after the project decides how to implement its required database compatibility without adding an unreviewed third-party runtime. Until then, clearly state that .gpkg is unsupported; do not approximate it with a renamed custom file.

3.4 Renderer and platform path

The renderer should use a retained scene and display-list model with incremental invalidation. CPU work prepares compact draw batches; GPU work handles repeated symbols, circles, lines, fills, heatmap accumulation, and raster composition. Cache compiled style expressions and geometry buffers by source generation, style revision, tile key, and device scale. Label placement should use bounded candidate sets, collision grids, stable priorities, and small hysteresis windows to reduce flicker while panning.

Use one renderer interface with backends: WebGPU for capable browsers, WebGL2 as the compatibility fallback, and direct native graphics APIs such as Metal or Vulkan through narrow YAZA-owned host adapters. WebGPU cannot be the only web backend today because browser support remains limited. The common non-GPU pipeline should be shared across targets; backend code must not depend on a bundled third-party map renderer. Web and mobile should use the same style and scene semantics while allowing platform-specific text, accessibility, and input behavior.

The render loop should share YAZA Frame Engine scheduling concepts: publish immutable frame snapshots, coalesce redundant state changes, prioritize visible tiles, and stop optional work when the frame deadline is near. Network and disk operations must not block rendering. Rendering and data work should consume explicit memory, CPU, GPU-resource, and battery budgets. Device loss and context restoration must rebuild resources from CPU-side state.

3.5 Style, interaction, and accessibility

Define a typed YAZA style language for sources, layers, filters, expressions, zoom ranges, paint, and layout. Validate style types at compile time where possible. Provide deterministic defaults and a small, readable starter style, while keeping colors, typography, icons, and controls aligned with YAZA UI tokens. Support pan, zoom, rotate, pitch, feature picking, keyboard operation, screen-reader descriptions, reduced motion, high contrast, and touch input.

The first renderer target is a useful 2D map with vector fills/lines/symbols, raster tiles, hit testing, and feature selection. Clustering, animated routes, heatmaps, elevation, terrain, globe projection, 3D buildings, indoor maps, and scene overlays follow only after the 2D profile is stable.

4. Search, geocoding, and routing

These are distinct data products, not automatic consequences of drawing a map. Geocoding requires a licensed address/place dataset and update pipeline. Routing requires a road graph, access restrictions, turn costs, travel profiles, and a documented data license. Live traffic requires a lawful real-time feed; the engine cannot create coverage from code alone.

The later routing module should import an open, versioned road-data profile into a YAZA-owned compact graph; calculate routes with A* and a YAZA-owned multi-level preprocessing strategy; and expose route cost, restrictions, alternatives, and explanation metadata. Routing correctness needs road-network fixtures and route-quality comparison, not only speed tests. Turn-by-turn guidance, transit, trucks, bicycles, pedestrians, and motorcycles each require separate profile support. Do not advertise a mode as available where its underlying dataset is incomplete.

Place search should begin with local indexed feature search and an explicit remote provider interface. Search results must include source attribution and freshness. Offline geocoding is a separate downloadable dataset with size and license information.

5. Proposed API sketch

This is illustrative syntax, not currently supported by the compiler:

use "yaza.atlas"
use "yaza.atlas.data"

start:
    let source = atlas_data.geojson("assets/places.geojson")
    let map = atlas.create(width: 1280, height: 720, center: geo.coordinate(-6.2, 106.8), zoom: 11)
    map.layer("places", source).symbols(icon: "pin", label: "name")
    map.fit_to(source.bounds())
    atlas.render(map)

The final API must use explicit CRS and ownership semantics and must not load remote data implicitly.

6. Security, privacy, and licensing

• Parse untrusted geometry and tile payloads under byte, feature, nesting, coordinate, decompression, CPU, and allocation budgets.
• Reject malformed numeric values, non-finite coordinates, overlong strings, invalid geometry rings, and integer overflow.
• Network tile sources require explicit origin policy, TLS validation, request deadlines, redirect limits, and SSRF protections on servers. Browser CORS behavior must remain visible to users.
• Offline packs require path-safe extraction, integrity verification, atomic update behavior, and explicit storage limits. Checksums detect corruption; they are not authentication.
• Device location is a capability requiring explicit user permission, platform authorization, and a clear retention policy. Do not place raw location values in logs by default.
• Every dataset adapter records source, license, attribution text, date, and update procedure. Dataset redistribution terms must be reviewed before bundling data into templates or installers.
• Use YAZA-owned implementations for the engine, but rely on the operating system for narrow graphics, filesystem, and permission APIs. This proposal does not authorize copying or vendoring another map engine.

7. Delivery stages and exit gates

1. Geo kernel: coordinate/CRS types, WGS 84/Web Mercator profiles, bounds, core geometry operations, fixtures, fuzz targets, and accuracy report.
2. Static data: bounded GeoJSON reader, feature model, static spatial index, query API, and CLI inspection tool.
3. 2D native renderer: deterministic software-rendered reference images and a native GPU adapter; style, symbols, labels, pan/zoom, and hit testing.
4. Web renderer: WebGPU backend with WebGL2 fallback; browser conformance, device-loss tests, accessibility, and responsive resizing.
5. Tile services and cache: OGC API - Tiles client/server building blocks, cancellation, bounded cache, slow-source handling, and request tests.
6. Offline profiles: public .ymap specification or a separately approved standard-container path; import/export, recovery, integrity, and license metadata.
7. Mobile: Android first per RFC 0008, then iOS; location permission, lifecycle, GPU loss, background limits, and battery measurements.
8. Search and routing: separate proposals and data-license review before implementation; route-quality corpus, coverage report, and stale-data policy.
9. 3D and advanced layers: terrain, buildings, globe, heatmaps, and large-data visualization after 2D correctness and resource budgets pass.

Every stage must have positive/negative fixtures, malformed and oversized inputs, sanitizer/fuzz runs, deterministic visual regressions, performance measurements, and a support table. Compare only equivalent render style, data, camera, hardware, scale, cache state, and GPU backend. Report frame-time percentiles, tile latency, cold/warm startup, memory, GPU memory, battery where available, and data size. “Fastest” requires repeatable head-to-head evidence.

8. Standards and research references

• OGC API - Tiles and its overview describe tile retrieval, tile matrix sets, metadata, and interoperability building blocks.
• OGC API - Features defines interoperable web access to geographic features.
• OGC GeoPackage is a portable SQLite-based geospatial container; YAZA support is a later scoped target, not an existing feature.
• RFC 7946 GeoJSON is the initial interchange profile.
• PROJ coordinate operations documentation is a reference for the distinction among projections, conversions, and datum transformations; it is not a runtime dependency or an implementation to copy.
• MapLibre GL JS documentation and its graphics modernization roadmap are public examples of GPU rendering and backend separation used for design research only. YAZA will not use MapLibre's implementation.
• MDN WebGPU API currently reports limited availability, supporting the proposed WebGPU plus WebGL2 fallback approach.
• OpenStreetMap copyright and license guidance must be consulted for any OSM data distribution; other datasets need their own license review.

9. Status

YAZA currently has no geospatial feature model, map renderer, tile engine, geocoder, route engine, or mobile map view. This document is a draft proposal only. Nothing in it is implementation evidence or a claim that map data comes bundled with YAZA.

← Kembali ke semua dokumentasiVersi dan status rilis →