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

By default, `sequential_hcl` returns an object of class `hclpalette`
identical to the pre-defined `"Blues 2"` palette.

`h1` and `h2` both allow for lambda functions to create uniformly distributed
hues around the (full) circle (360 degrees).

* `h1`: can be a lambda function with one single argument `n` (number of colors).
* `h2`: can be a lambda function with one or two arguments. If only one, `n`
    (number of colors) will be handed over when evaluated. If two, the first
    one is expected to be `n` (number of colors), as second argument the
    value `h1` will be used.

See also: [qualitative_hcl](colorspace.palettes.qualitative_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'>sequential_hcl(h=260, c=80, l=[30, 90], power=1.5,<br/>               fixup=True, palette=None, rev=False,<br/>               *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.sequential_hcl:h">h</code><code class="argument-class">float, int, list, str</code>
  </dt>
 <dd>Hue values (color). If only one value is given the value
is recycled which yields a single-hue sequential color palette.  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.sequential_hcl:c">c</code><code class="argument-class">float, int, list</code>
  </dt>
 <dd>Chroma values (colorfullness), int or float
(linear to zero), list of two numerics (linear in interval), =
or three numerics (advanced; `[c1, cmax, c2]`).</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.sequential_hcl:l">l</code><code class="argument-class">float, int, list</code>
  </dt>
 <dd>Luminance values (luminance). If float or int,
the element will be recycled, or a list of two numerics
(defining `[l1, l2]`).</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.sequential_hcl:power">power</code><code class="argument-class">float, int, list</code>
  </dt>
 <dd>Power parameter for non-linear behaviour
of the color palette. Single float or int, or a list of numerics
(defining `[p1, p2]`).</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.sequential_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.sequential_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.sequential_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.sequential_hcl:*args">*args</code>
  </dt>
 <dd>Currently unused.</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.sequential_hcl:**kwargs">**kwargs</code>
  </dt>
 <dd>Additional named arguments to overwrite the palette settings.
Allowed: `h1`, `h2`, `c1`, `c2`, `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>[sequential_hcl.cmap(n=256, name=&#x27;custom_hcl_cmap&#x27;)](colorspace.palettes.sequential_hcl.cmap.qmd)</code>
    </dt>
    <dd>Create Matplotlib Compatible Color Map</dd>
    <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
       <code>[sequential_hcl.colors(n=11, fixup=None, alpha=None, **kwargs)](colorspace.palettes.sequential_hcl.colors.qmd)</code>
    </dt>
    <dd>Get Colors</dd>
    <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
       <code>[sequential_hcl.get(key)](colorspace.palettes.sequential_hcl.get.qmd)</code>
    </dt>
    <dd>Get Specific Palette Setting</dd>
    <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
       <code>[sequential_hcl.hclplot(n=7, **kwargs)](colorspace.palettes.sequential_hcl.hclplot.qmd)</code>
    </dt>
    <dd>Palette Plot in HCL Space</dd>
    <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
       <code>[sequential_hcl.name()](colorspace.palettes.sequential_hcl.name.qmd)</code>
    </dt>
    <dd>Get Palette Name</dd>
    <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
       <code>[sequential_hcl.show_settings()](colorspace.palettes.sequential_hcl.show_settings.qmd)</code>
    </dt>
    <dd>Show Palette Settings</dd>
    <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
       <code>[sequential_hcl.specplot(n=180, *args, **kwargs)](colorspace.palettes.sequential_hcl.specplot.qmd)</code>
    </dt>
    <dd>Color Spectrum Plot</dd>
    <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
       <code>[sequential_hcl.swatchplot(n=7, **kwargs)](colorspace.palettes.sequential_hcl.swatchplot.qmd)</code>
    </dt>
    <dd>Palette Swatch Plot</dd>
</dl>


### Examples

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

```{python}
#| echo: true
#| warning: true
#| error: true
# Different color palette by name
b = sequential_hcl("Peach")
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
sequential_hcl("Peach")(10)
```



