New data → color pipeline (matplotlib#28658)

This overhauls the data -> color pipeline used in ScalarMappable to open the path to higher-dimension mappings.

Co-authored-by: Thomas A Caswell <[email protected]>
Co-authored-by: Kyle Sunden <[email protected]>

Author: 3 people

doc/api/.gitignore

@@ -0,0 +1 @@
+scalarmappable.gen_rst

doc/api/cm_api.rst

@@ -6,3 +6,5 @@
    :members:
    :undoc-members:
    :show-inheritance:
+
+.. include:: scalarmappable.gen_rst

doc/api/colorizer_api.rst

@@ -0,0 +1,9 @@
+************************
+``matplotlib.colorizer``
+************************
+
+.. automodule:: matplotlib.colorizer
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members: _ColorizerInterface, _ScalarMappable

doc/api/colors_api.rst

@@ -32,8 +32,8 @@ Color norms
    SymLogNorm
    TwoSlopeNorm
 
-Colormaps
----------
+Univariate Colormaps
+--------------------
 
 .. autosummary::
    :toctree: _as_gen/
@@ -43,6 +43,17 @@ Colormaps
    LinearSegmentedColormap
    ListedColormap
 
+Multivariate Colormaps
+----------------------
+
+.. autosummary::
+   :toctree: _as_gen/
+   :template: autosummary.rst
+
+   BivarColormap
+   SegmentedBivarColormap
+   BivarColormapFromImage
+
 Other classes
 -------------
 

doc/api/index.rst

@@ -93,6 +93,7 @@ Alphabetical list of modules:
    cm_api.rst
    collections_api.rst
    colorbar_api.rst
+   colorizer_api.rst
    colors_api.rst
    container_api.rst
    contour_api.rst

doc/conf.py

@@ -29,7 +29,6 @@
 
 import matplotlib
 
-
 # debug that building expected version
 print(f"Building Documentation for Matplotlib: {matplotlib.__version__}")
 
@@ -853,6 +852,58 @@ def linkcode_resolve(domain, info):
     extensions.append('sphinx.ext.viewcode')
 
 
+def generate_ScalarMappable_docs():
+
+    import matplotlib.colorizer
+    from numpydoc.docscrape_sphinx import get_doc_object
+    from pathlib import Path
+    import textwrap
+    from sphinx.util.inspect import stringify_signature
+    target_file = Path(__file__).parent / 'api' / 'scalarmappable.gen_rst'
+    with open(target_file, 'w') as fout:
+        fout.write("""
+.. class:: ScalarMappable(colorizer, **kwargs)
+   :canonical: matplotlib.colorizer._ScalarMappable
+
+""")
+        for meth in [
+                matplotlib.colorizer._ScalarMappable.autoscale,
+                matplotlib.colorizer._ScalarMappable.autoscale_None,
+                matplotlib.colorizer._ScalarMappable.changed,
+                """
+   .. attribute:: colorbar
+
+        The last colorbar associated with this ScalarMappable. May be None.
+""",
+                matplotlib.colorizer._ScalarMappable.get_alpha,
+                matplotlib.colorizer._ScalarMappable.get_array,
+                matplotlib.colorizer._ScalarMappable.get_clim,
+                matplotlib.colorizer._ScalarMappable.get_cmap,
+                """
+   .. property:: norm
+""",
+                matplotlib.colorizer._ScalarMappable.set_array,
+                matplotlib.colorizer._ScalarMappable.set_clim,
+                matplotlib.colorizer._ScalarMappable.set_cmap,
+                matplotlib.colorizer._ScalarMappable.set_norm,
+                matplotlib.colorizer._ScalarMappable.to_rgba,
+        ]:
+            if isinstance(meth, str):
+                fout.write(meth)
+            else:
+                name = meth.__name__
+                sig = stringify_signature(inspect.signature(meth))
+                docstring = textwrap.indent(
+                    str(get_doc_object(meth)),
+                    '      '
+                ).rstrip()
+                fout.write(f"""
+   .. method::  {name}{sig}
+{docstring}
+
+""")
+
+
 # -----------------------------------------------------------------------------
 # Sphinx setup
 # -----------------------------------------------------------------------------
@@ -866,3 +917,4 @@ def setup(app):
     app.connect('autodoc-process-bases', autodoc_process_bases)
     if sphinx.version_info[:2] < (7, 1):
         app.connect('html-page-context', add_html_cache_busting, priority=1000)
+    generate_ScalarMappable_docs()

doc/missing-references.json

@@ -306,8 +306,8 @@
       "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.broken_barh:84",
       "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.fill_between:121",
       "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.fill_betweenx:121",
-      "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.hexbin:213",
-      "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.pcolor:182",
+      "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.hexbin:217",
+      "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.pcolor:186",
       "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.quiver:215",
       "lib/matplotlib/collections.py:docstring of matplotlib.artist.AsteriskPolygonCollection.set:44",
       "lib/matplotlib/collections.py:docstring of matplotlib.artist.CircleCollection.set:44",
@@ -321,8 +321,8 @@
       "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.broken_barh:84",
       "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.fill_between:121",
       "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.fill_betweenx:121",
-      "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.hexbin:213",
-      "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.pcolor:182",
+      "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.hexbin:217",
+      "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.pcolor:186",
       "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.quiver:215",
       "lib/matplotlib/quiver.py:docstring of matplotlib.artist.Barbs.set:45",
       "lib/matplotlib/quiver.py:docstring of matplotlib.artist.Quiver.set:45",
@@ -332,10 +332,10 @@
       "lib/mpl_toolkits/mplot3d/art3d.py:docstring of matplotlib.artist.Poly3DCollection.set:45"
     ],
     "matplotlib.collections._MeshData.set_array": [
-      "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.pcolormesh:164",
+      "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.pcolormesh:168",
       "lib/matplotlib/collections.py:docstring of matplotlib.artist.PolyQuadMesh.set:17",
       "lib/matplotlib/collections.py:docstring of matplotlib.artist.QuadMesh.set:17",
-      "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.pcolormesh:164"
+      "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.pcolormesh:168"
     ]
   },
   "py:obj": {
@@ -355,12 +355,6 @@
     "Line2D.pick": [
       "doc/users/explain/figure/event_handling.rst:571"
     ],
-    "QuadContourSet.changed()": [
-      "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.contour:156",
-      "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.contourf:156",
-      "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.contour:156",
-      "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.contourf:156"
-    ],
     "Rectangle.contains": [
       "doc/users/explain/figure/event_handling.rst:285"
     ],