Stable API (#62)

* API break, major changes: removed Py prefix, move to unified sl namespace
stereolabs · Dec 14, 2018 · a16e114 · a16e114
1 parent 7227db6
commit a16e114
Show file tree

Hide file tree

Showing 30 changed files with 3,875 additions and 4,123 deletions.
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2017 Stereolabs
+Copyright (c) 2018 Stereolabs
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/README.md b/README.md
@@ -1,7 +1,13 @@
-# Stereolabs ZED - Python Integration (beta)
+# Stereolabs ZED - Python API
 
 This package lets you use the ZED stereo camera in Python 3.
 
+## Stable API notice
+
+The ZED Python API is now stable but has some breaking changes from the previous (beta) version. The older beta version can be found in the [legacy branch](https://github.com/stereolabs/zed-python-api/tree/legacy).
+
+The changes were made to better reflect the C++ API and ease of use. Mainly all classes have a similar name to the C++ SDK (without the "Py" prefix), and all components were migrated to a unified `sl` namespace.
+
 ## Getting started
 
 - First, download the latest version of the ZED SDK on [stereolabs.com](https://www.stereolabs.com/developers)
@@ -63,18 +69,12 @@ You can use `python setup.py cleanall` to remove every cpp files generated and b
 
 Import the packages in your Python terminal or file like this:
 ```
-import pyzed.camera as zcam
-import pyzed.core as mat
-import pyzed.defines as sl
-import pyzed.types as types
-import pyzed.mesh as mesh
-import numpy as np
+import pyzed.sl as sl
 ```
+
 Vectors operations like norm, sum, square, dot, cross, distance but also simple operations can be done with
 Numpy package.
 
-**Note:** **pyzed.camera* is linked with *pyzed.core* and *pyzed.mesh* packages so you must import *pyzed.camera* before *pyzed.core* and *pyzed.mesh* to avoid import errors.
-
 ### Run the tutorials
 
 The [tutorials](tutorials) provide simple projects to show how to use each module of the ZED SDK. For a similar version using the C++ API checkout the [Cpp tutorials](https://github.com/stereolabs/zed-examples/tree/master/tutorials).
@@ -85,4 +85,4 @@ Please refer to the [examples](examples) README for more informations.
 
 ## Contributing
 
-This is a beta version of the wrapper. Feel free to open an issue if you find a bug, or a pull request for bug fixes, features or other improvements.
+Feel free to open an issue if you find a bug, or a pull request for bug fixes, features or other improvements.
diff --git a/examples/README.md b/examples/README.md
@@ -34,3 +34,18 @@ Mesh sample shows mesh information after filtering and applying texture on frame
 python examples/mesh_example.py svo_file.svo
 ```
 
+### Object
+
+Object sample shows the objects detected and tracked by the AI module with their bouding boxes and their 3D positions
+
+```
+python examples/object_example.py
+```
+
+### Plane
+
+Plane sample is searching for the floor in a video and extracts it into a mesh if it found it.
+
+```
+python examples/plane_example.py svo_file.svo
+```
diff --git a/examples/live_camera.py b/examples/live_camera.py
@@ -24,38 +24,35 @@
 """
 
 import cv2
-import pyzed.camera as zcam
-import pyzed.types as tp
-import pyzed.core as core
-import pyzed.defines as sl
+import pyzed.sl as sl
 
-camera_settings = sl.PyCAMERA_SETTINGS.PyCAMERA_SETTINGS_BRIGHTNESS
+camera_settings = sl.CAMERA_SETTINGS.CAMERA_SETTINGS_BRIGHTNESS
 str_camera_settings = "BRIGHTNESS"
 step_camera_settings = 1
 
 
 def main():
     print("Running...")
-    init = zcam.PyInitParameters()
-    cam = zcam.PyZEDCamera()
+    init = sl.InitParameters()
+    cam = sl.Camera()
     if not cam.is_opened():
         print("Opening ZED Camera...")
     status = cam.open(init)
-    if status != tp.PyERROR_CODE.PySUCCESS:
+    if status != sl.ERROR_CODE.SUCCESS:
         print(repr(status))
         exit()
 
-    runtime = zcam.PyRuntimeParameters()
-    mat = core.PyMat()
+    runtime = sl.RuntimeParameters()
+    mat = sl.Mat()
 
     print_camera_information(cam)
     print_help()
 
     key = ''
     while key != 113:  # for 'q' key
         err = cam.grab(runtime)
-        if err == tp.PyERROR_CODE.PySUCCESS:
-            cam.retrieve_image(mat, sl.PyVIEW.PyVIEW_LEFT)
+        if err == sl.ERROR_CODE.SUCCESS:
+            cam.retrieve_image(mat, sl.VIEW.VIEW_LEFT)
             cv2.imshow("ZED", mat.get_data())
             key = cv2.waitKey(5)
             settings(key, cam, runtime, mat)
@@ -97,13 +94,13 @@ def settings(key, cam, runtime, mat):
             cam.set_camera_settings(camera_settings, current_value - step_camera_settings)
             print(str_camera_settings + ": " + str(current_value - step_camera_settings))
     elif key == 114:  # for 'r' key
-        cam.set_camera_settings(sl.PyCAMERA_SETTINGS.PyCAMERA_SETTINGS_BRIGHTNESS, -1, True)
-        cam.set_camera_settings(sl.PyCAMERA_SETTINGS.PyCAMERA_SETTINGS_CONTRAST, -1, True)
-        cam.set_camera_settings(sl.PyCAMERA_SETTINGS.PyCAMERA_SETTINGS_HUE, -1, True)
-        cam.set_camera_settings(sl.PyCAMERA_SETTINGS.PyCAMERA_SETTINGS_SATURATION, -1, True)
-        cam.set_camera_settings(sl.PyCAMERA_SETTINGS.PyCAMERA_SETTINGS_GAIN, -1, True)
-        cam.set_camera_settings(sl.PyCAMERA_SETTINGS.PyCAMERA_SETTINGS_EXPOSURE, -1, True)
-        cam.set_camera_settings(sl.PyCAMERA_SETTINGS.PyCAMERA_SETTINGS_WHITEBALANCE, -1, True)
+        cam.set_camera_settings(sl.CAMERA_SETTINGS.CAMERA_SETTINGS_BRIGHTNESS, -1, True)
+        cam.set_camera_settings(sl.CAMERA_SETTINGS.CAMERA_SETTINGS_CONTRAST, -1, True)
+        cam.set_camera_settings(sl.CAMERA_SETTINGS.CAMERA_SETTINGS_HUE, -1, True)
+        cam.set_camera_settings(sl.CAMERA_SETTINGS.CAMERA_SETTINGS_SATURATION, -1, True)
+        cam.set_camera_settings(sl.CAMERA_SETTINGS.CAMERA_SETTINGS_GAIN, -1, True)
+        cam.set_camera_settings(sl.CAMERA_SETTINGS.CAMERA_SETTINGS_EXPOSURE, -1, True)
+        cam.set_camera_settings(sl.CAMERA_SETTINGS.CAMERA_SETTINGS_WHITEBALANCE, -1, True)
         print("Camera settings: reset")
     elif key == 122:  # for 'z' key
         record(cam, runtime, mat)
@@ -112,51 +109,51 @@ def settings(key, cam, runtime, mat):
 def switch_camera_settings():
     global camera_settings
     global str_camera_settings
-    if camera_settings == sl.PyCAMERA_SETTINGS.PyCAMERA_SETTINGS_BRIGHTNESS:
-        camera_settings = sl.PyCAMERA_SETTINGS.PyCAMERA_SETTINGS_CONTRAST
+    if camera_settings == sl.CAMERA_SETTINGS.CAMERA_SETTINGS_BRIGHTNESS:
+        camera_settings = sl.CAMERA_SETTINGS.CAMERA_SETTINGS_CONTRAST
         str_camera_settings = "Contrast"
         print("Camera settings: CONTRAST")
-    elif camera_settings == sl.PyCAMERA_SETTINGS.PyCAMERA_SETTINGS_CONTRAST:
-        camera_settings = sl.PyCAMERA_SETTINGS.PyCAMERA_SETTINGS_HUE
+    elif camera_settings == sl.CAMERA_SETTINGS.CAMERA_SETTINGS_CONTRAST:
+        camera_settings = sl.CAMERA_SETTINGS.CAMERA_SETTINGS_HUE
         str_camera_settings = "Hue"
         print("Camera settings: HUE")
-    elif camera_settings == sl.PyCAMERA_SETTINGS.PyCAMERA_SETTINGS_HUE:
-        camera_settings = sl.PyCAMERA_SETTINGS.PyCAMERA_SETTINGS_SATURATION
+    elif camera_settings == sl.CAMERA_SETTINGS.CAMERA_SETTINGS_HUE:
+        camera_settings = sl.CAMERA_SETTINGS.CAMERA_SETTINGS_SATURATION
         str_camera_settings = "Saturation"
         print("Camera settings: SATURATION")
-    elif camera_settings == sl.PyCAMERA_SETTINGS.PyCAMERA_SETTINGS_SATURATION:
-        camera_settings = sl.PyCAMERA_SETTINGS.PyCAMERA_SETTINGS_GAIN
+    elif camera_settings == sl.CAMERA_SETTINGS.CAMERA_SETTINGS_SATURATION:
+        camera_settings = sl.CAMERA_SETTINGS.CAMERA_SETTINGS_GAIN
         str_camera_settings = "Gain"
         print("Camera settings: GAIN")
-    elif camera_settings == sl.PyCAMERA_SETTINGS.PyCAMERA_SETTINGS_GAIN:
-        camera_settings = sl.PyCAMERA_SETTINGS.PyCAMERA_SETTINGS_EXPOSURE
+    elif camera_settings == sl.CAMERA_SETTINGS.CAMERA_SETTINGS_GAIN:
+        camera_settings = sl.CAMERA_SETTINGS.CAMERA_SETTINGS_EXPOSURE
         str_camera_settings = "Exposure"
         print("Camera settings: EXPOSURE")
-    elif camera_settings == sl.PyCAMERA_SETTINGS.PyCAMERA_SETTINGS_EXPOSURE:
-        camera_settings = sl.PyCAMERA_SETTINGS.PyCAMERA_SETTINGS_WHITEBALANCE
+    elif camera_settings == sl.CAMERA_SETTINGS.CAMERA_SETTINGS_EXPOSURE:
+        camera_settings = sl.CAMERA_SETTINGS.CAMERA_SETTINGS_WHITEBALANCE
         str_camera_settings = "White Balance"
         print("Camera settings: WHITEBALANCE")
-    elif camera_settings == sl.PyCAMERA_SETTINGS.PyCAMERA_SETTINGS_WHITEBALANCE:
-        camera_settings = sl.PyCAMERA_SETTINGS.PyCAMERA_SETTINGS_BRIGHTNESS
+    elif camera_settings == sl.CAMERA_SETTINGS.CAMERA_SETTINGS_WHITEBALANCE:
+        camera_settings = sl.CAMERA_SETTINGS.CAMERA_SETTINGS_BRIGHTNESS
         str_camera_settings = "Brightness"
         print("Camera settings: BRIGHTNESS")
 
 
 def record(cam, runtime, mat):
-    vid = tp.PyERROR_CODE.PyERROR_CODE_FAILURE
+    vid = sl.ERROR_CODE.ERROR_CODE_FAILURE
     out = False
-    while vid != tp.PyERROR_CODE.PySUCCESS and not out:
+    while vid != sl.ERROR_CODE.SUCCESS and not out:
         filepath = input("Enter filepath name: ")
         vid = cam.enable_recording(filepath)
         print(repr(vid))
-        if vid == tp.PyERROR_CODE.PySUCCESS:
+        if vid == sl.ERROR_CODE.SUCCESS:
             print("Recording started...")
             out = True
             print("Hit spacebar to stop recording: ")
             key = False
             while key != 32:  # for spacebar
                 err = cam.grab(runtime)
-                if err == tp.PyERROR_CODE.PySUCCESS:
+                if err == sl.ERROR_CODE.SUCCESS:
                     cam.retrieve_image(mat)
                     cv2.imshow("ZED", mat.get_data())
                     key = cv2.waitKey(5)

diff --git a/examples/mesh_example.py b/examples/mesh_example.py
@@ -23,10 +23,7 @@
     parameters can be saved.
 """
 import sys
-import pyzed.camera as zcam
-import pyzed.core as core
-import pyzed.mesh as mesh
-import pyzed.types as tp
+import pyzed.sl as sl
 
 
 def main():
@@ -38,22 +35,22 @@ def main():
     filepath = sys.argv[1]
     print("Reading SVO file: {0}".format(filepath))
 
-    cam = zcam.PyZEDCamera()
-    init = zcam.PyInitParameters(svo_input_filename=filepath)
+    cam = sl.Camera()
+    init = sl.InitParameters(svo_input_filename=filepath)
     status = cam.open(init)
-    if status != tp.PyERROR_CODE.PySUCCESS:
+    if status != sl.ERROR_CODE.SUCCESS:
         print(repr(status))
         exit()
 
-    runtime = zcam.PyRuntimeParameters()
-    spatial = zcam.PySpatialMappingParameters()
-    transform = core.PyTransform()
-    tracking = zcam.PyTrackingParameters(transform)
+    runtime = sl.RuntimeParameters()
+    spatial = sl.SpatialMappingParameters()
+    transform = sl.Transform()
+    tracking = sl.TrackingParameters(transform)
 
     cam.enable_tracking(tracking)
     cam.enable_spatial_mapping(spatial)
 
-    pymesh = mesh.PyMesh()
+    pymesh = sl.Mesh()
     print("Processing...")
     for i in range(200):
         cam.grab(runtime)
@@ -63,11 +60,11 @@ def main():
     cam.disable_tracking()
     cam.disable_spatial_mapping()
 
-    filter_params = mesh.PyMeshFilterParameters()
-    filter_params.set(mesh.PyFILTER.PyFILTER_HIGH)
+    filter_params = sl.MeshFilterParameters()
+    filter_params.set(sl.MESH_FILTER.MESH_FILTER_HIGH)
     print("Filtering params : {0}.".format(pymesh.filter(filter_params)))
 
-    apply_texture = pymesh.apply_texture(mesh.PyMESH_TEXTURE_FORMAT.PyMESH_TEXTURE_RGBA)
+    apply_texture = pymesh.apply_texture(sl.MESH_TEXTURE_FORMAT.MESH_TEXTURE_RGBA)
     print("Applying texture : {0}.".format(apply_texture))
     print_mesh_information(pymesh, apply_texture)
 
@@ -88,7 +85,7 @@ def print_mesh_information(pymesh, apply_texture):
                 print("Triangles : \n{0} \n".format(pymesh.triangles))
                 break
             else:
-                print("Cannot display information of the mesh.")
+                print("Cannot display information of the sl.")
                 break
         if res == "n":
             print("Mesh information will not be displayed.")
@@ -101,8 +98,8 @@ def save_filter(filter_params):
     while True:
         res = input("Do you want to save the mesh filter parameters? [y/n]: ")
         if res == "y":
-            params = tp.PyERROR_CODE.PyERROR_CODE_FAILURE
-            while params != tp.PyERROR_CODE.PySUCCESS:
+            params = sl.ERROR_CODE.ERROR_CODE_FAILURE
+            while params != sl.ERROR_CODE.SUCCESS:
                 filepath = input("Enter filepath name : ")
                 params = filter_params.save(filepath)
                 print("Saving mesh filter parameters: {0}".format(repr(params)))
@@ -122,8 +119,8 @@ def save_mesh(pymesh):
     while True:
         res = input("Do you want to save the mesh? [y/n]: ")
         if res == "y":
-            msh = tp.PyERROR_CODE.PyERROR_CODE_FAILURE
-            while msh != tp.PyERROR_CODE.PySUCCESS:
+            msh = sl.ERROR_CODE.ERROR_CODE_FAILURE
+            while msh != sl.ERROR_CODE.SUCCESS:
                 filepath = input("Enter filepath name: ")
                 msh = pymesh.save(filepath)
                 print("Saving mesh: {0}".format(repr(msh)))

diff --git a/examples/multi_camera.py b/examples/multi_camera.py
@@ -23,38 +23,35 @@
 """
 
 import cv2
-import pyzed.camera as zcam
-import pyzed.types as tp
-import pyzed.core as core
-import pyzed.defines as sl
+import pyzed.sl as sl
 
 
 def main():
     print("Running...")
-    init = zcam.PyInitParameters()
-    init.camera_resolution = sl.PyRESOLUTION.PyRESOLUTION_HD720
+    init = sl.InitParameters()
+    init.camera_resolution = sl.RESOLUTION.RESOLUTION_HD720
     init.camera_linux_id = 0
     init.camera_fps = 30  # The framerate is lowered to avoid any USB3 bandwidth issues
-    cam = zcam.PyZEDCamera()
+    cam = sl.Camera()
     if not cam.is_opened():
         print("Opening ZED Camera 1...")
     status = cam.open(init)
-    if status != tp.PyERROR_CODE.PySUCCESS:
+    if status != sl.ERROR_CODE.SUCCESS:
         print(repr(status))
         exit()
 
     init.camera_linux_id = 1  # selection of the ZED ID
-    cam2 = zcam.PyZEDCamera()
+    cam2 = sl.Camera()
     if not cam2.is_opened():
         print("Opening ZED Camera 2...")
     status = cam2.open(init)
-    if status != tp.PyERROR_CODE.PySUCCESS:
+    if status != sl.ERROR_CODE.SUCCESS:
         print(repr(status))
         exit()
 
-    runtime = zcam.PyRuntimeParameters()
-    mat = core.PyMat()
-    mat2 = core.PyMat()
+    runtime = sl.RuntimeParameters()
+    mat = sl.Mat()
+    mat2 = sl.Mat()
 
     print_camera_information(cam)
     print_camera_information(cam2)
@@ -63,13 +60,13 @@ def main():
     while key != 113:  # for 'q' key
         # The computation could also be done in a thread, one for each camera
         err = cam.grab(runtime)
-        if err == tp.PyERROR_CODE.PySUCCESS:
-            cam.retrieve_image(mat, sl.PyVIEW.PyVIEW_LEFT)
+        if err == sl.ERROR_CODE.SUCCESS:
+            cam.retrieve_image(mat, sl.VIEW.VIEW_LEFT)
             cv2.imshow("ZED 1", mat.get_data())
 
         err = cam2.grab(runtime)
-        if err == tp.PyERROR_CODE.PySUCCESS:
-            cam2.retrieve_image(mat2, sl.PyVIEW.PyVIEW_LEFT)
+        if err == sl.ERROR_CODE.SUCCESS:
+            cam2.retrieve_image(mat2, sl.VIEW.VIEW_LEFT)
             cv2.imshow("ZED 2", mat2.get_data())
 
         key = cv2.waitKey(5)