docs

Author: lfagundes

docs/using-solid-node.rst

@@ -0,0 +1,276 @@
+
+.. _using-solid-node:
+
+================
+Using Solid Node
+================
+
+Make sure you have completed the ::doc:`Quickstart <quickstart>`.
+At this point, you should be able to view your project at the viewer
+- either Openscad or the web viewer - and have a source code to edit.
+
+Getting started
+---------------
+
+Open `root/__init__.py`, you should have the code for a cube with a hole
+in it:
+
+    ```python
+    from solid_node.node import Solid2Node
+    from solid2 import cube, cylinder, translate
+
+    class DemoProject(Solid2Node):
+
+        def render(self):
+            return translate(-25, -25, 0)(
+                cube(50, 50, 50)
+            ) - cylinder(r=10, h=100)
+    ```
+
+In Solid Node, project is organized in a tree structure, with leaf nodes
+and internal nodes. Leaf nodes use uderlying modelling libraries, like
+SolidPython and CadQuery, to generate solid models.
+
+The starting example has just one Solid2Node node, which is a leaf node
+using SolidPython.
+The same result can be obtained using a CadQueryNode:
+
+    ```python
+    import cadquery as cq
+    from solid_node.node import CadQueryNode
+
+    class DemoProject(CadQueryNode):
+
+        def render(self):
+            wp = cq.Workplane("XY")
+            cube = wp.box(50, 50, 50)
+            hole = wp.workplane(offset=-50).circle(10).extrude(100)
+            return cube.cut(hole)
+    ```
+
+Each node must implement the `render()` method. Leaf nodes should return
+an object of the underlying library. Internal nodes `render()` should return
+a list of child instances.
+
+There are two types of internal nodes: `AssemblyNode` and `FusionNode`.
+An AssemblyNode is an assemble of its children nodes, while in FusionNode
+the children nodes are fused in one mesh.
+
+Let's make a very simple clock, as a proof of concept, mixing together
+CadQuery and SolidPython
+
+Simple Clock
+------------
+
+Create a new file `root/clock_base.py` and create a `CadQueryNode`:
+
+    ```python
+    import cadquery as cq
+    from solid_node.node import CadQueryNode
+    
+    class ClockBase(CadQueryNode):
+    
+        def render(self):
+            wp = cq.Workplane("XY")
+            return wp.circle(100).extrude(2)
+    ```
+
+Now, a file `root/pointer.py` with a `Solid2Node`:
+
+    ```python
+    from solid_node.node import Solid2Node
+    from solid2 import cube, cylinder, translate
+    
+    class Pointer(Solid2Node):
+    
+        def render(self):
+            return translate(-5, -5, 3)(
+                cube(10, 90, 10)
+            )
+    ```
+
+And at `root/__init__.py`, an `AssemblyNode`
+
+    ```python
+    from solid_node.node import AssemblyNode
+    from .clock_base import ClockBase
+    from .pointer import Pointer
+    
+    class SimpleClock(AssemblyNode):
+    
+        base = ClockBase()
+        pointer = Pointer()
+        
+        def render(self):
+            return [self.base, self.pointer]
+    ```
+
+Now in the viewer you should see a round clock base with a pointer.
+The `AssemblyNode` can use the property `self.time` to position elements.
+
+Edit `root/__init__.py` to rotate the pointer:
+
+    ```python
+    from solid_node.node import AssemblyNode
+    from .clock_base import ClockBase
+    from .pointer import Pointer
+    
+    class SimpleClock(AssemblyNode):
+    
+        base = ClockBase()
+        pointer = Pointer()
+        
+        def render(self):
+	    angle = 360 * self.time
+	    self.pointer.rotate(angle, [0, 0, 1])
+            return [self.base, self.pointer]
+    ```
+
+At this point you should see a rotating pointer in the viewer.
+If you are using the Openscad viewer, you need to enable animation
+(View -> Animate) and set fps and number of frames.
+Reload is not automatic in Openscad while animating.
+
+Let's make a pin holding the pointer and base together.
+First, to create a hole at the base, edit `root/clock_base.py`
+
+    ```python
+    class ClockBase(CadQueryNode):
+    
+        def render(self):
+            wp = cq.Workplane("XY")
+            return wp.circle(100).extrude(2)
+    ```
+
+And a hole in the pointer, at `root/pointer.py`
+
+    ```python
+    class Pointer(Solid2Node):
+    
+        def render(self):
+            pointer = translate(-5, -5, 3)(
+                cube(10, 90, 10)
+            )
+            hole = cylinder(r=3, h=15)
+            return pointer - hole
+    ```
+
+Now, you should see a hole through both pointer and
+pin, while the pointer is rotating.
+
+Let's make a pin through them. Create the file `root/pin.py`:
+
+    ```python
+    from solid_node.node import Solid2Node
+    from solid2 import cube, cylinder, translate
+    
+    class Pin(Solid2Node):
+    
+        def render(self):
+            return cylinder(r=3, h=20)
+    ```
+
+And at `root/__init__.py`, assemble the pin together:
+
+    ```python
+    from solid_node.node import AssemblyNode
+    from .clock_base import ClockBase
+    from .pointer import Pointer
+    from .pin import Pin
+    
+    class SimpleClock(AssemblyNode):
+    
+        base = ClockBase()
+        pointer = Pointer()
+        pin = Pin()
+        
+        def render(self):
+            angle = 360 * self.time
+            self.pointer.rotate(angle, [0, 0, 1])
+            return [self.base, self.pointer, self.pin]
+    ```
+
+You should see the pin rendered in viewer, with a tight fit.
+We want to test if this is functional: if in reality, this
+arrangement will work. So, let's write a test.
+
+For that, we'll use `solid_node.test.TestCaseMixin`. Add
+it to the base classes of the root node at `root/__init__.py`:
+
+    ```python
+    ...
+    from solid_node.test import TestCaseMixin
+
+    class SimpleClock(AssemblyNode, TestCaseMixin)
+    ```
+
+Now we'll add tests to our root node. Our SimpleClock
+class will extend `solid_node.test.TestCaseMixin` and
+we'll add two tests to `root/__init__.py`:
+
+    ```python
+    from solid_node.node import AssemblyNode
+    from solid_node.test import TestCaseMixin
+    from .clock_base import ClockBase
+    from .pointer import Pointer
+    from .pin import Pin
+    
+    class SimpleClock(AssemblyNode, TestCaseMixin):
+    
+        base = ClockBase()
+        pointer = Pointer()
+        pin = Pin()
+        
+        def render(self):
+            ...
+    
+        def test_pin_runs_free_in_base(self):
+            self.assertNotIntersecting(self.base, self.pin)
+            
+        def test_pin_runs_free_in_pointer(self):
+            self.assertNotIntersecting(self.pointer, self.pin)
+    ```
+
+On the command line, stop the `solid root develop` command, and
+run `solid root test`.
+
+You should see two tests failing, as in practice there is a very
+small intersection between rendered meshes even though matematically
+they should not. Let's reduce the radius of our pin to 2.9, at
+`root/pin.py`:
+
+    ```python
+    class Pin(Solid2Node):
+   
+        def render(self):
+            return cylinder(r=2.9, h=20)
+    ```
+
+Run the tests again. This time, the two tests will pass.
+If you look closely, the cylinder of the pins are not really round.
+They are an approximation. This is because internally STLs are generated
+for the models.
+
+The tests are passing, the pieces are not intersect. But would they still
+not intersect during the rotation of the pointer? The test we made just
+tested the situation for the initial setup. We can improve the test
+by using the decorator `solid_node.test.testing_steps`:
+
+    ```python
+    ...
+    from solid_node.test import TestCaseMixin, testing_steps
+    
+    class SimpleClock(AssemblyNode, TestCaseMixin):
+        ...
+
+	@testing_steps(3, end=0.1)
+        def test_pin_runs_free_in_base(self):
+            self.assertNotIntersecting(self.base, self.pin)
+            
+        def test_pin_runs_free_in_pointer(self):
+            self.assertNotIntersecting(self.pointer, self.pin)
+    ```
+
+
+
+