[doc] add a lot of developer's information

meshroom/ui/components/scene3D.py

@@ -111,7 +111,14 @@ class Transformations3DHelper(QObject):
 
     @Slot(QVector4D, Qt3DRender.QCamera, QSize, result=QVector2D)
     def pointFromWorldToScreen(self, point, camera, windowSize):
-        """ Compute the Screen point corresponding to a World Point. """
+        """ Compute the Screen point corresponding to a World Point.
+            Args:
+                point (QVector4D): point in world coordinates
+                camera (QCamera): camera viewing the scene
+                windowSize (QSize): size of the Scene3D window
+            Returns:
+                QVector2D: point in screen coordinates
+        """
         # Transform the point from World Coord to Normalized Device Coord
         viewMatrix = camera.transform().matrix().inverted()
         projectedPoint = (camera.projectionMatrix() * viewMatrix[0]).map(point)
@@ -130,7 +137,14 @@ def pointFromWorldToScreen(self, point, camera, windowSize):
 
     @Slot(Qt3DCore.QTransform, QMatrix4x4, QMatrix4x4, QMatrix4x4, QVector3D)
     def relativeLocalTranslate(self, transformQtInstance, initialPosMat, initialRotMat, initialScaleMat, translateVec):
-        """ Translate the QTransform in its local space relatively to an initial state. """
+        """ Translate the QTransform in its local space relatively to an initial state.
+            Args:
+                transformQtInstance (QTransform): reference to the Transform to modify
+                initialPosMat (QMatrix4x4): initial position matrix
+                initialRotMat (QMatrix4x4): initial rotation matrix
+                initialScaleMat (QMatrix4x4): initial scale matrix
+                translateVec (QVector3D): vector used for the local translation
+        """
         # Compute the translation transformation matrix 
         translationMat = QMatrix4x4()
         translationMat.translate(translateVec)
@@ -141,7 +155,15 @@ def relativeLocalTranslate(self, transformQtInstance, initialPosMat, initialRotM
 
     @Slot(Qt3DCore.QTransform, QMatrix4x4, QQuaternion, QMatrix4x4, QVector3D, int)
     def relativeLocalRotate(self, transformQtInstance, initialPosMat, initialRotQuat, initialScaleMat, axis, degree):
-        """ Rotate the QTransform in its local space relatively to an initial state. """    
+        """ Rotate the QTransform in its local space relatively to an initial state.
+            Args:
+                transformQtInstance (QTransform): reference to the Transform to modify
+                initialPosMat (QMatrix4x4): initial position matrix
+                initialRotQuat (QQuaternion): initial rotation quaternion
+                initialScaleMat (QMatrix4x4): initial scale matrix
+                axis (QVector3D): axis to rotate around
+                degree (int): angle of rotation in degree
+        """
         # Compute the transformation quaternion from axis and angle in degrees
         transformQuat = QQuaternion.fromAxisAndAngle(axis, degree)
 
@@ -155,7 +177,14 @@ def relativeLocalRotate(self, transformQtInstance, initialPosMat, initialRotQuat
 
     @Slot(Qt3DCore.QTransform, QMatrix4x4, QMatrix4x4, QMatrix4x4, QVector3D)
     def relativeLocalScale(self, transformQtInstance, initialPosMat, initialRotMat, initialScaleMat, scaleVec):
-        """ Scale the QTransform in its local space relatively to an initial state. """
+        """ Scale the QTransform in its local space relatively to an initial state.
+            Args:
+                transformQtInstance (QTransform): reference to the Transform to modify
+                initialPosMat (QMatrix4x4): initial position matrix
+                initialRotMat (QMatrix4x4): initial rotation matrix
+                initialScaleMat (QMatrix4x4): initial scale matrix
+                scaleVec (QVector3D): vector used for the relative scale
+        """
         # Make a copy of the scale matrix (otherwise, it is a reference and it does not work as expected)
         scaleMat = self.copyMatrix4x4(initialScaleMat)
 
@@ -175,7 +204,12 @@ def relativeLocalScale(self, transformQtInstance, initialPosMat, initialRotMat,
 
     @Slot(QMatrix4x4, result="QVariant")
     def modelMatrixToMatrices(self, modelMat):
-        """ Decompose a model matrix into individual matrices. """
+        """ Decompose a model matrix into individual matrices.
+            Args:
+                modelMat (QMatrix4x4): model matrix to decompose
+            Returns:
+                QVariant: object containing position, rotation and scale matrices + rotation quaternion
+        """
         decomposition = self.decomposeModelMatrix(modelMat)
 
         posMat = QMatrix4x4()
@@ -251,7 +285,12 @@ def copyMatrix4x4(self, mat):
         return newMat
 
     def decomposeModelMatrix(self, modelMat):
-        """ Decompose a model matrix into individual component. """
+        """ Decompose a model matrix into individual component.
+            Args:
+                modelMat (QMatrix4x4): model matrix to decompose
+            Returns:
+                QVariant: object containing translation and scale vectors + rotation quaternion
+        """
         translation = modelMat.column(3).toVector3D()
         quaternion = QQuaternion.fromDirection(modelMat.column(2).toVector3D(), modelMat.column(1).toVector3D())
         scale = QVector3D(modelMat.column(0).length(), modelMat.column(1).length(), modelMat.column(2).length())

meshroom/ui/qml/Viewer3D/EntityWithGizmo.qml

@@ -5,12 +5,19 @@ import Qt3D.Extras 2.10
 import QtQuick 2.9
 import Qt3D.Logic 2.0
 
+/**
+ * Wrapper for TransformGizmo.
+ * Must be instantiated to control an other entity.
+ * The goal is to instantiate the other entity inside this wrapper to gather the object and the gizmo.
+ * objectTranform is the component the other entity should use as a Transform.
+ */
+
 Entity {
     id: root
     property DefaultCameraController sceneCameraController
     property Layer frontLayerComponent
     property var window
-    property alias uniformScale: transformGizmo.uniformScale // by default, if not set, the value is: false
+    property alias uniformScale: transformGizmo.uniformScale // By default, if not set, the value is: false
     property TransformGizmo transformGizmo: TransformGizmo {
         id: transformGizmo
         camera: root.camera

meshroom/ui/qml/Viewer3D/MeshingBoundingBox.qml

@@ -4,6 +4,10 @@ import Qt3D.Input 2.0
 import Qt3D.Extras 2.10
 import QtQuick 2.9
 
+/**
+ * BoundingBox entity for Meshing node. Used to define the area to reconstruct.
+ * Simple box controlled by a gizmo to give easy and visual representation.
+ */
 Entity {
     id: root
     property DefaultCameraController sceneCameraController
@@ -56,22 +60,25 @@ Entity {
             }
         }
 
-        // Automatically evaluate the Transform: value is taken from the node OR from the actual modification if the gizmo is moved by mouse.
-        // When the gizmo has changed (with mouse), the new values are set to the node, the priority is given back to the node and the Transform is re-evaluated once with those values.
+        // Translation values from node (vector3d because this is the type of QTransform.translation)
         property var nodeTranslation : Qt.vector3d(
             root.currentMeshingNode.attribute("boundingBox.bboxTranslation.x").value,
             root.currentMeshingNode.attribute("boundingBox.bboxTranslation.y").value,
             root.currentMeshingNode.attribute("boundingBox.bboxTranslation.z").value
         )
+        // Rotation values from node (3 separated values because QTransform stores Euler angles like this)
         property var nodeRotationX: root.currentMeshingNode.attribute("boundingBox.bboxRotation.x").value
         property var nodeRotationY: root.currentMeshingNode.attribute("boundingBox.bboxRotation.y").value
         property var nodeRotationZ: root.currentMeshingNode.attribute("boundingBox.bboxRotation.z").value
+        // Scale values from node (vector3d because this is the type of QTransform.scale3D)
         property var nodeScale: Qt.vector3d(
             root.currentMeshingNode.attribute("boundingBox.bboxScale.x").value,
             root.currentMeshingNode.attribute("boundingBox.bboxScale.y").value,
             root.currentMeshingNode.attribute("boundingBox.bboxScale.z").value
         )
 
+        // Automatically evaluate the Transform: value is taken from the node OR from the actual modification if the gizmo is moved by mouse.
+        // When the gizmo has changed (with mouse), the new values are set to the node, the priority is given back to the node and the Transform is re-evaluated once with those values.
         transformGizmo.gizmoDisplayTransform.translation: transformGizmo.focusGizmoPriority ? transformGizmo.gizmoDisplayTransform.translation : nodeTranslation
         transformGizmo.gizmoDisplayTransform.rotationX: transformGizmo.focusGizmoPriority ? transformGizmo.gizmoDisplayTransform.rotationX : nodeRotationX
         transformGizmo.gizmoDisplayTransform.rotationY: transformGizmo.focusGizmoPriority ? transformGizmo.gizmoDisplayTransform.rotationY : nodeRotationY

meshroom/ui/qml/Viewer3D/SfMTransformGizmo.qml

@@ -4,6 +4,10 @@ import Qt3D.Input 2.0
 import Qt3D.Extras 2.10
 import QtQuick 2.9
 
+/**
+ * Gizmo for SfMTransform node.
+ * Uses EntityWithGizmo wrapper because we should not instantiate TransformGizmo alone.
+ */
 Entity {
     id: root
     property DefaultCameraController sceneCameraController
@@ -60,18 +64,21 @@ Entity {
             }
         }
 
-        // Automatically evaluate the Transform: value is taken from the node OR from the actual modification if the gizmo is moved by mouse.
-        // When the gizmo has changed (with mouse), the new values are set to the node, the priority is given back to the node and the Transform is re-evaluated once with those values.
+        // Translation values from node (vector3d because this is the type of QTransform.translation)
         property var nodeTranslation : Qt.vector3d(
             root.currentSfMTransformNode.attribute("manualTransform.manualTranslation.x").value,
             root.currentSfMTransformNode.attribute("manualTransform.manualTranslation.y").value,
             root.currentSfMTransformNode.attribute("manualTransform.manualTranslation.z").value
         )
+        // Rotation values from node (3 separated values because QTransform stores Euler angles like this)
         property var nodeRotationX: root.currentSfMTransformNode.attribute("manualTransform.manualRotation.x").value
         property var nodeRotationY: root.currentSfMTransformNode.attribute("manualTransform.manualRotation.y").value
         property var nodeRotationZ: root.currentSfMTransformNode.attribute("manualTransform.manualRotation.z").value
+        // Scale value from node (simple number because we use uniform scale)
         property var nodeScale: root.currentSfMTransformNode.attribute("manualTransform.manualScale").value
 
+        // Automatically evaluate the Transform: value is taken from the node OR from the actual modification if the gizmo is moved by mouse.
+        // When the gizmo has changed (with mouse), the new values are set to the node, the priority is given back to the node and the Transform is re-evaluated once with those values.
         transformGizmo.gizmoDisplayTransform.translation: transformGizmo.focusGizmoPriority ? transformGizmo.gizmoDisplayTransform.translation : nodeTranslation
         transformGizmo.gizmoDisplayTransform.rotationX: transformGizmo.focusGizmoPriority ? transformGizmo.gizmoDisplayTransform.rotationX : nodeRotationX
         transformGizmo.gizmoDisplayTransform.rotationY: transformGizmo.focusGizmoPriority ? transformGizmo.gizmoDisplayTransform.rotationY : nodeRotationY