Documented 7 functions across 2 files

.komment/komment.json

@@ -0,0 +1,31 @@
+{
+  "meta": {
+    "version": "1",
+    "updated_at": "2024-07-31T13:11:04.283Z",
+    "created_at": "2024-07-03T15:48:27.349Z",
+    "pipelines": [
+      "50c96b7c-ad3b-4b93-ae19-7f6fbd5637f7",
+      "9e4d0253-62f2-4920-b2d3-607cb4cf3291",
+      "510e9758-a82c-441e-9653-dc071bb409eb",
+      "1f636eb0-7f1e-4d1d-b462-6d1eff3533cb",
+      "d6a72e5c-096b-4179-ac39-3343ea5ec3a5",
+      "395b32ba-01b1-45bb-84e0-96a1b0abb44e",
+      "fb0c09b8-650c-42fb-a814-0c07d121ec67",
+      "3216d745-95dc-419d-8524-71b95ba17b45",
+      "bdcf9dc7-844d-44d2-af0f-6fcd7dfa4a7c",
+      "2a176ad9-6055-453c-8640-de6390f8f6fd"
+    ]
+  },
+  "lookup": [
+    [
+      "agents/long_term_spatial_memory_agent/src/long_term_graph.py",
+      "agents/g2o_agent/src/genericworker.py",
+      "agents/g2o_agent/src/specificworker.py",
+      "agents/long_term_spatial_memory_agent/scripts/long_term_graph.py",
+      "agents/long_term_spatial_memory_agent/scripts/main.py",
+      "agents/long_term_spatial_memory_agent/src/genericworker.py",
+      "agents/long_term_spatial_memory_agent/src/specificworker.py",
+      "agents/long_term_spatial_memory_agent/src/specificworker_sec.py"
+    ]
+  ]
+}

agents/g2o_agent/src/genericworker.py

@@ -42,9 +42,33 @@
 
 class GenericWorker(QtWidgets.QWidget):
 
+    """
+    Manages a worker process with a periodic timer and provides a signal for
+    termination. It also has a method to set the period of the timer.
+
+    Attributes:
+        kill (QtCoreSignal): Used to emit a signal when the object needs to be killed.
+        ui (Ui_guiDlg): Used to initialize and access the user interface of the widget.
+        mutex (QMutex): Used to protect access to the internal state of the worker
+            object, particularly the timer and kill signal.
+        Period (int): 30 milliseconds by default, which represents the time interval
+            for the timer to run.
+        timer (QTimer): Used to schedule a call to the `killYourSelf` slot after
+            a specified period of time.
+
+    """
     kill = QtCore.Signal()
 
     def __init__(self, mprx):
+        """
+        Initializes an instance of the `GenericWorker` class, setting up a GUI
+        dialog and creating a mutex for managing access to the timer. It also sets
+        the period of the timer to 30 seconds.
+
+        Args:
+            mprx (Ui_guiDlg): Used as an argument for the setupUi method.
+
+        """
         super(GenericWorker, self).__init__()
 
 
@@ -59,13 +83,25 @@ def __init__(self, mprx):
 
     @QtCore.Slot()
     def killYourSelf(self):
+        """
+        Emits the `kill` signal, indicating that the instance should be destroyed.
+
+        """
         rDebug("Killing myself")
         self.kill.emit()
 
     # \brief Change compute period
     # @param per Period in ms
     @QtCore.Slot(int)
     def setPeriod(self, p):
+        """
+        Updates the `Period` attribute and starts a timer with the new period value
+        using the `timer.start()` method.
+
+        Args:
+            p (int): Used to set the new period for the timer.
+
+        """
         print("Period changed", p)
         self.Period = p
         self.timer.start(self.Period)

agents/long_term_spatial_memory_agent/scripts/long_term_graph.py

@@ -13,7 +13,32 @@
 
 
 class LongTermGraph:
+    """
+    Draws a graph of long-term spatial mobility data using PyQt and Matplotlib.
+    It provides methods to visualize rooms, doors, walls, and edges in the graph.
+
+    Attributes:
+        g (Graph): Used to represent the graph object that contains the rooms,
+            doors, and walls to be visualized.
+        read_graph (instance): Used to read a graph from a file specified by the
+            user. It takes a string path as input and reads the graph data from it.
+        fig (instance): A reference to the figure object that will be used to draw
+            the graph.
+        ax (MatplotlibFigure): Used to represent the axis object for the graph.
+            It provides methods for adding patches, lines, and other visual elements
+            to the graph.
+
+    """
     def __init__(self, file_name):
+        """
+        Initializes an object of `LongTermGraph` class, loading a graph from a
+        file using the `read_graph` method and displaying its summary.
+
+        Args:
+            file_name (str): Used to specify the name of a file containing a graph
+                represented as an adjacency matrix.
+
+        """
         self.g = self.read_graph(file_name, directed=True)
         print("Graph read from", file_name, self.g.summary())
 
@@ -189,6 +214,17 @@ def check_point_in_map(self, rooms_map: dict, point: QPoint):
         return None
 
     def draw_graph(self, only_rooms=True):
+        """
+        Generates a graphical representation of a subgraph within a larger graph,
+        based on node and edge properties. It creates a figure and axis object,
+        sets the title, and draws the nodes and edges using different colors for
+        each type of node or edge.
+
+        Args:
+            only_rooms (bool): Used to filter the nodes in the graph based on their
+                types, only showing rooms and doors.
+
+        """
         fig1, ax1 = plt.subplots()
         ax1.set_title('LTSM graph')
         fig1.canvas.draw()

agents/long_term_spatial_memory_agent/scripts/main.py

@@ -4,6 +4,15 @@
 
 
 def draw_graph(graph):
+    """
+    Generates a graph based on a provided adjacency matrix using Kamada-Kawai
+    layout algorithm, and adds node names and edges with arrowheads.
+
+    Args:
+        graph (AbstractGraph): Used to represent a graph object that contains
+            vertices and edges.
+
+    """
     fig1, ax1 = plt.subplots()
     ax1.set_title('LTSM graph')
     fig1.canvas.draw()
@@ -39,12 +48,43 @@ def draw_graph(graph):
     ax1.set_ylim([min(y) - 2, max(y) + 2])
 
 def find_edge_with_attribute(graph, attribute, value):
+    """
+    Searches through a graph's edges for an edge with a specific attribute equal
+    to a given value. If such an edge is found, it returns it; otherwise, it returns
+    `None`.
+
+    Args:
+        graph (Graph): Represented as an object that contains a collection of
+            edges, where each edge represents a connection between two nodes in
+            the graph.
+        attribute (attribute): Used to specify the attribute of interest for finding
+            an edge in a graph.
+        value (object): Used to search for an edge in a graph based on a specific
+            attribute.
+
+    Returns:
+        edge: An untyped reference to a graph edge that has the specified attribute
+        equal to the provided value.
+
+    """
     for edge in graph.es:
         if edge[attribute] == value:
             return edge
     return None
 
 def get_room_edges(graph):
+    """
+    Iterates over the edges in a graph and adds to an output list any edge connecting
+    nodes with "door" in their names.
+
+    Args:
+        graph (Graph): Represented as g, which contains a collection of nodes and
+            edges that define a graph structure.
+
+    Returns:
+        list: A collection of edges from the given graph.
+
+    """
     edges = []
     for edge in g.es:
         source_node = g.vs[edge.source]
@@ -57,6 +97,19 @@ def get_room_edges(graph):
 
 def get_connected_door_nodes(graph, node):
     # Base case: if the node is a door node, return it
+    """
+    In Java code recursively queries the graph for all nodes connected to a given
+    node via doors, returning a list of such nodes.
+
+    Args:
+        graph (Graph): Used to represent a graph structure.
+        node (GraphNode): Referred to as a node in the graph.
+
+    Returns:
+        list: A collection of nodes that are connected to a specific node through
+        doors.
+
+    """
     if "door" in node["name"] and node["connected_room_name"] is not None:
         return [node]
 
@@ -72,6 +125,21 @@ def get_connected_door_nodes(graph, node):
     return door_nodes
 
 def traverse_graph(graph, current_room, visited=None):
+    """
+    Navigates through a graph by starting from a given room and visiting all other
+    rooms reachable through doors. It keeps track of visited rooms using a list
+    and prints information about each room it visits.
+
+    Args:
+        graph (Graph): Used to represent a graph with nodes and edges.
+        current_room (dict): Represents the current room to be traversed in the graph.
+        visited (list): Used to keep track of the rooms that have been visited
+            during the traversal process, initialized to an empty list if None.
+
+    Returns:
+        list: A collection of strings representing the rooms that have been visited.
+
+    """
     if visited is None:
         visited = list()
 

agents/long_term_spatial_memory_agent/src/genericworker.py

@@ -42,13 +42,38 @@
 
 class GenericWorker(QtWidgets.QWidget):
 
+    """
+    Manages a timer and a signal to stop its own execution. It has methods to
+    change the timer period and to emit the signal to stop itself.
+
+    Attributes:
+        kill (QtCoreQObjectSlot): Used to emit a signal that can be caught by any
+            connected slots to stop the worker's execution.
+        ui (Ui_guiDlg): Used to setup the user interface of the class.
+        mutex (QMutex): Used to protect the worker's state from concurrent access.
+        Period (int): Used to set the time interval for the timer signal emitted
+            by the `setPeriod()` method, which changes its value on each call.
+        timer (QtCoreQTimer): Used to start a timer that emits the `kill` signal
+            after a specified period.
+
+    """
     kill = QtCore.Signal()
 
     def __init__(self, mprx):
+        """
+        Initializes an object of the `GenericWorker` class, setting up a UI widget,
+        creating a mutex for synchronization, and defining a timer with a period
+        of 500 milliseconds.
+
+        Args:
+            mprx (Ui_guiDlg): Used as the parent widget for the GenericWorker
+                object's UI.
+
+        """
         super(GenericWorker, self).__init__()
 
 
-        self.ui = Ui_guiDlg()ss
+        self.ui = Ui_guiDlg()
         self.ui.setupUi(self)
         # self.show()
 
@@ -59,13 +84,24 @@ def __init__(self, mprx):
 
     @QtCore.Slot()
     def killYourSelf(self):
+        """
+        Emits the `kill` signal, indicating that the object should be terminated.
+
+        """
         rDebug("Killing myself")
         self.kill.emit()
 
     # \brief Change compute period
     # @param per Period in ms
     @QtCore.Slot(int)
     def setPeriod(self, p):
+        """
+        Sets the period of a timer and updates the internal variable `Period`.
+
+        Args:
+            p (int): Used to set the new period for the timer.
+
+        """
         print("Period changed", p)
         self.Period = p
         self.timer.start(self.Period)