Package: zivid
Zivid PythonZivid Python is the official Python package for Zivid 3D cameras. Read more about Zivid atzivid.com.Contents:Installation|Quick Start|Examples|Versioning|License|Support|Test MatrixInstallationDependenciesPythonversion 3.7 or higherZivid SDKversion 2.11.1 (seeherefor help)Compilerwith C++17 supportUbuntu users must install Python headers (apt install python3-dev) in addition to the regularpython3package.Windows users also needs to make sure that the Zivid SDK installation folder is in systemPATHbefore using the package, not only the terminal PATH variable. The default install location that should be added to systemPATHisC:\Program Files\Zivid\bin.Installing official version from PyPI using PIPAfter having installed the latest Zivid SDK, the easiest way to install Zivid Python is to use PIP to fetch the latest official version from PyPI:pip install zividNote:If you don't use the latest Zivid SDK version you need to manually specify the version. SeeVersioning.Installation may take some time since thesetup.pyscript will download additional dependencies and compile C++ source code in the background.On some systems Python 3pipis calledpip3. In this guide we assume it is calledpip. When using PIP version 19 or higher build dependencies are handled automatically.Old PIPIf you are using a version of PIP older than version 19 please manually install the dependencies listed inpyproject.tomlbefore installing zivid.pip install <packages listed in pyproject.toml>
pip install zividInstalling from sourcegit clone <zivid-python clone URL>
cd zivid-python
pip install .You may want to build Zivid Python against a different (but compatible) version of Zivid SDK. An example would be if Zivid SDK 2.1 was released but the official
Zivid Python still formally only supports SDK 2.0. Since all the features of the 2.0 API exist in the 2.1 API, Zivid Python can still be built with the new SDK
(but without wrapping the latest features). In order to achieve this, editsetup.pyto target the new SDK version before doingpip install .. Note that
this option is considered experimental/unofficial.Quick StartPoint cloud captureTo quickly capture a point cloud using default settings, run the following code:import zivid
app = zivid.Application()
camera = app.connect_camera()
settings = zivid.Settings(acquisitions=[zivid.Settings.Acquisition()])
frame = camera.capture(settings)
frame.save("result.zdf")Instead of using the API to define capture settings, it is also possible to load them from YML files that
have been exported fromZivid Studioor downloaded from the Zivid Knowledge Basesettings library. This can be done by providing the filesystem path to
such a file, for example:settings = Settings.load("ZividTwo_Settings_2xHDR_Normal.yml")
frame = camera.capture(settings)Point cloud data accessData can easily be accessed in the form of Numpy arrays:import zivid
app = zivid.Application()
camera = app.connect_camera()
settings = zivid.Settings(acquisitions=[zivid.Settings.Acquisition()])
frame = camera.capture(settings)
xyz = frame.point_cloud().copy_data("xyz") # Get point coordinates as [Height,Width,3] float array
rgba = frame.point_cloud().copy_data("rgba") # Get point colors as [Height,Width,4] uint8 array
bgra = frame.point_cloud().copy_data("bgra") # Get point colors as [Height,Width,4] uint8 arrayCapture AssistantInstead of manually adjusting settings, the Capture Assistant may be used to find the optimal settings for your scene:import zivid
app = zivid.Application()
camera = app.connect_camera()
capture_assistant_params = zivid.capture_assistant.SuggestSettingsParameters()
settings = zivid.capture_assistant.suggest_settings(camera, capture_assistant_params)
frame = camera.capture(settings)
frame.save("result.zdf")Using camera emulationIf you do not have a camera, you can use theFileCameraZivid2M70.zfcfile in theSample Datato emulate a camera.import zivid
app = zivid.Application()
camera = app.create_file_camera("path/to/FileCameraZivid2M70.zfc")
settings = zivid.Settings(acquisitions=[zivid.Settings.Acquisition()])
frame = camera.capture(settings)
frame.save("result.zdf")ExamplesBasic example programs can be found in thesamplesdirectory.
Many more advanced example programs may be found in the separatezivid-python-samplesrepository.VersioningThis python module is usingPEP 440for versioning. The features available in the module depends on the Zivid SDK version used when building the module. When updating this Python package it isrecommendedto also update to the latestZivid SDK. Refer to theTest Matrixfor supported version.The version number of the Zivid Python module consists of six numbers. The three first numbers of the version is thesemantic versionof the code in this repository. The last three numbers is the version of the underlying Zivid SDK library used by the Python module.To check which version of zivid-python that corresponds to a specific version of Zivid SDK, check outzivid-python-releases-urlor runpip index versions zivid.Version breakdownZivid SDK version = 1.4.1 (semantic version)
                                    v v v
Zivid Python module version = 1.0.0.1.4.1
                              ^ ^ ^
                              Wrapper code version = 1.0.0 (semantic version)PyPIWhen installing using PIP it is possible to specify the required version. This can be useful if upgrading Zivid SDK is not desired, but you want to update Zivid Python.Install latest version of Zivid Python using latest version of Zivid SDKpip install zividInstall version 1.0.0 of Zivid Python using latest version of Zivid SDKpip install zivid==1.0.0Install version 1.0.0 of Zivid Python using Zivid SDK version 1.4.0pip install zivid==1.0.0.1.4.0Install version 1.0.0 of Zivid Python using Zivid SDK version 1.3.0pip install zivid==1.0.0.1.3.0Support for older versions of Zivid SDK will be discontinued when they are no longer compatible with latest version of the wrapper code.LicenseThis project is licensed, see theLICENSEfile for details. The licenses of dependencies are listedhere.SupportPlease visitZivid Knowledge Basefor general information on using Zivid 3D cameras. If you cannot find a solution to your issue, please contactcustomersuccess@zivid.com.Test matrixOperating SystemPython versionUbuntu 23.103.11Ubuntu 23.043.11Ubuntu 22.043.10Ubuntu 20.043.8Fedora 383.11Fedora 373.11Windows 103.7, 3.8, 3.9, 3.10, 3.11, 3.12