Main interface for downloading and exporting Tessera embeddings.
This R6 class provides methods for downloading tiles, exporting GeoTIFFs,
and sampling embeddings at specific points.
Use GeoTessera$new() to create a new instance, or the convenience
function geotessera.
Convenience function to create a new GeoTessera object.
Methods
Method new()
Create a new GeoTessera object
Usage
GeoTessera$new(
dataset_version = "v1",
cache_dir = NULL,
embeddings_dir = NULL,
registry_url = NULL,
registry_path = NULL,
registry_dir = NULL,
verify_hashes = TRUE
)Method sample_embeddings_at_points()
Sample embeddings at specific points
Method export_embedding_geotiff()
Export a single tile as GeoTIFF
Usage
GeoTessera$export_embedding_geotiff(
lon,
lat,
year,
output_path,
bands = NULL,
compress = "lzw"
)Method export_embedding_geotiffs()
Export multiple tiles as GeoTIFFs
Usage
GeoTessera$export_embedding_geotiffs(
tiles,
output_dir,
bands = NULL,
compress = "lzw",
progress = TRUE
)Method fetch_mosaic_for_region()
Fetch a mosaic of embeddings for a region
Method apply_pca_to_embeddings()
Apply PCA to embeddings
Method export_pca_geotiffs()
Export tiles with PCA reduction
Method merge_geotiffs_to_mosaic()
Merge GeoTIFFs into a single mosaic
Method summarize_region()
Summarize embeddings for a geographic region
Downloads embeddings for a region to a temporary location, applies summary functions, and cleans up automatically. Useful for processing large regions where only summary statistics are needed.
Usage
GeoTessera$summarize_region(
region,
year,
summary_fns = NULL,
mask_to_region = TRUE,
progress = TRUE,
keep_tiles = FALSE
)Arguments
regionBounding box (numeric vector, list, or sf bbox) or sf/sfc object (e.g., from a shapefile). For sf objects, the bounding box is used for tile selection, and pixels are masked to the geometry.
yearInteger year
summary_fnsNamed list of summary functions. Each function should accept parameters: embeddings (list of 3D arrays), region (the input region), tiles_df (tile metadata). Some functions also accept gt and year for sampling operations. Default includes mean, centroid, and pixel_count summaries.
mask_to_regionLogical; if TRUE and region is an sf object, pixels outside the geometry are set to NA before summarization. Default TRUE.
progressShow progress bars. Default TRUE.
keep_tilesLogical; if TRUE, returns the downloaded Tile objects along with summaries (tiles are NOT cleaned up). Default FALSE.
Returns
Named list containing:
summaries: Named list of summary results (one per summary_fn)
metadata: List with region info, year, n_tiles, processing time
tiles: (only if keep_tiles=TRUE) List of Tile objects
Examples
\dontrun{
gt <- geotessera()
# Basic usage with bounding box
result <- gt$summarize_region(
region = c(0.08, 52.18, 0.15, 52.21),
year = 2024
)
print(result$summaries$mean)
# With sf object from shapefile
library(sf)
shape <- st_read("my_region.shp")
result <- gt$summarize_region(region = shape, year = 2024)
# Custom summary functions
my_summary <- function(embeddings, region, tiles_df) {
# Custom computation
colMeans(do.call(rbind, lapply(embeddings, function(e) {
apply(e, 3, mean, na.rm = TRUE)
})))
}
result <- gt$summarize_region(
region = bbox,
year = 2024,
summary_fns = list(
mean = summary_mean,
custom = my_summary,
quantiles = summary_quantile(c(0.1, 0.9))
)
)
}
Method summarize_region_streaming()
Summarize a large region using streaming (memory efficient)
Processes tiles one at a time using Welford's online algorithm for computing the mean, avoiding memory issues with large regions.
Usage
GeoTessera$summarize_region_streaming(
region,
year,
sample_rate = 1,
mask_to_region = TRUE,
seed = NULL,
progress = TRUE
)Arguments
regionBounding box or sf object
yearInteger year
sample_rateFraction of pixels to sample (0-1). Use lower values for very large regions. Default 1.0.
mask_to_regionIf TRUE and region is sf, only include pixels inside the polygon. Default TRUE.
seedRandom seed for reproducible sampling
progressShow progress. Default TRUE.
Examples
## ------------------------------------------------
## Method `GeoTessera$summarize_region`
## ------------------------------------------------
if (FALSE) { # \dontrun{
gt <- geotessera()
# Basic usage with bounding box
result <- gt$summarize_region(
region = c(0.08, 52.18, 0.15, 52.21),
year = 2024
)
print(result$summaries$mean)
# With sf object from shapefile
library(sf)
shape <- st_read("my_region.shp")
result <- gt$summarize_region(region = shape, year = 2024)
# Custom summary functions
my_summary <- function(embeddings, region, tiles_df) {
# Custom computation
colMeans(do.call(rbind, lapply(embeddings, function(e) {
apply(e, 3, mean, na.rm = TRUE)
})))
}
result <- gt$summarize_region(
region = bbox,
year = 2024,
summary_fns = list(
mean = summary_mean,
custom = my_summary,
quantiles = summary_quantile(c(0.1, 0.9))
)
)
} # }
## ------------------------------------------------
## Method `GeoTessera$summarize_region_streaming`
## ------------------------------------------------
if (FALSE) { # \dontrun{
gt <- geotessera()
# For large regions, use streaming approach
result <- gt$summarize_region_streaming(
region = large_polygon,
year = 2024,
sample_rate = 0.1
)
} # }
if (FALSE) { # \dontrun{
gt <- geotessera()
tiles <- gt$get_tiles(bbox = c(-0.2, 51.4, 0.1, 51.6), year = 2024)
} # }