API docs: Add page on burn correction

documentation/src/api_burn.rst

@@ -0,0 +1,53 @@
+Burn correction
+===============
+
+The burn correction -- aka kerf -- is integrated into the low level
+commands of Boxes.py. So for the most part developer do not need to
+care about it. Nevertheless they need to understand how it works to
+catch the places the do need to care.
+
+Burn correction is done by increasing the radius of all outer
+corners. This moves all the straight lines outward by the same
+amount. This has he addeed benefit of not needing to change the length
+of the straight lines -- making them independent of the adjacent
+angles. An issue arises when it comes to inner corners. If they do
+have a radius reducing it by the burn value does the right thing. But
+for small radii and sharp corners (radius zero) this results in a
+negative values. It turns out flipping over the arc for negative radii
+allows keeping the lengths of the straight lines unchanged. So this is
+what Boxes.py does:
+
+.. image:: burn.svg
+
+This results in the straight lines touching the piece. This leads to
+overcuts. They are not as nice as proper dog bones as might be used by
+a dedicated CAM software. But as Boxes.py is meant to be used for laser
+cutting this is deemed acceptable:
+
+.. image:: overcuts.svg
+
+Programmer's perspective
+------------------------
+
+For this to work it is important that outside is drawn in a counter
+clock wise direction while holes are drawn in a clock wise direction. 
+
+:py:meth:`boxes.Boxes.corner` adjusts the radius automatically
+according to **.burn**. This propagates to higher level
+functions. Parts shipped with Boxes.py do take the
+burn out-set into account and execute callbacks at the correct position.
+
+In case developers move to a feature inside of a part or executing
+callbacks while implementing a part they need to be aware of the burn
+correction. :py:meth:`boxes.Boxes.cc` does correct for the out-set if
+called without an **y** parameter. But if a value is given one has to
+add **self.burn** to compansate. Note that the **x** value typically
+does not have to be corrected as the callbacks are executed from right
+underneeth the part.
+
+A similar approach is necessary when moving to a feature drawn inside
+the part without the use of callbacks. Here you typically have to
+correct for the out-set at the outside of the part and again for in-set
+of the hole one is about to cut. This can be done in **x** or **y**
+direction depending on whether the cut ist started vertical or
+horizontally.

documentation/src/apidoc.rst

@@ -16,4 +16,5 @@ new one from scratch.
    api_existing_parts
    api_edges
    api_drawing
+   api_burn
    api_examples

documentation/src/burn.svg

@@ -0,0 +1,61 @@
+<?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="170mm"
+   height="170mm"
+   viewBox="0 0 170 170"
+   version="1.1"
+   id="svg1682"
+   sodipodi:docname="burn.svg"
+   inkscape:version="0.92.3 (2405546, 2018-03-11)">
+  <metadata
+     id="metadata1688">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <defs
+     id="defs1686" />
+  <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="1171"
+     id="namedview1684"
+     showgrid="false"
+     inkscape:zoom="2.0777847"
+     inkscape:cx="321.25984"
+     inkscape:cy="321.25984"
+     inkscape:window-x="3840"
+     inkscape:window-y="0"
+     inkscape:window-maximized="1"
+     inkscape:current-layer="svg1682" />
+  <path
+     inkscape:connector-curvature="0"
+     id="path1677"
+     d="m 72.601562,134.89844 h 12.5 12.5 v 10 h 9.999998 v -10 h 12.5 c 8.28516,0 15,-6.71485 15,-15 v -10 h 10 V 99.898438 h -10 v -10 h 10 v -10 h -10 v -10 h 10 v -10 h -10 V 49.89844 c 0,-8.28516 -6.71484,-15 -15,-15 h -10 v -10 h -10 v 10 h -9.999998 v -10 h -10 v 10 h -10 v -10 h -10 v 10 h -10 c -8.285156,0 -15,6.71484 -15,15 v 9.999998 h -10 v 10 h 10 v 10 h -10 v 10 h 10 v 10 h -10 v 10.000002 h 10 v 10 c 0,8.28515 6.714844,15 15,15 h 12.5 v 10 h 10 z"
+     style="fill:#999999;stroke:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-opacity:1"
+     sodipodi:nodetypes="ccccccscccccccccccccscccccccccccccscccccccccccccsccccc" />
+  <path
+     inkscape:connector-curvature="0"
+     id="path1679"
+     d="m 50.101562,137.89844 h 12.5 c -1.65625,0 -3,-1.34375 -3,-3 m 0,0 v 10 c 0,1.65625 1.34375,3 3,3 m 0,0 h 10 c 1.65625,0 3,-1.34375 3,-3 m 0,0 v -10 c 0,1.65625 -1.34375,3 -3,3 m 0,0 h 12.5 m 0,0 h 12.5 c -1.65625,0 -3,-1.34375 -3,-3 m 0,0 v 10 c 0,1.65625 1.34375,3 3,3 m 0,0 h 9.999998 c 1.65625,0 3,-1.34375 3,-3 m 0,0 v -10 c 0,1.65625 -1.34375,3 -3,3 m 0,0 h 12.5 c 9.94141,0 18,-8.0586 18,-18 m 0,0 v -10 c 0,1.65625 -1.34375,3 -3,3 m 0,0 h 10 c 1.65625,0 3,-1.34375 3,-3 m 0,0 V 99.898438 c 0,-1.65625 -1.34375,-3 -3,-3 m 0,0 h -10 c 1.65625,0 3,1.34375 3,3 m 0,0 v -10 c 0,1.65625 -1.34375,3 -3,3 m 0,0 h 10 c 1.65625,0 3,-1.34375 3,-3 m 0,0 v -10 c 0,-1.65625 -1.34375,-3 -3,-3 m 0,0 h -10 c 1.65625,0 3,1.34375 3,3 m 0,0 v -10 c 0,1.65625 -1.34375,3 -3,3 m 0,0 h 10 c 1.65625,0 3,-1.34375 3,-3 m 0,0 v -10 c 0,-1.65625 -1.34375,-3 -3,-3 m 0,0 h -10 c 1.65625,0 3,1.34375 3,3 m 0,0 V 49.89844 c 0,-9.94141 -8.05859,-18 -18,-18 m 0,0 h -10 c 1.65625,0 3,1.34375 3,3 m 0,0 v -10 c 0,-1.65625 -1.34375,-3 -3,-3 m 0,0 h -10 c -1.656248,0 -2.999998,1.34375 -2.999998,3 m 0,0 v 10 c 0,-1.65625 1.34375,-3 2.999998,-3 m 0,0 h -9.999998 c 1.65625,0 3,1.34375 3,3 m 0,0 v -10 c 0,-1.65625 -1.34375,-3 -3,-3 m 0,0 h -10 c -1.65625,0 -3,1.34375 -3,3 m 0,0 v 10 c 0,-1.65625 1.34375,-3 3,-3 m 0,0 h -10 c 1.65625,0 3,1.34375 3,3 m 0,0 v -10 c 0,-1.65625 -1.34375,-3 -3,-3 m 0,0 h -10 c -1.65625,0 -3,1.34375 -3,3 m 0,0 v 10 c 0,-1.65625 1.34375,-3 3,-3 m 0,0 h -10 c -9.941406,0 -18,8.05859 -18,18 m 0,0 v 9.999998 c 0,-1.65625 1.34375,-3 3,-3 m 0,0 h -10 c -1.65625,0 -3,1.34375 -3,3 m 0,0 v 10 c 0,1.65625 1.34375,3 3,3 m 0,0 h 10 c -1.65625,0 -3,-1.34375 -3,-3 m 0,0 v 10 c 0,-1.65625 1.34375,-3 3,-3 m 0,0 h -10 c -1.65625,0 -3,1.34375 -3,3 m 0,0 v 10 c 0,1.65625 1.34375,3 3,3 m 0,0 h 10 c -1.65625,0 -3,-1.34375 -3,-3 m 0,0 v 10 c 0,-1.65625 1.34375,-3 3,-3 m 0,0 h -10 c -1.65625,0 -3,1.34375 -3,3 m 0,0 v 10.000002 c 0,1.65625 1.34375,3 3,3 m 0,0 h 10 c -1.65625,0 -3,-1.34375 -3,-3 m 0,0 v 10 c 0,9.9414 8.058594,18 18,18 m -15,0"
+     style="fill:none;stroke:#000000;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-opacity:1" />
+</svg>