Support (mostly) all image surface formats, and dithering.

Author: anntzer

CHANGELOG.rst

@@ -1,3 +1,9 @@
+next
+====
+
+- Changed image format selection to ``set_options(image_format=...)``.
+- Added support for dithering control.
+
 v0.6.1 (2024-11-07)
 ===================
 

README.rst

@@ -110,10 +110,10 @@ path <add_dll_directory_>`_).
    is detected at runtime.
 
    cairo 1.17.2 added support for floating point surfaces, usable with
-   ``mplcairo.set_options(float_surface=True)``; the presence of this feature
-   is detected at runtime.  However, cairo 1.17.2 (and only that version) also
-   has a bug that causes (in particular) polar gridlines to be incorrectly
-   cropped.  This bug was fixed in 2d1a137.
+   ``mplcairo.set_options(image_format=mplcairo.format_t.RGBA128F)``; the
+   presence of this feature is detected at runtime.  However, cairo 1.17.2
+   (and only that version) also has a bug that causes (in particular) polar
+   gridlines to be incorrectly cropped.  This bug was fixed in 2d1a137.
 
    cairo 1.17.4 fixed a rare crash in rasterization (in dfe3aa6).
 

dither.py

@@ -0,0 +1,35 @@
+"""
+Similarly to support for blending operators, mplcairo also exposes support for
+dithering_ control.
+
+The example below uses 1-bit rendering (A1, monochrome) to demonstrate the
+effect of the dithering algorithms.  Note that A1 buffers are currently only
+supported with the ``mplcairo.qt`` backend.
+
+.. _dithering: https://www.cairographics.org/manual/cairo-cairo-pattern-t.html#cairo-dither-t
+"""
+
+import matplotlib as mpl
+from matplotlib import pyplot as plt
+import numpy as np
+
+import mplcairo
+from mplcairo import dither_t
+
+
+mplcairo.set_options(image_format="A1")
+
+rgba = mpl.image.imread(mpl.cbook.get_sample_data("grace_hopper.jpg"))
+alpha = rgba[:, :, :3].mean(-1).round().astype("u1")  # To transparency mask.
+rgba = np.dstack([np.full(alpha.shape + (3,), 0xff), alpha])
+
+# Figure and axes are made transparent, otherwise their patches would cover
+# everything else.
+axs = (plt.figure(figsize=(12, 4), facecolor="none")
+       .subplots(1, len(dither_t),
+                 subplot_kw=dict(xticks=[], yticks=[], facecolor="none")))
+for dither, ax in zip(dither_t, axs):
+    im = ax.imshow(rgba)
+    ax.set(title=dither.name)
+    dither.patch_artist(im)
+plt.show()

ext/_mplcairo.cpp

@@ -26,6 +26,14 @@ P11X_DECLARE_ENUM(
   {"GOOD", CAIRO_ANTIALIAS_GOOD},
   {"BEST", CAIRO_ANTIALIAS_BEST}
 )
+P11X_DECLARE_ENUM(
+  "dither_t", "enum.Enum",
+  {"NONE", mplcairo::detail::CAIRO_DITHER_NONE},
+  {"DEFAULT", mplcairo::detail::CAIRO_DITHER_DEFAULT},
+  {"FAST", mplcairo::detail::CAIRO_DITHER_FAST},
+  {"GOOD", mplcairo::detail::CAIRO_DITHER_GOOD},
+  {"BEST", mplcairo::detail::CAIRO_DITHER_BEST},
+)
 P11X_DECLARE_ENUM(
   "operator_t", "enum.Enum",
   {"CLEAR", CAIRO_OPERATOR_CLEAR},
@@ -58,15 +66,17 @@ P11X_DECLARE_ENUM(
   {"HSL_COLOR", CAIRO_OPERATOR_HSL_COLOR},
   {"HSL_LUMINOSITY", CAIRO_OPERATOR_HSL_LUMINOSITY}
 )
-P11X_DECLARE_ENUM(  // Only for error messages.
-  "_format_t", "enum.Enum",
+P11X_DECLARE_ENUM(
+  "format_t", "enum.Enum",
   {"INVALID", CAIRO_FORMAT_INVALID},
   {"ARGB32", CAIRO_FORMAT_ARGB32},
   {"RGB24", CAIRO_FORMAT_RGB24},
   {"A8", CAIRO_FORMAT_A8},
   {"A1", CAIRO_FORMAT_A1},
   {"RGB16_565", CAIRO_FORMAT_RGB16_565},
-  {"RGB30", CAIRO_FORMAT_RGB30}
+  {"RGB30", CAIRO_FORMAT_RGB30},
+  {"RGB96F", static_cast<cairo_format_t>(6)},
+  {"RGBA128F", static_cast<cairo_format_t>(7)}
 )
 P11X_DECLARE_ENUM(  // Only for error messages.
   "_surface_type_t", "enum.Enum",
@@ -263,7 +273,8 @@ GraphicsContextRenderer::GraphicsContextRenderer(
       /* hatch_linewidth */ {},  // Lazily loaded by get_hatch_linewidth.
       /* sketch */          {},
       /* snap */            true,  // Defaults to None, i.e. True for us.
-      /* url */             {}
+      /* url */             {},
+      /* dither */          detail::CAIRO_DITHER_DEFAULT
     }}}));
 }
 
@@ -303,7 +314,7 @@ GraphicsContextRenderer::~GraphicsContextRenderer()
 cairo_t* GraphicsContextRenderer::cr_from_image_args(int width, int height)
 {
   auto const& surface =
-    cairo_image_surface_create(get_cairo_format(), width, height);
+    cairo_image_surface_create(detail::IMAGE_FORMAT, width, height);
   auto const& cr = cairo_create(surface);
   cairo_surface_destroy(surface);
   return cr;
@@ -953,6 +964,9 @@ void GraphicsContextRenderer::draw_image(
   auto const& mtx =
     cairo_matrix_t{1, 0, 0, -1, -x, -y + height_};
   cairo_pattern_set_matrix(pattern, &mtx);
+  if (detail::cairo_pattern_set_dither) {
+    detail::cairo_pattern_set_dither(pattern, get_additional_state().dither);
+  }
   cairo_set_source(cr_, pattern);
   cairo_pattern_destroy(pattern);
   cairo_paint(cr_);
@@ -1049,7 +1063,7 @@ void maybe_multithread(
     for (auto i = 0; i < detail::COLLECTION_THREADS; ++i) {
       auto const& surface =
         cairo_surface_create_similar_image(
-          cairo_get_target(cr), get_cairo_format(), width, height);
+          cairo_get_target(cr), detail::IMAGE_FORMAT, width, height);
       auto const& ctx = cairo_create(surface);
       cairo_surface_destroy(surface);
       ctxs.push_back(ctx);
@@ -1164,7 +1178,7 @@ void GraphicsContextRenderer::draw_markers(
     auto const& raster_gcr =
       make_pattern_gcr(
         cairo_surface_create_similar_image(
-          cairo_get_target(cr_), get_cairo_format(),
+          cairo_get_target(cr_), detail::IMAGE_FORMAT,
           std::ceil(x1 - x0 + 1), std::ceil(y1 - y0 + 1)));
     auto const& raster_cr = raster_gcr.cr_;
     cairo_set_antialias(raster_cr, cairo_get_antialias(cr_));
@@ -1669,7 +1683,8 @@ py::array GraphicsContextRenderer::_stop_filter_get_buffer()
   restore();
   auto const& pattern = cairo_pop_group(cr_);
   auto const& raster_surface =
-    cairo_image_surface_create(get_cairo_format(), int(width_), int(height_));
+    cairo_image_surface_create(
+      detail::IMAGE_FORMAT, int(width_), int(height_));
   auto const& raster_cr = cairo_create(raster_surface);
   cairo_set_source(raster_cr, pattern);
   cairo_pattern_destroy(pattern);
@@ -2012,8 +2027,8 @@ Note that the defaults below refer to the initial values of the options;
 options not passed to `set_options` are left unchanged.
 
 At import time, mplcairo will set the initial values of the options from the
-``MPLCAIRO_<OPTION_NAME>`` environment variables (loading them as Python
-literals), if any such variables are set.
+``MPLCAIRO_<OPTION_NAME>`` environment variables, if any such variables are
+set.  (They are loaded as Python literals, e.g. strings must be quoted.)
 
 This function can also be used as a context manager
 (``with set_options(...): ...``).  In that case, the original values of the
@@ -2028,9 +2043,11 @@ cairo_circles : bool, default: True
 collection_threads : int, default: 0
     Number of threads to use to render markers and collections, if nonzero.
 
-float_surface : bool, default: False
-    Whether to use a floating point surface (more accurate, but uses more
-    memory).
+image_format : format_t, default: ARGB32
+    The internal image format (either a `format_t`, or the corresponding name).
+    All backends can render ARGB32 and RGBA128F images.  Qt can additionally
+    render RGB24, A8, RGB16_565, RGB30, and (with an extra conversion) A1.  No
+    backend currently supports RGBA96F.
 
 miter_limit : float, default: 10
     Setting for cairo_set_miter_limit__.  If negative, use Matplotlib's (bad)
@@ -2048,7 +2065,7 @@ _debug: bool, default: False
 Notes
 -----
 An additional format-specific control knob is the ``MaxVersion`` entry in the
-*metadata* dict passed to ``savefig``.  It can take values ``"1.4"``/``"1.5``
+*metadata* dict passed to ``savefig``.  It can take values ``"1.4"``/``"1.5"``
 (to restrict to PDF 1.4 or 1.5 -- default: 1.5), ``"2"``/``"3"`` (to restrict
 to PostScript levels 2 or 3 -- default: 3), or ``"1.1"``/``"1.2"`` (to restrict
 to SVG 1.1 or 1.2 -- default: 1.1).
@@ -2186,12 +2203,21 @@ Only intended for debugging purposes.
     .def("set_snap", &GraphicsContextRenderer::set_snap)
     .def("set_url", &GraphicsContextRenderer::set_url)
 
-    // This one function is specific to mplcairo.
+    // mplcairo-specific methods.
     .def(
       "set_mplcairo_operator",
       [](GraphicsContextRenderer& gcr, cairo_operator_t op) -> void {
         cairo_set_operator(gcr.cr_, op);
       })
+    .def(
+      "set_mplcairo_dither",
+      [](GraphicsContextRenderer& gcr, detail::cairo_dither_t dither) -> void {
+        if (!detail::cairo_pattern_set_dither) {
+          py::module::import("warnings").attr("warn")(
+            "cairo_pattern_set_dither requires cairo>=1.18.0");
+        }
+        gcr.get_additional_state().dither = dither;
+      })
 
     .def(
       "get_clip_rectangle",

ext/_util.cpp

@@ -66,7 +66,7 @@ py::object RC_PARAMS{},
            PIXEL_MARKER{},
            UNIT_CIRCLE{};
 int COLLECTION_THREADS{};
-bool FLOAT_SURFACE{};
+cairo_format_t IMAGE_FORMAT{CAIRO_FORMAT_ARGB32};
 double MITER_LIMIT{10.};
 bool DEBUG{};
 MplcairoScriptSurface MPLCAIRO_SCRIPT_SURFACE{[] {
@@ -114,7 +114,7 @@ py::dict get_options()
   return py::dict(
     "cairo_circles"_a=bool(detail::UNIT_CIRCLE),
     "collection_threads"_a=detail::COLLECTION_THREADS,
-    "float_surface"_a=detail::FLOAT_SURFACE,
+    "image_format"_a=detail::IMAGE_FORMAT,
     "miter_limit"_a=detail::MITER_LIMIT,
     "raqm"_a=has_raqm(),
     "_debug"_a=detail::DEBUG);
@@ -139,11 +139,24 @@ py::object set_options(py::kwargs kwargs)
       Py_XDECREF(detail::UNIT_CIRCLE.release().ptr());
     }
   }
-  if (auto const& float_surface = pop_option("float_surface", bool{})) {
-    if (*float_surface && cairo_version() < CAIRO_VERSION_ENCODE(1, 17, 2)) {
+  if (auto const& image_format =
+      pop_option("image_format",
+                 std::variant<cairo_format_t, std::string>{})) {
+    auto fmt = std::visit(overloaded {
+      [](cairo_format_t fmt) {
+        return fmt;
+      },
+      [](std::string fmt) {  // operator[]() doesn't support std::string
+        return
+          py::module::import("mplcairo").attr("format_t")[fmt.c_str()]
+          .cast<cairo_format_t>();
+      }
+    }, *image_format);
+    if (fmt > CAIRO_FORMAT_RGB30
+        && cairo_version() < CAIRO_VERSION_ENCODE(1, 17, 2)) {
       throw std::invalid_argument{"float surfaces require cairo>=1.17.2"};
     }
-    detail::FLOAT_SURFACE = *float_surface;
+    detail::IMAGE_FORMAT = fmt;
   }
   if (auto const& threads = pop_option("collection_threads", int{})) {
     detail::COLLECTION_THREADS = *threads;
@@ -175,12 +188,6 @@ py::object rc_param(std::string key)
     PyDict_GetItemString(detail::RC_PARAMS.ptr(), key.data()));
 }
 
-cairo_format_t get_cairo_format() {
-  return
-    detail::FLOAT_SURFACE
-    ? static_cast<cairo_format_t>(7) : CAIRO_FORMAT_ARGB32;
-}
-
 rgba_t to_rgba(py::object color, std::optional<double> alpha)
 {
   return
@@ -679,6 +686,15 @@ void fill_and_stroke_exact(
 }
 
 py::array image_surface_to_buffer(cairo_surface_t* surface) {
+  // Possible outputs:
+  //   ARGB32    -> uint8, (h, w, 4)
+  //   RGB24     -> uint8, (h, w, 3) (non-contiguous)
+  //   A8        -> uint8, (h, w)
+  //   A1        -> ("V{w}", void(ceil(w/8))), (h,)
+  //   RGB16_565 -> uint16, (h, w)
+  //   RGB30     -> uint32, (h, w)
+  //   RGB96F    -> float, (h, w, 3)
+  //   RGB128F   -> float, (h, w, 4)
   if (auto const& type = cairo_surface_get_type(surface);
       type != CAIRO_SURFACE_TYPE_IMAGE) {
     throw std::runtime_error{
@@ -687,37 +703,47 @@ py::array image_surface_to_buffer(cairo_surface_t* surface) {
   }
   cairo_surface_reference(surface);
   cairo_surface_flush(surface);
+  auto const& h = cairo_image_surface_get_height(surface),
+            & w = cairo_image_surface_get_width(surface),
+            & stride = cairo_image_surface_get_stride(surface);
+  auto const& data = cairo_image_surface_get_data(surface);
+  auto const& capsule = py::capsule(
+    surface,
+    [](void* surface) -> void {
+      cairo_surface_destroy(static_cast<cairo_surface_t*>(surface));
+    });
   switch (auto const& fmt = cairo_image_surface_get_format(surface);
           // Avoid "not in enumerated type" warning with CAIRO_FORMAT_RGBA_128F.
           static_cast<int>(fmt)) {
     case static_cast<int>(CAIRO_FORMAT_ARGB32):
-      return py::array_t<uint8_t>{
-        {cairo_image_surface_get_height(surface),
-         cairo_image_surface_get_width(surface),
-         4},
-        {cairo_image_surface_get_stride(surface), 4, 1},
-         cairo_image_surface_get_data(surface),
-         py::capsule(
-           surface,
-           [](void* surface) -> void {
-             cairo_surface_destroy(static_cast<cairo_surface_t*>(surface));
-           })};
-    case 7:  // CAIRO_FORMAT_RGBA_128F.
+      return py::array_t<uint8_t>{{h, w, 4}, {stride, 4, 1}, data, capsule};
+    case static_cast<int>(CAIRO_FORMAT_RGB24):
+      return py::array_t<uint8_t>{{h, w, 3}, {stride, 4, 1}, data, capsule};
+    case static_cast<int>(CAIRO_FORMAT_A8):
+      return py::array_t<uint8_t>{{h, w}, {stride, 1}, data, capsule};
+    case static_cast<int>(CAIRO_FORMAT_A1): {
+      auto dtype_args = py::list{};
+      dtype_args.append(py::make_tuple(
+        "V" + std::to_string(w), "V" + std::to_string((w + 7) / 8)));
+      return py::array{
+        py::dtype::from_args(dtype_args), {h}, {stride}, data, capsule};
+    }
+    case static_cast<int>(CAIRO_FORMAT_RGB16_565):
+      return py::array_t<uint16_t>{
+        {h, w}, {stride, 2}, reinterpret_cast<uint16_t*>(data), capsule};
+    case static_cast<int>(CAIRO_FORMAT_RGB30):
+      return py::array_t<uint32_t>{
+        {h, w}, {stride, 4}, reinterpret_cast<uint32_t*>(data), capsule};
+    case 6:  // CAIRO_FORMAT_RGB96F.
+      return py::array_t<float>{
+        {h, w, 3}, {stride, 12, 4}, reinterpret_cast<float*>(data), capsule};
+    case 7:  // CAIRO_FORMAT_RGBA128F.
       return py::array_t<float>{
-        {cairo_image_surface_get_height(surface),
-         cairo_image_surface_get_width(surface),
-         4},
-        {cairo_image_surface_get_stride(surface), 16, 4},
-        reinterpret_cast<float*>(cairo_image_surface_get_data(surface)),
-        py::capsule(
-          surface,
-          [](void* surface) -> void {
-            cairo_surface_destroy(static_cast<cairo_surface_t*>(surface));
-          })};
+        {h, w, 4}, {stride, 16, 4}, reinterpret_cast<float*>(data), capsule};
     default:
       throw std::invalid_argument{
-        "_get_buffer only supports images surfaces with ARGB32 and RGBA128F "
-        "formats, not {}"_format(fmt).cast<std::string>()};
+        "_get_buffer does not support image surfaces with format "
+        "{}"_format(fmt).cast<std::string>()};
   }
 }