Skip to main content

Defining the Future of 3D Machine Vision

Project description

Zivid Python

Zivid Python is the official Python package for Zivid 3D cameras. Read more about Zivid at zivid.com.

Build Status PyPI Package Zivid Image


Contents: Installation | Quick Start | Examples | Versioning | License | Support | Test Matrix


Installation

Dependencies

Ubuntu users must install Python headers (apt install python3-dev) in addition to the regular python3 package.

Windows users also needs to make sure that the Zivid SDK installation folder is in system PATH before using the package, not only the terminal PATH variable. The default install location that should be added to system PATH is C:\Program Files\Zivid\bin.

Installing official version from PyPI using PIP

After 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 zivid

Note:

If you don't use the latest Zivid SDK version you need to manually specify the version. See Versioning.

Installation may take some time since the setup.py script will download additional dependencies and compile C++ source code in the background.

On some systems Python 3 pip is called pip3. In this guide we assume it is called pip. When using PIP version 19 or higher build dependencies are handled automatically.

Old PIP

If you are using a version of PIP older than version 19 please manually install the dependencies listed in pyproject.toml before installing zivid.

pip install <packages listed in pyproject.toml>
pip install zivid

Installing from source

git clone <zivid-python clone URL>
cd zivid-python
pip install .

The above pip install . command may give permission issues on some Windows machines. If so, try the following instead:

python continuous-integration/windows/create_binary_distribution.py
pip install ./dist/*.whl

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, edit setup.py to target the new SDK version before doing pip install .. Note that this option is considered experimental/unofficial.

Quick Start

Point cloud capture

To 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 from Zivid Studio or downloaded from the Zivid Knowledge Base settings 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 access

Data 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 array

Capture Assistant

Instead 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 emulation

If you do not have a camera, you can use the FileCameraZivid2M70.zfc file in the Sample Data to 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")

Examples

Basic example programs can be found in the samples directory. Many more advanced example programs may be found in the separate zivid-python-samples repository.

Versioning

This python module is using PEP 440 for versioning. The features available in the module depends on the Zivid SDK version used when building the module. When updating this Python package it is recommended to also update to the latest Zivid SDK. Refer to the Test Matrix for supported version.

The version number of the Zivid Python module consists of six numbers. The three first numbers of the version is the semantic version of 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 out zivid-python-releases-url or run pip index versions zivid.

Version breakdown

                                    Zivid 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)

PyPI

When 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 SDK

pip install zivid

Install version 1.0.0 of Zivid Python using latest version of Zivid SDK

pip install zivid==1.0.0

Install version 1.0.0 of Zivid Python using Zivid SDK version 1.4.0

pip install zivid==1.0.0.1.4.0

Install version 1.0.0 of Zivid Python using Zivid SDK version 1.3.0

pip install zivid==1.0.0.1.3.0

Support for older versions of Zivid SDK will be discontinued when they are no longer compatible with latest version of the wrapper code.

License

This project is licensed, see the LICENSE file for details. The licenses of dependencies are listed here.

Support

Please visit Zivid Knowledge Base for general information on using Zivid 3D cameras. If you cannot find a solution to your issue, please contact customersuccess@zivid.com.

Test matrix

Operating System Python version
Ubuntu 24.04 3.12
Ubuntu 23.10 3.11
Ubuntu 22.04 3.10
Ubuntu 20.04 3.8
Fedora 39 3.12
Fedora 40 3.12
Windows 10 3.7, 3.8, 3.9, 3.10, 3.11, 3.12

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

zivid-2.13.1.2.13.1.tar.gz (84.6 kB view details)

Uploaded Source

Built Distributions

zivid-2.13.1.2.13.1-cp312-cp312-win_amd64.whl (611.0 kB view details)

Uploaded CPython 3.12 Windows x86-64

zivid-2.13.1.2.13.1-cp311-cp311-win_amd64.whl (610.4 kB view details)

Uploaded CPython 3.11 Windows x86-64

zivid-2.13.1.2.13.1-cp310-cp310-win_amd64.whl (610.6 kB view details)

Uploaded CPython 3.10 Windows x86-64

zivid-2.13.1.2.13.1-cp39-cp39-win_amd64.whl (541.5 kB view details)

Uploaded CPython 3.9 Windows x86-64

zivid-2.13.1.2.13.1-cp38-cp38-win_amd64.whl (610.9 kB view details)

Uploaded CPython 3.8 Windows x86-64

zivid-2.13.1.2.13.1-cp37-cp37m-win_amd64.whl (586.6 kB view details)

Uploaded CPython 3.7m Windows x86-64

File details

Details for the file zivid-2.13.1.2.13.1.tar.gz.

File metadata

  • Download URL: zivid-2.13.1.2.13.1.tar.gz
  • Upload date:
  • Size: 84.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.3

File hashes

Hashes for zivid-2.13.1.2.13.1.tar.gz
Algorithm Hash digest
SHA256 545e13ebc52b033ccfddb416cb52b93c1bd871df6d0bc1986c46b0a92adc3dab
MD5 19eb5ad8c4b52b3f87b15ea96a07afd2
BLAKE2b-256 32c24ba5ba752122c55cc31d5a07d9ec44e14f4c09963bdd41dcc7dcb88da118

See more details on using hashes here.

File details

Details for the file zivid-2.13.1.2.13.1-cp312-cp312-win_amd64.whl.

File metadata

File hashes

Hashes for zivid-2.13.1.2.13.1-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 6d84c85fcac1265bf2067eb63911e9f37250825725c7008a1066f923c2ccd2ba
MD5 0350a1881385bbae19c619afc4d4e3ad
BLAKE2b-256 f3f1d0bbf0367b86c88fd540c9f999e0e8b0963dc3243bf03f70d1bcb456618e

See more details on using hashes here.

File details

Details for the file zivid-2.13.1.2.13.1-cp311-cp311-win_amd64.whl.

File metadata

File hashes

Hashes for zivid-2.13.1.2.13.1-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 9783fdad9ed8032829c34606b24b83fbb775494bfe2575eb1e6223c40130ed40
MD5 8bece7c34d8d657b998a1b01703a226c
BLAKE2b-256 b2f50450c96ba9359c35b0f886042fd23265009e58d938b52eef8af19eda9f67

See more details on using hashes here.

File details

Details for the file zivid-2.13.1.2.13.1-cp310-cp310-win_amd64.whl.

File metadata

File hashes

Hashes for zivid-2.13.1.2.13.1-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 24e7f942ed512b4fe524460a6b7993e0710f0e800fffe87a876e00feeb95091a
MD5 16c67fbe6651892801b8b7ec92c22ef2
BLAKE2b-256 ec7e68e7539be2d6206a81d4eb2a727e6c3821493d18af61a9b27ba825ddc2b4

See more details on using hashes here.

File details

Details for the file zivid-2.13.1.2.13.1-cp39-cp39-win_amd64.whl.

File metadata

File hashes

Hashes for zivid-2.13.1.2.13.1-cp39-cp39-win_amd64.whl
Algorithm Hash digest
SHA256 22049d2b6564a5ad06bd349d7cb537d9daa70d417e191ad8fd92b77bc81b5e88
MD5 ff8250c32ad6302739f19ebb7756f7f5
BLAKE2b-256 78f103890aeccfb609a31c4a268f25a874521524e5df47fafae30672cfbace15

See more details on using hashes here.

File details

Details for the file zivid-2.13.1.2.13.1-cp38-cp38-win_amd64.whl.

File metadata

File hashes

Hashes for zivid-2.13.1.2.13.1-cp38-cp38-win_amd64.whl
Algorithm Hash digest
SHA256 5717e049a07aab72618801eb4bb756fe9cea45bd6201994a1a5eff75f0a52c53
MD5 62b969ffaa8a0c4d1824da2433307d02
BLAKE2b-256 0809c6c86a27592c3e86eca5fdda336c2762cebe87e1553668f2e7ba325d29c0

See more details on using hashes here.

File details

Details for the file zivid-2.13.1.2.13.1-cp37-cp37m-win_amd64.whl.

File metadata

File hashes

Hashes for zivid-2.13.1.2.13.1-cp37-cp37m-win_amd64.whl
Algorithm Hash digest
SHA256 790f08e7bb4d48c442bc83768f0a51d7189eecec6b16d34c2ba31e26bde10644
MD5 b425d64026255b08693dbd70923efe41
BLAKE2b-256 f1a0a2db4f5209e851a374a275a7e7f0010751ea9210f220a2ad1611a6e5cc16

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page