Implementation of the gradient palettes presented in https://leahsmyth.github.io/Princess-Colour-Schemes/index.html. Three scales are provided:

`scale_*_princess_d()`

: For discrete values.`scale_*_princess_c()`

: For continuous values.`scale_*_princess_b()`

: For binning continuous values.

Additionally, a color palette `princess.colors()`

is provided. See also
`grDevices::terrain.colors()`

for details.

Additional parameters `...`

would be passed on to:

Discrete values:

`ggplot2::discrete_scale()`

.Continuous values:

`ggplot2::continuous_scale()`

.Binned continuous values:

`ggplot2::binned_scale()`

.

**Note that** tidyterra just documents a selection of these
additional parameters, check the ggplot2 functions listed above to
see the full range of parameters accepted by these scales.

## Usage

```
scale_fill_princess_d(
palette = "snow",
...,
alpha = 1,
direction = 1,
na.translate = FALSE,
drop = TRUE
)
scale_colour_princess_d(
palette = "snow",
...,
alpha = 1,
direction = 1,
na.translate = FALSE,
drop = TRUE
)
scale_fill_princess_c(
palette = "snow",
...,
alpha = 1,
direction = 1,
na.value = "transparent",
guide = "colourbar"
)
scale_colour_princess_c(
palette = "snow",
...,
alpha = 1,
direction = 1,
na.value = "transparent",
guide = "colourbar"
)
scale_fill_princess_b(
palette = "snow",
...,
alpha = 1,
direction = 1,
na.value = "transparent",
guide = "coloursteps"
)
scale_colour_princess_b(
palette = "snow",
...,
alpha = 1,
direction = 1,
na.value = "transparent",
guide = "coloursteps"
)
princess.colors(n, palette = "snow", alpha = 1, rev = FALSE)
```

## Arguments

- palette
A valid palette name. The name is matched to the list of available palettes, ignoring upper vs. lower case. Values available are:

`"snow"`

,`"ella"`

,`"bell"`

,`"aura"`

,`"denmark"`

,`"france"`

,`"arabia"`

,`"america"`

,`"asia"`

,`"neworleans"`

,`"punz"`

,`"scotland"`

,`"cold"`

,`"norge"`

,`"maori"`

.- ...
Arguments passed on to

`ggplot2::discrete_scale`

,`ggplot2::continuous_scale`

,`ggplot2::binned_scale`

`breaks`

One of:

`labels`

One of:

`NULL`

for no labels`waiver()`

for the default labels computed by the transformation objectA character vector giving labels (must be same length as

`breaks`

)An expression vector (must be the same length as breaks). See ?plotmath for details.

A function that takes the breaks as input and returns labels as output. Also accepts rlang lambda function notation.

`limits`

One of:

`NULL`

to use the default scale valuesA character vector that defines possible values of the scale and their order

A function that accepts the existing (automatic) values and returns new ones. Also accepts rlang lambda function notation.

`expand`

For position scales, a vector of range expansion constants used to add some padding around the data to ensure that they are placed some distance away from the axes. Use the convenience function

`expansion()`

to generate the values for the`expand`

argument. The defaults are to expand the scale by 5% on each side for continuous variables, and by 0.6 units on each side for discrete variables.`minor_breaks`

One of:

`NULL`

for no minor breaks`waiver()`

for the default breaks (one minor break between each major break)A numeric vector of positions

A function that given the limits returns a vector of minor breaks. Also accepts rlang lambda function notation. When the function has two arguments, it will be given the limits and major breaks.

`n.breaks`

An integer guiding the number of major breaks. The algorithm may choose a slightly different number to ensure nice break labels. Will only have an effect if

`breaks = waiver()`

. Use`NULL`

to use the default number of breaks given by the transformation.`nice.breaks`

Logical. Should breaks be attempted placed at nice values instead of exactly evenly spaced between the limits. If

`TRUE`

(default) the scale will ask the transformation object to create breaks, and this may result in a different number of breaks than requested. Ignored if breaks are given explicitly.

- alpha
The alpha transparency, a number in [0,1], see argument alpha in

`hsv`

.- direction
Sets the order of colors in the scale. If 1, the default, colors are ordered from darkest to lightest. If -1, the order of colors is reversed.

- na.translate
Should

`NA`

values be removed from the legend? Default is`TRUE`

.- drop
Should unused factor levels be omitted from the scale? The default (

`TRUE`

) removes unused factors.- na.value
Missing values will be replaced with this value. By default, tidyterra uses

`na.value = "transparent"`

so cells with`NA`

are not filled. See also #120.- guide
A function used to create a guide or its name. See

`guides()`

for more information.- n
the number of colors (\(\ge 1\)) to be in the palette.

- rev
logical indicating whether the ordering of the colors should be reversed.

## Value

The corresponding ggplot2 layer with the values applied to the
`fill/colour`

aesthetics.

## See also

`terra::plot()`

, `ggplot2::scale_fill_viridis_c()`

See also ggplot2 docs on additional `...`

parameters.

Other gradient scales and palettes for hypsometry:
`scale_color_coltab()`

,
`scale_cross_blended`

,
`scale_grass`

,
`scale_hypso`

,
`scale_terrain`

,
`scale_whitebox`

## Examples

```
# \donttest{
filepath <- system.file("extdata/volcano2.tif", package = "tidyterra")
library(terra)
volcano2_rast <- rast(filepath)
# Palette
plot(volcano2_rast, col = princess.colors(100))
library(ggplot2)
ggplot() +
geom_spatraster(data = volcano2_rast) +
scale_fill_princess_c()
# Binned
ggplot() +
geom_spatraster(data = volcano2_rast) +
scale_fill_princess_b(breaks = seq(70, 200, 10), palette = "denmark")
# With discrete values
factor <- volcano2_rast %>% mutate(cats = cut(elevation,
breaks = c(100, 120, 130, 150, 170, 200),
labels = c(
"Very Low", "Low", "Average", "High",
"Very High"
)
))
ggplot() +
geom_spatraster(data = factor, aes(fill = cats)) +
scale_fill_princess_d(na.value = "gray10", palette = "maori")
# }
# Display all the princess palettes
pals <- unique(princess_db$pal)
# Helper fun for plotting
ncols <- 128
rowcol <- grDevices::n2mfrow(length(pals))
opar <- par(no.readonly = TRUE)
par(mfrow = rowcol, mar = rep(1, 4))
for (i in pals) {
image(
x = seq(1, ncols), y = 1, z = as.matrix(seq(1, ncols)),
col = princess.colors(ncols, i), main = i,
ylab = "", xaxt = "n", yaxt = "n", bty = "n"
)
}
par(opar)
```