Add Python bindings

Add libcamera Python bindings. pybind11 is used to generate the C++ <->
Python layer.

We use pybind11 'smart_holder' version to avoid issues with private
destructors and shared_ptr. There is also an alternative solution here:

pybind/pybind11#2067

Only a subset of libcamera classes are exposed. Implementing and testing
the wrapper classes is challenging, and as such only classes that I have
needed have been added so far.

Signed-off-by: Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>

Author: tomba

meson.build

@@ -177,6 +177,7 @@ summary({
             'Tracing support': tracing_enabled,
             'Android support': android_enabled,
             'GStreamer support': gst_enabled,
+            'Python bindings': pycamera_enabled,
             'V4L2 emulation support': v4l2_enabled,
             'cam application': cam_enabled,
             'qcam application': qcam_enabled,

meson_options.txt

@@ -58,3 +58,8 @@ option('v4l2',
         type : 'boolean',
         value : false,
         description : 'Compile the V4L2 compatibility layer')
+
+option('pycamera',
+        type : 'feature',
+        value : 'auto',
+        description : 'Enable libcamera Python bindings (experimental)')

src/meson.build

@@ -37,4 +37,5 @@ subdir('cam')
 subdir('qcam')
 
 subdir('gstreamer')
+subdir('py')
 subdir('v4l2')

src/py/libcamera/__init__.py

@@ -0,0 +1,84 @@
+# SPDX-License-Identifier: LGPL-2.1-or-later
+# Copyright (C) 2022, Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
+
+from ._libcamera import *
+
+
+class MappedFrameBuffer:
+    def __init__(self, fb):
+        self.__fb = fb
+
+    def __enter__(self):
+        import os
+        import mmap
+
+        fb = self.__fb
+
+        # Collect information about the buffers
+
+        bufinfos = {}
+
+        for i in range(fb.num_planes):
+            fd = fb.fd(i)
+
+            if fd not in bufinfos:
+                buflen = os.lseek(fd, 0, os.SEEK_END)
+                bufinfos[fd] = {'maplen': 0, 'buflen': buflen}
+            else:
+                buflen = bufinfos[fd]['buflen']
+
+            if fb.offset(i) > buflen or fb.offset(i) + fb.length(i) > buflen:
+                raise RuntimeError(f'plane is out of buffer: buffer length={buflen}, ' +
+                                   f'plane offset={fb.offset(i)}, plane length={fb.length(i)}')
+
+            bufinfos[fd]['maplen'] = max(bufinfos[fd]['maplen'], fb.offset(i) + fb.length(i))
+
+        # mmap the buffers
+
+        maps = []
+
+        for fd, info in bufinfos.items():
+            map = mmap.mmap(fd, info['maplen'], mmap.MAP_SHARED, mmap.PROT_READ | mmap.PROT_WRITE)
+            info['map'] = map
+            maps.append(map)
+
+        self.__maps = tuple(maps)
+
+        # Create memoryviews for the planes
+
+        planes = []
+
+        for i in range(fb.num_planes):
+            fd = fb.fd(i)
+            info = bufinfos[fd]
+
+            mv = memoryview(info['map'])
+
+            start = fb.offset(i)
+            end = fb.offset(i) + fb.length(i)
+
+            mv = mv[start:end]
+
+            planes.append(mv)
+
+        self.__planes = tuple(planes)
+
+        return self
+
+    def __exit__(self, exc_type, exc_value, exc_traceback):
+        for p in self.__planes:
+            p.release()
+
+        for mm in self.__maps:
+            mm.close()
+
+    @property
+    def planes(self):
+        return self.__planes
+
+
+def __FrameBuffer__mmap(self):
+    return MappedFrameBuffer(self)
+
+
+FrameBuffer.mmap = __FrameBuffer__mmap

src/py/libcamera/meson.build

@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: CC0-1.0
+
+py3_dep = dependency('python3', required : get_option('pycamera'))
+
+if not py3_dep.found()
+    pycamera_enabled = false
+    subdir_done()
+endif
+
+pycamera_enabled = true
+
+pybind11_proj = subproject('pybind11')
+pybind11_dep = pybind11_proj.get_variable('pybind11_dep')
+
+pycamera_sources = files([
+    'pyenums.cpp',
+    'pymain.cpp',
+])
+
+pycamera_deps = [
+    libcamera_public,
+    py3_dep,
+    pybind11_dep,
+]
+
+pycamera_args = [
+    '-fvisibility=hidden',
+    '-Wno-shadow',
+    '-DPYBIND11_USE_SMART_HOLDER_AS_DEFAULT',
+    '-DLIBCAMERA_BASE_PRIVATE',
+]
+
+destdir = get_option('libdir') / ('python' + py3_dep.version()) / 'site-packages' / 'libcamera'
+
+pycamera = shared_module('_libcamera',
+                         pycamera_sources,
+                         install : true,
+                         install_dir : destdir,
+                         name_prefix : '',
+                         dependencies : pycamera_deps,
+                         cpp_args : pycamera_args)
+
+run_command('ln', '-fsT', '../../../../src/py/libcamera/__init__.py',
+            meson.current_build_dir() / '__init__.py',
+            check: true)
+
+install_data(['__init__.py'], install_dir : destdir)
+
+# \todo Generate stubs when building. See https://peps.python.org/pep-0484/#stub-files
+# Note: Depends on pybind11-stubgen. To generate pylibcamera stubs:
+# $ PYTHONPATH=build/src/py pybind11-stubgen --no-setup-py -o build/src/py libcamera
+# $ mv build/src/py/libcamera-stubs/* build/src/py/libcamera/

src/py/libcamera/pyenums.cpp

@@ -0,0 +1,34 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+/*
+ * Copyright (C) 2022, Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
+ *
+ * Python bindings - Enumerations
+ */
+
+#include <libcamera/libcamera.h>
+
+#include <pybind11/smart_holder.h>
+
+namespace py = pybind11;
+
+using namespace libcamera;
+
+void init_pyenums(py::module &m)
+{
+	py::enum_<StreamRole>(m, "StreamRole")
+		.value("StillCapture", StreamRole::StillCapture)
+		.value("Raw", StreamRole::Raw)
+		.value("VideoRecording", StreamRole::VideoRecording)
+		.value("Viewfinder", StreamRole::Viewfinder);
+
+	py::enum_<ControlType>(m, "ControlType")
+		.value("None", ControlType::ControlTypeNone)
+		.value("Bool", ControlType::ControlTypeBool)
+		.value("Byte", ControlType::ControlTypeByte)
+		.value("Integer32", ControlType::ControlTypeInteger32)
+		.value("Integer64", ControlType::ControlTypeInteger64)
+		.value("Float", ControlType::ControlTypeFloat)
+		.value("String", ControlType::ControlTypeString)
+		.value("Rectangle", ControlType::ControlTypeRectangle)
+		.value("Size", ControlType::ControlTypeSize);
+}