Merge branch 'main' into conversions-api

Author: tomvanmele

CHANGELOG.md

@@ -38,6 +38,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Added `compas_rhino.conversions.docobjects.meshobject_to_compas`.
 * Added `compas_rhino.conversions.docobjects.pointobject_to_compas`.
 * Added `compas_rhino.conversions.docobjects.surfaceobject_to_compas`.
+* Added `compas.datastructures.HashTree` and `compas.datastructures.HashNode`.
 
 ### Changed
 
@@ -62,6 +63,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Changed `compas_rhino.objects.get_line_coordinates` to deprecated (removed in v2.3).
 * Changed `compas_rhino.objects.get_polyline_coordinates` to deprecated (removed in v2.3).
 * Changed `compas_rhino.objects.get_polygon_coordinates` to deprecated (removed in v2.3).
+* Fixed a bug in `worldtransformation` of `compas.scene.SceneObject` to include the object's own frame.
 
 ### Removed
 

docs/userguide/advanced.hashtree.rst

@@ -0,0 +1,80 @@
+********************************************************************************
+Hash Tree
+********************************************************************************
+
+Hash tree (or Merkle tree) is a tree data structure in which every leaf node is labelled with the hash of a data block and every non-leaf node is labelled with the cryptographic hash of the labels of its child nodes. 
+Hash trees are useful because they allow efficient and secure verification of the contents of large data structures. It is widly used in modern distributed version control systems like Git as well as peer-to-peer systems like Blockchain.
+COMPAS provides a simple implementation of a hash tree that can be used for detecting and locating changes in a complex data structure. In context of AEC, this feature can also be useful for many real-world applications,
+such as detecting changes in a complicated Building Information Model, tracking minor deformation in structural assessments, or even detecting robot joint movements in a digital fabracation process, and many more. 
+
+Hash Tree From Dict
+===================
+
+A COMPAS hash tree can be created from any raw python dictionary using the `HashTree.from_dict` method.
+
+>>> from compas.datastructures import HashTree
+>>> data = {'a': 1, 'b': 2, 'c': {'d': 3, 'e': 4}}
+>>> tree = HashTree.from_dict(data)
+
+The structure of the hash tree and crypo hash on each node can be visualised using the `print` function.
+
+>>> print(tree)
+<Tree with 6 nodes>
+└── ROOT @ b2e1c
+    ├── .a:1 @ 4d9a8
+    ├── .b:2 @ 82b86
+    └── .c @ 664a3
+        ├── .d:3 @ 76d82
+        └── .e:4 @ ebe84
+
+Once the original data is modified, a new hash tree can be created from the modified data and the changes can be detected by comparing the two hash trees.
+
+>>> data['c']['d'] = 5
+>>> del data["b"]
+>>> data["f"] = True
+>>> new_tree = HashTree.from_dict(data)
+>>> print(new_tree)
+<Tree with 6 nodes>
+└── ROOT @ a8c1b
+    ├── .a:1 @ 4d9a8
+    ├── .c @ e1701
+    │   ├── .d:5 @ 98b1e
+    │   └── .e:4 @ ebe84
+    └── .f:True @ 753e5
+
+>>> new_tree.diff(tree)
+{'added': [{'path': '.f', 'value': True}], 'removed': [{'path': '.b', 'value': 2}], 'modified': [{'path': '.c.d', 'old': 3, 'new': 5}]}
+
+Hash Tree From COMPAS Data
+==========================
+
+A COMPAS hash tree can also be created from any classes that inherit from the base `Data` class in COMPAS, such as `Mesh`, `Graph`, `Shape`, `Geometry`, etc.
+This is done by hashing the serilised data of the object.
+
+>>> from compas.datastructures import Mesh
+>>> mesh = Mesh.from_polyhedron(6)
+>>> tree = HashTree.from_object(mesh)
+>>> print(tree)
+<Tree with 58 nodes>
+└── ROOT @ 44cc1
+    ├── .attributes @ 3370c
+    ├── .default_vertex_attributes @ 84700
+    │   ├── .x:0.0 @ 5bc2d
+    │   ├── .y:0.0 @ 1704b
+    │   └── .z:0.0 @ 6199e
+    ├── .default_edge_attributes @ 5e834
+    ├── .default_face_attributes @ 5a8d9
+    ├── .vertex @ ff6d0
+    │   ├── .0 @ 84ec1
+    │   │   ├── .x:-1.1547005383792517 @ 874f4
+    │   │   ├── .y:-1.1547005383792517 @ d2b16
+    │   │   └── .z:-1.1547005383792517 @ bd9f0
+    │   ├── .1 @ 316d3
+...
+
+>>> mesh.vertex_attribute(0, "x", 1.0)
+>>> mesh.delete_face(3)
+>>> new_tree = HashTree.from_object(mesh)
+>>> new_tree.diff(tree)
+{'added': [], 'removed': [{'path': '.face.3', 'value': [4, 2, 3, 5]}, {'path': '.facedata.3', 'value': None}], 'modified': [{'path': '.vertex.0.x', 'old': -1.1547005383792517, 'new': 1.0}]}
+

docs/userguide/basics.visualisation.rst

@@ -64,28 +64,6 @@ For example, meshes can have different colors for the vertices, the edges, and t
 And the colors of vertices, edges, and faces can be specified individually, per element.
 See the section about mesh visualisation for more information.
 
-Object Transformation
-=====================
-
-All scene objects have a transformation matrix that can be used to transform the object in the visualisation,
-independently of the geometry of the underlying data object.
-The default transformation matrix is the identity matrix, which means that the visualised geometry is the same as the geometry represented by the data.
-
->>> sceneobj = scene.add(box)
->>> sceneobj.transformation
-Transformation([[1.0, 0.0, 0.0, 0.0], [0.0, 1.0, 0.0, 0.0], [0.0, 0.0, 1.0, 0.0], [0.0, 0.0, 0.0, 1.0]])
-
-The transformation matrix can be set using a COMPAS Transformation object, or a 4x4 nested list of floats.
-
->>> from compas.geometry import Translation
->>> sceneobj.transformation = Translation.from_vector([1.0, 2.0, 3.0])
->>> sceneobj.transformation
-Transformation([[1.0, 0.0, 0.0, 1.0], [0.0, 1.0, 0.0, 2.0], [0.0, 0.0, 1.0, 3.0], [0.0, 0.0, 0.0, 1.0]])
-
-.. note::
-
-    For more information about working with transformations in COMPAS, see :doc:`basics.geometry.transformations`.
-
 Scene Hierarchy
 ===============
 
@@ -115,6 +93,34 @@ To use a different scene object as the parent, the parent attribute of the scene
 >>> boxobj.parent
 PointObject
 
+Object Frame And Transformation
+=====================
+
+Every scene objects can have a reference "frame" that represents its local coordinate system relative to the frame of its hierarchical parent.
+In addition, an object can also have a local "transformation" which orientates this object from its frame.
+The final transformation of an object relative to the world coordinate system is the aggregated multiplication of all its hierarchical ancesters' frames, 
+together with its own local frame and transformation. This prorperty can be accessed through the read-only attribute "worldtransformation".
+
+>>> from compas.geometry import Translation
+>>> from compas.geometry import Box
+>>> from compas.geometry import Frame
+>>> sceneobj1 = scene.add(Box())
+>>> sceneobj1.frame = Frame(point = [1.0, 0.0, 0.0], xaxis=[1.0, 0.0, 0.0],yaxis=[0.0, 1.0, 0.0])
+>>> sceneobj1.transformation = Translation.from_vector([10.0, 0.0, 0.0])
+>>> sceneobj1.worldtransformation
+Transformation([[1.0, 0.0, 0.0, 11.0], [0.0, 1.0, 0.0, 0.0], [0.0, 0.0, 1.0, 0.0], [0.0, 0.0, 0.0, 1.0]], check=False)
+>>> sceneobj1.worldtransformation == sceneobj1.frame.to_transfromation() * sceneobj1.transformation
+True
+
+The worldtransformation of a nestd "sceneobj2" will be calculated as: Frame of "sceneobj1" * Frame of "sceneobj2" * Transformation of "sceneobj2" 
+>>> sceneobj2 = scene.add(Box(), parent=sceneobj1)
+>>> sceneobj2.frame = Frame([1.0, 1.0, 0.0], xaxis=[1.0, 0.0, 0.0],yaxis=[0.0, 1.0, 0.0])
+>>> sceneobj2.transformation = Translation.from_vector([10.0, 10.0, 0.0])
+>>> sceneobj.worldtransformation
+Transformation([[1.0, 0.0, 0.0, 12.0], [0.0, 1.0, 0.0, 11.0], [0.0, 0.0, 1.0, 0.0], [0.0, 0.0, 0.0, 1.0]], check=False)
+>>> sceneobj2.worldtransformation == sceneobj1.frame.to_transfromation() * sceneobj2.frame.to_transfrom() * sceneobj2.transformation
+True
+
 
 Scene Context
 =============

docs/userguide/index.rst

@@ -32,6 +32,7 @@ User Guide
     advanced.tolerance
     advanced.serialisation
     advanced.rpc
+    advanced.hashtree
 
 
 .. toctree::

src/compas/datastructures/__init__.py

@@ -55,6 +55,7 @@
 from .assembly.part import Feature, GeometricFeature, ParametricFeature, Part
 from .cell_network.cell_network import CellNetwork
 from .tree.tree import Tree, TreeNode
+from .tree.hashtree import HashTree, HashNode
 
 Network = Graph
 
@@ -72,4 +73,6 @@
     "ParametricFeature",
     "Tree",
     "TreeNode",
+    "HashTree",
+    "HashNode",
 ]