---
title: "Pre-Defined HCL Palettes"
---

### Description

Function to retrieve and/or display pre-defined color palettes based on the
HCL (Hue-Chroma-Luminance) color model, excludes 'diverging xtra'
(see [divergingx_palettes](colorspace.hcl_palettes.divergingx_palettes.qmd)).

The inputs `type_` and `name` can be used to retrieve a custom subset,
`custom` can be used to add custom palettes if if needed.

If `plot = True`, `**kwargs` can be used to specify the figure size of the resulting
image by specifying `figsize = (height, width)` where both, `height`
and `width` must be int/float, specifying the height and width in inches.
Note that `matplotlib` must be installed when `plot = True`.

### Usage

<pre><code class='language-python'>hcl_palettes(n=5, type_=None, name=None, plot=False,<br/>             custom=None, ncol=4, **kwargs)</code></pre>

### Arguments

<dl class="pyp-list param-list">
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.hcl_palettes.hcl_palettes:n">n</code><code class="argument-class">int</code>
  </dt>
 <dd>The number of colors to be plotted, defaults to `7`.
Only used if `plot = True`.</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.hcl_palettes.hcl_palettes:type_">type_</code><code class="argument-class">None, str, list</code>
  </dt>
 <dd>Given a str or a list of str,
only a subset of all available default color maps will
returned/displayed. Can be used in combination with input argument
`name`. Uses partial matching, not case sensitive.</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.hcl_palettes.hcl_palettes:name">name</code><code class="argument-class">None, str, list</code>
  </dt>
 <dd>Similar to `type_`. If not specified
all palettes will be returned. Can be set to a str or a list of
str containing the names of the palettes which should be
returned/plotted.</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.hcl_palettes.hcl_palettes:plot">plot</code><code class="argument-class">bool</code>
  </dt>
 <dd>If `False` (default) an object of type
[hclpalettes](colorspace.palettes.hclpalettes.qmd) is returned, containing the
(subset) of pre-defined HCL color palettes.</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.hcl_palettes.hcl_palettes:custom">custom</code><code class="argument-class">defaultpalette</code>
  </dt>
 <dd>One or multiple
defaultpalettes can be provided in addition.</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.hcl_palettes.hcl_palettes:ncol">ncol</code><code class="argument-class">int</code>
  </dt>
 <dd>Positive int, number of columns, defaults to `4`.</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.hcl_palettes.hcl_palettes:**kwargs">**kwargs</code>
  </dt>
 <dd>Forwarded to the main
[swatchplot](colorspace.swatchplot.swatchplot.qmd) 
function if `plot = True`.</dd>
</dl>

### Return

Object of type `hclpalettes` or a `matplotlib.figure.Figure` object. If `plot = True`
a plot will be created and the figure handler returned. If `plot = False` (default)
an object of class [hclpalettes](colorspace.palettes.hclpalettes.qmd) is returned.

### Examples

```{python}
#| echo: true
#| warning: true
#| error: true
## Basic usage:

from colorspace import hcl_palettes
# Get all pre-defined HCL palettes shipped with the package
hcl_palettes()
```

```{python}
#| echo: true
#| warning: true
#| error: true
# Get all diverging HCL palettes (basic and advanced)
hcl_palettes(type_ = "Diverging")
```

```{python}
#| echo: true
#| warning: true
#| error: true
# Get only basic diverging HCL palettes
hcl_palettes(type_ = "Basic: Diverging")
```

```{python}
#| echo: true
#| warning: true
#| error: true
# Get specific HCL palettes by name
hcl_palettes(name = ["Oranges", "Tropic"]) 
```

```{python}
#| echo: true
#| warning: true
#| error: true
# Visualize all diverging HCL palettes
hcl_palettes(type_ = "Diverging", ncol = 2,
             plot = True, figsize = (6, 4));
```

```{python}
#| echo: true
#| warning: true
#| error: true
# Visualize specific palettes selected by name
hcl_palettes(name = ["Oranges", "Tropic"],
             plot = True, ncol = 1, figsize = (6, 2));
```

```{python}
#| echo: true
#| warning: true
#| error: true
# Specify number of colors shown
hcl_palettes(n = 5,  type_ = "Basic: Diverging",
             plot = True, ncol = 1, figsize = (6, 3));
```

```{python}
#| echo: true
#| warning: true
#| error: true
hcl_palettes(n = 51, type_ = "Advanced: Diverging",
             plot = True, ncol = 1, figsize = (6, 8));
```

```{python}
#| echo: true
#| warning: true
#| error: true
# Extract specific palettes after loading
palettes = hcl_palettes()
c1 = palettes.get_palette("Oranges")
c1
```

```{python}
#| echo: true
#| warning: true
#| error: true
c2 = palettes.get_palette("Greens")
c2
```

```{python}
#| echo: true
#| warning: true
#| error: true
# Modify palettes by overwriting palette settings
c1.set(h1 = 99, l2 = 30, l1 = 30)
c1.rename("Custom Palette #1")
c2.set(h1 = -30, l1 = 40, l2 = 30, c1 = 30, c2 = 40)
c2.rename("Custom Palette #2")

# Visualize customized palettes
hcl_palettes(type_ = "Custom", custom = [c1, c2],
             plot = True, ncol = 1, figsize = (6, 1));
```




### Raises

<ul class="python-raises">
<li><code class="text-warning">TypeError</code>: If `n`/`ncol` not of type int.
<li><code class="text-warning">TypeError</code>: If `type_` is not None or str.
<li><code class="text-warning">TypeError</code>: If not is bool `plot`.
<li><code class="text-warning">TypeError</code>: In case `custom` is an invalid input.
<li><code class="text-warning">ValueError</code>: If `n` or `ncol` are not positive.
<li><code class="text-warning">Exception</code>: If no palettes can be found matching the `type_` argument.
</ul>

