API / geotoolkit3d / picking / RendererPicking / RendererPicking
picking.RendererPicking.RendererPicking
Default implementation for the picking renderer mechanism.
This class uses rendering as a way to do picking.
The idea is similar to the one used here: THREEJS tutorial
Instead of rendering color in each pixel, it will render more information coded as a rgba pixel.
Then it will read the pixel and extract the information encoded in it.
To do so, it will replace the current materials by custom shader-materials which will encode the required information into the pixel.
The picking might require several steps to retrieve all the information it needs, for each pass one rgba component will be read from the graphic card.
Typically it will execute the picking-rendering 4 passes:
- shape-identifier: First pass to find which shapes is at the given position using its identifier
- x-coordinate: Another pass to retrieve the world x coordinate at the pick position
- y-coordinate: Another pass to retrieve the world y coordinate at the pick position
- z-coordinate: Another pass to retrieve the world z coordinate at the pick position
One could add more passes to the picking by declaring them in the #getExtraPickingModes() of the picking material.
Unlike the Raycasting approach, the picking occurs on the GPU, which means that:
- Vertex&Fragment shader are supported
- No distance based criteria, the shape rendered at the given pixel coordinates is the one picked
- Performance is based on frame rendering performance only, however it may require several frames for a single picking operation
- Returns only the closest object(s) to the camera (the one(s) visible on screen), transparency is ignored. (see filtering)
Note that this picking implementation accepts a width&height parameters to select shapes in a rectangle centered on the given coordinates.
A given shape will be returned only once even if it has several pixels in the picked area.
The results entry for such case would correspond to the pixel closest to the given picking coordinate.
For example if the picked object fills the whole area being picked.
Then the picking coordinates returned will match the center of the picked rectangle.
This picking also accepts a 'filter' function that can hide objects that are not pickable.
As this filtering occurs prior to said GPU picking it may make some objects pickable even if those were initially hidden.
For example, if a cube is behind a plane, it's not pickable because it's hidden.
But if a filter that discards the plane is given, then the cube can be picked 'through' the plane.
This feature is intended to implement picking through non opaque object not as a convenience filter to ignore some shapes.
↳
RendererPicking
Constructors
Methods
▸ getClassName(): string
string
▸ Static getClassName(): string
string
▸ Static pick(plot, x, y, width?, height?, filter?): PickingResult[]
Do a picking at the given plot coordinates and returns the objects found at this location.
The returned objects will be in a json along with some meta information like xyz coordinates of the picked points.
If using a width or height greater than 0, several object might be picked at once.
In that case, the returned array would be sorted by distance to center pixel (device point given as parameter to this function).
If using a width or height greater than 0, one object may occupy several pixels in the picked area.
Such object will be be returned only once in the result array.
The results entry will correspond to the pixel closest to the given picking coordinate.
Example
import {RendererPicking} from '@int/geotoolkit3d/picking/RendererPicking';
import {Line} from 'three';
// Pick the objects in the rectangle of size 5,5 centered at (12,13)
const selection = RendererPicking.pick(plot, 12, 13, 2, 2, (object, pickable) => {
if (!pickable) return false; // If object is already filtered natively, keep filtering it
return !(object instanceof Line); // Prevent line picking, letting user pick through a line
});| Name | Type | Description |
|---|---|---|
plot | Plot | The target plot |
x | number | The x coordinate in plot device space |
y | number | The y coordinate in plot device space |
Optional width | number | The amount of pixels to consider on the left and right side of the given x (effective width will be 2 times given width, plus 1 (the center pixel)) |
Optional height | number | The amount of pixels to consider on the top and bottom side of the given y (effective height will be 2 times given height, plus 1 (the center pixel)) |
Optional filter | FilterFunction | A function that can filter the pickable shape, takes the object to filter and it's current pickable status as parameter. Note that this filtering occurs prior to picking. As a result, an object can be picked through a filtered object. (see filtering documentation) |
An array of jsons containing the intersecting object3d(s)
▸ Static pickArbitrary(plot, ray, width?, height?, filter?): PickingResult[]
Perform a 3D GPU picking selection based on an arbitrary ray picking (position + direction), rather than a camera/cursor-based picking. The ray length is unlimited, and the result will be the first intersection in the scene based on the ray direction.
| Name | Type | Description |
|---|---|---|
plot | Plot | the 3D Plot to select from. |
ray | Ray | the Three.js Ray object that defines the position and direction of the ray picking. |
Optional width | number | The amount of pixels to consider on the left and right side of the given x (effective width will be 2 times given width, plus 1 (the center pixel)) |
Optional height | number | The amount of pixels to consider on the top and bottom side of the given y (effective height will be 2 times given height, plus 1 (the center pixel)) |
Optional filter | FilterFunction | A function that can filter the pickable shape, takes the object to filter and it's current pickable status as parameter. Note that this filtering occurs prior to picking. As a result, an object can be picked through a filtered object. (see filtering documentation) |
result the picked object, if any
▸ Static setPickingMaterial(materialClassName, pickingMaterialConstructor): void
Register the picking material class to be used for picking for a given material.
The picking renderer requires custom implementation of materials that write information instead of pixels.
To customize the picking for a given object, one should implement the corresponding material and register it.
Deprecated
RendererPicking.setPickingMaterial is deprecated since 5.0, please use PickingMaterialRegistrar.setPickingMaterial instead.
See
| Name | Type | Description |
|---|---|---|
materialClassName | string | The picked material's classname to replace |
pickingMaterialConstructor | MaterialClass | The picking material's constructor |
void