Embreex

Warnings

• breaking A new major version `4.x` is in release candidate stage (`4.4.0rc0`). Future stable releases in this series may introduce breaking API changes compared to the current stable `2.x` series.
  Fix: Review the `4.x` changelog and documentation (once stable) for migration instructions before upgrading.
• gotcha Embreex is a fork of `scopatz/pyembree` with a name change to avoid confusion. While aiming for compatibility, users migrating from `pyembree` or other Embree Python bindings might encounter subtle API differences or behavioral changes.
  Fix: Refer to the `embreex` GitHub repository README for details on its relationship to other forks and ensure your code aligns with the `embreex` API.
• gotcha The library primarily provides pre-built wheels for easy installation on supported platforms (Windows, Linux, macOS) and Python versions (>=3.8). Installing on unsupported platforms, older Python versions (e.g., 3.6, 3.7 as mentioned in old documentation), or from source may require manual compilation of the underlying Intel Embree C++ library, which can be complex.
  Fix: Ensure your environment meets the pre-built wheel requirements (OS, Python version). If compilation is necessary, consult the `trimesh/embreex` GitHub repository for build instructions and dependencies.

Install

• pip install embreex Latest stable version

Imports

• embreex

  import embreex

  The core library is imported directly as `embreex`.
• RayMeshIntersector

  from embreex import RayMeshIntersector

  Used for creating a ray intersector object.
• EmbreeTrimesh

  from embreex import EmbreeTrimesh

  Used for creating an Embree-compatible mesh from NumPy arrays.

Quickstart

This quickstart demonstrates how to create a basic triangular mesh, initialize an `EmbreeTrimesh` object, create a `RayMeshIntersector`, and perform a ray-mesh intersection query to check for hits and retrieve hit details.

import embreex
import numpy as np

# Define a simple mesh (e.g., a triangle)
vertices = np.array([
    [0.0, 0.0, 0.0],
    [1.0, 0.0, 0.0],
    [0.0, 1.0, 0.0]
], dtype=np.float32)
faces = np.array([
   
], dtype=np.int32)

# Create an Embree mesh object
mesh = embreex.EmbreeTrimesh(vertices, faces)

# Create a ray intersector from the mesh
intersector = embreex.RayMeshIntersector(mesh)

# Define a single ray (origin and direction)
ray_origins = np.array([[0.1, 0.1, 1.0]], dtype=np.float32)
ray_directions = np.array([[0.0, 0.0, -1.0]], dtype=np.float32)

# Check if the ray hits the mesh
hits = intersector.intersects_any(ray_origins, ray_directions)
print(f"Ray hits mesh: {hits}")

# Find the first hit location and triangle index
index_tri, u, v, t = intersector.intersects_first(ray_origins, ray_directions)
if index_tri != -1:
    print(f"\nFirst hit details:")
    print(f"  Hit triangle index: {index_tri}")
    print(f"  Barycentric coordinates (U, V): {u:.4f}, {v:.4f}")
    print(f"  Distance along ray (t): {t:.4f}")
else:
    print("\nNo hit found for the ray.")