Documentation

docs/key_concepts.rst

@@ -0,0 +1,191 @@
+############
+Key Concepts
+############
+
+The following key concepts will help new users understand Build123D quickly.
+
+********
+Builders
+********
+
+The three builders, `BuildLine`, `BuildSketch`, and `BuildPart` are tools to create
+new objects - not the objects themselves. Each of the objects and operations applicable
+to these builders create objects of the standard CadQuery Direct API, most commonly
+`Compound` objects.  This is opposed to CadQuery's Fluent API which creates objects
+of the `Workplane` class which frequently needed to be converted back to base
+class for further processing.
+
+One can access the objects created by these builders by referencing the appropriate
+instance variable. For example:
+
+.. code-block:: python
+
+    with BuildPart() as my_part:
+        ...
+
+    show_object(my_part.part)
+
+.. code-block:: python
+
+    with BuildSketch() as my_sketch:
+        ...
+
+    show_object(my_sketch.sketch)
+
+.. code-block:: python
+
+    with BuildLine() as my_line:
+        ...
+
+    show_object(my_line.line)
+
+****************
+Operation Inputs
+****************
+
+When one is operating on an existing object, e.g. adding a fillet to a part,
+a sequence of objects is often required. A python sequence of objects is
+simply either a single object or a string of objects separated by commas.
+To pass an array into a sequence, precede it with a `*` operator.
+When a sequence is followed by another parameter, that parameter must be
+entered as a keyword parameter (e.g. radius=1) to separate this parameter
+from the preceding sequence.
+
+Here is the definition of `FilletPart` to help illustrate:
+
+.. code-block:: python
+
+    class FilletPart(Compound):
+        def __init__(self, *edges: Edge, radius: float):
+
+To use this fillet operation, a sequence of edges must be provided followed by
+a fillet radius as follows:
+
+.. code-block:: python
+
+    with BuildPart() as pipes:
+        Box(10, 10, 10, rotation=(10, 20, 30))
+        ...
+        FilletPart(*pipes.edges(Select.LAST), radius=0.2)
+
+Here the list of edges from the last operation of the `pipes` builder are converted
+to a sequence and a radius is provided as a keyword argument.
+
+*****************
+Combination Modes
+*****************
+Almost all objects or operations have a `mode` parameter which is defined by the
+`Mode` Enum class as follows:
+
+.. code-block:: python
+
+    class Mode(Enum):
+        ADDITION = auto()
+        SUBTRACTION = auto()
+        INTERSECTION = auto()
+        CONSTRUCTION = auto()
+        PRIVATE = auto()
+
+The `mode` parameter describes how the user would like the object or operation to
+interact with the object within the builder. For example, `Mode.ADDITION` will
+integrate a new object(s) in with an existing `part`.  Note that a part doesn't
+necessarily have to be a single object so multiple distinct objects could be added
+resulting is multiple objects stored as a `Compound` object. As one might expect
+`Mode.SUBTRACTION` and `Mode.INTERSECTION` subtract from or intersect and object
+with the builder's object. `Mode.PRIVATE` instructs the builder that this object
+should not be combined with the builder's object in any way.
+
+Most commonly, the default `mode` is `Mode.ADDITION` but this isn't always true.
+For example, the `Hole` classes use a default `Mode.SUBTRACTION` as they remove
+a volume from the part under normal circumstances. However, the `mode` used in
+the `Hole` classes can be specified as `Mode.ADDITION` or `Mode.INTERSECTION` to
+help in inspection or debugging.
+
+*********************************
+Pushing Points & Rotating Objects
+*********************************
+
+Build123D stores points (to be specific `Locations`) internally to be used as
+positions for the placement of new objects.  By default, a single location
+will be created at the origin of the given workplane such that:
+
+.. code-block:: python
+
+    with BuildPart() as pipes:
+        Box(10, 10, 10, rotation=(10, 20, 30))
+
+will create a single 10x10x10 box centered at (0,0,0) - by default objects are
+centered. One can create multiple objects by pushing points prior to creating
+objects as follows:
+
+.. code-block:: python
+
+    with BuildPart() as pipes:
+        PushPointsToPart((-10, -10, -10), (10, 10, 10))
+        Box(10, 10, 10, rotation=(10, 20, 30))
+
+which will create two boxes.  Note that whenever points are pushed, previous
+points are replaced.
+
+To orient a part, a `rotation` parameter is available on `BuildSketch`` and
+`BuildPart` APIs. When working in a sketch, the rotation is a single angle in
+degrees so the parameter is a float. When working on a part, the rotation is
+a three dimensional `Rotation` object of the form
+`Rotation(<about x>, <about y>, <about z>)` although a simple three tuple of
+floats can be used as input.  As 3D rotations are not cumulative, one can
+combine rotations with the `*` operator like this:
+`Rotation(10, 20, 30) * Rotation(0, 90, 0)` to generate any desired rotation.
+
+.. hint::
+    Experts Only
+
+    `PushPoints` will accept `Location` objects for input which allows one
+    to specify both the position and orientation.  However, the orientation
+    is often determined by the `Plane` that an object was created on.
+    `Rotation` is a subclass of `Location` and therefore will also accept
+    a position component.
+
+*************************
+Builder's Pending Objects
+*************************
+
+When a builder exits, it will push the object created back to its parent if
+there was one.  Here is an example:
+
+.. code-block:: python
+
+    with BuildPart() as pillow_block:
+        with BuildSketch() as plan:
+            Rectangle(width, height)
+            FilletSketch(*plan.vertices(), radius=fillet)
+        Extrude(thickness)
+
+`BuildSketch` exits after the `FilletSketch` operation and when doing so it transfers
+the sketch to the `pillow_block` instance of `BuildPart` as the internal instance variable
+`pending_faces`. This allows the `Extrude` operation to be immediately invoked as it
+extrudes these pending faces into `Solid` objects. Likewise, `Loft` will take all of the
+`pending_faces` and attempt to create a single `Solid` object from them.
+
+Normally the user will not need to interact directly with pending objects.
+
+*************************************
+Multiple Work Planes - BuildPart Only
+*************************************
+
+When `BuildPart` is invoked it will by default select the XY plane for the user to work on.
+One can work on any plane by overriding this `workplane` parameter. The `workplane` can be changed
+at any time to one or more planes which is most commonly used to create workplanes from
+existing object Faces. The `WorkplanesFromFaces` class is used to do this as shown below:
+
+.. code-block:: python
+
+    with BuildPart() as pipes:
+        Box(10, 10, 10, rotation=(10, 20, 30))
+        WorkplanesFromFaces(*pipes.faces(), replace=True)
+        with BuildSketch() as pipe:
+            Circle(4)
+        Extrude(-5, mode=Mode.SUBTRACTION)
+
+In this example a `Box` is created and workplanes are created from each of the box's faces.
+The following sketch is then created on each of these workplanes and the `Extrude` operation
+creates holes in each of the faces of the box.