search

cinemascience / cinema_components

A JavaScript library for building Cinema viewers
Other
2 stars 5 forks source link

readme

CINEMA_COMPONENTS

Version 2.8.0

A javascript library containing prebuilt components for viewing and querying Cinema SpecD databases.

Components

PcoordSVG

A component for viewing and browsing a database on a Parallel Coordinates Chart (rendered with SVG)

PcoordCanvas

A component for viewing and browsing a database on a Parallel Coordinates Chart (rendered with Canvas)

Glyph

A component for viewing data on a Glyph Chart

ImageSpread

A component for viewing image data for a set of data points

Query

A component that provides an interface for defining a custom data point and querying the database for similar points.

ScatterPlotSVG

A component for viewing data on a Scatter plot (rendered with SVG)

ScatterPlotCanvas

A component for viewing data on a Scatter plot (rendered with Canvas)

LineChart

A component for viewing multiple parameters on a single line chart

Usage

Below is a simple example of a webpage that uses a pcoordSVG component to control the display of an ImageSpread component

<html>
<head>
    <!--Import D3-->
    <script src="https://github.com/cinemascience/cinema_components/raw/master/lib/d3.min.js"></script>
    <!--Import Cinema Components Library-->
    <script src="https://github.com/cinemascience/cinema_components/raw/master/CinemaComponents.js"></script>
    <!--Include Component's CSS-->
    <link rel='stylesheet' href='css/CinemaComponents.min.css'>
</head>
<body>
    <!--The component will be placed inside container-->
    <div id="pcoord_container" style="width:500px;height:400px;"></div>
    <div id="spread_container" style="width:100%;height:400px;"></div>
    <script>
        var chart, spread;
        //First create a database
        var database = new CINEMA_COMPONENTS.Database('mydata.cdb',function() {
            //This callback function is called when the database has finished loading
            //Use it to create your components
            chart = new CINEMA_COMPONENTS.PcoordSVG(document.getElementByID('pcoord_container'), database);
            spread = new CINEMA_COMPONENTS.ImageSpread(document.getElementByID('spread_container'),database);

            //Using dispatch events, components can communicate with each other
            chart.dispatch.on('selectionchange',function(selection) {
                spread.setSelection(selection);
            });
        });
    </script>
</body>
</html>

How to Build

The provided makefile will combine all the cinema components source files into a single file. Be aware of the following targets available:

Build Options

The file build_options contains various options for building as space-separated, key-value pairs (one-per-line). If you want to override these values to values specific to your machine, copy and rename the file to build_options.local and the makefile will use the values from there instead, while the local file is ignored by git.

Documentation

Database

At the heart of CinemaComponents is the Database object. An instance of Database represents all of the data in a SpecD Cinema Database. All components will refer to a Database for their information and occasionally use the functions provided in Database for data processing.

Constructor

CINEMA_COMPONENTS.Database(directory,callback,errorCallback)

Example:

var myDatabase = CINEMA_COMPONENTS.Database("path/to/database.cdb",done,error);
function done() {console.log("Loaded Succesfully!");}
function error(message) {console.log("Error! " + message);}

Fields

Component

All components in CinemaComponents are subclasses of Component. Component contains fields and methods common to all components (though some may be overridden). Component.js also contains definitions for some small classes that may be used by components such as CINEMA_COMPONENTS.ExtraData and CINEMA_COMPONENTS.Margin

Usage of Components

Components are built inside DOM elements where they create an interface for interacting with their respective databases. Not all components provide much functionality on their own and are expected to "communicate" with other components through d3.dispatch events. (For example, the query component can query for data points, but does nothing with the query unless another component listens for the query event and does something with it (such as display the results)).

Constructor

CINEMA_COMPONENTS.Component(parent, database, filterRegex) This constructor is abstract and will throw an error if called directly. You should instead instantiate subclasses of Component. However, the parameters for all components constructors are the same, so they will be listed here.

Glyph

Glyph is a type of component for viewing one data point at a time in a glyph chart.

Usage

The Glyph offers no user interactivity other than looking at it.

Events

The Glyph component does not dispatch any events.

Structure

Inside the container, the glyph consists of an SVG element classed ".glyphChart." Inside that is a path classed ".glyph" representing the glyph being drawn, a group (g) classed ".labels" for all the axis labels, and a group classed ".axisContainer" for the axes. Inside labels, are more groups each classed ".label." Inside each label is a text element with the name of the dimension. Inside axisContainer, are groups classed ".axisGroup" for each dimension. Each axisGroup contains another group classed ".axis" which is where d3 places the axis content.

Fields

Pcoord

Pcoord is a component for displaying and selecting data on a Parallel Coordinates Chart. It is an abstract class and cannot be built on its own. Instead use either a PcoordSVG or PcoordCanvas component which use different methods of rendering paths. Both subclasses expose the same fields and methods so they will be listed here.

Usage

Data shown on the chart can be filtered by click-and-dragging along an axis. This will create a selection and only show data that passes through the selection. Data can be filtered further by creating selections on other axes. Axes can be re-arranged by click-and-dragging along the axis titles.

Events

Query

Query is a component for defining a custom data point and querying the database for data similar to it.

Usage

The query panel contains a slider for every numeric dimension in the database. Adjusting these sliders defines a value along that dimension for the custom data point. The checkbox next to each slider indicates whether or not to include that dimension in the query. The "Threshold" input defines the threshold value for the query. Pressing the "Find Similar" button performs the query. The results of the query are not represented in the component but instead given out with an event and is expected to be recieved by other components.

Events

ScatterPlot

ScatterPlot is a component for viewing data on a 2D Scatter Plot. It is an abstract class and cannot be built on its own. Instead use either a ScatterPlotSVG or ScatterPlotCanvas component which use different methods of rendering points. Both subclasses expose the same fields and methods so they will be listed here.

Usage

Selected data points are displayed on the Scatter Plot. The dimensions used on the plot can be changed with the select elements on the left and bottom sides of the chart.

Events

ImageSpread

ImageSpread is a component for viewing the FILE data associated with a selection of data as a spread of images.

Usage

The file data for all selected data is displayed in boxes. Each box represents a data point and contains a display for each FILE dimension of the data. Valid images (PNG,GIF,JPEG) are displayed while other filetypes have text explaining that they couldn't be displayed. An image can be clicked on to reveal the full-size image. If the boxes extend outside of the size of the component, it can be scrolled through to reveal more. If there is more data selected than can fit on a single page, buttons will appear at the bottom of the component to select different pages. Settings for displaying and sorting the data are in the header at the top of the component.

Events

If there are no FILE dimensions in the data, the only contents of imageContainer is div classed '.noFileWarning' with text saying so.

If there are multiple pages of data the container also has a div classed '.pageNavWrapper' for the page navigation widget. in pageNavWrapper is a ul element classed '.pageNav' and a div clased '.pageReadout'. Every li element in pageNav is classed '.pageButton.'

Fields

LineChart

LineChart is a component for viewing aggregate function as multiple lines in a chart.

Usage

The aggregate functions will be shown as lines and every line is selectable using the checkboxes. The X-axis can be changed by using the drop-down menu on the bottom. Selections can be made by using the dragging motion, while holding the left mouse button down.

Events

The tableContainer contains two tables containing the group checkboxes(.lineSelect .yGroup) and the single checkboxes(.lineSelect .y)

The linechart consists of an svg plane.

Fields

Changelog

Version 2.7.1