refactor: add dedicated lassoSelect() method per code review

  - Replace overloaded select(polygon) with lassoSelect(vertices) API
  - Add isVertices() validation checking all vertices
  - Add verticesToPolygon() helper to auto-close polygons
  - Rename polygonDataToGl to verticesFromDataToGl for clarity
  - Addtests
  - Update programmatic-lasso example to use new API
  - Update changelog.md

Author: glebmoisseyev

CHANGELOG.md

@@ -1,6 +1,6 @@
 ## 1.15.0
 
-- Feat: add programmatic lasso selection API allowing `select()` to accept polygon vertices in data space. This enables automated point selection without manual interaction. Works with `merge` and `remove` options and requires `xScale` and `yScale` to be defined.
+- Feat: add programmatic lasso selection API via new `lassoSelect()` method that accept a polygon in either data or GL space. This enables automated point selection without manual interaction. Supports `merge` and `remove` options. Note, vertices in data space requires `xScale` and `yScale` to be defined.
 
 ## 1.14.1
 

example/programmatic-lasso.js

@@ -189,7 +189,7 @@ const createButton = (label, onClick, wide = false) => {
 // Button 1: Select bottom-left triangle
 buttonContainer.appendChild(
   createButton('△ Bottom-Left', () => {
-    scatterplot.select([
+    scatterplot.lassoSelect([
       [10, 10],
       [40, 10],
       [10, 40],
@@ -214,14 +214,14 @@ buttonContainer.appendChild(
       ]);
     }
 
-    scatterplot.select(polygon);
+    scatterplot.lassoSelect(polygon);
   })
 );
 
 // Button 3: Select center rectangle
 buttonContainer.appendChild(
   createButton('▭ Center', () => {
-    scatterplot.select([
+    scatterplot.lassoSelect([
       [30, 30],
       [70, 30],
       [70, 70],
@@ -233,7 +233,7 @@ buttonContainer.appendChild(
 // Button 4: Add diagonal stripe (merge)
 buttonContainer.appendChild(
   createButton('+ Diagonal (Merge)', () => {
-    scatterplot.select(
+    scatterplot.lassoSelect(
       [
         [0, 40],
         [60, 100],
@@ -248,7 +248,7 @@ buttonContainer.appendChild(
 // Button 5: Remove center square
 buttonContainer.appendChild(
   createButton('− Center (Remove)', () => {
-    scatterplot.select(
+    scatterplot.lassoSelect(
       [
         [40, 40],
         [60, 40],
@@ -279,7 +279,7 @@ buttonContainer.appendChild(
       ]);
     }
 
-    scatterplot.select(polygon);
+    scatterplot.lassoSelect(polygon);
   })
 );
 

src/index.js

@@ -148,19 +148,22 @@ import {
   isHorizontalLine,
   isMultipleColors,
   isPointInPolygon,
+  isPolygonAnnotation,
   isPositiveNumber,
   isRect,
   isSameRgbas,
   isStrictlyPositiveNumber,
   isString,
   isValidBBox,
   isVerticalLine,
+  isVertices,
   limit,
   max,
   min,
   rgbBrightness,
   toArrayOrientedPoints,
   toRgba,
+  verticesToPolygon,
 } from './utils.js';
 
 import { version } from '../package.json';
@@ -785,27 +788,11 @@ const createScatterplot = (
   };
 
   /**
-   * Check if argument is a polygon (array of [x, y] coordinate pairs)
-   * @param {any} arg - The argument to check
-   * @returns {boolean} True if argument is a valid polygon
-   */
-  const isPolygon = (arg) => {
-    return (
-      Array.isArray(arg) &&
-      arg.length >= 3 &&
-      Array.isArray(arg[0]) &&
-      arg[0].length === 2 &&
-      typeof arg[0][0] === 'number' &&
-      typeof arg[0][1] === 'number'
-    );
-  };
-
-  /**
-   * Convert polygon from data space to GL space for lasso selection
-   * @param {Array<[number, number]>} polygonData - Polygon vertices in data space
+   * Convert vertices from data space to GL space
+   * @param {Array<[number, number]>} vertices - Vertices in data space
    * @returns {number[] | null} Flat array of GL coordinates or null if scales not defined
    */
-  const polygonDataToGl = (polygonData) => {
+  const verticesFromDataToGl = (vertices) => {
     // Check if xScale/yScale are defined
     if (!(xScale && yScale)) {
       // biome-ignore lint/suspicious/noConsole: User warning for missing configuration
@@ -815,8 +802,8 @@ const createScatterplot = (
       return null;
     }
 
-    const polygonGl = [];
-    for (const [x, y] of polygonData) {
+    const verticesGl = [];
+    for (const [x, y] of vertices) {
       // Step 1: Data space → normalized [0, 1]
       const xNorm = (x - xDomainStart) / xDomainSize;
       const yNorm = (y - yDomainStart) / yDomainSize;
@@ -828,39 +815,21 @@ const createScatterplot = (
       // Step 3: NDC → GL space (camera transform)
       const [xGl, yGl] = getScatterGlPos(xNdc, yNdc);
 
-      polygonGl.push(xGl, yGl);
+      verticesGl.push(xGl, yGl);
     }
 
-    return polygonGl;
+    return verticesGl;
   };
 
   /**
    * Select and highlight a set of points
-   * @param {number | number[] | Array<[number, number]>} pointIdxs - Point indices or polygon vertices
+   * @param {number | number[]} pointIdxs
    * @param {import('./types').ScatterplotMethodOptions['select']}
    */
   const select = (
     pointIdxs,
     { merge = false, remove = false, preventEvent = false } = {},
   ) => {
-    // Check if input is a polygon (array of [x, y] coordinate pairs)
-    if (isPolygon(pointIdxs)) {
-      // Convert polygon from data space to GL space
-      const polygonGl = polygonDataToGl(pointIdxs);
-
-      if (!polygonGl) {
-        // Scales not defined, cannot proceed
-        return;
-      }
-
-      // Find points within the polygon using existing lasso logic
-      const pointsInPolygon = findPointsInLasso(polygonGl);
-
-      // Recursively call select with the found point indices
-      select(pointsInPolygon, { merge, remove, preventEvent });
-      return;
-    }
-
     const newSelectedPoints = Array.isArray(pointIdxs)
       ? pointIdxs
       : [pointIdxs];
@@ -938,6 +907,47 @@ const createScatterplot = (
     draw = true;
   };
 
+  /**
+   * Lasso a certain area and select contained points
+   * @param {[number, number][]} vertices - Lasso vertices in either data space (default) or GL space
+   * @param {import('./types').ScatterplotMethodOptions['lasso']}
+   */
+  const lassoSelect = (
+    vertices,
+    { merge = false, remove = false, isGl = false } = {},
+  ) => {
+    if (!isVertices(vertices)) {
+      throw new Error(
+        'Lasso selection requires at least 3 vertices as [x, y] coordinate pairs',
+      );
+    }
+
+    const closedPolygon = verticesToPolygon(vertices);
+
+    let polygonGl;
+    let polygonGlFlat;
+
+    if (isGl) {
+      polygonGl = closedPolygon;
+      polygonGlFlat = closedPolygon.flat();
+    } else {
+      polygonGlFlat = verticesFromDataToGl(closedPolygon);
+
+      if (!polygonGlFlat) {
+        throw new Error(
+          'xScale and yScale must be defined to convert lasso vertices from data space to GL space',
+        );
+      }
+
+      polygonGl = [];
+      for (let i = 0; i < polygonGlFlat.length; i += 2) {
+        polygonGl.push([polygonGlFlat[i], polygonGlFlat[i + 1]]);
+      }
+    }
+
+    lassoEnd(polygonGl, polygonGlFlat, { merge, remove });
+  };
+
   /**
    * @param {number} point
    * @param {import('./types').ScatterplotMethodOptions['hover']} options
@@ -2797,7 +2807,7 @@ const createScatterplot = (
           continue;
         }
 
-        if (isPolygon(annotation)) {
+        if (isPolygonAnnotation(annotation)) {
           newPoints.push(annotation.vertices.flatMap(identity));
           addColorAndWidth(annotation);
         }
@@ -4639,6 +4649,7 @@ const createScatterplot = (
     get,
     getScreenPosition,
     hover,
+    lassoSelect,
     redraw,
     refresh: renderer.refresh,
     reset: withDraw(reset),

src/utils.js

@@ -578,9 +578,48 @@ export const isRect = (annotation) =>
   Number.isFinite(annotation.x2) &&
   Number.isFinite(annotation.x2);
 
-export const isPolygon = (annotation) =>
+export const isPolygonAnnotation = (annotation) =>
   'vertices' in annotation && annotation.vertices.length > 1;
 
+/**
+ * Check if an array is a valid list of 2D vertices
+ * @param {any} arg - The argument to check
+ * @returns {boolean} True if argument is an array of [x, y] coordinate pairs
+ */
+export const isVertices = (arg) => {
+  if (!Array.isArray(arg) || arg.length < 3) {
+    return false;
+  }
+
+  for (const vertex of arg) {
+    if (
+      !Array.isArray(vertex) ||
+      vertex.length !== 2 ||
+      typeof vertex[0] !== 'number' ||
+      typeof vertex[1] !== 'number'
+    ) {
+      return false;
+    }
+  }
+
+  return true;
+};
+
+/**
+ * Ensure a list of vertices forms a closed polygon
+ * @param {Array<[number, number]>} vertices - Array of [x, y] coordinates
+ * @returns {Array<[number, number]>} Closed polygon (first vertex repeated at end if needed)
+ */
+export const verticesToPolygon = (vertices) => {
+  const polygon = [...vertices];
+  const firstVertex = vertices.at(0);
+  const lastVertex = vertices.at(-1);
+  if (firstVertex[0] !== lastVertex[0] || firstVertex[1] !== lastVertex[1]) {
+    polygon.push(firstVertex);
+  }
+  return polygon;
+};
+
 export const insertionSort = (array) => {
   const end = array.length;
   for (let i = 1; i < end; i++) {