From 684e665f348bff827bff8adcf9ce80b906f94a3c Mon Sep 17 00:00:00 2001 From: Dennis Irorere <35724017+denironyx@users.noreply.github.com> Date: Sun, 16 Jun 2024 16:41:25 +0100 Subject: [PATCH] overturemapsr document --- README.Rmd | 30 ++++++++++++++++++++++++++---- README.md | 48 +++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 71 insertions(+), 7 deletions(-) diff --git a/README.Rmd b/README.Rmd index 82b8e53..a7af1e1 100644 --- a/README.Rmd +++ b/README.Rmd @@ -13,17 +13,21 @@ knitr::opts_chunk$set( ) ``` -# overturemapsr +# OvertureMaps R Package + +This package provides functions to interact with OvertureMaps datasets. It includes utilities for fetching data from S3 and converting it to sf objects for spatial analysis. + [![R-CMD-check](https://github.com/denironyx/overturemapsr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/denironyx/overturemapsr/actions/workflows/R-CMD-check.yaml) + Overture Maps provides free and open geospatial map data, from many different sources and normalized to a common schema. This tool helps to download Overture data within a region of interest and converts it to a few different file formats. ## Installation -You can install the development version of overturemapsr from [GitHub](https://github.com/) with: +To install this package, you need to have the necessary dependencies installed. You can install the package using the following commands: ``` r # install.packages("devtools") @@ -39,8 +43,26 @@ library(overturemapsr) ## basic example code ``` - You'll still need to render `README.Rmd` regularly, to keep `README.md` up-to-date. `devtools::build_readme()` is handy for this. - In that case, don't forget to commit and push the resulting figure files, so they display on GitHub and CRAN. + +## Functions + +- `get_all_overture_types`: This function returns all available OvertureMaps theme types. +- `dataset_path`: This function returns the S3 path for the specified Overture dataset type. +- `record_batch_reader`: This function retrieves a filtered dataset from the specified Overture dataset type, optionally within a bounding box, and converts it to an sf object. + +#### Parameters + +- overture_type: Character. Required. The type of feature to select. Examples include 'building', 'place', etc. To learn more, run get_all_overture_types(). +- bbox: Numeric vector. Optional. A bounding box specified as c(xmin, ymin, xmax, ymax). It is recommended to use a bounding box to limit the dataset size and processing time. Without a bounding box, processing the entire dataset (e.g., buildings over 2 billion) can be time-consuming. + + +[Bounding Box Tool from Klokantech](https://boundingbox.klokantech.com/): Use this tool to find and specify bounding boxes of interest for your data queries. + +### Notes +This repository and project are based on [OvertureMaps Python Repository](https://github.com/OvertureMaps/overturemaps-py/tree/main). The functionality are similar and things are likely to change, including the user interface, until a stable release. We will keep the documentation here up-to-date. + +##### License +This package is licensed under the MIT License. diff --git a/README.md b/README.md index ef29dc7..fe8af17 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,16 @@ -# overturemapsr +# OvertureMaps R Package + +This package provides functions to interact with OvertureMaps datasets. +It includes utilities for fetching data from S3 and converting it to sf +objects for spatial analysis. [![R-CMD-check](https://github.com/denironyx/overturemapsr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/denironyx/overturemapsr/actions/workflows/R-CMD-check.yaml) + Overture Maps provides free and open geospatial map data, from many @@ -15,8 +20,8 @@ few different file formats. ## Installation -You can install the development version of overturemapsr from -[GitHub](https://github.com/) with: +To install this package, you need to have the necessary dependencies +installed. You can install the package using the following commands: ``` r # install.packages("devtools") @@ -37,3 +42,40 @@ up-to-date. `devtools::build_readme()` is handy for this. In that case, don’t forget to commit and push the resulting figure files, so they display on GitHub and CRAN. + +## Functions + +- `get_all_overture_types`: This function returns all available + OvertureMaps theme types. +- `dataset_path`: This function returns the S3 path for the specified + Overture dataset type. +- `record_batch_reader`: This function retrieves a filtered dataset from + the specified Overture dataset type, optionally within a bounding box, + and converts it to an sf object. + +#### Parameters + +- overture_type: Character. Required. The type of feature to select. + Examples include ‘building’, ‘place’, etc. To learn more, run + get_all_overture_types(). +- bbox: Numeric vector. Optional. A bounding box specified as c(xmin, + ymin, xmax, ymax). It is recommended to use a bounding box to limit + the dataset size and processing time. Without a bounding box, + processing the entire dataset (e.g., buildings over 2 billion) can be + time-consuming. + +[Bounding Box Tool from +Klokantech](https://boundingbox.klokantech.com/): Use this tool to find +and specify bounding boxes of interest for your data queries. + +### Notes + +This repository and project are based on [OvertureMaps Python +Repository](https://github.com/OvertureMaps/overturemaps-py/tree/main). +The functionality are similar and things are likely to change, including +the user interface, until a stable release. We will keep the +documentation here up-to-date. + +##### License + +This package is licensed under the MIT License.