Package 'ALSdownloadeR'

Description

Create the Shiny application object

Usage

als_app(
  mode = "local",
  tile_index_dir = NULL,
  provider_limit = 2L,
  submission_dir = NULL,
  reviewer = NULL
)

Arguments

Value

A shiny.appobj suitable for shiny::runApp() or a deployment entry point.

Examples

if (interactive()) shiny::runApp(als_app())

Description

Generate an HTML or PDF summary of a search/download selection

Usage

als_report(
  tiles,
  output_dir,
  format = c("html", "pdf"),
  aoi_area_km2 = NA_real_,
  aoi = NULL,
  figures = character(),
  details = FALSE,
  map_image = character(),
  map_credits = "",
  figure_captions = NULL
)

Arguments

Details

Content is limited to data already carried by tiles: filename, dataset, provider, provider-reported acquisition dates, known size and the recorded citation/licence per tile. Transfer-time scenarios use known bytes and illustrative aggregate speeds, not CPU core counts. Unknown file sizes are explicitly excluded. Nothing is fetched. The report is written only to output_dir and is never transmitted anywhere.

Value

Invisibly, the path to the rendered report file.

Examples

# Render a local planning report from synthetic metadata; no downloads.
# Rendering can take more than 5 seconds and requires Pandoc.

if (requireNamespace("rmarkdown", quietly = TRUE) && rmarkdown::pandoc_available()) {
  index <- system.file("extdata", "example-index", "demo.tiles.geojson",
                       package = "ALSdownloadeR")
  tiles <- read_tile_index(index)
  output_dir <- tempfile("als-report-")
  report <- als_report(tiles, output_dir, format = "html")
  basename(report)
  file.exists(report)
  unlink(output_dir, recursive = TRUE)
}

Description

Calculate AOI size

Usage

aoi_area(aoi)

Arguments

Value

Geodesic union area in square kilometres, without double-counting overlapping polygons.

Examples

ring <- matrix(c(0,0, 1,0, 1,1, 0,1, 0,0), ncol = 2, byrow = TRUE)
aoi_area(sf::st_sfc(sf::st_polygon(list(ring)), crs = 4326))

Description

Configure email-link access to local proposal review

Usage

configure_reviewer_access(path, emails)

Arguments

Details

Access requires a single-use private review link delivered to an allowed mailbox by the administrator-configured mail service. Preview mail cannot authenticate. Reconfiguration revokes sessions and outstanding invitations. Restrict the file's parent directory to the host owner (use Windows ACLs where applicable). The reviewer remains localhost-only; remote HTTPS hosting is separate.

Value

Invisibly, the allowlist-file path. No password is requested or stored. Set option ALSdownloadeR.reviewer_credentials or environment variable ALS_REVIEWER_CREDENTIALS to this path at launch.

Examples

# Create a temporary allowlist only; this does not send invitations or email.
if (requireNamespace("openssl", quietly = TRUE)) {
  path <- tempfile(fileext = ".rds")
  configure_reviewer_access(path, "[email protected]")
  file.exists(path)
  unlink(path)
}

Description

List persistent country source links

Usage

country_links(path = country_links_path(), history = FALSE)

Arguments

Details

Reading does not create a file or contact a website. Country names follow the bundled world map. These links do not imply national ALS coverage or enable an in-app download adapter. Restart the app after updating links.

Value

A data frame of country, country_code, source_id, name, url, updated_on and notes. The initial records are the packaged external portals.

Examples

country_links()

Description

Create an ALS download planning report

Usage

create_als_report(...)

Arguments

Value

The generated report path, invisibly.

Examples

# Render a local planning report from synthetic metadata; no downloads.
# Rendering can take more than 5 seconds and requires Pandoc.

if (requireNamespace("rmarkdown", quietly = TRUE) && rmarkdown::pandoc_available()) {
  index <- system.file("extdata", "example-index", "demo.tiles.geojson",
                       package = "ALSdownloadeR")
  tiles <- read_tile_index(index)
  output_dir <- tempfile("als-report-")
  report <- create_als_report(tiles, output_dir, format = "html")
  basename(report)
  file.exists(report)
  unlink(output_dir, recursive = TRUE)
}

Description

Download selected airborne laser scanning files

Usage

download_als_data(...)

Arguments

Value

A transfer status table, as returned by download_tiles().

Examples

# Requires an interactive session, Internet and your own polygon file.
# Provider availability and original tile sizes vary; allow more than 5 seconds.

if (interactive()) {
  aoi <- read_aoi(file.choose())
  tiles <- find_tiles(aoi, provider = "usgs3dep")
  if (nrow(tiles) > 0L) {
    output_dir <- tempfile("als-download-")
    result <- download_als_data(tiles[1, ], output_dir = output_dir, workers = 1)
    result[, c("status", "path")]
    # The downloaded file and its manifest remain in output_dir for inspection.
  }
}

Description

Download selected tiles with resumable transfer records

Usage

download_tiles(
  tiles,
  output_dir,
  workers = 1L,
  mode = c("local", "hosted"),
  provider_limit = 2L,
  retries = 2L,
  timeout = 600,
  progress_dir = NULL
)

Arguments

Details

Uses future.apply::future_lapply() and restores the caller's future plan. Resume requires both a completed sidecar record and a matching file checksum. HTTP status, reported length and LAS signature are checked; complete point-stream decompression is not verified. Existing untracked destination files are never overwritten. Credentials are not written to the exported manifest. Large datasets should be downloaded locally.

Value

A data frame with one row per asset, transfer status, canonical source URL, byte count, checksum and local path. Failed tiles remain in the result.

Examples

# Requires an interactive session, Internet and your own polygon file.
# Provider availability and original tile sizes vary; allow more than 5 seconds.

if (interactive()) {
  aoi <- read_aoi(file.choose())
  tiles <- find_tiles(aoi, provider = "usgs3dep")
  if (nrow(tiles) > 0L) {
    output_dir <- tempfile("als-download-")
    result <- download_tiles(tiles[1, ], output_dir = output_dir, workers = 1)
    result[, c("status", "path")]
    # The downloaded file and its manifest remain in output_dir for inspection.
  }
}

Description

Plan download concurrency

Usage

download_worker_policy(
  mode,
  available_cores = NA_integer_,
  requested = NULL,
  provider_limit = Inf,
  jobs = Inf
)

Arguments

Details

Hosted mode uses one worker. Local mode leaves four available cores unused when possible and initially recommends at most ten workers. During automated package checks callers must explicitly request no more than two.

Value

A list containing recommended, maximum, requested and effective counts.

Examples

download_worker_policy("local", available_cores = 8)
download_worker_policy("hosted", available_cores = 16, requested = 4)

Description

Extract acquisition years and retain their evidence

Usage

extract_als_dates(tiles, lookup = TRUE, lookup_budget = 60)

Arguments

Value

The table with acquisition_year, source, precision, scope and status. Missing values remain NA. Filename years are labelled unverified references.

Examples

# Synthetic catalogue values, read locally without contacting their URLs.
index <- system.file("extdata", "example-index", "demo.tiles.geojson",
                     package = "ALSdownloadeR")
tiles <- read_tile_index(index)
dated <- extract_als_dates(tiles, lookup = FALSE)
dated[, c("acquisition_year", "date_source", "date_status")]

Description

Find airborne laser scanning data

Usage

find_als_data(
  aoi,
  provider = c("usgs3dep", "planetary", "opentopography", "contributed", "ahn6",
    "swisstopo", "ignfr", "canelevation"),
  start = NULL,
  end = NULL,
  tile_index_dir = NULL,
  max_items = 10000L
)

Arguments

Value

An sf asset table including acquisition evidence and file sizes when retrievable. The download summary is available with summarize_als_download().

Examples

# Read a small synthetic catalogue supplied with the package; no Internet.
index_dir <- system.file("extdata", "example-index", package = "ALSdownloadeR")
index <- read_tile_index(file.path(index_dir, "demo.tiles.geojson"))
aoi <- read_aoi(sf::st_geometry(index))
# Search the local demonstration index and inspect the matching record.
tiles <- find_als_data(aoi, provider = "contributed", tile_index_dir = index_dir)
tiles[, c("tile_id", "acquired_start", "acquired_end", "size_bytes")]
# The example.org URLs are placeholders: do not download these demo records.

Description

Find point-cloud tiles intersecting an AOI

Usage

find_tiles(
  aoi,
  provider = c("usgs3dep", "planetary", "opentopography", "contributed", "ahn6",
    "swisstopo", "ignfr", "canelevation"),
  start = NULL,
  end = NULL,
  tile_index_dir = NULL,
  max_items = 10000L
)

Arguments

Details

Network access occurs only when this function is explicitly called for a remote source. OpenTopography searches the packaged, audited airborne-LiDAR registry by default and fetches matching provider indexes with SHA-256 verification. An explicit local index directory overrides that route in the R API. Public tile downloads do not require an API key. Asset licenses vary per dataset.

Value

An sf table of assets with stable identifiers, canonical URLs, acquisition dates, citation information and tile geometry in EPSG:4326. campaign_id contains the reported 3DEP project or IGN mission identifier. campaign_group and campaign_basis also describe fallback groups from recognized project directories, delivery blocks or datasets. Fallback groups do not establish distinct flight dates.

Examples

# Read a small synthetic catalogue supplied with the package; no Internet.
index_dir <- system.file("extdata", "example-index", package = "ALSdownloadeR")
index <- read_tile_index(file.path(index_dir, "demo.tiles.geojson"))
aoi <- read_aoi(sf::st_geometry(index))
# Search the local demonstration index and inspect the matching record.
tiles <- find_tiles(aoi, provider = "contributed", tile_index_dir = index_dir)
tiles[, c("tile_id", "acquired_start", "acquired_end", "size_bytes")]
# The example.org URLs are placeholders: do not download these demo records.

Description

Retrieve sizes of ALS files without downloading point clouds

Usage

get_als_file_sizes(tiles, timeout = 15, budget = 60, connections = 4L)

Arguments

Value

The asset table with size_bytes and size provenance/status. NA sizes are not zero. Requests use HEAD and, when necessary, a bounded byte range.

Examples

# Synthetic catalogue values, read locally without contacting their URLs.
index <- system.file("extdata", "example-index", "demo.tiles.geojson",
                     package = "ALSdownloadeR")
tiles <- read_tile_index(index)
# Sizes are already recorded, so no HTTP lookup is needed.
sized <- get_als_file_sizes(tiles)
sized[, c("size_bytes", "size_source", "size_status")]

Description

Rebuild an inbox contribution in the private review queue

Usage

import_zenodo_inbox(fields, queue)

Arguments

Details

This maintainer operation supports the link-only Formspree fields generated by ALSdownloadeR. It retrieves Zenodo metadata and, for polygon coverage, one bounded boundary file. It never downloads point clouds. Access to the inbox is configured separately; no inbox API key is bundled.

Value

Pending proposal ID. Repeated imports are deduplicated. No approval or publication is performed.

Examples

# Maintainer-only: requires an actual inbox export, Internet and a private queue.
# The JSON file must contain the named fields received by the submission inbox.
## Not run: 
fields <- jsonlite::read_json(file.choose(), simplifyVector = TRUE)
queue <- readline("Private review queue directory: ")
id <- import_zenodo_inbox(fields, queue)
zenodo_submissions(queue)

## End(Not run)

Description

Inspect a public Zenodo record without downloading point clouds

Usage

inspect_zenodo(link)

Arguments

Details

Only retrieves a bounded JSON metadata response from zenodo.org. Publication dates are never treated as acquisition dates. No catalogue changes.

Value

Metadata including authors, licence, description, file sizes and links.

Examples

# Requires Internet and a published, openly accessible Zenodo record.

if (interactive()) {
  link <- readline("Published Zenodo record URL or DOI: ")
  metadata <- inspect_zenodo(link)
  metadata[c("title", "doi", "license_url")]
}

Description

Launch the ALSdownloadeR Shiny application

Usage

launch_app(
  mode = c("local", "hosted"),
  tile_index_dir = NULL,
  provider_limit = 2L,
  host = "127.0.0.1",
  port = NULL,
  launch.browser = interactive(),
  submission_dir = NULL,
  reviewer = NULL
)

Arguments

Details

Launch is explicit: loading the package does not start a browser, contact providers, change the working directory or install packages. Background transfer processes are terminated when the owning session ends. Optional browser submissions use option ALSdownloadeR.formspree, a list with endpoint (a public https://formspree.io/f/ form URL) and attachments (FALSE by default; TRUE requires a file-upload plan). Alternatively set environment variable ALS_FORMSPREE_ENDPOINT for links-only submissions. The community form is the default when no local submission directory is set. Set option ALSdownloadeR.formspree = FALSE to disable remote submission. An explicitly configured transport takes precedence over the local queue button. It requires explicit submission and Internet access, but no contributor account. Service quotas apply; receiving a proposal never approves its publication.

Value

Invisibly, the return value of shiny::runApp(). Runs until stopped.

Examples

if (interactive()) launch_app()

Description

Prepare a Zenodo contribution for maintainer review

Usage

prepare_zenodo_submission(
  link,
  boundary,
  acquired = "",
  platform = "ALS",
  email = ""
)

Arguments

Value

A pending proposal; no files are published and no point clouds read.

Examples

# Requires Internet and coverage polygons matching the files in your record.
# This prepares a proposal but does not submit it or approve its publication.

if (interactive()) {
  link <- readline("Published Zenodo record URL or DOI: ")
  boundary <- read_aoi(file.choose())
  proposal <- prepare_zenodo_submission(link, boundary, acquired = "", platform = "ALS")
  proposal$id
}

Description

Make a bounded point-cloud preview

Usage

preview_points(points, max_points = 100000L)

Arguments

Details

Sampling is deterministic and affects only the returned preview. The source cloud is not modified. Elevation is not normalized canopy height.

Value

A data frame of sampled coordinates with an origin attribute. Coordinates are translated to a local origin for display precision. An optional numeric Classification column is retained as an aligned classification attribute; missing or invalid codes become NA. Optional numeric Intensity is retained as an aligned intensity attribute. No classification or intensity is inferred.

Examples

preview_points(data.frame(X = 1:10, Y = 1:10, Z = 11:20), 5)

Description

Download one remote tile temporarily and read a bounded preview

Usage

preview_remote_tile(
  tile,
  max_bytes = 1024 * 1024^2,
  path = tempfile(fileext = ".laz"),
  reader = function(path) read_preview(path, 100000L),
  progress = NULL,
  zip_member = NULL,
  max_uncompressed_bytes = 2 * 1024^3
)

Arguments

Details

A temporary, single-file preview; never persists a cloud in the source catalog. Exported (rather than internal-only) so a background callr::r_bg() worker can call it by namespace-qualified name – a plain closure passed as a callr argument can lose access to sibling package-internal helpers it calls, such as require_data_terms().

Value

Whatever reader returns.

Examples

# Requires an interactive session, Internet and your own polygon file.
# Provider availability and original tile sizes vary; allow more than 5 seconds.

if (interactive() && requireNamespace("lidR", quietly = TRUE)) {
  aoi <- read_aoi(file.choose())
  tiles <- find_tiles(aoi, provider = "usgs3dep")
  if (nrow(tiles) > 0L) {
    # Downloads one original tile temporarily (up to 10 MiB here).
    points <- preview_remote_tile(tiles[1, ], max_bytes = 10 * 1024^2)
    head(points)
  }
}

Description

Inspect provider access and implementation status

Usage

provider_catalog()

Value

A data frame with provider identifiers, access notes, source links, and whether a tile-search adapter is implemented. Implemented does not mean that every dataset or endpoint is currently available.

Examples

provider_catalog()

Description

Read and validate a polygon AOI

Usage

read_aoi(x, layer = NULL)

Arguments

Details

Zipped Shapefiles must contain one Shapefile with a declared CRS. Archives with unsafe paths or more than 200 MB uncompressed are rejected. No coordinate reference system is guessed.

Value

An sf polygon object in EPSG:4326. Empty geometries are removed.

Examples

ring <- matrix(c(0,0, 1,0, 1,1, 0,1, 0,0), ncol = 2, byrow = TRUE)
aoi <- read_aoi(sf::st_sfc(sf::st_polygon(list(ring)), crs = 4326))

Description

Read a decimated, spatially windowed preview for the forest close-up viewer

Usage

read_forest_preview(
  path,
  percent = 2,
  window = 100,
  center_x = 50,
  center_y = 50,
  voxel = 0,
  xy_units = "auto",
  z_units = "auto"
)

Arguments

Details

Requires the optional package 'lidR'. Exported so a background callr::r_bg() worker can call it by namespace-qualified name; see preview_remote_tile() for why.

Value

The same translated coordinate table as preview_points(), with a display_note attribute describing the sampling actually used.

Examples

# Use a small LAS/LAZ example distributed with the optional lidR package.
if (requireNamespace("lidR", quietly = TRUE)) {
  path <- system.file("extdata", "MixedConifer.laz", package = "lidR")
  points <- read_forest_preview(path, percent = 1)
  head(points)
  attr(points, "origin")
  attr(points, "units")
}

Description

Read a small preview from a local LAS or LAZ file

Usage

read_preview(path, max_points = 100000L, xy_units = "auto", z_units = "auto")

Arguments

Details

Requires the optional package 'lidR'. Reader-side decimation limits retained points before they enter R. The file may still need to be scanned in full; this function is not a remote COPC range reader.

Value

The same translated coordinate table as preview_points().

Examples

# Use a small LAS/LAZ example distributed with the optional lidR package.
if (requireNamespace("lidR", quietly = TRUE)) {
  path <- system.file("extdata", "MixedConifer.laz", package = "lidR")
  points <- read_preview(path, max_points = 1000)
  head(points)
  attr(points, "origin")
  attr(points, "units")
}

Description

Read a contributed aerial LiDAR tile index

Usage

read_tile_index(path)

Arguments

Details

Reads metadata only. Does not contact asset URLs or approve a source. Required properties are tile_id, dataset, url, acquired_start, acquired_end, platform, license_url and citation. Dates may be null when unknown. Platform must be ALS or UAV-LiDAR. Coordinates must be EPSG:4326. Assets must be direct HTTPS LAS/LAZ files or Zenodo record ZIP files. ZIP files are downloaded intact and require local extraction for preview.

Value

An sf tile table accepted by download_tiles().

Examples

read_tile_index(system.file("extdata", "contribution-template.geojson",
                           package = "ALSdownloadeR"))

Description

Accept or reject a queued Zenodo contribution

Usage

review_zenodo_submission(
  queue,
  id,
  decision = c("approve", "reject"),
  reviewer,
  confirmed = FALSE,
  reason = ""
)

Arguments

Details

Approval re-fetches Zenodo metadata and rejects changed records. Only approved indexes under queue/approved participate in catalogue search. Never downloads point clouds. Expose this operation only to trusted maintainers.

Value

Path to an approved index, or invisibly NULL on rejection.

Examples

# Maintainer-only example: records a real rejection in an existing private queue.
# Requires a pending proposal and an explicit review decision; not run automatically.
## Not run: 
queue <- readline("Private review queue directory: ")
zenodo_submissions(queue)
id <- readline("ID of the proposal you have reviewed: ")
reviewer <- readline("Your maintainer name: ")
review_zenodo_submission(queue, id, decision = "reject", reviewer = reviewer,
                         reason = "Coverage or metadata needs correction.")

## End(Not run)

Description

Submit a proposal to a private local review queue

Usage

submit_zenodo(proposal, queue)

Arguments

Details

Does not activate coverage or download data. Optional administrator configuration in option ALSdownloadeR.submission_mail enables notifications; see the notification setup guide in the repository documentation.

Value

Proposal ID. Identical metadata/coverage proposals are deduplicated.

Examples

# Requires a real record, matching coverage and an administrator-owned queue.
# Run only when intending to submit; configured notifications may send email.
## Not run: 
link <- readline("Published Zenodo record URL or DOI: ")
boundary <- read_aoi(file.choose())
proposal <- prepare_zenodo_submission(link, boundary, acquired = "", platform = "ALS")
queue <- readline("Private review queue directory: ")
id <- submit_zenodo(proposal, queue)
zenodo_submissions(queue)

## End(Not run)

Description

Summarize an ALS data selection

Usage

summarize_als_data(tiles)

Arguments

Value

Counts and total download size; incomplete totals remain NA.

Examples

# Synthetic catalogue values, read locally without contacting their URLs.
index <- system.file("extdata", "example-index", "demo.tiles.geojson",
                     package = "ALSdownloadeR")
tiles <- read_tile_index(index)
summarize_als_data(tiles)
# Unknown sizes remain unknown rather than being counted as zero.
tiles$size_bytes <- NA_real_
summarize_als_data(tiles)

Description

Summarize the total download size of a selection

Usage

summarize_als_download(tiles)

Arguments

Value

A one-row data frame with file count, known bytes, missing sizes and complete total bytes (NA when any size is missing). GB uses 10^9 bytes.

Examples

# Synthetic catalogue values, read locally without contacting their URLs.
index <- system.file("extdata", "example-index", "demo.tiles.geojson",
                     package = "ALSdownloadeR")
tiles <- read_tile_index(index)
summarize_als_download(tiles)
# Unknown sizes remain unknown rather than being counted as zero.
tiles$size_bytes <- NA_real_
summarize_als_download(tiles)

Description

Add or update an external ALS source link for a country

Usage

update_country_link(
  country,
  url,
  updated_on,
  source_id = "country_portal",
  name = "ALS source portal",
  notes = "External access; consult source coverage and terms.",
  path = country_links_path()
)

Arguments

Details

Updates only the matching country/source pair; other entries remain. Prior revisions are retained in the registry and the previous file is saved with a .bak suffix. A lock rejects simultaneous writers. Registered links appear in the yellow External Access map layer and source catalogue after restarting the app, including countries with separate red survey footprints. No package installation files are modified. Share the registry path with the app process to use the same links in a hosted installation.

Value

The updated current country-link table, invisibly.

Examples

registry <- tempfile(fileext=".rds")
update_country_link("Italy", "https://example.org/lidar", "2026-09-22",
  name="Example portal (not a verified source)", path=registry)
country_links(path=registry)
unlink(c(registry, paste0(registry, ".bak")))

Description

List pending and reviewed Zenodo contributions

Usage

zenodo_submissions(queue)

Arguments

Value

A table of request IDs, DOI, title and status. Private contacts are omitted.

Examples

# A new private queue has no submissions; no network or files are created.
queue <- tempfile("als-review-")
zenodo_submissions(queue)