
View A5 cells on an interactive map
a5_view.RdRenders A5 cells with deck.gl over a MapLibre basemap. Cells are drawn as filled pentagons; the viewer provides a basemap switcher, an opacity slider, a legend for numeric fills, hover tooltips, and an optional polygon-draw tool.
Usage
a5_view(
cells,
fill = "#74ac90ff",
fill_identity = FALSE,
palette = "Viridis",
opacity = 0.3,
tooltip = TRUE,
elevation = NULL,
elevation_scale = 1,
border = "#74ac9080",
border_width = 1,
width = NULL,
height = NULL,
lng = NULL,
lat = NULL,
zoom = NULL,
globe = FALSE,
basemap = c("dark", "light", "osm", "satellite"),
draw_polygon = FALSE,
aggregate = c("none", "rep_child", "mean"),
lod_step = 1L
)Arguments
- cells
An a5R::a5_cell or a5R::a5_covering vector, or a data frame / tibble containing a column of either. A covering is drawn as the cells it stores, at their mixed resolutions; uncompact it with
a5R::a5_uncompact()first to draw its cells at one resolution. Each row of a covering column is repeated once per stored cell. Pyramids (aggregateother than"none") need cells at one resolution.- fill
Fill colour specification. One of:
A single hex colour string (e.g.
"#3388ff") for uniform fill.A numeric vector (same length as cells) mapped to
palette.A character vector of hex colours (same length as cells) for per-cell colours.
An unquoted column name when
cellsis a data frame.An expression evaluated against the columns of
cells, in the style ofggplot2::aes(). This makes the colour helperscells_rgb()andcells_pca_rgb()usable directly inside the call, e.g.a5_view(df, fill = cells_rgb(r, g, b))ora5_view(df, fill = cells_pca_rgb(embedding)). The helpers tag their output sofill_identityis auto-enabled. Default:"#74ac90ff".
- fill_identity
Logical. When
TRUE, treatfillvalues as literal colours rather than mapping throughpalette. Accepts packed RGB integers ((R << 16) | (G << 8) | B) or hex colour strings. Auto-enabled whenfillis produced bycells_rgb()/cells_pca_rgb()or any vector tagged withattr(x, "a5_identity") <- TRUE. Default:FALSE.- palette
Colour palette used when
fillis numeric. Either a palette name accepted bygrDevices::hcl.colors()(e.g."viridis","inferno","plasma","turbo","rocket") or a character vector of hex colours (at least 2). Default:"Viridis".- opacity
Numeric scalar, initial layer opacity (0–1). An interactive slider is provided in the viewer to adjust at runtime. Default:
0.3.- tooltip
Logical, or a character vector of column names from
cells.TRUE(default) shows the hovered cell's id plus its fill value whenfillis a numeric mapping. A character vector adds those columns to the tooltip (requiresaggregate = "none").FALSEdisables the tooltip. The tooltip only appears over cells present in the data (see the section on hover and click below).- elevation
Column name for 3D extrusion, or
NULLfor flat.- elevation_scale
Numeric scalar, scale factor for elevation.
- border
Border (stroke) colour for cell outlines, or
NULLfor no borders. A single colour string (e.g."#ffffff","white"). Default:"#74ac9080".- border_width
Numeric scalar, border width in pixels. Default:
1.- width, height
Widget dimensions. Default:
NULL(fills container).- lng, lat, zoom
Initial map view. If
NULL(default), auto-centres on the cell centroids.- globe
Logical. Use MapLibre's globe projection instead of the default Mercator map. Default:
FALSE.- basemap
Character vector of basemap styles to make available. Options are
"dark","light"and"osm"(OpenFreeMap vector tiles; no API key),"satellite"(Esri World Imagery) and"none". The first element is shown initially. When more than one is given, an interactive selector is shown. Default:c("dark", "light", "osm", "satellite").- draw_polygon
Logical. When
TRUE, adds a "Draw polygon" toggle to the controls panel. While draw mode is active, clicks place polygon vertices and a double-click closes the polygon. On completion, the polygon is emitted to Shiny as a WKT string atinput$<id>_polygon_draw; the drawn outline is held on screen until the user toggles draw mode off, presses Escape, or starts a new polygon. While draw mode is on, double-click-to-zoom is suppressed and cell-pick click events do not fire. The widget itself does not visualise which cells fall inside the polygon: resolve the WKT server-side (e.g. witha5R::a5_polygon_to_cells()) and update the map fills viaa5_view_update(). The outline is drawn with straight edges on the Web Mercator map, buta5R::a5_polygon_to_cells()reads edges as great circles, so along a long edge the selected cells can stray from the outline; place more vertices to keep them close. Only useful in a Shiny context. Default:FALSE.- aggregate
How parent cells are summarised when zooming out. One of:
"none"(default): no precomputed pyramid. All cells are shipped as Arrow IPC and rendered through deck.gl'sA5Layer. Cheapest to build, suitable for small to medium datasets."rep_child": each parent inherits the row of the child whose payload (RGBA + optionalfill_value/elevation) is closest in Euclidean distance to its parent's mean. Preserves real values, no blending. Use for embedding/RGB visualisations."mean": each numeric payload column is averaged independently within the parent group. Best for scalar fields; blends colours in RGB space, which can mute embedding visualisations. When set to"rep_child"or"mean", the pyramid is serialised to parquet with a spatial row-group index. The browser decodes only the row groups intersecting the viewport at the level of detail matching the current zoom. Inside Shiny the parquet file is served over HTTP with byte-range support, so only the footer and the visible row groups are ever transferred; elsewhere it is embedded in the widget as base64.
- lod_step
Integer >= 1, gap between successive precomputed LODs (only used when
aggregate != "none").1(default) precomputes every level from the data resolution down to the floor (LOD 2); larger values trade size for fewer levels and more visible popping at zoom transitions.
Hover, click and Shiny inputs
Hover and click only resolve to cells that are present in the data:
the tooltip, the outline highlight and the Shiny inputs below stay
empty over parts of the map with no cell. With aggregate = "none"
the resolved cell is the leaf cell under the cursor. With a pyramid
it is the cell at the level of detail currently on screen, so the id
and value reported are those of the pentagon you can see; zoom in
to reach the leaf cells.
When rendered in Shiny with output id <id>, the widget sets:
input$<id>_hover: hex id of the cell under the cursor (orNULL).input$<id>_click: hex id of the clicked cell; clicking it again, or clicking empty map, clears it.input$<id>_cursor,input$<id>_click_coord:list(lng, lat)of the pointer.input$<id>_polygon_draw: WKT of a completed polygon (seedraw_polygon).