@cosmos.gl/graph 2.4.0 → 2.6.0

package/src/index.ts

@@ -17,10 +17,10 @@ import { FPSMonitor } from '@/graph/modules/FPSMonitor'
 import { GraphData } from '@/graph/modules/GraphData'
 import { Lines } from '@/graph/modules/Lines'
 import { Points } from '@/graph/modules/Points'
-import { Store, ALPHA_MIN, MAX_POINT_SIZE, type Hovered } from '@/graph/modules/Store'
+import { Store, ALPHA_MIN, MAX_POINT_SIZE, MAX_HOVER_DETECTION_DELAY, type Hovered } from '@/graph/modules/Store'
 import { Zoom } from '@/graph/modules/Zoom'
 import { Drag } from '@/graph/modules/Drag'
-import { defaultConfigValues, defaultScaleToZoom } from '@/graph/variables'
+import { defaultConfigValues, defaultScaleToZoom, defaultGreyoutPointColor, defaultBackgroundColor } from '@/graph/variables'
 import { createWebGLErrorMessage } from './graph/utils/error-message'
 
 export class Graph {
@@ -50,12 +50,12 @@ export class Graph {
 
   private currentEvent: D3ZoomEvent<HTMLCanvasElement, undefined> | D3DragEvent<HTMLCanvasElement, undefined, Hovered> | MouseEvent | undefined
   /**
-   * The value of `_findHoveredPointExecutionCount` is incremented by 1 on each animation frame.
-   * When the counter reaches 2 (or more), it is reset to 0 and the `findHoveredPoint` method is executed.
+   * The value of `_findHoveredItemExecutionCount` is incremented by 1 on each animation frame.
+   * When the counter reaches MAX_HOVER_DETECTION_DELAY (default 4), it is reset to 0 and the `findHoveredPoint` or `findHoveredLine` method is executed.
    */
-  private _findHoveredPointExecutionCount = 0
+  private _findHoveredItemExecutionCount = 0
   /**
-   * If the mouse is not on the Canvas, the `findHoveredPoint` method will not be executed.
+   * If the mouse is not on the Canvas, the `findHoveredPoint` or `findHoveredLine` method will not be executed.
    */
   private _isMouseOnCanvas = false
   /**
@@ -123,7 +123,30 @@ export class Graph {
     this.canvasD3Selection
       .on('mouseenter.cosmos', () => { this._isMouseOnCanvas = true })
       .on('mousemove.cosmos', () => { this._isMouseOnCanvas = true })
-      .on('mouseleave.cosmos', () => { this._isMouseOnCanvas = false })
+      .on('mouseleave.cosmos', (event) => {
+        this._isMouseOnCanvas = false
+        this.currentEvent = event
+
+        // Clear point hover state and trigger callback if needed
+        if (this.store.hoveredPoint !== undefined && this.config.onPointMouseOut) {
+          this.config.onPointMouseOut(event)
+        }
+
+        // Clear link hover state and trigger callback if needed
+        if (this.store.hoveredLinkIndex !== undefined && this.config.onLinkMouseOut) {
+          this.config.onLinkMouseOut(event)
+        }
+
+        // Reset right-click flag
+        this.isRightClickMouse = false
+
+        // Clear hover states
+        this.store.hoveredPoint = undefined
+        this.store.hoveredLinkIndex = undefined
+
+        // Update cursor style after clearing hover states
+        this.updateCanvasCursor()
+      })
     select(document)
       .on('keydown.cosmos', (event) => { if (event.code === 'Space') this.store.isSpaceKeyPressed = true })
       .on('keyup.cosmos', (event) => { if (event.code === 'Space') this.store.isSpaceKeyPressed = false })
@@ -176,18 +199,15 @@ export class Graph {
     this.clusters = new Clusters(this.reglInstance, this.config, this.store, this.graph, this.points)
 
     this.store.backgroundColor = getRgbaColor(this.config.backgroundColor)
-    if (this.config.hoveredPointRingColor) {
-      this.store.setHoveredPointRingColor(this.config.hoveredPointRingColor)
-    }
-    if (this.config.focusedPointRingColor) {
-      this.store.setFocusedPointRingColor(this.config.focusedPointRingColor)
-    }
+    this.store.setHoveredPointRingColor(this.config.hoveredPointRingColor ?? defaultConfigValues.hoveredPointRingColor)
+    this.store.setFocusedPointRingColor(this.config.focusedPointRingColor ?? defaultConfigValues.focusedPointRingColor)
     if (this.config.focusedPointIndex !== undefined) {
       this.store.setFocusedPoint(this.config.focusedPointIndex)
     }
-    if (this.config.pointGreyoutColor) {
-      this.store.setGreyoutPointColor(this.config.pointGreyoutColor)
-    }
+    this.store.setGreyoutPointColor(this.config.pointGreyoutColor ?? defaultGreyoutPointColor)
+    this.store.setHoveredLinkColor(this.config.hoveredLinkColor ?? defaultConfigValues.hoveredLinkColor)
+
+    this.store.updateLinkHoveringEnabled(this.config)
 
     if (this.config.showFPSMonitor) this.fpsMonitor = new FPSMonitor(this.canvas)
 
@@ -227,7 +247,8 @@ export class Graph {
     if (this._isDestroyed || !this.reglInstance || !this.points || !this.lines || !this.clusters) return
     const prevConfig = { ...this.config }
     this.config.init(config)
-    if (prevConfig.pointColor !== this.config.pointColor) {
+    if ((prevConfig.pointDefaultColor !== this.config.pointDefaultColor) ||
+      (prevConfig.pointColor !== this.config.pointColor)) {
       this.graph.updatePointColor()
       this.points.updateColor()
     }
@@ -251,15 +272,20 @@ export class Graph {
       prevConfig.curvedLinks !== this.config.curvedLinks) {
       this.lines.updateCurveLineGeometry()
     }
-    if (prevConfig.backgroundColor !== this.config.backgroundColor) this.store.backgroundColor = getRgbaColor(this.config.backgroundColor)
+    if (prevConfig.backgroundColor !== this.config.backgroundColor) {
+      this.store.backgroundColor = getRgbaColor(this.config.backgroundColor ?? defaultBackgroundColor)
+    }
     if (prevConfig.hoveredPointRingColor !== this.config.hoveredPointRingColor) {
-      this.store.setHoveredPointRingColor(this.config.hoveredPointRingColor)
+      this.store.setHoveredPointRingColor(this.config.hoveredPointRingColor ?? defaultConfigValues.hoveredPointRingColor)
     }
     if (prevConfig.focusedPointRingColor !== this.config.focusedPointRingColor) {
-      this.store.setFocusedPointRingColor(this.config.focusedPointRingColor)
+      this.store.setFocusedPointRingColor(this.config.focusedPointRingColor ?? defaultConfigValues.focusedPointRingColor)
     }
     if (prevConfig.pointGreyoutColor !== this.config.pointGreyoutColor) {
-      this.store.setGreyoutPointColor(this.config.pointGreyoutColor)
+      this.store.setGreyoutPointColor(this.config.pointGreyoutColor ?? defaultGreyoutPointColor)
+    }
+    if (prevConfig.hoveredLinkColor !== this.config.hoveredLinkColor) {
+      this.store.setHoveredLinkColor(this.config.hoveredLinkColor ?? defaultConfigValues.hoveredLinkColor)
     }
     if (prevConfig.focusedPointIndex !== this.config.focusedPointIndex) {
       this.store.setFocusedPoint(this.config.focusedPointIndex)
@@ -285,6 +311,12 @@ export class Graph {
     if (prevConfig.enableZoom !== this.config.enableZoom || prevConfig.enableDrag !== this.config.enableDrag) {
       this.updateZoomDragBehaviors()
     }
+
+    if (prevConfig.onLinkClick !== this.config.onLinkClick ||
+        prevConfig.onLinkMouseOver !== this.config.onLinkMouseOver ||
+        prevConfig.onLinkMouseOut !== this.config.onLinkMouseOut) {
+      this.store.updateLinkHoveringEnabled(this.config)
+    }
   }
 
   /**
@@ -309,6 +341,7 @@ export class Graph {
     this.isPointSizeUpdateNeeded = true
     this.isPointShapeUpdateNeeded = true
     this.isPointImageIndicesUpdateNeeded = true
+    this.isPointImageSizesUpdateNeeded = true
     this.isPointClusterUpdateNeeded = true
     this.isForceManyBodyUpdateNeeded = true
     this.isForceLinkUpdateNeeded = true
@@ -561,6 +594,29 @@ export class Graph {
     this.isPointClusterUpdateNeeded = true
   }
 
+  /**
+   * Sets which points are pinned (fixed) in position.
+   *
+   * Pinned points:
+   * - Do not move due to physics forces (gravity, repulsion, link forces, etc.)
+   * - Still participate in force calculations (other nodes are attracted to/repelled by them)
+   * - Can still be dragged by the user if `enableDrag` is true
+   *
+   * @param {number[] | null} pinnedIndices - Array of point indices to pin. Set to `[]` or `null` to unpin all points.
+   * @example
+   *   // Pin points 0 and 5
+   *   graph.setPinnedPoints([0, 5])
+   *
+   *   // Unpin all points
+   *   graph.setPinnedPoints([])
+   *   graph.setPinnedPoints(null)
+   */
+  public setPinnedPoints (pinnedIndices: number[] | null): void {
+    if (this._isDestroyed || !this.points) return
+    this.graph.inputPinnedPoints = pinnedIndices && pinnedIndices.length > 0 ? pinnedIndices : undefined
+    this.points.updatePinnedStatus()
+  }
+
   /**
    * Renders the graph.
    *
@@ -1065,7 +1121,8 @@ export class Graph {
   }
 
   /**
-   * Pause the simulation.
+   * Pause the simulation. When paused, the simulation stops running
+   * and can be resumed using the unpause method.
    */
   public pause (): void {
     if (this._isDestroyed) return
@@ -1074,7 +1131,19 @@ export class Graph {
   }
 
   /**
-   * Restart the simulation.
+   * Unpause the simulation. This method resumes a paused
+   * simulation and continues its execution.
+   */
+  public unpause (): void {
+    if (this._isDestroyed) return
+    this.store.isSimulationRunning = true
+    this.config.onSimulationUnpause?.()
+  }
+
+  /**
+   * Restart/Resume the simulation. This method unpauses a paused
+   * simulation and resumes its execution.
+   * @deprecated Use `unpause()` instead. This method will be removed in a future version.
    */
   public restart (): void {
     if (this._isDestroyed) return
@@ -1245,6 +1314,7 @@ export class Graph {
   }
 
   private frame (): void {
+    if (this._isDestroyed) return
     const { config: { simulationGravity, simulationCenter, renderLinks, enableSimulation }, store: { alpha, isSimulationRunning } } = this
     if (alpha < ALPHA_MIN && isSimulationRunning) this.end()
     if (!this.store.pointsTextureSize) return
@@ -1252,7 +1322,9 @@ export class Graph {
     this.requestAnimationFrameId = window.requestAnimationFrame((now) => {
       this.fpsMonitor?.begin()
       this.resizeCanvas()
-      if (!this.dragInstance.isActive) this.findHoveredPoint()
+      if (!this.dragInstance.isActive) {
+        this.findHoveredItem()
+      }
 
       if (enableSimulation) {
         if (this.isRightClickMouse && this.config.enableRightClickRepulsion) {
@@ -1314,11 +1386,15 @@ export class Graph {
         // To prevent the dragged point from suddenly jumping, run the drag function twice
         this.points?.drag()
         this.points?.drag()
+        // Update tracked positions after drag, even when simulation is disabled
+        this.points?.trackPoints()
       }
       this.fpsMonitor?.end(now)
 
       this.currentEvent = undefined
-      this.frame()
+      if (!this._isDestroyed) {
+        this.frame()
+      }
     })
   }
 
@@ -1338,6 +1414,23 @@ export class Graph {
       this.store.hoveredPoint?.position,
       event
     )
+
+    if (this.store.hoveredPoint) {
+      this.config.onPointClick?.(
+        this.store.hoveredPoint.index,
+        this.store.hoveredPoint.position,
+        event
+      )
+    } else if (this.store.hoveredLinkIndex !== undefined) {
+      this.config.onLinkClick?.(
+        this.store.hoveredLinkIndex,
+        event
+      )
+    } else {
+      this.config.onBackgroundClick?.(
+        event
+      )
+    }
   }
 
   private updateMousePosition (event: MouseEvent | D3DragEvent<HTMLCanvasElement, undefined, Hovered>): void {
@@ -1365,6 +1458,7 @@ export class Graph {
   }
 
   private resizeCanvas (forceResize = false): void {
+    if (this._isDestroyed) return
     const prevWidth = this.canvas.width
     const prevHeight = this.canvas.height
     const w = this.canvas.clientWidth
@@ -1382,6 +1476,10 @@ export class Graph {
       this.canvasD3Selection
         ?.call(this.zoomInstance.behavior.transform, this.zoomInstance.getTransform([centerPosition], k))
       this.points?.updateSampledPointsGrid()
+      // Only update link index FBO if link hovering is enabled
+      if (this.store.isLinkHoveringEnabled) {
+        this.lines?.updateLinkIndexFbo()
+      }
     }
   }
 
@@ -1413,13 +1511,31 @@ export class Graph {
     }
   }
 
-  private findHoveredPoint (): void {
-    if (!this._isMouseOnCanvas || !this.reglInstance || !this.points) return
-    if (this._findHoveredPointExecutionCount < 2) {
-      this._findHoveredPointExecutionCount += 1
+  private findHoveredItem (): void {
+    if (this._isDestroyed || !this._isMouseOnCanvas || !this.reglInstance) return
+    if (this._findHoveredItemExecutionCount < MAX_HOVER_DETECTION_DELAY) {
+      this._findHoveredItemExecutionCount += 1
       return
     }
-    this._findHoveredPointExecutionCount = 0
+    this._findHoveredItemExecutionCount = 0
+    this.findHoveredPoint()
+
+    if (this.graph.linksNumber && this.store.isLinkHoveringEnabled) {
+      this.findHoveredLine()
+    } else if (this.store.hoveredLinkIndex !== undefined) {
+      // Clear stale hoveredLinkIndex when there are no links
+      const wasHovered = this.store.hoveredLinkIndex !== undefined
+      this.store.hoveredLinkIndex = undefined
+      if (wasHovered && this.config.onLinkMouseOut) {
+        this.config.onLinkMouseOut(this.currentEvent)
+      }
+    }
+
+    this.updateCanvasCursor()
+  }
+
+  private findHoveredPoint (): void {
+    if (this._isDestroyed || !this.reglInstance || !this.points) return
     this.points.findHoveredPoint()
     let isMouseover = false
     let isMouseout = false
@@ -1447,15 +1563,46 @@ export class Graph {
       )
     }
     if (isMouseout) this.config.onPointMouseOut?.(this.currentEvent)
-    this.updateCanvasCursor()
+  }
+
+  private findHoveredLine (): void {
+    if (this._isDestroyed || !this.reglInstance || !this.lines) return
+    if (this.store.hoveredPoint) {
+      if (this.store.hoveredLinkIndex !== undefined) {
+        this.store.hoveredLinkIndex = undefined
+        this.config.onLinkMouseOut?.(this.currentEvent)
+      }
+      return
+    }
+    this.lines.findHoveredLine()
+    let isMouseover = false
+    let isMouseout = false
+
+    const pixels = readPixels(this.reglInstance, this.lines.hoveredLineIndexFbo as regl.Framebuffer2D)
+    const hoveredLineIndex = pixels[0] as number
+
+    if (hoveredLineIndex >= 0) {
+      if (this.store.hoveredLinkIndex !== hoveredLineIndex) isMouseover = true
+      this.store.hoveredLinkIndex = hoveredLineIndex
+    } else {
+      if (this.store.hoveredLinkIndex !== undefined) isMouseout = true
+      this.store.hoveredLinkIndex = undefined
+    }
+
+    if (isMouseover && this.store.hoveredLinkIndex !== undefined) {
+      this.config.onLinkMouseOver?.(this.store.hoveredLinkIndex)
+    }
+    if (isMouseout) this.config.onLinkMouseOut?.(this.currentEvent)
   }
 
   private updateCanvasCursor (): void {
-    const { hoveredPointCursor } = this.config
+    const { hoveredPointCursor, hoveredLinkCursor } = this.config
     if (this.dragInstance.isActive) select(this.canvas).style('cursor', 'grabbing')
     else if (this.store.hoveredPoint) {
       if (!this.config.enableDrag || this.store.isSpaceKeyPressed) select(this.canvas).style('cursor', hoveredPointCursor)
       else select(this.canvas).style('cursor', 'grab')
+    } else if (this.store.isLinkHoveringEnabled && this.store.hoveredLinkIndex !== undefined) {
+      select(this.canvas).style('cursor', hoveredLinkCursor)
     } else select(this.canvas).style('cursor', null)
   }
 

package/src/modules/GraphData/index.ts

@@ -27,6 +27,7 @@ export class GraphData {
   public inputPointClusters: (number | undefined)[] | undefined
   public inputClusterPositions: (number | undefined)[] | undefined
   public inputClusterStrength: Float32Array | undefined
+  public inputPinnedPoints: number[] | undefined
 
   public pointPositions: Float32Array | undefined
   public pointColors: Float32Array | undefined
@@ -87,7 +88,7 @@ export class GraphData {
     }
 
     // Sets point colors to default values from config if the input is missing or does not match input points number.
-    const defaultRgba = getRgbaColor(this._config.pointColor)
+    const defaultRgba = getRgbaColor(this._config.pointDefaultColor ?? this._config.pointColor)
     if (this.inputPointColors === undefined || this.inputPointColors.length / 4 !== this.pointsNumber) {
       this.pointColors = new Float32Array(this.pointsNumber * 4)
       for (let i = 0; i < this.pointColors.length / 4; i++) {

package/src/modules/Lines/draw-curve-line.frag

@@ -6,6 +6,10 @@ varying float arrowLength;
 varying float useArrow;
 varying float smoothing;
 varying float arrowWidthFactor;
+varying float linkIndex;
+
+// renderMode: 0.0 = normal rendering, 1.0 = index buffer rendering for picking
+uniform float renderMode;
 
 float map(float value, float min1, float max1, float min2, float max2) {
   return min2 + (value - min1) * (max2 - min2) / (max1 - min1);
@@ -31,5 +35,12 @@ void main() {
     opacity = linkOpacity;
   } else opacity = rgbaColor.a * smoothstep(0.5, 0.5 - smoothing, abs(pos.y));
   
-  gl_FragColor = vec4(color, opacity);
+  if (renderMode > 0.0) {
+    if (opacity > 0.0) {
+      gl_FragColor = vec4(linkIndex, 0.0, 0.0, 1.0);
+    } else {
+      gl_FragColor = vec4(-1.0, 0.0, 0.0, 0.0);
+    }
+  } else gl_FragColor = vec4(color, opacity);
+
 }

package/src/modules/Lines/draw-curve-line.vert

@@ -4,13 +4,14 @@ attribute vec2 position, pointA, pointB;
 attribute vec4 color;
 attribute float width;
 attribute float arrow;
+attribute float linkIndices;
 
 uniform sampler2D positionsTexture;
 uniform sampler2D pointGreyoutStatus;
 uniform mat3 transformationMatrix;
 uniform float pointsTextureSize;
 uniform float widthScale;
-uniform float arrowSizeScale;
+uniform float linkArrowsSizeScale;
 uniform float spaceSize;
 uniform vec2 screenSize;
 uniform vec2 linkVisibilityDistanceRange;
@@ -22,6 +23,11 @@ uniform float curvedLinkControlPointDistance;
 uniform float curvedLinkSegments;
 uniform bool scaleLinksOnZoom;
 uniform float maxPointSize;
+// renderMode: 0.0 = normal rendering, 1.0 = index buffer rendering for picking
+uniform float renderMode;
+uniform float hoveredLinkIndex;
+uniform vec4 hoveredLinkColor;
+uniform float hoveredLinkWidthIncrease;
 
 varying vec4 rgbaColor;
 varying vec2 pos;
@@ -29,6 +35,7 @@ varying float arrowLength;
 varying float useArrow;
 varying float smoothing;
 varying float arrowWidthFactor;
+varying float linkIndex;
 
 float map(float value, float min1, float max1, float min2, float max2) {
   return min2 + (value - min1) * (max2 - min2) / (max1 - min1);
@@ -73,6 +80,7 @@ float calculateArrowWidth(float arrowWidth) {
 
 void main() {
   pos = position;
+  linkIndex = linkIndices;
 
   vec2 pointTexturePosA = (pointA + 0.5) / pointsTextureSize;
   vec2 pointTexturePosB = (pointB + 0.5) / pointsTextureSize;
@@ -102,7 +110,7 @@ void main() {
   float k = 2.0;
   // Arrow width is proportionally larger than the line width
   float arrowWidth = linkWidth * k;
-  arrowWidth *= arrowSizeScale;
+  arrowWidth *= linkArrowsSizeScale;
 
   // Ensure arrow width difference is non-negative to prevent unwanted changes to link width
   float arrowWidthDifference = max(0.0, arrowWidth - linkWidth);
@@ -124,10 +132,22 @@ void main() {
 
   // Calculate final link width in pixels with smoothing
   float linkWidthPx = calculateLinkWidth(linkWidth);
+    
+  if (renderMode > 0.0) {
+    // Add 5 pixels padding for better hover detection
+    linkWidthPx += 5.0 / transformationMatrix[0][0];
+  } else {
+      // Add pixel increase if this is the hovered link
+    if (hoveredLinkIndex == linkIndex) {
+      linkWidthPx += hoveredLinkWidthIncrease / transformationMatrix[0][0];
+    }
+  }
   float smoothingPx = 0.5 / transformationMatrix[0][0];
   smoothing = smoothingPx / linkWidthPx;
   linkWidthPx += smoothingPx;
 
+
+
   // Calculate final color with opacity based on link distance
   vec3 rgbColor = color.rgb;
   // Adjust opacity based on link distance
@@ -141,6 +161,13 @@ void main() {
   // Pass final color to fragment shader
   rgbaColor = vec4(rgbColor, opacity);
 
+  // Apply hover color if this is the hovered link and hover color is defined
+  if (hoveredLinkIndex == linkIndex && hoveredLinkColor.a > -0.5) {
+    // Keep existing RGB values but multiply opacity with hover color opacity
+    rgbaColor.rgb = hoveredLinkColor.rgb;
+    rgbaColor.a *= hoveredLinkColor.a;
+  }
+
   // Calculate position on the curved path
   float t = position.x;
   float w = curvedWeight;

package/src/modules/Lines/hovered-line-index.frag

@@ -0,0 +1,27 @@
+precision highp float;
+
+uniform sampler2D linkIndexTexture;
+uniform vec2 mousePosition;
+uniform vec2 screenSize;
+
+varying vec2 vTexCoord;
+
+void main() {
+  // Convert mouse position to texture coordinates
+  vec2 texCoord = mousePosition / screenSize;
+  
+  // Read the link index from the linkIndexFbo texture at mouse position
+  vec4 linkIndexData = texture2D(linkIndexTexture, texCoord);
+  
+  // Extract the link index (stored in the red channel)
+  float linkIndex = linkIndexData.r;
+  
+  // Check if there's a valid link at this position (alpha > 0)
+  if (linkIndexData.a > 0.0 && linkIndex >= 0.0) {
+    // Output the link index
+    gl_FragColor = vec4(linkIndex, 0.0, 0.0, 1.0);
+  } else {
+    // No link at this position, output -1 to indicate no hover
+    gl_FragColor = vec4(-1.0, 0.0, 0.0, 0.0);
+  }
+} 

package/src/modules/Lines/hovered-line-index.vert

@@ -0,0 +1,8 @@
+attribute vec2 position;
+
+varying vec2 vTexCoord;
+
+void main() {
+  vTexCoord = position * 0.5 + 0.5;
+  gl_Position = vec4(position, 0.0, 1.0);
+}