fix rasterization of clipping masks based on vector images

- previously the vector would be rasterized at the width/height of the PDF or SVG, then that bitmap mask would be scaled - now the vector image is scaled to the size it will occupy on the canvas *before* being rasterized, so the masking is still pixel-based, but will no longer be super-low res - partially addresses #83 (though it doesn't provide the vector-based mask the user exptected)
samizdatco · Jul 9, 2026 · Jul 9, 2026 · Jul 9, 2026 · Jul 9, 2026 · Jul 9, 2026
commit 41556e2bd82509ee3470ebffefa400ac23e1e55a
diff --git a/plotdevice/gfx/effects.py b/plotdevice/gfx/effects.py
@@ -320,7 +320,7 @@ def set(self):
             singlechannel = ciFilter(self.channel, self.bmp._ciImage)
             greyscale = ciFilter(self.invert, singlechannel)
             ci_ctx = CIContext.contextWithOptions_(None)
-            maskRef = ci_ctx.createCGImage_fromRect_(greyscale, ((0,0), self.bmp.size))
+            maskRef = ci_ctx.createCGImage_fromRect_(greyscale, ((0,0), self.bmp._screen_size))
 
             # turn the image into an ‘imagemask’ cg-image
             cg_mask = CGImageMaskCreate(CGImageGetWidth(maskRef),

diff --git a/plotdevice/gfx/image.py b/plotdevice/gfx/image.py
@@ -15,7 +15,7 @@
 from .geometry import Region, Size, Point, Transform, CENTER
 from .atoms import TransformMixin, EffectsMixin, FrameMixin, Grob
 from .colors import CMYK
-from . import _ns_context
+from . import _ns_context, _cg_port
 
 _ctx = None
 __all__ = ("Image", 'ImageWriter')
@@ -174,21 +174,48 @@ def _nsBitmap(self):
             if isinstance(bitmap, NSBitmapImageRep):
                 break
         else:
-            # ...otherwise convert the vector image to a bitmap
-            # (note that this should use _screen_transform somehow but currently doesn't)
+            # ...otherwise convert the vector image to a bitmap at its native size.
+            # it will only be used for a hasAlpha() check in effects.py, so the actual
+            # pixel data needn't match its _screen_size
             tiffdata = self._nsImage.TIFFRepresentation()
             image = NSImage.alloc().initWithData_(tiffdata)
             bitmap = image.representations()[0]
         return bitmap
 
     @property
     def _ciImage(self):
+        """A CIImage suitable for use as a clip()/mask() stencil.
+
+        Raster sources are used as-is. Vector sources are scaled to the size
+        they'll actually occupy on the canvas before being rasterized.
+        """
+
+        # if the image is raster-based, use its bitmap as-is
+        for bitmap in self._nsImage.representations():
+            if isinstance(bitmap, NSBitmapImageRep):
+                break
+        else:
+            # if vector-based, rasterize it at its 'actual' on-screen size
+            w, h = self._screen_size
+
+            # create an offscreen bitmap context and rasterize the scaled image into it
+            bitmap_opts = kCGImageAlphaPremultipliedFirst | kCGBitmapByteOrder32Host
+            bitmap_ctx = CGBitmapContextCreate(None, w, h, 8, w*4, CGColorSpaceCreateDeviceRGB(), bitmap_opts)
+            NSGraphicsContext.saveGraphicsState()
+            NSGraphicsContext.setCurrentContext_(
+              NSGraphicsContext.graphicsContextWithCGContext_flipped_(bitmap_ctx, True)
+            )
+            self._nsImage.drawInRect_fromRect_operation_fraction_(((0,0),(w,h)), NSZeroRect, NSCompositeSourceOver, 1.0)
+            NSGraphicsContext.restoreGraphicsState() # NB: class-level restore also resets currentContext
+
+            bitmap = NSBitmapImageRep.alloc().initWithCGImage_(CGBitmapContextCreateImage(bitmap_ctx))
+
         # core-image needs to be told to compensate for our flipped coords
         flip = NSAffineTransform.transform()
-        flip.translateXBy_yBy_(0, self.size.height)
+        flip.translateXBy_yBy_(0, bitmap.pixelsHigh())
         flip.scaleXBy_yBy_(1,-1)
 
-        ciImage = CIImage.alloc().initWithBitmapImageRep_(self._nsBitmap)
+        ciImage = CIImage.alloc().initWithBitmapImageRep_(bitmap)
         transform = CIFilter.filterWithName_("CIAffineTransform")
         transform.setValue_forKey_(ciImage, "inputImage")
         transform.setValue_forKey_(flip, "inputTransform")
@@ -249,6 +276,29 @@ def _screen_transform(self):
         xf.scale(factor)           # scale to fit size constraints (if any)
         return xf
 
+    @property
+    def _screen_size(self):
+        """Returns the image's real pixel dimensions.
+
+        Raster-backed images return their native size, but vector-based images incorporate
+        the canvas's current CTM and the image's scaling based on its _screen_transform."""
+
+        # if the image is raster-based, use its native size
+        for bitmap in self._nsImage.representations():
+            if isinstance(bitmap, NSBitmapImageRep):
+                return bitmap.pixelsWide(), bitmap.pixelsHigh()
+
+        # if vector-based, use the canvas's CTM and the image's _screen_transform to
+        # determine its 'actual' size (rather than just using its mediabox 1:1)
+        ctm = CGContextGetCTM(_cg_port())
+        ctm_scale = max(math.hypot(ctm.a, ctm.b), math.hypot(ctm.c, ctm.d))
+        xf_a, xf_b, xf_c, xf_d, _, _ = self._screen_transform.matrix
+        xf_scale = max(math.hypot(xf_a, xf_b), math.hypot(xf_c, xf_d))
+        scale = max(ctm_scale * xf_scale, 1.0)
+        src_w, src_h = self._nsImage.size()
+
+        return max(1, round(src_w * scale)), max(1, round(src_h * scale))
+
     def _draw(self):
         """Draw an image on the given coordinates."""
 
@@ -390,4 +440,3 @@ def finish(self):
             if self.session.writer.doneWriting():
                 break
             time.sleep(0.1)
-
diff --git a/plotdevice/lib/cocoa.py b/plotdevice/lib/cocoa.py
@@ -4,7 +4,7 @@
                    CGColorSpaceCreateDeviceCMYK, CGColorSpaceCreateDeviceRGB, CGContextAddPath, CGContextAddRect, \
                    CGContextBeginPath, CGContextBeginTransparencyLayer, CGContextBeginTransparencyLayerWithRect, \
                    CGContextClearRect, CGContextClearRect, CGContextClip, CGContextClipToMask, CGContextDrawPath, \
-                   CGContextEndTransparencyLayer, CGContextEOClip, CGContextRestoreGState, CGContextSaveGState, \
+                   CGContextEndTransparencyLayer, CGContextEOClip, CGContextGetCTM, CGContextRestoreGState, CGContextSaveGState, \
                    CGContextSetAlpha, CGContextSetBlendMode, CGContextSetFillColorWithColor, CGContextSetLineCap, \
                    CGContextSetLineDash, CGContextSetLineJoin, CGContextSetLineWidth, \
                    CGContextSetStrokeColorWithColor, CGDataConsumerCreateWithCFData, CGImageDestinationAddImage, \
@@ -56,7 +56,8 @@
                        NSIntersectionRect, NSLocale, NSLog, NSMacOSRomanStringEncoding, NSMakeRange, NSMidX, NSMidY, \
                        NSMutableAttributedString, NSMutableData, NSNotificationCenter, NSObject, NSOffsetRect, \
                        NSOperationQueue, NSPoint, NSRect, NSRectFromString, NSSelectorFromString, NSSize, NSString, \
-                       NSStringFromRect, NSTimer, NSTimeZone, NSURL, NSUserDefaults, NSUTF8StringEncoding, NSWidth
+                       NSStringFromRect, NSTimer, NSTimeZone, NSURL, NSUserDefaults, NSUTF8StringEncoding, NSWidth, \
+                       NSZeroRect
 from LaunchServices import kUTTypePNG, kUTTypeJPEG, kUTTypeGIF, kUTTypeTIFF
 from WebKit import WebView
 from objc import IBOutlet, IBAction
diff --git a/tests/_in/tiny-triangle.pdf b/tests/_in/tiny-triangle.pdf
diff --git a/tests/_ref/compositing/clip-vector-image.png b/tests/_ref/compositing/clip-vector-image.png
diff --git a/tests/_ref/compositing/mask-vector-image.png b/tests/_ref/compositing/mask-vector-image.png
diff --git a/tests/compositing.py b/tests/compositing.py
@@ -42,6 +42,13 @@ def test_clip_text(self):
         with clip(text('Hi', 5, 100)):
             image('tests/_in/plaid.png')
 
+    @reference('compositing/clip-vector-image.png')
+    def test_clip_image_vector(self):
+        size(125, 125)
+        # ensure tiny PDF is scaled up before rasterizing into a larger mask
+        with clip(image('tests/_in/tiny-triangle.pdf', width=125, height=125)):
+            image('tests/_in/plaid.png')
+
     @reference('compositing/mask.png')
     def test_mask(self):
         # ref/Compositing/commands/mask()
@@ -64,6 +71,13 @@ def test_mask_text(self):
         with mask(text('Hi', 5, 100)):
             image('tests/_in/plaid.png')
 
+    @reference('compositing/mask-vector-image.png')
+    def test_mask_image_vector(self):
+        size(125, 125)
+        # ensure tiny PDF is scaled up before rasterizing into a larger mask
+        with mask(image('tests/_in/tiny-triangle.pdf', width=125, height=125)):
+            image('tests/_in/plaid.png')
+
     @reference('compositing/shadow-multi.png')
     def test_shadow_multi(self):
         # ref/Compositing/commands/shadow()