@hema-to/regl-scatterplot 1.14.1-hemato.3 → 1.16.0-hemato.0

package/README.md

@@ -516,6 +516,85 @@ scatterplot.draw([
 scatterplot.select([0, 1]);
 ```
 
+<a name="scatterplot.lassoSelect" href="#scatterplot.lassoSelect">#</a> scatterplot.<b>lassoSelect</b>(<i>vertices</i>, <i>options = {}</i>)
+
+Programmatically select points within a polygon region. This enables automated point selection without manual lasso interaction. This will trigger a `select` event (and `lassoEnd` event) unless `options.preventEvent === true`.
+
+**Arguments:**
+
+- `vertices` is an array of `[x, y]` coordinate pairs defining the polygon (minimum 3 vertices required). Coordinates are in **data space** by default (requires `xScale` and `yScale`), or **GL space** if `options.isGl === true`.
+- `options` [optional] is an object with the following properties:
+  - `merge`: if `true`, add the selected points to the current selection instead of replacing it.
+  - `remove`: if `true`, remove the selected points from the current selection.
+  - `isGl`: if `true`, interpret vertices as GL space coordinates (NDC). If `false` (default), interpret vertices as data space coordinates.
+  - `preventEvent`: if `true` the `select` and `lassoEnd` events will not be published.
+
+**Notes:**
+
+- Polygons are automatically closed if the first and last vertices differ.
+- Data space coordinates require `xScale` and `yScale` to be defined during scatterplot initialization.
+- GL space coordinates work without scales and are useful for direct NDC coordinate selection.
+
+**Examples:**
+
+```javascript
+import { scaleLinear } from 'd3-scale';
+
+// Create scatterplot with scales for data space coordinates
+const scatterplot = createScatterplot({
+  canvas,
+  xScale: scaleLinear().domain([0, 100]),
+  yScale: scaleLinear().domain([0, 100]),
+});
+
+// Draw points (internally stored in NDC, but we think in data space)
+scatterplot.draw([
+  [-0.8, -0.8],  // corresponds to data coords ~[10, 10]
+  [0.8, 0.8],    // corresponds to data coords ~[90, 90]
+  [0, 0],        // corresponds to data coords [50, 50]
+]);
+
+// Select points within a triangular region (data space coordinates)
+scatterplot.lassoSelect([
+  [10, 20],
+  [50, 80],
+  [90, 30]
+]);
+
+// Select points within a rectangle, merging with current selection
+scatterplot.lassoSelect(
+  [
+    [0, 0],
+    [100, 0],
+    [100, 100],
+    [0, 100]
+  ],
+  { merge: true }
+);
+
+// Remove points in a polygon from the current selection
+scatterplot.lassoSelect(
+  [
+    [40, 40],
+    [60, 40],
+    [60, 60],
+    [40, 60]
+  ],
+  { remove: true }
+);
+
+// Use GL space coordinates (useful without scales)
+scatterplot.lassoSelect(
+  [
+    [-0.5, -0.5],
+    [0.5, -0.5],
+    [0.5, 0.5],
+    [-0.5, 0.5]
+  ],
+  { isGl: true }
+);
+```
+
 <a name="scatterplot.deselect" href="#scatterplot.deselect">#</a> scatterplot.<b>deselect</b>(<i>options = {}</i>)
 
 Deselect all selected points. This will trigger a `deselect` event unless `options.preventEvent === true`.
@@ -764,6 +843,7 @@ can be read and written via [`scatterplot.get()`](#scatterplot.get) and [`scatte
 | colorBy                               | string                                       | `null`                              | See [data encoding](#property-by)                               | `true`   | `true`      |
 | sizeBy                                | string                                       | `null`                              | See [data encoding](#property-by)                               | `true`   | `true`      |
 | opacityBy                             | string                                       | `null`                              | See [data encoding](#property-by)                               | `true`   | `true`      |
+| pointOrder                            | int[]                                        | `null`                              | Array of point indices defining draw order                      | `true`   | `true`      |
 | deselectOnDblClick                    | boolean                                      | `true`                              |                                                                 | `true`   | `false`     |
 | deselectOnEscape                      | boolean                                      | `true`                              |                                                                 | `true`   | `false`     |
 | opacity                               | float                                        | `1`                                 | Must be in ]0, 1]                                               | `true`   | `false`     |
@@ -890,6 +970,20 @@ example go to [dynamic-opacity.html](https://flekschas.github.io/regl-scatterplo
 The implementation is an extension of [Ricky Reusser's awesome notebook](https://observablehq.com/@rreusser/selecting-the-right-opacity-for-2d-point-clouds).
 Huuuge kudos Ricky! 🙇‍♂️
 
+<a name="property-point-order" href="#property-point-order">#</a> <b>pointOrder:</b>
+
+By default, points are drawn in the order they appear in the input data. Since depth testing is disabled, later-drawn points render on top of earlier ones. To control the draw order, set `pointOrder` to an array of point indices. Points are drawn in array order, so the last index renders on top. Any indices not included in the array are appended in sequential order.
+
+```javascript
+// Ensure point 3 is drawn on top
+scatterplot.set({ pointOrder: [0, 1, 2, 4, 3] });
+
+// Reset to default input order
+scatterplot.set({ pointOrder: null });
+```
+
+The point order is respected when [filtering](#scatterplot.filter), and resets automatically when `draw()` is called with a different number of points.
+
 <a name="property-point-conntection-by" href="#property-point-conntection-by">#</a> <b>pointConnectionColorBy, pointConnectionOpacityBy, and pointConnectionSizeBy:</b>
 
 In addition to the properties understood by [`colorBy`, etc.](#property-by),

package/dist/regl-scatterplot.esm.d.ts

@@ -65,6 +65,7 @@ export function createSpatialIndex(points: import("./types").Points, useWorker?:
  */
 export function createTextureFromUrl(regl: import("regl").Regl, url: string, timeout?: number): Promise<import("regl").Texture2D>;
 declare function createScatterplot(initialProperties?: Partial<import("./types").Properties>): {
+    attachSpatialIndex: (buffer: any) => void;
     /**
      * Get whether the browser supports all necessary WebGL features
      * @return {boolean} If `true` the browser supports all necessary WebGL features
@@ -85,6 +86,7 @@ declare function createScatterplot(initialProperties?: Partial<import("./types")
     get: <Key extends keyof import("./types").Properties>(property: Key) => import("./types").Properties[Key];
     getScreenPosition: (pointIdx: number) => [number, number] | undefined;
     hover: (point: number, { showReticleOnce, preventEvent }?: import("./types").ScatterplotMethodOptions["hover"]) => void;
+    lassoSelect: (vertices: [number, number][], { merge, remove, isGl }?: import("./types").ScatterplotMethodOptions["lasso"]) => void;
     redraw: () => void;
     refresh: () => void;
     reset: (args_0?: Partial<{