Vector.js

Vector is an open source javascript library for creating interactive vector graphics. View the repository, browse the API, run the tests, or meet the team.

Getting Started

Welcome! To use this library, download the getting-started.tgz tar ball and follow the instructions below. The tar ball contains a folder with an index.html file and script.js file. The HTML file links the library’s style sheet, has an element with an unique id, and includes the script file.

index.html
<!DOCTYPE html>
<html lang="en" dir="ltr">
  <head>
    <meta charset="utf-8">
    <title>Getting Started</title>
    <link rel="stylesheet" href="https://vectorjs.org/library.css">
  </head>
  <body>
    <div id="my-interactive"></div>
    <script type="module" src="script.js"></script>
  </body>
</html>

The script file imports the Interactive class from the website, constructs an interactive within the HTML element with the id “my-interactive”, and then constructs a control point which can be dragged around. It also prints out the control and interactive to the console to play around with.

script.js
import Interactive from "https://vectorjs.org/interactive.js";

// Construct an interactive within the HTML element with the id "my-interactive"
let myInteractive = new Interactive("my-interactive");
myInteractive.border = true;

// Construct a control point at the the location (100, 100)
let control = myInteractive.control(100, 100);

// Print the two objects to the console
console.log( control, myInteractive);

To view the interactive, serve the folder containing the two files using a local server like Web Server for Chrome or your tool of choice. The result is a simple interactive with a draggable control point:

Input

User input drives the animations of these graphics and is the main focus of this library. These input elements are part of the SVG ecosystem and provide the end users with ways to manipulate and interact with the visual in front of them.

Button

The button element has a position, label, and default style. Defining the “onclick” method handles when a user clicks the button.

let button = interactive.button( 100, 75, "My Button");

Check Box

A checkbox has two different states: checked and unchecked. When a user clicks the box the state changes.

let checkBox = interactive.checkBox( 100, 75, "My Checkbox", false);

Control Point

A control point is a two dimensional point that can be clicked and dragged by the user. The control has a (x,y) position as well as its change in position (dx, dy).

let control = interactive.control( 150, 75);

Radio Control

The radio control elements allows the user to select from a list of options. Only one option can be selected at a time.

let radio = interactive.radioControl(100, 50, ["red","green","blue"]);

Scrubber

The scrubber has a play and pause button that start and stop the animation. The position indicator can also be dragged to change the state of the scrubber.

let scrubber = interactive.scrubber( 100, 75, 400);

Slider

A slider has a position, width, and starting value.

let slider = interactive.slider( 75, 75, 150, 20);

Elements

Our library has basic visual elements that are used to create the graphics. All elements contain a root SVGElement that contains the visual part of the element. Basic element root’s correspond directly to the visual aspect of the element, more complicated elements often contain many SVGElements that describe the graphic.

Ellipse

let ellipse = interactive.ellipse( 100, 75, 80, 40);

Line

let line = interactive.line( 50, 25, 150, 125);

Path

let line = interactive.path("M 50 50 Q 100 150 150 50");

Rectangle

let rectangle = interactive.rectangle( 50, 50, 100, 50);

Text

let text = interactive.text( 50, 75, "My Text");

TSpan

A text span element allows for text to be styled and positioned differently within a body of text. In the example below, a word is randomly selected to be bolded.

let text = interactive.text( 50, 75, '');
text.tspan('normal. ');
text.tspan('bold. ').style.fontWeight = '600';
text.tspan('normal again.');

Interaction

There are two forms of interaction within our system: dependencies and events.

The first form of interaction is dependencies. Elements can be related together using dependency functions, similar to how cells are related together in a spreadsheet application. These dependencies are explicit and give dependents access to the data of the elements they rely on. These dependencies also define how the interactive should update elements and in what order the update should happen when an element’s state is changed.

The second, more tradditional, form of interaction is events. Events are typically utilized with input elements and the main interactive object. Events follow a design pattern common to the web - a user event happens and then the corresponding event handler is called.

Dependency Functions

All elements contain the ability to define dependencies to other elements. An element declares what it is dependent on using the “addDependency” function and then defines an update function which describes how the element should update itself. Circular dependencies will cause an exception. By convention, an element should only use the data of the elements it has declared itself dependent on.

let control1 = interactive.control( 100, 100);
let control2 = interactive.control( 200, 200);
control2.addDependency(control1);
control2.update = function(){
  this.x += control1.dx;
};

Keyboard Input

Key board input can be used to change the state of an interactive as well as control different elements within the interactive. The example below highlights the numbers one through five with the corresponding key on the keyboard when pressed.

window.onkeydown = function( event ) {
  ...
}

Mouse Input

Mouse input can be used to change the state of an interactive. Mouse input consists of the mouse’s position, when the users clicks the interactive, etc.

interactive.mouse ?
interactive.onclick ?
interactive.onmousemove ?

Animation

While animation isn’t the main focus the library, some basic animations are supported.

Transitions?

Time Line

Adding a time-line to an interactive gives the user control over a basic animation. For beginner users, the scrubber is a great element to animate parts of an interactive. It allows the user to start, stop, and “scrub” to different parts of the animation.

let circle = interactive.circle( 75, 75, 20);
let path = interactive.path("...");
circle.animateAlongPath( path, true, SPEED);

Maps

Wishful thinking (x,y) to lattitude longitude and vice versa.

World Map

import canada from './maps/canada.js';
let map = interactive.map(canada);

SVG World Map

United States

let map = interactive.map("united-states.geojson");

SVG United States Map

Custom Maps

import { getJSON } from 'Util.js';

getJSON('custom.geojson').then(function(geoData){

});

Coordinates

The coordinate system of the interactive image follows the SVG standard: the default origin is the top left corner of the image and the positive x direction is to the right and the positive y direction is down. This is visualized by the control point below.

// TODO: show changing the origin of the coordinate system
// TODO: mathmode -> changes positive direction of the y axis to be up

Alternatively, the viewbox of the interactive can be changed

// what happens when the dimensions of the interactive and the viewbox disagree?

Scaling

SVG Coordinate System

// TODO: Scaling example

Zooming and Panning

Transforming

Styling

The appearance of elements within this library can be styled using CSS. Styles can either be applied using a user defined style sheet or directly within the Javascript file. Helper classes are provided for the convenience of the user.

Basic Styling

Basic geometric elements have two basic properties: fill and stroke. Fill is the area contained within the shape and stroke is the edge of the geometric shape. These styles can be accessed through the style property.

Fill and Stroke Element

let rectangle = interactive.rectangle( 50, 50, 100, 50);
rectangle.style.fill = 'blue';
rectangle.style.stroke = 'red';
rectangle.style.strokeWidth = '1px';

Custom Styling

Every element within the library has a root property which is a SVG element. This root element contains zero or more child elements all of which can have custom styling applied to them through CSS selectors or Javascript. The style sheet for the library can be found in the Library.css file. Typically, elements have an associated class that gives them their default look and feel.

// element.style ...
// TODO: how to load a custom style sheet