# `rgeedim` Demo

This vignette shows how to extract a Google Earth Engine asset by name for an arbitrary extent and visualize it in R.

First, we load {rgeedim} and call `gd_initialize()`. This is a wrapper function around `geedim.Initialize()` that must be run before using the Python Google Earth Engine API.

    library(rgeedim)
    gd_initialize()

Perhaps the simplest way to specify the target extent is using the xmin/xmax/ymin/ymax arguments to `gd_bbox()`. This function returns a Python object equivalent to GeoJSON, which is interchangeably represented as a simple `list` object in R using {reticulate}.

## Determine Target Region

    r <- gd_bbox(
      xmin = -121,
      xmax = -120.5,
      ymin = 38.5,
      ymax = 39
    )

As is standard for GeoJSON, coordinates of the bounding box are expressed in WGS84 decimal degrees (`"OGC:CRS84"`). Note that longitude, latitude (X, Y) coordinate pair order is implied.

## Access by ID

We can find IDs of assets of interest using the Google Earth Engine data catalog: https://developers.google.com/earth-engine/datasets/catalog

To obtain an R object reference to the asset we pass the `"id"` to `gd_image_from_id()`. For example here we use Global SRTM Topographic Diversity:

    x <- gd_image_from_id('CSP/ERGo/1_0/Global/SRTM_topoDiversity')

`gd_image_from_id()` will return `geedim.mask.MaskedImage` and `gd_collection_from_name()` will return `geedim.collection.MaskedCollection` objects.

Now, we pass the image result to `gd_download()`. We can specify output `filename` and target area as `region` arguments. See `gd_bbox()` for examples of making a region argument from bounding coordinates or a {terra} `SpatExtent` object.

Other options that can be passed to the `BaseImage.download()` method include `scale` which allows warping of the result to a target resolution. Try modifying this example to use `scale=90` (~native SRTM resolution):

    img <- gd_download(x, filename = 'image.tif',
                       region = r, scale = 900,
                       overwrite = TRUE, silent = FALSE
                      )

`gd_download()` (invisibly) returns the `filename` on successful download, which helps to “pipe” into functions that might read the result.

So we can use the {terra} `rast()` function to read the GeoTIFF `gd_download()` result.

    library(terra)
    f <- rast(img)

    par(mar=c(1,1,1,1))
    plot(f[[1]])

    # inspect object
    f