vpype plugin that cuts lines using named filled SVG objects or groups as masks.
Русская версия: README.ru.md 🪆
Comparison of vmask and occult
vpype-vmask adds a vmaskcut command to vpype.
It reads an SVG file, finds filled objects or groups whose names match a given pattern, converts them into polygons, and uses those polygons as masks to cut or remove parts of lines from the vpype document.
This is useful when you want to remove line segments hidden under filled areas, for example objects named vmask, mask, cutout, etc.
- Mask objects must be filled.
- Objects with
fill="none"are ignored. - The plugin checks these names:
idinkscape:labelclass
- The SVG passed to
--svgshould use the same coordinate system as the vpype document. - Usually you run it like this:
vpype read input.svg vmaskcut --svg input.svg --name vmask write out.svgFrom GitHub:
python -m pip install "git+https://github.com/klimromanyuk/vpype-vmask.git"Install a specific tag:
python -m pip install "git+https://github.com/klimromanyuk/vpype-vmask.git@v0.1.0"For development:
git clone https://github.com/klimromanyuk/vpype-vmask.git
cd vpype-vmask
python -m pip install -e .If vpype is installed via pipx, install the plugin into vpype's environment instead:
pipx inject vpype "git+https://github.com/klimromanyuk/vpype-vmask.git"Basic usage:
vpype read input.svg vmaskcut --svg input.svg --name vmask write out.svgShow help:
vpype vmaskcut --helpTo list all names found in the SVG:
vpype read input.svg vmaskcut --svg input.svg --list-namesThis prints id, inkscape:label, and class attributes found in the SVG.
If masks are not found, use:
vpype read input.svg vmaskcut --svg input.svg --name vmask --debug write out.svg| Option | Default | Description |
|---|---|---|
--svg FILE |
required | Source SVG file from which named masks are read. |
--name TEXT |
vmask |
Name of an object or group treated as a mask. |
--match MODE |
startswith |
Matching mode: exact, startswith, contains, or regex. |
--target-layers TEXT |
all layers | Layer IDs to process, separated by commas, semicolons, or spaces. |
--mode MODE |
below |
below: cut only lines below mask outlines; all: cut all lines with all masks. |
--unfound MODE |
all |
What to do with masks whose outline is not found: all or skip. |
--remove-mask/--keep-mask |
--remove-mask |
Remove lines coinciding with mask outlines. |
--remove-position MODE |
below |
Which coincident outline to remove: below or above. |
--tol LENGTH |
0.05mm |
Tolerance for finding mask outlines and removing coincident lines. |
--sample-tol LENGTH |
same as --tol |
Tolerance for approximating SVG curves. |
--min-area FLOAT |
1e-6 |
Ignore masks smaller than this area, in square SVG user units. |
--min-length LENGTH |
0.05mm |
Discard line pieces shorter than this after cutting. |
--list-names |
off | Print all id, inkscape:label, and class names found in the SVG and exit. |
--debug |
off | Print diagnostic information. |
Length options accept:
px
mm
cm
in
pt
pc
Example:
--tol 0.1mmUse objects whose names start with vmask:
vpype read input.svg vmaskcut --svg input.svg --name vmask write out.svgUse objects whose names contain mask:
vpype read input.svg vmaskcut --svg input.svg --name mask --match contains write out.svgUse an exact object name:
vpype read input.svg vmaskcut --svg input.svg --name MyMask --match exact write out.svgUse a regular expression:
vpype read input.svg vmaskcut --svg input.svg --name "^mask-[0-9]+$" --match regex write out.svgCut all lines with all masks, regardless of order:
vpype read input.svg vmaskcut --svg input.svg --name vmask --mode all write out.svgKeep the mask outline in the result:
vpype read input.svg vmaskcut --svg input.svg --name vmask --keep-mask write out.svgSkip masks whose outline was not found in the vpype document:
vpype read input.svg vmaskcut --svg input.svg --name vmask --unfound skip write out.svgProcess only layers 1 and 2:
vpype read input.svg vmaskcut --svg input.svg --name vmask --target-layers 1,2 write out.svgIn below mode, the plugin tries to find the mask boundary among the lines in the current vpype layer.
Line order inside a layer is treated as stacking order:
- earlier lines are lower;
- later lines are higher.
If a mask boundary is found, only lines below that boundary are cut.
If the boundary is not found, the behavior depends on --unfound:
all: apply the mask to all lines;skip: ignore this mask.
If you want simpler behavior, use:
--mode allMIT