---
title: "Diverging HCL Color Palettes"
---

### Description

The HCL (hue-chroma-luminance) color model is a perceptual color model
obtained by using polar coordinates in CIELUV space
(i.e., [polarLUV](colorspace.colorlib.polarLUV.qmd)),
where steps of equal size correspond to approximately equal perceptual
changes in color. By taking polar coordinates the resulting three
dimensions capture the three perceptual axes very well: hue is the type of
color, chroma the colorfulness compared to the corresponding gray, and
luminance the brightness. This makes it relatively easy to create balanced
palettes through trajectories in this HCL space. In contrast, in the more
commonly-used ‘HSV’ (hue-saturation-value) model (a simple transformation
of ‘RGB’), the three axes are confounded so that luminance changes along
with the hue leading to very unbalanced palettes.

`diverging_hcl` codes the underlying numeric values by a
triangular luminance sequence with different hues in the left and
in the right arm of the palette. Thus, it can be seen as a
combination of two sequential palettes with some restrictions: (a)
a single hue is used for each arm of the palette, (b) chroma and
luminance trajectory are balanced between the two arms, (c) the
neutral central value has zero chroma. To specify such a palette a
vector of two hues `h` (or equivalently `h1` and `h2`), either a
single chroma value `c` (or `c1`) or a vector of two chroma values
`c` (or `c1` and `cmax`), a vector of two luminances `l` (or `l1`
and `l2`), and power parameter(s) `power` (or `p1` and `p2`) are
used. For more flexible diverging palettes without the
restrictrictions above (and consequently more parameters)
`divergingx_hcl` is available. For backward compatibility,
`diverge_hcl` is a copy of `diverging_hcl`.

If `h` is str it will overwrite the `palette` argument. In this case,
pre-specified palette settings will be loaded but are allowed to be
overwritten by the user. At any time the user can overwrite any of the
settings. By default, `diverging_hcl` returns an object of class
`hclpalette` identical to the pre-defined `"Blue-Red"` palette.

See also: [qualitative_hcl](colorspace.palettes.qualitative_hcl.qmd), [sequential_hcl](colorspace.palettes.sequential_hcl.qmd),
[divergingx_hcl](colorspace.palettes.divergingx_hcl.qmd), [rainbow_hcl](colorspace.palettes.rainbow_hcl.qmd), [heat_hcl](colorspace.palettes.heat_hcl.qmd),
[terrain_hcl](colorspace.palettes.terrain_hcl.qmd), [diverging_hsv](colorspace.palettes.diverging_hsv.qmd), and
[rainbow](colorspace.palettes.rainbow.qmd).

### Usage

<pre><code class='language-python'>diverging_hcl(h=[260, 0], c=80, l=[30, 90],<br/>              power=1.5, fixup=True, palette=None,<br/>              rev=False, *args, **kwargs)</code></pre>

### Arguments

<dl class="pyp-list param-list">
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.diverging_hcl:h">h</code><code class="argument-class">list, float, int</code>
  </dt>
 <dd>Hue values (color), diverging color palettes should
have different hues for both ends of the palette. If only one value is
present it will be recycled ending up in a diverging color palette with the
same colors on both ends.  If more than two values are provided the first
two will be used while the rest is ignored.  If input `h` is a str
this argument acts like the `palette` argument (see `palette` input
parameter).</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.diverging_hcl:c">c</code><code class="argument-class">float, int, list</code>
  </dt>
 <dd>Chroma value (colorfullness), a single numeric value. If two
values are provided the first will be taken as `c1`, the second as `cmax`.</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.diverging_hcl:l">l</code><code class="argument-class">float, int, list</code>
  </dt>
 <dd>luminance values (lightness). The first value is for
the two ends of the color palette, the second one for the neutral center
point. If only one value is given this value will be recycled.</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.diverging_hcl:power">power</code><code class="argument-class">float, int, list</code>
  </dt>
 <dd>Power parameter for non-linear behaviour of the color
palette.</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.diverging_hcl:fixup">fixup</code><code class="argument-class">bool</code>
  </dt>
 <dd>Only used when converting the HCL colors to hex.  Should RGB
values outside the defined RGB color space be corrected?</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.diverging_hcl:palette">palette</code><code class="argument-class">str</code>
  </dt>
 <dd>Can be used to load a default diverging color palette
specification. If the palette does not exist an exception will be raised.
Else the settings of the palette as defined will be used to create the
color palette.</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.diverging_hcl:rev">rev</code><code class="argument-class">bool</code>
  </dt>
 <dd>Should the color map be reversed.</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.diverging_hcl:*args">*args</code>
  </dt>
 <dd>Currently unused.</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.diverging_hcl:**kwargs">**kwargs</code>
  </dt>
 <dd>Additional named arguments to overwrite the palette settings.
Allowed: `h1`, `h2`, `c1`, `cmax`, `l1`, `l2`, `p1`, `p2`.</dd>
</dl>

### Return

Initialize new object, no return. Raises a set of errors if the parameters
are misspecified. Note that the object is callable, the default object call
can be used to return hex colors (identical to the `.colors()` method),
see examples.

### Methods

<dl class="pyp-list method-list">
    <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
       <code>[diverging_hcl.cmap(n=256, name=&#x27;custom_hcl_cmap&#x27;)](colorspace.palettes.diverging_hcl.cmap.qmd)</code>
    </dt>
    <dd>Create Matplotlib Compatible Color Map</dd>
    <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
       <code>[diverging_hcl.colors(n=11, fixup=None, alpha=None, **kwargs)](colorspace.palettes.diverging_hcl.colors.qmd)</code>
    </dt>
    <dd>Get Colors</dd>
    <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
       <code>[diverging_hcl.get(key)](colorspace.palettes.diverging_hcl.get.qmd)</code>
    </dt>
    <dd>Get Specific Palette Setting</dd>
    <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
       <code>[diverging_hcl.hclplot(n=7, **kwargs)](colorspace.palettes.diverging_hcl.hclplot.qmd)</code>
    </dt>
    <dd>Palette Plot in HCL Space</dd>
    <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
       <code>[diverging_hcl.name()](colorspace.palettes.diverging_hcl.name.qmd)</code>
    </dt>
    <dd>Get Palette Name</dd>
    <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
       <code>[diverging_hcl.show_settings()](colorspace.palettes.diverging_hcl.show_settings.qmd)</code>
    </dt>
    <dd>Show Palette Settings</dd>
    <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
       <code>[diverging_hcl.specplot(n=180, *args, **kwargs)](colorspace.palettes.diverging_hcl.specplot.qmd)</code>
    </dt>
    <dd>Color Spectrum Plot</dd>
    <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
       <code>[diverging_hcl.swatchplot(n=7, **kwargs)](colorspace.palettes.diverging_hcl.swatchplot.qmd)</code>
    </dt>
    <dd>Palette Swatch Plot</dd>
</dl>


### Examples

```{python}
#| echo: true
#| warning: true
#| error: true
from colorspace import diverging_hcl
a = diverging_hcl()
a.colors(10)
```

```{python}
#| echo: true
#| warning: true
#| error: true
# Different color palette by name
b = diverging_hcl("Tropic")
b.colors(10)
```

```{python}
#| echo: true
#| warning: true
#| error: true
b.swatchplot(show_names = False, figsize = (5.5, 0.5));
```

```{python}
#| echo: true
#| warning: true
#| error: true
# The standard call of the object also returns hex colors
diverging_hcl("Tropic")(10)
```



