{"id":13858015,"url":"https://github.com/hypertidy/vapour","last_synced_at":"2025-05-14T23:12:02.338Z","repository":{"id":38106995,"uuid":"98496053","full_name":"hypertidy/vapour","owner":"hypertidy","description":"GDAL API package for R","archived":false,"fork":false,"pushed_at":"2025-04-04T01:29:38.000Z","size":10011,"stargazers_count":85,"open_issues_count":59,"forks_count":10,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-06T05:05:22.327Z","etag":null,"topics":["cpp","gdal","gdal-api"],"latest_commit_sha":null,"homepage":"https://hypertidy.github.io/vapour/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hypertidy.png","metadata":{"files":{"readme":"README.Rmd","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":null,"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,"publiccode":null,"codemeta":null},"funding":{"github":["mdsumner"]}},"created_at":"2017-07-27T05:08:36.000Z","updated_at":"2025-04-04T01:29:43.000Z","dependencies_parsed_at":"2024-01-29T14:56:19.921Z","dependency_job_id":"16481e43-5fc4-4de1-824e-7d9023d90d5b","html_url":"https://github.com/hypertidy/vapour","commit_stats":{"total_commits":911,"total_committers":6,"mean_commits":"151.83333333333334","dds":"0.021953896816684915","last_synced_commit":"4bebe4f1771963437e22b373a7379c82395c7bb4"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypertidy%2Fvapour","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypertidy%2Fvapour/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypertidy%2Fvapour/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypertidy%2Fvapour/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hypertidy","download_url":"https://codeload.github.com/hypertidy/vapour/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253854601,"owners_count":21974324,"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":["cpp","gdal","gdal-api"],"created_at":"2024-08-05T03:01:53.948Z","updated_at":"2025-05-14T23:12:02.330Z","avatar_url":"https://github.com/hypertidy.png","language":"C++","funding_links":["https://github.com/sponsors/mdsumner"],"categories":["R","Geospatial Library"],"sub_categories":["R"],"readme":"---\noutput: github_document\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n \n```{r setup, include = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\"\n)\n\n```\n\n# vapour  \u003cimg src=\"man/figures/logo.png\" align=\"right\" height=\"228\" /\u003e\n\n\n\u003c!-- badges: start --\u003e\n[![R_build_status](https://github.com/hypertidy/vapour/workflows/R-CMD-check/badge.svg)](https://github.com/hypertidy/vapour/actions)\n[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/vapour)](https://cran.r-project.org/package=vapour)\n[![CRAN status](https://www.r-pkg.org/badges/version/vapour)](https://CRAN.R-project.org/package=vapour)\n\u003c!-- badges: end --\u003e\n\n\n## Overview\n\nThe vapour package provides access to the basic *read* functions available in [GDAL](https://gdal.org/) for both [raster](https://gdal.org/en/stable/user/raster_data_model.html) and [vector](https://gdal.org/en/stable/user/vector_data_model.html) data sources. \n\nThe functions are deliberately *lower-level* than these data models and provide access to the\ncomponent entities independently. \n\nFor vector data: \n\n* read access to fields alone\n* read raw binary geometry alone, or geometry in text forms (GeoJSON, WKT, GML, KML).\n* read access to the extent of geometries\n* helper functions to summarize feature identity and geometry status\n* limit/skip control on records read \n* execution of [OGRSQL](https://gdal.org/en/stable/user/ogr_sql_dialect.html) with control of SQL dialect\n* read in the context of a [bounding box spatial filter](https://gdal.org/en/stable/user/ogr_sql_dialect.html#executesql) can be applied via the `extent` argument\n \n\nFor raster data: \n\n* read access to the list of available rasters within a collection source (subdatasets). \n* read access to *structural metadata* for individual raster sources. \n* read access for raw data using GDAL's  [RasterIO framework](https://gdal.org/en/stable/tutorials/raster_api_tut.html) and its dynamic image decimation / replication resampling algorithms. \n* read access for raw data using GDAL's [Warper framework](https://gdal.org/en/stable/api/gdalwarp_cpp.html) and its dynamic image warping, a superset of the RasterIO capabilities. \n\nThe warper works for data sources that contain *overviews* (or pyramid levels-of-detail) as it automatically chooses an appropriate level for the request made, files, urls, database connections, online tiled image servers, and all the various ways of specifying GDAL data sources. \n\nThe workflows available are intended to support development of applications in R for these vector and [raster data](https://en.wikipedia.org/wiki/Raster_data) without being constrained to any particular data model. \n\n\n## Installation\n\nInstall from CRAN, this should work on MacOS and Windows because CRAN provide binaries. \n\n\n```{r, install-cran,eval=FALSE}\ninstall.packages(\"vapour\")\n```\n\nThe development version can be installed from Github. \n\n```{r install-universe, eval=FALSE}\noptions(repos = c(\n    hypertidy = 'https://hypertidy.r-universe.dev',\n    CRAN = 'https://cloud.r-project.org'))\ninstall.packages(\"vapour\")\n```\n\nTo install the development version the more github-traditional way: \n\n```{r install-dev, eval=FALSE}\nremotes::install_github(\"hypertidy/vapour\")\n```\n\nYou will need development tools for building R packages. \n\nOn Linux, I'm using latest ubuntu and R usually, check CRAN on ubuntu (search for \"ubuntu cran\"). \n\nthen\n\n```bash\napt install --no-install-recommends software-properties-common dirmngr\nadd-apt-repository ppa:ubuntugis/ubuntugis-unstable --yes\n\napt update\n\n## Install 3rd parties\n\n## NetCDF and geo-spatial wunderkind\napt install libgdal-dev \n\n```\n\nthen `install.packages(\"vapour\")` or whatever you use. \n\n## Purpose \n\nThe goal of vapour is to provide a basic **GDAL API** package for R. The key functions provide vector geometry or attributes and raster data and raster metadata. \n\nThe priority is to give low-level access to key functionality rather than\ncomprehensive coverage of the library. The real advantage of `vapour` is the\nflexibility of a modular workflow, not the outright efficiency.\n\nA parallel goal is to be freed from the powerful but sometimes limiting\nhigh-level data models of GDAL itself, specifically these are *simple features*\nand *affine-based regular rasters composed of 2D slices*. (GDAL will possibly\nremove these limitations over time but still there will always be value in\nhaving modularity in an ecosystem of tools.)\n\nGDAL's dynamic resampling of arbitrary raster windows is also very useful\nfor interactive tools on local data, and is radically under-utilized. A quick example, topography data is available from Amazon\ncompute servers, first we need a config for the source: \n\n```{r config-file}\nelevation.tiles.prod \u003c- \n '\u003cGDAL_WMS\u003e\n  \u003cService name=\"TMS\"\u003e\n    \u003cServerUrl\u003ehttps://s3.amazonaws.com/elevation-tiles-prod/geotiff/${z}/${x}/${y}.tif\u003c/ServerUrl\u003e\n  \u003c/Service\u003e\n  \u003cDataWindow\u003e\n    \u003cUpperLeftX\u003e-20037508.34\u003c/UpperLeftX\u003e\n    \u003cUpperLeftY\u003e20037508.34\u003c/UpperLeftY\u003e\n    \u003cLowerRightX\u003e20037508.34\u003c/LowerRightX\u003e\n    \u003cLowerRightY\u003e-20037508.34\u003c/LowerRightY\u003e\n    \u003cTileLevel\u003e14\u003c/TileLevel\u003e\n    \u003cTileCountX\u003e1\u003c/TileCountX\u003e\n    \u003cTileCountY\u003e1\u003c/TileCountY\u003e\n    \u003cYOrigin\u003etop\u003c/YOrigin\u003e\n  \u003c/DataWindow\u003e\n  \u003cProjection\u003eEPSG:3857\u003c/Projection\u003e\n  \u003cBlockSizeX\u003e512\u003c/BlockSizeX\u003e\n  \u003cBlockSizeY\u003e512\u003c/BlockSizeY\u003e\n  \u003cBandsCount\u003e1\u003c/BandsCount\u003e\n  \u003cDataType\u003eInt16\u003c/DataType\u003e\n  \u003cZeroBlockHttpCodes\u003e403,404\u003c/ZeroBlockHttpCodes\u003e\n  \u003cDataValues\u003e\n    \u003cNoData\u003e-32768\u003c/NoData\u003e\n  \u003c/DataValues\u003e\n  \u003cCache/\u003e\n\u003c/GDAL_WMS\u003e'\n\n```\n```{r topo-example}\n## we want an extent\nex \u003c- c(-1, 1, -1, 1) * 5000  ## 10km wide/high region\n## Madrid is at this location\npt \u003c- cbind(-3.716667, 40.416667)\ncrs \u003c- sprintf(\"+proj=laea +lon_0=%f +lat_0=%f +datum=WGS84\", pt[1,1,drop = TRUE], pt[1,2, drop = TRUE])\ndm \u003c- c(256, 256)\n\n\nvals \u003c- vapour::vapour_warp_raster(elevation.tiles.prod, extent = ex, dimension = dm, projection = crs)\n## now we can use this in a matrix\nimage(m \u003c- matrix(vals[[1]], nrow = dm[2], ncol = dm[1])[,dm[2]:1 ])\n## using the image list format\nx \u003c- list(x = seq(ex[1], ex[2], length.out = dm[1] + 1), y = seq(ex[3] ,ex[4], length.out = dm[1] + 1), z = m)\nimage(x)\n\n## or as a spatial object\nlibrary(terra)\nr \u003c- rast(ext(ex), nrows = dm[2], ncols = dm[1], crs = crs, vals = vals[[1]])\ncontour(r, add = TRUE)\n\n```\n\nIf we want more detail, go ahead: \n\n```{r lod}\ndm \u003c- c(512, 512)\nvals \u003c- vapour::vapour_warp_raster(elevation.tiles.prod, extent = ex, dimension = dm, projection = crs)\n(r \u003c- rast(ext(ex), nrows = dm[2], ncols = dm[1], crs = crs, vals = vals[[1]]))\nplot(r, col = hcl.colors(24))\n\n```\n\nGDAL is obstinately *format agnostic*, the A stands for *Abstraction* and we like that in R too, just gives us the data. Here we created a base matrix image object, and a raster package *RasterLayer*, but we could use the spatstat im, or objects in stars or terra packages, it makes no difference to the read-through-warp process. \n\nThis partly draws on work done in [the sf package](https://github.com/r-spatial/sf) and [the terra package](https://github.com/rspatial/terra) and in packages `rgdal` and `rgdal2`.\nI'm amazed that something as powerful and general as GDAL is still only\navailable through these lenses, but maybe more folks will get interested over time. \n\n\n\n## Examples\n\nThe package documentation page gives an overview of available functions. \n\n```R\nhelp(\"vapour-package\")\n```\n\nSee the vignettes and documentation for examples WIP. \n\n\n## Context\n\nExamples of packages that use vapour are in development, especially [whatarelief](https://github.com/hypertidy/whatarelief) and [ggdal](https://github.com/rgdal-dev/ggdal). \n\n\nLimitations, work-in-progress and other discussion: \n\nhttps://github.com/hypertidy/vapour/issues/4\n\nWe've kept a record of a minimal GDAL wrapper package here: \n\nhttps://github.com/diminutive/gdalmin\n\n\n# Code of conduct\n\nPlease note that this project is released with a [Contributor Code of\nConduct](https://github.com/hypertidy/vapour/blob/master/CONDUCT.md). By participating in this project you agree to abide by its\nterms.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhypertidy%2Fvapour","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhypertidy%2Fvapour","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhypertidy%2Fvapour/lists"}