import { Selection as MosaicSelection } from '@uwdata/mosaic-core'; import { CosmographConfig } from "./config"; import { ColorAccessorFn, CosmographData, SizeAccessorFn, CosmographPointInput, CosmographLinkInput } from "./config/interfaces/data"; import { PointColorStrategyType } from "./strategies/point-color"; import { PointSizeStrategyType } from "./strategies/point-size"; import { MosaicVgplotComponent } from "./modules/mosaic-vgplot/compenent-wrapper"; import { LinkColorStrategyType } from './strategies/link-color'; import { LinkWidthStrategyType } from './strategies/link-width'; /** * Public Cosmograph API interface. */ export interface ICosmograph { /** * Statistical information about current points and links in the graph. * * @returns An object containing the count of points and links and summaries of points and links data. * * Summaries include: * - Column names and types * - Aggregates for each column (count, min, max, approx_unique, avg, std, q25, q50, q75) * - Percentage of NULL values */ readonly stats: CosmographStats; /** * Gets the index of the currently focused point. * * @returns The index of the focused point, or `undefined` if no point is focused. */ readonly focusedPointIndex: number | undefined; /** * Gets the mapping of cluster values to their auto-generated indices and counts of items in each cluster. * * @remarks * If {@link CosmographConfig.pointClusterByFn pointClusterByFn} is provided, keys of map will be values of {@link CosmographConfig.pointClusterBy pointClusterBy} after applying {@link CosmographConfig.pointClusterByFn pointClusterByFn}. */ readonly clusterMapping: Map; /** * Gets the crossfilter sets for links, points, and their intersection. * * @returns An object containing the crossfiltered indices Sets. */ readonly crossfilter: { links: Set; points: Set; intersection: Set; }; /** * Provides the active point color strategy for the Cosmograph instance. * @returns The active point color strategy. */ readonly activePointColorStrategy: PointColorStrategyType; /** * Provides the active point size strategy for the Cosmograph instance. * @returns The active point size strategy. */ readonly activePointSizeStrategy: PointSizeStrategyType; /** * Provides the active link color strategy for the Cosmograph instance. * @returns The active link color strategy. */ readonly activeLinkColorStrategy: LinkColorStrategyType; /** * Provides the active link width strategy for the Cosmograph instance. * @returns The active link width strategy. */ readonly activeLinkWidthStrategy: LinkWidthStrategyType; /** * Provides the name of the links table used by the Cosmograph instance. * @returns The name of the links table. */ readonly linksTableName: string; /** * Provides the name of the points table used by the Cosmograph instance. * @returns The name of the points table. */ readonly pointsTableName: string; /** * A value that gives information about the running simulation progress. * @returns The current progress of the simulation, where 0 represents the start of the simulation and 1 represents the end, or `undefined` if not available. */ readonly progress: number | undefined; /** * Gets a boolean indicating whether the simulation is currently running. * @returns `true` if the simulation is running, `false` if it is not running, or `undefined` if the information is not available. */ readonly isSimulationRunning: boolean | undefined; /** * Gets a boolean indicating if a simulation can run for the current graph configuration and data. * @remarks Determined on graph init/rebuild. Based on `enableSimulation` config (if set), or defaults to `true` if links exist or points lack layout (pointXBy/pointYBy). * * The value updates upon graph initialization or rebuild (e.g., after `setConfig` or data loading). * @returns `true` if a simulation can run, `false` otherwise. */ readonly isSimulationAvailable: boolean; /** * Gets the point degrees for the current graph. * @returns The point degrees as an array of their degree values in the order they were sent to Cosmograph, or `undefined` if not available. */ readonly pointDegrees: number[] | undefined; /** * Gets the point directions for the current graph. * @remarks * The point directions are calculated based on the in-degree and out-degree of the points. * The value is 0 if the point has only an outgoing link (source), 1 if it has both incoming and outgoing links (source+target), 2 if it has only an incoming link (target), and 3 if it has no links (not linked). * @returns The point directions as an array of their direction values in the order they were sent to Cosmograph, or `undefined` if not available. */ readonly pointDirections: number[] | undefined; /** * Gets the maximum point size. This value is the maximum size of the `gl.POINTS` primitive that WebGL can render on the user's hardware. * @returns The maximum point size, or 0 if not available. */ readonly maxPointSize: number; /** * Waits for the data upload promise to resolve, if it exists. * This method is used to ensure that any necessary data has been uploaded * before proceeding with other operations. * @returns A promise that resolves when the data is ready. */ dataUploaded: () => Promise; /** * Gets the callback function for rescaling the x-axis. * @returns The callback function for rescaling the x-axis, or `undefined` if not set. */ readonly rescaleXFn: ((x: number) => number) | undefined; /** * Gets the callback function for rescaling the y-axis. * @returns The callback function for rescaling the y-axis, or `undefined` if not set. */ readonly rescaleYFn: ((y: number) => number) | undefined; /** * Sets the config for the Cosmograph. * @param config - Config to be applied to the Cosmograph. */ setConfig(config?: CosmographConfig): void; /** * Retrieves the current configuration of the Cosmograph. * @returns A promise that resolves with the current Cosmograph configuration. */ getConfig(): Promise; /** * Gets the current coloring function. * @returns The point coloring function, or `undefined` if not available. */ getActivePointColorFn(): Promise; /** * Gets the current point sizing function. * @returns The point sizing function, or `undefined` if not available. */ getActivePointSizeFn(): Promise; /** * Gets the current link coloring function. * @returns The link coloring function, or `undefined` if not available. */ getActiveLinkColorFn(): Promise; /** * Gets the current link width function. * @returns The link width function, or `undefined` if not available. */ getActiveLinkWidthFn(): Promise; /** * Captures a screenshot of the current graph view. * @param fileName Optional name for the downloaded file (default: 'cosmograph-screenshot.png'). */ captureScreenshot(fileName?: string, scale?: number): void; /** * Activates the rectangular selection element. */ activateRectSelection(): void; /** * Deactivates the rectangular selection element. */ deactivateRectSelection(): void; /** * Activates the polygonal selection element. */ activatePolygonalSelection(): void; /** * Deactivates the polygonal selection element. */ deactivatePolygonalSelection(): void; /** * Selects points inside a rectangular area. * @param selection Array of two corners of the rectangle `[[left, top], [right, bottom]]`. */ selectPointsInRect(selection: [[number, number], [number, number]] | null): void; /** * Selects points inside a polygonal polygon. * @param polygonalPoints Array of points defining the polygonal polygon. * @param addToSelection Optional parameter determining whether to add the points to the current selection. */ selectPointsInPolygon(polygonalPoints: [number, number][], addToSelection?: boolean): void; /** * Selects points. * @param pointIndices Array of point indices to be selected. */ selectPoints(pointIndices: number[] | null): void; /** * Selects a point and, optionally, its connected points. * @param pointIndexBy Selected point index. * @param addToSelection Optional parameter determining whether to add the point to the current selection. * @param selectConnectedPoints Optional parameter determining whether to also select the connected points. */ selectPoint(pointIndexBy?: number, addToSelection?: boolean, selectConnectedPoints?: boolean): void; /** * Unselects a point and, optionally, its connected points. * @param pointIndexBy Selected point index. * @param unselectConnectedPoints Optional parameter determining whether to also unselect the connected points. */ unselectPoint(pointIndexBy?: number, unselectConnectedPoints?: boolean): void; /** * Unselects points by indices. * @param indicesToRemove Array of point indices to be unselected. */ unselectPointsByIndices(indicesToRemove: number[]): void; /** * Unselects all points. */ unselectAllPoints(): void; /** * Get indices for currently selected points. * @returns Array of selected point indices. */ getSelectedPointIndices(): number[] | undefined; /** * Get indices for currently selected links. * @returns Array of selected link indices. */ getSelectedLinkIndices(): number[] | undefined; /** * Starts the simulation. * @param alpha Value between 0 and 1. The higher the value, the more energy the simulation gets. */ start(alpha?: number): void; /** * Pauses the simulation. */ pause(): void; /** * Unpauses the simulation. */ unpause(): void; /** * Stops the simulation. */ stop(): void; /** * Renders only one frame of the simulation (stops the simulation if it was running). */ step(): void; /** * Destroys the Cosmograph instance and cleans up associated resources. * @returns A promise that resolves when the destroy operation is complete. */ destroy(): Promise; /** * Resets the Cosmograph instance to its initial state. * @param total - If true, resets configuration and displays the message div. * @returns A promise that resolves when the reset operation is complete. */ reset(total?: boolean): Promise; /** * Zooms the view in or out to the specified zoom level. * @param value Zoom level. * @param duration Duration of the zoom transition. */ setZoomLevel(value: number, duration?: number): void; /** * Gets the zoom level of the view. * @returns Zoom level value. */ getZoomLevel(): number | undefined; /** * Sets the zoom transform so that the given point positions fit in the viewport, with optional animation. * * @param positions Flat array of point coordinates as `[x0, y0, x1, y1, ...]`. * @param duration Animation duration in milliseconds. Default `250`. * @param scale Optional scale factor; if omitted, scale is chosen to fit the positions. * @param padding Padding around the viewport as a fraction (e.g. `0.1` = 10%). Default `0.1`. */ setZoomTransformByPointPositions(pointPositions: Float32Array, duration?: number, scale?: number, padding?: number): void; /** * Centers the view and zooms in to a point by its index. * @param index Point index to be zoomed in. * @param duration Optional duration in milliseconds. * @param scale Optional zoom level. * @param canZoomOut Optional parameter determining whether the view can zoom out. */ zoomToPoint(index: number, duration?: number, scale?: number, canZoomOut?: boolean): void; /** * Gets the current X and Y coordinates of the points. * @returns Array of point positions. */ getPointPositions(): number[] | undefined; /** * Gets the current X and Y coordinates of a point by its index. * @param index Point index. * @returns Array with X and Y coordinates of the point, or `undefined` if the point index is invalid. */ getPointPositionByIndex(index: number): [number, number] | undefined; /** * Gets the current X and Y coordinates of the clusters. * @returns Array of point cluster positions. */ getClusterPositions(): number[] | undefined; /** * Gets the current colors for each point. * @returns A Float32Array containing RGBA color values for each point, or `undefined` if not available. */ getPointColors(): Float32Array | undefined; /** * Gets the current sizes for each point. * @returns A Float32Array containing size values for each point, or `undefined` if not available. */ getPointSizes(): Float32Array | undefined; /** * Gets the current colors for each link. * @returns A Float32Array containing RGBA color values for each link, or `undefined` if not available. */ getLinkColors(): Float32Array | undefined; /** * Gets the current widths for each link. * @returns A Float32Array containing width values for each link, or `undefined` if not available. */ getLinkWidths(): Float32Array | undefined; /** * Retrieves sampled point data as arrays with indices and positions. * @returns An object containing separate arrays for point indices and their corresponding positions, or `undefined` if not available. * The `indices` array contains point indices, and the `positions` array contains flattened coordinates `[x0, y0, x1, y1, ...]`. */ getSampledPoints(): { indices: number[]; positions: number[]; } | undefined; /** * For the links that are currently visible on the screen, get a sample of link indices, midpoint positions, and angles. * The resulting number of links will depend on the `linkSamplingDistance` configuration property, * and the sampled links will be evenly distributed. * Positions are in data space; angles are in radians for screen-space rotation (0 = right, positive = clockwise, e.g. for CSS rotation). */ getSampledLinks(): { indices: number[]; positions: number[]; angles: number[]; } | undefined; /** * Gets an array of point positions that are currently tracked by the renderer. * Use {@link trackPointPositionsByIndices} to specify which points to track. * @returns A flattened array of point positions `[x0, y0, x1, y1, ...]` for tracked points, or `undefined` if not available. * @see {@link trackPointPositionsByIndices} to set which points to track * @see {@link getTrackedPointPositionsMap} for a more convenient Map-based format */ getTrackedPointPositionsArray(): number[] | undefined; /** * Gets a Map of point positions that are currently tracked by the renderer. * Use {@link trackPointPositionsByIndices} to specify which points to track. * @returns A Map where keys are point indices and values are their corresponding X, Y coordinates, or `undefined` if not available. * @see {@link trackPointPositionsByIndices} to set which points to track * @see {@link getTrackedPointPositionsArray} for a flattened array format */ getTrackedPointPositionsMap(): ReadonlyMap | undefined; /** * Tracks point positions by indices on each simulation tick. * Once tracking is enabled, use {@link getTrackedPointPositionsArray} or {@link getTrackedPointPositionsMap} to retrieve the current positions. * @param indices Array of point indices. * @see {@link getTrackedPointPositionsArray} to get tracked positions as a flattened array * @see {@link getTrackedPointPositionsMap} to get tracked positions as a Map */ trackPointPositionsByIndices(indices: number[]): void; /** * Centers and zooms the view to fit all points in the scene. * @param duration Duration of the animation (default: 250ms). * @param padding Padding around the viewport (0 to 1 as 100% of the viewport, default 0.1. */ fitView(duration?: number, padding?: number): void; /** * Centers and zooms the viewport to fit points based on their indices. * @param indices Array of point indices. * @param duration Duration of the animation (default: 250ms). * @param padding Padding around the viewport (0 to 1 as 100% of the viewport, default 0.1. */ fitViewByIndices(indices: number[], duration?: number, padding?: number): void; /** * Fits the given coordinates into the viewport. * @param coordinates Array of coordinates in the format [x0, y0, x1, y1, ...]. * @param duration Duration of the animation (default: 250ms). * @param padding Padding around the viewport (0 to 1 as 100% of the viewport, default 0.1). */ fitViewByCoordinates(coordinates: number[], duration?: number, padding?: number): void; /** * Sets focus on a point by index. Draws a ring around the focused point. * @param index Index of the point to be focused. * @remarks * If `focusedPointIndex` is set, it will have priority over this method. */ setFocusedPoint(index?: number): void; /** * Sets which points are pinned (fixed) in position. * * Pinned points: * - Do not move due to physics forces (gravity, repulsion, link forces, etc.) * - Still participate in force calculations (other nodes are attracted to/repelled by them) * - Can still be dragged by the user if `enableDrag` is true * * @param {number[] | null} indices - Array of point indices to pin. Set to `[]` or `null` to unpin all points. * @example * // Pin points 0 and 5 * graph.setPinnedPoints([0, 5]) * * // Unpin all points * graph.setPinnedPoints([]) * graph.setPinnedPoints(null) */ setPinnedPoints(indices: number[]): void; /** * Gets the indices of the points that are connected to the point with the given index. * @param index The index of the point to get the connected points for. * @returns An array of indices of the connected points, or `undefined` if the point index is invalid or there are no connected points. */ getConnectedPointIndices(index: number): number[] | undefined; /** * Gets the in-degree and out-degree (link counts) for the point with the given index. * @param index The index of the point to get the degrees for. * @returns An object containing the in-degree (incoming links) and out-degree (outgoing links) for the point, * or `undefined` if the cosmograph instance is not initialized or the point index is invalid. */ getPointDegrees(index: number): { inDegree: number; outDegree: number; } | undefined; /** * Converts the X and Y point coordinates from the space coordinate system to the screen coordinate system. * @param spacePosition Array of x and y coordinates in the space coordinate system. * @returns Array of x and y coordinates in the screen coordinate system. */ spaceToScreenPosition(spacePosition: [number, number]): [number, number] | undefined; /** * Converts the X and Y point coordinates from the screen coordinate system to the space coordinate system. * @param screenPosition Array of x and y coordinates in the screen coordinate system. * @returns Array of x and y coordinates in the space coordinate system. */ screenToSpacePosition(screenPosition: [number, number]): [number, number] | undefined; /** * Converts the point radius value from the space coordinate system to the screen coordinate system. * @param spaceRadius Radius of the point in the space coordinate system. * @returns Radius of the point in the screen coordinate system. */ spaceToScreenRadius(spaceRadius: number): number | undefined; /** * Get point space radius by its index. * @param index Index of the point. * @returns Radius of the point in the space coordinate system. */ getPointRadiusByIndex(index: number): number | undefined; /** * Get point screen radius by its index. * @param index Index of the point. * @returns Radius of the point in the screen coordinate system. */ getPointScreenRadiusByIndex(index: number): number | undefined; /** * For the points that are currently visible on the screen, get a sample of point ids with their coordinates. * The resulting number of points will depend on the `pointSamplingDistance` configuration property, * and the sampled points will be evenly distributed. * @returns A Map where keys are the ids of the points and values are their corresponding X and Y coordinates. */ getSampledPointPositionsMap(): Map | undefined; /** * For the links that are currently visible on the screen, get a sample of link indices with their midpoint coordinates and angle. * The resulting number of links will depend on the `linkSamplingDistance` configuration property, * and the sampled links will be evenly distributed (one link per grid cell, based on link midpoint in screen space). * Each value is [x, y, angle]: position in data space; angle in radians for screen-space rotation (0 = right, positive = clockwise, e.g. for CSS rotation). */ getSampledLinkPositionsMap(): Map | undefined; /** * Gets the id of the active selection source. * @returns The id of the active selection source, or `undefined` if no selection is active. */ getActiveSelectionSourceId(): string | undefined; /** * Gets the points selection object from the crossfilter. * Provides access to selection clauses and active selection state. */ pointsSelection: MosaicSelection; /** * Gets the links selection object from the crossfilter. * Provides access to selection clauses and active selection state. */ linksSelection: MosaicSelection; /** * Returns an array of point indices in the order they were sent to `getPointIndicesByIds`. * @param ids Array of point ids. * @returns A Promise resolving to an array of point indices. */ getPointIndicesByIds(ids: string[]): Promise; /** * Returns an array of point ids in the order they were sent to `getPointIdsByIndices`. * @param indices Array of point indices. * @returns A Promise resolving to an array of point ids. */ getPointIdsByIndices(indices: number[]): Promise; /** * Returns points entries as a `CosmographData` table by their indices. * @param indices Array of point indices. * @returns A Promise resolving to a `CosmographData` table of points. */ getPointsByIndices(indices: number[]): Promise; /** * Returns an array of point indices that match the provided values in a column. * @param column The column to filter by. * @param values The values to match in the specified column. * @returns A Promise resolving to an array of point indices, or `undefined` if the operation fails. */ getPointIndicesByExactValues(column: string, values: (number | string)[]): Promise; /** * Returns an array of point indices that match the provided numeric value in the specified column. * @param column The column in the points table to filter by. * @param value The numeric value to match in the specified column. * @param isMax Indicates whether to return the indices for the maximum or minimum value. * @returns A Promise resolving to an array of point indices, or `undefined` if the operation fails. */ getPointIndicesByNumericValue(column: string, value: number | string, isMax: boolean): Promise; /** * Returns an array of point indices that match the provided link column values. * @param column The column in the links table to filter by. * @param values The values to match in the specified column. * @returns A Promise resolving to an array of point indices. */ getPointIndicesByLinksExactValues(column: string, values: (number | string)[]): Promise; /** * Returns an array of point indices that match the provided link column numeric value. * @param column The column in the links table to filter by. * @param value The numeric value to match in the specified column. * @param isMax Indicates whether to return the indices for the maximum or minimum value. * @returns A Promise resolving to an array of point indices. */ getPointIndicesByLinksNumericValue(column: string, value: number | string, isMax: boolean): Promise; /** * Returns links entries as a `CosmographData` table where the source or target point id is in the provided array. * @param ids Array of point ids. * @returns A Promise resolving to a `CosmographData` table of links. */ getLinksByPointIds(ids: string[]): Promise; /** * Returns links entries as a `CosmographData` table where the source or target point index is in the provided array. * @param indices Array of point indices. * @returns A Promise resolving to a `CosmographData` table of links. */ getLinksByPointIndices(indices: number[]): Promise; /** * Returns all points entries as a `CosmographData` table. * @returns A Promise resolving to a `CosmographData` table of points. */ getPointsData(): Promise; /** * Returns all links entries as a `CosmographData` table. * @returns A Promise resolving to a `CosmographData` table of links. */ getLinksData(): Promise; /** * Converts a `CosmographData` table to an array of objects. * @param data `CosmographData` table. * @returns An array of objects. */ convertCosmographDataToObject(data: CosmographData): Record[]; /** * Converts an array of tuple positions to a single flattened array containing all coordinates sequentially. * @param positions An array of tuple positions. * @returns A flattened array of coordinates. */ flattenPositions(positions: [number, number][]): number[] | undefined; /** * Converts a flat array of point positions to tuple pairs representing coordinates. * @param pointPositions A flattened array of coordinates. * @returns An array of tuple positions. */ pair(pointPositions: number[]): [number, number][] | undefined; /** * Adds points to the Cosmograph instance. * @param points The points data to add. * @remarks * Minimal to provide is point a id. Other fields are optional, should respect already existing fields in the points data, if not provided, will be filled with default values. * @returns A promise that resolves when the points have been added. */ addPoints(points: CosmographPointInput[]): Promise; /** * Adds links to the Cosmograph instance. * @param links The links data to add. * @remarks * Minimal to provide is a source point and target point id. Other fields are optional, should respect already existing fields in the links data, if not provided, will be filled with default values. * @returns A promise that resolves when the links have been added. */ addLinks(links: CosmographLinkInput[]): Promise; /** * Removes points from the Cosmograph instance by their indices. * @param indices The indices of the points to remove. * @param removeAttachedLinks Whether to also remove links attached to the points. * @returns A promise that resolves when the points have been removed. */ removePointsByIndices(indices: number[], removeAttachedLinks?: boolean): Promise; /** * Removes points from the Cosmograph instance by their IDs. * @param ids The IDs of the points to remove. * @returns A promise that resolves when the points have been removed. */ removePointsByIds(ids: string[]): Promise; /** * Removes links from the Cosmograph instance by their point ID pairs. * @param pairs The point ID pairs of the links to remove. * @returns A promise that resolves when the links have been removed. */ removeLinksByPointIdPairs(pairs: [string, string][]): Promise; /** * Removes links from the Cosmograph instance by their point indices pairs. * @param pairs The point indices pairs of the links to remove. * @returns A promise that resolves when the links have been removed. */ removeLinksByPointIndicesPairs(pairs: [number, number][]): Promise; /** * Adds a custom Mosaic component (vgplot, spec, etc.) and mounts it to a container. * The component will automatically participate in Cosmograph's crossfilter system. * @param component The vgplot component * @param container The DOM element to mount the component into * @param config Optional configuration for the component * @returns A promise that resolves to the created component */ addMosaicComponent(component: HTMLElement, container: HTMLElement, config?: { id?: string; }): Promise; /** * Removes a custom Mosaic component by its ID. * @param id The ID of the component to remove * @returns A promise that resolves to true if the component was removed, false otherwise */ removeMosaicComponent(id: string): Promise; /** * Gets all registered Mosaic components. * @returns A readonly map of component IDs to components */ getMosaicComponents(): ReadonlyMap | undefined; } export type Summary = Record[]; export type CosmographSummary = { pointsSummary?: Summary; linksSummary?: Summary; }; export type CosmographStats = { /** * Current number of points in the Cosmograph visualization. */ pointsCount: number; /** * Current number of links in the Cosmograph visualization. */ linksCount: number; /** * Summary information for the points in the Cosmograph visualization. * Stats include column names, column types, number of aggregates over all columns (`count`, `min`, `max`, `approx_unique`, `avg`, `std`, `q25`, `q50`, `q75`), * and the percentage of `NULL` values in the columns. */ pointsSummary?: Summary; /** * Summary information for the links in the Cosmograph visualization (if links are present). * Stats include column names, column types, number of aggregates over all columns (`count`, `min`, `max`, `approx_unique`, `avg`, `std`, `q25`, `q50`, `q75`), * and the percentage of `NULL` values in the columns. */ linksSummary?: Summary; };