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

package/README.md

@@ -1,16 +1,16 @@
 
 <p align="center" style="color: #444">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://github.com/user-attachments/assets/1428fb58-c85e-4f9c-8f14-5be2f7c73b16">
-    <source media="(prefers-color-scheme: light)" srcset="https://github.com/user-attachments/assets/44cdb7c6-2ccd-4ed0-a6c3-e9c4606559f0">
-    <img align="center" width="225px" alt="cosmos.gl logo" src="https://github.com/user-attachments/assets/1428fb58-c85e-4f9c-8f14-5be2f7c73b16">
+    <source media="(prefers-color-scheme: dark)" srcset="https://assets.cosmograph.app/cosmos-dark-theme.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://assets.cosmograph.app/cosmos-light-theme.svg">
+    <img align="center" width="225px" alt="cosmos.gl logo" src="https://assets.cosmograph.app/cosmos-light-theme.svg">
   </picture>
 </p>
 <p align="center" style="font-size: 1.2rem;">GPU-accelerated Force Graph</p>
 
-**Cosmos.gl** is a high-performance WebGL Force Graph algorithm and rendering engine. All the computations and drawing occur on the GPU in fragment and vertex shaders, avoiding expensive memory operations. It enables the real-time simulation of network graphs consisting of hundreds of thousands of points and links on modern hardware.
+**cosmos.gl** is a high-performance WebGL Force Graph algorithm and rendering engine. All the computations and drawing occur on the GPU in fragment and vertex shaders, avoiding expensive memory operations. It enables the real-time simulation of network graphs consisting of hundreds of thousands of points and links on modern hardware.
 
-This engine powers 🪐 [Cosmograph](http://cosmograph.app) — a toolset for exploring complex networks and AI embeddings.
+This engine powers 🪐 [Cosmograph](https://cosmograph.app) — a toolset for exploring complex networks and AI embeddings.
 
 <video src="https://user-images.githubusercontent.com/755708/173392407-9b05cbb6-d39e-4c2c-ab41-50900cfda823.mp4" autoplay controls alt="Demo of cosmos.gl GPU-accelerated Force Graph">
 </video>
@@ -77,7 +77,7 @@ graph.render()
 
 ### What's New in v2.0?
 
-Cosmos.gl v2.0 introduces significant improvements in performance and data handling:
+cosmos.gl v2.0 introduces significant improvements in performance and data handling:
 
 - Enhanced data structures with WebGL-compatible formats.
 - Methods like `setPointPositions` and `setLinks` replace `setData` for improved efficiency.
@@ -107,7 +107,7 @@ Check the [Migration Guide](./cosmos-2-0-migration-notes.md) for details.
 ### Known Issues
 
 - ~~Starting from version 15.4, iOS has stopped supporting the key WebGL extension powering our Many-Body force implementation (`EXT_float_blend`). We're investigating this issue and exploring solutions.~~ The latest iOS works again!
-- Cosmos.gl doesn't work on some Android devices.
+- cosmos.gl doesn't work on Android devices that don't support the `OES_texture_float` WebGL extension.
 
 
 ---

package/dist/config.d.ts

@@ -57,6 +57,13 @@ export interface GraphConfigInterface {
      * Default value: `4`
     */
     pointSize?: number;
+    /**
+     * 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.
+     * Default value: `1.0`
+     */
+    pointOpacity?: number;
     /**
      * Scale factor for the point size.
      * Default value: `1`
@@ -103,6 +110,13 @@ export interface GraphConfigInterface {
      * Default value: '#666666'
      */
     linkColor?: string | [number, number, number, number];
+    /**
+     * 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.
+     * Default value: `1.0`
+     */
+    linkOpacity?: number;
     /**
      * Greyed out link opacity value when the selection is active.
      * Default value: `0.1`
@@ -468,6 +482,7 @@ export declare class GraphConfig implements GraphConfigInterface {
     pointGreyoutOpacity: undefined;
     pointGreyoutColor: undefined;
     pointSize: number;
+    pointOpacity: number;
     pointSizeScale: number;
     hoveredPointCursor: string;
     renderHoveredPointRing: boolean;
@@ -475,6 +490,7 @@ export declare class GraphConfig implements GraphConfigInterface {
     focusedPointRingColor: string;
     focusedPointIndex: undefined;
     linkColor: string;
+    linkOpacity: number;
     linkGreyoutOpacity: number;
     linkWidth: number;
     linkWidthScale: number;

package/dist/index.d.ts

@@ -87,6 +87,13 @@ export declare class Graph {
      * Example: `new Float32Array([255, 0, 0, 1, 0, 255, 0, 1])` sets the first point to red and the second point to green.
     */
     setPointColors(pointColors: Float32Array): void;
+    /**
+     * Gets the current colors of the graph points.
+     *
+     * @returns {Float32Array} 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. Returns an empty Float32Array if no point colors are set.
+     */
+    getPointColors(): Float32Array;
     /**
      * Sets the sizes for the graph points.
      *
@@ -95,6 +102,13 @@ export declare class Graph {
      * Example: `new Float32Array([10, 20, 30])` sets the first point to size 10, the second point to size 20, and the third point to size 30.
      */
     setPointSizes(pointSizes: Float32Array): void;
+    /**
+     * Gets the current sizes of the graph points.
+     *
+     * @returns {Float32Array} A Float32Array representing the sizes of points in the format [size1, size2, ..., sizen],
+     * where `n` is the index of the point. Returns an empty Float32Array if no point sizes are set.
+     */
+    getPointSizes(): Float32Array;
     /**
      * Sets the links for the graph.
      *
@@ -112,6 +126,13 @@ export declare class Graph {
      * Example: `new Float32Array([255, 0, 0, 1, 0, 255, 0, 1])` sets the first link to red and the second link to green.
      */
     setLinkColors(linkColors: Float32Array): void;
+    /**
+     * Gets the current colors of the graph links.
+     *
+     * @returns {Float32Array} 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. Returns an empty Float32Array if no link colors are set.
+     */
+    getLinkColors(): Float32Array;
     /**
      * Sets the widths for the graph links.
      *
@@ -120,6 +141,13 @@ export declare class Graph {
      * Example: `new Float32Array([1, 2, 3])` sets the first link to width 1, the second link to width 2, and the third link to width 3.
      */
     setLinkWidths(linkWidths: Float32Array): void;
+    /**
+     * Gets the current widths of the graph links.
+     *
+     * @returns {Float32Array} A Float32Array representing the widths of links in the format [width1, width2, ..., widthn],
+     * where `n` is the index of the link. Returns an empty Float32Array if no link widths are set.
+     */
+    getLinkWidths(): Float32Array;
     /**
      * Sets the arrows for the graph links.
      *
@@ -238,24 +266,40 @@ export declare class Graph {
      * The `top` and `bottom` coordinates should be from 0 to the height of the canvas.
      * @returns A Float32Array containing the indices of points inside a rectangular area.
      */
+    getPointsInRect(selection: [[number, number], [number, number]]): Float32Array;
+    /**
+     * Get points indices inside a rectangular area.
+     * @param selection - Array of two corner points `[[left, top], [right, bottom]]`.
+     * The `left` and `right` coordinates should be from 0 to the width of the canvas.
+     * The `top` and `bottom` coordinates should be from 0 to the height of the canvas.
+     * @returns A Float32Array containing the indices of points inside a rectangular area.
+     * @deprecated Use `getPointsInRect` instead. This method will be removed in a future version.
+     */
     getPointsInRange(selection: [[number, number], [number, number]]): Float32Array;
     /**
-     * Get points indices inside a lasso (polygon) area.
-     * @param lassoPath - Array of points `[[x1, y1], [x2, y2], ..., [xn, yn]]` that defines the lasso polygon.
+     * Get points indices inside a polygon area.
+     * @param polygonPath - Array of points `[[x1, y1], [x2, y2], ..., [xn, yn]]` that defines the polygon.
      * The coordinates should be from 0 to the width/height of the canvas.
-     * @returns A Float32Array containing the indices of points inside the lasso area.
+     * @returns A Float32Array containing the indices of points inside the polygon area.
      */
-    getPointsInLasso(lassoPath: [number, number][]): Float32Array;
+    getPointsInPolygon(polygonPath: [number, number][]): Float32Array;
     /** Select points inside a rectangular area.
      * @param selection - Array of two corner points `[[left, top], [right, bottom]]`.
      * The `left` and `right` coordinates should be from 0 to the width of the canvas.
      * The `top` and `bottom` coordinates should be from 0 to the height of the canvas. */
+    selectPointsInRect(selection: [[number, number], [number, number]] | null): void;
+    /** Select points inside a rectangular area.
+     * @param selection - Array of two corner points `[[left, top], [right, bottom]]`.
+     * The `left` and `right` coordinates should be from 0 to the width of the canvas.
+     * The `top` and `bottom` coordinates should be from 0 to the height of the canvas.
+     * @deprecated Use `selectPointsInRect` instead. This method will be removed in a future version.
+     */
     selectPointsInRange(selection: [[number, number], [number, number]] | null): void;
-    /** Select points inside a lasso (polygon) area.
-     * @param lassoPath - Array of points `[[x1, y1], [x2, y2], ..., [xn, yn]]` that defines the lasso polygon.
+    /** Select points inside a polygon area.
+     * @param polygonPath - Array of points `[[x1, y1], [x2, y2], ..., [xn, yn]]` that defines the polygon.
      * The coordinates should be from 0 to the width/height of the canvas.
      * Set to null to clear selection. */
-    selectPointsInLasso(lassoPath: [number, number][] | null): void;
+    selectPointsInPolygon(polygonPath: [number, number][] | null): void;
     /**
      * Select a point by index. If you want the adjacent points to get selected too, provide `true` as the second argument.
      * @param index The index of the point in the array of points.
@@ -316,6 +360,13 @@ export declare class Graph {
      * @returns A Map object where keys are the indices of the points and values are their corresponding X and Y coordinates in the [number, number] format.
      */
     getTrackedPointPositionsMap(): Map<number, [number, number]>;
+    /**
+     * Get current X and Y coordinates of the tracked points as an array.
+     * @returns Array of point positions in the format [x1, y1, x2, y2, ..., xn, yn] for tracked points only.
+     * The positions are ordered by the tracking indices (same order as provided to trackPointPositionsByIndices).
+     * Returns an empty array if no points are being tracked.
+     */
+    getTrackedPointPositionsArray(): number[];
     /**
      * For the points that are currently visible on the screen, get a sample of point indices with their coordinates.
      * The resulting number of points will depend on the `pointSamplingDistance` configuration property,
@@ -323,6 +374,16 @@ export declare class Graph {
      * @returns A Map object where keys are the index of the points and values are their corresponding X and Y coordinates in the [number, number] format.
      */
     getSampledPointPositionsMap(): Map<number, [number, number]>;
+    /**
+     * For the points that are currently visible on the screen, get a sample of point indices and positions.
+     * The resulting number of points will depend on the `pointSamplingDistance` configuration property,
+     * and the sampled points will be evenly distributed.
+     * @returns An object containing arrays of point indices and positions.
+     */
+    getSampledPoints(): {
+        indices: number[];
+        positions: number[];
+    };
     /**
      * Gets the X-axis of rescaling function.
      *