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

package/src/modules/Points/track-positions.frag

@@ -0,0 +1,30 @@
+#version 300 es
+#ifdef GL_ES
+precision highp float;
+#endif
+
+uniform sampler2D positionsTexture;
+uniform sampler2D trackedIndices;
+
+#ifdef USE_UNIFORM_BUFFERS
+layout(std140) uniform trackPointsUniforms {
+  float pointsTextureSize;
+} trackPoints;
+
+#define pointsTextureSize trackPoints.pointsTextureSize
+#else
+uniform float pointsTextureSize;
+#endif
+
+in vec2 textureCoords;
+
+out vec4 fragColor;
+
+void main() {
+  vec4 trackedPointIndices = texture(trackedIndices, textureCoords);
+  if (trackedPointIndices.r < 0.0) discard;
+  vec4 pointPosition = texture(positionsTexture, (trackedPointIndices.rg + 0.5) / pointsTextureSize);
+
+  fragColor = vec4(pointPosition.rg, 1.0, 1.0);
+}
+

package/src/modules/Points/update-position.frag

@@ -0,0 +1,39 @@
+#version 300 es
+#ifdef GL_ES
+precision highp float;
+#endif
+
+uniform sampler2D positionsTexture;
+uniform sampler2D velocity;
+
+#ifdef USE_UNIFORM_BUFFERS
+layout(std140) uniform updatePositionUniforms {
+  float friction;
+  float spaceSize;
+} updatePosition;
+
+#define friction updatePosition.friction
+#define spaceSize updatePosition.spaceSize
+#else
+uniform float friction;
+uniform float spaceSize;
+#endif
+
+in vec2 textureCoords;
+
+out vec4 fragColor;
+
+void main() {
+  vec4 pointPosition = texture(positionsTexture, textureCoords);
+  vec4 pointVelocity = texture(velocity, textureCoords);
+
+  // Friction
+  pointVelocity.rg *= friction;
+
+  pointPosition.rg += pointVelocity.rg;
+
+  pointPosition.r = clamp(pointPosition.r, 0.0, spaceSize);
+  pointPosition.g = clamp(pointPosition.g, 0.0, spaceSize);
+  
+  fragColor = pointPosition;
+}

package/src/modules/Shared/buffer.ts

@@ -0,0 +1,39 @@
+import regl from 'regl'
+
+export function createQuadBuffer (reglInstance: regl.Regl): { buffer: regl.Buffer; size: number } {
+  const QUAD_POSITIONS = [-1, -1, 1, -1, -1, 1, 1, 1]
+
+  const quadBuffer = reglInstance.buffer(new Float32Array(QUAD_POSITIONS))
+  return {
+    buffer: quadBuffer,
+    size: 2,
+  }
+}
+
+export function createIndexesForBuffer (textureSize: number): Float32Array {
+  const indexes = new Float32Array(textureSize * textureSize * 2)
+  for (let y = 0; y < textureSize; y++) {
+    for (let x = 0; x < textureSize; x++) {
+      const i = y * textureSize * 2 + x * 2
+      indexes[i + 0] = x
+      indexes[i + 1] = y
+    }
+  }
+  return indexes
+}
+
+export function destroyFramebuffer (fbo?: regl.Framebuffer2D): void {
+  if (!fbo) return
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  if ((fbo as any)?._framebuffer?.framebuffer) {
+    fbo.destroy()
+  }
+}
+
+export function destroyBuffer (fbo?: regl.Buffer): void {
+  if (!fbo) return
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  if ((fbo as any)?._buffer?.buffer) {
+    fbo.destroy()
+  }
+}

package/src/modules/Shared/clear.frag

@@ -0,0 +1,10 @@
+#version 300 es
+#ifdef GL_ES
+precision highp float;
+#endif
+
+out vec4 fragColor;
+
+void main() {
+  fragColor = vec4(0.0);
+}

package/src/modules/Shared/quad.vert

@@ -0,0 +1,13 @@
+#version 300 es
+#ifdef GL_ES
+precision highp float;
+#endif
+
+in vec2 vertexCoord; // Vertex coordinates in normalized device coordinates
+out vec2 textureCoords; // Texture coordinates to pass to the fragment shader
+
+void main() {
+    // Convert vertex coordinates from [-1, 1] range to [0, 1] range for texture sampling
+    textureCoords = (vertexCoord + 1.0) / 2.0;
+    gl_Position = vec4(vertexCoord, 0, 1);
+}

package/src/modules/Store/index.ts

@@ -0,0 +1,283 @@
+import { scaleLinear } from 'd3-scale'
+import { mat3 } from 'gl-matrix'
+import { Random } from 'random'
+import { getRgbaColor, rgbToBrightness } from '@/graph/helper'
+import { hoveredPointRingOpacity, focusedPointRingOpacity, defaultConfigValues } from '@/graph/variables'
+import type { GraphConfigInterface } from '@/graph/config'
+
+export const ALPHA_MIN = 0.001
+export const MAX_POINT_SIZE = 64
+
+/**
+ * Maximum number of executions to delay before performing hover detection.
+ * This threshold prevents excessive hover detection calls for performance optimization.
+ * The `findHoveredItem` method will skip actual detection until this count is reached.
+ */
+export const MAX_HOVER_DETECTION_DELAY = 4
+
+export type Hovered = { index: number; position: [ number, number ] }
+type Focused = { index: number }
+
+/**
+ * Type alias for a 4x4 matrix stored as a 16-element array in column-major order.
+ * Used for std140 uniform buffer layout compatibility.
+ */
+type Mat4Array = [number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number]
+
+export class Store {
+  public pointsTextureSize = 0
+  public linksTextureSize = 0
+  public alpha = 1
+  public transform = mat3.create()
+  public screenSize: [number, number] = [0, 0]
+  public mousePosition = [0, 0]
+  public screenMousePosition = [0, 0]
+  public selectedArea = [[0, 0], [0, 0]]
+  public isSimulationRunning = false
+  public simulationProgress = 0
+  public selectedIndices: Float32Array | null = null
+  public maxPointSize = MAX_POINT_SIZE
+  public hoveredPoint: Hovered | undefined = undefined
+  public focusedPoint: Focused | undefined = undefined
+  public draggingPointIndex: number | undefined = undefined
+  public hoveredLinkIndex: number | undefined = undefined
+  public adjustedSpaceSize = defaultConfigValues.spaceSize
+  public isSpaceKeyPressed = false
+  public div: HTMLDivElement | undefined
+  public webglMaxTextureSize = 16384 // Default fallback value
+
+  public hoveredPointRingColor = [1, 1, 1, hoveredPointRingOpacity]
+  public focusedPointRingColor = [1, 1, 1, focusedPointRingOpacity]
+  public hoveredLinkColor = [-1, -1, -1, -1]
+  // -1 means that the color is not set
+  public greyoutPointColor = [-1, -1, -1, -1]
+  // If backgroundColor is dark, isDarkenGreyout is true
+  public isDarkenGreyout = false
+  // Whether link hovering is enabled based on configured event handlers
+  public isLinkHoveringEnabled = false
+  private alphaTarget = 0
+  private scalePointX = scaleLinear()
+  private scalePointY = scaleLinear()
+  private random = new Random()
+  private _backgroundColor: [number, number, number, number] = [0, 0, 0, 0]
+
+  public get backgroundColor (): [number, number, number, number] {
+    return this._backgroundColor
+  }
+
+  /**
+   * Gets the transformation matrix as a 4x4 matrix for std140 uniform buffer layout.
+   *
+   * This method converts the internal 3x3 transformation matrix (mat3) to a 4x4 matrix format
+   * required by WebGPU uniform buffers using the std140 layout standard.
+   *
+   * ## Matrix Storage Format
+   *
+   * Matrices are stored in **column-major order** (GLSL convention). The internal `transform`
+   * array is a 9-element array representing a 3x3 matrix:
+   *
+   * ```
+   * [m00, m10, m20, m01, m11, m21, m02, m12, m22]
+   * ```
+   *
+   * Which represents the matrix:
+   * ```
+   * [m00 m01 m02]
+   * [m10 m11 m12]
+   * [m20 m21 m22]
+   * ```
+   *
+   * ## Why This Conversion Is Needed
+   *
+   * The internal `transform` property stores a 3x3 matrix (9 elements) which is sufficient for
+   * 2D transformations (translation, rotation, scaling in x/y plane). However, when passing
+   * transformation matrices to GPU shaders via uniform buffers, we must comply with the std140
+   * layout standard.
+   *
+   * ### std140 Layout Requirements
+   *
+   * The std140 layout standard (used in both OpenGL and WebGPU) defines strict alignment rules:
+   *
+   * 1. **Matrix Alignment**: In std140, matrices are stored as arrays of column vectors
+   *    - `mat3` requires each column to be aligned to 16 bytes (vec4 alignment)
+   *    - This means `mat3` occupies 3 columns × 16 bytes = 48 bytes total
+   *    - `mat4` occupies 4 columns × 16 bytes = 64 bytes total
+   *
+   * 2. **Alignment Issues with mat3**:
+   *    - The 48-byte size of `mat3` creates awkward alignment and padding requirements
+   *    - Different GPU drivers may handle `mat3` padding inconsistently
+   *    - This can lead to data misalignment and incorrect transformations
+   *
+   * 3. **Why mat4 is Preferred**:
+   *    - `mat4` has clean 64-byte alignment (power of 2)
+   *    - Consistent behavior across all GPU drivers and platforms
+   *    - The shader can easily extract the 3x3 portion: `mat3 transformMat3 = mat3(transformationMatrix)`
+   *    - The 4th column is set to `[0, 0, 0, 1]` (homogeneous coordinate) which doesn't affect 2D transforms
+   *
+   * ### Conversion Process
+   *
+   * The 3x3 matrix is converted to 4x4 by:
+   * - Placing the 3x3 values in the top-left corner (preserving column-major order)
+   * - Setting the 4th column to `[0, 0, 0, 1]` (homogeneous coordinate)
+   * - The 4th row is implicitly `[0, 0, 0, 1]` due to column-major storage
+   *
+   * This creates a valid 4x4 transformation matrix that:
+   * - Maintains the same 2D transformation behavior
+   * - Satisfies std140 alignment requirements
+   * - Works consistently across all GPU platforms
+   *
+   * ### Usage in Shaders
+   *
+   * Shaders using uniform buffers receive this as `mat4` and extract the 3x3 portion:
+   * ```glsl
+   * layout(std140) uniform uniforms {
+   *   mat4 transformationMatrix;
+   * } uniforms;
+   *
+   * mat3 transformMat3 = mat3(uniforms.transformationMatrix);
+   * vec3 final = transformMat3 * vec3(position, 1);
+   * ```
+   *
+   * @returns A 16-element array representing a 4x4 matrix in column-major order,
+   *          suitable for std140 uniform buffer layout. The matrix preserves the
+   *          2D transformation from the original 3x3 matrix.
+   *
+   * @example
+   * ```typescript
+   * const matrix = store.transformationMatrix4x4;
+   * uniformStore.setUniforms({
+   *   uniforms: {
+   *     transformationMatrix: matrix  // Expects mat4x4<f32> in shader
+   *   }
+   * });
+   * ```
+   */
+  public get transformationMatrix4x4 (): Mat4Array {
+    const t = this.transform
+
+    // Validate transform array length
+    if (t.length !== 9) {
+      throw new Error(`Transform must be a 9-element array (3x3 matrix), got ${t.length} elements`)
+    }
+
+    // Convert 3x3 to 4x4 matrix in column-major order
+    return [
+      t[0], t[1], t[2], 0, // Column 0
+      t[3], t[4], t[5], 0, // Column 1
+      t[6], t[7], t[8], 0, // Column 2
+      0, 0, 0, 1, // Column 3 (homogeneous)
+    ]
+  }
+
+  public set backgroundColor (color: [number, number, number, number]) {
+    this._backgroundColor = color
+    const brightness = rgbToBrightness(color[0], color[1], color[2])
+    document.documentElement.style.setProperty('--cosmosgl-attribution-color', brightness > 0.65 ? 'black' : 'white')
+    document.documentElement.style.setProperty('--cosmosgl-error-message-color', brightness > 0.65 ? 'black' : 'white')
+    if (this.div) this.div.style.backgroundColor = `rgba(${color[0] * 255}, ${color[1] * 255}, ${color[2] * 255}, ${color[3]})`
+
+    this.isDarkenGreyout = brightness < 0.65
+  }
+
+  public addRandomSeed (seed: number | string): void {
+    this.random = this.random.clone(seed)
+  }
+
+  public getRandomFloat (min: number, max: number): number {
+    return this.random.float(min, max)
+  }
+
+  /**
+   * If the config parameter `spaceSize` exceeds the limits of WebGL,
+   * it reduces the space size without changing the config parameter.
+   */
+  public adjustSpaceSize (configSpaceSize: number, webglMaxTextureSize: number): void {
+    if (configSpaceSize >= webglMaxTextureSize) {
+      this.adjustedSpaceSize = webglMaxTextureSize / 2
+      console.warn(`The \`spaceSize\` has been reduced to ${this.adjustedSpaceSize} due to WebGL limits`)
+    } else this.adjustedSpaceSize = configSpaceSize
+  }
+
+  /**
+   * Sets the WebGL texture size limit for use in atlas creation and other texture operations.
+   */
+  public setWebGLMaxTextureSize (webglMaxTextureSize: number): void {
+    this.webglMaxTextureSize = webglMaxTextureSize
+  }
+
+  public updateScreenSize (width: number, height: number): void {
+    const { adjustedSpaceSize } = this
+    this.screenSize = [width, height]
+    this.scalePointX
+      .domain([0, adjustedSpaceSize])
+      .range([(width - adjustedSpaceSize) / 2, (width + adjustedSpaceSize) / 2])
+    this.scalePointY
+      .domain([adjustedSpaceSize, 0])
+      .range([(height - adjustedSpaceSize) / 2, (height + adjustedSpaceSize) / 2])
+  }
+
+  public scaleX (x: number): number {
+    return this.scalePointX(x)
+  }
+
+  public scaleY (y: number): number {
+    return this.scalePointY(y)
+  }
+
+  public setHoveredPointRingColor (color: string | [number, number, number, number]): void {
+    const convertedRgba = getRgbaColor(color)
+    this.hoveredPointRingColor[0] = convertedRgba[0]
+    this.hoveredPointRingColor[1] = convertedRgba[1]
+    this.hoveredPointRingColor[2] = convertedRgba[2]
+  }
+
+  public setFocusedPointRingColor (color: string | [number, number, number, number]): void {
+    const convertedRgba = getRgbaColor(color)
+    this.focusedPointRingColor[0] = convertedRgba[0]
+    this.focusedPointRingColor[1] = convertedRgba[1]
+    this.focusedPointRingColor[2] = convertedRgba[2]
+  }
+
+  public setGreyoutPointColor (color: string | [number, number, number, number] | undefined): void {
+    if (color === undefined) {
+      this.greyoutPointColor = [-1, -1, -1, -1]
+      return
+    }
+    const convertedRgba = getRgbaColor(color)
+    this.greyoutPointColor[0] = convertedRgba[0]
+    this.greyoutPointColor[1] = convertedRgba[1]
+    this.greyoutPointColor[2] = convertedRgba[2]
+    this.greyoutPointColor[3] = convertedRgba[3]
+  }
+
+  public updateLinkHoveringEnabled (config: Pick<GraphConfigInterface, 'onLinkClick' | 'onLinkMouseOver' | 'onLinkMouseOut'>): void {
+    this.isLinkHoveringEnabled = !!(config.onLinkClick || config.onLinkMouseOver || config.onLinkMouseOut)
+    if (!this.isLinkHoveringEnabled) {
+      this.hoveredLinkIndex = undefined
+    }
+  }
+
+  public setHoveredLinkColor (color?: string | [number, number, number, number]): void {
+    if (color === undefined) {
+      this.hoveredLinkColor = [-1, -1, -1, -1]
+      return
+    }
+    const convertedRgba = getRgbaColor(color)
+    this.hoveredLinkColor[0] = convertedRgba[0]
+    this.hoveredLinkColor[1] = convertedRgba[1]
+    this.hoveredLinkColor[2] = convertedRgba[2]
+    this.hoveredLinkColor[3] = convertedRgba[3]
+  }
+
+  public setFocusedPoint (index?: number): void {
+    if (index !== undefined) {
+      this.focusedPoint = { index }
+    } else this.focusedPoint = undefined
+  }
+
+  public addAlpha (decay: number): number {
+    return (this.alphaTarget - this.alpha) * this.alphaDecay(decay)
+  }
+
+  private alphaDecay = (decay: number): number => 1 - Math.pow(ALPHA_MIN, 1 / decay)
+}

package/src/modules/Zoom/index.ts

@@ -0,0 +1,148 @@
+import { zoom, ZoomTransform, zoomIdentity, D3ZoomEvent } from 'd3-zoom'
+import { extent } from 'd3-array'
+import { mat3 } from 'gl-matrix'
+import { Store } from '@/graph/modules/Store'
+import { GraphConfigInterface } from '@/graph/config'
+import { clamp } from '@/graph/helper'
+
+export class Zoom {
+  public readonly store: Store
+  public readonly config: GraphConfigInterface
+  public eventTransform = zoomIdentity
+  public behavior = zoom<HTMLCanvasElement, undefined>()
+    .scaleExtent([0.001, Infinity])
+    .on('start', (e: D3ZoomEvent<HTMLCanvasElement, undefined>) => {
+      this.isRunning = true
+      const userDriven = !!e.sourceEvent
+      this.config?.onZoomStart?.(e, userDriven)
+    })
+    .on('zoom', (e: D3ZoomEvent<HTMLCanvasElement, undefined>) => {
+      this.eventTransform = e.transform
+      const { eventTransform: { x, y, k }, store: { transform, screenSize } } = this
+      const w = screenSize[0]
+      const h = screenSize[1]
+      if (!w || !h) return
+      mat3.projection(transform, w, h)
+      mat3.translate(transform, transform, [x, y])
+      mat3.scale(transform, transform, [k, k])
+      mat3.translate(transform, transform, [w / 2, h / 2])
+      mat3.scale(transform, transform, [w / 2, h / 2])
+      mat3.scale(transform, transform, [1, -1])
+
+      const userDriven = !!e.sourceEvent
+      this.config?.onZoom?.(e, userDriven)
+    })
+    .on('end', (e: D3ZoomEvent<HTMLCanvasElement, undefined>) => {
+      this.isRunning = false
+
+      const userDriven = !!e.sourceEvent
+      this.config?.onZoomEnd?.(e, userDriven)
+    })
+
+  public isRunning = false
+
+  public constructor (store: Store, config: GraphConfigInterface) {
+    this.store = store
+    this.config = config
+  }
+
+  /**
+   * Get the zoom transform that will fit the given point positions into the viewport
+   *
+   * @param positions An array of point positions in the form `[x, y]`
+   * @param scale An optional scale factor to apply to the transform
+   * @param padding Padding around the viewport in percentage
+   */
+  public getTransform (positions: [number, number][], scale?: number, padding = 0.1): ZoomTransform {
+    if (positions.length === 0) return this.eventTransform
+    const { store: { screenSize } } = this
+    const width = screenSize[0]
+    const height = screenSize[1]
+    const xExtent = extent(positions.map(d => d[0])) as [number, number]
+    const yExtent = extent(positions.map(d => d[1])) as [number, number]
+    xExtent[0] = this.store.scaleX(xExtent[0])
+    xExtent[1] = this.store.scaleX(xExtent[1])
+    yExtent[0] = this.store.scaleY(yExtent[0])
+    yExtent[1] = this.store.scaleY(yExtent[1])
+    // Adjust extent with one screen pixel if one point coordinate is set
+    if (xExtent[0] === xExtent[1]) {
+      xExtent[0] -= 0.5
+      xExtent[1] += 0.5
+    }
+    if (yExtent[0] === yExtent[1]) {
+      yExtent[0] += 0.5
+      yExtent[1] -= 0.5
+    }
+
+    const xScale = (width * (1 - padding * 2)) / (xExtent[1] - xExtent[0])
+    const yScale = (height * (1 - padding * 2)) / (yExtent[0] - yExtent[1])
+    const clampedScale = clamp(scale ?? Math.min(xScale, yScale), ...this.behavior.scaleExtent())
+    const xCenter = (xExtent[1] + xExtent[0]) / 2
+    const yCenter = (yExtent[1] + yExtent[0]) / 2
+    const translateX = width / 2 - xCenter * clampedScale
+    const translateY = height / 2 - yCenter * clampedScale
+
+    const transform = zoomIdentity
+      .translate(translateX, translateY)
+      .scale(clampedScale)
+
+    return transform
+  }
+
+  public getDistanceToPoint (position: [number, number]): number {
+    const { x, y, k } = this.eventTransform
+    const point = this.getTransform([position], k)
+    const dx = x - point.x
+    const dy = y - point.y
+    return Math.sqrt(dx * dx + dy * dy)
+  }
+
+  public getMiddlePointTransform (position: [number, number]): ZoomTransform {
+    const { store: { screenSize }, eventTransform: { x, y, k } } = this
+    const width = screenSize[0]
+    const height = screenSize[1]
+    const currX = (width / 2 - x) / k
+    const currY = (height / 2 - y) / k
+    const pointX = this.store.scaleX(position[0])
+    const pointY = this.store.scaleY(position[1])
+    const centerX = (currX + pointX) / 2
+    const centerY = (currY + pointY) / 2
+
+    const scale = 1
+    const translateX = width / 2 - centerX * scale
+    const translateY = height / 2 - centerY * scale
+
+    return zoomIdentity
+      .translate(translateX, translateY)
+      .scale(scale)
+  }
+
+  public convertScreenToSpacePosition (screenPosition: [number, number]): [number, number] {
+    const { eventTransform: { x, y, k }, store: { screenSize } } = this
+    const w = screenSize[0]
+    const h = screenSize[1]
+    const invertedX = (screenPosition[0] - x) / k
+    const invertedY = (screenPosition[1] - y) / k
+    const spacePosition = [invertedX, (h - invertedY)] as [number, number]
+    spacePosition[0] -= (w - this.store.adjustedSpaceSize) / 2
+    spacePosition[1] -= (h - this.store.adjustedSpaceSize) / 2
+    return spacePosition
+  }
+
+  public convertSpaceToScreenPosition (spacePosition: [number, number]): [number, number] {
+    const screenPointX = this.eventTransform.applyX(this.store.scaleX(spacePosition[0]))
+    const screenPointY = this.eventTransform.applyY(this.store.scaleY(spacePosition[1]))
+    return [screenPointX, screenPointY]
+  }
+
+  public convertSpaceToScreenRadius (spaceRadius: number): number {
+    const { config: { scalePointsOnZoom }, store: { maxPointSize }, eventTransform: { k } } = this
+    let size = spaceRadius * 2
+    if (scalePointsOnZoom) {
+      size *= k
+    } else {
+      size *= Math.min(5.0, Math.max(1.0, k * 0.01))
+    }
+    return Math.min(size, maxPointSize) / 2
+  }
+}

package/src/modules/core-module.ts

@@ -0,0 +1,28 @@
+import { Device } from '@luma.gl/core'
+import { GraphConfigInterface } from '@/graph/config'
+import { GraphData } from '@/graph/modules/GraphData'
+import { Points } from '@/graph/modules/Points'
+import { Store } from '@/graph/modules/Store'
+
+export class CoreModule {
+  public readonly device: Device
+  public readonly config: GraphConfigInterface
+  public readonly store: Store
+  public readonly data: GraphData
+  public readonly points: Points | undefined
+  public _debugRandomNumber = Math.floor(Math.random() * 1000)
+
+  public constructor (
+    device: Device,
+    config: GraphConfigInterface,
+    store: Store,
+    data: GraphData,
+    points?: Points
+  ) {
+    this.device = device
+    this.config = config
+    this.store = store
+    this.data = data
+    if (points) this.points = points
+  }
+}

package/src/stories/1. welcome.mdx

@@ -0,0 +1,75 @@
+import { Meta } from "@storybook/blocks";
+
+<Meta title="Welcome to cosmos.gl" />
+
+<p style={{ fontSize: '2rem', lineHeight: '1.25em' }}>Welcome to cosmos.gl — a high-performance WebGL library for visualizing network graphs and machine learning embeddings.</p>
+
+<video style={{ width: '100%' }} src="https://user-images.githubusercontent.com/755708/173392407-9b05cbb6-d39e-4c2c-ab41-50900cfda823.mp4" loop autoPlay muted playsInline>
+</video>
+
+<p style={{ fontSize: '1.0rem' }}>Here you can find documentaion and examples of how to use cosmos.gl</p>
+
+---
+
+### Quick Start
+
+Install the package:
+
+```bash
+npm install @cosmos.gl/graph
+```
+
+
+Get the data, [configure](../?path=/docs/configuration--docs) the graph and run the simulation:
+```javascript
+import { Graph } from '@cosmos.gl/graph'
+
+const div = document.querySelector('div')
+const config = {
+  spaceSize: 4096,
+  simulationFriction: 0.1, // keeps the graph inert
+  simulationGravity: 0, // disables gravity
+  simulationRepulsion: 0.5, // increases repulsion between points
+  curvedLinks: true, // curved links
+  fitViewDelay: 1000, // wait 1 second before fitting the view
+  fitViewPadding: 0.3, // centers the graph width padding of ~30% of screen
+  rescalePositions: true, // rescale positions
+  enableDrag: true, // enable dragging points
+  onPointClick: pointIndex => { console.log('Clicked point index: ', pointIndex) },
+  onBackgroundClick: () => { console.log('Clicked background') },
+  /* ... */
+}
+
+const graph = new Graph(div, config)
+
+// Points: [x1, y1, x2, y2, x3, y3]
+const pointPositions = new Float32Array([
+  0.0, 0.0,    // Point 1 at (0,0)
+  1.0, 0.0,    // Point 2 at (1,0)
+  0.5, 1.0,    // Point 3 at (0.5,1)
+]);
+
+graph.setPointPositions(pointPositions)
+
+// Links: [sourceIndex1, targetIndex1, sourceIndex2, targetIndex2]
+const links = new Float32Array([
+  0, 1,    // Link from point 0 to point 1
+  1, 2,    // Link from point 1 to point 2
+  2, 0,    // Link from point 2 to point 0
+]);
+
+graph.setLinks(links)
+
+graph.render()
+```
+
+Try the [Quick Start](../?path=/story/examples-beginners--quick-start) example.
+
+### Examples
+- [Basic Set-Up](../?path=/story/examples-beginners--basic-set-up)
+- [Adding Point Labels](../?path=/story/examples-beginners--point-labels) (via [`@interacta/css-labels`](https://www.npmjs.com/package/@interacta/css-labels))
+
+
+---
+Copyright [OpenJS Foundation](https://openjsf.org) and cosmos.gl contributors. All rights reserved. The [OpenJS Foundation](https://openjsf.org) has registered trademarks and uses trademarks.  For a list of trademarks of the [OpenJS Foundation](https://openjsf.org), please see our [Trademark Policy](https://trademark-policy.openjsf.org/) and [Trademark List](https://trademark-list.openjsf.org/).  Trademarks and logos not indicated on the [list of OpenJS Foundation trademarks](https://trademark-list.openjsf.org) are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.
+[The OpenJS Foundation](https://openjsf.org/) | [Terms of Use](https://terms-of-use.openjsf.org/) | [Privacy Policy](https://privacy-policy.openjsf.org/) | [Bylaws](https://bylaws.openjsf.org/) | [Code of Conduct](https://code-of-conduct.openjsf.org) | [Trademark Policy](https://trademark-policy.openjsf.org/) | [Trademark List](https://trademark-list.openjsf.org/) | [Cookie Policy](https://www.linuxfoundation.org/cookies/)