{"id":15893675,"url":"https://github.com/brownag/rgeedim","last_synced_at":"2025-07-23T21:03:24.218Z","repository":{"id":45204208,"uuid":"513402501","full_name":"brownag/rgeedim","owner":"brownag","description":" Search, composite, and download 'Google Earth Engine' imagery with the 'Python' module 'geedim'","archived":false,"fork":false,"pushed_at":"2025-03-17T14:39:24.000Z","size":5452,"stargazers_count":50,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-17T17:03:43.904Z","etag":null,"topics":["geedim","geotiff","gis","google-earth-engine","python","r","raster","remote-sensing","satellite-imagery","spatial","terra"],"latest_commit_sha":null,"homepage":"https://humus.rocks/rgeedim","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brownag.png","metadata":{"files":{"readme":"README.Rmd","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-07-13T06:13:56.000Z","updated_at":"2025-03-16T23:34:36.000Z","dependencies_parsed_at":"2024-01-07T21:07:52.875Z","dependency_job_id":"6523b2e4-c753-4c88-9cf9-732026ee201f","html_url":"https://github.com/brownag/rgeedim","commit_stats":{"total_commits":143,"total_committers":1,"mean_commits":143.0,"dds":0.0,"last_synced_commit":"a8b2cd552d6817a8f9556cdf0de6e3fd1f599ae4"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brownag%2Frgeedim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brownag%2Frgeedim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brownag%2Frgeedim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brownag%2Frgeedim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brownag","download_url":"https://codeload.github.com/brownag/rgeedim/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244629989,"owners_count":20484293,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["geedim","geotiff","gis","google-earth-engine","python","r","raster","remote-sensing","satellite-imagery","spatial","terra"],"created_at":"2024-10-06T08:12:38.881Z","updated_at":"2025-07-23T21:03:24.205Z","avatar_url":"https://github.com/brownag.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\noutput: markdown\nknit: litedown:::knit\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r, include = FALSE}\nlitedown::reactor(\n  eval = !inherits(rgeedim::gd_version(), 'try-error'),\n  collapse = TRUE,\n  dev = 'jpeg',\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\"\n)\n```\n\n# {rgeedim}\n\n\u003c!-- badges: start --\u003e\n[![R-CMD-check](https://github.com/brownag/rgeedim/workflows/R-CMD-check/badge.svg)](https://github.com/brownag/rgeedim/actions)\n[![HTML Docs](https://img.shields.io/badge/docs-HTML-informational)](https://humus.rocks/rgeedim/)\n[![codecov](https://codecov.io/gh/brownag/rgeedim/branch/main/graph/badge.svg?token=BYBKW7PKC3)](https://app.codecov.io/gh/brownag/rgeedim)\n[![CRAN status](https://www.r-pkg.org/badges/version-last-release/rgeedim)](https://CRAN.R-project.org/package=rgeedim)\n\u003c!-- badges: end --\u003e\n\n{rgeedim} supports search and download of Google Earth Engine imagery with Python module [`geedim`](https://github.com/leftfield-geospatial/geedim)  by Dugal Harris. This package provides wrapper functions that make it more convenient to use `geedim` from R. \n\nThe [rgeedim manual](https://humus.rocks/rgeedim/) describes the R API. See the [geedim manual]( https://geedim.readthedocs.io/) for more information on Python API and command line interface.\n\nUsing `geedim`, images larger than the [`Image.getDownloadURL()` size limit](https://developers.google.com/earth-engine/apidocs/ee-image-getdownloadurl) are split and downloaded as separate tiles, then re-assembled into a single GeoTIFF.\n\n## Installation\n\n{rgeedim} is available on CRAN, and can be installed as follows:\n\n``` r\ninstall.packages(\"rgeedim\")\n```\n\nYou can install the development version of {rgeedim} using {remotes}:\n\n``` r\nif (!require(\"remotes\")) install.packages(\"remotes\")\nremotes::install_github(\"brownag/rgeedim\")\n```\n\n## How {rgeedim} Works\n\n{rgeedim} uses the `geedim` and `earthengine-api` Python modules via {reticulate}. If you do not have Python installed on your computer you can use `reticulate::install_python()` to download and set up a Python binary and virtual environment.\n\nIf you are running {rgeedim} interactively for the first time you may be prompted to create a default Python environment called `\"r-reticulate\"` for {reticulate} to use. Select 'Yes' at the prompt. If you select 'No' you will need to manually configure a Python environment. {rgeedim} provides a helper function, `gd_install()`, to facilitate installing the required Python dependencies.\n\n```{r example}\nlibrary(rgeedim)\n```\n\n## Dependencies\n\nYou will need Python 3 with the `geedim` module installed to use {rgeedim}.\n\n#### Using `gd_install()`\n\n`gd_install()` provides a simple wrapper around `reticulate::py_install()` that allows you to install dependencies using `pip`, virtual, or Conda environments.\n\n```r\n# install with pip (with reticulate)\ngd_install()\n\n# install with pip (system() call)\ngd_install(system = TRUE)\n\n# use virtual environment with default name \"r-rgeedim\"\ngd_install(method = \"virtualenv\")\n\n# use \"conda\" environment named \"foo\"\ngd_install(method = \"conda\", envname = \"foo\")\n```\n\n#### Using `pip`\n\nYou can install `geedim` with `pip`, for example:\n\n``` sh\npython -m pip install geedim\n```\n\nThis shell command assumes you have a Python 3 executable named (or aliased) as `python` on your PATH, or the command is being called from within an active Python virtual environment.\n\n### Troubleshooting \n\nIf using Python within RStudio, you may need to set your default interpreter in _Tools_ \u003e\u003e _Global Options..._ \u003e\u003e _Python_.\n\n## Authentication \u0026 Initialization\n\nIf this is your first time using any Google Earth Engine tools, authenticate with `gd_authenticate()`. You can pass arguments to use several different authorization methods.\n\nPerhaps the easiest to use is `auth_mode=\"notebook\"` since it does not rely on an existing `GOOGLE_APPLICATION_CREDENTIALS` file nor an installation of the `gcloud` CLI tools. However, the other options (using `gcloud` or a service account) are better for non-interactive or long-term use.\n\n``` r\n# short duration token\ngd_authenticate(auth_mode = \"notebook\")\n```\n\n``` r\n# longer duration (default); requires gcloud command-line tools\ngd_authenticate(auth_mode = \"gcloud\")\n```\n\nIn each R session you will need to initialize the Earth Engine library.\n\n```{r}\ngd_initialize(project = \"rgeedim-demo\")\n```\n\nNote that with `auth_mode=\"gcloud\"` you need to specify the project via `project=` argument, in your default configuration file or via system environment variable `GOOGLE_CLOUD_QUOTA_PROJECT`. The authorization tokens generated for `auth_mode=\"notebook\"` are always associated with a specific project.\n \nOnce initialized you can select an extent of interest. `gd_bbox()` is a simple function for specifying extents to {rgeedim} functions like `gd_download()`. \n\n``` {r}\nr \u003c- gd_bbox(\n  xmin = -120.6032,\n  xmax = -120.5377,\n  ymin = 38.0807,\n  ymax = 38.1043\n)\n```\n\nWe will download the US NED CHILI (Continuous Heat-Insolation Load Index) \u003chttps://developers.google.com/earth-engine/datasets/catalog/CSP_ERGo_1_0_US_CHILI\u003e. We specify an equal-area coordinate reference system (NAD83 Albers), bilinear resampling, and a resolution of 10 meters.\n\n```{r}\nx \u003c- 'CSP/ERGo/1_0/US/CHILI' |\u003e\n          gd_image_from_id() |\u003e\n          gd_download(\n            filename = 'image.tif',\n            region = r,\n            crs = \"EPSG:5070\",\n            resampling = \"bilinear\",\n            scale = 10, # scale=10: request ~10m resolution\n            overwrite = TRUE,\n            silent = FALSE\n          )\n```\n\nWe can inspect our results with {terra}. The resulting GeoTIFF has two layers,  `\"constant\"` and  `\"FILL_MASK\"`. The former contains the data, and the latter contains a mask reflecting data availability (value = 1 where data are available).\n\n```{r inspect}\nlibrary(terra)\nf \u003c- rast(x)\nf\n\nplot(f[[1]])\n```\n\n## Example: Hillshade from DEM\n\nThis example demonstrates the download of a section of the USGS NED seamless 10m grid. This DEM is processed locally with {terra} to calculate some terrain derivatives (slope, aspect) and a hillshade.\n\n```{r dem10-hillshade}\nlibrary(rgeedim)\nlibrary(terra)\n\ngd_initialize(project = \"rgeedim-demo\")\n\nb \u003c- gd_bbox(\n  xmin = -120.296,\n  xmax = -120.227,\n  ymin = 37.9824,\n  ymax = 38.0071\n)\n\n## hillshade example\n# download 10m NED DEM in AEA\nx \u003c- \"USGS/3DEP/10m\" |\u003e\n  gd_image_from_id() |\u003e\n  gd_download(\n    region = b,\n    scale = 10,\n    crs = \"EPSG:5070\",\n    resampling = \"bilinear\",\n    filename = \"image.tif\",\n    bands = list(\"elevation\"),\n    overwrite = TRUE,\n    silent = FALSE\n  )\ndem \u003c- rast(x)$elevation\n\n# calculate slope, aspect, and hillshade with terra\nslp \u003c- terrain(dem, \"slope\", unit = \"radians\")\nasp \u003c- terrain(dem, \"aspect\", unit = \"radians\")\nhsd \u003c- shade(slp, asp)\n\n# compare elevation vs. hillshade\nplot(c(dem, hillshade = hsd))\n```\n\nSubsets of the `\"USGS/3DEP/10m\"` image result in multi-band GeoTIFF with `\"elevation\"` and `\"FILL_MASK\"` bands. In the contiguous US we know the DEM is continuous so the `FILL_MASK` is not that useful. With geedim \u003e1.7 we retrieve only the `\"elevation\"` band by specifying argument `bands = list(\"elevation\")`. This cuts the raw image size that we need to download in half.\n\n## Example: LiDAR Slope Map\n\nThis example demonstrates how to access 1-meter LiDAR data from the USGS 3D Elevation Program (3DEP). \n\nThere are other methods to derive an area of interest from existing spatial data sources, here we use `gd_region()` on a SpatVector object and pass resulting object to several functions that require a processing extent.\n\nLiDAR data are not available everywhere, and are generally available as collections of (tiled) layers. Therefore we use `gd_search()` to narrow down the options. The small sample extent covers only one tile. Additional filters on date and data quality are also possible with `gd_search()`. A key step in this process is the use of `gd_composite()` to resample the component images of interest from the collection on the server-side.\n\n```{r lidar-composite}\nlibrary(rgeedim)\nlibrary(terra)\n\n# search and download from USGS 1m lidar data collection\ngd_initialize(project = \"rgeedim-demo\")\n\n# wkt-\u003eSpatVector-\u003eGeoJSON\nb \u003c- 'POLYGON((-121.355 37.56,-121.355 37.555,\n          -121.35 37.555,-121.35 37.56,\n          -121.355 37.56))' |\u003e\n  vect(crs = \"OGC:CRS84\")\n\n# create a GeoJSON-like list from a SpatVector object\n# (most rgeedim functions arguments for spatial inputs do this automatically)\nr \u003c- gd_region(b)\n\n# search collection for an area of interest\na \u003c- \"USGS/3DEP/1m\" |\u003e\n  gd_collection_from_name() |\u003e\n  gd_search(region = r) \n\n# inspect individual image metadata in the collection\ngd_properties(a)\n\n# resampling images as part of composite; before download\nx \u003c- a |\u003e\n  gd_composite(resampling = \"bilinear\") |\u003e \n  gd_download(region = r,\n              crs = \"EPSG:5070\",\n              scale = 1,\n              filename = \"image.tif\",\n              bands = list(\"elevation\"),\n              overwrite = TRUE,\n              silent = FALSE) |\u003e\n  rast()\n\n# inspect\nplot(terra::terrain(x$elevation))\nplot(project(b, x), add = TRUE)\n```\n\n## Example: Landsat-7 cloud/shadow-free composite\n\nThis example demonstrates download of a Landsat-7 cloud/shadow-free composite image. A collection is created from the NASA/USGS Landsat 7 Level 2, Collection 2, Tier 1. \n\nThis example is based on a [tutorial](https://geedim.readthedocs.io/en/latest/examples/l7_composite.html) in the `geedim` manual.\n\n```{r landsat7-composite}\nlibrary(rgeedim)\nlibrary(terra)\n\ngd_initialize(project = \"rgeedim-demo\")\n\nb \u003c- gd_bbox(\n  xmin = -120.296,\n  xmax = -120.227,\n  ymin = 37.9824,\n  ymax = 38.0071\n)\n\n## landsat example\n# search collection for date range and minimum data fill (85%)\nx \u003c- 'LANDSAT/LE07/C02/T1_L2' |\u003e\n  gd_collection_from_name() |\u003e\n  gd_search(\n    start_date = '2020-11-01',\n    end_date = '2021-02-28',\n    region = b,\n    cloudless_portion = 85\n  )\n\n# inspect individual image metadata in the collection\ngd_properties(x)\n\n# download a single image, no compositing\ny \u003c- gd_properties(x)$id[1] |\u003e \n  gd_image_from_id() |\u003e\n  gd_download(\n    filename = \"image.tif\",\n    region = b,\n    scale = 30,\n    crs = 'EPSG:5070',\n    dtype = 'uint16',\n    overwrite = TRUE,\n    silent = FALSE\n  )\n\nplot(rast(y)[[1:4]])\n```\n\nNow we have several images of interest, and also major issues with some of the inputs. In this case there were failures of sensors on the Landsat satellite, but other data gaps may occur due to masked cloudy areas or due to patchy coverage of the source product.\n\n```{r landsat7-qmosaic}\n# create composite landsat image near December 1st, 2020 and download  \n# using q-mosaic method. \nz \u003c- x |\u003e \n  gd_composite(\n    method = \"q-mosaic\",\n    date = '2020-12-01'\n  ) |\u003e\n  gd_download(\n    filename = \"image.tif\",\n    region = b,\n    scale = 30,\n    crs = 'EPSG:5070',\n    dtype = 'uint16',\n    overwrite = TRUE,\n    silent = FALSE\n  )\n\nplot(rast(z)[[1:4]])\n```\n\nThe `\"q-mosaic\"` method produces a composite largely free of artifacts; this is because it prioritizes pixels with higher distance from clouds to fill in the gaps. Other methods are available such as `\"medoid\"`; this may give better results when compositing more contrasting inputs such as several dates over a time period where vegetation or other cover changes appreciably.\n\n```{r include=FALSE}\nunlink('image.tif')\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrownag%2Frgeedim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrownag%2Frgeedim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrownag%2Frgeedim/lists"}