---
title: "Qualitative 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.

`qualitative_hcl` distinguishes the underlying categories by a
sequence of hues while keeping both chroma and luminance constant to give
each color in the resulting palette the same perceptual weight. Thus, `h`
should be a pair of hues (or equivalently `h1` and `h2` can be used) with
the starting and ending hue of the palette. Then, an equidistant sequence
between these hues is employed, by default spanning the full color wheel
(i.e, the full 360 degrees). Chroma `c` (or equivalently `c1`) and
luminance `l` (or equivalently `l1`) are constants. 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. 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, `qualitative_hcl` returns an object of class `hclpalette` which
allows to draw a number of colors (`n`) uniformly distributed around the
circle (`[0, 360 * (n - 1) / n]`) controlled via the `h` (Hue) argument. As
the number of colors is not yet defined, the upper hue limit (`h[1]`, `h2`)
is defined via lambda function.

See also: [sequential_hcl](colorspace.palettes.sequential_hcl.qmd), [diverging_hcl](colorspace.palettes.diverging_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'>qualitative_hcl(h=[0, &lt;function qualitative_hcl.&lt;lambda&gt;&gt;],<br/>                c=80, l=60, fixup=True,<br/>                palette=None, rev=False, **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.qualitative_hcl:h">h</code><code class="argument-class">list, str</code>
  </dt>
 <dd>Hue values defining the 'color' or name of pre-defined
palette (`str`) or a list of two numeric values (float/int) defining
the hue on the two ends of the palette. If str, it acts as the
input argument `palette`.
Elements in list can also be lambda functions with one single input
argument `n` (number of colors; see default value).</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.qualitative_hcl:c">c</code><code class="argument-class">int, float</code>
  </dt>
 <dd>Chroma value (colorfullness), a single numeric value.</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.qualitative_hcl:l">l</code><code class="argument-class">int, float</code>
  </dt>
 <dd>luminance value (lightness), a single numeric value.</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.qualitative_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.qualitative_hcl:palette">palette</code><code class="argument-class">None, str</code>
  </dt>
 <dd>Can be used to load a default diverging color
qpalette 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
qthe color palette.</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.qualitative_hcl:rev">rev</code><code class="argument-class">bool</code>
  </dt>
 <dd>Should the color map be reversed? Default `False`.</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.qualitative_hcl:**kwargs">**kwargs</code>
  </dt>
 <dd>Additional named arguments to overwrite the palette settings.
Allowed: `h1`, `h2`, `c1`, `l1`.</dd>
</dl>

### Return

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


### Examples

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

```{python}
#| echo: true
#| warning: true
#| error: true
b = qualitative_hcl("Warm")
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
qualitative_hcl("Warm")(10)
```

```{python}
#| echo: true
#| warning: true
#| error: true
# Example where `h` is a list of two lambda functions
from colorspace import hexcols
pal = qualitative_hcl([lambda n: 100. * (n - 1) / n,  
                       lambda n, h1: 300. * (n - 1) / n + h1], c = 30)
cols = hexcols(pal.colors(5))
cols
```

```{python}
#| echo: true
#| warning: true
#| error: true
cols.to("HCL")
cols
```




### Raises

<ul class="python-raises">
<li><code class="text-warning">TypeError</code>: If `h` is neither str nor list of length 2.
<li><code class="text-warning">TypeError</code>: If `h` is list of length 2, the elements must be int, float, or
lambda functions.
<li><code class="text-warning">ValueError</code>: If `c` and/or `l` contain unexpected values.
<li><code class="text-warning">ValueError</code>: If `h` is str or `palette` is set, but a pre-defined palette
with this name does not exist.
</ul>

