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.
Contents: Installation | Quick Start | Examples | Versioning | License | Support | Test Matrix
Installation
Dependencies
- Python version 3.7 or higher
- Zivid SDK version 2.16.0 (see here for help)
- Compiler with C++17 support
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 sdk_version.json
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()],
color=zivid.Settings2D(acquisitions=[zivid.Settings2D.Acquisition()]),
)
frame = camera.capture_2d_3d(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_2d_3d(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()],
color=zivid.Settings2D(acquisitions=[zivid.Settings2D.Acquisition()]),
)
frame = camera.capture_2d_3d(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_2d_3d(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_3d(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 released with the same version number as the Zivid SDK that it supports. The Zivid SDK is using semantic versioning with major, minor, and patch versions.
If a patch is released to fix an issue with this python module separately from a Zivid SDK patch release, then a fourth number signifying the patch version of the python module will be added to the end:
Version breakdown
Zivid SDK version = 2.16.0
v vv v
Zivid Python module version = 2.16.0.1
^
Zivid Python module patch version (omitted if 0)
[!NOTE] Versioning Prior to 2.16.0
Before version 2.16.0, this python module used a similar but different versioning scheme with six numbers. In this scheme, the first three numbers specified the semantic version of the python module while the next three numbers specified the semantic version of the supported Zivid SDK. In some early versions of the python module, these semantic versions could be different, but eventually they were synced up, and from version 2.16.0 the versioning system was simplified as explained above.
PyPI
When installing using PIP it is possible to specify the required version. This can be useful if using an older version of the Zivid SDK.
To see the complete list of released versions of this python module, see zivid-python-releases-url or run
pip index versions zivid
.
Note that as explained above, the versioning system was simplified starting with version 2.16.0 such that the Zivid Python is the same as the supported Zivid SDK version. Older releases used a different versioning scheme, which is also explained above.
Install latest version of Zivid Python using latest available version of Zivid SDK
pip install zivid
Note: The installation may fail if the latest available version of Zivid SDK is not installed on the system. See Installation.
Install a specific version of Zivid Python
pip install zivid==2.16.0
This requires Zivid SDK version 2.16.0 to be installed on the system.
Using the old versioning scheme, install version 2.6.0 of the Zivid Python wrapper supporting Zivid SDK 2.7.0
pip install zivid==2.6.0.2.7.0
This requires Zivid SDK version 2.7.0 to be installed on the system.
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
The test matrix shows which Python versions and operating systems are tested in CI. Click here to go to the test matrix.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
File details
Details for the file zivid-2.16.0.tar.gz
.
File metadata
- Download URL: zivid-2.16.0.tar.gz
- Upload date:
- Size: 113.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.12.9
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
289000b13d1834817a926c3530f1ca929cb903a9a4684d4c72f4ce037358745d
|
|
MD5 |
b15971fefec311c71a52a5b282fdcc75
|
|
BLAKE2b-256 |
0d1729b8cc88d881e1eaec19457f0a9660a6782f301e9c3e92b724a871c0375b
|
File details
Details for the file zivid-2.16.0-cp313-cp313-win_amd64.whl
.
File metadata
- Download URL: zivid-2.16.0-cp313-cp313-win_amd64.whl
- Upload date:
- Size: 679.6 kB
- Tags: CPython 3.13, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.12.9
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
70f46888e7a125690ee536663db43dbee6fe8abe6ce339aaa82b48488c31f08e
|
|
MD5 |
263d176f5cf7c6e59107b2a20123b047
|
|
BLAKE2b-256 |
24f8c46deb1c000389d8b072c0411e7d69ba1b630567ae6e61222e75bb71dc9c
|
File details
Details for the file zivid-2.16.0-cp312-cp312-win_amd64.whl
.
File metadata
- Download URL: zivid-2.16.0-cp312-cp312-win_amd64.whl
- Upload date:
- Size: 679.8 kB
- Tags: CPython 3.12, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.12.9
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
958a1351114c55a49e52297127206175fa087559f92f63b9ca0f670fa8486c4b
|
|
MD5 |
d75add0b1866c0fdd8ac3642b3e33100
|
|
BLAKE2b-256 |
242bf98ecd6cd3e5da9e4642884859e6046269870b5fdebdebad17375f3776ac
|
File details
Details for the file zivid-2.16.0-cp311-cp311-win_amd64.whl
.
File metadata
- Download URL: zivid-2.16.0-cp311-cp311-win_amd64.whl
- Upload date:
- Size: 670.4 kB
- Tags: CPython 3.11, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.12.9
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
ba7def246559cd400f503e427d8408068096c7370688111612c7e06405ecc930
|
|
MD5 |
334e66e12c53e056ee76e5d5d5e8265e
|
|
BLAKE2b-256 |
e2de366c95e8a772be54e2272b035ecd116a580bd1a9f394555da0f84987249d
|
File details
Details for the file zivid-2.16.0-cp310-cp310-win_amd64.whl
.
File metadata
- Download URL: zivid-2.16.0-cp310-cp310-win_amd64.whl
- Upload date:
- Size: 670.2 kB
- Tags: CPython 3.10, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.12.9
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
78651c7c3ac0b7d142430a88953fb8aae2edb64e41da0be617b029364fa087b2
|
|
MD5 |
1f1caae5b5b56c910def3099f83219ec
|
|
BLAKE2b-256 |
6d15b21c14069a5a12388df53d6cbe6bfec18414ec8bc829dd8e6a9daba5d085
|
File details
Details for the file zivid-2.16.0-cp39-cp39-win_amd64.whl
.
File metadata
- Download URL: zivid-2.16.0-cp39-cp39-win_amd64.whl
- Upload date:
- Size: 841.8 kB
- Tags: CPython 3.9, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.12.9
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
12621e4440e756fef2b96455c9f6a1ade6dd2d2705614d6d080ac95a42e42f30
|
|
MD5 |
bf79fa5e8314bd051b72c6899c64cd45
|
|
BLAKE2b-256 |
4a761034417c27ae953a1f5215afe3c5911571aed5ac4d750bf0a0d34891d39b
|
File details
Details for the file zivid-2.16.0-cp38-cp38-win_amd64.whl
.
File metadata
- Download URL: zivid-2.16.0-cp38-cp38-win_amd64.whl
- Upload date:
- Size: 670.0 kB
- Tags: CPython 3.8, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.12.9
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
b74f65b217c13f2f439c6a57d0ba3bb7de5731e814f4d1ea00d705efd599a4ce
|
|
MD5 |
8f77a2ac4ada0a801b64b262ddb6880c
|
|
BLAKE2b-256 |
eec1e876ddba8ae6871936d29993d02e6b322651c42a8413190f628a7348edb2
|
File details
Details for the file zivid-2.16.0-cp37-cp37m-win_amd64.whl
.
File metadata
- Download URL: zivid-2.16.0-cp37-cp37m-win_amd64.whl
- Upload date:
- Size: 650.8 kB
- Tags: CPython 3.7m, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.12.9
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
ea96a863ddb6ad34a7a5465c550600a7672fd60042dea6c529d0b40dd2e8335f
|
|
MD5 |
6cda328a6b04c14910ac97b6bd267e88
|
|
BLAKE2b-256 |
acbb11624e645f67310dd769b97d760dffbada3964e6f0e258c3f72de89f2164
|