Updating doc: separating key concepts, adding OpenSCAD section

docs/OpenSCAD.rst

@@ -0,0 +1,149 @@
+Transitioning from OpenSCAD
+===========================
+
+Welcome to build123d! If you're familiar with OpenSCAD, you'll notice key differences in 
+how models are constructed. This guide is designed to help you adapt your design approach 
+and understand the fundamental differences in modeling philosophies. While OpenSCAD relies 
+heavily on Constructive Solid Geometry (CSG) to combine primitive 3D shapes like cubes and 
+spheres, build123d encourages a more flexible and efficient workflow based on building 
+lower-dimensional objects.
+
+Why Transition to build123d?
+----------------------------
+
+Transitioning to build123d allows you to harness a modern and efficient approach to 3D modeling. 
+By starting with lower-dimensional objects and leveraging powerful transformation tools, you can 
+create precise, complex designs with ease. This workflow emphasizes modularity and maintainability, 
+enabling quick modifications and reducing computational complexity.
+
+Moving Beyond Constructive Solid Geometry (CSG)
+-----------------------------------------------
+
+OpenSCAD's modeling paradigm heavily relies on Constructive Solid Geometry (CSG) to build 
+models by combining and subtracting 3D solids. While build123d supports similar operations, 
+its design philosophy encourages a fundamentally different, often more efficient approach: 
+starting with lower-dimensional entities like faces and edges and then transforming them 
+into solids.
+
+### Why Transition Away from CSG?
+
+CSG is a powerful method for creating 3D models, but it has limitations when dealing with 
+complex designs. build123d’s approach offers several advantages:
+
+- **Simplified Complexity Management**: 
+  Working with 2D profiles and faces instead of directly manipulating 3D solids simplifies 
+  your workflow. In large models, the number of operations on solids can grow exponentially, 
+  making it difficult to manage and debug. Building with 2D profiles helps keep designs 
+  modular and organized.
+
+- **Improved Robustness**: 
+  Operations on 2D profiles are inherently less computationally intensive and 
+  less error-prone than equivalent operations on 3D solids. This robustness ensures smoother 
+  workflows and reduces the likelihood of failing operations in complex models.
+
+- **Enhanced Efficiency**: 
+  Constructing models from 2D profiles using operations like **extruding**, **lofting**, 
+  **sweeping**, or **revolving** is computationally faster. These methods also provide 
+  greater design flexibility, enabling you to create intricate forms with ease.
+
+- **Better Precision and Control**: 
+  Starting with 2D profiles allows for more precise geometric control. Constraints, dimensions, 
+  and relationships between entities can be established more effectively in 2D, ensuring a solid 
+  foundation for your 3D design.
+
+Using a More Traditional CAD Design Workflow
+--------------------------------------------
+
+Most industry-standard CAD packages recommend starting with a sketch (a 2D object) and 
+transforming it into a 3D model—a design philosophy that is central to build123d.
+
+In build123d, the design process typically begins with defining the outline of an object. 
+This might involve creating a complex 1D object using **BuildLine**, which provides tools 
+for constructing intricate wireframe geometries. The next step involves converting these 
+1D objects into 2D sketches using **BuildSketch**, which offers a wide range of 2D primitives 
+and advanced capabilities, such as:
+
+- **make_face**: Converts a 1D **BuildLine** object into a planar 2D face.
+- **make_hull**: Generates a convex hull from a 1D **BuildLine** object.
+
+Once a 2D profile is created, it can be transformed into 3D objects in a **BuildPart** context 
+using operations such as:
+
+- **Extrusion**: Extends a 2D profile along a straight path to create a 3D shape.
+- **Revolution**: Rotates a 2D profile around an axis to form a symmetrical 3D object.
+- **Lofting**: Connects multiple 2D profiles along a path to create smooth transitions 
+  between shapes.
+- **Sweeping**: Moves a 2D profile along a defined path to create a 3D form.
+
+### Refining the Model
+
+After creating the initial 3D shape, you can refine the model by adding details or making 
+modifications using build123d's advanced features, such as:
+
+- **Fillets and Chamfers**: Smooth or bevel edges to enhance the design.
+- **Boolean Operations**: Combine, subtract, or intersect 3D shapes to achieve the desired 
+  geometry.
+
+### Example Comparison
+
+To illustrate the advantages of this approach, compare a simple model in OpenSCAD and 
+build123d:
+
+**OpenSCAD Approach**
+
+.. code-block:: openscad
+
+    // A basic cylinder with a hole
+    difference() {
+        cylinder(r=10, h=20);
+        translate([0, 0, 5]) cylinder(r=5, h=20);
+    }
+
+**build123d Approach**
+
+.. code-block:: python
+
+    from build123d import *
+
+    # In Builder mode
+    with BuildPart() as cylinder_with_hole:
+        with BuildSketch():
+            Circle(10)
+        extrude(amount=20)
+        with BuildSketch(cylinder_with_hole.faces().sort_by(Axis.Z).last):
+            Circle(5)
+        extrude(amount=-15, mode=Mode.SUBTRACT)
+
+    # In Algebra mode
+    cyl = extrude(Circle(10), 20)
+    cyl -= extrude(Plane(cyl.faces().sort_by(Axis.Z)[-1]) * Circle
+
+
+This approach emphasizes creating a 2D profile (such as the **Circle**) and then applying a 
+3D operation (like **extrude**) to achieve the desired result. Topological features of the 
+part under construction are extracted and used as references for adding further details.
+
+Tips for Transitioning
+----------------------
+
+- **Think in Lower Dimensions**: Begin with 1D curves or 2D sketches as the foundation 
+  and progressively build upwards into 3D shapes.
+
+- **Leverage Topological References**: Use build123d's powerful selector system to 
+  reference features of existing objects for creating new ones. For example, apply 
+  inside or outside fillets and chamfers to vertices and edges of an existing part 
+  with precision.
+
+- **Explore the Documentation**: Dive into build123d’s comprehensive API documentation 
+  to unlock its full potential and discover advanced features.
+
+By shifting your design mindset from solid-based CSG to a profile-driven approach, you 
+can fully harness build123d's capabilities to create precise, efficient, and complex models. 
+Welcome aboard, and happy designing!
+
+Conclusion
+----------
+While OpenSCAD and build123d share the goal of empowering users to create parametric 3D 
+models, their approaches differ significantly. Embracing build123d’s workflow of building 
+with lower-dimensional objects and applying extrusion, lofting, sweeping, or revolution 
+will unlock its full potential and lead to better design outcomes.

docs/index.rst

@@ -106,7 +106,9 @@ Table Of Contents
     introduction.rst
     installation.rst
     key_concepts.rst
+    key_concepts_builder.rst
     key_concepts_algebra.rst
+    OpenSCAD.rst
     introductory_examples.rst
     tutorials.rst
     objects.rst