@cosmos.gl/graph 2.6.2-rc.0 → 2.7.0-beta.0

package/cosmos-2-0-migration-notes.md

@@ -0,0 +1,98 @@
+### Migration Guide cosmos.gl v2.0 
+
+#### Introduction
+
+Welcome to the updated cosmos.gl library! Version 2.0 introduces significant improvements in data handling and performance, marking a major milestone for the library. This guide will help you transition to the new version smoothly.
+
+#### Key Changes in Data Handling
+
+This update is centered on enhancing data performance by utilizing formats directly compatible with WebGL. Since WebGL operates with buffers and framebuffers created from arrays of numbers, we have introduced new methods to handle data more efficiently.
+
+#### Replacing `setData`
+
+The `setData` method has been replaced with `setPointPositions` and `setLinks`. These new methods accept Float32Array, which are directly used to create WebGL textures.
+
+**Before:**
+```js
+graph.setData(
+  [{ id: 'a' }, { id: 'b' }], // Nodes
+  [{ source: 'a', target: 'b' }] // Links
+);
+```
+
+**After:**
+```js
+graph.setPointPositions(new Float32Array([
+  400, 400, // x and y of the first point
+  500, 500, // x and y of the second point
+]));
+graph.setLinks(new Float32Array([
+  0, 1 // Link between the first and second point
+]));
+```
+
+#### Configuration Updates
+
+Accessor functions for styling such as `nodeColor`, `nodeSize`, `linkColor`, `linkWidth`, and `linkArrows`, are eliminated. You can now set these attributes directly using Float32Array.
+
+**Old Method for Setting Node Color:**
+```js
+config.nodeColor = node => node.color;
+```
+
+**New Method for Setting Point Colors:**
+```js
+graph.setPointColors(new Float32Array([
+  0.5, 0.5, 1, 1, // r, g, b, alpha for the first point
+  0.5, 1, 0.5, 1, // r, g, b, alpha for the second point
+]));
+```
+
+**Flat Configuration Object:**
+
+The configuration object is now flat instead of nested.
+
+**Old Config:**
+```js
+const config = {
+  backgroundColor: 'black',
+  simulation: {
+    repulsion: 0.5,
+  },
+  events: {
+    onNodeMouseOver: (node, index, pos) => console.log(`Hovered over node ${node.id}`)
+  }
+}
+```
+
+**New config:**
+```js
+const config = {
+  backgroundColor: 'black',
+  simulationRepulsion: 0.5,
+  onPointMouseOver: (index, pos) => console.log(`Hovered over point at index ${index}`);
+}
+```
+
+**Initialization Change: From Canvas to Div**
+
+In version 2.0, the initialization of the graph now requires a div element instead of a canvas element.
+
+**Before**
+```js
+const canvas = document.getElementById('myCanvas')
+const graph = new Graph(canvas, config)
+```
+
+**After**
+```js
+const div = document.getElementById('myDiv')
+const graph = new Graph(div, config)
+```
+
+**Summary of Additional Changes**
+
+- **Terminology Update:** "Node" is now "Point," but "Link" remains unchanged.
+- **API Modifications:** All methods that focused on node objects have been updated or replaced to handle indices.
+- **Manual Rendering:** After setting data or updating point/link properties, remember to run `graph.render()` to update WebGL textures and render the graph with the new data.
+

package/cosmos_awesome.md

@@ -0,0 +1,96 @@
+## About
+The cosmos.gl awesome list is a list of awesome things curated by the community.
+
+## cosmos.gl Examples:
+**MathWorks/Kuu** The MathWorks, Inc: symmetric positive definite matrix
+- Source: https://sparse.tamu.edu/MathWorks/Kuu
+- Example: https://cosmograph.app/run/?data=https://cosmograph.app/data/Kuu.csv
+
+**HB/blckhole** S CONNECTIVITY STRUCTURE OF A GEODESIC DOME ON A COARSE BASE
+- Source: https://sparse.tamu.edu/HB/blckhole
+- Example: https://cosmograph.app/run/?data=https://cosmograph.app/data/blckhole.csv
+
+**HB/can_229** SYMMETRIC PATTERN FROM CANNES,LUCIEN MARRO,JUNE 1981.
+- Source: https://sparse.tamu.edu/HB/can_229
+- Example: https://cosmograph.app/run/?data=https://cosmograph.app/data/can_229.csv
+ 
+**Gset/G34** 2D torus, 40-by-50, uniformly random +1/-1 entries
+- Source: https://sparse.tamu.edu/Gset/G34
+- Example: https://cosmograph.app/run/?data=https://cosmograph.app/data/G34.csv
+
+**Pothen/sphere3** sphere3, with coordinates. From NASA, collected by Alex Pothen
+- Source: https://sparse.tamu.edu/Pothen/sphere3
+- Example: https://cosmograph.app/run/?data=https://cosmograph.app/data/sphere3.csv
+
+**Bydder/mri1** MRI reconstruction (1), from Mark Bydder, UCSD
+- Source: https://sparse.tamu.edu/Bydder/mri1
+- Example: https://cosmograph.app/run/?data=https://cosmograph.app/data/mri1.csv
+
+**Mittelmann/pds-90** Patient distribution (evacuation) system
+- Source: https://sparse.tamu.edu/Mittelmann/pds-90
+- Example: https://cosmograph.app/run/?data=https://cosmograph.app/data/pds-90.csv
+
+**Chen/pkustk10** PKU SYMMETRIC STIFFNESS, 4 TOWER SILO
+- Source: https://sparse.tamu.edu/Chen/pkustk10
+- Example: https://cosmograph.app/run/?data=https://cosmograph.app/data/pkustk10.csv
+
+**GHS_indef/aug3d** Gould, Hu, & Scott: expanded system-3D PDE (CUTEr)
+- Source: https://sparse.tamu.edu/GHS_indef/aug3d
+- Example: https://cosmograph.app/run/?data=https://cosmograph.app/data/aug3d.csv
+
+**Nasa/barth5** BARTH5: Nasa matrix, but with a diagonal added to the original matrix
+- Source: https://sparse.tamu.edu/Nasa/barth5
+- Example: https://cosmograph.app/run/?data=https://cosmograph.app/data/barth5.csv
+
+**DIMACS10/delaunay_n10**
+DIMACS10 set: delaunay/delaunay_n10
+- Source: https://sparse.tamu.edu/DIMACS10/delaunay_n10
+- Example:https://cosmograph.app/run/?data=https://cosmograph.app/data/delaunay_n10.csv
+
+**HB/dwt_1005** SYMMETRIC CONNECTION TABLE FROM DTNSRDC, WASHINGTON
+- Source: https://sparse.tamu.edu/HB/dwt_1005
+- Example: https://cosmograph.app/run/?data=https://cosmograph.app/data/dwt_1005.csv
+
+**HB/gre_1107** UNSYMMETRIC MATRIX FROM GRENOBLE,FRANCOIS CACHARD,MARCH 1981.
+- Source: https://sparse.tamu.edu/HB/gre_1107
+- Example: https://cosmograph.app/run/?data=https://cosmograph.app/data/gre_1107.csv
+
+**Hollinger/jan99jac040sc** Jacobian from Bank of Canada ‘jan99’ model, oldstack 040, with scaling
+- Source: https://sparse.tamu.edu/Hollinger/jan99jac040sc
+- Example: https://cosmograph.app/run/?data=https://cosmograph.app/data/jan99jac040sc.csv
+
+**HB/man_5976** MANTEUFFEL’S FINITE ELEMENT PROBLEM (CONDENSED)
+- Source: https://sparse.tamu.edu/HB/man_5976
+- Example: https://cosmograph.app/run/?data=https://cosmograph.app/data/man_5976.csv
+
+**Boeing/msc01440** SYMMETRIC TEST MATRIX FROM MSC/NASTRAN CYLF8.OUT2
+- Source: https://sparse.tamu.edu/Boeing/msc01440
+- Example: https://cosmograph.app/run/?data=https://cosmograph.app/data/msc01440.csv
+
+**Nasa/nasa4704** STRUCTURE FROM NASA LANGLEY, 4704 DEGREES OF FREEDOM
+- Source: https://sparse.tamu.edu/Nasa/nasa4704
+- Example: https://cosmograph.app/run/?data=https://cosmograph.app/data/nasa4704.csv
+
+**Bai/rw5151** MARKOV CHAIN MODELING, RANDOM WALK (M = 100) G. W. STEWART
+- Source: https://sparse.tamu.edu/Bai/rw5151
+- Example: https://cosmograph.app/run/?data=https://cosmograph.app/data/rw5151.csv
+
+**Shyy/shyy41** Wei Shyy, Univ. Florida. CFD/Navier-Stokes,viscous flow, fully coupled
+- Source: https://sparse.tamu.edu/Shyy/shyy41
+- Example: https://cosmograph.app/run/?data=https://cosmograph.app/data/shyy41.csv
+
+**Shyy/shyy161** Wei Shyy, Univ. Florida. CFD/Navier-Stokes,viscous flow, fully coupled
+- Source: https://sparse.tamu.edu/Shyy/shyy161
+- Example: https://cosmograph.app/run/?data=https://cosmograph.app/data/shyy161.csv
+
+**HB/young3c** real matrix from aero research, David Young, corrected RUA version
+- Source: https://sparse.tamu.edu/HB/young3c
+- Example: https://cosmograph.app/run/?data=https://cosmograph.app/data/young3c.csv
+
+**TKK/cyl6** Cylindrical shell, non-linear analysis, 3 RHS vectors at step 6. R Kouhia
+- Source: https://sparse.tamu.edu/TKK/cyl6
+- Example: https://cosmograph.app/run/?data=https://cosmograph.app/data/cyl6.csv
+
+**GHS_psdef/cvxbqp1** Gould, Hu, & Scott: barrier Hessian from convex QP (CUTEr)
+- Source: https://sparse.tamu.edu/GHS_psdef/cvxbqp1
+- Example: https://cosmograph.app/run/?data=https://cosmograph.app/data/cvxbqp1.csv

package/dist/config.d.ts

@@ -27,15 +27,13 @@ export interface GraphConfigInterface {
      * in the format `[red, green, blue, alpha]` where each value is a number between 0 and 255.
      * Default value: '#b3b3b3'
      */
-    pointDefaultColor?: string | [number, number, number, number];
-    /** @deprecated Use `pointDefaultColor` instead */
     pointColor?: string | [number, number, number, number];
     /**
      * The color to use for points when they are greyed out (when selection is active).
      * This can be either a hex color string (e.g., '#b3b3b3') or an array of RGBA values
      * in the format `[red, green, blue, alpha]` where each value is a number between 0 and 255.
      *
-     * If not provided, the color will be the same as the point's original color,
+     * If not provided, the color will be the same as the `pointColor`,
      * but darkened or lightened depending on the background color.
      *
      * If `pointGreyoutOpacity` is also defined, it will override the alpha/opacity component
@@ -116,8 +114,6 @@ export interface GraphConfigInterface {
      * in the format `[red, green, blue, alpha]` where each value is a number between 0 and 255.
      * Default value: '#666666'
      */
-    linkDefaultColor?: string | [number, number, number, number];
-    /** @deprecated Use `linkDefaultColor` instead */
     linkColor?: string | [number, number, number, number];
     /**
      * Universal opacity value applied to all links.
@@ -441,8 +437,10 @@ export interface GraphConfigInterface {
      */
     showFPSMonitor?: boolean;
     /**
-     * Canvas pixel ratio.
-     * Default value: `2`
+     * Pixel ratio for the canvas. Controls the resolution of the drawing buffer.
+     * - Higher values use more GPU memory but provide better quality on high-DPI displays
+     * - If not provided, uses `window.devicePixelRatio` or falls back to `2`
+     * Default value: `typeof window !== 'undefined' ? window.devicePixelRatio || 2 : 2`
      */
     pixelRatio?: number;
     /**
@@ -549,7 +547,6 @@ export declare class GraphConfig implements GraphConfigInterface {
     backgroundColor: string;
     spaceSize: number;
     pointColor: string;
-    pointDefaultColor: undefined;
     pointGreyoutOpacity: undefined;
     pointGreyoutColor: undefined;
     pointSize: number;
@@ -562,7 +559,6 @@ export declare class GraphConfig implements GraphConfigInterface {
     focusedPointRingColor: string;
     focusedPointIndex: undefined;
     linkColor: string;
-    linkDefaultColor: undefined;
     linkOpacity: number;
     linkGreyoutOpacity: number;
     linkWidth: number;

package/dist/graph/utils/error-message.d.ts

@@ -3,4 +3,4 @@
  * @param container The HTML element to append the error message to
  * @returns The created error div element
  */
-export declare function createWebGLErrorMessage(container: HTMLElement): HTMLDivElement;
+export declare function createWebGLErrorMessage(container: HTMLElement, error: string): HTMLDivElement;

package/dist/helper.d.ts

@@ -1,4 +1,4 @@
-import { default as regl } from 'regl';
+import { Device, Framebuffer } from '@luma.gl/core';
 import { default as DOMPurify } from 'dompurify';
 export declare const isFunction: <T>(a: T) => boolean;
 export declare const isArray: <T>(a: unknown | T[]) => a is T[];
@@ -7,7 +7,44 @@ export declare const isAClassInstance: <T>(a: T) => boolean;
 export declare const isPlainObject: <T>(a: T) => boolean;
 export declare function getRgbaColor(value: string | [number, number, number, number]): [number, number, number, number];
 export declare function rgbToBrightness(r: number, g: number, b: number): number;
-export declare function readPixels(reglInstance: regl.Regl, fbo: regl.Framebuffer2D): Float32Array;
+/**
+ * TODO: Migrate from deprecated `readPixelsToArrayWebGL` to CommandEncoder API
+ *
+ * `readPixelsToArrayWebGL` is deprecated in luma.gl v9. The recommended modern approach is:
+ *
+ * 1. Create a buffer to hold the pixel data:
+ *    const buffer = device.createBuffer({
+ *      byteLength: width * height * 4 * 4, // RGBA, 4 bytes per float
+ *      usage: Buffer.COPY_DST | Buffer.MAP_READ
+ *    });
+ *
+ * 2. Copy texture/framebuffer to buffer using command encoder:
+ *    const commandEncoder = device.createCommandEncoder();
+ *    commandEncoder.copyTextureToBuffer({
+ *      sourceTexture: fbo, // Can be Texture or Framebuffer
+ *      width: sourceWidth ?? fbo.width,
+ *      height: sourceHeight ?? fbo.height,
+ *      origin: [sourceX, sourceY],
+ *      destinationBuffer: buffer
+ *    });
+ *    const commandBuffer = commandEncoder.finish();
+ *    device.submit(commandBuffer);
+ *
+ * 3. Read the data from the buffer (async):
+ *    const pixelData = await buffer.readAsync(); // Returns ArrayBuffer
+ *    return new Float32Array(pixelData);
+ *
+ * Note: The modern approach is asynchronous, so this function signature would need to change
+ * to return Promise<Float32Array> or we'd need to handle async at all call sites (18 locations).
+ *
+ * Migration impact:
+ * - This function is used in 18 places across the codebase
+ * - All call sites would need to be updated to handle async
+ * - Consider batching the migration to avoid inconsistencies
+ *
+ * Current status: Deprecated but still functional. Keeping for now until full migration can be planned.
+ */
+export declare function readPixels(device: Device, fbo: Framebuffer, sourceX?: number, sourceY?: number, sourceWidth?: number, sourceHeight?: number): Float32Array;
 export declare function clamp(num: number, min: number, max: number): number;
 export declare function isNumber(value: number | undefined | null | typeof NaN): boolean;
 /**