grapher-ts v0.0.5
Grapher.ts
A TypeScript component for drawing graphs.
Provided Functionality (User Guide)
Project provides a UI component that allows users to draw directed weighted graphs.
Adding Vertices
To add a vertice user needs to select "Vertices tool" (circle in the toolbar) and click on graph drawing field wherever vertex needs to be added.
Adding Edges
To connect two vertices with an edge user needs to select "Edges tool", click and drag from source vertex to target vertex.
Specifying Weights
To specify weights for edges user needs to select "Weights tool", select an edge and input the weight using keyboard. Weights can be deleted using backspace and delete keys. Only numeric values are allowed.
Repositioning Vertices
To reposition vertices user needs to select "Vertices tool" and drag a vertex to a new position.
Removing Graph Items
To remove individual items from the graph user needs to select "Removal tool" and click on items that needs to be removed. To remove all items in the graph user can click "Clear graph" button (thrash can in the toolbar).
Limitations and Issues
Tool cannot draw multigraphs or self-loop edges.
Weights inputed via GUI must be integer and cannot be negative or zero.
Selecting an edge for weight input on a device with soft keyboard (e.g. mobile devices) will not automatically open the keyboard.
Install
To use this component in Node.js
project run:
npm install grapher-ts
Usage
Basic example
A very basic example of adding Grapher.ts
component to an HTML document on load. This is sufficient to render the graph drawing tool.
import { Grapher } from 'grapher-ts';
window.onload = () => {
const container = document.createElement('div');
const grapher = new Grapher(container);
document.body.appendChild(container);
};
Adding vertices and edges using API
const grapher = new Grapher(container);
const sourceVertex = grapher.addVertex(new Point(10, 20));
const targetVertex = grapher.addVertex(new Point(30, 30));
const weight = 3;
// This will create a directed edge going from source to target
// with specified weight.
grapher.addEdge(new Edge(sourceVertex, targetVertex, weight));
Exporting graph to a common format
const grapher = new Grapher(container);
// Converts graph to adjacency matrix where graph is represneted as V x V
// array where array elements are weights of edges (0 indicates no edge).
// Array is indexed using IDs of vertices.
grapher.graph.toAdjacencyMatrix();
// Coverts graph to adjacency list where graph is represented as a list
// of edges where each list element is an object of form
// {source, target, weight} where source is source vertex ID, target is
// target vertex ID and weight is the weight of represented edge.
grapher.graph.toAdjacencyList();
Changing appearance of elements using CSS classes
Appearance of graph elements can be manipulated using CSS classes. This can be used to style graph to fit some design or to visualize algorithms.
const grapher = new Grapher(container);
const vertex = grapher.addVertex(new Point(10, 20));
// Add CSS class to vertex.
vertex.svgElement.classList.add('active');
const edge = grapher.svgEdges[0];
// Add CSS class to edge path element.
edge.edgeSvg.classList.add('active');
// Add CSS class to edge weight element.
edge.weightSvg.classList.add('active');
// Remove a CSS class from some item.
edge.weightSvg.classList.remove('hidden');
Component Architecture
Packages
Component consists of three packages:
- Domain - package defines classes for modelling a graph. It defines edges, vertices, graph and basic operations of the graph.
- Visual - package extends classes defined in domain by adding visual components to them. Deals with creating and manipulating DOM elements that represent the graph.
- Interaction - package defines handlers for user input. Each handler defined in the package deals with one mode of operation that is controlled by the toolbar.
Classes
Below is a UML class diagram that covers all the classes of the component and shows relationships between them.
Description of each class can be found as comments in the source code or in generated TypeDoc documentation.
TypeDoc Documentation
Documentation generated from the source using TypeDoc can be found here.
Changelog
0.0.5
Implemented graph export.
Updated readme.
0.0.4
Updated webpack output to correctly export library as module.
Updated readme with user guide, examples and documentation.
0.0.3
- Reconfigured typings.
0.0.2
- Added missing typings.
0.0.1
- Initial version.
Compile
Builds use /lib
as outpud directory. Builds will also generate documentation from source code using TypeDoc
that will be placed under /docs
.
Prod build
To compile the project run:
npm run-script build
This will output a Javascript file /lib/grapher.js
that can be used to distribute this component.
Dev build
For local development purposes it is possible to build with:
npm run-script build-dev
Unlike regular build, this will output /lib/index.js
that can be included in HTML file to load a demo of the component. To view the component, one can open src/index.html
.
License
Project is licensed under MIT license. License file can be found here.