Update README

2 files changed, 336 insertions, 1 deletions

diff --git a/README.rst b/README.rst
index 6a67973..4a090e5 100644
--- a/README.rst
+++ b/README.rst
@@ -116,6 +116,246 @@ This is the algorithm svg-flatten uses to process an SVG.
 * for KiCAD S-Expression export: vector-composite results using CavalierContours: subtract each clear output primitive
   from all previous dark output primitives
 
+Command-line usage
+------------------
+
+Generate SVG template from Gerber files:
+
+.. code-block:: shell
+
+    gerbolyze template [options] [-t|--top top_side_output.svg] [-b|--bottom ...] input_dir_or.zip
+
+Render design from an SVG made with the template above into a set of gerber files:
+
+.. code-block:: shell
+
+    gerbolyze paste [options] [-t|--top top_side_design.svg] [-b|--bottom ...] input_dir_or.zip output_dir
+
+Use svg-flatten to convert an SVG file into Gerber or flattened SVG:
+
+.. code-block:: shell
+
+    svg-flatten [options] --format [gerber|svg] [input_file.svg] [output_file]
+
+Use svg-flatten to convert an SVG file into the given layer of a KiCAD S-Expression (``.kicad_mod``) file:
+
+.. code-block:: shell
+
+    svg-flatten [options] --format kicad --sexp-layer F.SilkS --sexp-mod-name My_Module [input_file.svg] [output_file]
+
+Use svg-flatten to convert an SVG file into a ``.kicad_mod`` with SVG layers fed into separate KiCAD layers based on
+their IDs like the popular ``svg2mod`` is doing:
+
+.. note::
+    Right now, the input SVG's layers must have *ids* that match up KiCAD's s-exp layer names. Note that when you name
+    a layer in Inkscape that only sets a ``name`` attribute, but does not change the ID. In order to change the ID in
+    Inkscape, you have to use Inkscape's "object properties" context menu function.
+
+    Also note that svg-flatten expects the layer names KiCAD uses in their S-Expression format. These are *different* to
+    the layer names KiCAD exposes in the UI (even though most of them match up!).
+
+    For your convenience, there is an SVG template with all the right layer names and IDs located next to this README.
+
+.. code-block:: shell
+
+    svg-flatten [options] --format kicad --sexp-mod-name My_Module [input_file.svg] [output_file]
+
+``gerbolyze template``
+~~~~~~~~~~~~~~~~~~~~~~
+
+Usage: ``gerbolyze template [OPTIONS] INPUT``
+
+Generate SVG template for gerbolyze paste from gerber files.
+
+INPUT may be a gerber file, directory of gerber files or zip file with gerber files
+
+Options:
+********
+``-t, --top top_layer.svg``
+    Top layer output file.
+
+``-b, --bottom bottom_layer.svg``
+    Bottom layer output file. --top or --bottom may be given at once. If neither is given, autogenerate filenames.
+
+``--vector | --raster``
+    Embed preview renders into output file as SVG vector graphics instead of rendering them to PNG bitmaps. The
+    resulting preview may slow down your SVG editor.
+
+``--raster-dpi FLOAT``
+    DPI for rastering preview
+
+``--bbox TEXT``
+    Output file bounding box. Format: "w,h" to force [w] mm by [h] mm output canvas OR "x,y,w,h" to force [w] mm by [h]
+    mm output canvas with its bottom left corner at the given input gerber coördinates.
+
+
+``gerbolyze paste``
+~~~~~~~~~~~~~~~~~~~
+(see `below <vectorization_>`__)
+
+Usage: ``gerbolyze paste [OPTIONS] INPUT_GERBERS OUTPUT_GERBERS``
+
+Render vector data and raster images from SVG file into gerbers.
+
+Options:
+********
+
+``-t, --top TEXT``
+    Top side SVG overlay input file. At least one of this and ``--bottom`` should be given.
+
+``-b, --bottom TEXT``
+    Bottom side SVG overlay input file. At least one of this and ``--top`` should be given.
+
+``--bbox TEXT``
+    Output file bounding box. Format: "w,h" to force [w] mm by [h] mm output canvas OR "x,y,w,h" to force [w] mm by [h]
+    mm output canvas with its bottom left corner at the given input gerber coördinates. This **must match the ``--bbox`` value given to
+    template**!
+
+``--subtract TEXT``
+    Use user subtraction script from argument (see `below <subtraction_script_>`_)
+
+``--no-subtract``
+    Disable subtraction (see `below <subtraction_script_>`_)
+
+``--dilate FLOAT``
+    Default dilation for subtraction operations in mm (see `below <subtraction_script_>`_)
+
+``--trace-space FLOAT``
+    Passed through to svg-flatten, see `below <svg_flatten_>`__.
+
+``--vectorizer TEXT``
+    Passed through to svg-flatten, see `its description below <svg_flatten_>`__. Also have a look at `the examples below <vectorization_>`_.
+
+``--vectorizer-map TEXT``
+    Passed through to svg-flatten, see `below <svg_flatten_>`__.
+
+``--exclude-groups TEXT``
+    Passed through to svg-flatten, see `below <svg_flatten_>`__.
+
+.. _subtraction_script:
+Subtraction scripts
+*******************
+
+Subtraction scripts tell ``gerbolyze paste`` which layers to remove from other layers. When a source layer is given in
+the subtraction script, gerbolyze will dilate everything on this source layer and remove it from the target layer. By
+default, Gerbolyze subtracts the mask layer from the silk layer to make sure there are no silk primitives that overlap
+bare copper.
+
+The syntax of these scripts is:
+
+.. code-block::
+
+    {target layer} -= {source layer} {dilation} [; ...]
+
+The target layer must be ``out.{layer name}`` and the source layer ``in.{layer name}``. The layer names are gerbolyze's
+internal layer names, i.e.: ``paste, silk, mask, copper, outline, drill``
+
+The dilation value is optional, but can be a float with a leading ``+`` or ``-``. If given, before subtraction the
+source layer's features will be extended by that many mm. If not given, the dilation defaults to the value given by
+``--dilate`` if given or 0.1 mm otherwise. To disable dilation, simply pass ``+0`` here.
+
+Multiple commands can be separated by semicolons ``;`` or line breaks.
+
+The default subtraction script is:
+
+.. code-block::
+
+    out.silk -= in.mask
+
+.. _svg_flatten:
+``svg-flatten``
+~~~~~~~~~~~~~~~
+
+Usage: ``svg-flatten [OPTIONS]... [INPUT_FILE] [OUTPUT_FILE]``
+
+Specify ``-`` for stdin/stdout.
+
+Options:
+********
+
+``-h, --help``
+    Print help and exit
+
+``-v, --version``
+    Print version and exit
+
+``-o, --format``
+    Output format. Supported: gerber, svg, s-exp (KiCAD S-Expression)
+
+``-p, --precision``
+    Number of decimal places use for exported coordinates (gerber: 1-9, SVG: 0-*). Note that not all gerber viewers are
+    happy with too many digits. 5 or 6 is a reasonable choice.
+
+``--clear-color``
+    SVG color to use for "clear" areas (default: white)
+
+``--dark-color``
+    SVG color to use for "dark" areas (default: black)
+
+``-d, --trace-space``
+    Minimum feature size of elements in vectorized graphics (trace/space) in mm. Default: 0.1mm.
+
+``--no-header``
+    Do not export output format header/footer, only export the primitives themselves
+
+``--flatten``
+    Flatten output so it only consists of non-overlapping white polygons. This perform composition at the vector level.
+    Potentially slow. This defaults to on when using KiCAD S-Exp export because KiCAD does not know polarity or colors.
+
+``--no-flatten``
+    Disable automatic flattening for KiCAD S-Exp export
+
+``--dilate``
+    Dilate output gerber primitives by this amount in mm. Used for masking out other layers.
+
+``-g, --only-groups``
+    Comma-separated list of group IDs to export.
+
+``-b, --vectorizer``
+    Vectorizer to use for bitmap images. One of poisson-disc (default), hex-grid, square-grid, binary-contours,
+    dev-null. Have a look at `the examples below <vectorization_>`_.
+
+``--vectorizer-map``
+    Map from image element id to vectorizer. Overrides --vectorizer.  Format: id1=vectorizer,id2=vectorizer,...
+
+    You can use this to set a certain vectorizer for specific images, e.g. if you want to use both halftone
+    vectorization and contour tracing in the same SVG. Note that you can set an ``<image>`` element's SVG ID from within
+    Inkscape though the context menu's Object Properties tool.
+
+``--force-svg``
+    Force SVG input irrespective of file name
+
+``--force-png``
+    Force bitmap graphics input irrespective of file name
+
+``-s, --size``
+    Bitmap mode only: Physical size of output image in mm. Format: 12.34x56.78
+
+``--sexp-mod-name``
+    Module name for KiCAD S-Exp output. This is a mandatory argument if using S-Exp output.
+
+``--sexp-layer``
+    Layer for KiCAD S-Exp output. Defaults to auto-detect layers from SVG layer/top-level group IDs. If given, SVG
+    groups and layers are completely ignored and everything is simply vectorized into this layer, though you cna still
+    use ``-g`` for group selection.
+
+``-a, --preserve-aspect-ratio``
+    Bitmap mode only: Preserve aspect ratio of image. Allowed values are meet, slice. Can also parse full SVG
+    preserveAspectRatio syntax.
+
+``--no-usvg``
+    Do not preprocess input using usvg (do not use unless you know *exactly* what you're doing)
+
+``--usvg-dpi``
+    Passed through to usvg's --dpi, in case the input file has different ideas of DPI than usvg has.
+
+``--scale``
+    Scale input svg lengths by this factor.
+
+``-e, --exclude-groups``
+    Comma-separated list of group IDs to exclude from export. Takes precedence over --only-groups.
+
+.. _vectorization:
 Gerbolyze image vectorization
 -----------------------------
 
@@ -303,7 +543,7 @@ This tool is licensed under the rather radical AGPLv3 license. Briefly, this mea
 webapp using this tool in the backend with this tool's source.
 
 I get that some people have issues with the AGPL. In case this license prevents you from using this software, please
-send me [an email](mailto:agpl.sucks@jaseg.de) and I can grant you an exception. I want this software to be useful to as
+send me `an email <mailto:agpl.sucks@jaseg.de>`__ and I can grant you an exception. I want this software to be useful to as
 many people as possible and I wouldn't want the license to be a hurdle to anyone. OTOH I see a danger of some cheap
 board house just integrating a fork into their webpage without providing their changes back upstream, and I want to
 avoid that so the default license is still AGPL.
diff --git a/kicad_mod_template.svg b/kicad_mod_template.svg
new file mode 100644
index 0000000..4e7a6b7
--- /dev/null
+++ b/kicad_mod_template.svg
@@ -0,0 +1,95 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="160mm"
+   height="100mm"
+   viewBox="0 0 160 100"
+   version="1.1"
+   id="svg8"
+   inkscape:version="1.0.1 (3bc2e813f5, 2020-09-07, custom)"
+   sodipodi:docname="kicad_mod_template.svg">
+  <metadata
+     id="metadata20">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <defs
+     id="defs18" />
+  <sodipodi:namedview
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1"
+     objecttolerance="10"
+     gridtolerance="10"
+     guidetolerance="10"
+     inkscape:pageopacity="0"
+     inkscape:pageshadow="2"
+     inkscape:window-width="1920"
+     inkscape:window-height="1019"
+     id="namedview16"
+     showgrid="false"
+     inkscape:zoom="1.1197381"
+     inkscape:cx="293.88402"
+     inkscape:cy="186.11375"
+     inkscape:window-x="0"
+     inkscape:window-y="0"
+     inkscape:window-maximized="1"
+     inkscape:current-layer="F.SilkS" />
+  <g
+     inkscape:groupmode="layer"
+     id="Eco2.User"
+     inkscape:label="Eco2.User" />
+  <g
+     inkscape:groupmode="layer"
+     id="Eco1.User"
+     inkscape:label="Eco1.User" />
+  <g
+     inkscape:groupmode="layer"
+     id="Margin"
+     inkscape:label="Margin" />
+  <g
+     inkscape:groupmode="layer"
+     id="F.CrtYd"
+     inkscape:label="F.CrtYd" />
+  <g
+     inkscape:groupmode="layer"
+     id="F.Fab"
+     inkscape:label="F.Fab" />
+  <g
+     inkscape:groupmode="layer"
+     id="Dwgs.User"
+     inkscape:label="Dwgs.User" />
+  <g
+     inkscape:groupmode="layer"
+     id="Cmts.User"
+     inkscape:label="Cmts.User" />
+  <g
+     inkscape:groupmode="layer"
+     id="Edge.Cuts"
+     inkscape:label="Edge.Cuts" />
+  <g
+     inkscape:groupmode="layer"
+     id="g5"
+     inkscape:label="F.Cu" />
+  <g
+     inkscape:groupmode="layer"
+     id="F.Mask"
+     inkscape:label="F.Mask" />
+  <g
+     inkscape:groupmode="layer"
+     id="F.SilkS"
+     inkscape:label="F.SilkS" />
+</svg>