![\"cosmos.gl](\"https://assets.cosmograph.app/cosmos-light-theme.svg\")
\n \n \n
GPU-accelerated Force Graph
\n\n**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.\n\nThis engine powers 🪐 [Cosmograph](https://cosmograph.app) — a toolset for exploring complex networks and AI embeddings.\n\n\n\n[📺 Comparison with other libraries](https://www.youtube.com/watch?v=HWk78hP8aEE)\n\n[🎮 Check out our storybook for examples](https://cosmosgl.github.io/graph/)\n\n---\n\n### Quick Start\n\nInstall the package:\n\n```bash\nnpm install @cosmos.gl/graph\n```\n\nGet the data, [configure](https://cosmosgl.github.io/graph/?path=/docs/configuration--docs) the graph and run the simulation:\n\n```ts\nimport { Graph } from '@cosmos.gl/graph'\n\nconst div = document.querySelector('div')\nconst config = {\n spaceSize: 4096,\n simulationFriction: 0.1, // keeps the graph inert\n simulationGravity: 0, // disables the gravity force\n simulationRepulsion: 0.5, // increases repulsion between points\n curvedLinks: true, // curved links\n fitViewOnInit: true, // fit the view to the graph after initialization\n fitViewDelay: 1000, // wait 1 second before fitting the view\n fitViewPadding: 0.3, // centers the graph with a padding of ~30% of screen\n rescalePositions: false, // rescale positions, useful when coordinates are too small\n enableDrag: true, // enable dragging points\n onClick: (pointIndex) => { console.log('Clicked point index: ', pointIndex) },\n /* ... */\n}\n\nconst graph = new Graph(div, config)\n\n// Points: [x1, y1, x2, y2, x3, y3]\nconst pointPositions = new Float32Array([\n 0.0, 0.0, // Point 1 at (0,0)\n 1.0, 0.0, // Point 2 at (1,0)\n 0.5, 1.0, // Point 3 at (0.5,1)\n]);\n\ngraph.setPointPositions(pointPositions)\n\n// Links: [sourceIndex1, targetIndex1, sourceIndex2, targetIndex2]\nconst links = new Float32Array([\n 0, 1, // Link from point 0 to point 1\n 1, 2, // Link from point 1 to point 2\n 2, 0, // Link from point 2 to point 0\n]);\n\ngraph.setLinks(links)\n\ngraph.render()\n```\n\n---\n\n### What's New in v3.0?\n\ncosmos.gl v3.0 brings a new rendering engine, async initialization, and several new features:\n\n- **luma.gl (WebGL 2)** — rendering ported from regl to [luma.gl](https://luma.gl/), with support for sharing a custom `Device` across multiple graphs via `new Graph(div, config, devicePromise)`.\n- **Async initialization** — the constructor returns immediately; all public methods queue until the device is ready. Use `graph.ready` / `graph.isReady` to know when the graph is usable.\n- **Simulation control** — rendering is now separate from simulation. The simulation starts automatically by default; use `start()`, `stop()`, `pause()`, and `unpause()` to control it independently.\n- **Link sampling** — sample visible links on screen with `getSampledLinks()` and `getSampledLinkPositionsMap()` for rendering labels or overlays along links.\n- **Touch and pen support** — tap, drag, and pinch-to-zoom on phones and tablets. Long-press (~500 ms) triggers context menu callbacks. `onMouseMove` and all click callbacks fire from touch input.\n- **Context menu support** — new callbacks for right-click on desktop and long-press on touch/pen: `onContextMenu`, `onPointContextMenu`, `onLinkContextMenu`, `onBackgroundContextMenu`.\n- **Fit viewport to points** — `setZoomTransformByPointPositions()` zooms and pans to fit a set of points into view.\n- **Config-driven highlighting** — imperative selection methods replaced by `highlightedPointIndices`, `highlightedLinkIndices`, and `outlinedPointIndices` config properties. Points and links are highlighted independently. Focused links are rendered wider via `focusedLinkIndex` / `focusedLinkWidthIncrease`. New `findPointsInRect()`, `findPointsInPolygon()`, `getNeighboringPointIndices()`, `getConnectedLinkIndices()`, and `getConnectedPointIndices()` methods.\n- **Link blending control** — `linkBlending: false` disables alpha blending for significantly faster link rendering on dense graphs.\n- **Hover improvements** — `onPointMouseOver` now includes `isHighlighted` and `isOutlined` parameters; hover correctly highlights the topmost point when points overlap.\n- **Config API changes** — `setConfig()` now resets all values to defaults before applying; use the new `setConfigPartial()` to update individual properties without resetting the rest.\n- **Init-only config fields** — `initialZoomLevel`, `randomSeed`, and `attribution` can only be set during initialization and are preserved across config updates.\n- **Runtime simulation toggle** — `enableSimulation` can now be changed at runtime via `setConfig()` or `setConfigPartial()`.\n- **GPU transitions** — point positions, point colors/sizes, and link colors/widths now animate by default (`transitionDuration: 800`, `transitionEasing: TransitionEasing.CubicInOut`). Use `transitionDuration: 0` to keep snap updates.\n- **Transition callbacks** — use `onTransitionStart`, `onTransition`, and `onTransitionEnd` to track transition lifecycle and progress.\n- **Default point shape** — new `pointDefaultShape` config property lets you set the fallback shape for all points when no per-point shapes are provided. Accepts a `PointShape` enum value (e.g., `PointShape.Star`), a plain number (e.g., `6`), or a numeric string (e.g., `\"6\"`).\n- **Collision force** — new GPU-accelerated collision force keeps points from overlapping, using a spatial-hash grid that scales to large graphs. Enable it with `simulationCollision`, and tune the spacing with `simulationCollisionRadius` (fixed radius vs. size-derived) and `simulationCollisionPadding` (extra gap between points). See the [Collision example](https://cosmosgl.github.io/graph/?path=/story/examples-forces--collision).\n- **Exported defaults** — `defaultConfigValues` is now part of the public API.\n- **Optimized hover detection** — skips GPU work when the mouse hasn't moved.\n\nCheck the [Migration Guide](./migration-notes.md) for upgrading from v2.\n\n### What's New in v2.0?\n\ncosmos.gl v2.0 introduces significant improvements in performance and data handling:\n\n- Enhanced data structures with WebGL-compatible formats.\n- Methods like `setPointPositions` and `setLinks` replace `setData` for improved efficiency.\n- Direct control over point and link attributes via Float32Array (e.g., colors, sizes, widths).\n- Updated event handling based on indices instead of objects.\n- New Point Clustering force (`setPointClusters`, `setClusterPositions` and `setPointClusterStrength`).\n- Ability to drag points.\n\nCheck the [Migration Guide](./migration-notes.md) for upgrading from v1.\n\n---\n\n### Examples\n\n- [Actions](https://cosmosgl.github.io/graph/?path=/story/examples-get-started--actions)\n\n---\n\n### Showcase (via [cosmograph.app](https://cosmograph.app))\n\n- [Silk Road Case: Bitcoin Transactions](https://run.cosmograph.app/public/987cf266-fd90-4940-b52d-f75a1e006237) ([📄 Read more](https://medium.com/@cosmograph.app/visualizing-darknet-6846dec7f1d7))\n- [ABACUS Shell](https://run.cosmograph.app/public/b099a861-47ba-4110-b778-c4ef0f29644f) ([source](http://sparse.tamu.edu/Puri/ABACUS_shell_hd))\n- [The MathWorks, Inc: symmetric positive definite matrix](https://run.cosmograph.app/public/cb6f43f2-71c7-47de-97c5-d86ac549cfed) ([source](https://sparse.tamu.edu/MathWorks/Kuu))\n\n---\n\n### Known Issues\n\n- ~~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!\n- cosmos.gl doesn't work on Android devices that don't support the `OES_texture_float` WebGL extension.\n\n\n---\n\n### Documentation\n- 🧑💻 [Quick Start](https://cosmosgl.github.io/graph/?path=/docs/welcome-to-cosmos-gl--docs)\n- 🛠 [Configuration](https://cosmosgl.github.io/graph/?path=/docs/configuration--docs)\n- ⚙️ [API Reference](https://cosmosgl.github.io/graph/?path=/docs/api-reference--docs)\n- 🚀 [Migration Guide](https://github.com/cosmosgl/graph/blob/main/migration-notes.md)\n\n---\n\n### License\n\n**MIT**\n\n---\n\n### Contact\n\n[GitHub Discussions](https://github.com/orgs/cosmosgl/discussions)\n","readmeFilename":"README.md"}