docling-parse 7.22.2__tar.gz → 7.22.4__tar.gz

{docling_parse-7.22.2 → docling_parse-7.22.4}/CHANGELOG.md

@@ -1,3 +1,16 @@
+## [v7.22.4](https://github.com/docling-project/docling-parse/releases/tag/v7.22.4) - 2026-10-21
+
+### Fix
+
+* Allow Pillow 13 ([#420](https://github.com/docling-project/docling-parse/issues/420)) ([`fbe3190`](https://github.com/docling-project/docling-parse/commit/fbe31904e81093c4f4a4f2ea3f5d1f8d36b0962c))
+
+## [v7.22.3](https://github.com/docling-project/docling-parse/releases/tag/v7.22.3) - 2026-10-13
+
+### Fix
+
+* Unit stroke curves ([#407](https://github.com/docling-project/docling-parse/issues/407)) ([`30ae51f`](https://github.com/docling-project/docling-parse/commit/30ae51feb4ee4b4cc69c9e9aaee78eb74d4206fd))
+* **render:** Decode JBIG2 /Mask stencils ([#360](https://github.com/docling-project/docling-parse/issues/360)) ([`e0e678c`](https://github.com/docling-project/docling-parse/commit/e0e678ce182a8a9b1b143e50251b51048ad767e4))
+
 ## [v7.22.2](https://github.com/docling-project/docling-parse/releases/tag/v7.22.2) - 2026-10-05
 
 ### Fix

{docling_parse-7.22.2 → docling_parse-7.22.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docling-parse
-Version: 7.22.2
+Version: 7.22.4
 Summary: Simple package to extract text with coordinates from programmatic PDFs
 Author-email: Peter Staar <taa@zurich.ibm.com>, Christoph Auer <cau@zurich.ibm.com>, Michele Dolfi <dol@zurich.ibm.com>, Panos Vagenas <pva@zurich.ibm.com>, Maxim Lysak <mly@zurich.ibm.com>
 License-Expression: MIT
@@ -23,7 +23,7 @@ Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: pillow<13.0.0,>=10.0.0
+Requires-Dist: pillow<14.0.0,>=10.0.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: docling-core<3.0.0,>=2.99.0
 Requires-Dist: pywin32>=305; sys_platform == "win32"

{docling_parse-7.22.2 → docling_parse-7.22.4}/docling_parse.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docling-parse
-Version: 7.22.2
+Version: 7.22.4
 Summary: Simple package to extract text with coordinates from programmatic PDFs
 Author-email: Peter Staar <taa@zurich.ibm.com>, Christoph Auer <cau@zurich.ibm.com>, Michele Dolfi <dol@zurich.ibm.com>, Panos Vagenas <pva@zurich.ibm.com>, Maxim Lysak <mly@zurich.ibm.com>
 License-Expression: MIT
@@ -23,7 +23,7 @@ Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: pillow<13.0.0,>=10.0.0
+Requires-Dist: pillow<14.0.0,>=10.0.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: docling-core<3.0.0,>=2.99.0
 Requires-Dist: pywin32>=305; sys_platform == "win32"

{docling_parse-7.22.2 → docling_parse-7.22.4}/docling_parse.egg-info/SOURCES.txt

@@ -762,6 +762,7 @@ tests/test_unit_gid_glyph_names.py
 tests/test_unit_glyph_proportions.py
 tests/test_unit_indexed_images.py
 tests/test_unit_invalid_font_metrics.py
+tests/test_unit_jbig2_masks.py
 tests/test_unit_jpeg_images.py
 tests/test_unit_load_failure.py
 tests/test_unit_nul_mapping.py
@@ -774,6 +775,7 @@ tests/test_unit_shadings.py
 tests/test_unit_shape_boundary_origin.py
 tests/test_unit_shape_queries_page_frame.py
 tests/test_unit_standard_font_widths.py
+tests/test_unit_stroke_curves.py
 tests/test_unit_text_render_modes.py
 tests/test_unit_threaded_page_range.py
 tests/test_unit_tounicode_fallback.py

{docling_parse-7.22.2 → docling_parse-7.22.4}/docling_parse.egg-info/requires.txt

@@ -1,4 +1,4 @@
-pillow<13.0.0,>=10.0.0
+pillow<14.0.0,>=10.0.0
 pydantic>=2.0.0
 docling-core<3.0.0,>=2.99.0
 

{docling_parse-7.22.2 → docling_parse-7.22.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docling-parse"
-version = "7.22.2"
+version = "7.22.4"
 description = "Simple package to extract text with coordinates from programmatic PDFs"
 license = "MIT"
 keywords = ["docling", "pdf", "parser"]
@@ -29,7 +29,7 @@ authors = [
 ]
 requires-python = ">=3.10"
 dependencies = [
-    "pillow>=10.0.0,<13.0.0",
+    "pillow>=10.0.0,<14.0.0",
     "pydantic>=2.0.0",
     "docling-core>=2.99.0,<3.0.0",
     "pywin32>=305; sys_platform == 'win32'",

{docling_parse-7.22.2 → docling_parse-7.22.4}/src/parse/pdf_resources/page_xobject_image.h

@@ -4,6 +4,7 @@
 #define PDF_PAGE_XOBJECT_IMAGE_RESOURCE_H
 
 #include <parse/utils/ccitt/ccitt_utils.h>
+#include <third_party/pdfium_jbig2.h>
 
 #include <cstdint>
 #include <cstring>
@@ -1241,10 +1242,9 @@ namespace pdflib
         return;
       }
 
-    // A stencil mask is very often CCITTFax-compressed, which qpdf cannot
-    // defilter; decode it here. `ccitt::decode` yields one byte per pixel
-    // with 0 = dark.
-    std::vector<uint8_t> ccitt_samples;
+    // A stencil mask is very often CCITTFax- or JBIG2-compressed, which qpdf
+    // cannot defilter; decode it here into one byte per pixel with 0 = dark.
+    std::vector<uint8_t> mask_samples;
     if(not smask.has_decoded_stream_data())
       {
         QPDFObjectHandle mdict = qpdf_smask.getDict();
@@ -1269,10 +1269,10 @@ namespace pdflib
               }
 
             auto encoded = smask.get_codec_stream_data();
-            ccitt_samples = ccitt::decode(
+            mask_samples = ccitt::decode(
               reinterpret_cast<const uint8_t*>(encoded->getBuffer()),
               encoded->getSize(), sm_w, sm_h, ccitt_parms);
-            if(ccitt_samples.size() < static_cast<size_t>(sm_w) * sm_h)
+            if(mask_samples.size() < static_cast<size_t>(sm_w) * sm_h)
               {
                 LOG_S(WARNING) << "mask CCITT decode too small for xobject_key="
                                << xobject_key;
@@ -1280,6 +1280,41 @@ namespace pdflib
               }
             smask_bpc = 8;
           }
+        else if(filter.find("JBIG2Decode") != std::string::npos and
+                smask.has_codec_stream_data())
+          {
+            // MRC scans stencil their foreground layer with a JBIG2 mask.
+            // `jbig2_decode` returns packed 1bpp rows with 0 = black, so
+            // expanding each bit to 0x00/0xFF matches the CCITT samples above.
+            auto encoded = smask.get_codec_stream_data();
+            auto globals = smask.get_jbig2_globals_data();
+            const bool has_globals = globals and globals->getSize() > 0;
+            auto bits = jbig2_decode(
+              {reinterpret_cast<const uint8_t*>(encoded->getBuffer()), encoded->getSize()},
+              {has_globals ? reinterpret_cast<const uint8_t*>(globals->getBuffer()) : nullptr,
+               has_globals ? globals->getSize() : 0},
+              static_cast<uint32_t>(sm_w), static_cast<uint32_t>(sm_h));
+
+            const size_t pitch = (static_cast<size_t>(sm_w) + 7u) / 8u;
+            if(bits.size() < pitch * static_cast<size_t>(sm_h))
+              {
+                LOG_S(WARNING) << "mask JBIG2 decode failed for xobject_key="
+                               << xobject_key;
+                return;
+              }
+
+            mask_samples.resize(static_cast<size_t>(sm_w) * sm_h);
+            for(int row = 0; row < sm_h; ++row)
+              {
+                for(int col = 0; col < sm_w; ++col)
+                  {
+                    const uint8_t byte = bits[static_cast<size_t>(row) * pitch + col / 8];
+                    const bool bit = ((byte >> (7 - (col % 8))) & 1u) != 0;
+                    mask_samples[static_cast<size_t>(row) * sm_w + col] = bit ? 0xFFu : 0x00u;
+                  }
+              }
+            smask_bpc = 8;
+          }
         else
           {
             LOG_S(WARNING) << "SMask has no decoded stream data for xobject_key=" << xobject_key;
@@ -1296,7 +1331,7 @@ namespace pdflib
     // eight columns to be the whole row, so the transparent part of the image
     // keeps painting. Expand to one byte per sample first.
     std::vector<uint8_t> smask_unpacked;
-    if(smask_bpc != 8 and ccitt_samples.empty())
+    if(smask_bpc != 8 and mask_samples.empty())
       {
         const size_t row_bits = static_cast<size_t>(sm_w) * static_cast<size_t>(smask_bpc);
         const size_t row_bytes = (row_bits + 7u) / 8u;
@@ -1336,7 +1371,7 @@ namespace pdflib
       }
 
     const size_t smask_expected = static_cast<size_t>(sm_w) * sm_h;
-    if(smask_unpacked.empty() and ccitt_samples.empty()
+    if(smask_unpacked.empty() and mask_samples.empty()
        and smask_buf->getSize() < smask_expected)
       {
         LOG_S(WARNING) << "SMask decoded stream too small for xobject_key=" << xobject_key
@@ -1357,7 +1392,7 @@ namespace pdflib
     out->resize(static_cast<size_t>(dst_w) * dst_h);
 
     auto const* src =
-      not ccitt_samples.empty() ? ccitt_samples.data()
+      not mask_samples.empty() ? mask_samples.data()
       : not smask_unpacked.empty() ? smask_unpacked.data()
       : reinterpret_cast<uint8_t const*>(smask_buf->getBuffer());
     auto const decode = smask.get_decode_array();
@@ -1378,8 +1413,8 @@ namespace pdflib
                 alpha = jpeg::apply_decode_component(alpha, decode[0], decode[1]);
               }
             // Stencil (/Mask): a 1-sample masks the pixel OUT, the inverse
-            // of /SMask's alpha reading. ccitt::decode returns 0 = dark =
-            // sample 0 = painted, so the same inversion applies there.
+            // of /SMask's alpha reading. The CCITT and JBIG2 samples above use
+            // 0 = dark = sample 0 = painted, so the same inversion applies there.
             (*out)[static_cast<size_t>(row) * dst_w + col] =
               stencil ? static_cast<uint8_t>(255 - alpha) : alpha;
           }

{docling_parse-7.22.2 → docling_parse-7.22.4}/src/render/blend2d_renderer.h

@@ -1590,7 +1590,8 @@ namespace pdflib
     // the canvas-space bounding rectangle of all touched points. Control
     // points give a conservative bbox (a Bézier never leaves its control
     // polygon's hull), which is what the clip skip-test needs.
-    BLPath make_shape_path(const shape_instruction& instr, BLRect& bbox) const;
+    BLPath make_shape_path(const shape_instruction& instr, BLRect& bbox,
+                           bool flatten_curves = false) const;
 
     // Draws a semi-transparent yellow placeholder over the bitmap destination
     // quad. This makes missing or invalid image data visible in debug renders.
@@ -3673,10 +3674,49 @@ namespace pdflib
   // ---------------------------------------------------------------------------
 
   inline BLPath renderer<BLEND2D>::make_shape_path(const shape_instruction& instr,
-                                                   BLRect& bbox) const
+                                                   BLRect& bbox,
+                                                   bool flatten_curves) const
   {
     BLPath path;
 
+    // Blend2D's curve stroker can repeatedly split a near-cusp quadratic
+    // without making progress at floating-point precision. Feed strokes a
+    // polyline instead, keeping the original cubic geometry for fills.
+    // Comparing the controls with the chord's degree-elevated controls also
+    // detects collinear reversals and loops (distance to a line does not).
+    const auto append_flattened_cubic = [&](const auto& self,
+                                            BLPoint p0, BLPoint p1,
+                                            BLPoint p2, BLPoint p3,
+                                            unsigned depth) -> void
+    {
+      constexpr double tolerance = 0.05; // canvas pixels, independent of scale
+      constexpr unsigned max_depth = 20;
+      const double error1 = std::hypot(
+        p1.x - (p0.x * (2.0 / 3.0) + p3.x / 3.0),
+        p1.y - (p0.y * (2.0 / 3.0) + p3.y / 3.0));
+      const double error2 = std::hypot(
+        p2.x - (p0.x / 3.0 + p3.x * (2.0 / 3.0)),
+        p2.y - (p0.y / 3.0 + p3.y * (2.0 / 3.0)));
+      if (depth == max_depth or std::max(error1, error2) <= tolerance)
+        {
+          path.line_to(p3.x, p3.y);
+          return;
+        }
+
+      const auto midpoint = [](BLPoint a, BLPoint b)
+      {
+        return BLPoint(a.x * 0.5 + b.x * 0.5, a.y * 0.5 + b.y * 0.5);
+      };
+      const BLPoint p01 = midpoint(p0, p1);
+      const BLPoint p12 = midpoint(p1, p2);
+      const BLPoint p23 = midpoint(p2, p3);
+      const BLPoint p012 = midpoint(p01, p12);
+      const BLPoint p123 = midpoint(p12, p23);
+      const BLPoint mid = midpoint(p012, p123);
+      self(self, p0, p01, p012, mid, depth + 1);
+      self(self, mid, p123, p23, p3, depth + 1);
+    };
+
     double x_min = std::numeric_limits<double>::infinity();
     double y_min = std::numeric_limits<double>::infinity();
     double x_max = -std::numeric_limits<double>::infinity();
@@ -3733,7 +3773,17 @@ namespace pdflib
                 const double y3 = canvas_y(py[k + 2]);
                 k += 3;
 
-                path.cubic_to(x1, y1, x2, y2, x3, y3);
+                if (flatten_curves)
+                  {
+                    const BLPoint p0 = path.vertex_data()[path.size() - 1];
+                    append_flattened_cubic(append_flattened_cubic, p0,
+                                          BLPoint(x1, y1), BLPoint(x2, y2),
+                                          BLPoint(x3, y3), 0);
+                  }
+                else
+                  {
+                    path.cubic_to(x1, y1, x2, y2, x3, y3);
+                  }
                 accumulate(x1, y1);
                 accumulate(x2, y2);
                 accumulate(x3, y3);
@@ -3938,7 +3988,8 @@ namespace pdflib
                         << " (not implemented by the Blend2D stroker)";
           }
 
-        ctx.stroke_path(path);
+        BLRect stroke_bbox;
+        ctx.stroke_path(make_shape_path(instr, stroke_bbox, true));
       }
   }
 

docling_parse-7.22.4/tests/test_unit_jbig2_masks.py

@@ -0,0 +1,318 @@
+#!/usr/bin/env python
+"""Images stencilled by a JBIG2-coded /Mask.
+
+An image XObject's /Mask may be a stream: a 1-bit /ImageMask whose 0-samples
+let the image through and whose 1-samples knock it out (ISO 32000-1, 8.9.6.3).
+MRC-compressed scans are built this way: a JPEG 2000 foreground that carries
+the text colour, stencilled by a JBIG2 mask holding the glyph shapes. QPDF
+cannot decode JBIG2, so the mask has to be decoded here like the page's other
+JBIG2 images, or the foreground is painted across the whole page.
+"""
+
+from __future__ import annotations
+
+import struct
+import zlib
+
+from tests.pdf_builder import render_page, simple_page_pdf, stream_object
+from tests.rendering_regression import assert_color_near, center_color, region_image
+
+WHITE = (255, 255, 255)
+RED = (255, 0, 0)
+
+# Every fixture draws its image over the middle 100x100 points of a 200x200
+# page. The mask lets the image through over the middle half of the image in
+# both directions, so the painted part lands on the middle 50x50 points of the
+# page. Boxes are (left, top, right, bottom) in points from the top-left.
+OPENING = (90.0, 90.0, 110.0, 110.0)
+# Inside the image, outside the opening: masked out, so the page shows.
+MASKED = (55.0, 55.0, 70.0, 70.0)
+
+
+def middle_half(extent: int) -> range:
+    return range(extent // 4, 3 * extent // 4)
+
+
+# ---------------------------------------------------------------------------
+# A JBIG2 encoder for the fixtures: an MQ arithmetic coder (T.88, Annex E) and
+# a generic region coded with template 0 and the nominal adaptive pixels
+# (6.2.5.3). This is how MRC scanners code their masks. The control test below
+# draws the same codestream through the renderer's existing JBIG2 image path.
+# ---------------------------------------------------------------------------
+
+# (Qe, NMPS, NLPS, SWITCH), Table E.1.
+MQ_STATES = [
+    (0x5601, 1, 1, 1),
+    (0x3401, 2, 6, 0),
+    (0x1801, 3, 9, 0),
+    (0x0AC1, 4, 12, 0),
+    (0x0521, 5, 29, 0),
+    (0x0221, 38, 33, 0),
+    (0x5601, 7, 6, 1),
+    (0x5401, 8, 14, 0),
+    (0x4801, 9, 14, 0),
+    (0x3801, 10, 14, 0),
+    (0x3001, 11, 17, 0),
+    (0x2401, 12, 18, 0),
+    (0x1C01, 13, 20, 0),
+    (0x1601, 29, 21, 0),
+    (0x5601, 15, 14, 1),
+    (0x5401, 16, 14, 0),
+    (0x5101, 17, 15, 0),
+    (0x4801, 18, 16, 0),
+    (0x3801, 19, 17, 0),
+    (0x3401, 20, 18, 0),
+    (0x3001, 21, 19, 0),
+    (0x2801, 22, 19, 0),
+    (0x2401, 23, 20, 0),
+    (0x2201, 24, 21, 0),
+    (0x1C01, 25, 22, 0),
+    (0x1801, 26, 23, 0),
+    (0x1601, 27, 24, 0),
+    (0x1401, 28, 25, 0),
+    (0x1201, 29, 26, 0),
+    (0x1101, 30, 27, 0),
+    (0x0AC1, 31, 28, 0),
+    (0x09C1, 32, 29, 0),
+    (0x08A1, 33, 30, 0),
+    (0x0521, 34, 31, 0),
+    (0x0441, 35, 32, 0),
+    (0x02A1, 36, 33, 0),
+    (0x0221, 37, 34, 0),
+    (0x0141, 38, 35, 0),
+    (0x0111, 39, 36, 0),
+    (0x0085, 40, 37, 0),
+    (0x0049, 41, 38, 0),
+    (0x0025, 42, 39, 0),
+    (0x0015, 43, 40, 0),
+    (0x0009, 44, 41, 0),
+    (0x0005, 45, 42, 0),
+    (0x0001, 45, 43, 0),
+    (0x5601, 46, 46, 0),
+]
+
+
+class MQEncoder:
+    """The encoder of T.88 E.2, with the byte before the output as a dummy."""
+
+    def __init__(self) -> None:
+        self.a, self.c, self.ct = 0x8000, 0, 12
+        self.out = bytearray([0])
+        self.state: dict[int, int] = {}
+        self.mps: dict[int, int] = {}
+
+    def encode(self, bit: int, cx: int) -> None:
+        index, mps = self.state.get(cx, 0), self.mps.get(cx, 0)
+        qe, nmps, nlps, switch = MQ_STATES[index]
+        self.a -= qe
+        if bit == mps:
+            if self.a & 0x8000:
+                self.c += qe
+                return
+            if self.a < qe:
+                self.a = qe
+            else:
+                self.c += qe
+            self.state[cx] = nmps
+        else:
+            if self.a < qe:
+                self.c += qe
+            else:
+                self.a = qe
+            if switch:
+                self.mps[cx] = 1 - mps
+            self.state[cx] = nlps
+        self.renormalise()
+
+    def renormalise(self) -> None:
+        while True:
+            self.a = (self.a << 1) & 0xFFFF
+            self.c = (self.c << 1) & 0xFFFFFFFF
+            self.ct -= 1
+            if self.ct == 0:
+                self.byte_out()
+            if self.a & 0x8000:
+                return
+
+    def byte_out(self) -> None:
+        if self.out[-1] == 0xFF:
+            self.out.append(self.c >> 20)
+            self.c &= 0xFFFFF
+            self.ct = 7
+            return
+        if self.c >= 0x8000000:
+            self.out[-1] += 1
+            self.c &= 0x7FFFFFF
+            if self.out[-1] == 0xFF:
+                self.out.append(self.c >> 20)
+                self.c &= 0xFFFFF
+                self.ct = 7
+                return
+        self.out.append(self.c >> 19)
+        self.c &= 0x7FFFF
+        self.ct = 8
+
+    def flush(self) -> bytes:
+        top = self.c + self.a
+        self.c |= 0xFFFF
+        if self.c >= top:
+            self.c -= 0x8000
+        self.c = (self.c << self.ct) & 0xFFFFFFFF
+        self.byte_out()
+        self.c = (self.c << self.ct) & 0xFFFFFFFF
+        self.byte_out()
+        if self.out[-1] != 0xFF:
+            self.out.append(0xFF)
+        self.out.append(0xAC)
+        return bytes(self.out[1:])
+
+
+# Template 0's nominal adaptive pixels A1..A4, as (dx, dy).
+TEMPLATE0_AT = [(3, -1), (-3, -1), (2, -2), (-2, -2)]
+
+
+def generic_region_codes(pixels: list[list[int]]) -> bytes:
+    """Arithmetic-code a bitmap (1 = black) as a template-0 generic region."""
+    height, width = len(pixels), len(pixels[0])
+
+    def pixel(x: int, y: int) -> int:
+        return pixels[y][x] if 0 <= x < width and 0 <= y < height else 0
+
+    def run(y: int, first: int, last: int, x: int) -> int:
+        value = 0
+        for dx in range(first, last + 1):
+            value = (value << 1) | pixel(x + dx, y)
+        return value
+
+    (a1x, a1y), (a2x, a2y), (a3x, a3y), (a4x, a4y) = TEMPLATE0_AT
+    encoder = MQEncoder()
+    for y in range(height):
+        for x in range(width):
+            context = (
+                run(y, -4, -1, x)
+                | pixel(x + a1x, y + a1y) << 4
+                | run(y - 1, -2, 2, x) << 5
+                | pixel(x + a2x, y + a2y) << 10
+                | pixel(x + a3x, y + a3y) << 11
+                | run(y - 2, -1, 1, x) << 12
+                | pixel(x + a4x, y + a4y) << 15
+            )
+            encoder.encode(pixels[y][x], context)
+    return encoder.flush()
+
+
+def jbig2_segment(number: int, segment_type: int, data: bytes) -> bytes:
+    """One JBIG2 segment (T.88, 7.2): no referred-to segments, page 1."""
+    return struct.pack(">IBBBI", number, segment_type, 0, 1, len(data)) + data
+
+
+def jbig2_stream(width: int, height: int) -> bytes:
+    """An embedded JBIG2 stream (T.88, Annex D.3), black over the middle half.
+
+    JBIG2 reads a black pixel as 1 and the PDF filter hands it back as 0, the
+    sample that paints (or, in a /Mask, lets the image through).
+    """
+    pixels = [
+        [
+            int(x in middle_half(width) and y in middle_half(height))
+            for x in range(width)
+        ]
+        for y in range(height)
+    ]
+    page_information = struct.pack(">IIIIBH", width, height, 0, 0, 0, 0)
+    region_information = struct.pack(">IIIIB", width, height, 0, 0, 0)
+    # Flags 0: arithmetic coding, template 0, no typical prediction.
+    region_header = bytes([0x00]) + struct.pack(
+        ">8b", *(v for at in TEMPLATE0_AT for v in at)
+    )
+
+    return (
+        jbig2_segment(0, 48, page_information)
+        + jbig2_segment(
+            1,
+            38,  # immediate generic region
+            region_information + region_header + generic_region_codes(pixels),
+        )
+        + jbig2_segment(2, 49, b"")  # end of page
+    )
+
+
+def jbig2_mask_object(width: int, height: int) -> bytes:
+    return stream_object(
+        f"/Type /XObject /Subtype /Image /Width {width} /Height {height} "
+        "/ImageMask true /BitsPerComponent 1 /Filter /JBIG2Decode",
+        jbig2_stream(width, height),
+    )
+
+
+def masked_image_page(
+    *, image_size: int, mask_size: int, compress_image: bool = False
+) -> bytes:
+    """A red image stencilled by a JBIG2 /Mask, over the middle of the page."""
+    samples = bytes(RED) * (image_size * image_size)
+    filter_entry = ""
+    if compress_image:
+        samples = zlib.compress(samples)
+        filter_entry = " /Filter /FlateDecode"
+
+    return simple_page_pdf(
+        "q 100 0 0 100 50 50 cm /Im0 Do Q",
+        resources="/XObject << /Im0 5 0 R >>",
+        extra_objects=[
+            stream_object(
+                f"/Type /XObject /Subtype /Image /Width {image_size} "
+                f"/Height {image_size} /ColorSpace /DeviceRGB "
+                f"/BitsPerComponent 8 /Mask 6 0 R{filter_entry}",
+                samples,
+            ),
+            jbig2_mask_object(mask_size, mask_size),
+        ],
+    )
+
+
+def assert_opening_rendered(result, what: str) -> None:
+    assert_color_near(
+        center_color(region_image(result, OPENING)),
+        RED,
+        tolerance=30,
+        what=f"opening of {what}",
+    )
+    assert_color_near(
+        center_color(region_image(result, MASKED)),
+        WHITE,
+        tolerance=30,
+        what=f"masked-out part of {what}",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+
+def test_jbig2_image_mask_paints_its_black_pixels():
+    """The fixture's codestream, drawn as a plain /ImageMask, paints the opening.
+
+    This path decoded JBIG2 already; it keeps the bits the /Mask tests below
+    rely on honest.
+    """
+    size = 64
+    pdf = simple_page_pdf(
+        "q 1 0 0 rg 100 0 0 100 50 50 cm /Im0 Do Q",
+        resources="/XObject << /Im0 5 0 R >>",
+        extra_objects=[jbig2_mask_object(size, size)],
+    )
+    assert_opening_rendered(render_page(pdf), "a JBIG2 /ImageMask")
+
+
+def test_jbig2_mask_stencils_an_image_of_the_same_size():
+    result = render_page(masked_image_page(image_size=64, mask_size=64))
+    assert_opening_rendered(result, "an image under a same-size JBIG2 /Mask")
+
+
+def test_jbig2_mask_stencils_a_lower_resolution_image():
+    """An MRC foreground is coarser than its mask; the mask keeps its detail."""
+    result = render_page(
+        masked_image_page(image_size=2, mask_size=64, compress_image=True)
+    )
+    assert_opening_rendered(result, "a 2x2 image under a 64x64 JBIG2 /Mask")