zed-python-api: Python API for the ZED SDK

# Stereolabs ZED - Python Wrapper
How to maintain the Python wrapper with Cython.

## Documentation

The **Cython** documentation: http://cython.org/

The **Cython** wiki: https://github.com/cython/cython/wiki

The **ZED SDK** documentation:
https://www.stereolabs.com/developers/documentation/API/latest

## Configuration

New packages can simply be added in the GPUmodulesTable with the package name and its *.pyx* file.

The version of the SDK and the wrapper is the same and should be indicated in the setup version.

Check the new Cython versions, they may need to update the wrapper.

## Notes

### General

* The wrapper keeps the same structure as the ZED SDK.
  
  * The classes of the wrapper contain a maximum of Python functions like str, repr, gettitem, settitem
  and properties.
  
  * *.pxd* files correspond to C++ headers and contain all the C++ methods and functions that can be used in
  the wrapper. *.pyx* files contain methods, functions and their bodies.
  
  * Python and C++ functions must be named differently.
  
  * Warning about deprecated Numpy API is showing during building but we can ignore it.
  
### Enum

* Enum must be redefined in order to use them with Python.
  They have their own representation so you must redefine str and repr if there is a string
  conversion function.
  
  * Enum arguments can't be typed directly with classes defined in the wrapper.
  They must be tested inside the functions.
  
### Types

* Each representation of matrix or vectors are done with Numpy.
  
  * Template can't be used with Cython. 
  Each function with a different type must be defined in a file like Utils.cpp
  
  * typedef made inside classes is not working in Cython. We can create it outside of the class and
  link it to its C++ declaration directly. See MeshFilterParameters FILTER in *mesh.pxd*
  for example.
  
  * Ctypes can be used, for example with *bool* type or *memcpy*.

* Vector2, Vector3, Vector4; float1, float2, float3, float4; uchar1, uchar2, uchar3, uchar4 
  are not available in Python but can be used in the wrapper.
  
### Code in *.pyx*
  
  * Other classes attributes must be declared in *.pxd* file instead of *.pyx* file if you want
  to have access to them when the package is imported.

* Default values of function arguments must be given in the Python function in *.pyx* file but not
  in the declaration in the *.pxd*.

* Python does not support constructor overloading but Cython does. However, this is not working
  when the number of arguments is the same but the types are different. The other constructors are
  defined in a C++ file with another name and called as a function after the creation of the Python object.
  
  * When there is an object to get defined in another file, it must be given in parameters 
  if not Python will interpret it as a C++ type trying to be converted in Python object and 
  won't work.

* Subclasses of Matrix3f and Matrix4f have both Matrix and their own type as attributes.
  For example: PyTransform has a sl::Transform and sl::Matrix4f attributes initialized.
  
  * Python will crash if you return a C++ object not initialized (like an empty sl::String).
 
  * *memcpy* is used when there is not any access to pointer data directly.
  
## Limitations

* PyMat/Mat constructor with resolution and pointer not working directly when Mat
    constructors with width and height are defined because of the same number of arguments,
    replaced by matResolution redefined in Utils.cpp.
  
  * ```Normalise(const Orientation  orient)```
 is not working, replaced by normalizing the Orientation argument with normalise().
  
  * Overloading operators like *=, /=, += and -= (for Vector3 and Vector4) are not supported by Cython.

dongzhou/zed-python-api

简介

发行版

贡献者

近期动态

dongzhou/zed-python-api .gitee-modal { width: 500px !important; }

简介

发行版

贡献者

近期动态

搜索帮助

dongzhou/zed-python-api