fix(picker): update doc/definitions related to picking

BREAKING CHANGE: vtkPicker.intersectWithLine takes 5 parameters instead of 4. The fourth param, prop, is not used, so you can pass null.
Kitware · Mar 22, 2024 · 4cd4052 · 4cd4052
1 parent 32151d7
commit 4cd4052
Show file tree

Hide file tree

Showing 7 changed files with 76 additions and 45 deletions.
diff --git a/Sources/Rendering/Core/CellPicker/index.d.ts b/Sources/Rendering/Core/CellPicker/index.d.ts
@@ -2,7 +2,9 @@ import vtkCell from '../../../Common/DataModel/Cell';
 import { Vector3 } from '../../../types';
 import vtkMapper from '../Mapper';
 import vtkPicker, { IPickerInitialValues } from '../Picker';
+import vtkProp3D from '../Prop3D';
 import vtkRenderer from '../Renderer';
+import { Nullable } from "../../../types";
 
 /**
  * 
@@ -88,21 +90,33 @@ export interface vtkCellPicker extends vtkPicker {
 	 * 
 	 * @param {Vector3} p1 
 	 * @param {Vector3} p2 
-	 * @param {Number} tol 
+	 * @param {Number} tolerance
+	 * @param {Nullable<vtkProp3D>} actor
 	 * @param {vtkMapper} mapper The vtkMapper instance.
 	 */
-	intersectWithLine(p1: Vector3, p2: Vector3, tol: number, mapper: vtkMapper): number;
+	intersectWithLine(p1: Vector3, p2: Vector3, tolerance: number, actor: Nullable<vtkProp3D>, mapper: vtkMapper): number;
 
 	/**
 	 * 
 	 * @param {Vector3} p1 
 	 * @param {Vector3} p2 
 	 * @param {Number} t1 
 	 * @param {Number} t2 
-	 * @param {Number} tol 
+	 * @param {Number} tolerance
 	 * @param {vtkMapper} mapper The vtkMapper instance.
 	 */
-	intersectActorWithLine(p1: Vector3, p2: Vector3, t1: number, t2: number, tol: number, mapper: vtkMapper): number;
+	intersectActorWithLine(p1: Vector3, p2: Vector3, t1: number, t2: number, tolerance: number, mapper: vtkMapper): number;
+
+	/**
+	 * 
+	 * @param {Vector3} p1 
+	 * @param {Vector3} p2 
+	 * @param {Number} t1 
+	 * @param {Number} t2 
+	 * @param {Number} tolerance
+	 * @param {vtkMapper} mapper The vtkMapper instance.
+	 */
+	intersectVolumeWithLine(p1: Vector3, p2: Vector3, t1: number, t2: number, tolerance: number, mapper: vtkMapper): number;
 }
 
 /**

diff --git a/Sources/Rendering/Core/CellPicker/index.js b/Sources/Rendering/Core/CellPicker/index.js
@@ -172,7 +172,7 @@ function vtkCellPicker(publicAPI, model) {
     return pickResult;
   };
 
-  publicAPI.intersectWithLine = (p1, p2, tol, actor, mapper) => {
+  publicAPI.intersectWithLine = (p1, p2, tolerance, actor, mapper) => {
     let tMin = Number.MAX_VALUE;
     let t1 = 0.0;
     let t2 = 1.0;
@@ -217,9 +217,23 @@ function vtkCellPicker(publicAPI, model) {
           ? interceptionObject.t2
           : clipLine.t2;
 
-      tMin = publicAPI.intersectVolumeWithLine(p1, p2, t1, t2, tol, actor);
+      tMin = publicAPI.intersectVolumeWithLine(
+        p1,
+        p2,
+        t1,
+        t2,
+        tolerance,
+        actor
+      );
     } else if (mapper.isA('vtkMapper')) {
-      tMin = publicAPI.intersectActorWithLine(p1, p2, t1, t2, tol, mapper);
+      tMin = publicAPI.intersectActorWithLine(
+        p1,
+        p2,
+        t1,
+        t2,
+        tolerance,
+        mapper
+      );
     }
 
     if (tMin < model.globalTMin) {
@@ -266,7 +280,7 @@ function vtkCellPicker(publicAPI, model) {
     return tMin;
   };
 
-  publicAPI.intersectVolumeWithLine = (p1, p2, t1, t2, tol, volume) => {
+  publicAPI.intersectVolumeWithLine = (p1, p2, t1, t2, tolerance, volume) => {
     let tMin = Number.MAX_VALUE;
     const mapper = volume.getMapper();
     const imageData = mapper.getInputData();
@@ -388,7 +402,7 @@ function vtkCellPicker(publicAPI, model) {
     return tMin;
   };
 
-  publicAPI.intersectActorWithLine = (p1, p2, t1, t2, tol, mapper) => {
+  publicAPI.intersectActorWithLine = (p1, p2, t1, t2, tolerance, mapper) => {
     let tMin = Number.MAX_VALUE;
     const minXYZ = [0, 0, 0];
     let pDistMin = Number.MAX_VALUE;
@@ -460,15 +474,15 @@ function vtkCellPicker(publicAPI, model) {
               t2,
               p1,
               p2,
-              tol,
+              tolerance,
               x,
               pCoords
             );
           } else {
-            cellPicked = cell.intersectWithLine(p1, p2, tol, x, pCoords);
+            cellPicked = cell.intersectWithLine(p1, p2, tolerance, x, pCoords);
           }
         } else {
-          cellPicked = cell.intersectWithLine(q1, q2, tol, x, pCoords);
+          cellPicked = cell.intersectWithLine(q1, q2, tolerance, x, pCoords);
           if (t1 !== 0.0 || t2 !== 1.0) {
             cellPicked.t = t1 * (1.0 - cellPicked.t) + t2 * cellPicked.t;
           }

diff --git a/Sources/Rendering/Core/Picker/index.d.ts b/Sources/Rendering/Core/Picker/index.d.ts
@@ -2,6 +2,7 @@ import { Vector3, Nullable } from "../../../types";
 import vtkAbstractPicker, { IAbstractPickerInitialValues } from "../AbstractPicker";
 import vtkActor from "../Actor";
 import vtkMapper from '../Mapper';
+import vtkProp3D from '../Prop3D';
 import vtkRenderer from '../Renderer';
 import { vtkSubscription } from "../../../interfaces";
 
@@ -72,10 +73,11 @@ export interface vtkPicker extends vtkAbstractPicker {
 	 * Project the center point of the mapper onto the ray and determine its parametric value
 	 * @param {Vector3} p1 
 	 * @param {Vector3} p2 
-	 * @param {Number} tol 
+	 * @param {Number} tolerance
+	 * @param {Nullable<vtkProp3D>} prop
 	 * @param {vtkMapper} mapper 
 	 */
-	intersectWithLine(p1: Vector3, p2: Vector3, tol: number, mapper: vtkMapper): number;
+	intersectWithLine(p1: Vector3, p2: Vector3, tolerance: number, prop: Nullable<vtkProp3D>, mapper: vtkMapper): number;
 
 	/**
 	 * Perform pick operation with selection point provided.
@@ -84,6 +86,15 @@ export interface vtkPicker extends vtkAbstractPicker {
 	 */
 	pick(selection: Vector3, renderer: vtkRenderer): void;
 
+	/**
+	 * Perform pick operation with the provided selection and focal points.
+	 * Both point are in world coordinates.
+	 * @param {Vector3} selectionPoint
+	 * @param {Vector3} focalPoint
+	 * @param {vtkRenderer} renderer
+	 */
+	pick3DPoint(selectionPoint: Vector3, focalPoint: Vector3, renderer: vtkRenderer): void;
+
 	/**
 	 * Set position in mapper coordinates of pick point.
 	 * @param {Number} x The x coordinate.
@@ -141,6 +152,8 @@ export function newInstance(initialValues?: IPickerInitialValues): vtkPicker;
  * picking of points or cells based on the geometry of any vtkProp3D, use the
  * subclasses vtkPointPicker or vtkCellPicker.  For hardware-accelerated
  * picking of any type of vtkProp, use vtkPropPicker or vtkWorldPointPicker.
+ *
+ * Note that only vtkProp3D's can be picked by vtkPicker.
  */
 export declare const vtkPicker: {
 	newInstance: typeof newInstance,

diff --git a/Sources/Rendering/Core/Picker/index.js b/Sources/Rendering/Core/Picker/index.js
@@ -104,15 +104,6 @@ function vtkPicker(publicAPI, model) {
     const ray = [];
     const hitPosition = [];
 
-    if (!renderer) {
-      vtkErrorMacro('You must specify a renderer.');
-      return;
-    }
-
-    //  Loop over all props.  Transform ray (defined from position of
-    //  camera to selection point) into coordinates of mapper (not
-    //  transformed to actors coordinates!  Reduces overall computation!!!).
-    //  Note that only vtkProp3D's can be picked by vtkPicker.
     const props = model.pickFromList ? model.pickList : renderer.getActors();
 
     // pre-allocate some arrays.
@@ -185,8 +176,8 @@ function vtkPicker(publicAPI, model) {
           const actorIndex = model.actors.indexOf(prop);
 
           if (actorIndex !== -1) {
-            // If already in list, compare the previous position we the new one,
-            // and update if the new is closer.
+            // If already in list, compare the previous picked position with the new one.
+            // Store the new one if it is closer from the ray endpoint.
             const previousPickedPosition = model.pickedPositions[actorIndex];
             if (
               vtkMath.distance2BetweenPoints(p1World, pickedPosition) <
@@ -386,13 +377,7 @@ function vtkPicker(publicAPI, model) {
     initialize();
     model.renderer = renderer;
 
-    const selectionX = selectionPoint[0];
-    const selectionY = selectionPoint[1];
-    const selectionZ = selectionPoint[2];
-
-    model.selectionPoint[0] = selectionX;
-    model.selectionPoint[1] = selectionY;
-    model.selectionPoint[2] = selectionZ;
+    vec3.copy(model.selectionPoint, selectionPoint);
 
     const view = renderer.getRenderWindow().getViews()[0];
     const dims = view.getViewportSize(renderer);
@@ -405,7 +390,8 @@ function vtkPicker(publicAPI, model) {
     const aspect = dims[0] / dims[1];
 
     const tolerance =
-      computeTolerance(selectionZ, aspect, renderer) * model.tolerance;
+      computeTolerance(model.selectionPoint[2], aspect, renderer) *
+      model.tolerance;
 
     pick3DInternal(renderer, tolerance, selectionPoint, focalPoint);
   };

diff --git a/Sources/Rendering/Core/PointPicker/index.d.ts b/Sources/Rendering/Core/PointPicker/index.d.ts
@@ -1,6 +1,8 @@
 import vtkPicker, { IPickerInitialValues } from "../Picker";
 import vtkMapper from "../Mapper";
 import { Vector3 } from "../../../types";
+import vtkProp3D from "../Prop3D";
+import { Nullable } from "../../../types";
 
 interface IPointPickerInitialValues extends IPickerInitialValues {
 	pointId?: number;
@@ -35,19 +37,21 @@ export interface vtkPointPicker extends vtkPicker {
 	 * 
 	 * @param {Vector3} p1 
 	 * @param {Vector3} p2 
-	 * @param {Number} tol 
+	 * @param {Number} tolerance 
+	 * @param {vtkProp3D} actor
 	 * @param {vtkMapper} mapper 
 	 */
-	intersectWithLine(p1: Vector3, p2: Vector3, tol: number, mapper: vtkMapper): number;
+	intersectWithLine(p1: Vector3, p2: Vector3, tolerance: number, actor: Nullable<vtkProp3D>, mapper: vtkMapper): number;
 
 	/**
 	 * 
 	 * @param {Vector3} p1 
 	 * @param {Vector3} p2 
-	 * @param {Number} tol 
+	 * @param {Number} tolerance
+	 * @param {vtkProp3D} actor
 	 * @param {vtkMapper} mapper 
 	 */
-	intersectActorWithLine(p1: Vector3, p2: Vector3, tol: number, mapper: vtkMapper): number;
+	intersectActorWithLine(p1: Vector3, p2: Vector3, tolerance: number, mapper: vtkMapper): number;
 
 	/**
 	 * Specify whether the point search should be based on cell points or directly on the point list.

diff --git a/Sources/Rendering/Core/PointPicker/index.js b/Sources/Rendering/Core/PointPicker/index.js
@@ -12,7 +12,7 @@ function vtkPointPicker(publicAPI, model) {
   // Set our className
   model.classHierarchy.push('vtkPointPicker');
 
-  publicAPI.intersectWithLine = (p1, p2, tol, actor, mapper) => {
+  publicAPI.intersectWithLine = (p1, p2, tolerance, actor, mapper) => {
     let tMin = Number.MAX_VALUE;
 
     if (mapper.isA('vtkImageMapper') || mapper.isA('vtkImageArrayMapper')) {
@@ -22,13 +22,13 @@ function vtkPointPicker(publicAPI, model) {
         model.pointIJK = pickData.ijk;
       }
     } else if (mapper.isA('vtkMapper')) {
-      tMin = publicAPI.intersectActorWithLine(p1, p2, tol, mapper);
+      tMin = publicAPI.intersectActorWithLine(p1, p2, tolerance, mapper);
     }
 
     return tMin;
   };
 
-  publicAPI.intersectActorWithLine = (p1, p2, tol, mapper) => {
+  publicAPI.intersectActorWithLine = (p1, p2, tolerance, mapper) => {
     // Get dataset
     const input = mapper.getInputData();
 
@@ -96,7 +96,7 @@ function vtkPointPicker(publicAPI, model) {
                 maxDist = dist;
               }
             } // end for i
-            if (maxDist <= tol && maxDist < minPtDist) {
+            if (maxDist <= tolerance && maxDist < minPtDist) {
               // within tolerance
               minPtId = ptId;
               minXYZ[0] = x[0];
@@ -132,7 +132,7 @@ function vtkPointPicker(publicAPI, model) {
               maxDist = dist;
             }
           } // end for i
-          if (maxDist <= tol && maxDist < minPtDist) {
+          if (maxDist <= tolerance && maxDist < minPtDist) {
             // within tolerance
             minPtId = ptId;
             minXYZ[0] = x[0];

diff --git a/Sources/Rendering/Core/VolumeMapper/index.d.ts b/Sources/Rendering/Core/VolumeMapper/index.d.ts
@@ -1,12 +1,12 @@
 import vtkPiecewiseFunction from "../../../Common/DataModel/PiecewiseFunction";
 import { Bounds, Range } from "../../../types";
-import vtkAbstractMapper, { IAbstractMapperInitialValues } from "../AbstractMapper";
+import vtkAbstractMapper3D, { IAbstractMapper3DInitialValues } from "../AbstractMapper3D";
 import { BlendMode, FilterMode } from "./Constants";
 
 /**
  *
  */
-export interface IVolumeMapperInitialValues extends IAbstractMapperInitialValues {
+export interface IVolumeMapperInitialValues extends IAbstractMapper3DInitialValues {
 	anisotropy?: number;
 	autoAdjustSampleDistances?: boolean;
 	averageIPScalarRange?: Range;
@@ -23,7 +23,7 @@ export interface IVolumeMapperInitialValues extends IAbstractMapperInitialValues
 	LAOKernelSize?: number;
 }
 
-export interface vtkVolumeMapper extends vtkAbstractMapper {
+export interface vtkVolumeMapper extends vtkAbstractMapper3D {
 
 	/**
      * Get the bounds for this mapper as [xmin, xmax, ymin, ymax,zmin, zmax].