documentation

python/CMakeLists.txt

@@ -13,15 +13,34 @@ FetchContent_MakeAvailable(pybind11)
 
 # Declare our python embree module
 pybind11_add_module(pyembree
-    src/bindings.cpp
-    #pyembree.cpp
-    #intersect_callback_guard.cpp
-    #rtcore_common.cpp
-    #rtcore_device.cpp
-    #rtcore_buffer.cpp
-    #rtcore_ray.cpp
-    #rtcore_geometry.cpp
-    #rtcore_scene.cpp
-    #rtcore_builder.cpp
-    #rtcore_quaternion.cpp
-)
+    #src/bindings.cpp
+    src/pyembree.cpp
+    src/intersect_callback_guard.cpp
+    src/rtcore_common.cpp
+    src/rtcore_device.cpp
+    src/rtcore_buffer.cpp
+    src/rtcore_ray.cpp
+    src/rtcore_geometry.cpp
+    src/rtcore_scene.cpp
+    src/rtcore_builder.cpp
+    src/rtcore_quaternion.cpp
+)
+
+
+# Make sure we have embree
+if (NOT embree_DIR)
+    message("-- building embree from source")
+    option(EMBREE_INSTALL_DEPENDENCIES "always on for pyembree" ON)
+    option(EMBREE_TUTORIALS "alway off for pyembree" OFF)
+    set(embree_BINARY_DIR ${CMAKE_BINARY_DIR}/_deps/embree-build)
+    message("bin dir    ${embree_BINARY_DIR}")
+    add_subdirectory(${CMAKE_CURRENT_LIST_DIR}/.. ${embree_BINARY_DIR})
+
+    message("EMBREE LIBS:   ${EMBREE_LIBRARIES}")
+else()
+    message("-- using embree from ${embree_DIR}")
+    set(embree_BINARY_DIR "${embree_DIR}/../../../bin")
+endif()
+
+target_include_directories(pyembree PRIVATE ${CMAKE_INSTALL_PREFIX}/include)
+target_link_libraries(pyembree PRIVATE embree)

python/README.md

@@ -1,33 +1,62 @@
-# pyembree - Python bindings for embree
+# PyEmbree - Python bindings for embree
 
-## Building pyembree
+These Python bindings for Embree are available under the same license as Intel® Embree. 
+By utilizing these bindings, you can access the full capabilities of the Embree API through a Python interface, making it easier to integrate Embree's powerful ray tracing functionalities into your Python projects. 
+For a comprehensive understanding of the available API functions and their usage, please refer to the Embree C-API documentation. 
+This documentation provides detailed descriptions and examples to help you effectively get you started with Embree in python applications.
 
-```
-cmake -B build -D embree_DIR=path/to/installed/embree/cmake/files
-cmake --build build
-```
+This is a pre-release version, and PyEmbree is still under active development. 
+In its current state, it provides a one-to-one mapping of the C-style Embree API, allowing users to utilize Embree's functionalities directly through Python. 
+This is however expected to change in the future, when Embree's SYCL support is integrated in a more unified and streamlined manner. 
+As development progresses, users can anticipate enhancements that will simplify and enrich the interaction with Embree's powerful ray tracing capabilities.
 
-## Running test
 
-Make sure that build artefacts of pyembree can be sourced by python, i.e. setting your PYTHONPATH.
-Make sure that embree binaries are located in you PATH.
+## Building, Installing, and Testing PyEmbree
 
-### Linux
+PyEmbree provides a `setup.py` to create a python wheel and install it locally to the system.
+To do so follow a few simple steps inside the `python` subfolder inside the Embree repository:
 
 ```
-export PYTHONPATH=<pyembree_dir>\build\src:$PYTHONPATH
-python
-
->>> import pyembree
->>> print(pyembree.RTC_INVALID_GEOMETRY_ID)
+pip install .
 ```
 
-### Windows
+You may then run the tutorials, e.g.:
 
 ```
-$env:PYTHONPATH += "<pyembree_dir>\build\src\Debug"
-python
+python tutorials/minimal.py
+```
+
+### Troubleshooting
+
+Dependencies are built and installed using the pip command. 
+If you encounter issues loading the module, please ensure that your PATH environment variable includes the location where the dependencies are installed.
+
+
+## API Extensions
+
+Embree functions that handle arrays of data, such as the rtcIntersect* class of functions, accept both Python lists and NumPy arrays. 
+When using NumPy arrays, it is crucial to ensure that the data is properly aligned to meet Embree's requirements. 
+To facilitate the use of these functions with NumPy, several helper functions are provided. 
+These helpers assist with generating and accessing ray hit data, making it easier to integrate Embree's capabilities with NumPy arrays.
+
+### rtcCreateRayHits
+
+This function creates a ray hits structure array from several NumPy arrays, which provide the ray origins, directions, and ray IDs component-wise. 
+The resulting Python array is properly aligned for use with rtcIntersect*.
+
+### rtcTransformRayHits
+
+Applies a transformation to a list of ray hit structures.
+
+### rtcRayHits_get_org(x|y|z), rtcRayHits_get_dir(x|y/|), rtcRayHits_get_tfar, rtcRayHits_get_rayids
+
+These functions provide convenient access to components within an array of ray hit structures. 
+They enable straightforward conversion between a structure of arrays and an array of structures for ray hits.
+
+### rtcIntersectN
 
->>> import pyembree
->>> print(pyembree.RTC_INVALID_GEOMETRY_ID)
-```
+This function extends the functionality of the rtcIntersect(1|4|8|16) functions found in the Embree C-API. 
+While it is possible to perform ray packet intersections from Python, doing so typically involves complex steps to ensure that arrays of ray hits are correctly aligned. 
+Constructing these aligned arrays can be challenging and error-prone from within Python. 
+The rtcIntersectN function simplifies this process by providing an interface that allows for the intersection of arrays of ray hit structures of any length. 
+It manages the complexities of ray packets and parallelization automatically, making the process more straightforward and efficient from within Python.

python/__init__.py

@@ -1,9 +1 @@
-print("AOEUAOEUAOEUAOEUAOEU")
-print("AOEUAOEUAOEUAOEUAOEU")
-print("AOEUAOEUAOEUAOEUAOEU")
-print("AOEUAOEUAOEUAOEUAOEU")
-print("AOEUAOEUAOEUAOEUAOEU")
-print("AOEUAOEUAOEUAOEUAOEU")
-print("AOEUAOEUAOEUAOEUAOEU")
-
 from .pyembree import *

python/setup.py

@@ -9,12 +9,34 @@
 from setuptools import setup, Extension
 from setuptools.command.build_ext import build_ext
 
+
+
+def tabulate(data):
+    if not data:
+        return ""
+
+    col_widths = [max(len(str(item)) for item in col) for col in zip(*data)]
+    format_str = ' | '.join(f'{{:<{width}}}' for width in col_widths)
+    table = [format_str.format(*row) for row in data]
+
+    return '\n'.join(table)
+
+
 class CMakeExtension(Extension):
     def __init__(self, name):
         Extension.__init__(self, name, sources=[])
 
 
 class CMakeBuild(build_ext):
+
+    user_options = build_ext.user_options + [
+        ('embree-config=', None, 'Comma separated list of embree configs')
+    ]
+
+    def initialize_options(self):
+        build_ext.initialize_options(self)
+        self.embree_config = ""
+
     def run(self):
         try:
             out = subprocess.check_output(['cmake', '--version'])
@@ -29,17 +51,22 @@ def run(self):
 
 
     def build_extension(self, ext):
-        extdir = os.path.join(os.path.abspath(os.path.dirname(self.get_ext_fullpath(ext.name))), ext.name)
-        print("AOEUAOEUAOEUAOEU")
-        print("AOEUAOEUAOEUAOEU")
-        print("AOEUAOEUAOEUAOEU")
-        print("extdir")
-        print(extdir)
+
+        extension_dir = os.path.join(os.path.abspath(os.path.dirname(self.get_ext_fullpath(ext.name))), ext.name)
+        setuppy_dir = os.path.abspath('')
+        build_dir = setuppy_dir + os.path.sep + 'build'
+        embree_install_dir = build_dir + os.path.sep + 'embree_install'
+        print(tabulate([
+            ["extension_dir", extension_dir],
+            ["setuppy_dir", setuppy_dir],
+            ["build_dir", build_dir],
+            ["embree_install_dir", embree_install_dir],
+        ]))
 
         cmake_args = [
-            '-DCMAKE_LIBRARY_OUTPUT_DIRECTORY=' + extdir,
-            '-DCMAKE_LIBRARY_OUTPUT_DIRECTORY_RELEASE=' + extdir,
-            '-DCMAKE_LIBRARY_OUTPUT_DIRECTORY_DEBUG=' + extdir,
+            '-DCMAKE_LIBRARY_OUTPUT_DIRECTORY=' + extension_dir,
+            '-DCMAKE_LIBRARY_OUTPUT_DIRECTORY_RELEASE=' + extension_dir,
+            '-DCMAKE_LIBRARY_OUTPUT_DIRECTORY_DEBUG=' + extension_dir,
             #'-DPYTHON_EXECUTABLE=' + sys.executable,
             #'-G Ninja',
         ]
@@ -50,27 +77,28 @@ def build_extension(self, ext):
         #    '-DCMAKE_C_COMPILER=clang',
         #]
 
-
-        print("debug")
-        print(self.debug)
-
         cfg = 'Debug' if self.debug else 'Release'
-        cmake_args += ['DCMAKE_BUILD_TYPE=' + cfg]
+        cmake_args += ['-DCMAKE_BUILD_TYPE=' + cfg]
+        cmake_args += ['-DEMBREE_MAX_ISA=SSE2']
+        cmake_args += ['-DCMAKE_INSTALL_PREFIX=' + embree_install_dir]
 
         print("cmake_args")
-        print(cmake_args)
+        print(tabulate([s.split('=') for s in cmake_args]))
 
         env = os.environ.copy()
         if not os.path.exists(self.build_temp):
             os.makedirs(self.build_temp)
 
-        subprocess.check_call(['cmake', os.path.abspath('')] + cmake_args, cwd=self.build_temp, env=env)
-        subprocess.check_call(['cmake', '--build', '.', '--config', cfg, '--verbose'], cwd=self.build_temp)
+        subprocess.check_call(['cmake', setuppy_dir] + cmake_args, cwd=self.build_temp, env=env)
+        subprocess.check_call(['cmake', '--build', '.', '--config', cfg, '-j', '--verbose'], cwd=self.build_temp)
         subprocess.check_call(['cmake', '--install', '.', '--verbose'], cwd=self.build_temp)
 
-        shutil.copy("__init__.py", extdir)
-
+        # copy additional dependencies
+        shutil.copy("__init__.py", extension_dir)
 
+        embree_bin_dir = embree_install_dir + os.path.sep + 'bin'
+        for f in os.listdir(embree_bin_dir):
+            shutil.copy(os.path.join(embree_bin_dir, f), extension_dir)
 
 
 setup(