plebeiangraphlibrary 2.0.1 → 2.1.2

package/Build/HelperClasses/ColorHelper.d.ts

@@ -0,0 +1,21 @@
+/**
+ *
+ * Converts Rgb to hex
+ *
+ * @param r red value
+ * @param g green value
+ * @param b blue value
+ * @returns the hex value
+ */
+declare function rgbToHex(r: number, g: number, b: number): string;
+/**
+ *
+ * @param hex the hex color code
+ * @returns RGB values as r, g, b values
+ */
+declare function hexToRgb(hex: string | number): {
+    r: number;
+    g: number;
+    b: number;
+} | null;
+export { rgbToHex, hexToRgb };

package/Build/HelperClasses/GeometryHelpers.d.ts

@@ -0,0 +1,31 @@
+import { default as Point } from './Point';
+import { default as Line } from './Line';
+/**
+ * Creates a line based on the number of divisons
+ *
+ * @param start the start point
+ * @param end the end point
+ * @param divisions the number of divisions
+ * @returns the line object
+ */
+declare function line_from_start_end_divisions(start: Point, end: Point, divisions: number): Line;
+/**
+ * Divides the line into a number of divisions based on distance
+ * @param start - the start point
+ * @param end - the end point
+ * @param distance - the distance at which this line must be divided
+ * @returns A line object with the right number of points
+ */
+declare function line_from_start_end_distance(start: Point, end: Point, distance: number): Line;
+/**
+ * Calculates the centroid of an array of points
+ * @param points An array of points
+ * @returns the central point of the array of points
+ */
+declare function centroid(points: Point[]): Point;
+declare const _default: {
+    line_from_start_end_divisions: typeof line_from_start_end_divisions;
+    line_from_start_end_distance: typeof line_from_start_end_distance;
+    centroid: typeof centroid;
+};
+export default _default;

package/Build/HelperClasses/GraphConstructors.d.ts

@@ -0,0 +1,12 @@
+import { default as Graph } from '../Core/Graph';
+/**
+ * construct a graph based on an edge list and node list
+ * @param nodes nodes as a list
+ * @param edges edges as a list
+ * @returns A graph that was construct from the list of nodes and edges
+ */
+declare function ConstructGraphNodeEdgesList(nodes: any[], edges: any[]): Promise<Graph>;
+declare const _default: {
+    ConstructGraphNodeEdgesList: typeof ConstructGraphNodeEdgesList;
+};
+export default _default;

package/Build/HelperClasses/Line.d.ts

@@ -0,0 +1,12 @@
+import { default as Point } from './Point';
+interface Line {
+    points: Point[];
+}
+declare class Line {
+    /**
+     * Constructs a line from an array of points
+     * @param points an array of points
+     */
+    constructor(points: Point[]);
+}
+export default Line;

package/Build/HelperClasses/Point.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Minimal 3D point shape. Use for typing position objects (e.g. from custom layout).
+ * The Point class implements this interface.
+ */
+export type PointLike = {
+    x: number;
+    y: number;
+    z: number;
+};
+interface Point extends PointLike {
+}
+declare class Point {
+    /**
+     * Constructs a point based on the x y z values
+     * @param x x value
+     * @param y y value
+     * @param z z value
+     */
+    constructor(x: number, y: number, z: number);
+    /**
+     * Displaces a point - note this method moves the existing point
+     * @param Point - Displacement vector (used as a point)
+     */
+    translate(Point: Point): void;
+}
+export default Point;

package/Build/HelperClasses/Utilities.d.ts

@@ -0,0 +1,45 @@
+import { default as Point } from './Point';
+/**
+ * calculate the average of an array of numberss
+ * @param arr an array of number whose average has to be calculated
+ * @returns the average
+ */
+declare function calculateAverage(arr: number[]): number;
+/**
+ * Calculate the distance betweeen two points
+ * @param p1 the first point
+ * @param p2 the second point
+ * @returns the distance between the points
+ */
+declare function calculateDistance(p1: Point, p2: Point): number;
+/**
+ * Calculate the squared distance between two points
+ * @param p1 the first point
+ * @param p2 the second point
+ * @returns the squared distance between the two points
+ */
+declare function calculateSquaredDistance(p1: Point, p2: Point): number;
+/**
+ * get a random subset of something from a array of things must provide the number of things we want from that array
+ * @param arr the array from which the subset has to be made
+ * @param n number of items to select
+ * @returns a new array made up of a random sample from the original array
+ */
+declare function getRandomSubset(arr: any[], n: number): any[];
+/**
+ * This is a super useful method to get a random number of edges or something that you would like to draw
+ * this is primarily done because there are way too many edges sometimes and and the number of edges is really
+ * What slows the whole rendering process down
+ * @param map - the map that youd like to reduce
+ * @param n - the fraction of items that youd like to return from this map
+ * @returns A reduced map with a fractio of those many entries
+ */
+declare function getRandomSubset_map(map: Map<number, any>, n: number): Map<any, any>;
+declare const _default: {
+    calculateAverage: typeof calculateAverage;
+    calculateDistance: typeof calculateDistance;
+    calculateSquaredDistance: typeof calculateSquaredDistance;
+    getRandomSubset: typeof getRandomSubset;
+    getRandomSubset_map: typeof getRandomSubset_map;
+};
+export default _default;

package/Build/HelperClasses/index.d.ts

@@ -0,0 +1,3 @@
+export { default as Constructors } from './GraphConstructors';
+export { default as Geometry } from './GeometryHelpers';
+export { default as Utilities } from './Utilities';

package/Build/Hierarchy/KDDistanceStrategy.d.ts

@@ -0,0 +1,8 @@
+import { default as Graph } from '../Core/Graph';
+import { ClusterResult, ClusterByDistanceOptions } from './types';
+/**
+ * Cluster strategy that groups nodes by Euclidean distance using a KD-tree.
+ */
+export declare function createKDDistanceStrategy(): {
+    cluster: (graph: Graph, options: ClusterByDistanceOptions) => ClusterResult;
+};

package/Build/Hierarchy/KDTree.d.ts

@@ -0,0 +1,10 @@
+import { default as Point } from '../HelperClasses/Point';
+export interface PointWithId {
+    point: Point;
+    nodeId: number;
+}
+/**
+ * Find all point IDs within `radius` of each point in `items`.
+ * Returns Map<nodeId, nodeIds[] within radius (including self)>.
+ */
+export declare function pointsWithinRadius(items: PointWithId[], radius: number): Map<number, number[]>;

package/Build/Hierarchy/buildSimplifiedGraph.d.ts

@@ -0,0 +1,7 @@
+import { default as Graph } from '../Core/Graph';
+import { ClusterResult } from './types';
+/**
+ * Build a new graph where each cluster is one node (at its centroid) and edges
+ * between clusters are merged (one edge per cluster pair; optional weight/count in data).
+ */
+export declare function buildSimplifiedGraph(originalGraph: Graph, clusterResult: ClusterResult): Promise<Graph>;

package/Build/Hierarchy/index.d.ts

@@ -0,0 +1,29 @@
+import { default as Graph } from '../Core/Graph';
+import { ClusterResult, ClusterStrategy, ClusterByDistanceOptions } from './types';
+import { createKDDistanceStrategy } from './KDDistanceStrategy';
+import { buildSimplifiedGraph } from './buildSimplifiedGraph';
+/**
+ * Cluster the graph by distance (KD-tree based) and return a simplified graph.
+ * Nodes within `distanceThreshold` are merged; super-nodes are placed at cluster centroids.
+ *
+ * @param graph - The graph to cluster
+ * @param options - { distanceThreshold: number }
+ * @returns A new graph with one node per cluster and aggregated edges between clusters
+ */
+declare function clusterByDistance(graph: Graph, options: ClusterByDistanceOptions): Promise<Graph>;
+/**
+ * Cluster the graph using a custom strategy and return a simplified graph.
+ *
+ * @param graph - The graph to cluster
+ * @param strategy - A ClusterStrategy implementation
+ * @param options - Strategy-specific options
+ * @returns A new graph with one node per cluster and aggregated edges
+ */
+declare function clusterByStrategy(graph: Graph, strategy: ClusterStrategy, options: Record<string, unknown>): Promise<Graph>;
+export type { ClusterResult, ClusterStrategy, ClusterByDistanceOptions };
+export { createKDDistanceStrategy, buildSimplifiedGraph };
+declare const _default: {
+    clusterByDistance: typeof clusterByDistance;
+    clusterByStrategy: typeof clusterByStrategy;
+};
+export default _default;

package/Build/Hierarchy/types.d.ts

@@ -0,0 +1,33 @@
+import { default as Graph } from '../Core/Graph';
+import { default as Point } from '../HelperClasses/Point';
+/**
+ * Options for distance-based clustering.
+ */
+export interface ClusterByDistanceOptions {
+    /** Maximum distance between two nodes for them to be in the same cluster. */
+    distanceThreshold: number;
+}
+/**
+ * Result of a clustering step: maps each node ID to its cluster ID.
+ */
+export interface ClusterResult {
+    /** Map from original node ID to cluster ID (integer). */
+    nodeToCluster: Map<number, number>;
+    /** Map from cluster ID to centroid position (e.g. for super-node placement). */
+    clusterCentroids: Map<number, Point>;
+    /** List of unique cluster IDs. */
+    clusterIds: number[];
+}
+/**
+ * Strategy interface for hierarchical node combining.
+ * Implementations (e.g. KD-tree distance-based, or future class-based) produce a clustering.
+ */
+export interface ClusterStrategy {
+    /**
+     * Compute clustering of graph nodes.
+     * @param graph - The graph to cluster
+     * @param options - Strategy-specific options
+     * @returns Assignment of each node to a cluster and cluster centroids
+     */
+    cluster(graph: Graph, options: Record<string, unknown>): ClusterResult;
+}

package/Build/MatrixHelpers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Helpers for matrix/vector math in the browser. Work with Float32Arrays
+ * returned by get_adjacency_matrix() and simulation positions.
+ */
+/**
+ * Matrix-vector multiply: out = A * x (row-major n×n matrix A).
+ */
+export declare function matrixVectorMultiply(A: Float32Array, n: number, x: Float32Array, out: Float32Array): void;
+/**
+ * Normalize vector x in-place by its 2-norm. If norm is 0, leaves x unchanged.
+ */
+export declare function normalizeVector(x: Float32Array): void;

package/Build/Models/ErdosRenyiModel.d.ts

@@ -0,0 +1,13 @@
+import { default as Graph } from '../Core/Graph';
+/**
+ * The G ( n , p ) G(n,p) model, a graph is constructed by connecting labeled nodes randomly. Each edge is included in the graph with probability p p, independently from every other edge.
+ * https://en.wikipedia.org/wiki/Erd%C5%91s%E2%80%93R%C3%A9nyi_model
+ * @param n Number of nodes
+ * @param p Probability of two edges to eb connected
+ * @returns A Erdos Reyni graph
+ */
+declare function GenerateErdosReyni_n_p(n: number, p: number): Promise<Graph>;
+declare const _default: {
+    GenerateErdosReyni_n_p: typeof GenerateErdosReyni_n_p;
+};
+export default _default;

package/Build/Models/index.d.ts

@@ -0,0 +1 @@
+export { default as Models } from './ErdosRenyiModel';

package/Build/SampleData/DataLoader.d.ts

@@ -0,0 +1,49 @@
+import { default as Graph } from '../Core/Graph';
+/**
+ * Parse (sgd)²-style edge list text (one "i j" per line; lines starting with # or empty are skipped).
+ * Node IDs can be 0-based or 1-based. Returns a graph with nodes at origin (layout will set positions).
+ * Format used by the s_gd2 reference implementation from Imperial College London.
+ * @see https://github.com/jxz12/s_gd2
+ */
+declare function LoadGraphFromEdgeListText(edgeListText: string): Promise<Graph>;
+/**
+ *
+ * @returns the raw ZKC dataset
+ */
+declare function LoadZKC(): Promise<Graph>;
+/**
+ *
+ * @returns the ZKC dataset with the positions simulated beforehand
+ */
+declare function LoadZKCSimulated(): Promise<Graph>;
+/**
+ * Result of loading a mesh from OBJ: graph (vertices = nodes, face edges = graph edges) and original 3D positions.
+ * positions[i*3], positions[i*3+1], positions[i*3+2] are x,y,z for node id i (0-based).
+ */
+export interface LoadGraphFromObjResult {
+    graph: Graph;
+    /** Flat array of length n*3: x,y,z for each node in order of node id 0..n-1 */
+    positions: Float32Array;
+}
+/**
+ * Parse OBJ mesh: "v x y z" lines and "f i j k" (or "f i j k l" for quads) lines.
+ * Builds a graph whose nodes are mesh vertices (ids 0..n-1) and edges are unique mesh edges from faces.
+ * Returns the graph and original vertex positions so they can be used as initial layout (e.g. for 3D stress).
+ * OBJ vertex indices are 1-based; we use 0-based node ids.
+ * @see e.g. Stanford Bunny https://graphics.stanford.edu/~mdfisher/Data/Meshes/bunny.obj
+ */
+declare function LoadGraphFromObjText(objText: string): Promise<LoadGraphFromObjResult>;
+/**
+ * Load the DWT 1005 graph from the paper (1005 nodes, adjacency-list format).
+ * Same structural graph used in the 2D stress layout reference.
+ * @see dwt_1005.ts
+ */
+declare function LoadDwt1005(): Promise<Graph>;
+declare const _default: {
+    LoadZKC: typeof LoadZKC;
+    LoadZKCSimulated: typeof LoadZKCSimulated;
+    LoadGraphFromEdgeListText: typeof LoadGraphFromEdgeListText;
+    LoadGraphFromObjText: typeof LoadGraphFromObjText;
+    LoadDwt1005: typeof LoadDwt1005;
+};
+export default _default;

package/Build/SampleData/ZKC.d.ts

@@ -0,0 +1,5 @@
+declare const zkc: {
+    nodes: number[];
+    edges: number[][];
+};
+export { zkc };

package/Build/SampleData/ZKC_simulated.d.ts

@@ -0,0 +1,10 @@
+declare const zkc_simulated: {
+    nodes: {
+        id: number;
+        px: number;
+        py: number;
+        member: number;
+    }[];
+    edges: number[][];
+};
+export { zkc_simulated };