Support for `clip()` in p5.plotSvg

[golanlevin]

Summary

p5.plotSvg does not currently support p5.js’s clip() functionality.

Background

p5.js implements clipping by delegating to the HTML Canvas API: this.drawingContext.clip();. This modifies the canvas’s internal clip region in the graphics state. However: the Canvas API does not expose the resulting clipped geometry. There is no method to retrieve things like: the current clip region, the intersection result, nor the post-clip path outlines. drawingContext is a raster-oriented state machine, not a vector geometry engine. Therefore, it is not possible to extract plotter-ready clipped paths from the browser after the fact.

Why Proper Support Is Nontrivial

To fully support clipping in a plotter-oriented exporter like p5.plotSvg, the exporter would need to compute the actual clipped geometry itself. The correct solution would require things like: Robust polygon clipping, Bézier curve clipping, and support for: holes, winding rules (nonzero vs even-odd), nested clips; and handling of numeric tolerances, self-intersections, and degenerate segments. In other words, this becomes a full computational geometry problem involving boolean operations on complex paths. This is substantial engineering work and likely requires a dedicated geometry library or a carefully designed internal path model.

Provisional Solution

A practical intermediate approach: When clip() is used, export SVG <clipPath> definitions instead of computing boolean geometry. Wrap affected elements in:

<g clip-path="url(#clipId)">
  ...
</g>

Also, emit a clear runtime warning in p5.plotSvg such as: "Warning: SVG contains <clipPath> elements. These are not plotter-ready. You must flatten clip paths using an external tool before plotting."

Flattening Clip Paths for Plotting

SVG clip paths are rendering instructions, not actual geometry. Plotters will not obey them directly. To convert clipped SVG into plotter-ready paths, a flattening step is required. One suitable tool is vpype-clipflatten. This is a CLI plugin for vpype, available at https://github.com/Sladix/vpype-clipflatten, which uses Shapely to compute intersections, and converts into actual clipped geometry. Example usage:

vpype clipflatten input.svg write output.svg

After this step, the resulting SVG should contain real intersected paths suitable for plotting.

Recommended Roadmap

• Implement semantic export of <clipPath>
• Emit user warning
• Document required flattening step (e.g., vpype-clipflatten)

Conclusion

There is no browser-side "silver bullet" for extracting clipped paths from drawingContext. Full support requires extensive computational geometry. A pragmatic solution is to export SVG clip paths and require a downstream flattening step such as vpype-clipflatten.