version 0.1.1

cran · Dec 17, 2022 · e0a78f3 · e0a78f3
1 parent 853bd4b
commit e0a78f3
Show file tree

Hide file tree

Showing 20 changed files with 266 additions and 107 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,6 +1,6 @@
 Package: googletraffic
 Title: Google Traffic
-Version: 0.1.0
+Version: 0.1.1
 Authors@R: 
     person("Robert", "Marty", , "rmarty@worldbank.org", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0002-3164-3813"))
@@ -9,11 +9,12 @@ License: MIT + file LICENSE
 Encoding: UTF-8
 RoxygenNote: 7.2.1
 URL: https://dime-worldbank.github.io/googletraffic/
+BugReports: https://github.com/dime-worldbank/googletraffic/issues
 Imports: dplyr, googleway, htmlwidgets, plotwidgets, png, sf, sp,
-        stringr, webshot, raster
+        stringr, webshot, raster, ColorNameR, schemr
 NeedsCompilation: no
-Packaged: 2022-11-08 13:18:07 UTC; robmarty
+Packaged: 2022-12-17 16:22:24 UTC; robmarty
 Author: Robert Marty [aut, cre] (<https://orcid.org/0000-0002-3164-3813>)
 Maintainer: Robert Marty <rmarty@worldbank.org>
 Repository: CRAN
-Date/Publication: 2022-11-09 10:30:14 UTC
+Date/Publication: 2022-12-17 16:50:02 UTC
diff --git a/MD5 b/MD5
@@ -1,23 +1,23 @@
-3436f69d4f936d9071064a6100da5456 *DESCRIPTION
+9140499745c0f0c42f86c796e8849003 *DESCRIPTION
 93e38382609732cbe38b7590d04f1baf *LICENSE
-021210188198a038ebf5ff9be63ae35d *NAMESPACE
-970f9fef926bc47a757c404e87c73f53 *NEWS.md
+2f20fdfb47fd2afdab970d975d89be94 *NAMESPACE
+7672a2bb5e47d526fa77a85854d45742 *NEWS.md
 65914942c7eef48505361e20636c65d7 *R/gt_estimate_webshot_delay.R
-8df7bfa9ce59e473e40eb81ead4afb72 *R/gt_html_to_raster.R
-b91b0a2fee47cac2573ed05ccc2b31a1 *R/gt_load_png_as_traffic_raster.R
-40d789e353f2c66d18f087c0a6bc223b *R/gt_make_extent.R
-ca9426f50aca30fd410f556601c88e90 *R/gt_make_grid.R
-863106448ea1625fb21c144ee000ef2e *R/gt_make_html.R
-a0e6432ac4bee9e5bc5ec5f3275836d3 *R/gt_make_png.R
-49f7124f9286fcabb76097db63bfbd40 *R/gt_make_raster.R
-f617146e1fcd45116399214493c54bde *R/gt_make_raster_from_grid.R
-b02fc029d99cfa32443a277548fdacea *R/gt_make_raster_from_polygon.R
+c5467788357bd19e8edaeea266df56c5 *R/gt_html_to_raster.R
+d4ac561456a3de8af7cd6f4ef3759910 *R/gt_load_png_as_traffic_raster.R
+92bbe6cd57ceec6ec4e8967b6fb72506 *R/gt_make_extent.R
+3b95438a81785b0f2a97a94bf2305e13 *R/gt_make_grid.R
+b7b453167d0bd7cb3b0ab9317b2dafbe *R/gt_make_html.R
+c6a18e60d8258cde0211ca7cce0df283 *R/gt_make_png.R
+ac59cbfafeaf6c72214b8411f410a6a9 *R/gt_make_raster.R
+47262b439be4101d06214ca85e2f791b *R/gt_make_raster_from_grid.R
+7166dc7b407726b2d3d4fdfb30860a00 *R/gt_make_raster_from_polygon.R
 785de68094e542ee5e67caf3eef8fa82 *R/gt_mosaic.R
-b9fe1905f4bceb5c808a5f9629ad650f *README.md
-1218a15dfcc00aea21fa1ddf3b177275 *man/gt_load_png_as_traffic_raster.Rd
-67852b68599aedb34597fac7d44e2dc9 *man/gt_make_grid.Rd
-f6a1aa25622d42cedc935ac28e863938 *man/gt_make_png.Rd
-947ed94860d56d477c27754c83f2c106 *man/gt_make_raster.Rd
-cfcabb066b49bd2deb9767638c538ab4 *man/gt_make_raster_from_grid.Rd
-d79118dfefa3ddc1151185728d2d3314 *man/gt_make_raster_from_polygon.Rd
+a7cae88e6a9e4655db7c560509ac6c3e *README.md
+9d8dbebbff14ed7cab49ec9c951f539e *man/gt_load_png_as_traffic_raster.Rd
+f1ab06099837d416c6bff23d9420382f *man/gt_make_grid.Rd
+2847c3a6193ef3975e443febba5ec5bf *man/gt_make_png.Rd
+d3c900634a9d8abb4c55bdf8ad446af6 *man/gt_make_raster.Rd
+fa214d595cd1d5b1aac7acb56caabf47 *man/gt_make_raster_from_grid.Rd
+2aedd088f2feff6992ebed3545dd777a *man/gt_make_raster_from_polygon.Rd
 cb612a512cdbe7da6c98bd0d1dae8128 *man/gt_mosaic.Rd
diff --git a/NAMESPACE b/NAMESPACE
@@ -7,12 +7,14 @@ export(gt_make_raster)
 export(gt_make_raster_from_grid)
 export(gt_make_raster_from_polygon)
 export(gt_mosaic)
+import(ColorNameR)
 import(dplyr)
 import(googleway)
 import(htmlwidgets)
 import(plotwidgets)
 import(png)
 import(raster, except = c(union, select, intersect))
+import(schemr)
 import(sf)
 import(sp)
 import(stringr)

diff --git a/NEWS.md b/NEWS.md
@@ -1,4 +1,11 @@
 # googletraffic 0.1.0
 
+* Add `webshot_zoom` parameter
+* Add `traffic_color_dist_thresh` parameter
+* Add `traffic_color_dist_metric` parameter
+* Improve documentation
+
+# googletraffic 0.1.0
+
 * Make package
 * Added a `NEWS.md` file to track changes to the package.
diff --git a/R/gt_html_to_raster.R b/R/gt_html_to_raster.R
@@ -8,16 +8,23 @@
 # @param location Vector of latitude and longitude
 # @param height Height (in pixels; pixel length depends on zoom)
 # @param width Width (in pixels; pixel length depends on zoom)
-# @param zoom Zoom level
+# @param zoom Zoom level; integer from 5 to 20. For more information about how zoom levels correspond to pixel size, see [here](https://wiki.openstreetmap.org/wiki/Zoom_levels) and [here](https://developers.google.com/maps/documentation/javascript/overview#zoom-levels).
+# @param traffic_color_dist_thresh Google traffic relies on four main base colors: `#63D668` for no traffic, `#FF974D` for medium traffic, `#F23C32` for high traffic, and `#811F1F` for heavy traffic. Slight variations of these colors can also represent traffic. By default, the base colors and all colors within a 2.3 color distance of each base color are used; by default, the `CIEDE2000` formula is used to determine color distance. A value of 2.3 is one threshold used to define a "just noticeable distance" between colors. This parameter changes the color distance from the base colors used to define colors as traffic.
+# @param traffic_color_dist_metric See above; this parameter changes the formula used to calculate distances between colors. By default, `CIEDE2000` is used; `CIE76` and `CIE94` can also be used.
+# @param webshot_zoom How many pixels should be created relative to height and width values. If `height` and `width` are set to `100` and `webshot_zoom` is set to `2`, the resulting raster will have dimensions of about `200x200` (default: `1`). 
 # @param webshot_delay How long to wait for .html file to load. Larger .html files (large height/widths) will require more time to fully load. If `NULL`, the following delay time (in seconds) is used: `delay = max(height,width)/200`.
 # @param print_progress Whether to print function progress
 #
 # @return Returns a georeferenced raster. Raster pixels can contain the following values: 1 = no traffic; 2 = medium traffic; 3 = high traffic; 4 = heavy traffic.
+# @references Sharma, G., Wu, W., & Dalal, E. N. (2005). The CIEDE2000 color-difference formula: Implementation notes, supplementary test data, and mathematical observations. Color Research & Application: Endorsed by Inter-Society Color Council, The Colour Group (Great Britain), Canadian Society for Color, Color Science Association of Japan, Dutch Society for the Study of Color, The Swedish Colour Centre Foundation, Colour Society of Australia, Centre Français de la Couleur, 30(1), 21-30.
 gt_html_to_raster <- function(filename,
                               location,
                               height,
                               width,
                               zoom,
+                              traffic_color_dist_thresh = 2.3,
+                              traffic_color_dist_metric = "CIEDE2000",
+                              webshot_zoom = 1,
                               webshot_delay = NULL,
                               print_progress = TRUE){
 
@@ -47,7 +54,7 @@ gt_html_to_raster <- function(filename,
                      vwidth = width,
                      cliprect = "viewport",
                      delay = webshot_delay,
-                     zoom = 1)
+                     zoom = webshot_zoom) # change
   })
 
   #### Load as raster and image
@@ -57,7 +64,9 @@ gt_html_to_raster <- function(filename,
                                      location = c(latitude, longitude),
                                      height   = height,
                                      width    = width,
-                                     zoom     = zoom)
+                                     zoom     = zoom,
+                                     traffic_color_dist_thresh = traffic_color_dist_thresh,
+                                     traffic_color_dist_metric = traffic_color_dist_metric)
 
   ## Delete png from temp file
   unlink(file.path(filename_dir, paste0(filename_only,".png")))

diff --git a/R/gt_load_png_as_traffic_raster.R b/R/gt_load_png_as_traffic_raster.R
@@ -2,16 +2,20 @@
 
 #' Converts PNG to raster
 #'
-#' Converts PNG of Google traffic data to raster and translates color values to traffic values
+#' Converts PNG of [Google traffic data](https://developers.google.com/maps/documentation/javascript/trafficlayer) to raster and translates color values to traffic values
 #'
 #' @param filename Filename of PNG file
 #' @param location Vector of latitude and longitude used to create PNG file using [gt_make_png()]
 #' @param height Height (in pixels; pixel length depends on zoom) used to create PNG file using [gt_make_png()]
 #' @param width Width (in pixels; pixel length depends on zoom) used to create PNG file using [gt_make_png()]
-#' @param zoom Zoom used to PNG png file using [gt_make_png()]
-#'
+#' @param zoom Zoom level used to create PNG file using [gt_make_png()]
+#' @param traffic_color_dist_thresh Google traffic relies on four main base colors: `#63D668` for no traffic, `#FF974D` for medium traffic, `#F23C32` for high traffic, and `#811F1F` for heavy traffic. Slight variations of these colors can also represent traffic. By default, the base colors and all colors within a 4.6 color distance of each base color are used to define traffic; by default, the `CIEDE2000` metric is used to determine color distance. A value of 2.3 is one threshold used to define a "just noticeable distance" (JND) between colors (by default, 2 X JND is used). This parameter changes the color distance from the base colors used to define colors as traffic. For more information, see [here](https://en.wikipedia.org/wiki/Color_difference#CIEDE2000).
+#' @param traffic_color_dist_metric See above; this parameter changes the metric used to calculate distances between colors. By default, `CIEDE2000` is used; `CIE76` and `CIE94` can also be used. For more information, see [here](https://en.wikipedia.org/wiki/Color_difference#CIEDE2000).
 #' @return Returns a raster where each pixel represents traffic level (1 = no traffic, 2 = medium traffic, 3 = traffic delays, 4 = heavy traffic)
 #'
+#' @references Markus Hilpert, Jenni A. Shearston, Jemaleddin Cole, Steven N. Chillrud, and Micaela E. Martinez. [Acquisition and analysis of crowd-sourced traffic data](https://arxiv.org/abs/2105.12235). CoRR, abs/2105.12235, 2021.
+#' @references Pavel Pokorny. [Determining traffic levels in cities using google maps](https://ieeexplore.ieee.org/abstract/document/8326831). In 2017 Fourth International Conference on Mathematics and Computers in Sciences and in Industry (MCSI), pages 144–147, 2017.
+#'
 #' @examples 
 #' \dontrun{
 #' ## Make png
@@ -35,7 +39,9 @@ gt_load_png_as_traffic_raster <- function(filename,
                                           location,
                                           height,
                                           width,
-                                          zoom){
+                                          zoom,
+                                          traffic_color_dist_thresh = 4.6,
+                                          traffic_color_dist_metric = "CIEDE2000"){
 
   # Code produces some warnings that are not relevant; for example, when initially
   # make a raster, we get a warning that the extent is not defined. This warning
@@ -54,45 +60,63 @@ gt_load_png_as_traffic_raster <- function(filename,
     ## Image to hex
     rimg <- raster::as.raster(img) 
 
-    colors_df <- rimg %>% 
-      table() %>% 
-      as.data.frame() %>%
-      dplyr::rename(hex = ".")
-
-    colors_df$hex <- colors_df$hex %>% 
-      as.character()
-
-    ## Assign traffic colors based on hsl
-    hsl_df <- colors_df$hex %>% 
-      plotwidgets::col2hsl() %>%
-      t() %>%
-      as.data.frame() 
-
-    colors_df <- dplyr::bind_cols(colors_df, hsl_df)
-
-    colors_df <- colors_df %>%
-      dplyr::mutate(color = case_when(#((H == 0) & (S < 0.2)) ~ "background",
-        ((H == 0) & (S >= 0.28) & (S < 0.7) & (L >= 0.3) & (L <= 0.42)) ~ "dark-red",
-        H > 0 & H <= 5 & L <= 0.65 ~ "red", # L <= 0.80
-        H >= 20 & H <= 28 & L <= 0.80 ~ "orange", # L <= 0.85
-        H >= 120 & H <= 135 & L <= 0.80 ~ "green"))
-
-    ## Apply traffic colors to raster
-    colors_unique <- colors_df$color %>% unique()
-    colors_unique <- colors_unique[!is.na(colors_unique)]
-    colors_unique <- colors_unique[!(colors_unique %in% "background")]
-    rimg <- matrix(rimg) #%>% raster::t() #%>% base::t()
-    for(color_i in colors_unique){
-      rimg[rimg %in% colors_df$hex[colors_df$color %in% color_i]] <- color_i
+    if(traffic_color_dist_thresh == 0){
+
+      r[] <- NA
+      r[rimg %in% "#63D668FF"] <- 1
+      r[rimg %in% "#FF974DFF"] <- 2
+      r[rimg %in% "#F23C32FF"] <- 3
+      r[rimg %in% "#811F1FFF"] <- 4
+
+    } else {
+
+      ## Color Values
+      color_df <- rimg[] %>% 
+        unique() %>% 
+        as.data.frame() %>%
+        dplyr::rename(hex = ".") %>%
+        dplyr::mutate(hex_noff = str_replace_all(.data$hex, "FF$", ""))
+
+      lab_df <- color_df$hex_noff %>% 
+        schemr::hex_to_lab()
+
+      color_df <- bind_cols(color_df,
+                            lab_df)
+
+      ## Distance
+      color_df$dist_1 <- ColorNameR::colordiff(color_df[,c("l", "a", "b")],
+                                               as.matrix(schemr::hex_to_lab("#63D668")),
+                                               metric = traffic_color_dist_metric)
+
+      color_df$dist_2 <- ColorNameR::colordiff(color_df[,c("l", "a", "b")],
+                                               as.matrix(schemr::hex_to_lab("#FF974D")),
+                                               metric = traffic_color_dist_metric)
+
+      color_df$dist_3 <- ColorNameR::colordiff(color_df[,c("l", "a", "b")],
+                                               as.matrix(schemr::hex_to_lab("#F23C32")),
+                                               metric = traffic_color_dist_metric)
+
+      color_df$dist_4 <- ColorNameR::colordiff(color_df[,c("l", "a", "b")],
+                                               as.matrix(schemr::hex_to_lab("#811F1F")),
+                                               metric = traffic_color_dist_metric)
+
+      ## Assign traffic levels
+      color_df <- color_df %>%
+        dplyr::mutate(traffic = case_when(
+          dist_1 <= traffic_color_dist_thresh ~ 1,
+          dist_2 <= traffic_color_dist_thresh ~ 2,
+          dist_3 <= traffic_color_dist_thresh ~ 3,
+          dist_4 <= traffic_color_dist_thresh ~ 4
+        )) 
+
+      r[] <- NA
+      r[rimg %in% color_df$hex[color_df$traffic %in% 1]] <- 1
+      r[rimg %in% color_df$hex[color_df$traffic %in% 2]] <- 2
+      r[rimg %in% color_df$hex[color_df$traffic %in% 3]] <- 3
+      r[rimg %in% color_df$hex[color_df$traffic %in% 4]] <- 4
     }
 
-    r[] <- NA
-    r[rimg %in% "green"]    <- 1
-    r[rimg %in% "orange"]   <- 2
-    r[rimg %in% "red"]      <- 3
-    r[rimg %in% "dark-red"] <- 4
-
-    ## Spatially define raster
+    #### Spatially define raster
     ext_4326 <- gt_make_extent(latitude = latitude,
                                longitude = longitude,
                                height = height,

diff --git a/R/gt_make_extent.R b/R/gt_make_extent.R
@@ -63,7 +63,7 @@ gt_make_extent <- function(latitude,
   mapWidth  <- 256
   mapHeight <- 256
   xScale    <- (2^zoom) / (width/mapWidth)
-  yScale    <- (2^zoom) / (height/mapWidth)
+  yScale    <- (2^zoom) / (height/mapHeight)
 
   corners      <- getImageBounds(mapWidth, mapHeight, xScale, yScale, latitude, longitude)
   point_left   <- corners[2]

diff --git a/R/gt_make_grid.R b/R/gt_make_grid.R
@@ -5,7 +5,7 @@
 #' Creates a grid of sf polygons, where traffic data for each polygon can then be queried using [gt_make_raster_from_grid()]. 
 #'
 #' @param polygon Polygon (`sf` object or `SpatialPolygonsDataframe`) in WGS84 CRS the defines region to be queried.
-#' @param zoom Zoom level; integer from 0 to 20. For more information about how zoom levels correspond to pixel size, see [here](https://wiki.openstreetmap.org/wiki/Zoom_levels)
+#' @param zoom Zoom level; integer from 5 to 20. For more information about how zoom levels correspond to pixel size, see [here](https://wiki.openstreetmap.org/wiki/Zoom_levels) and [here](https://developers.google.com/maps/documentation/javascript/overview#zoom-levels).
 #' @param height_width_max Maximum pixel height and width to check using for each grid (pixel length depends on zoom). If the same number of grids can be made with a smaller height/width, the function will use a smaller height/width. If `height` and `width` are specified, that height and width will be used and `height_width_max` will be ignored. (Default: `2000`) 
 #' @param height Height, in pixels, for each grid (pixel length depends on zoom). Enter a `height` to manually specify the height; otherwise, a height of `height_width_max` or smaller will be used.
 #' @param width Pixel, in pixels, for each grid (pixel length depends on zoom). Enter a `width` to manually specify the width; otherwise, a width of `height_width_max` or smaller will be used.

diff --git a/R/gt_make_html.R b/R/gt_make_html.R
@@ -8,7 +8,7 @@
 # @param location Vector of latitude and longitude
 # @param height Height (in pixels; pixel length depends on zoom)
 # @param width Width (in pixels; pixel length depends on zoom)
-# @param zoom Zoom level; integer from 0 to 20. For more information about how zoom levels correspond to pixel size, see [here](https://wiki.openstreetmap.org/wiki/Zoom_levels)
+# @param zoom Zoom level; integer from 5 to 20. For more information about how zoom levels correspond to pixel size, see [here](https://wiki.openstreetmap.org/wiki/Zoom_levels)
 # @param filename Path and filename to save file
 # @param google_key Google API key
 #