Skip to content

About

Cut vpype lines with named filled SVG masks. Hidden-line removal for pen plotters.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

vpype-vmask

vpype plugin that cuts lines using named filled SVG objects or groups as masks.

Русская версия: README.ru.md 🪆


Demo

vmask demo only occult demo
Comparison of vmask and occult

What it does

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.


Important notes

  • Mask objects must be filled.
  • Objects with fill="none" are ignored.
  • The plugin checks these names:
    • id
    • inkscape:label
    • class
  • The SVG passed to --svg should 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.svg

Installation

From 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"

Usage

Basic usage:

vpype read input.svg vmaskcut --svg input.svg --name vmask write out.svg

Show help:

vpype vmaskcut --help

Finding mask names

To list all names found in the SVG:

vpype read input.svg vmaskcut --svg input.svg --list-names

This prints id, inkscape:label, and class attributes found in the SVG.


Debugging

If masks are not found, use:

vpype read input.svg vmaskcut --svg input.svg --name vmask --debug write out.svg

Options

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.1mm

Examples

Use objects whose names start with vmask:

vpype read input.svg vmaskcut --svg input.svg --name vmask write out.svg

Use objects whose names contain mask:

vpype read input.svg vmaskcut --svg input.svg --name mask --match contains write out.svg

Use an exact object name:

vpype read input.svg vmaskcut --svg input.svg --name MyMask --match exact write out.svg

Use a regular expression:

vpype read input.svg vmaskcut --svg input.svg --name "^mask-[0-9]+$" --match regex write out.svg

Cut all lines with all masks, regardless of order:

vpype read input.svg vmaskcut --svg input.svg --name vmask --mode all write out.svg

Keep the mask outline in the result:

vpype read input.svg vmaskcut --svg input.svg --name vmask --keep-mask write out.svg

Skip masks whose outline was not found in the vpype document:

vpype read input.svg vmaskcut --svg input.svg --name vmask --unfound skip write out.svg

Process only layers 1 and 2:

vpype read input.svg vmaskcut --svg input.svg --name vmask --target-layers 1,2 write out.svg

How --mode below works

In 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 all

License

MIT

About

Cut vpype lines with named filled SVG masks. Hidden-line removal for pen plotters.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages