IGLPicker
Module: graphics
GPU-accelerated ray casting picker for interactive geometry selection.
Supports multi-level picking: body, face, and edge selection with filtering.
Uses ray-AABB and ray-triangle intersection for efficient spatial queries.
Attributes:
last_result: The most recent pick operation result.
CENTER_TOL: Tolerance for tie-breaking when multiple faces share
the same intersection distance.
filter: Active picking filter mode (body, face, or edge).
__init__
method
__init__(self, center_tol: float)
Initialize the picker.
Args
| Name | Type | Description |
|---|---|---|
| center_tol | Tolerance for face center-distance tie-breaking. | Defaults to 1e-3. |
Setfilter
method
Setfilter(self, filter: int)
Set the active picking filter mode.
Args
| Name | Type | Description |
|---|---|---|
| filter | An IGLFilterMode constant (F_WGLBODY, F_WGLFACE, or F_WGLEDGE). |
pick
method
pick(self, mx: float, my: float, width: int, height: int, proj: Any, view: Any, bodies: Sequence[Any])
Perform ray casting intersection test on a collection of bodies.
Generates a view-space ray from screen coordinates, then tests
intersection against all selectable bodies. Returns the closest
intersection according to the active filter mode.
Generates a view-space ray from screen coordinates, then tests
intersection against all selectable bodies. Returns the closest
intersection according to the active filter mode.
Args
| Name | Type | Description |
|---|---|---|
| mx | Mouse x-coordinate in screen space [0, width). | |
| my | Mouse y-coordinate in screen space [0, height). | |
| width | Viewport width in pixels. | |
| height | Viewport height in pixels. | |
| proj | Projection matrix (QMatrix4x4). | |
| view | View matrix (QMatrix4x4). | |
| bodies | Sequence of selectable body objects with geometry data. |
Returns
PickResult containing the closest intersection, or empty result
if no intersections were found.
compute_ray
method
compute_ray(self, mx: float, my: float, w: int, h: int, proj: Any, view: Any)
Convert screen coordinates to a world-space ray via unprojection.
Uses the inverse of the combined projection-view matrix to map
two z-depth samples (near and far planes) to world space, yielding
a ray origin and direction.
Uses the inverse of the combined projection-view matrix to map
two z-depth samples (near and far planes) to world space, yielding
a ray origin and direction.
Args
| Name | Type | Description |
|---|---|---|
| mx | Mouse x-coordinate in screen space. | |
| my | Mouse y-coordinate in screen space. | |
| w | Viewport width in pixels. | |
| h | Viewport height in pixels. | |
| proj | Projection matrix (QMatrix4x4). | |
| view | View matrix (QMatrix4x4). |
Returns
Tuple of (ray_origin, ray_direction) as float64 numpy arrays
of shape (3,). ray_direction is normalized.
_intersect_body
method
_intersect_body(self, ray_origin: np.ndarray, ray_dir: np.ndarray, body: Any)
Test ray intersection against a single body's geometry.
Performs hierarchical intersection testing: first against the body's
bounding box, then delegates to face or edge intersection based on
the active filter mode.
Performs hierarchical intersection testing: first against the body's
bounding box, then delegates to face or edge intersection based on
the active filter mode.
Args
| Name | Type | Description |
|---|---|---|
| ray_origin | Ray origin in world space (shape (3,)). | |
| ray_dir | Ray direction in world space, normalized (shape (3,)). | |
| body | Body object with geometry (bb_min, bb_max, faces, edges). |
Returns
PickResult with the best intersection for this body, or empty
if no intersection occurred.
_ray_triangle
method
_ray_triangle(self, orig: np.ndarray, dir: np.ndarray, v0: np.ndarray, v1: np.ndarray, v2: np.ndarray)
Test ray-triangle intersection using the Möller–Trumbore algorithm.
Args
| Name | Type | Description |
|---|---|---|
| orig | Ray origin (shape (3,)). | |
| dir | Ray direction, should be normalized (shape (3,)). | |
| v0 | First triangle vertex (shape (3,)). | |
| v1 | Second triangle vertex (shape (3,)). | |
| v2 | Third triangle vertex (shape (3,)). |
Returns
Scalar parameter t along the ray at intersection, or None
if no intersection or intersection is behind ray origin.
_ray_segment_distance
method
_ray_segment_distance(self, ro: np.ndarray, rd: np.ndarray, p0: np.ndarray, p1: np.ndarray)
Compute closest-approach distance between a ray and a line segment.
Args
| Name | Type | Description |
|---|---|---|
| ro | Ray origin (shape (3,)). | |
| rd | Ray direction, should be normalized (shape (3,)). | |
| p0 | Segment start point (shape (3,)). | |
| p1 | Segment end point (shape (3,)). |
Returns
Tuple of (t_on_ray, distance) where t_on_ray is the ray parameter
at closest approach and distance is the separation. Returns
(None, None) if the segment is parallel to or not clamped to [0, 1].
_ray_aabb
method
_ray_aabb(self, orig: np.ndarray, dir: np.ndarray, bb_min: np.ndarray, bb_max: np.ndarray)
Test ray intersection against an axis-aligned bounding box (AABB).
Uses the slab method with tolerance for near-parallel rays.
Uses the slab method with tolerance for near-parallel rays.
Args
| Name | Type | Description |
|---|---|---|
| orig | Ray origin (shape (3,)). | |
| dir | Ray direction (shape (3,)). | |
| bb_min | AABB minimum corner (shape (3,)). | |
| bb_max | AABB maximum corner (shape (3,)). |
Returns
True if the ray intersects the AABB or passes through it, False otherwise.
qmatrix_to_numpy
method
qmatrix_to_numpy(self, m: Any)
Convert QMatrix4x4 to numpy array with correct orientation.
Transforms column-major QMatrix4x4 data to row-major numpy format
via explicit transpose.
Transforms column-major QMatrix4x4 data to row-major numpy format
via explicit transpose.
Args
| Name | Type | Description |
|---|---|---|
| m | QMatrix4x4 object with .data() method returning 16 floats. |
Returns
4x4 float32 numpy array in row-major order.
_qmat_to_np
method
_qmat_to_np(self, m: Any)
Convert QMatrix4x4 to numpy array via element access.
Args
| Name | Type | Description |
|---|---|---|
| m | QMatrix4x4 object with element access via m(row, col). |
Returns
4x4 float64 numpy array.
_unproject
method
_unproject(self, win: Sequence[float], model: np.ndarray, proj: np.ndarray, viewport: Sequence[float])
Convert normalized device coordinates to world space.
Inverts the combined projection-view matrix and applies perspective
division to transform screen-space coordinates to world space.
Inverts the combined projection-view matrix and applies perspective
division to transform screen-space coordinates to world space.
Args
| Name | Type | Description |
|---|---|---|
| win | Screen-space coordinate [x, y, z] where z ∈ [0, 1]. | |
| model | View matrix (4x4). | |
| proj | Projection matrix (4x4). | |
| viewport | Viewport bounds [x, y, width, height]. |
Returns
World-space point as float64 array of shape (3,).
getregion
method
getregion(self, posA: Tuple[float, float], posB: Tuple[float, float], w: int, h: int, proj: Any, view: Any)
Compute viewport pan and zoom parameters from a screen-space region.
Given two screen corners, calculates the translation and scale needed
to fit that region within the current viewport.
Given two screen corners, calculates the translation and scale needed
to fit that region within the current viewport.
Args
| Name | Type | Description |
|---|---|---|
| posA | First corner [x, y] in screen space. | |
| posB | Second corner [x, y] in screen space. | |
| w | Viewport width in pixels. | |
| h | Viewport height in pixels. | |
| proj | Projection matrix (QMatrix4x4). | |
| view | View matrix (QMatrix4x4). |
Returns
Tuple of (dx, dy, dRange) representing pan offset and zoom factor.