Merge pull request #277 from gramaziokohler/UpdatedDocs

Updated documentation for Gh components

CHANGELOG.md

@@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+* Updated documentation for Grasshopper components.
 * Fixed missing input parameter in `SurfaceModelOptions` GH Component.
 * Fixed error with tolerances for `SurfaceModel`s modeled in meters.
 * Renamed `beam` to `element` in different locations to make it more generic.

docs/tutorials.rst

@@ -2,22 +2,21 @@ Grasshopper plugin
 ******************
 
 
-**COMPAS TIMBER for Grasshopper** is an easy-to-use tool to design timber frame structures from simple centerline input.
+**COMPAS Timber for Grasshopper** is an easy-to-use tool to design timber frame structures from simple centerline input.
 It provides tools to automate the process of creating timber frame structures with simple joints,
 *bake* the geometry with fibre-aligned box-mapping for texturing/rendering,
 add boolean-style features like planar cuts or holes,
 and some more.
 
-The plugin is built on top of the COMPAS TIMBER python library and provides additional functionalities that might be useful for design in Grasshopper.
+The plugin is built on top of the COMPAS Timber python library and provides additional functionalities that might be useful for design in Grasshopper.
 
-.. image:: tutorials/images/gh_ct_toolbar.png
+.. image:: tutorials/images/gh_toolbar.png
     :width: 100%
 
 
 .. note::
-    You can also use the COMPAS TIMBER python library in Grasshopper using the
-    `ghPython componenent <https://developer.rhino3d.com/guides/rhinopython/ghpython-component/>`__.
-    See COMPAS TIMBER :doc:`api` and :doc:`examples` for more details.
+    You can also use the COMPAS Timber python library in Grasshopper using the ghPython componenent.
+    See COMPAS Timber :doc:`api` and :doc:`examples` for more details.
 
 To get an overall idea how to use it, start with :doc:`tutorials/grasshopper/workflow`.
 Then, the following sections explain in detail the concepts and tools:
@@ -29,12 +28,13 @@ Then, the following sections explain in detail the concepts and tools:
     :titlesonly:
 
     tutorials/grasshopper/workflow
-    tutorials/grasshopper/beam
     tutorials/grasshopper/attributes
-    tutorials/grasshopper/joints
-    tutorials/grasshopper/rules
+    tutorials/grasshopper/beams
+    tutorials/grasshopper/design
+    tutorials/grasshopper/fabrication
     tutorials/grasshopper/features
-    tutorials/grasshopper/assembly
+    tutorials/grasshopper/joint_rules
+    tutorials/grasshopper/model
     tutorials/grasshopper/show
     tutorials/grasshopper/utils
     tutorials/grasshopper/examples

docs/tutorials/grasshopper/attributes.rst

@@ -10,20 +10,49 @@ and an underscore (:code:`\_`)
 to separate entries (for example: *attr1name:attr1value_attr2name:attr2value*)
 
 
-There are four *standard* attributes, corresponding to the inputs in the **Beam** components: `Width`, `Height`, `Category` or `ZVector`. 
+There are four *standard* attributes, corresponding to the inputs in the :doc:`beams` components: `Width`, `Height`, `Category` or `ZVector`. 
 
-*   **SetStandardAttributes** - sets the standard attributes' values, e.g.  writes them to the source object.
-*   **ReadStandardAttributes** - reads the standard attributes from the source object. *Group* attribute refers to indices of groups if source objects were grouped.
-*   **CheckStandardAttributes** - checks if the standard attributes are set and/or correctly formatted, and displays errors or missing values.
+Standard Attributes
+^^^^^^^^^^^^^^^^^^^
+
+**SetStandardAttributes** - sets the standard attributes' values, e.g.  writes them to the source object.
+**GetStandardAttributes** - gets the standard attributes from the source object. *Group* attribute refers to indices of groups if source objects were grouped.
+
+.. image:: ../images/gh_attributes_standard.png
+    :width: 100%
+
+|
+
+Custom Attributes
+^^^^^^^^^^^^^^^^^
 
 It is also possible to set and retrieve custom, user-defined attributes. This may be useful if later the source objects need to be filtered according to additional criteria.
 These attributes are only set to source objects, not the beams created from them. 
 
-*   **DeleteAttributes** - removes the given attribute and its value from the source object.
-*   **SetCustomAttributes** - sets a custom attribute and its value to the source object.
-*   **ReadAllAttributes** - reads all attributes from the source object.
+**SetCustomAttributes** - sets a custom attribute and its value to the source object.
+**GetCustomAttributes** - gets all attributes from the source object.
+
+.. image:: ../images/gh_attributes_custom.png
+    :width: 100%
 
 |
- 
-.. image:: ../images/Attributes_components.png
-    :width: 80%
+
+Check Attributes
+^^^^^^^^^^^^^^^^
+
+**CheckStandardAttributes** - checks if the standard attributes are set and/or correctly formatted, and displays errors or missing values.
+
+.. image:: ../images/gh_attributes_check.png
+    :width: 100%
+
+|
+
+Delete Attributes
+^^^^^^^^^^^^^^^^^
+
+**DeleteAttributes** - removes the given attribute and its value from the source object.
+
+.. image:: ../images/gh_attributes_delete.png
+    :width: 100%
+
+|

docs/tutorials/grasshopper/beam.rst → docs/tutorials/grasshopper/beams.rst

@@ -1,14 +1,14 @@
-****
-Beam
-****
+*****
+Beams
+*****
 
 A :class:`~compas_timber.parts.Beam` object represents a linear (straight) timber part with a rectangular cross-section - for example as a stud, rafter, beam, joist etc.
 It has a local coordinate system, where the X-axis corresponds with the *centerline*,
 Y-axis with the *width* of the cross-section and Z-axis with the *height* of the cross-section.
 The *origin* is located at the start of the centerline.
 
-.. image:: ../images/beam_01png.png
-    :width: 40%
+.. image:: ../images/gh_beam.png
+    :width: 50%
 
 Beams are created with the component :code:`Beam` - to create a beam from a Grasshopper `Line` or `LineCurve`, or from a `Guid` of a `Line` object referenced from an active Rhino document.
 The latter is intended for a design workflow, where the input geometry (centerlines, etc.) is drawn or stored in a Rhino document instead of generated within the Grasshopper environment.
@@ -34,17 +34,26 @@ Outputs:
 *	`Beam` : the resulting beam(s).
 * 	`Blank`: the corresponding blank beam. The blank represents the raw material from which the beam is cut and without :doc:`features`. It is used to define the stock size for the beam.
 
-.. image:: ../images/gh_beam.png
+.. image:: ../images/gh_beam_beam.png
     :width: 40%
 
-Once a :code:`Beam` is created, it can be used as an input for the :doc:`assembly` component or the following components:
+Once a :code:`Beam` is created, it can be used as an input for the :doc:`model` component or the following components:
+
+DecomposeBeam
+^^^^^^^^^^^^^
 
-*   **DecomposeBeam** : extracts the frame, centreline, box, width and height from a beam.
-*   **FindBeamByRhinoGeometry** : finds the beam corresponding to a referenced Rhino curve or line.
+Extracts the frame, centreline, box, width and height from a Beam.
 
-.. image:: ../images/gh_beamDecompose.png
+.. image:: ../images/gh_beam_decompose.png
     :width: 40%
 
-.. image:: ../images/gh_beamGUID.png
+|
+
+FindBeamByRhinoGuid
+^^^^^^^^^^^^^^^^^^^
+
+Finds a specific Beam corresponding to a referenced Rhino curve or line.
+
+.. image:: ../images/gh_beam_guid.png
     :width: 40%
 

docs/tutorials/grasshopper/design.rst

@@ -0,0 +1,70 @@
+******
+Design
+******
+
+Design Components help to generate standard Wall structures from Surfaces, using different Options.
+
+.. image:: ../images/gh_design_workflow.png
+    :width: 80%
+
+|
+
+A bit of timber construction vocabulary will help you work with these components:
+
+.. image:: ../images/gh_design_modeldiagram.png
+    :width: 90%
+
+
+Surface Model
+^^^^^^^^^^^^^
+
+Creates a Model from a Surface
+
+Inputs:
+
+* `surface` - Referenced planar :code:`Surface` from which to generate beams and joint rules.
+* `stud_spacing` - :code:`Number`: Spacing between the Studs.
+* `beam_width` - :code:`Number`: Width of the cross-section.
+* `frame_depth` - :code:`Number`: Thickness of the frame section of the resulting model. Used to set Beam height.
+* `stud_direction` - :code:`Vector` or :code:`Line`: Optional, Vector defining the direction of stud in the model. Default is World-Z.
+* `options` - Optional, **Surface Model Options** Component
+* `CreateGeometry` - :code:`Boolean`: Set to True to generate Joint and Feature geometry.
+
+|
+
+Outputs:
+
+*	`Model` : the resulting COMPAS Timber Model.
+*	`Geometry` : Model geometry.
+*   `DebugInfo` : Debug information object in the case of feature or joining errors.
+
+Surface Model Options
+^^^^^^^^^^^^^^^^^^^^^
+Creates the Options for the Surface Model
+
+Inputs:
+
+* `sheeting_outside` - :code:`Number`: Optional, thickness of sheeting on the side of assembly closest to input surface. If zero, no sheeting will be added.
+* `sheeting_inside` - :code:`Number`: Optional, thickness of sheeting on the side of assembly furthest from input surface. If zero, no sheeting will be added.
+* `lintel_posts` - :code:`Boolean`: Optional, if False, jack studs will not be generated and headers will butt directly onto king studs.
+* `edge_stud_offset` - :code:`Number`: Optional, distance to offset the studs at the edge of the assembly. If zero, the studs will be flush with the edge of the assembly.
+* `custom_dimensions` - Optional, from **Custom Dimensions** Component. Beam dimensions must either be defined here or in with beam_width and frame_depth inputs.
+* `joint_overrides` - Optional, from **Joint Overrides** Component. Allows user to specify joints between specific beam types in surface model.
+
+Outputs:
+
+*	`Options` : the resulting Beam Model Options.
+
+Custom Beam Dimensions
+^^^^^^^^^^^^^^^^^^^^^^
+
+This is a dynamic component. Sets Beam Dimensions for a selected Beam Type in the Surface Model.
+
+Inputs:
+
+* `width` - :code:`Number`: Width of all studs, king_studs, jack_studs, edge_studs, plates, headers or sills.
+* `height` - :code:`Number`: Height of all studs, king_studs, jack_studs, edge_studs, plates, headers or sills.
+
+Outputs:
+
+*	`Beam Type` : stud, king_stud, jack_stud, edge_stud, plate, header or sill.

docs/tutorials/grasshopper/fabrication.rst

@@ -0,0 +1,22 @@
+***********
+Fabrication
+***********
+
+Fabrication components are used to create Data for machining Compas Timber Models.
+
+Write BTLx
+----------
+Writes a BTLx File from a Compas Timber Model.
+
+.. image:: ../images/gh_fabrication_WriteBtlx.png
+    :width: 60%
+
+Inputs:
+
+* `Model` : the Compas Timber Model.
+* `Path` : a :code:`File Path` where to save the BTLx File.
+* `Write` : Writes the File if the Input is :code:`True`.
+
+Outputs:
+
+*	`BTLx` : the BTLx Content as xml text.

docs/tutorials/grasshopper/features.rst

@@ -7,23 +7,34 @@ Features are additional geometric operations on beams:
 .. image:: ../images/diagram_features.png
   :width: 75%
 
+|
+
+.. image:: ../images/gh_features.png
+  :width: 100%
+
+|
+
+Brep Subtraction Feature
+^^^^^^^^^^^^^^^^^^^^^^^^
 **BrepSubtractionFeature** is a boolean operation to subtract any *Brep* geometry from a beam.
 
 * `Beam` : the beam to be subtracted from
 * `Brep` : the Brep geometry to subtract as a Brep
 
+Brep Drill Hole Feature
+^^^^^^^^^^^^^^^^^^^^^^^
 **BrepDrillHoleFeature** is a boolean operation to subtract a hole from a beam.
 
 * `Beam` : the beam to be drilled
 * `Line` : the axis of the hole as a Line
 * `Diameter` : the diameter of the hole
 
+Trim Feature
+^^^^^^^^^^^^
 **TrimFeature** cuts a beam with a *Plane*. The part of the beam lying on the *z-positive* side of the plane will be removed.
 
 * `Beam` : the beam to be trimmed
 * `Plane` : the plane to trim the beam as a surface
 
-The output `Feature` is to be used as input for the **Assembly** component. See :doc:`assembly`.
+The output `Feature` is to be used as input for the **Model** component. See :doc:`model`.
 
-.. image:: ../images/gh_features.png
-  :width: 51%