<spanid="matplotlib-cm"></span><h1><codeclass="docutils literal notranslate"><spanclass="pre">matplotlib.cm</span></code><aclass="headerlink" href="#module-matplotlib.cm" title="Permalink to this headline">¶</a></h1>
<p>Builtin colormaps, colormap handling utilities, and the <aclass="reference internal" href="#matplotlib.cm.ScalarMappable" title="matplotlib.cm.ScalarMappable"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">ScalarMappable</span></code></a> mixin.</p>
<divclass="admonition seealso">
<pclass="first admonition-title">See also</p>
<p><aclass="reference internal" href="../gallery/color/colormap_reference.html"><spanclass="doc">Colormap reference</span></a> for a list of builtin colormaps.</p>
<p><aclass="reference internal" href="../tutorials/colors/colormap-manipulation.html"><spanclass="doc">Creating Colormaps in Matplotlib</span></a> for examples of how to
make colormaps.</p>
<p><aclass="reference internal" href="../tutorials/colors/colormaps.html"><spanclass="doc">Choosing Colormaps in Matplotlib</span></a> an in-depth discussion of
choosing colormaps.</p>
<pclass="last"><aclass="reference internal" href="../tutorials/colors/colormapnorms.html"><spanclass="doc">Colormap Normalization</span></a> for more details about data
normalization.</p>
</div>
<dlclass="py class">
<dtid="matplotlib.cm.ScalarMappable">
<emclass="property">class </em><codeclass="descclassname">matplotlib.cm.</code><codeclass="descname">ScalarMappable</code><spanclass="sig-paren">(</span><em><spanclass="n">norm</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <em><spanclass="n">cmap</span><spanclass="o">=</span><spanclass="default_value">None</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable" title="Permalink to this definition">¶</a></dt>
<trclass="field-odd field"><thclass="field-name">Parameters:</th><tdclass="field-body"><dlclass="first last docutils">
<dt><strong>norm</strong><spanclass="classifier"><aclass="reference internal" href="_as_gen/matplotlib.colors.Normalize.html#matplotlib.colors.Normalize" title="matplotlib.colors.Normalize"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">matplotlib.colors.Normalize</span></code></a> (or subclass thereof)</span></dt><dd><p>The normalizing object which scales data, typically into the
If <em>None</em>, <em>norm</em> defaults to a <em>colors.Normalize</em> object which
initializes its scaling based on the first data processed.</p>
</dd>
<dt><strong>cmap</strong><spanclass="classifier">str or <aclass="reference internal" href="_as_gen/matplotlib.colors.Colormap.html#matplotlib.colors.Colormap" title="matplotlib.colors.Colormap"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Colormap</span></code></a></span></dt><dd><p>The colormap used to map normalized data values to RGBA colors.</p>
</dd>
</dl>
</td>
</tr>
</tbody>
</table>
<dlclass="py method">
<dtid="matplotlib.cm.ScalarMappable.add_checker">
<codeclass="descname">add_checker</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em>, <em><spanclass="n">checker</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.add_checker"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.add_checker" title="Permalink to this definition">¶</a></dt>
<dd><p>[<em>Deprecated</em>]</p>
<pclass="rubric">Notes</p>
<divclass="deprecated">
<p><spanclass="versionmodified deprecated">Deprecated since version 3.3: </span></p>
</div>
</dd></dl>
<dlclass="py method">
<dtid="matplotlib.cm.ScalarMappable.autoscale">
<codeclass="descname">autoscale</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.autoscale"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.autoscale" title="Permalink to this definition">¶</a></dt>
<dd><p>Autoscale the scalar limits on the norm instance using the
<codeclass="descname">autoscale_None</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.autoscale_None"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.autoscale_None" title="Permalink to this definition">¶</a></dt>
<dd><p>Autoscale the scalar limits on the norm instance using the
current array, changing only limits that are None</p>
</dd></dl>
<dlclass="py method">
<dtid="matplotlib.cm.ScalarMappable.changed">
<codeclass="descname">changed</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.changed"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.changed" title="Permalink to this definition">¶</a></dt>
<dd><p>Call this whenever the mappable is changed to notify all the
<codeclass="descname">check_update</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em>, <em><spanclass="n">checker</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.check_update"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.check_update" title="Permalink to this definition">¶</a></dt>
<dd><p>[<em>Deprecated</em>]</p>
<pclass="rubric">Notes</p>
<divclass="deprecated">
<p><spanclass="versionmodified deprecated">Deprecated since version 3.3: </span></p>
</div>
</dd></dl>
<dlclass="py attribute">
<dtid="matplotlib.cm.ScalarMappable.colorbar">
<codeclass="descname">colorbar</code><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.colorbar" title="Permalink to this definition">¶</a></dt>
<dd><p>The last colorbar associated with this ScalarMappable. May be None.</p>
</dd></dl>
<dlclass="py method">
<dtid="matplotlib.cm.ScalarMappable.get_alpha">
<codeclass="descname">get_alpha</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.get_alpha"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.get_alpha" title="Permalink to this definition">¶</a></dt>
<trclass="field-odd field"><thclass="field-name">Returns:</th><tdclass="field-body"><dlclass="first last docutils">
<dt>float</dt><dd><p>Always returns 1.</p>
</dd>
</dl>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="py method">
<dtid="matplotlib.cm.ScalarMappable.get_array">
<codeclass="descname">get_array</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.get_array"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.get_array" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the data array.</p>
</dd></dl>
<dlclass="py method">
<dtid="matplotlib.cm.ScalarMappable.get_clim">
<codeclass="descname">get_clim</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.get_clim"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.get_clim" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the values (min, max) that are mapped to the colormap limits.</p>
</dd></dl>
<dlclass="py method">
<dtid="matplotlib.cm.ScalarMappable.get_cmap">
<codeclass="descname">get_cmap</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.get_cmap"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.get_cmap" title="Permalink to this definition">¶</a></dt>
<codeclass="descname">set_array</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em>, <em><spanclass="n">A</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.set_array"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.set_array" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the image array from numpy array <em>A</em>.</p>
<trclass="field-odd field"><thclass="field-name">Parameters:</th><tdclass="field-body"><dlclass="first last docutils">
<dt><strong>A</strong><spanclass="classifier">ndarray or None</span></dt><dd></dd>
</dl>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="py method">
<dtid="matplotlib.cm.ScalarMappable.set_clim">
<codeclass="descname">set_clim</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em>, <em><spanclass="n">vmin</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <em><spanclass="n">vmax</span><spanclass="o">=</span><spanclass="default_value">None</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.set_clim"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.set_clim" title="Permalink to this definition">¶</a></dt>
<p>The limits may also be passed as a tuple (<em>vmin</em>, <em>vmax</em>) as a
single positional argument.</p>
</dd>
</dl>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="py method">
<dtid="matplotlib.cm.ScalarMappable.set_cmap">
<codeclass="descname">set_cmap</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em>, <em><spanclass="n">cmap</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.set_cmap"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.set_cmap" title="Permalink to this definition">¶</a></dt>
<trclass="field-odd field"><thclass="field-name">Parameters:</th><tdclass="field-body"><dlclass="first last docutils">
<dt><strong>cmap</strong><spanclass="classifier"><aclass="reference internal" href="_as_gen/matplotlib.colors.Colormap.html#matplotlib.colors.Colormap" title="matplotlib.colors.Colormap"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Colormap</span></code></a> or str or None</span></dt><dd></dd>
</dl>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="py method">
<dtid="matplotlib.cm.ScalarMappable.set_norm">
<codeclass="descname">set_norm</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em>, <em><spanclass="n">norm</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.set_norm"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.set_norm" title="Permalink to this definition">¶</a></dt>
<p>If there are any colorbars using the mappable for this norm, setting
the norm of the mappable will reset the norm, locator, and formatters
on the colorbar to default.</p>
</dd></dl>
<dlclass="py method">
<dtid="matplotlib.cm.ScalarMappable.to_rgba">
<codeclass="descname">to_rgba</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em>, <em><spanclass="n">x</span></em>, <em><spanclass="n">alpha</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <em><spanclass="n">bytes</span><spanclass="o">=</span><spanclass="default_value">False</span></em>, <em><spanclass="n">norm</span><spanclass="o">=</span><spanclass="default_value">True</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.to_rgba"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.to_rgba" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a normalized rgba array corresponding to <em>x</em>.</p>
<p>In the normal case, <em>x</em> is a 1D or 2D sequence of scalars, and
the corresponding ndarray of rgba values will be returned,
based on the norm and colormap set for this ScalarMappable.</p>
<p>There is one special case, for handling images that are already
rgb or rgba, such as might have been read from an image file.
If <em>x</em> is an ndarray with 3 dimensions,
and the last dimension is either 3 or 4, then it will be
treated as an rgb or rgba array, and no mapping will be done.
The array can be uint8, or it can be floating point with
values in the 0-1 range; otherwise a ValueError will be raised.
If it is a masked array, the mask will be ignored.
If the last dimension is 3, the <em>alpha</em> kwarg (defaulting to 1)
will be used to fill in the transparency. If the last dimension
is 4, the <em>alpha</em> kwarg is ignored; it does not
replace the pre-existing alpha. A ValueError will be raised
if the third dimension is other than 3 or 4.</p>
<p>In either case, if <em>bytes</em> is <em>False</em> (default), the rgba
array will be floats in the 0-1 range; if it is <em>True</em>,
the returned rgba array will be uint8 in the 0 to 255 range.</p>
<p>If norm is False, no normalization of the input data is
performed, and it is assumed to be in the range (0-1).</p>
</dd></dl>
<dlclass="py method">
<dtid="matplotlib.cm.ScalarMappable.update_dict">
<emclass="property">property </em><codeclass="descname">update_dict</code><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.update_dict" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
</dd></dl>
<dlclass="py function">
<dtid="matplotlib.cm.get_cmap">
<codeclass="descclassname">matplotlib.cm.</code><codeclass="descname">get_cmap</code><spanclass="sig-paren">(</span><em><spanclass="n">name</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <em><spanclass="n">lut</span><spanclass="o">=</span><spanclass="default_value">None</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#get_cmap"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.get_cmap" title="Permalink to this definition">¶</a></dt>
<dd><p>Get a colormap instance, defaulting to rc values if <em>name</em> is None.</p>
<p>Colormaps added with <aclass="reference internal" href="#matplotlib.cm.register_cmap" title="matplotlib.cm.register_cmap"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">register_cmap()</span></code></a> take precedence over
<trclass="field-odd field"><thclass="field-name">Parameters:</th><tdclass="field-body"><dlclass="first last docutils">
<dt><strong>name</strong><spanclass="classifier"><aclass="reference internal" href="_as_gen/matplotlib.colors.Colormap.html#matplotlib.colors.Colormap" title="matplotlib.colors.Colormap"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">matplotlib.colors.Colormap</span></code></a> or str or None, default: None</span></dt><dd><p>If a <aclass="reference internal" href="_as_gen/matplotlib.colors.Colormap.html#matplotlib.colors.Colormap" title="matplotlib.colors.Colormap"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Colormap</span></code></a> instance, it will be returned. Otherwise, the name of
a colormap known to Matplotlib, which will be resampled by <em>lut</em>. The
<dt><strong>lut</strong><spanclass="classifier">int or None, default: None</span></dt><dd><p>If <em>name</em> is not already a Colormap instance and <em>lut</em> is not None, the
colormap will be resampled to have <em>lut</em> entries in the lookup table.</p>
</dd>
</dl>
</td>
</tr>
</tbody>
</table>
<pclass="rubric">Notes</p>
<p>Currently, this returns the global colormap object, which is deprecated.
In Matplotlib 3.5, you will no longer be able to modify the global
colormaps in-place.</p>
</dd></dl>
<dlclass="py function">
<dtid="matplotlib.cm.register_cmap">
<codeclass="descclassname">matplotlib.cm.</code><codeclass="descname">register_cmap</code><spanclass="sig-paren">(</span><em><spanclass="n">name</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <em><spanclass="n">cmap</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <em><spanclass="o">*</span></em>, <em><spanclass="n">override_builtin</span><spanclass="o">=</span><spanclass="default_value">False</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#register_cmap"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.register_cmap" title="Permalink to this definition">¶</a></dt>
<dd><p>Add a colormap to the set recognized by <aclass="reference internal" href="#matplotlib.cm.get_cmap" title="matplotlib.cm.get_cmap"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">get_cmap()</span></code></a>.</p>
<p>Register a new colormap to be accessed by name</p>
<trclass="field-odd field"><thclass="field-name">Parameters:</th><tdclass="field-body"><dlclass="first last docutils">
<dt><strong>name</strong><spanclass="classifier">str, optional</span></dt><dd><p>The name that can be used in <aclass="reference internal" href="#matplotlib.cm.get_cmap" title="matplotlib.cm.get_cmap"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">get_cmap()</span></code></a> or <codeclass="docutils literal notranslate"><aclass="reference external" href="../tutorials/introductory/customizing.html?highlight=image.cmap#a-sample-matplotlibrc-file"><spanclass="pre">rcParams["image.cmap"]</span></a></code> (default: <codeclass="docutils literal notranslate"><spanclass="pre">'viridis'</span></code>)</p>
<p>If absent, the name will be the <codeclass="xref py py-attr docutils literal notranslate"><spanclass="pre">name</span></code>
attribute of the <em>cmap</em>.</p>
</dd>
<dt><strong>cmap</strong><spanclass="classifier">matplotlib.colors.Colormap</span></dt><dd><p>Despite being the second argument and having a default value, this
is a required argument.</p>
</dd>
<dt><strong>override_builtin</strong><spanclass="classifier">bool</span></dt><dd><p>Allow built-in colormaps to be overridden by a user-supplied
colormap.</p>
<p>Please do not use this unless you are sure you need it.</p>
</dd>
</dl>
</td>
</tr>
</tbody>
</table>
<pclass="rubric">Notes</p>
<p>Registering a colormap stores a reference to the colormap object
which can currently be modified and inadvertently change the global
colormap state. This behavior is deprecated and in Matplotlib 3.5
the registered colormap will be immutable.</p>
</dd></dl>
<dlclass="py function">
<dtid="matplotlib.cm.unregister_cmap">
<codeclass="descclassname">matplotlib.cm.</code><codeclass="descname">unregister_cmap</code><spanclass="sig-paren">(</span><em><spanclass="n">name</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#unregister_cmap"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.unregister_cmap" title="Permalink to this definition">¶</a></dt>
<dd><p>Remove a colormap recognized by <aclass="reference internal" href="#matplotlib.cm.get_cmap" title="matplotlib.cm.get_cmap"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">get_cmap()</span></code></a>.</p>
<p>You may not remove built-in colormaps.</p>
<p>If the named colormap is not registered, returns with no error, raises
if you try to de-register a default colormap.</p>
<divclass="admonition warning">
<pclass="first admonition-title">Warning</p>
<pclass="last">Colormap names are currently a shared namespace that may be used
by multiple packages. Use <aclass="reference internal" href="#matplotlib.cm.unregister_cmap" title="matplotlib.cm.unregister_cmap"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">unregister_cmap</span></code></a> only if you know you
have registered that name before. In particular, do not
unregister just in case to clean the name before registering a
<dt>ColorMap or None</dt><dd><p>If the colormap was registered, return it if not return <aclass="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.9)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">None</span></code></a></p>
</dd>
</dl>
</td>
</tr>
<trclass="field-odd field"><thclass="field-name">Raises:</th><tdclass="field-body"><dlclass="first last docutils">
<dt>ValueError</dt><dd><p>If you try to de-register a default built-in colormap.</p>