Cosmograph

https://next.cosmograph.app/versions/v1-docs/
Admin
Cosmograph is a WebGL-based visualization library for rendering and interacting with large-scale...
Tokens:3,348
Snippets:25
Trust Score:7.4
Update:1 year ago
Show doc for...
Tokens:
Raw
### Cosmograph Usage Example for Simulation Parameters

Source: https://next.cosmograph.app/versions/v1-docs/app/sharing-graphs

An example URL showing how to launch Cosmograph with a specific data file and custom simulation parameters, including decay, link distance, and link spring strength.

```URL
https://cosmograph.app/run/?&decay=100000&link-distance=1&link-spring=2&data=https://cosmograph.app/data/100x100.csv
```

--------------------------------

### Cosmograph Usage Example for Link Color

Source: https://next.cosmograph.app/versions/v1-docs/app/sharing-graphs

An example URL demonstrating how to use the Cosmograph app with a specific data file and set the link color based on the average of the 'value' column.

```URL
https://cosmograph.app/run/?data=https://cosmograph.app/data/data-links-example.csv&linkColorBy=avg-value
```

--------------------------------

### Graph Mode Edge List Example

Source: https://next.cosmograph.app/versions/v1-docs/app/how-to-use

This example shows the minimal required format for the graph mode, an edge list with 'source' and 'target' columns to define node connections.

```csv
source,target
node1,node2
node1,node3
```

--------------------------------

### Graph Mode Metadata with Color and Size

Source: https://next.cosmograph.app/versions/v1-docs/app/how-to-use

Example of a metadata file for graph mode, providing 'id', 'color', and 'size' for nodes. This allows for customization of node appearance.

```csv
id,color,size
node1,red,10
node2,green,20
node3,blue,30
```

--------------------------------

### Control Cosmograph Methods using useRef in React

Source: https://next.cosmograph.app/versions/v1-docs/lib/react

Illustrates how to use the useRef hook in React to get a reference to the Cosmograph instance and call its methods, such as zoomToNode. This is useful for imperative control over the graph after it mounts.

```jsx
import React, { useRef, useEffect } from 'react'
import { Cosmograph } from '@cosmograph/react'
 
export function GraphVisualization ({ nodes, links }) {
  // Create a ref to hold the Cosmograph instance
  const cosmographRef = useRef(null)
  // Access methods through .current ref
  const zoomToNode = () => cosmographRef.current?.zoomToNode({ id: 'node0' })
 
  return (
    <>
      <button onClick={zoomToNode}>Zoom to "node0"</button>
      <Cosmograph ref={cosmographRef} nodes={nodes} links={links} ... />
    </>
  )
}
```

--------------------------------

### JavaScript: Get Zoom Level

Source: https://next.cosmograph.app/versions/v1-docs/lib/cosmograph/zoom-and-view

Retrieves the current zoom level of the view as a numeric value.

```javascript
/**
 * Getter. Returns a numeric value that represents zoom level value of the view.
 * @returns {number} The current zoom level.
 */
function getZoomLevel() {
  // Implementation details for getting zoom level
  return currentZoomLevel;
}
```

--------------------------------

### Initialize CosmographProvider with Nodes and Links in React

Source: https://next.cosmograph.app/versions/v1-docs/lib/react

Demonstrates how to wrap a React application with CosmographProvider to provide Cosmograph instance and initial data (nodes and links) using React's Context API. This ensures data is accessible to child components.

```jsx
import { CosmographProvider, Cosmograph } from '@cosmograph/react'
import { nodes, links } from './path/to/data'
 
function App() {
  return (
    <CosmographProvider nodes={nodes} links={links}>
      <Cosmograph />
      {/* Your app components */}
    </CosmographProvider>
  )
}
```

--------------------------------

### Zoom and View Initialization Settings

Source: https://next.cosmograph.app/versions/v1-docs/lib/cosmograph/zoom-and-view

Configuration options for controlling the initial zoom level and view fitting behavior when the graph is first loaded.

```APIDOC
## Zoom and View Initialization Settings

### Description
These settings configure the initial state of the graph's zoom and viewport.

### Parameters
#### Request Body
- **initialZoomLevel** (number) - Optional - Sets the initial zoom level of the graph. Increase this value if the graph appears too small.
- **disableZoom** (boolean) - Optional - Disables zoom and drag events, preventing users from interacting with the graph canvas. Defaults to `false`.
- **fitViewOnInit** (boolean) - Optional - Determines whether to center and zoom the view to fit all nodes in the scene on initialization. Defaults to `true`.
- **fitViewDelay** (number) - Optional - Specifies a delay in milliseconds before fitting the view. Useful for allowing the layout to stabilize. Defaults to `250`.
- **fitViewByNodesInRect** (array) - Optional - Used when `fitViewOnInit` is `true`. Defines the corner coordinates `[[left, bottom], [right, top]]` of the rectangle that encloses the nodes in the scene.
```

--------------------------------

### Cosmograph Additional URL Parameters

Source: https://next.cosmograph.app/versions/v1-docs/app/sharing-graphs

Describes additional URL parameters for Cosmograph that control display features. 'showFps' enables an on-screen FPS counter, and 'useQuadtree' activates a specific algorithm for force calculation, noting potential GPU and OS compatibility issues.

```URL Parameters
showFps=true
useQuadtree=true
```

--------------------------------

### Zooming Methods

Source: https://next.cosmograph.app/versions/v1-docs/lib/cosmograph/zoom-and-view

Programmatic methods to control the zoom and view fitting of the graph after initialization.

```APIDOC
## Zooming Methods

### Description
These methods allow for dynamic control over the graph's zoom and view fitting.

### Methods
#### `fitView(duration = 250)`
**Description**: Centers and zooms the view to fit all nodes in the scene. The `duration` parameter specifies the animation time in milliseconds.

#### `fitViewByNodeIds(ids: string[], duration = 250)`
**Description**: Centers and zooms the view to fit specific nodes identified by their IDs. The `duration` parameter specifies the animation time in milliseconds.

#### `zoomToNode(node: N)`
**Description**: Zooms the view to focus on a specific node.

#### `setZoomLevel(value: number, duration = 0)`
**Description**: Zooms the view in or out to a specified zoom level. The `duration` parameter controls the transition time in milliseconds.

#### `getZoomLevel()`
**Description**: _Getter_. Returns the current zoom level of the view as a number.
```

--------------------------------

### Cosmograph URL Parameters for Simulation

Source: https://next.cosmograph.app/versions/v1-docs/app/sharing-graphs

Lists the URL parameters available for configuring simulation physics in Cosmograph. These parameters control aspects like gravity, repulsion, link strength, and simulation decay rate, with specified min/max ranges and step increments.

```URL Parameters
gravity: min: 0, max: 0.5, step: 0.01
repulsion: min: 0, max: 2, step: 0.01
repulsion-theta: min: 0.3, max: 2, step: 0.01
link-spring: min: 0, max: 2, step: 0.01
link-distance: min: 1, max: 20, step: 1
friction: min: 0, max: 1, step: 0.01
decay: min: 100, max: 10000, step: 1
```

--------------------------------

### Graph Mode with Time and Value Columns

Source: https://next.cosmograph.app/versions/v1-docs/app/how-to-use

An extended graph mode data file including 'time', 'source', 'target', and 'value' columns. The 'time' column enables timeline features, and 'value' can be used for link styling.

```csv
time,source,target,value
2/4/2022,node1,node2,2
2/5/2022,node1,node3,10
```

--------------------------------

### JavaScript: Zoom Event Callbacks

Source: https://next.cosmograph.app/versions/v1-docs/lib/cosmograph/zoom-and-view

Callbacks triggered during zoom and pan events. `onZoomStart` is called when the action begins, `onZoom` is called continuously during the action, and `onZoomEnd` is called when the action concludes. Each callback receives a D3 zoom event and a boolean indicating user interaction.

```javascript
/**
 * Triggered when zooming or panning starts.
 * @param {D3ZoomEvent<HTMLCanvasElement, undefined>} event - The D3 zoom event object.
 * @param {boolean} userDriven - True if the event was initiated by user interaction.
 */
function onZoomStart(event, userDriven) {
  // Handle zoom start event
}

/**
 * Continuously called during zooming or panning.
 * @param {D3ZoomEvent<HTMLCanvasElement, undefined>} event - The D3 zoom event object.
 * @param {boolean} userDriven - True if the event was initiated by user interaction.
 */
function onZoom(event, userDriven) {
  // Handle ongoing zoom event
}

/**
 * Called when zooming or panning ends.
 * @param {D3ZoomEvent<HTMLCanvasElement, undefined>} event - The D3 zoom event object.
 * @param {boolean} userDriven - True if the event was initiated by user interaction.
 */
function onZoomEnd(event, userDriven) {
  // Handle zoom end event
}
```

--------------------------------

### Configure Cosmograph Simulation Forces (ReactJS/TS)

Source: https://next.cosmograph.app/versions/v1-docs/lib/cosmograph/simulation

Demonstrates how to configure simulation forces for the Cosmograph component using ReactJS and TypeScript. This includes setting properties like simulationFriction, simulationLinkSpring, and simulationLinkDistance directly on the component or via a configuration object.

```jsx
<Cosmograph
  ...
  simulationFriction={0.1} 
  simulationLinkSpring={0.5} 
  simulationLinkDistance={2.0}
/>
```

```javascript
const config = {
  simulationFriction: 0.1,
  simulationLinkSpring: 0.5, 
  simulationLinkDistance: 2.0,
}
 
cosmograph.setConfig(config)
```

--------------------------------

### Cosmograph URL Parameters for Node Metadata

Source: https://next.cosmograph.app/versions/v1-docs/app/sharing-graphs

Specifies how to use metadata columns to control node size and color. 'nodeSize' is used for numeric columns to determine node size, and 'nodeColor' can be used for color, numeric, or text columns to set node color. Exact column names from the metadata must be used.

```URL Parameters
nodeSize=_node_value_
nodeColor=_node_color_
```

--------------------------------

### Control Cosmograph Methods using useCallback in React

Source: https://next.cosmograph.app/versions/v1-docs/lib/react

Demonstrates using the useCallback hook in React to access the Cosmograph instance and execute methods like focusNode immediately after the Cosmograph component mounts. This is suitable for actions that need to be triggered on mount.

```jsx
import React, { useRef, useEffect } from 'react'
import { Cosmograph } from '@cosmograph/react'
 
export function Example ({ nodes, links }) {
  // Create a ref to hold the Cosmograph instance
  const cosmographRef = useCallback((ref) => {
  // Focus node after Cosmograph mount
  ref?.focusNode({ id: 'node0' })
  }, [])
 
  return (
    <Cosmograph 
      ref={cosmographRef} 
      hoveredNodeRingColor={'red'}
      focusedNodeRingColor={'yellow'}
      ... 
    />  
  )
}
```

--------------------------------

### JavaScript: Fit View to All Nodes

Source: https://next.cosmograph.app/versions/v1-docs/lib/cosmograph/zoom-and-view

Centers and zooms the view to fit all nodes in the scene. The `duration` parameter controls the animation speed in milliseconds. Defaults to 250ms.

```javascript
/**
 * Centers and zooms the view to fit all nodes in the scene.
 * @param {number} [duration=250] - Duration of the animation in milliseconds.
 */
function fitView(duration = 250) {
  // Implementation details for fitting view
}
```

--------------------------------

### Zoom Event Callbacks

Source: https://next.cosmograph.app/versions/v1-docs/lib/cosmograph/zoom-and-view

Callbacks triggered during zoom and pan events, providing information about the event and user interaction.

```APIDOC
## Zoom Event Callbacks

### Description
These callbacks are invoked during zoom and pan operations, providing event details.

### Callbacks
#### `onZoomStart(event: D3ZoomEvent<HTMLCanvasElement, undefined>, userDriven: boolean)`
**Description**: Triggered when zooming or panning starts. Receives a D3 zoom event and a boolean indicating user interaction.

#### `onZoom(event: D3ZoomEvent<HTMLCanvasElement, undefined>, userDriven: boolean)`
**Description**: Continuously called during zooming or panning. Receives a D3 zoom event and a boolean indicating user interaction.

#### `onZoomEnd(event: D3ZoomEvent<HTMLCanvasElement, undefined>, userDriven: boolean)`
**Description**: Called when zooming or panning ends. Receives a D3 zoom event and a boolean indicating user interaction.
```

--------------------------------

### Embedding Mode Data with Coordinates

Source: https://next.cosmograph.app/versions/v1-docs/app/how-to-use

The required format for embedding mode, a file with 'id', 'x', and 'y' columns to define node positions.

```csv
id,x,y
node1,0.2,0.5 
node2,0.7,0.3
node3,0.4,0.8
```

--------------------------------

### Graph Mode Metadata with Type and Time

Source: https://next.cosmograph.app/versions/v1-docs/app/how-to-use

An expanded metadata file including 'id', 'color', 'size', 'type', and 'time' for nodes. This enables node categorization and timeline data for nodes.

```csv
id,color,size,type,time
node1,red,10,bird,2/4/2022
node2,green,20,plant,2/5/2022
node3,blue,30,bird,2/6/2022
```

--------------------------------

### Cosmograph URL Parameters for Link Appearance

Source: https://next.cosmograph.app/versions/v1-docs/app/sharing-graphs

Defines how to control link width and color using URL parameters. 'linkWidthBy' and 'linkColorBy' can be set to 'records' to size/color links based on the count of data records between nodes. For numeric columns, 'linkWidthBy' and 'linkColorBy' support 'sum-_value_' and 'avg-_value_' for sizing based on the sum or average of values in the specified column. 'linkColorBy' also supports using the raw values from a color column.

```URL Parameters
linkWidthBy=default
linkColorBy=default
linkWidthScale=0.1 to 2
linkColorBy=records
linkWidthBy=records
linkWidthBy=sum-_value_
linkWidthBy=avg-_value_
linkColorBy=<columnName>
```

--------------------------------

### JavaScript: Fit View by Node IDs

Source: https://next.cosmograph.app/versions/v1-docs/lib/cosmograph/zoom-and-view

Centers and zooms the view to fit a specific set of nodes identified by their IDs. The `duration` parameter controls the animation speed in milliseconds. Defaults to 250ms.

```javascript
/**
 * Centers and zooms the view to fit nodes by the list of passed ids.
 * @param {string[]} ids - An array of node IDs to fit.
 * @param {number} [duration=250] - Duration of the animation in milliseconds.
 */
function fitViewByNodeIds(ids, duration = 250) {
  // Implementation details for fitting view by node IDs
}
```

--------------------------------

### JavaScript: Set Zoom Level

Source: https://next.cosmograph.app/versions/v1-docs/lib/cosmograph/zoom-and-view

Programmatically sets the zoom level of the view. The `value` parameter specifies the desired zoom level, and `duration` controls the transition time in milliseconds. Defaults to 0ms (instantaneous).

```javascript
/**
 * Zooms the view in or out to the specified zoom level.
 * @param {number} value - The target zoom level.
 * @param {number} [duration=0] - Duration of the zoom transition in milliseconds.
 */
function setZoomLevel(value, duration = 0) {
  // Implementation details for setting zoom level
}
```

--------------------------------

### JavaScript: Zoom to Specific Node

Source: https://next.cosmograph.app/versions/v1-docs/lib/cosmograph/zoom-and-view

Zooms the view to focus on a specific node. The node object is passed as an argument.

```javascript
/**
 * Zooms the view to a specific node.
 * @param {N} node - The node object to zoom to.
 */
function zoomToNode(node) {
  // Implementation details for zooming to a node
}
```

--------------------------------

### Access Cosmograph Instance and Data with useCosmograph Hook in React

Source: https://next.cosmograph.app/versions/v1-docs/lib/react

Shows how to use the useCosmograph hook within a React component to access the Cosmograph instance, nodes, and links data. This hook must be used within a component that is a descendant of CosmographProvider.

```jsx
import { useCosmograph } from'@cosmograph/react'
 
function MyComponent() {
  const { cosmograph, nodes, links } = useCosmograph()
 
  // Now you can access cosmograph and data in your component
 
  return (
    // Your component JSX
  )
}
```
Tokens:
Raw