Add support for global and per-layer metadata

[abey79]

Description

This PR introduce per-layer and global metadata to the vpype pipeline. Metadata takes the form of a free-form set of properties identified by a string. Supported types include str, int, float, and vpype.Color (as color in the UI).

Low-level inspection, modification and deletion of both global and layer properties can be done with a new set of low-level commands prefixed by prop-:

# global operations
propset -g -t int my_prop 18
proplist -g
propget -g my_prop
propdel -g my_prop
propclear -g

# per layer(s) operations
propset -l 1 -t str my_prop my_value
proplist -l 1
propget -l 1 my_prop
propdel -l all my_prop
propclear -l 1

Properties whose name is prefixed by vp: are used by vpype for a number of features, some of which are newly introduced in this PR. Such properties are referred to as "system properties".

Layer system properties:

• vp:color (color): the color to be used for the layer
• vp:pen_width (float): the pen width to be used for the layer
• vp:name (float): the name of the layer (in the inkscape:label SVG attribute sense)

Global system properties:

• vp:page_size: the page size (formerly stored as an instance attribute to the vp.Document class

The show and write command now take into account the above layer system properties. The page size related commands (pagesize and layout) now act on the vp:page_size global system property.

New, high-level commands are introduced to interact with the new layer system properties:

• name: sets the name of a given layer
• color: changes the color for a given layer
• penwidth: changes the pen-width of a given layer
• pens: apply a pre-defined set of per-layer name, color, and/or pen width to the pipelines, based on a template defined in a config file (rgb and cmyk templates are bundled in the new config file)

In addition to populating the system properties (when possible), the read command now extracts a number of SVG attributes and stores them as properties (prefixed with svg:). Optionally, the write command can attempt to restore those properties when possible. Note: since properties are per layer, SVG attributes are saved only if they are shared by all the geometries contained in a given layer.

The layer operation commands are updated to handle metadata:

• When a single source layer is specified and --prob is not used, the lcopy and lmove commands now copy the source layer's properties to the destination layer (possibly overwriting existing properties).
• When --prob is not used, the lswap command now swaps the layer properties as well.
• These behaviours may be disabled with the --no-prop option.

API changes:

• vpype.Document and vpype.LineCollection have been extended to support operation on their metadata (through the use of a mix-in class)

Other changes:

• the bundled config file is renamed to vpype_config.toml (since it's no longer specific to HPGL features)
• stat command now display all the metadata in the pipeline
• added a warning when a layer passed to --layer doesn't exist
• tests: added a few SVG test cases
• doc: several addition/changes relative to metadata
• doc: some minor fixes

Fixes #145 and #213

TODO:

• populate vp:name in read_[multilayer_]svg()
• finalize commands
• add document-level metadata
• change link to config file in cookbook.rst
• test read -m
• use metadata in write_svg()
• test: add viewer tests depending on metadata (Fix failing viewer tests on M1 mac and add metadata-specific viewer tests #375)
• doc: add metadata paragraph in fundamentals
• doc: add cookbook chapters (incl custom pen config)
• readme command list
• finalise vpype viewer
• propset must accept units for float/int values

Checklist

• feature/fix implemented
• code formatting ok (black and isort)
• mypy vpype vpype_cli tests returns no error
• tests added/updated and pytest succeeds
• documentation added/updated
  • command docstring and option/argument help
  • README.md updated (Feature Overview)
  • CHANGELOG.md updated
  • RTD doc updated and building with no error (make clean && make html in docs/)

[codecov]

Codecov Report

Merging #359 (5c9f19e) into master (a7ce621) will increase coverage by 0.19%.
The diff coverage is 93.96%.

@@            Coverage Diff             @@
##           master     #359      +/-   ##
==========================================
+ Coverage   92.35%   92.55%   +0.19%     
==========================================
  Files          50       53       +3     
  Lines        3992     4457     +465     
  Branches      552      621      +69     
==========================================
+ Hits         3687     4125     +438     
- Misses        203      222      +19     
- Partials      102      110       +8     

Impacted Files	Coverage Δ
vpype_cli/read.py	87.50% <ø> (ø)
vpype/io.py	78.61% <81.17%> (+0.38%)	⬆️
tests/test_commands.py	98.95% <92.00%> (-0.68%)	⬇️
vpype_cli/metadata.py	92.06% <92.06%> (ø)
tests/test_files.py	97.72% <94.87%> (-2.28%)	⬇️
vpype/model.py	92.10% <96.49%> (+0.62%)	⬆️
vpype/metadata.py	97.05% <97.05%> (ø)
tests/test_layers.py	100.00% <100.00%> (ø)
tests/test_metadata.py	100.00% <100.00%> (ø)
tests/test_model.py	100.00% <100.00%> (ø)
... and 14 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update a7ce621...5c9f19e. Read the comment docs.

[EmmaSimon]

Not sure if I should make this a feature request somewhere else, but it might make sense to add support for changing the background color of the SVG as part of this, since this will enable stroke color changes.

[abey79]

@EmmaSimon can you elaborate? Why would the background color be important to change stroke color?

[EmmaSimon]

@abey79 Er, sorry, I phrased that weird. I just meant that I want the ability to change background color, in addition to stroke color.

[abey79]

@EmmaSimon I've not planned "global" metadata yet, but that might be a good reason to think about it. I have a rather strict policy favouring feature that make sens for plotter application but custom background color makes sense to prefix plots on colored paper.

[EmmaSimon]

Right, that was my reasoning, stroke color drastically changes how plots can look, and paper color drastically changes how stroke color looks! So it would be nice to see that while you're designing the sketch.

[abey79]

@EmmaSimon as you might have seen, everything is ready for custom background colour support. I won't however include it in the present PR.

[sonarqubecloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
0.0% Duplication