fixed documentation

compLib/Camera.py

@@ -1,5 +1,5 @@
 import sys
-from typing import Any
+from typing import Any, Tuple, List
 
 # build image is somehow different from raspberry image? opencv-python is installed to a directory which is not in the pythonpath by default....
 sys.path.append("/usr/lib/python3.9/site-packages")
@@ -58,6 +58,7 @@ class Camera:
             def __video_feed():
                 """
                 Define route for serving jpeg stream.
+
                 :return: Return the response generated along with the specific media.
                 """
                 return Response(self.__camera._newest_frame_generator(),
@@ -67,13 +68,15 @@ class Camera:
             def __index():
                 """
                 Define route for serving a static http site to view the stream.
-                :return: Static html page
+
+                :return: Static html page where the video stream of Opencv can be viewed.
                 """
                 return HTML
 
         def __start_flask(self):
             """
             Function for running flask server in a thread.
+
             :return:
             """
             logging.getLogger("complib-logger").info("starting flask server")
@@ -121,27 +124,31 @@ class Camera:
 
         self.__logger.info("Initialized vision")
 
-    def get_frame(self):
+    def get_frame(self) -> Any:
         """
-        Die Funktion das neuste Bild, welches die Kamera aufgenommen hat zurück.
+        Die Funktion gibt das neuste Bild, welches die Kamera aufgenommen, hat zurück.
+
         :return: Ein "opencv image frame"
         """
         img16 = self.__camera_stream.read()
         return img16
 
-    def detect_markers(self, image):
+    def detect_markers(self, image) -> Any:
         """
         Funktion um die ArUco Marker in einem Bild zu erkennen.
+
         :param image: Bild, welches die Kamera aufgenommen hat.
         :return: Gibt drei Variablen zurueck. Erstens eine Liste an Postionen der "Ecken" der erkannten Markern. Zweitens eine Liste an IDs der erkannten Markern und dritten noch Debug Informationen (diese können ignoriert werden).
         """
         return cv2.aruco.detectMarkers(image, self.aruco_dict, parameters=self.aruco_params)
 
-    def detect_markers_midpoint(self, image) -> tuple[list[Marker], Any]:
+    def detect_markers_midpoint(self, image) -> Tuple[List[Marker], Any]:
         """
         Funktion um die ArUco Marker in einem Bild zu erkennen, einzuzeichnen und den Mittelpunkt der Marker auszurechnen.
+
         :param image: Bild, welches die Kamera aufgenommen hat.
         :return: Gibt zwei Variablen zurueck. Erstens eine Liste an "Markern" und zweitens das Bild mit den eigezeichneten Marken.
+        :rtype: Tuple[List[Marker], Any]
         """
         (corners, ids, rejected) = self.detect_markers(image)
         self.draw_markers(image, corners, ids)
@@ -154,9 +161,10 @@ class Camera:
 
         return res, image
 
-    def draw_markers(self, image, corners, ids):
+    def draw_markers(self, image, corners, ids) -> Any:
         """
         Zeichnet die erkannten Markern mit ihren IDs in das Bild.
+
         :param image: Original Bild, in dem die Marker erkannt wurden.
         :param corners: List der Positionen der Ecken der erkannten Marker.
         :param ids: IDs der erkannten Markern.
@@ -167,6 +175,7 @@ class Camera:
     def publish_frame(self, image):
         """
         Sendet das Bild, welches der Funktion übergeben wird, an den Webserver, damit es der Nutzer in seinem Browser ansehen kann.
+
         :param image: Opencv Bild, welches dem Nutzer angezeigt werden soll.
         :return: None
         """
@@ -177,6 +186,7 @@ class Camera:
     def _newest_frame_generator(self):
         """
         Private generator which is called directly from flask server.
+
         :return: Yields image/jpeg encoded frames published from publish_frame function.
         """
         while True:

docs/source/lib/classes/Opencv.rst

@@ -11,3 +11,69 @@ Dokumentation des Camera Moduls
 
 .. autoclass:: compLib.Camera.Camera
    :members:
+
+Beispiele
+=========
+
+Bild Anzeigen
+---------------
+
+Das folgende Programm fragt Bilder von der Kamera ab und schickt sie an den Webserver, der im Hintergrund läuft. Der Benutzer kann dann auf die Webseite: http://raspi_ip:9898 gehen und die Ausgabe der Kamera sehen.
+
+.. code-block:: python
+
+    from compLib.Camera import *
+
+    camera = Camera()
+    while True:
+        image = camera.get_frame()
+        camera.publish_frame(image)
+
+ArUco Marker Erkennen
+------------------------
+
+In diesem Programm werden die ArUco Marker, die sich am Spielfeld befinden, erkannt. Diese "QR-Code" ähnlichen Marker finden sich in den Logistikzonen und können dazu verwendet werden zu erkennen, wo der Roboter hinfahren sollt etc.
+
+.. code-block:: python
+
+    from compLib.Camera import *
+
+    camera = Camera()
+    while True:
+        image = camera.get_frame()
+
+        markers, image = camera.detect_markers_midpoint(image)
+        print(markers)
+        print("-----------------")
+
+        camera.publish_frame(image)
+
+Hier ist z.B. der ArUco Marker mit der ID 0. Führe das Programm aus und lass den Roboter auf den Bildschirm schauen. Das Programm sollte die 2D Position ausgeben, welcher der ArUco Marker (genauer sein Mittelpunkt) im Camera Bild hat.
+
+|ArucoExample|
+
+.. |ArucoExample| image:: images/6x6_1000-0.png
+
+Um die Positionen zu verarbeiten, muss dann nur noch das "markers" array durchgegangen werden. Das könnte z.B. so gemacht werden:
+
+.. code-block:: python
+
+    from compLib.Camera import *
+
+    camera = Camera()
+    while True:
+        image = camera.get_frame()
+
+        markers, image = camera.detect_markers_midpoint(image)
+        print(markers)
+        print("-----------------")
+
+        for marker in markers:
+            print(f"Marker mit der id: {marker.id}")
+            print(f"Ist auf der X Position: {marker.x}")
+            print(f"und auf der Y Position: {marker.y}")
+            print("-----------------")
+
+        camera.publish_frame(image)
+
+Wichtig ist noch zu beachten, dass die X und Y Positionen ihren Ursprung in der linken oberen Ecke des Bildes haben. D.h. die Position (0,0) ist im oberen linken Bildrand.