---
title: "earthtones"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{earthtones}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

```{r setup, include=FALSE,message=FALSE,warning=FALSE}
library("earthtones")
requireNamespace("ggplot2", quietly = TRUE)
```

## Find the color pallette of particular parts of the world

This package does a few simple things: 
1. downloads an image from google earth, which in turn comes from a variety of sources, sometimes they are aerial photos.
2. translates the colors in the image into a perceptually uniform color space
3. runs a clustering method on the pixels in that color space
4. returns a color palette.  

There is only one function `get_earthtones`.  Here is how you use it, in this case for the grand canyon:

```{r grand canyon,message=FALSE,dpi=300}
get_earthtones(latitude = 36.094994, longitude=-111.837962, 
               zoom=12, number_of_colors=8)
```

`number_of_colors` corresponds to how many colors you want back.  The `zoom` value is passed to `ggmap::get_map`--essentially larger values zoom closer to the target lat+long.  

Maybe desert colors aren't your thing: you want a color scheme drawn from tropical reefs and lagoons.  How about the Bahamas?

```{r bahamas,message=FALSE,dpi=300}
get_earthtones(latitude = 24.2, longitude=-77.88, zoom=11, number_of_colors=5)
```

Just pick your favorite place in the world, and find out the major colors

Here is San Francisco:

```{r sf,message=FALSE,dpi=300}
get_earthtones(latitude = 37.89, longitude=-122.28, zoom=11, number_of_colors=12)
```

or the golden gate bridge:

```{r ggb,message=FALSE,dpi=300}
get_earthtones(latitude = 37.81391, longitude=-122.478289, zoom=19, number_of_colors=12)
```

or Sydney Opera House :

```{r opera,message=FALSE,dpi=300}
get_earthtones(latitude = -33.857077, longitude=151.214722, zoom=17, number_of_colors=12)
```


If you want to actually use the color scheme for graphing or something and not just plot pretty pictures, there is a switch in the `get_earthtones` function: just add `include.map=FALSE` to the function call, and the function will only return the color palette for later use:

```{r bahama_iris,message=FALSE,dpi=100}
require(ggplot2)
bahamas_colors <- get_earthtones(latitude = 24.2,
      longitude=-77.88, zoom=11, number_of_colors=3,include.map=FALSE)
ggplot2::ggplot(iris, aes(x=Petal.Length, y=Petal.Width, col=Species))+
  geom_point(size = 2)+
  scale_color_manual(values = bahamas_colors)+
  theme_bw()
```

And now Fisher's irises are colored in a Bahama style.  However, data from two of the three iris species was actually collected by a botanist named Edgar Anderson from the [Gaspé Peninsula in Quebec](https://www.jstor.org/stable/2394164?seq=1#page_scan_tab_contents), so it might be better to use a color scheme from there for those two species.  

```{R gaspe,message=FALSE,dpi=100}
iris.from.gaspe <- subset(iris, iris$Species!="virginica")

get_earthtones(latitude = 48.7709,
  longitude=-64.660939,zoom=9,number_of_colors = 2)
gaspe <- get_earthtones(latitude = 48.7709,
  longitude=-64.660939 ,zoom=9, number_of_colors = 2,include.map=FALSE)
ggplot2::ggplot(iris.from.gaspe, aes(x=Petal.Length, y=Petal.Width,col=Species))+
  geom_point(size = 2)+
  scale_color_manual(values = gaspe)+
  theme_bw()
```

## Some notes on clustering methods

There are lots of ways to do the clustering of the colors.  The default is partitioning around medoid (PAM) algorithm but there is also the k-means, which is a bit simpler.

Here is the k-means result for the Bahamas:

```{r bahamas_kmeans,message=FALSE,dpi=300}
get_earthtones(latitude = 24.2, longitude=-77.88,
               zoom=11, number_of_colors=5, method="kmeans")
```

and here is the PAM one:

```{r bahamas_pam,message=FALSE,dpi=300}
get_earthtones(latitude = 24.2, longitude=-77.88, 
               zoom=11, number_of_colors=5, method="pam")
```

The sand-color is perhaps a bit sandier with the PAM approach.  This actually makes sense because the PAM method returns medoids rather than centroids so the outputs are guaranteed to be actual colors in the image.  For the k-means method the mean of the colors may actually be a color that is not itself present in the image.  

## Inspiration

There are some other cool things to do with the cool and images in the [RImagePallette package](https://github.com/joelcarlson/RImagePalette).  And there is a very cool blog on [the colors of Antartica](https://havecamerawilltravel.com/colors-antarctica/).  And of course if you want a quirky cinematic color scheme, check out [wesanderson](https://github.com/karthik/wesanderson).