mikemahoney218 / spacey Goto Github PK

View Code? Open in Web Editor NEW

12.0 3.0 2.0 17.89 MB

Access USGS and ESRI maps for fast rayshader mapping

Home Page: https://mikemahoney218.github.io/spacey/

License: Other

R 98.67% Shell 1.33%

spacey cran r r-package rstats rayshader esri usgs map mapping

spacey's Introduction

spacey

The spacey package provides three main functions to make it easy to quickly build beautiful maps of locations in the United States via the [rayshader](https://github.com/tylermorganwall/rayshader) package. First off, it provides an automap function to quickly make maps using data from the USGS national map:

library(spacey)
automap(44.121268, -73.903734)

As well as letting you incorporate overlay textures from ESRI’s MapServer API:

automap(44.121268, -73.903734, overlay = "World_Imagery")

And optionally even turn these into 3D visualizations:

automap(44.121268,
  -73.903734,
  overlay = "World_Imagery",
  method = "3d"
)

And while automap tries to make it easy to configure these maps, spacey also lets you save off your heightmaps and overlays directly, either through arguments to automap or the functions get_heightmap and get_overlay, so that you can work directly with rayshader to make these maps by yourself.

There’s a lot more to these three functions, alongside a few basic geospatial utilities spacey implements to make it easier to make maps from your data. For more information, check out the introductory vignette! ## Installation

If the CRAN version badge above is green, you can install the released version of spacey from CRAN with:

install.packages("spacey")

You can always get the most up-to-date development version with:

# install.packages("devtools")
devtools::install_github("mikemahoney218/spacey")

Functions

At the moment, spacey consists mainly of the following functions:

automap uses a combination of sensible defaults to produce attractive square map outputs from a single central point location.
get_heightmap retrieves an elevation map from the USGS for a specified boundary box and translates it into an R matrix.
get_image_overlay retrieves a texture from ESRI for a specified boundary box and translates it into a matrix.

It also includes several helper functions, including:

get_coord_bounding_box finds the smallest rectangle required to contain a list of lat/long coordinates.
get_centroid_bounding_box finds the corners of a square with diagonals a set distance from a central point, enabling map creation for a single central lat/long combination.
get_centroid finds the central point for matched vectors of latitude and longitude.
load_heightmap can import stored .tif files in order to used saved USGS national map data (or potentially other sources).
load_overlay is an extremely thin wrapper around png::readPNG, used to read stored ESRI image overlay files.

Limitations

At the moment, spacey is only able to retrieve data from the USGS National Map API, limiting its use to the United States. If you have a good API for other regions, open an issue or submit a PR!

Similarly, most geospatial calculations implemented in this package don’t deal well with areas near the poles or Prime Meridian. Given the spatial constraints of the USGS dataset, this isn’t a problem for current use cases, but be careful extending these functions outside of this package.

spacey's People

Contributors

Stargazers

Watchers

Forkers

melimore86 quinnpertuit

spacey's Issues

Add wrapper functions to save heightmap, overlay to file

It would make sense to wrap the raster and png functions used to save rasters and pngs, so that users can save those objects without another library call (and this will probably reduce code duplication, as well).

"automap" should accept native R objects for mapping

Right now, rerunning maps made via automap requires either rehitting the API or reloading data from file, even though get_image_overlay and get_heightmap allow the data to be stored in an object. It should be possible to create automap maps from R objects without having to write to disk or hit the API.

"automap" can and should be extracted into multiple functions

Right now, spacey uses the automap as a monolithic approach to mapping, coordinating calls to get_heightmap and get_image_overlay as well as the map building and input checking processes. A smarter approach would be to subset this into smaller pieces, increasing code maintainability and potentially allowing for greater reuse.

0.1.0 to-do

~~Implement support for futures in mapping functions~~
~~Retry API once on failure (with optional default to fail and stay failed)~~
~~Alter img_size spec to accept width and height vector (and potentially fix rectangular returns)~~ done by making this the only API

"get_textures" should implement additional palettes and include shortnames

Right now, "spacey" ships with three new palettes. It would be great to include additional options, and to give them reference names that aren't just spaceyX in order to be better remembered by users.

let "automap" take NULL lat and lng

Right now, "automap" needs a lat and lng argument in order to make any maps, even if using files for the heightmap and overlay. This is silly, because those arguments aren't used if using files for heightmap and overlay. lat and lng should be set to NULL by default, with error handling if no other data source is provided.

This is somewhat related to #4 -- viewing automap as a central approach for mapping from a) coordinates, b) files, and c) objects lends itself to a natural pattern for decomposition.

automap error

My fellow peers and I are working on creating a vignette for your spacey package. We are students in Kelly Bodwin's Introduction to R class here at Cal Poly San Luis Obispo.
We are running into issues running the automap function. If you have any troubleshooting tips we can use to utilize spacey, let us know. Below is an example.
We also would like to here suggestions on what added material you would like to be added on top of your current introduction vignette found of Github.
Thank you for your time,
331 Project Team

spacey::automap(44.121268, -73.903734)
#> Error in .local(.Object, ...) :
#> Error in value[[3L]](cond): attempt to apply non-function

^{Created on 2020-03-02 by the reprex package (v0.3.0)}

"get_coord_bounding_box" should include an "expand" argument

Right now, in order to expand maps created from more than a single coordinate pair beyond their immediate bounding box, the user needs to get the centroid for their data, calculate the distance from their centroid they want included, and then provide those as arguments to any major function. Much more useful would be an expand argument, allowing users to move their bounding box out by X meters in each direction -- this way, users whose points represent field samples (for instance) can have their entire dataset contextualized by its surroundings.