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


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.16.0.tar.gz (113.1 kB view details)

Uploaded Source

Built Distributions

zivid-2.16.0-cp313-cp313-win_amd64.whl (679.6 kB view details)

Uploaded CPython 3.13Windows x86-64

zivid-2.16.0-cp312-cp312-win_amd64.whl (679.8 kB view details)

Uploaded CPython 3.12Windows x86-64

zivid-2.16.0-cp311-cp311-win_amd64.whl (670.4 kB view details)

Uploaded CPython 3.11Windows x86-64

zivid-2.16.0-cp310-cp310-win_amd64.whl (670.2 kB view details)

Uploaded CPython 3.10Windows x86-64

zivid-2.16.0-cp39-cp39-win_amd64.whl (841.8 kB view details)

Uploaded CPython 3.9Windows x86-64

zivid-2.16.0-cp38-cp38-win_amd64.whl (670.0 kB view details)

Uploaded CPython 3.8Windows x86-64

zivid-2.16.0-cp37-cp37m-win_amd64.whl (650.8 kB view details)

Uploaded CPython 3.7mWindows x86-64

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

Hashes for zivid-2.16.0.tar.gz
Algorithm Hash digest
SHA256 289000b13d1834817a926c3530f1ca929cb903a9a4684d4c72f4ce037358745d
MD5 b15971fefec311c71a52a5b282fdcc75
BLAKE2b-256 0d1729b8cc88d881e1eaec19457f0a9660a6782f301e9c3e92b724a871c0375b

See more details on using hashes here.

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

Hashes for zivid-2.16.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 70f46888e7a125690ee536663db43dbee6fe8abe6ce339aaa82b48488c31f08e
MD5 263d176f5cf7c6e59107b2a20123b047
BLAKE2b-256 24f8c46deb1c000389d8b072c0411e7d69ba1b630567ae6e61222e75bb71dc9c

See more details on using hashes here.

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

Hashes for zivid-2.16.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 958a1351114c55a49e52297127206175fa087559f92f63b9ca0f670fa8486c4b
MD5 d75add0b1866c0fdd8ac3642b3e33100
BLAKE2b-256 242bf98ecd6cd3e5da9e4642884859e6046269870b5fdebdebad17375f3776ac

See more details on using hashes here.

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

Hashes for zivid-2.16.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 ba7def246559cd400f503e427d8408068096c7370688111612c7e06405ecc930
MD5 334e66e12c53e056ee76e5d5d5e8265e
BLAKE2b-256 e2de366c95e8a772be54e2272b035ecd116a580bd1a9f394555da0f84987249d

See more details on using hashes here.

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

Hashes for zivid-2.16.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 78651c7c3ac0b7d142430a88953fb8aae2edb64e41da0be617b029364fa087b2
MD5 1f1caae5b5b56c910def3099f83219ec
BLAKE2b-256 6d15b21c14069a5a12388df53d6cbe6bfec18414ec8bc829dd8e6a9daba5d085

See more details on using hashes here.

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

Hashes for zivid-2.16.0-cp39-cp39-win_amd64.whl
Algorithm Hash digest
SHA256 12621e4440e756fef2b96455c9f6a1ade6dd2d2705614d6d080ac95a42e42f30
MD5 bf79fa5e8314bd051b72c6899c64cd45
BLAKE2b-256 4a761034417c27ae953a1f5215afe3c5911571aed5ac4d750bf0a0d34891d39b

See more details on using hashes here.

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

Hashes for zivid-2.16.0-cp38-cp38-win_amd64.whl
Algorithm Hash digest
SHA256 b74f65b217c13f2f439c6a57d0ba3bb7de5731e814f4d1ea00d705efd599a4ce
MD5 8f77a2ac4ada0a801b64b262ddb6880c
BLAKE2b-256 eec1e876ddba8ae6871936d29993d02e6b322651c42a8413190f628a7348edb2

See more details on using hashes here.

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

Hashes for zivid-2.16.0-cp37-cp37m-win_amd64.whl
Algorithm Hash digest
SHA256 ea96a863ddb6ad34a7a5465c550600a7672fd60042dea6c529d0b40dd2e8335f
MD5 6cda328a6b04c14910ac97b6bd267e88
BLAKE2b-256 acbb11624e645f67310dd769b97d760dffbada3964e6f0e258c3f72de89f2164

See more details on using hashes here.

Supported by

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