updated linebuilder docs

dfm_tools/linebuilder.py

@@ -6,7 +6,8 @@
 
 class LineBuilder:
     """
-    To interactively draw a line in a figure axis, for instance to use as cross-section.
+    To interactively draw a line in a figure axis, for instance to use as cross-section line for `dfmt.polyline_mapslice()`.
+    
     - ctrl+leftmouseclick to add a point to the line
     - ctrl+rightmouseclick to remove the last point of the line
     - ctrl+doublemouseclick to finish and let the script continue
@@ -25,39 +26,42 @@ def __init__(self, ax=None):
         self.line = line
 
         # register both button press events and key press events
-        self.cid_button = self.line.figure.canvas.mpl_connect('button_press_event', self.on_press)
-        self.cid_key = self.line.figure.canvas.mpl_connect('key_press_event', self.on_press)
+        self.cid_button = self.line.figure.canvas.mpl_connect('button_press_event', self)
+        self.cid_key = self.line.figure.canvas.mpl_connect('key_press_event', self)
         # start a blocking event loop to prevent continuation of the script where LineBuilder was called
         self.line.figure.canvas.start_event_loop()
 
     @property
     def line_array(self):
+        """
+        numpy array of the x/y coordinates of the interactively clicked line.
+        """
         line_array = np.c_[self.xs, self.ys]
         return line_array
 
-    def add_xy_to_line(self, event):
+    def _add_xy_to_line(self, event):
         print(f"adding point: x={event.xdata:.6f}, y={event.ydata:.6f}")
         self.xs.append(event.xdata)
         self.ys.append(event.ydata)
         self.line.set_data(self.xs, self.ys)
         self.line.figure.canvas.draw()
 
-    def remove_last_xy_from_line(self, event):
+    def _remove_last_xy_from_line(self, event):
         print("removing last point if present")
         self.xs = self.xs[:-1]
         self.ys = self.ys[:-1]
         self.line.set_data(self.xs, self.ys)
         self.line.figure.canvas.draw()
 
-    def finish_linebuilder(self):
+    def _finish_linebuilder(self):
         # disconnect the interactive line drawing in the figure
         self.line.figure.canvas.mpl_disconnect(self.cid_button)
         self.line.figure.canvas.mpl_disconnect(self.cid_key)
         # let the rest of the script where LineBuilder was called continue
         self.line.figure.canvas.stop_event_loop()
         print("interactive line drawing finished")
 
-    def on_press(self, event):
+    def __call__(self, event):
         # do nothing if ctrl is not pressed
         if event.key != "control":
             return
@@ -74,13 +78,13 @@ def on_press(self, event):
 
         # add new point to line and wrap up line upon "ctrl + left mouse double click"
         if event.dblclick:
-            self.finish_linebuilder()
+            self._finish_linebuilder()
             return
 
         # add new point to line upon "ctrl + left mouse click"
         if event.button == 1:
-            self.add_xy_to_line(event)
+            self._add_xy_to_line(event)
 
         # remove last point from line upon "ctrl + right mouse click"
         if event.button == 3:
-            self.remove_last_xy_from_line(event)
+            self._remove_last_xy_from_line(event)

docs/installation.md

@@ -6,7 +6,7 @@
 
 ## Recommended installation
 
-- python 3.11 is recommended, python>=3.9 is required ([more info](https://github.com/Deltares/dfm_tools/issues/267)), python 3.13 not yet supported ([more info](https://github.com/Deltares/dfm_tools/issues/559))
+- python 3.11 is recommended, [python>=3.9 is required](https://github.com/Deltares/dfm_tools/issues/267), [python 3.13 not yet supported](https://github.com/Deltares/dfm_tools/issues/559)
 - download and install Anaconda from [anaconda.com](https://www.anaconda.com)
 - open Anaconda prompt
 - ``conda create --name dfm_tools_env python=3.11 git spyder -c conda-forge -y`` (``git`` and ``spyder`` are optional)

docs/modules.rst

@@ -24,6 +24,11 @@ dfm_tools post-processing
    :undoc-members:
    :show-inheritance:
 
+.. automodule:: dfm_tools.linebuilder
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 
 dfm_tools pre-processing
 ------------------------
@@ -85,11 +90,6 @@ dfm_tools unimportant stuff
    :undoc-members:
    :show-inheritance:
 
-.. automodule:: dfm_tools.linebuilder
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 
 dfm_tools example datasets
 --------------------------