Metadata-Version: 2.4
Name: pupil_labs_uvc
Version: 1.0.2
Summary: Usb Video Class Device bindings with format conversion tool
Home-page: https://github.com/pupil-labs/pyuvc
Author: Pupil Labs GmbH
Author-email: info@pupil-labs.com
License: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.6
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: importlib-metadata; python_version < "3.8"
Provides-Extra: docs
Requires-Dist: furo; extra == "docs"
Requires-Dist: jaraco.packaging>=9; extra == "docs"
Requires-Dist: rst.linker>=1.9; extra == "docs"
Requires-Dist: sphinx; extra == "docs"
Provides-Extra: example
Requires-Dist: opencv-python; extra == "example"
Requires-Dist: rich; extra == "example"
Provides-Extra: testing
Requires-Dist: pytest>=6; extra == "testing"
Requires-Dist: pytest-checkdocs>=2.4; extra == "testing"
Requires-Dist: pytest-cov; extra == "testing"
Requires-Dist: pytest-enabler>=1.3; extra == "testing"
Requires-Dist: pytest-mypy>=0.9.1; platform_python_implementation != "PyPy" and extra == "testing"
Dynamic: license-file

.. image:: https://img.shields.io/pypi/v/pupil-labs-uvc.svg
   :target: `PyPI link`_

.. image:: https://img.shields.io/pypi/pyversions/pupil-labs-uvc.svg
   :target: `PyPI link`_

.. _PyPI link: https://pypi.org/project/pupil-labs-uvc

.. image:: https://github.com/pupil-labs/pyuvc/actions/workflows/main.yml/badge.svg
   :target: https://github.com/pupil-labs/pyuvc/actions?query=workflow%3A%22tests%22
   :alt: tests

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
   :target: https://github.com/psf/black
   :alt: Code style: Black

.. .. image:: https://readthedocs.org/projects/skeleton/badge/?version=latest
..    :target: https://skeleton.readthedocs.io/en/latest/?badge=latest

.. image:: https://img.shields.io/badge/skeleton-2022-informational
   :target: https://blog.jaraco.com/skeleton

*****
pyuvc
*****

Python bindings for the Pupil Labs fork of `libuvc <https://github.com/pupil-labs/libuvc>`__
with super fast jpeg decompression using `libjpegturbo <http://libjpeg-turbo.virtualgl.org/>`__
(utilizing the tubojpeg api).

* cross platform access to UVC capture devices.
* Full access to all uvc settings (Zoom,Focus,Brightness,etc.)
* Full access to all stream and format parameters (rates,sizes,etc.)
* Enumerate all capture devices with device_list()
* Capture instance will always grab mjpeg conpressed frames from cameras.

Image data is returned as `Frame` object. This object will decompress and convert on the
fly when image data is requested. This gives the user the full flexiblity: Grab just the
jpeg buffers or have them converted to YUV or Gray or RGB and only when you need.

The `Frame` class has caching build in to avoid double decompression or conversion.

Install via PyPI
################

.. code-block::

   pip install pupil-labs-uvc

Example
#######

See `examples/` for code examples.

Install from source
###################

pyuvc requires the following dependencies:

- `libusb <https://github.com/libusb/libusb/>`__
- `libturbo-jpeg <https://libjpeg-turbo.org/>`__
- `POSIX Threads for Windows <https://sourceforge.net/projects/pthreads4w/>`__ (Windows
  only, supplied via the `pupil-pthreads-win <https://pypi.org/project/pupil-pthreads-win/>`__
  Python module)

Once the dependencies are installed, you can pip install the source tree::

   git clone https://github.com/pupil-labs/pyuvc --recursive
   export FORCE_LOCAL_LIBUVC_BUILD=ON
   pip install ./pyuvc

Linux
*****

Ubuntu/Debian::

   apt-get update -y
   apt-get install -y libusb-1.0-0-dev libturbojpeg-dev

Running as a non-root user
==========================

One needs to setup udev rules and add the target user to the ``plugdev`` group to avoid
the privileged access requirement.

.. code-block:: bash

   echo 'SUBSYSTEM=="usb",  ENV{DEVTYPE}=="usb_device", GROUP="plugdev", MODE="0664"' | sudo tee /etc/udev/rules.d/10-libuvc.rules > /dev/null
   sudo udevadm trigger
   sudo usermod -a -G plugdev $USER
   # logout and back in

macOS
*****

Homebrew::

   brew update
   brew install libusb jpeg-turbo

Running as a non-root user
==========================

Unfortunately, this is currently not possible. See
`this libusb issue thread <https://github.com/libusb/libusb/issues/1014>`__ for details.

WINDOWS
*******

Run the following code in a powershell to install the dependencies (requires
`7z <https://www.7-zip.org/>`__ to be installed)

.. code-block:: powershell

   pip install build delvewheel
   git clone https://github.com/pupil-labs/pyuvc --recursive
   cd pyuvc
   scripts/download-deps-win.ps1 -DEPS_TMP_PATH tmp
   $Env:DEPS_PATHS_LOC = "tmp/dep_paths.json"
   python -m build -w   # will create a wheel in dist/ folder; insert the wheel path below
   python scripts/repair-wheels-win.py $Env:DEPS_PATHS_LOC <wheel location> wheelhouse
   pip install wheelhouse/<wheel name>


Manual driver installation
==========================

pyuvc requires the libUSBk driver to be installed for your corresponding camera.
Otherwise, metadata like the product name will be set to ``"unknown"``.

Please see `these instructions <https://github.com/pupil-labs/pyuvc/blob/master/WINDOWS_USER.md>`__
on how to manually install libUSBk drivers for your specific camera.
