qtvcp -docs: update qt_vismach programming guide

Author: c-morley

docs/src/gui/qtvcp-vismach.adoc

@@ -7,6 +7,7 @@
 *Vismach* is a set of *Python functions that can be used to create and animate models of machines*.
 
 This chapter is about the Qt embedded version of <<cha:vismach,Vismach>>.
+Also see: https://sa-cnc.com/linuxcnc-vismach/
 
 [[sec:qtvcp:vismach:intro]]
 == Introduction
@@ -53,7 +54,6 @@ Taking the mill shown in the 3D Viewport picture above for example:
 
 So for this machine, the tree looks like this:
 
-//FIXME Shouldn't yassembly be a branch of base and zassembly a branch of column ?
 ----
 model
   |
@@ -149,8 +149,7 @@ It is probably easiest to:
 * _create geometry in a CAD package_
 * _import into the model script using the `AsciiSTL()` or `AsciiOBJ()` functions_.
 
-//FIXME Ascii(STL|OBJ): what's the second arg ?
-Both functions can take one of two named arguments, either a _filename_ or _raw data_:
+Both functions can take one of two named arguments, either a _filename_ or _data_:
 
 [source,python]
 ----
@@ -160,8 +159,12 @@ part = AsciiOBJ(filename="path/to/file.obj")
 part = AsciiOBJ(data="v 0.123 0.234 0.345 1.0 ...")
 ----
 
-The parts will be created in the Vismach space in the _same locations as they occupy in the STL or OBJ space_,
-meaning it may be possible to assemble the model in the CAD package.
+- STL model parts are added to the Vismach space in the _same locations as they were created in the STL or OBJ space_,
+ie ideally with a rotational point at their origin.
+
+[NOTE]
+It is much easier to move while building if the origin of the model is at 
+a rotational pivot point.
 
 [[sub:qtvcp:vismach:primitives]]
 === Build from Geometric Primitives
@@ -204,6 +207,8 @@ part4 = Collection([part1, part2])
 == Moving Model Parts
 
 Parts may need to be moved in the Vismach space to assemble the model.
+The origin does not move - Translate() and Rotate() move the Collection 
+as you add parts, relative to a stationary origin.
 
 //FIXME unclear
 They may also need to be moved to create the animation as the animation
@@ -217,16 +222,16 @@ rotation axis is created at the origin (but moves with the Part).
 [[sub:qtvcp:vismach:rotate]]
 === Rotating Model Parts
 
-//FIXME angle unit ?
 *`part1 = Rotate([part1], theta, x, y, z)`*::
-  Rotate the part by angle theta about an axis between the origin and x, y, z.
+  Rotate the part by angle theta degrees about an axis between the origin and
+  x, y, z.
 
 [[sec:qtvcp:vismach:animate]]
 == Animating Parts
 
 //FIXME 2 or 3 functions ? HalToolCylinder not documented here ?
 To *animate the model controlled by the values of HAL pins* there are
-two functions `HalTranslate`, `HalRotate` and `HalToolCylinder`.
+four functions `HalTranslate`, `HalRotate`, `HalToolCylinder` and 'HalToolTriangle'.
 
 _For parts to move inside an assembly they need to have their HAL motions
 defined before being assembled with the "Collection" command_.
@@ -274,6 +279,36 @@ Otherwise the component instance would be specified and the pin name of that com
     the axis of rotation can be considered to remain "embedded" in the part.
   `angle_scale`;; _Rotation angles_ are in degrees, so for a rotary joint with a 0-1 scaling you would need to use an angle scale of 360.
 
+=== 'HalToolCylinder'
+
+*`tool = HalToolCylinder()`*::
+ Make a cylinder to represent a cylindrical mill tool, based on the tool table 
+ and current loaded tool.
+
+[source,python]
+----
+tool = HalToolCylinder()
+toolshape = Color([1, .5, .5, .5],[tool])
+
+# or more compact:
+toolshape = Color([1, .5, .5, .5], [HalToolCylinder()])
+----
+
+=== 'HalToolTriangle'
+
+*`tool = HalToolTriangle()`*::
+ Make a triangle to represent a triangular lathe tool, based on the tool table 
+ and current loaded tool.
+
+[source,python]
+----
+tool = HalToolTriangle()
+toolshape = Color([1, 1, 0, 1],[tool])
+
+# or more compact:
+toolshape = Color([1, 1, 0, 1],[HalToolTriangle()])
+----
+
 [[sec:qtvcp:vismach:assembly]]
 == Assembling the model
 
@@ -370,6 +405,33 @@ model = Collection([base, saddle, head, carousel])
   `_rotation_vectors_` or `_lat, lon_`;; Can be used to set the original viewpoint. +
     It is advisable to do as the default initial viewpoint is rather unhelpful from immediately overhead.
 
+
+== Tips
+create an axes origin marker to be able to see parts relative to it, for 
+construction purposes. You can remove it when you are done.
+
+[source,python]
+----
+# build axis origin markers
+X = CylinderX(-500,1,500,1)
+X = Color([1, 0, 0, 1], [X])
+Y = CylinderY(-500,1,500,1)
+Y = Color([0, 1, 0, 1], [Y])
+Z = CylinderZ(-500,1,500,1)
+Z = Color([0, 0, 1, 1], [Z])
+origin = Collection([X,Y,Z])
+----
+
+ Add it to the Window class Collection so it is never moved from the origin.
+[source,python]
+----
+v.model = Collection([origin, model, world])
+----
+
+Start from the cutting tip and work your way back.
+add each collection to the model at the origin and run the script to confirm 
+the location, then rotate/translate and run the script to confirm again.
+
 [[sec:qtvcp:vismach:structure]]
 == Basic structure of a `QtVismach` script