Package 'earthtones'

Title: Derive a Color Palette from a Particular Location on Earth
Description: Downloads a satellite image via ESRI and maptiles (these are originally from a variety of aerial photography sources), translates the image into a perceptually uniform color space, runs one of a few different clustering algorithms on the colors in the image searching for a user-supplied number of colors, and returns the resulting color palette.
Authors: Will Cornwell [aut, cre] (ORCID: <https://orcid.org/0000-0003-4080-4073>), Mitch Lyons [aut], Nick Murray [aut]
Maintainer: Will Cornwell <[email protected]>
License: MIT + file LICENSE
Version: 0.2.1
Built: 2026-05-25 06:51:31 UTC
Source: https://github.com/traitecoevo/earthtones

Help Index

Extract Color Palettes from Satellite Imagery

Description

Download a satellite image from a selected provider, extract dominant colors, and generate an earth-tone palette.

Usage

get_earthtones(
  latitude = 50.759,
  longitude = -125.673,
  zoom = 11,
  number_of_colors = 3,
  method = "pam",
  sample_rate = 500,
  include_map = TRUE,
  provider = "Esri.WorldImagery",
  ...
)

Arguments

latitude

Numeric. Latitude coordinate for the center of the satellite image.
longitude

Numeric. Longitude coordinate for the center of the satellite image.
zoom

Numeric. Zoom level between 0 (whole world) and 13 (high detail). Higher values zoom in closer.
number_of_colors

Numeric. Number of dominant colors to extract.
method

Character. Clustering method to identify dominant colors. Options are "kmeans" (kmeans) or "pam" (pam - partitioning around medoids).
sample_rate

Numeric. Subsampling factor; higher values reduce computation by sampling fewer pixels.
include_map

Logical. If TRUE, returns both the color palette and the satellite image raster. If FALSE, returns only the color palette.
provider

Character. Tile provider for satellite imagery. Currently supports "Esri.WorldImagery".
...

Additional arguments passed to internal functions (currently unused).

Details

The function retrieves satellite imagery from the specified provider, extracts colors by converting the imagery into a perceptually uniform color space, and applies a clustering algorithm to determine dominant colors. Zoom level and location significantly influence the palette generated.

Value

An object of class "palette" if include_map = TRUE, containing:

  • pal: A vector of hexadecimal color codes representing the dominant colors.

  • map: A raster image object of the satellite imagery.

If include_map = FALSE, returns a vector of hexadecimal color codes.

See Also

get_tiles, kmeans, pam

Examples

## Not run: 
# Get a palette for a location in the Bahamas
get_earthtones(latitude = 24.2, longitude = -77.88, zoom = 11, number_of_colors = 5)

# Return palette only, without map
get_earthtones(latitude = 24.2, longitude = -77.88,
               zoom = 11, number_of_colors = 5, include_map = FALSE)

## End(Not run)

Print Method for Palette Objects

Description

Visualizes the palette and associated satellite image.

Usage

## S3 method for class 'palette'
print(x, ...)

Arguments

x

An object of class "palette".
...

Additional arguments passed to plotting methods.

Value

No return value; called for its side effect of plotting.