<divid="unreleased-message"> You are reading an old version of the documentation (v3.3.3). For the latest version see <ahref="https://matplotlib.org/stable/api/cm_api.html">https://matplotlib.org/stable/api/cm_api.html</a></div>
<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>
<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 1-D or 2-D 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="n">data</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#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>In the first case, <em>cmap</em> must be a <aclass="reference internal" href="_as_gen/matplotlib.colors.Colormap.html#matplotlib.colors.Colormap" title="matplotlib.colors.Colormap"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">matplotlib.colors.Colormap</span></code></a>
instance. The <em>name</em> is optional; 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>
<p>The second case is deprecated. Here, the three arguments are passed to
and the resulting colormap is registered. Instead of this implicit
colormap creation, create a <aclass="reference internal" href="_as_gen/matplotlib.colors.LinearSegmentedColormap.html#matplotlib.colors.LinearSegmentedColormap" title="matplotlib.colors.LinearSegmentedColormap"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">LinearSegmentedColormap</span></code></a> and use the first
<p>Registering a colormap stores a reference to the colormap object
which can currently be modified and inadvertantly 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.revcmap">
<codeclass="descclassname">matplotlib.cm.</code><codeclass="descname">revcmap</code><spanclass="sig-paren">(</span><em><spanclass="n">data</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#revcmap"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.revcmap" title="Permalink to this definition">¶</a></dt>
<dd><p>[<em>Deprecated</em>] Can only handle specification <em>data</em> in dictionary format.</p>
<pclass="rubric">Notes</p>
<divclass="deprecated">
<p><spanclass="versionmodified deprecated">Deprecated since version 3.2.</span></p>