@cosmos.gl/graph 2.2.1 → 2.3.0

package/src/stories/3. api-reference.mdx

@@ -43,6 +43,13 @@ graph.setPointColors(new Float32Array([
 graph.render();
 ```
 
+### <a name="get_point_colors" href="#get_point_colors">#</a> graph.<b>getPointColors</b>()
+
+This method retrieves the current colors of the graph points that were previously set using `setPointColors`.
+
+**Returns:** A Float32Array representing the colors of points in the format `[r1, g1, b1, a1, r2, g2, b2, a2, ..., rN, gN, bN, aN]`, where each color is in RGBA format. Each set of four values (`r`, `g`, `b`, `a`) represents the color of a single point. Returns an empty Float32Array if no point colors are set.
+
+The returned array contains the processed point colors used for rendering, including any default values that were applied during processing.
 
 ### <a name="set_point_sizes" href="#set_point_sizes">#</a> graph.<b>setPointSizes</b>(<i>pointSizes</i>)
 
@@ -60,6 +67,14 @@ graph.render();
 
 This example sets the size of the first point to 10, the second point to 20, and the third point to 30.
 
+### <a name="get_point_sizes" href="#get_point_sizes">#</a> graph.<b>getPointSizes</b>()
+
+This method retrieves the current sizes of the graph points that were previously set using `setPointSizes`.
+
+**Returns:** A Float32Array representing the sizes of points in the format `[size1, size2, ..., sizeN]`, where each `size` value corresponds to the size of the point at the same index in the graph's data. Returns an empty Float32Array if no point sizes are set.
+
+The returned array contains the processed point sizes used for rendering, including any default values that were applied during processing.
+
 ### <a name="set_links" href="#set_links">#</a> graph.<b>setLinks</b>(<i>links</i>)
 
 This method sets the links (connections) between points in a cosmos.gl graph.
@@ -105,6 +120,14 @@ graph.render();
 
 In this example, the `linkColors` array contains three sets of four elements, each representing the RGBA color for a single link. The first set `[1, 0, 0, 1]` sets the first link to red, the second set `[0, 1, 0, 1]` sets the second link to green, and the third set `[0, 0, 1, 1]` sets the third link to blue.
 
+### <a name="get_link_colors" href="#get_link_colors">#</a> graph.<b>getLinkColors</b>()
+
+This method retrieves the current colors of the graph links that were previously set using `setLinkColors`.
+
+**Returns:** A Float32Array representing the colors of links in the format `[r1, g1, b1, a1, r2, g2, b2, a2, ..., rN, gN, bN, aN]`, where each color is in RGBA format. Each set of four values (`r`, `g`, `b`, `a`) represents the color of a single link. Returns an empty Float32Array if no link colors are set.
+
+The returned array contains the processed link colors used for rendering, including any default values that were applied during processing.
+
 ### <a name="set_link_widths" href="#set_link_widths">#</a> graph.<b>setLinkWidths</b>(<i>linkWidths</i>)
 
 This method sets the widths for the graph links.
@@ -119,6 +142,14 @@ graph.render();
 
 In this example, the `linkWidths` array contains three numerical values. The first value `1` sets the width of the first link, the second value `2` sets the width of the second link, and the third value `3` sets the width of the third link.
 
+### <a name="get_link_widths" href="#get_link_widths">#</a> graph.<b>getLinkWidths</b>()
+
+This method retrieves the current widths of the graph links that were previously set using `setLinkWidths`.
+
+**Returns:** A Float32Array representing the widths of links in the format `[width1, width2, ..., widthN]`, where each `width` value corresponds to the width of the link at the same index in the graph's data. Returns an empty Float32Array if no link widths are set.
+
+The returned array contains the processed link widths used for rendering, including any default values that were applied during processing.
+
 ### <a name="set_link_arrows" href="#set_link_arrows">#</a> graph.<b>setLinkArrows</b>(<i>linkArrows</i>)
 
 This method sets the arrows for the graph links.
@@ -135,7 +166,6 @@ graph.render();
 
 In this example, the `linkArrows` array contains three boolean values. The first value `true` sets an arrow on the first link, the second value `false` leaves the second link without an arrow, and the third value `true` sets an arrow on the third link.
 
-
 ### <a name="set_link_strengths" href="#set_link_strengths">#</a> graph.<b>setLinkStrength</b>(<i>linkStrength</i>)
 
 This method sets the strength of the graph links.
@@ -184,7 +214,6 @@ This method sets the force strength coefficients for clustering points in the gr
   ```
   This example sets the force coefficient for point 0 to 1, point 1 to 0.4, and point 2 to 0.3.
 
-
 ### <a name="render" href="#render">#</a> graph.<b>render</b>([<i>simulationAlpha</i>])
 
 The `render` method renders the graph and, optionally, controls the initial energy of the simulation.
@@ -220,7 +249,6 @@ This method centers and zooms the view to fit all points within the scene.
 
 The `fitView` method is particularly useful when you want to ensure that all points in the graph are visible within the currently displayed viewport. By fitting the view to include all points, users can get a complete overview of the entire graph.
 
-
 ### <a name="fit_view_by_point_indices" href="#fit_view_by_point_indices">#</a> graph.<b>fitViewByPointIndices</b>(<i>indices</i>, [<i>duration</i>], [<i>padding</i>])
 
 The `fitViewByPointIndices` method centers and zooms the view to fit the points specified by their <i>indices</i> in the scene, with an optional animation <i>duration</i> and <i>padding</i>.
@@ -294,24 +322,20 @@ This method selects a point in the graph based on its index.
 * **`index`** (Number): The index of the point to be selected.
 * **`selectAdjacentPoints`** (Boolean, optional): If set to `true`, adjacent points to the specified index will also be selected. The default value is `false`.
 
-
 ### <a name="select_points_by_indices" href="#select_points_by_indices">#</a> graph.<b>selectPointsByIndices</b>(<i>indices</i>)
 
 This method selects multiple points in the graph based on their indices.
 
 * **`indices`** (Array): An array of numbers representing the indices of the points to be selected.
 
-
 ### <a name="unselect_points" href="#unselect_points">#</a> graph.<b>unselectPoints</b>()
 
 This method unselects all currently selected points in the graph.
 
-
 ### <a name="get_selected_indices" href="#get_selected_indices">#</a> graph.<b>getSelectedIndices</b>()
 
 This method returns an array of indices corresponding to the currently selected points in the graph.
 
-
 ### <a name="get_adjacent_indices" href="#get_adjacent_indices">#</a> graph.<b>getAdjacentIndices</b>(<i>index</i>)
 
 This method returns an array of indices that are adjacent to a specific point in the graph, identified by its <i>index</i>.
@@ -324,28 +348,24 @@ This method method is used to convert X and Y point coordinates from the space c
 
 * **`coordinates`** (Array): An array of two numbers in the format `[x, y]`, representing the X and Y coordinates in the space coordinate system.
 
-
 ### <a name="screen_to_space_position" href="#screen_to_space_position">#</a> graph.<b>screenToSpacePosition</b>(<i>coordinates</i>)
 
 This` method converts X and Y point coordinates from the screen coordinate system (which is used for rendering the graph on the display) to the space coordinate system (which is typically used for graph data).
 
 * **`coordinates`** (Array): An array of two numbers in the format `[x, y]`, representing the X and Y coordinates in the screen coordinate system.
 
-
 ### <a name="space_to_screen_radius" href="#space_to_screen_radius">#</a> graph.<b>spaceToScreenRadius</b>(<i>radius</i>)
 
 This method is used to convert a <i>radius</i> value from the space coordinate system (which is typically used for graph data) to the screen coordinate system (which is used for rendering the graph on the display).
 
 * **`radius`** (Number): The radius value in the space coordinate system that needs to be converted to the screen coordinate system.
 
-
 ### <a name="get_point_radius_by_index" href="#get_point_radius_by_index">#</a> graph.<b>getPointRadiusByIndex</b>(<i>index</i>)
 
 This method retrieves the radius of a point in the graph identified by its <i>index</i>.
 
 * **`index`** (Number): The index of the point for which the radius is to be retrieved.
 
-
 ### <a name="track_point_positions_by_indices" href="#track_point_positions_by_indices">#</a> graph.<b>trackPointPositionsByIndices</b>(<i>indices</i>)
 
 This method allows you to monitor the coordinates of specific points over time. This is particularly useful for observing dynamic changes in the positions of points during the simulation. The positions of the tracked points are updated on each tick of the cosmos.gl simulation.
@@ -354,7 +374,6 @@ This method allows you to monitor the coordinates of specific points over time.
 
 To retrieve the current positions of the tracked points, use the [**getTrackedPointPositionsMap**](#get_tracked_point_positions_map) method, which returns a `Map` object containing the point coordinates.
 
-
 ### <a name="get_tracked_point_positions_map" href="#get_tracked_point_positions_map">#</a> graph.<b>getTrackedPointPositionsMap</b>()
 
 This method retrieves the current positions of points that are being tracked. This method is particularly useful for monitoring the changing coordinates of specific points over time during the simulation. Using this method in conjunction with the [**trackPointPositionsByIndices**](#track_point_positions_by_indices) method allows for dynamic tracking and retrieval of point positions.
@@ -363,6 +382,15 @@ This method retrieves the current positions of points that are being tracked. Th
 
 * A `Map` object where the keys are the indices of the tracked points and the values are their corresponding X and Y coordinates in the form of a `[number, number]` array.
 
+### <a name="get_tracked_point_positions_array" href="#get_tracked_point_positions_array">#</a> graph.<b>getTrackedPointPositionsArray</b>()
+
+This method retrieves the current positions of points that are being tracked as an array for optimized performance. This method provides the same functionality as `getTrackedPointPositionsMap` but returns data as a flat array instead of a Map object, which can be more efficient for applications that need to process large numbers of tracked points.
+
+The positions are returned in the same order as the indices provided to [**trackPointPositionsByIndices**](#track_point_positions_by_indices).
+
+**Returns:**
+
+* An array of numbers representing the X and Y coordinates of tracked points in the format `[x1, y1, x2, y2, ..., xn, yn]`, where each pair corresponds to a tracked point in the order they were specified for tracking. Returns an empty array if no points are being tracked.
 
 ### <a name="get_sampled_point_positions_map" href="#get_sampled_point_positions_map">#</a> graph.<b>getSampledPointPositionsMap</b>()
 
@@ -374,6 +402,21 @@ The number of sampled points is determined by the `pointSamplingDistance` [confi
 
 The sample aims to distribute points evenly across the visible area.
 
+### <a name="get_sampled_points" href="#get_sampled_points">#</a> graph.<b>getSampledPoints</b>()
+
+This method provides an optimized way to retrieve both point indices and positions for sampled points that are currently visible on the screen. Unlike `getSampledPointPositionsMap`, this method returns the data as arrays rather than a Map.
+
+The number of sampled points is determined by the `pointSamplingDistance` [configuration property](../?path=/docs/configuration--docs). This property controls the density of the sampled points:
+* A higher value for `pointSamplingDistance` results in fewer sampled points.
+* A lower value results in more sampled points.
+
+The sample aims to distribute points evenly across the visible area.
+
+**Returns:**
+
+* An object containing:
+  - **`indices`**: Array of point indices for the sampled points
+  - **`positions`**: Flat array of coordinates in the format `[x1, y1, x2, y2, ..., xn, yn]`, where the coordinates correspond to the points at the same index positions in the `indices` array.
 
 ### <a name="start" href="#start">#</a> graph.<b>start</b>([<i>alpha</i>])
 
@@ -381,22 +424,18 @@ Starts the simulation with an optional <i>alpha</i> parameter, which controls th
 
 * **`alpha`** (Number, optional): A number between `0` and `1` representing the initial energy of the simulation. The default value is `1` if not provided. A higher `alpha` value results in more initial energy for the simulation.
 
-
 ### <a name="pause" href="#pause">#</a> graph.<b>pause</b>()
 
 Pauses the current simulation in the graph.
 
-
 ### <a name="restart" href="#restart">#</a> graph.<b>restart</b>()
 
 Restarts the current simulation in the graph.
 
-
 ### <a name="step" href="#step">#</a> graph.<b>step</b>()
 
 Renders a single frame of the simulation and pauses the simulation if it was active.
 
-
 ### <a name="destroy" href="#destroy">#</a> graph.<b>destroy</b>()
 
 Destroys the current cosmos.gl instance.
@@ -405,7 +444,6 @@ Destroys the current cosmos.gl instance.
 
 Creates a new cosmos.gl instance.
 
-
 ### <a name="flatten" href="#flatten">#</a> graph.<b>flatten</b>(<i>pointPositions</i>)
 
 This method converts an array of tuple positions into a single, flat array containing all coordinates sequentially.
@@ -418,7 +456,6 @@ This method converts a flat array of point positions into an array of tuple pair
 
 * **`pointPositions`** (Array): A flat array of numbers representing the x and y coordinates of points sequentially. For example, `[x1, y1, x2, y2, ..., xn, yn]`.
 
-
 ### <a name="get_point_positions" href="#get_point_positions">#</a> graph.<b>getPointPositions</b>()
 
 This method retrieves the current X and Y coordinates of all points in the graph as an array of numbers. The returned array is in the same order as the point positions were added to the graph.

package/src/stories/clusters/worm.ts

@@ -6,7 +6,7 @@ import { generateMeshData } from '../generate-mesh-data'
 export const worm = (): {graph: Graph; div: HTMLDivElement} => {
   const { pointPositions, pointColors, links, linkColors, pointClusters } = generateMeshData(100, 100, 1000, 1.0)
 
-  return createCosmos({
+  const { div, graph } = createCosmos({
     simulationGravity: 0.5,
     simulationRepulsion: 1,
     simulationLinkSpring: 1,
@@ -15,5 +15,26 @@ export const worm = (): {graph: Graph; div: HTMLDivElement} => {
     pointClusters,
     links,
     linkColors,
+    onSimulationTick: () => {
+      const currentPointColors = graph.getPointColors()
+      const newPointColors = new Float32Array(currentPointColors.length)
+      for (let i = 0; i < currentPointColors.length / 4; i++) {
+        if (i === 0) {
+          newPointColors[i * 4] = currentPointColors[currentPointColors.length - 4] as number
+          newPointColors[i * 4 + 1] = currentPointColors[currentPointColors.length - 3] as number
+          newPointColors[i * 4 + 2] = currentPointColors[currentPointColors.length - 2] as number
+          newPointColors[i * 4 + 3] = currentPointColors[currentPointColors.length - 1] as number
+        } else {
+          newPointColors[i * 4] = currentPointColors[(i - 1) * 4] as number
+          newPointColors[i * 4 + 1] = currentPointColors[(i - 1) * 4 + 1] as number
+          newPointColors[i * 4 + 2] = currentPointColors[(i - 1) * 4 + 2] as number
+          newPointColors[i * 4 + 3] = currentPointColors[(i - 1) * 4 + 3] as number
+        }
+      }
+      graph.setPointColors(newPointColors)
+      graph.render()
+    },
   })
+
+  return { div, graph }
 }

package/src/variables.ts

@@ -1,9 +1,11 @@
 export const defaultPointColor = '#b3b3b3'
 export const defaultGreyoutPointOpacity = undefined
 export const defaultGreyoutPointColor = undefined
+export const defaultPointOpacity = 1.0
 export const defaultPointSize = 4
 export const defaultLinkColor = '#666666'
 export const defaultGreyoutLinkOpacity = 0.1
+export const defaultLinkOpacity = 1.0
 export const defaultLinkWidth = 1
 export const defaultBackgroundColor = '#222222'