@cosmos.gl/graph 2.2.0 → 2.3.0-beta.0

package/src/modules/Points/index.ts

@@ -6,7 +6,7 @@ import { defaultConfigValues } from '@/graph/variables'
 import drawPointsFrag from '@/graph/modules/Points/draw-points.frag'
 import drawPointsVert from '@/graph/modules/Points/draw-points.vert'
 import findPointsOnAreaSelectionFrag from '@/graph/modules/Points/find-points-on-area-selection.frag'
-import findPointsOnLassoSelectionFrag from '@/graph/modules/Points/find-points-on-lasso-selection.frag'
+import findPointsOnPolygonSelectionFrag from '@/graph/modules/Points/find-points-on-polygon-selection.frag'
 import drawHighlightedFrag from '@/graph/modules/Points/draw-highlighted.frag'
 import drawHighlightedVert from '@/graph/modules/Points/draw-highlighted.vert'
 import findHoveredPointFrag from '@/graph/modules/Points/find-hovered-point.frag'
@@ -42,7 +42,7 @@ export class Points extends CoreModule {
   private updatePositionCommand: regl.DrawCommand | undefined
   private dragPointCommand: regl.DrawCommand | undefined
   private findPointsOnAreaSelectionCommand: regl.DrawCommand | undefined
-  private findPointsOnLassoSelectionCommand: regl.DrawCommand | undefined
+  private findPointsOnPolygonSelectionCommand: regl.DrawCommand | undefined
   private findHoveredPointCommand: regl.DrawCommand | undefined
   private clearHoveredFboCommand: regl.DrawCommand | undefined
   private clearSampledPointsFboCommand: regl.DrawCommand | undefined
@@ -53,9 +53,9 @@ export class Points extends CoreModule {
   private greyoutStatusTexture: regl.Texture2D | undefined
   private sizeTexture: regl.Texture2D | undefined
   private trackedIndicesTexture: regl.Texture2D | undefined
-  private lassoPathTexture: regl.Texture2D | undefined
-  private lassoPathFbo: regl.Framebuffer2D | undefined
-  private lassoPathLength = 0
+  private polygonPathTexture: regl.Texture2D | undefined
+  private polygonPathFbo: regl.Framebuffer2D | undefined
+  private polygonPathLength = 0
   private drawPointIndices: regl.Buffer | undefined
   private hoveredPointIndices: regl.Buffer | undefined
   private sampledPointIndices: regl.Buffer | undefined
@@ -232,6 +232,7 @@ export class Points extends CoreModule {
           transformationMatrix: () => store.transform,
           spaceSize: () => store.adjustedSpaceSize,
           screenSize: () => store.screenSize,
+          pointOpacity: () => config.pointOpacity,
           greyoutOpacity: () => config.pointGreyoutOpacity ?? -1,
           greyoutColor: () => store.greyoutPointColor,
           backgroundColor: () => store.backgroundColor,
@@ -285,9 +286,9 @@ export class Points extends CoreModule {
       })
     }
 
-    if (!this.findPointsOnLassoSelectionCommand) {
-      this.findPointsOnLassoSelectionCommand = reglInstance({
-        frag: findPointsOnLassoSelectionFrag,
+    if (!this.findPointsOnPolygonSelectionCommand) {
+      this.findPointsOnPolygonSelectionCommand = reglInstance({
+        frag: findPointsOnPolygonSelectionFrag,
         vert: updateVert,
         framebuffer: () => this.selectedFbo as regl.Framebuffer2D,
         primitive: 'triangle strip',
@@ -300,8 +301,8 @@ export class Points extends CoreModule {
           spaceSize: () => store.adjustedSpaceSize,
           screenSize: () => store.screenSize,
           transformationMatrix: () => store.transform,
-          lassoPathTexture: () => this.lassoPathTexture,
-          lassoPathLength: () => this.lassoPathLength,
+          polygonPathTexture: () => this.polygonPathTexture,
+          polygonPathLength: () => this.polygonPathLength,
         },
       })
     }
@@ -412,6 +413,7 @@ export class Points extends CoreModule {
           scalePointsOnZoom: () => config.scalePointsOnZoom,
           maxPointSize: () => store.maxPointSize,
           pointGreyoutStatusTexture: () => this.greyoutStatusFbo,
+          universalPointOpacity: () => config.pointOpacity,
           greyoutOpacity: () => config.pointGreyoutOpacity ?? -1,
           darkenGreyout: () => store.darkenGreyout,
           backgroundColor: () => store.backgroundColor,
@@ -573,26 +575,26 @@ export class Points extends CoreModule {
     this.findPointsOnAreaSelectionCommand?.()
   }
 
-  public findPointsOnLassoSelection (): void {
-    this.findPointsOnLassoSelectionCommand?.()
+  public findPointsOnPolygonSelection (): void {
+    this.findPointsOnPolygonSelectionCommand?.()
   }
 
-  public updateLassoPath (lassoPath: [number, number][]): void {
+  public updatePolygonPath (polygonPath: [number, number][]): void {
     const { reglInstance } = this
-    this.lassoPathLength = lassoPath.length
+    this.polygonPathLength = polygonPath.length
 
-    if (lassoPath.length === 0) {
-      this.lassoPathTexture = undefined
-      this.lassoPathFbo = undefined
+    if (polygonPath.length === 0) {
+      this.polygonPathTexture = undefined
+      this.polygonPathFbo = undefined
       return
     }
 
     // Calculate texture size (square texture)
-    const textureSize = Math.ceil(Math.sqrt(lassoPath.length))
+    const textureSize = Math.ceil(Math.sqrt(polygonPath.length))
     const textureData = new Float32Array(textureSize * textureSize * 4)
 
-    // Fill texture with lasso path points
-    for (const [i, point] of lassoPath.entries()) {
+    // Fill texture with polygon path points
+    for (const [i, point] of polygonPath.entries()) {
       const [x, y] = point
       textureData[i * 4] = x
       textureData[i * 4 + 1] = y
@@ -600,17 +602,17 @@ export class Points extends CoreModule {
       textureData[i * 4 + 3] = 0 // unused
     }
 
-    if (!this.lassoPathTexture) this.lassoPathTexture = reglInstance.texture()
-    this.lassoPathTexture({
+    if (!this.polygonPathTexture) this.polygonPathTexture = reglInstance.texture()
+    this.polygonPathTexture({
       data: textureData,
       width: textureSize,
       height: textureSize,
       type: 'float',
     })
 
-    if (!this.lassoPathFbo) this.lassoPathFbo = reglInstance.framebuffer()
-    this.lassoPathFbo({
-      color: this.lassoPathTexture,
+    if (!this.polygonPathFbo) this.polygonPathFbo = reglInstance.framebuffer()
+    this.polygonPathFbo({
+      color: this.polygonPathTexture,
       depth: false,
       stencil: false,
     })
@@ -695,6 +697,47 @@ export class Points extends CoreModule {
     return positions
   }
 
+  public getSampledPoints (): { indices: number[]; positions: number[] } {
+    const indices: number[] = []
+    const positions: number[] = []
+    if (!this.sampledPointsFbo) return { indices, positions }
+
+    this.clearSampledPointsFboCommand?.()
+    this.fillSampledPointsFboCommand?.()
+    const pixels = readPixels(this.reglInstance, this.sampledPointsFbo as regl.Framebuffer2D)
+
+    for (let i = 0; i < pixels.length / 4; i++) {
+      const index = pixels[i * 4]
+      const isNotEmpty = !!pixels[i * 4 + 1]
+      const x = pixels[i * 4 + 2]
+      const y = pixels[i * 4 + 3]
+
+      if (isNotEmpty && index !== undefined && x !== undefined && y !== undefined) {
+        indices.push(index)
+        positions.push(x, y)
+      }
+    }
+
+    return { indices, positions }
+  }
+
+  public getTrackedPositionsArray (): number[] {
+    const positions: number[] = []
+    if (!this.trackedIndices) return positions
+    positions.length = this.trackedIndices.length * 2
+    const pixels = readPixels(this.reglInstance, this.trackedPositionsFbo as regl.Framebuffer2D)
+    for (let i = 0; i < pixels.length / 4; i += 1) {
+      const x = pixels[i * 4]
+      const y = pixels[i * 4 + 1]
+      const index = this.trackedIndices[i]
+      if (x !== undefined && y !== undefined && index !== undefined) {
+        positions[i * 2] = x
+        positions[i * 2 + 1] = y
+      }
+    }
+    return positions
+  }
+
   private swapFbo (): void {
     const temp = this.previousPositionFbo
     this.previousPositionFbo = this.currentPositionFbo

package/src/stories/2. configuration.mdx

@@ -13,6 +13,7 @@ import { Meta } from "@storybook/blocks";
 | pointGreyoutOpacity | Greyed out point opacity value when the selection is active | `undefined` |
 | pointGreyoutColor | Greyed out point color value when the selection is active | `undefined` |
 | pointSize | The default size value to use for points when no point sizes are provided or if the size value in the array is `undefined` or `null` | `4` |
+| pointOpacity | Universal opacity value applied to all points. This value multiplies with individual point alpha values (if set via setPointColors). Useful for dynamically controlling opacity of all points without updating individual RGBA arrays. | `1.0` |
 | pointSizeScale | Scale factor for the point size | `1` |
 | hoveredPointCursor | Cursor style to use when hovering over a point | `auto` |
 | renderHoveredPointRing | Turns ring rendering around a point on hover on / off | `false` |
@@ -21,6 +22,7 @@ import { Meta } from "@storybook/blocks";
 | focusedPointIndex | Set focus on a point by index. A ring will be highlighted around the focused point. When set to `undefined`, no point is focused. | `undefined` |
 | renderLinks | Turns link rendering on / off | `true` |
 | linkColor | The default color to use for links when no link colors are provided, or if the color value in the array is `undefined` or `null`. This can be either a hex color string (e.g., '#666666') or an array of RGBA values in the format `[red, green, blue, alpha]` where each value is a number between 0 and 255 | `#666666` |
+| linkOpacity | Universal opacity value applied to all links. This value multiplies with individual link alpha values (if set via setLinkColors). Useful for dynamically controlling opacity of all links without updating individual RGBA arrays. | `1.0` |
 | linkGreyoutOpacity | Greyed out link opacity value when the selection is active | `0.1` |
 | linkWidth | The default width value to use for links when no link widths are provided or if the width value in the array is `undefined` or `null` | `1` |
 | linkWidthScale | Scale factor for the link width | `1` |

package/src/stories/3. api-reference.mdx

@@ -43,6 +43,13 @@ graph.setPointColors(new Float32Array([
 graph.render();
 ```
 
+### <a name="get_point_colors" href="#get_point_colors">#</a> graph.<b>getPointColors</b>()
+
+This method retrieves the current colors of the graph points that were previously set using `setPointColors`.
+
+**Returns:** A Float32Array representing the colors of points in the format `[r1, g1, b1, a1, r2, g2, b2, a2, ..., rN, gN, bN, aN]`, where each color is in RGBA format. Each set of four values (`r`, `g`, `b`, `a`) represents the color of a single point. Returns an empty Float32Array if no point colors are set.
+
+The returned array contains the processed point colors used for rendering, including any default values that were applied during processing.
 
 ### <a name="set_point_sizes" href="#set_point_sizes">#</a> graph.<b>setPointSizes</b>(<i>pointSizes</i>)
 
@@ -60,6 +67,14 @@ graph.render();
 
 This example sets the size of the first point to 10, the second point to 20, and the third point to 30.
 
+### <a name="get_point_sizes" href="#get_point_sizes">#</a> graph.<b>getPointSizes</b>()
+
+This method retrieves the current sizes of the graph points that were previously set using `setPointSizes`.
+
+**Returns:** A Float32Array representing the sizes of points in the format `[size1, size2, ..., sizeN]`, where each `size` value corresponds to the size of the point at the same index in the graph's data. Returns an empty Float32Array if no point sizes are set.
+
+The returned array contains the processed point sizes used for rendering, including any default values that were applied during processing.
+
 ### <a name="set_links" href="#set_links">#</a> graph.<b>setLinks</b>(<i>links</i>)
 
 This method sets the links (connections) between points in a cosmos.gl graph.
@@ -105,6 +120,14 @@ graph.render();
 
 In this example, the `linkColors` array contains three sets of four elements, each representing the RGBA color for a single link. The first set `[1, 0, 0, 1]` sets the first link to red, the second set `[0, 1, 0, 1]` sets the second link to green, and the third set `[0, 0, 1, 1]` sets the third link to blue.
 
+### <a name="get_link_colors" href="#get_link_colors">#</a> graph.<b>getLinkColors</b>()
+
+This method retrieves the current colors of the graph links that were previously set using `setLinkColors`.
+
+**Returns:** A Float32Array representing the colors of links in the format `[r1, g1, b1, a1, r2, g2, b2, a2, ..., rN, gN, bN, aN]`, where each color is in RGBA format. Each set of four values (`r`, `g`, `b`, `a`) represents the color of a single link. Returns an empty Float32Array if no link colors are set.
+
+The returned array contains the processed link colors used for rendering, including any default values that were applied during processing.
+
 ### <a name="set_link_widths" href="#set_link_widths">#</a> graph.<b>setLinkWidths</b>(<i>linkWidths</i>)
 
 This method sets the widths for the graph links.
@@ -119,6 +142,14 @@ graph.render();
 
 In this example, the `linkWidths` array contains three numerical values. The first value `1` sets the width of the first link, the second value `2` sets the width of the second link, and the third value `3` sets the width of the third link.
 
+### <a name="get_link_widths" href="#get_link_widths">#</a> graph.<b>getLinkWidths</b>()
+
+This method retrieves the current widths of the graph links that were previously set using `setLinkWidths`.
+
+**Returns:** A Float32Array representing the widths of links in the format `[width1, width2, ..., widthN]`, where each `width` value corresponds to the width of the link at the same index in the graph's data. Returns an empty Float32Array if no link widths are set.
+
+The returned array contains the processed link widths used for rendering, including any default values that were applied during processing.
+
 ### <a name="set_link_arrows" href="#set_link_arrows">#</a> graph.<b>setLinkArrows</b>(<i>linkArrows</i>)
 
 This method sets the arrows for the graph links.
@@ -135,7 +166,6 @@ graph.render();
 
 In this example, the `linkArrows` array contains three boolean values. The first value `true` sets an arrow on the first link, the second value `false` leaves the second link without an arrow, and the third value `true` sets an arrow on the third link.
 
-
 ### <a name="set_link_strengths" href="#set_link_strengths">#</a> graph.<b>setLinkStrength</b>(<i>linkStrength</i>)
 
 This method sets the strength of the graph links.
@@ -184,7 +214,6 @@ This method sets the force strength coefficients for clustering points in the gr
   ```
   This example sets the force coefficient for point 0 to 1, point 1 to 0.4, and point 2 to 0.3.
 
-
 ### <a name="render" href="#render">#</a> graph.<b>render</b>([<i>simulationAlpha</i>])
 
 The `render` method renders the graph and, optionally, controls the initial energy of the simulation.
@@ -220,7 +249,6 @@ This method centers and zooms the view to fit all points within the scene.
 
 The `fitView` method is particularly useful when you want to ensure that all points in the graph are visible within the currently displayed viewport. By fitting the view to include all points, users can get a complete overview of the entire graph.
 
-
 ### <a name="fit_view_by_point_indices" href="#fit_view_by_point_indices">#</a> graph.<b>fitViewByPointIndices</b>(<i>indices</i>, [<i>duration</i>], [<i>padding</i>])
 
 The `fitViewByPointIndices` method centers and zooms the view to fit the points specified by their <i>indices</i> in the scene, with an optional animation <i>duration</i> and <i>padding</i>.
@@ -237,34 +265,52 @@ The `fitViewByPointPositions` method centers and zooms the view to fit the point
 * **`duration`** (Number, optional): The duration of the animation in milliseconds. Default is 250 ms.
 * **`padding`** (Number, optional): The padding around the viewport in percentage. This value should be between 0 and 1. Default is 0.1 (10% padding).
 
-### <a name="get_points_in_range" href="#get_points_in_range">#</a> graph.<b>getPointsInRange</b>(<i>selection</i>)
+### <a name="get_points_in_rect" href="#get_points_in_rect">#</a> graph.<b>getPointsInRect</b>(<i>selection</i>)
 
 Get points as a Float32Array within a rectangular area defined by two corner points `[[left, top], [right, bottom]]`. The `left` and `right` values represent the horizontal position in pixels, relative to the left edge of the canvas, with `0` being the leftmost position and the width of the canvas being the rightmost position.
 
 The `top` and `bottom` values represent the vertical position in pixels, relative to the top edge of the canvas, with `0` being the topmost position and the height of the canvas being the bottommost position.
 
-### <a name="select_points_in_range" href="#select_points_in_range">#</a> graph.<b>selectPointsInRange</b>(<i>selection</i>)
+* **`selection`** (Array): An array containing two coordinate arrays representing the corners of the selection rectangle in the format `[[left, top], [right, bottom]]`.
+
+**Returns:** A Float32Array containing the indices of points inside the rectangular area.
+
+### <a name="get_points_in_range" href="#get_points_in_range">#</a> graph.<b>getPointsInRange</b>(<i>selection</i>) <b style={{ color: 'orange' }}>[DEPRECATED]</b>
+
+**⚠️ Deprecated:** Use `getPointsInRect` instead. This method will be removed in a future version.
+
+Get points as a Float32Array within a rectangular area defined by two corner points `[[left, top], [right, bottom]]`. This method has the same functionality as `getPointsInRect`.
+
+### <a name="select_points_in_rect" href="#select_points_in_rect">#</a> graph.<b>selectPointsInRect</b>(<i>selection</i>)
 
 Select points within a rectangular area defined by two corner points `[[left, top], [right, bottom]]`. The `left` and `right` values represent the horizontal position in pixels, relative to the left edge of the canvas, with `0` being the leftmost position and the width of the canvas being the rightmost position.
 
 The `top` and `bottom` values represent the vertical position in pixels, relative to the top edge of the canvas, with `0` being the topmost position and the height of the canvas being the bottommost position.
 
-### <a name="get_points_in_lasso" href="#get_points_in_lasso">#</a> graph.<b>getPointsInLasso</b>(<i>lassoPath</i>)
+* **`selection`** (Array | null): An array containing two coordinate arrays representing the corners of the selection rectangle in the format `[[left, top], [right, bottom]]`, or `null` to clear the current selection.
+
+### <a name="select_points_in_range" href="#select_points_in_range">#</a> graph.<b>selectPointsInRange</b>(<i>selection</i>) <b style={{ color: 'orange' }}>[DEPRECATED]</b>
+
+**⚠️ Deprecated:** Use `selectPointsInRect` instead. This method will be removed in a future version.
+
+Select points within a rectangular area defined by two corner points `[[left, top], [right, bottom]]`. This method has the same functionality as `selectPointsInRect`.
 
-Get points as a Float32Array within a lasso (polygon) area defined by an array of coordinate points.
+### <a name="get_points_in_polygon" href="#get_points_in_polygon">#</a> graph.<b>getPointsInPolygon</b>(<i>polygonPath</i>)
 
-* **`lassoPath`** (Array): An array of coordinate points in the format `[[x1, y1], [x2, y2], ..., [xN, yN]]` that defines the lasso polygon. The coordinates should be in pixels relative to the canvas, where:
+Get points as a Float32Array within a polygon area defined by an array of coordinate points.
+
+* **`polygonPath`** (Array): An array of coordinate points in the format `[[x1, y1], [x2, y2], ..., [xN, yN]]` that defines the polygon. The coordinates should be in pixels relative to the canvas, where:
   - **`x`**: Horizontal position from 0 to the width of the canvas
   - **`y`**: Vertical position from 0 to the height of the canvas
   - The polygon requires at least 3 points to form a valid selection area
 
-**Returns:** A Float32Array containing the indices of points inside the lasso area.
+**Returns:** A Float32Array containing the indices of points inside the polygon area.
 
-### <a name="select_points_in_lasso" href="#select_points_in_lasso">#</a> graph.<b>selectPointsInLasso</b>(<i>lassoPath</i>)
+### <a name="select_points_in_polygon" href="#select_points_in_polygon">#</a> graph.<b>selectPointsInPolygon</b>(<i>polygonPath</i>)
 
-Select points within a lasso (polygon) area defined by an array of coordinate points. This method combines the functionality of `getPointsInLasso` with point selection, making the identified points visually selected in the graph.
+Select points within a polygon area defined by an array of coordinate points. This method combines the functionality of `getPointsInPolygon` with point selection, making the identified points visually selected in the graph.
 
-* **`lassoPath`** (Array | null): An array of coordinate points in the format `[[x1, y1], [x2, y2], ..., [xN, yN]]` that defines the lasso polygon, or `null` to clear the current selection. The coordinates should be in pixels relative to the canvas, where:
+* **`polygonPath`** (Array | null): An array of coordinate points in the format `[[x1, y1], [x2, y2], ..., [xN, yN]]` that defines the polygon, or `null` to clear the current selection. The coordinates should be in pixels relative to the canvas, where:
   - **`x`**: Horizontal position from 0 to the width of the canvas  
   - **`y`**: Vertical position from 0 to the height of the canvas
   - The polygon requires at least 3 points to form a valid selection area
@@ -276,24 +322,20 @@ This method selects a point in the graph based on its index.
 * **`index`** (Number): The index of the point to be selected.
 * **`selectAdjacentPoints`** (Boolean, optional): If set to `true`, adjacent points to the specified index will also be selected. The default value is `false`.
 
-
 ### <a name="select_points_by_indices" href="#select_points_by_indices">#</a> graph.<b>selectPointsByIndices</b>(<i>indices</i>)
 
 This method selects multiple points in the graph based on their indices.
 
 * **`indices`** (Array): An array of numbers representing the indices of the points to be selected.
 
-
 ### <a name="unselect_points" href="#unselect_points">#</a> graph.<b>unselectPoints</b>()
 
 This method unselects all currently selected points in the graph.
 
-
 ### <a name="get_selected_indices" href="#get_selected_indices">#</a> graph.<b>getSelectedIndices</b>()
 
 This method returns an array of indices corresponding to the currently selected points in the graph.
 
-
 ### <a name="get_adjacent_indices" href="#get_adjacent_indices">#</a> graph.<b>getAdjacentIndices</b>(<i>index</i>)
 
 This method returns an array of indices that are adjacent to a specific point in the graph, identified by its <i>index</i>.
@@ -306,28 +348,24 @@ This method method is used to convert X and Y point coordinates from the space c
 
 * **`coordinates`** (Array): An array of two numbers in the format `[x, y]`, representing the X and Y coordinates in the space coordinate system.
 
-
 ### <a name="screen_to_space_position" href="#screen_to_space_position">#</a> graph.<b>screenToSpacePosition</b>(<i>coordinates</i>)
 
 This` method converts X and Y point coordinates from the screen coordinate system (which is used for rendering the graph on the display) to the space coordinate system (which is typically used for graph data).
 
 * **`coordinates`** (Array): An array of two numbers in the format `[x, y]`, representing the X and Y coordinates in the screen coordinate system.
 
-
 ### <a name="space_to_screen_radius" href="#space_to_screen_radius">#</a> graph.<b>spaceToScreenRadius</b>(<i>radius</i>)
 
 This method is used to convert a <i>radius</i> value from the space coordinate system (which is typically used for graph data) to the screen coordinate system (which is used for rendering the graph on the display).
 
 * **`radius`** (Number): The radius value in the space coordinate system that needs to be converted to the screen coordinate system.
 
-
 ### <a name="get_point_radius_by_index" href="#get_point_radius_by_index">#</a> graph.<b>getPointRadiusByIndex</b>(<i>index</i>)
 
 This method retrieves the radius of a point in the graph identified by its <i>index</i>.
 
 * **`index`** (Number): The index of the point for which the radius is to be retrieved.
 
-
 ### <a name="track_point_positions_by_indices" href="#track_point_positions_by_indices">#</a> graph.<b>trackPointPositionsByIndices</b>(<i>indices</i>)
 
 This method allows you to monitor the coordinates of specific points over time. This is particularly useful for observing dynamic changes in the positions of points during the simulation. The positions of the tracked points are updated on each tick of the cosmos.gl simulation.
@@ -336,7 +374,6 @@ This method allows you to monitor the coordinates of specific points over time.
 
 To retrieve the current positions of the tracked points, use the [**getTrackedPointPositionsMap**](#get_tracked_point_positions_map) method, which returns a `Map` object containing the point coordinates.
 
-
 ### <a name="get_tracked_point_positions_map" href="#get_tracked_point_positions_map">#</a> graph.<b>getTrackedPointPositionsMap</b>()
 
 This method retrieves the current positions of points that are being tracked. This method is particularly useful for monitoring the changing coordinates of specific points over time during the simulation. Using this method in conjunction with the [**trackPointPositionsByIndices**](#track_point_positions_by_indices) method allows for dynamic tracking and retrieval of point positions.
@@ -345,6 +382,15 @@ This method retrieves the current positions of points that are being tracked. Th
 
 * A `Map` object where the keys are the indices of the tracked points and the values are their corresponding X and Y coordinates in the form of a `[number, number]` array.
 
+### <a name="get_tracked_point_positions_array" href="#get_tracked_point_positions_array">#</a> graph.<b>getTrackedPointPositionsArray</b>()
+
+This method retrieves the current positions of points that are being tracked as an array for optimized performance. This method provides the same functionality as `getTrackedPointPositionsMap` but returns data as a flat array instead of a Map object, which can be more efficient for applications that need to process large numbers of tracked points.
+
+The positions are returned in the same order as the indices provided to [**trackPointPositionsByIndices**](#track_point_positions_by_indices).
+
+**Returns:**
+
+* An array of numbers representing the X and Y coordinates of tracked points in the format `[x1, y1, x2, y2, ..., xn, yn]`, where each pair corresponds to a tracked point in the order they were specified for tracking. Returns an empty array if no points are being tracked.
 
 ### <a name="get_sampled_point_positions_map" href="#get_sampled_point_positions_map">#</a> graph.<b>getSampledPointPositionsMap</b>()
 
@@ -356,6 +402,21 @@ The number of sampled points is determined by the `pointSamplingDistance` [confi
 
 The sample aims to distribute points evenly across the visible area.
 
+### <a name="get_sampled_points" href="#get_sampled_points">#</a> graph.<b>getSampledPoints</b>()
+
+This method provides an optimized way to retrieve both point indices and positions for sampled points that are currently visible on the screen. Unlike `getSampledPointPositionsMap`, this method returns the data as arrays rather than a Map.
+
+The number of sampled points is determined by the `pointSamplingDistance` [configuration property](../?path=/docs/configuration--docs). This property controls the density of the sampled points:
+* A higher value for `pointSamplingDistance` results in fewer sampled points.
+* A lower value results in more sampled points.
+
+The sample aims to distribute points evenly across the visible area.
+
+**Returns:**
+
+* An object containing:
+  - **`indices`**: Array of point indices for the sampled points
+  - **`positions`**: Flat array of coordinates in the format `[x1, y1, x2, y2, ..., xn, yn]`, where the coordinates correspond to the points at the same index positions in the `indices` array.
 
 ### <a name="start" href="#start">#</a> graph.<b>start</b>([<i>alpha</i>])
 
@@ -363,22 +424,18 @@ Starts the simulation with an optional <i>alpha</i> parameter, which controls th
 
 * **`alpha`** (Number, optional): A number between `0` and `1` representing the initial energy of the simulation. The default value is `1` if not provided. A higher `alpha` value results in more initial energy for the simulation.
 
-
 ### <a name="pause" href="#pause">#</a> graph.<b>pause</b>()
 
 Pauses the current simulation in the graph.
 
-
 ### <a name="restart" href="#restart">#</a> graph.<b>restart</b>()
 
 Restarts the current simulation in the graph.
 
-
 ### <a name="step" href="#step">#</a> graph.<b>step</b>()
 
 Renders a single frame of the simulation and pauses the simulation if it was active.
 
-
 ### <a name="destroy" href="#destroy">#</a> graph.<b>destroy</b>()
 
 Destroys the current cosmos.gl instance.
@@ -387,7 +444,6 @@ Destroys the current cosmos.gl instance.
 
 Creates a new cosmos.gl instance.
 
-
 ### <a name="flatten" href="#flatten">#</a> graph.<b>flatten</b>(<i>pointPositions</i>)
 
 This method converts an array of tuple positions into a single, flat array containing all coordinates sequentially.
@@ -400,7 +456,6 @@ This method converts a flat array of point positions into an array of tuple pair
 
 * **`pointPositions`** (Array): A flat array of numbers representing the x and y coordinates of points sequentially. For example, `[x1, y1, x2, y2, ..., xn, yn]`.
 
-
 ### <a name="get_point_positions" href="#get_point_positions">#</a> graph.<b>getPointPositions</b>()
 
 This method retrieves the current X and Y coordinates of all points in the graph as an array of numbers. The returned array is in the same order as the point positions were added to the graph.

package/src/stories/beginners/basic-set-up/index.ts

@@ -119,7 +119,7 @@ export const basicSetUp = (): { graph: Graph; div: HTMLDivElement} => {
     const top = getRandomInRange([h / 4, h / 2])
     const bottom = getRandomInRange([top, (h * 3) / 4])
     pause()
-    graph.selectPointsInRange([
+    graph.selectPointsInRect([
       [left, top],
       [right, bottom],
     ])

package/src/stories/clusters/{lasso-selection → polygon-selection}/index.ts

@@ -1,9 +1,9 @@
 import { Graph } from '@cosmos.gl/graph'
 import { createCosmos } from '../../create-cosmos'
 import { generateMeshData } from '../../generate-mesh-data'
-import { LassoSelection } from './lasso'
+import { PolygonSelection } from './polygon'
 
-export const lassoSelection = (): {div: HTMLDivElement; graph: Graph; destroy: () => void } => {
+export const polygonSelection = (): {div: HTMLDivElement; graph: Graph; destroy: () => void } => {
   const nClusters = 25
   const { pointPositions, pointColors, pointClusters } = generateMeshData(150, 150, nClusters, 1.0)
 
@@ -26,24 +26,24 @@ export const lassoSelection = (): {div: HTMLDivElement; graph: Graph; destroy: (
 
   graph.setZoomLevel(0.4)
 
-  const lassoSelection = new LassoSelection(div, (lassoPoints) => {
-    graph.selectPointsInLasso(lassoPoints)
+  const polygonSelection = new PolygonSelection(div, (polygonPoints) => {
+    graph.selectPointsInPolygon(polygonPoints)
   })
 
   const actionsDiv = document.createElement('div')
   actionsDiv.className = 'actions'
   div.appendChild(actionsDiv)
 
-  const lassoButton = document.createElement('div')
-  lassoButton.className = 'action'
-  lassoButton.textContent = 'Enable Lasso Selection'
-  lassoButton.addEventListener('click', () => {
-    lassoSelection.enableLassoMode()
+  const polygonButton = document.createElement('div')
+  polygonButton.className = 'action'
+  polygonButton.textContent = 'Enable Polygon Selection'
+  polygonButton.addEventListener('click', () => {
+    polygonSelection.enablePolygonMode()
   })
-  actionsDiv.appendChild(lassoButton)
+  actionsDiv.appendChild(polygonButton)
 
   const destroy = (): void => {
-    lassoSelection.destroy()
+    polygonSelection.destroy()
     if (actionsDiv.parentNode) {
       actionsDiv.parentNode.removeChild(actionsDiv)
     }

package/src/stories/clusters/{lasso-selection/lasso.ts → polygon-selection/polygon.ts}

@@ -1,20 +1,20 @@
 import './style.css'
 
-export class LassoSelection {
+export class PolygonSelection {
   private canvas: HTMLCanvasElement
   private ctx: CanvasRenderingContext2D
   private isDrawing = false
   private points: Array<{ x: number; y: number }> = []
   private graphDiv: HTMLElement
-  private onLassoComplete?: (points: [number, number][]) => void
+  private onPolygonComplete?: (points: [number, number][]) => void
   private boundStartDrawing: (e: MouseEvent) => void
   private boundDraw: (e: MouseEvent) => void
   private boundStopDrawing: () => void
   private resizeObserver: ResizeObserver
 
-  public constructor (graphDiv: HTMLElement, onLassoComplete?: (points: [number, number][]) => void) {
+  public constructor (graphDiv: HTMLElement, onPolygonComplete?: (points: [number, number][]) => void) {
     this.graphDiv = graphDiv
-    this.onLassoComplete = onLassoComplete
+    this.onPolygonComplete = onPolygonComplete
 
     // Bind event handlers
     this.boundStartDrawing = this.startDrawing.bind(this)
@@ -23,7 +23,7 @@ export class LassoSelection {
 
     // Create canvas
     this.canvas = document.createElement('canvas')
-    this.canvas.className = 'lasso-canvas'
+    this.canvas.className = 'polygon-canvas'
 
     const ctx = this.canvas.getContext('2d')
     if (!ctx) throw new Error('Could not get canvas context')
@@ -37,7 +37,7 @@ export class LassoSelection {
     this.resizeObserver.observe(this.graphDiv)
   }
 
-  public enableLassoMode (): void {
+  public enablePolygonMode (): void {
     this.canvas.style.pointerEvents = 'auto'
     this.canvas.style.cursor = 'crosshair'
 
@@ -47,7 +47,7 @@ export class LassoSelection {
     this.canvas.addEventListener('mouseup', this.boundStopDrawing)
   }
 
-  public disableLassoMode (): void {
+  public disablePolygonMode (): void {
     this.canvas.style.pointerEvents = 'none'
     this.canvas.style.cursor = 'default'
 
@@ -61,7 +61,7 @@ export class LassoSelection {
   }
 
   public destroy (): void {
-    this.disableLassoMode()
+    this.disablePolygonMode()
     this.resizeObserver.disconnect()
     if (this.canvas.parentNode) {
       this.canvas.parentNode.removeChild(this.canvas)
@@ -124,20 +124,20 @@ export class LassoSelection {
       this.ctx.closePath()
       this.ctx.stroke()
 
-      const lassoPoints: [number, number][] = this.points.map(p => [p.x, p.y])
-      const firstLassoPoint = lassoPoints[0]
-      const lastLassoPoint = lassoPoints[lassoPoints.length - 1]
-      if (firstLassoPoint && lastLassoPoint && (firstLassoPoint[0] !== lastLassoPoint[0] || firstLassoPoint[1] !== lastLassoPoint[1])) {
-        lassoPoints.push(firstLassoPoint)
+      const polygonPoints: [number, number][] = this.points.map(p => [p.x, p.y])
+      const firstPolygonPoint = polygonPoints[0]
+      const lastPolygonPoint = polygonPoints[polygonPoints.length - 1]
+      if (firstPolygonPoint && lastPolygonPoint && (firstPolygonPoint[0] !== lastPolygonPoint[0] || firstPolygonPoint[1] !== lastPolygonPoint[1])) {
+        polygonPoints.push(firstPolygonPoint)
       }
 
-      if (this.onLassoComplete) {
-        this.onLassoComplete(lassoPoints)
+      if (this.onPolygonComplete) {
+        this.onPolygonComplete(polygonPoints)
       }
     }
 
     const pixelRatio = window.devicePixelRatio || 1
     this.ctx.clearRect(0, 0, this.canvas.width / pixelRatio, this.canvas.height / pixelRatio)
-    this.disableLassoMode()
+    this.disablePolygonMode()
   }
 }

package/src/stories/clusters/{lasso-selection → polygon-selection}/style.css

@@ -1,4 +1,4 @@
-.lasso-canvas {
+.polygon-canvas {
   position: absolute;
   top: 0;
   left: 0;