Package {vantorr}

Add a Vantor Vivid Mosaic Basemap to a Leaflet Map

Description

Adds a high-resolution Vantor / Maxar Vivid Mosaic basemap (VIVID_STANDARD_30 or VIVID_ADVANCED_15) to a leaflet or leafletProxy map widget using either pre-cached OGC WMTS tiles (recommended for fast interactive panning) or dynamic OGC WMS rendering.

Usage

add_vantor_basemap(
  map,
  product = "VIVID_STANDARD_30",
  service = c("WMTS", "WMS"),
  api_key = NULL,
  group = "Vantor Vivid",
  layerId = NULL,
  show_seamlines = FALSE,
  cql_filter = NULL,
  shoreline_masking = FALSE,
  max_zoom = 21L,
  attribution = "Imagery © Vantor / Maxar Technologies",
  options = NULL,
  verbose = getOption("vantorr.verbose", TRUE)
)

addVantorBasemap(
  map,
  product = "VIVID_STANDARD_30",
  service = c("WMTS", "WMS"),
  api_key = NULL,
  group = "Vantor Vivid",
  layerId = NULL,
  show_seamlines = FALSE,
  cql_filter = NULL,
  shoreline_masking = FALSE,
  max_zoom = 21L,
  attribution = "Imagery © Vantor / Maxar Technologies",
  options = NULL,
  verbose = getOption("vantorr.verbose", TRUE)
)

Arguments

Value

The modified leaflet or leaflet_proxy map object.

Examples

if (requireNamespace("leaflet", quietly = TRUE)) {
  m <- leaflet::leaflet() |>
    add_vantor_basemap(
      product = "VIVID_STANDARD_30",
      api_key = "example_api_key",
      verbose = FALSE
    )
}

Add Vantor Archive Streaming Imagery to a Leaflet Map

Description

Streams individual archive satellite imagery strips or filtered collections from the Vantor / Maxar Streaming Imagery OGC WMS endpoint (⁠https://api.maxar.com/streaming/v1/ogc/wms⁠) onto a leaflet or leafletProxy map.

Usage

add_vantor_imagery(
  map,
  feature_id = NULL,
  cql_filter = NULL,
  api_key = NULL,
  group = "Vantor Archive Imagery",
  layerId = NULL,
  format = "image/vnd.jpeg-png",
  transparent = TRUE,
  max_zoom = 21L,
  attribution = "Imagery © Vantor / Maxar Technologies",
  options = NULL,
  verbose = getOption("vantorr.verbose", TRUE)
)

addVantorImagery(
  map,
  feature_id = NULL,
  cql_filter = NULL,
  api_key = NULL,
  group = "Vantor Archive Imagery",
  layerId = NULL,
  format = "image/vnd.jpeg-png",
  transparent = TRUE,
  max_zoom = 21L,
  attribution = "Imagery © Vantor / Maxar Technologies",
  options = NULL,
  verbose = getOption("vantorr.verbose", TRUE)
)

Arguments

Value

The modified leaflet or leaflet_proxy map object.

Examples

if (requireNamespace("leaflet", quietly = TRUE)) {
  m <- leaflet::leaflet() |>
    add_vantor_imagery(
      feature_id = "10300100EBEDF600",
      api_key = "example_api_key",
      verbose = FALSE
    )
}

Add Vantor Basemap Seamlines to a Leaflet Map

Description

Overlays Vantor / Maxar Vivid Mosaic seamlines onto a leaflet or leafletProxy map. Supports either fast OGC WMS raster cutline rendering (mode = "wms", default) or interactive OGC WFS vector polygons (mode = "wfs") with clickable popups displaying acquisition date (acq_time), resolution (gsd), sensor (sensor), and catalog ID (catid).

Usage

add_vantor_seamlines(
  map,
  product = "VIVID_STANDARD_30",
  mode = c("wms", "wfs"),
  bbox = NULL,
  api_key = NULL,
  group = "Vantor Seamlines",
  layerId = NULL,
  cql_filter = NULL,
  color = "#00E5FF",
  weight = 2,
  options = NULL,
  verbose = getOption("vantorr.verbose", TRUE)
)

addVantorSeamlines(
  map,
  product = "VIVID_STANDARD_30",
  mode = c("wms", "wfs"),
  bbox = NULL,
  api_key = NULL,
  group = "Vantor Seamlines",
  layerId = NULL,
  cql_filter = NULL,
  color = "#00E5FF",
  weight = 2,
  options = NULL,
  verbose = getOption("vantorr.verbose", TRUE)
)

Arguments

Value

The modified leaflet or leaflet_proxy map object.

Examples

if (requireNamespace("leaflet", quietly = TRUE)) {
  m <- leaflet::leaflet() |>
    add_vantor_seamlines(
      product = "VIVID_STANDARD_30",
      api_key = "example_api_key",
      verbose = FALSE
    )
}

Convert Lat/Lon Bounding Box to Web Mercator

Description

Helper function to convert a bounding box or spatial object from EPSG:4326 (lat/lon) to EPSG:3857 (Web Mercator).

Usage

convert_bbox_to_3857(bbox_4326)

Arguments

Value

Numeric vector of length 4 with bounding box coordinates in EPSG:3857: c(x_min, y_min, x_max, y_max).

Examples

# Denver area in lat/lon
bbox_latlon <- c(-105.01, 39.72, -104.96, 39.75)
bbox_mercator <- convert_bbox_to_3857(bbox_latlon)

Create Maxar / Vantor API Request with Authentication

Description

Helper function to create an httr2 request with Vantor/Maxar bearer token or API key authentication and built-in retry logic for transient HTTP errors.

Usage

create_maxar_request(url, token = NULL, api_key = NULL, verbose = FALSE)

Arguments

Value

An httr2_request object with authentication headers and retry policies set.

Examples

req <- create_maxar_request(
  "https://api.maxar.com/discovery/v1",
  api_key = "example_key"
)

Get Maxar / Vantor API Bearer Token

Description

Retrieves a bearer token from the Maxar/Vantor Authentication API using the OAuth2 Password Flow and caches it in the current session for automatic refresh.

Usage

get_maxar_token(
  username = Sys.getenv("VANTOR_USERNAME", unset = Sys.getenv("MAXAR_USERNAME", unset =
    "")),
  password = Sys.getenv("VANTOR_PASSWORD", unset = Sys.getenv("MAXAR_PASSWORD", unset =
    "")),
  verbose = getOption("vantorr.verbose", TRUE)
)

Arguments

Value

A list containing the token response (access_token, expires_in, refresh_token, token_type), or NULL (with an alert) if the API cannot be reached.

Examples

if (vantor_has_auth() && nzchar(Sys.getenv("VANTOR_USERNAME"))) {
  token_response <- get_maxar_token(verbose = FALSE)
}

Get Maxar / Vantor WMS Basemap as GeoTIFF or Spatial Raster Object

Description

Retrieves a Maxar/Vantor Vivid Mosaic basemap (30 cm or 15 cm) via OGC WMS for a specified area of interest. Supports spatial inputs from sf, terra, and stars, as well as numeric bounding boxes, and can return a file path, terra::SpatRaster, or stars object.

Usage

get_maxar_wms_basemap(
  bbox,
  token = NULL,
  output_file = tempfile(pattern = "vantor_basemap_", fileext = ".tif"),
  width = NULL,
  height = NULL,
  resolution = 0.3,
  product = "VIVID_STANDARD_30",
  crs = c("EPSG:3857", "EPSG:4326"),
  cql_filter = NULL,
  shoreline_masking = FALSE,
  api_key = NULL,
  return_type = c("file", "SpatRaster", "stars", "stars_proxy"),
  verbose = getOption("vantorr.verbose", TRUE)
)

Arguments

Value

Depending on return_type, the path to the saved GeoTIFF file (invisibly when return_type = "file"), a SpatRaster, or a stars object. Returns NULL invisibly (with an informative message) if the API request fails.

Examples

if (vantor_has_auth()) {
  # Define area of interest using an sf bounding box (WGS84)
  aoi <- sf::st_bbox(
    c(xmin = -105.005, ymin = 39.735, xmax = -105.000, ymax = 39.740),
    crs = sf::st_crs(4326)
  )

  # Retrieve basemap to a temporary GeoTIFF file
  tif_file <- get_maxar_wms_basemap(
    bbox = aoi,
    resolution = 0.5,
    verbose = FALSE
  )
}

Get Multiple WMS Basemap Tiles for Large Areas

Description

Splits a large area of interest into a regular grid of tiles, downloads each tile via get_maxar_wms_basemap(), and optionally merges them into a single GeoTIFF, terra::SpatRaster, or stars object.

Usage

get_maxar_wms_tiles(
  bbox,
  token = NULL,
  api_key = NULL,
  tile_size = 2500,
  output_dir = tempfile(pattern = "vantor_tiles_"),
  merge_tiles = TRUE,
  final_output = tempfile(pattern = "vantor_merged_", fileext = ".tif"),
  return_type = c("file", "SpatRaster", "stars", "stars_proxy"),
  progress_callback = NULL,
  verbose = getOption("vantorr.verbose", TRUE),
  ...
)

Arguments

Value

If merge_tiles = TRUE, returns the merged output formatted according to return_type. If merge_tiles = FALSE, returns a character vector of downloaded tile file paths.

Examples

if (vantor_has_auth()) {
  large_aoi <- sf::st_bbox(
    c(xmin = -105.02, ymin = 39.72, xmax = -104.98, ymax = 39.75),
    crs = sf::st_crs(4326)
  )
  merged_path <- get_maxar_wms_tiles(
    bbox = large_aoi,
    tile_size = 2000,
    resolution = 1.0,
    verbose = FALSE
  )
}

Refresh Maxar / Vantor API Bearer Token

Description

Refreshes a bearer token using a refresh token, avoiding the need to resend username and password, and updates the session token cache.

Usage

refresh_maxar_token(
  refresh_token = .vantorr_env$refresh_token,
  verbose = getOption("vantorr.verbose", TRUE)
)

Arguments

Value

A list containing the new token response, or NULL if refresh fails.

Examples

if (nzchar(Sys.getenv("VANTOR_USERNAME")) && nzchar(Sys.getenv("VANTOR_PASSWORD"))) {
  tok <- get_maxar_token(verbose = FALSE)
  if (!is.null(tok$refresh_token)) {
    new_token <- refresh_maxar_token(tok$refresh_token, verbose = FALSE)
  }
}

Launch Interactive Vantor Explorer Demo Shiny App

Description

Launches a standalone Shiny application combining vantor_auth_ui() and vantor_explorer_ui() for interactively browsing Vantor Vivid basemaps, inspecting seamline acquisition dates, monitoring account usage, and exporting GeoTIFFs.

Usage

run_vantor_demo_app(
  initial_bbox = c(xmin = -105.01, ymin = 39.73, xmax = -104.98, ymax = 39.75),
  verbose = getOption("vantorr.verbose", TRUE)
)

Arguments

Value

A shiny.appobj object.

Examples

if (interactive()) {
  run_vantor_demo_app()
}

Coerce Spatial Objects to a Bounding Box in a Target CRS

Description

S3 generic function that extracts a bounding box from spatial objects across major R geography packages (sf, terra, stars) or numeric vectors and transforms it to a target Coordinate Reference System (CRS).

Usage

vantor_as_bbox(x, target_crs = 3857, source_crs = NULL, ...)

Arguments

Value

An sf bbox object (c(xmin, ymin, xmax, ymax)) in target_crs.

Examples

# From a lat/lon numeric vector (automatically detected as EPSG:4326)
vantor_as_bbox(c(-105.01, 39.72, -104.96, 39.75), target_crs = 3857)

# From an sf bbox object
bb <- sf::st_bbox(c(xmin = -77.04, ymin = 38.88, xmax = -77.03, ymax = 38.89),
                  crs = sf::st_crs(4326))
vantor_as_bbox(bb, target_crs = 3857)

Authenticate with the Vantor / Maxar API

Description

Sets or retrieves authentication credentials for the current R session. Supports both long-lived API keys (maxar-api-key) and OAuth2 Bearer tokens (⁠Authorization: Bearer <token>⁠) with automatic refresh when expired.

Usage

vantor_auth(
  api_key = NULL,
  username = NULL,
  password = NULL,
  token = NULL,
  refresh_token = NULL,
  verbose = getOption("vantorr.verbose", TRUE)
)

Arguments

Details

By default, vantor_auth() checks the following environment variables if arguments are not explicitly supplied:

• VANTOR_API_KEY or MAXAR_API_KEY

• VANTOR_USERNAME or MAXAR_USERNAME

• VANTOR_PASSWORD or MAXAR_PASSWORD

Value

Invisibly returns a list representing the active authentication state, or NULL if no credentials could be resolved.

Note

Authentication Scope Across Vantor Endpoints:

• OGC & Non-Administrative APIs (get_maxar_wms_basemap(), get_maxar_wms_tiles(), vantor_get_seamlines()): Accept either an API key (maxar-api-key) or an OAuth2 Bearer token.

• Browser-Based leaflet Tile Layers (add_vantor_basemap(), add_vantor_seamlines(), add_vantor_imagery(), vantor_wmts_url()): Require an API key (maxar_api_key URL query parameter).

• Account Services / Admin APIs (vantor_get_usage()): Require an OAuth2 Bearer token (username and password, or token). Per the Vantor API specification, Admin APIs do not accept API keys.

Examples

# Check if credentials are configured in the environment
vantor_has_auth(verbose = FALSE)

# Set an API key for the current session
vantor_auth(api_key = "your_api_key_here", verbose = FALSE)

# Clear session credentials
vantor_auth_clear(verbose = FALSE)

Clear Stored Vantor Credentials

Description

Removes any cached API key or OAuth2 tokens from the internal session environment.

Usage

vantor_auth_clear(verbose = getOption("vantorr.verbose", TRUE))

Arguments

Value

Invisibly returns TRUE.

Examples

vantor_auth_clear(verbose = FALSE)

Vantor Authentication Shiny Module Server

Description

Server logic for the vantor_auth_ui() Shiny module. Manages session credentials, provides reactive authentication state for downstream modules (such as vantor_explorer_server()), and automatically refreshes OAuth2 bearer tokens in the background so long-running Shiny sessions do not expire.

Usage

vantor_auth_server(
  id,
  auto_refresh_ms = 3e+05,
  verbose = getOption("vantorr.verbose", TRUE)
)

Arguments

Value

A shiny::reactive expression returning a list with elements: authenticated (logical), type ("api_key", "bearer", or "none"), api_key (character or NULL), and updated_at (POSIXct).

Examples

if (requireNamespace("shiny", quietly = TRUE)) {
  server <- function(input, output, session) {
    auth_state <- vantor_auth_server("auth", verbose = FALSE)
  }
}

Vantor Authentication Shiny Module UI

Description

Creates a compact, namespace-safe Shiny UI panel for configuring Vantor / Maxar API credentials (API Key or OAuth2 Username/Password), displaying connection status, and optionally checking account credit usage.

Usage

vantor_auth_ui(id, show_usage = TRUE)

Arguments

Value

A shiny.tag.list UI definition.

Examples

if (requireNamespace("shiny", quietly = TRUE)) {
  ui <- shiny::fluidPage(
    vantor_auth_ui("auth")
  )
}

Vantor Interactive Imagery Explorer Shiny Module Server

Description

Server logic for the vantor_explorer_ui() Shiny module. Renders an interactive leaflet map with Vantor Vivid basemaps, updates layers via leaflet::leafletProxy(), queries WFS seamlines for the current viewport, and provides a shiny::downloadHandler() with progress bar integration for exporting GeoTIFFs via get_maxar_wms_basemap() or get_maxar_wms_tiles().

Usage

vantor_explorer_server(
  id,
  initial_bbox = c(xmin = -105.01, ymin = 39.73, xmax = -104.98, ymax = 39.75),
  auth_reactive = NULL,
  verbose = getOption("vantorr.verbose", TRUE)
)

Arguments

Value

A list of shiny::reactive expressions:

• bbox: Reactive sf::bbox (EPSG:4326) of the current map viewport

• seamlines: Reactive sf object of WFS seamlines when inspected

• product: Reactive selected Vivid product name

• resolution: Reactive selected ground resolution in meters

Examples

if (requireNamespace("shiny", quietly = TRUE) &&
    requireNamespace("leaflet", quietly = TRUE)) {
  server <- function(input, output, session) {
    explorer <- vantor_explorer_server("explorer", verbose = FALSE)
  }
}

Vantor Interactive Imagery Explorer Shiny Module UI

Description

Creates a drop-in, namespace-safe Shiny UI component featuring an interactive leaflet map with Vantor Vivid Mosaic basemap switching (VIVID_STANDARD_30 and VIVID_ADVANCED_15), seamline cutline overlay, WFS seamline vintage inspection, live AOI bounding box metrics, and one-click GeoTIFF export.

Usage

vantor_explorer_ui(id, height = "550px")

Arguments

Value

A shiny.tag.list UI definition.

Examples

if (requireNamespace("shiny", quietly = TRUE) &&
    requireNamespace("leaflet", quietly = TRUE)) {
  ui <- shiny::fluidPage(
    vantor_explorer_ui("explorer")
  )
}

Prepare and Export Survey Sample Points for CAPI Fieldwork Apps

Description

Enriches a set of survey sample locations (sf points or polygons, such as household structures, enumeration clusters, or ground-truth plots) with navigation and preload fields ready for ODK Collect, KoboToolbox, ArcGIS Survey123, World Bank Survey Solutions, and QField:

• sample_id: Unique formatted sample identifier

• longitude, latitude: WGS84 decimal degree coordinates

• odk_geopoint: Preload string ("<lat> <lon> 0 0") used by ODK / Kobo geopoint questions

• plus_code: Offline-capable 10-character Google Plus Code via vantor_plus_code()

• google_maps_url: One-click navigation link for mobile enumerators

• Optional grid cell assignment (cell_id) if a grid from vantor_survey_grid() is supplied

• Optional imagery vintage metadata (acq_date, sensor, gsd_m) if seamlines are supplied

Usage

vantor_export_capi(
  samples,
  id_col = NULL,
  grid = NULL,
  seamlines = NULL,
  output_csv = NULL,
  output_geojson = NULL,
  output_suso_tab = NULL,
  suso_gps_var = NULL,
  verbose = getOption("vantorr.verbose", TRUE)
)

Arguments

Details

Optionally writes the enriched dataset to a CSV preload table (output_csv) and/or a GeoJSON file (output_geojson).

Value

An enriched sf point object in EPSG:4326.

Examples

pts <- sf::st_as_sf(
  data.frame(
    hh_id = c("HH_01", "HH_02"),
    lon = c(-105.005, -105.002),
    lat = c(39.735, 39.738)
  ),
  coords = c("lon", "lat"),
  crs = 4326
)

capi_sf <- vantor_export_capi(pts, id_col = "hh_id", suso_gps_var = "hh_gps", verbose = FALSE)
head(capi_sf)

Generate a Printable Multi-Page Field Atlas (PDF Map Book)

Description

Creates a multi-page printable PDF Field Atlas (Map Book) for field supervisors and survey enumerators:

• Page 1 (Overview Index Map): Displays the full Area of Interest, all Enumeration Area / survey grid boundaries labeled by id_col (e.g., "A1", "A2"), sample points, scale bar, and north arrow.

• Subsequent Pages (Detail Enumeration Sheets): One page per grid cell or Enumeration Area polygon, zoomed in with a metric margin (buffer_m), optional high-resolution Vantor RGB satellite imagery background, labeled sample points, scale bar, north arrow, and a metadata header/footer with coordinates and imagery vintage.

Usage

vantor_field_atlas(
  grid,
  points = NULL,
  raster = NULL,
  output_file = tempfile(pattern = "vantor_field_atlas_", fileext = ".pdf"),
  id_col = "cell_id",
  point_label_col = "sample_id",
  title = "Vantor Field Enumeration Atlas",
  buffer_m = 50,
  fetch_basemap = FALSE,
  resolution = 0.5,
  product = "VIVID_STANDARD_30",
  paper_width = 11,
  paper_height = 8.5,
  verbose = getOption("vantorr.verbose", TRUE)
)

Arguments

Details

Works both offline (using a pre-downloaded raster SpatRaster or vector-only mode when fetch_basemap = FALSE) and online (fetching Vantor WMS basemap imagery automatically when fetch_basemap = TRUE).

Value

Invisibly returns the file path to the generated PDF Field Atlas.

Examples

aoi <- sf::st_bbox(
  c(xmin = -105.01, ymin = 39.73, xmax = -105.00, ymax = 39.74),
  crs = sf::st_crs(4326)
)
grid_sf <- vantor_survey_grid(aoi, cell_size = 600, verbose = FALSE)
pdf_path <- vantor_field_atlas(grid_sf, verbose = FALSE)
unlink(pdf_path)

Get Vantor Basemap Seamlines as an sf Object (OGC WFS)

Description

Queries the Vantor / Maxar Basemap Seamlines OGC Web Feature Service (WFS) to retrieve vector polygons representing the individual satellite imagery strips that make up a Vivid Mosaic basemap within an area of interest.

Usage

vantor_get_seamlines(
  bbox,
  product = "VIVID_STANDARD_30",
  cql_filter = NULL,
  token = NULL,
  api_key = NULL,
  verbose = getOption("vantorr.verbose", TRUE)
)

Arguments

Details

Each returned polygon feature typically includes metadata attributes such as:

• acq_time, acq_time_earliest, acq_time_latest: Imagery acquisition timestamp(s)

• gsd: Ground sample distance (resolution)

• sensor / vehicle_name: Satellite sensor identifier (e.g., "WV03", "WV02")

• ona: Off-nadir angle

• catid: Archive catalog ID of the source strip

Value

An sf object (in EPSG:4326) containing the seamline polygons and their acquisition metadata, or NULL invisibly if the API request fails.

Examples

if (vantor_has_auth()) {
  aoi <- sf::st_bbox(
    c(xmin = -105.01, ymin = 39.73, xmax = -104.99, ymax = 39.75),
    crs = sf::st_crs(4326)
  )
  seamlines <- vantor_get_seamlines(aoi, verbose = FALSE)
}

Get Vantor Account Usage and Credit Overview

Description

Queries the Vantor / Maxar Usage API (v2/activation/overview) to retrieve activation credit limits, total usage, and categorized consumption metrics. Useful for monitoring account quota in interactive R sessions or Shiny dashboards before launching large multi-tile downloads.

Usage

vantor_get_usage(
  category = c("PRODUCT", "DAY", "WEEK", "MONTH", "QUARTER"),
  unit = c("CREDIT", "FEATURE_COUNT", "REQUEST_COUNT", "MAP_VIEW", "GIGABYTE", "SQ_KM"),
  token = NULL,
  verbose = getOption("vantorr.verbose", TRUE)
)

Arguments

Value

A list containing the parsed usage overview response (including activations, usageCategories, and a tidy summary_df data frame when available), or NULL invisibly if the API request fails.

Note

Authentication Requirement (OAuth2 Bearer Token Only): The Usage API (⁠https://api.maxar.com/usage/v2/activation/overview⁠) is part of the Vantor Account Services (Admin API) (https://developers.maxar.com/docs/admin/guides/usage). Per the Vantor API specification, API keys (maxar-api-key) are not accepted by Admin APIs. You must authenticate using an OAuth2 Bearer Token via vantor_auth(username = "...", password = "...") (or VANTOR_USERNAME and VANTOR_PASSWORD in .Renviron), and your account must have Admin permissions to view activation usage.

Examples

if (nzchar(Sys.getenv("VANTOR_USERNAME")) && nzchar(Sys.getenv("VANTOR_PASSWORD"))) {
  usage <- vantor_get_usage(category = "PRODUCT", unit = "CREDIT", verbose = FALSE)
}

Check if Vantor Authentication is Available

Description

Checks whether an active session token, API key, or environment credentials are available. Useful for guarding examples and automated tests.

Usage

vantor_has_auth(verbose = FALSE)

Arguments

Value

Logical TRUE if authentication credentials are available, FALSE otherwise.

Examples

vantor_has_auth()

Package Offline Fieldwork Vector Layers and Satellite Basemaps

Description

Bundles survey grid cells, sample points, seamline vintage polygons, and high-resolution Vantor satellite imagery into a self-contained directory ready to copy onto mobile tablets for offline use in QField, Mergin Maps, ArcGIS Field Maps, World Bank Survey Solutions, or ODK Collect:

• Writes all vector layers (grid, samples, seamlines) into a single multi-layer OGC GeoPackage (.gpkg).

• Writes a CSV preload table (⁠<package_name>_samples.csv⁠) and a World Bank Survey Solutions tab-delimited assignment preload file (⁠<package_name>_suso_preload.tab⁠) when samples is provided.

• Saves or downloads the satellite basemap as a Web Mercator (EPSG:3857) georeferenced GeoTIFF (.tif).

• Optionally builds a multi-zoom Esri Tile Package (.tpk or .tpkx) via vantor_write_tpk() for zoomable offline basemaps in Survey Solutions (ArcGIS Maps SDK for .NET v200.x) and ArcGIS Field Maps.

• Optionally exports zipped Esri Shapefiles (⁠_shapes.zip⁠) for uploading vector Enumeration Area boundaries to Survey Solutions Headquarters.

Usage

vantor_offline_package(
  output_dir = tempfile(pattern = "vantor_offline_pkg_"),
  grid = NULL,
  samples = NULL,
  seamlines = NULL,
  raster = NULL,
  fetch_basemap = FALSE,
  create_tpk = FALSE,
  tpk_zoom = 15:16,
  create_shapefiles = FALSE,
  suso_gps_var = "hh_gps",
  resolution = 0.5,
  product = "VIVID_STANDARD_30",
  package_name = "vantor_fieldwork",
  verbose = getOption("vantorr.verbose", TRUE)
)

Arguments

Value

A list containing the paths to the generated offline bundle files: output_dir, gpkg_path, layers, csv_path, suso_tab_path, raster_path, tpk_path, tpk_zip_path, and shapefile_zip_path.

Examples

aoi <- sf::st_bbox(
  c(xmin = -105.01, ymin = 39.73, xmax = -105.00, ymax = 39.74),
  crs = sf::st_crs(4326)
)
grid_sf <- vantor_survey_grid(aoi, cell_size = 600, verbose = FALSE)
bundle <- vantor_offline_package(
  grid = grid_sf,
  create_shapefiles = TRUE,
  verbose = FALSE
)
unlink(bundle$output_dir, recursive = TRUE)

Encode Coordinates as Open Location Codes (Google Plus Codes)

Description

Converts WGS84 longitude and latitude coordinates into 10- or 11-character Open Location Codes (Plus Codes) (e.g., "85FQPPV4+2V"). Plus Codes are an open, offline-capable alphanumeric street address standard supported by Google Maps, ODK Collect, and field navigation apps without requiring an internet connection.

Usage

vantor_plus_code(lon, lat, code_length = 10L)

Arguments

Value

A character vector of formatted Plus Codes (with a "+" separator after the 8th character).

Examples

# Encode coordinates in downtown Denver, CO
vantor_plus_code(lon = -104.995, lat = 39.740)

Generate an Alphanumeric Survey Index Grid over an Area of Interest

Description

Partitions an Area of Interest (AOI) into a regular grid of square or hexagonal enumeration cells with human-readable alphanumeric index labels ("A1", "A2", "B1", etc.), cell centroids (centroid_lon, centroid_lat), and area in square meters (area_m2). Designed for planning field enumeration areas, printing map book index sheets with vantor_field_atlas(), and stratified spatial sampling.

Usage

vantor_survey_grid(
  aoi,
  cell_size = 500,
  shape = c("square", "hexagonal"),
  clip_to_aoi = TRUE,
  crs = 4326,
  verbose = getOption("vantorr.verbose", TRUE)
)

Arguments

Value

An sf polygon object with columns:

• cell_id: Alphanumeric grid label ("A1", "A2", ..., "B1", ...)

• row_idx: Row index (top-to-bottom, 1-based)

• col_idx: Column index (left-to-right, 1-based)

• centroid_lon, centroid_lat: Cell centroid coordinates in EPSG:4326

• area_m2: Approximate planar area in square meters

• geometry: Polygon geometry in crs

Examples

aoi <- sf::st_bbox(
  c(xmin = -105.01, ymin = 39.73, xmax = -104.99, ymax = 39.75),
  crs = sf::st_crs(4326)
)
grid_sf <- vantor_survey_grid(aoi, cell_size = 500, verbose = FALSE)
head(grid_sf)

Audit Basemap Imagery Vintage and Sensor Quality Across Survey Areas

Description

Evaluates the acquisition dates (acq_time), ground sample distance (gsd), off-nadir angle (ona), and contributing satellite sensors across an Area of Interest or a set of Enumeration Area / survey grid polygons. Can either query the Vantor OGC WFS Seamlines endpoint via vantor_get_seamlines() or use a pre-fetched seamlines sf object for offline workflows.

Usage

vantor_vintage_report(
  aoi,
  seamlines = NULL,
  product = "VIVID_STANDARD_30",
  max_age_days = 730,
  reference_date = Sys.Date(),
  token = NULL,
  api_key = NULL,
  verbose = getOption("vantorr.verbose", TRUE)
)

Arguments

Value

An sf object representing aoi enriched with vintage audit columns:

• n_strips: Number of intersecting satellite mosaic strips

• earliest_acq_date, latest_acq_date: Earliest and latest strip acquisition dates (YYYY-MM-DD)

• max_age_days: Age in days of the oldest intersecting imagery strip relative to reference_date

• min_gsd_m, max_gsd_m: Minimum and maximum ground sample distance (meters)

• max_ona_deg: Maximum off-nadir angle (degrees)

• sensors: Comma-separated list of contributing satellite sensors

• vintage_warning: Logical TRUE if max_age_days > max_age_days threshold

Examples

# Offline example using synthetic seamlines and a survey grid
aoi <- sf::st_bbox(
  c(xmin = -105.01, ymin = 39.73, xmax = -105.00, ymax = 39.74),
  crs = sf::st_crs(4326)
)
grid_sf <- vantor_survey_grid(aoi, cell_size = 600, verbose = FALSE)

mock_seamline <- sf::st_sf(
  acq_time = "2024-05-10T18:00:00Z",
  gsd = 0.30,
  ona = 11.5,
  sensor = "WV03",
  catid = "1040010012345600",
  geometry = sf::st_as_sfc(aoi)
)

audit_sf <- vantor_vintage_report(
  aoi = grid_sf,
  seamlines = mock_seamline,
  verbose = FALSE
)

Construct a Vantor OGC WMTS Tile URL Template

Description

Generates an OGC Web Map Tile Service (WMTS) URL template ({z}/{x}/{y}) for streaming Vantor / Maxar Vivid Mosaic basemap tiles in EPSG:3857 (Web Mercator) within leaflet, mapgl, or tmap.

Usage

vantor_wmts_url(
  product = "VIVID_STANDARD_30",
  api_key = NULL,
  format = "image/jpeg",
  cql_filter = NULL,
  verbose = FALSE
)

Arguments

Value

A character string containing the WMTS GetTile URL template with {z}, {x}, and {y} placeholders.

Examples

url_template <- vantor_wmts_url(
  product = "VIVID_STANDARD_30",
  api_key = "example_api_key"
)

Write an Esri Tile Package (.tpk or .tpkx) for Offline Field Basemaps

Description

Generates a multi-zoom Web Mercator (EPSG:3857) Esri Tile Package (.tpk Compact Cache V1 or .tpkx Compact Cache V2) in pure R without requiring proprietary ArcGIS software or ArcGIS Online credits. Designed for zoomable offline satellite basemaps in World Bank Survey Solutions (including v24.09+ built on the ArcGIS Maps SDK for .NET v200.x), ArcGIS Field Maps, and ArcGIS Survey123.

Tiles can either be sliced offline from a local terra::SpatRaster / GeoTIFF (raster), or fetched directly across zoom levels from the Vantor WMS/WMTS imagery service (raster = NULL).

Usage

vantor_write_tpk(
  x = NULL,
  output_file = tempfile(fileext = ".tpk"),
  zoom = 15:17,
  format = c("auto", "tpk", "tpkx"),
  raster = NULL,
  product = "VIVID_STANDARD_30",
  max_tiles = 2500L,
  title = "Vantor Satellite Basemap",
  zip_for_suso = FALSE,
  aoi = NULL,
  verbose = getOption("vantorr.verbose", TRUE)
)

Arguments

Value

Invisibly returns the normalized output_file path, with attributes n_tiles, zoom, format, and suso_zip_path (when zip_for_suso = TRUE).

Examples

if (requireNamespace("terra", quietly = TRUE)) {
  # Create a synthetic RGB SpatRaster in EPSG:3857
  r <- terra::rast(
    xmin = -11689500, xmax = -11688500,
    ymin = 4826500, ymax = 4827500,
    nrows = 128, ncols = 128, nlyrs = 3,
    crs = "EPSG:3857"
  )
  terra::values(r) <- sample(50:220, terra::ncell(r) * 3, replace = TRUE)

  # Export both .tpk (Compact Cache V1) and .tpkx (Compact Cache V2)
  tpk_file <- vantor_write_tpk(
    raster = r,
    output_file = tempfile(fileext = ".tpk"),
    zoom = 14:15,
    verbose = FALSE
  )
  tpkx_file <- vantor_write_tpk(
    raster = r,
    output_file = tempfile(fileext = ".tpkx"),
    zoom = 14:15,
    verbose = FALSE
  )
  unlink(c(tpk_file, tpkx_file))
}