vpype-clipflatten

A vpype plugin that reads SVG files and flattens clipPath elements into geometry.

The Problem

When working with SVGs for pen plotting, clipPath elements are often ignored by conversion tools. This means paths that should be clipped to a specific region are drawn in full, extending beyond their intended boundaries.

The Solution

vpype-clipflatten parses SVG files, identifies all clipPath definitions and their associations, and clips each element according to its assigned clip path. The result is geometry that respects the original clipping regions.

Installation

If you installed vpype with pipx:

pipx inject vpype vpype-clipflatten

If you installed vpype with pip:

pip install vpype-clipflatten

For development:

git clone https://github.com/yourusername/vpype-clipflatten
cd vpype-clipflatten
pip install -e .

Usage

Basic usage:

vpype clipflatten input.svg write output.svg

With other vpype commands:

vpype clipflatten input.svg linemerge linesort write output.svg

Increase sample resolution for complex curved clip paths:

vpype clipflatten input.svg --samples 500 write output.svg

Options

Option	Short	Description
--samples	-s	Number of samples for approximating curved paths (default: 200)
--layer	-l	Target layer (inherited from vpype)

Supported Features

Clip Path Shapes

The following shapes are supported inside <clipPath> elements:

• <path> - SVG path data
• <rect> - Rectangles (including rounded corners)
• <circle> - Circles
• <ellipse> - Ellipses
• <polygon> - Polygons

Visual Elements

All standard SVG visual elements are processed:

• <path>
• <rect>
• <circle>
• <ellipse>
• <polygon>
• <polyline>
• <line>

Transforms

SVG transforms are fully supported and properly accumulated through the element hierarchy:

• translate(x, y)
• scale(sx, sy)
• rotate(angle, cx, cy)
• skewX(angle)
• skewY(angle)
• matrix(a, b, c, d, e, f)

Clip Path Inheritance

Clip paths applied to groups (<g>) are properly inherited by all child elements.

Example

Input SVG with clip paths:

<svg xmlns="http://www.w3.org/2000/svg" width="200" height="200">
  <defs>
    <clipPath id="circleClip">
      <circle cx="100" cy="100" r="50"/>
    </clipPath>
  </defs>

  <g clip-path="url(#circleClip)">
    <line x1="0" y1="100" x2="200" y2="100" stroke="black"/>
  </g>
</svg>

The horizontal line will be clipped to only the portion inside the circle.

Limitations

• CSS clip-path: Only the clip-path attribute is supported, not CSS clip-path properties in <style> blocks
• clipPathUnits: The clipPathUnits attribute is not yet supported (assumes userSpaceOnUse)
• Use elements: <use> elements inside clip paths are not yet supported
• Text: <text> elements are not converted to geometry

How It Works

1. Parse the SVG file using Python's xml.etree.ElementTree
2. Build a dictionary of all clipPath definitions
3. Walk the SVG tree, tracking accumulated transforms and active clip paths
4. For each visual element, convert to Shapely geometry
5. Apply transforms and clip using Shapely's intersection() method
6. Convert back to vpype LineCollection

Dependencies

• vpype >= 1.14
• Shapely >= 2.0
• svgpathtools
• NumPy

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.