canvas-curve

DEMO 1 - DEMO 2 - DOC

Features

• create a nice canvas-based spline editor widget
• add/remove points both programmatically and with the UI
• interpolate points using cubic splines the graphic way (a-la Photoshop)
• use both natural cubic splines and monotonic cubic splines
• use unit coordinates
• programmatically get single interpolated values (as Numbers) or along the whole x axis (as an Array)
• no dependency
• Retina automatically adjusted
• lock a point over the x and/or the y axis when adding programmatically
• make a point safe when adding programmatically so that it cannot be removed

How to install

Directly in the browser:

<script src="dist/CanvasSpliner.min.js"></script>

Or with a bundler

npm install --save jonathanlurie/CanvasSpliner

how to use

// create a new CanvasSpliner, with a parent DIV id, a width and a heigh
var cs = new CanvasSpliner("parent", 300, 300);

// Optional: Add points (with unit coordinates)
cs.add( {x:0, y: 0, xLocked: true, yLocked: true, safe: true} );
cs.add( {x:0.1, y: 0.4} );
cs.add( {x:0.3, y: 0.45} );
cs.add( {x:0.6, y: 1} );
cs.add( {x:1, y: 0.6, xLocked: true, safe: true} );

Adding points programmatically

As shown above, we can add points directly from the code. Those points can have other attributes than (x, y) coordinates.

• we can lock a point so that it does not move along the x axis:

s.add( {x:0.1, y: 0.5, xLocked: true} );

• we can lock a point so that it does not move along the y axis:

s.add( {x:0.12, y: 0.6, yLocked: true} );

• We can make a point safe so that the user cannot remove it with a double-click:

s.add( {x:0.8, y: 0.4, safe: true} );

• We could also use all that together:

cs.add( {x:0.4, y: 0.1, xLocked: true, yLocked: true, safe: true} );

What kind of cubic spline to use?

CanvasSpliner allows two kinds of cubic spline: natural and monotonic. The math behind does not matter, just remember the natural is a bit curvyer and the monotonic is a bit stiffer. You can enable one mode or the other two diferent ways:

• with the constructor optional last argument:

var cs = new CanvasSpliner("parent", 300, 300, "natural");

Note that this is the default mode when the argument is omited.

• with the setter

cs.setSplineType( "monotonic" );
// or
cs.setSplineType( "natural" );

Control the UI

• click on a point: it is selected, you can move it (unless it is xLocked or yLocked)
• double click on a point: deletes it (unless it is safe)
• double click somewhere else in the canvas: adds a point

Other methods

Get an interpolated value, in unit coordinates:

var interpolatedY = cs.getValue( 0.15 );

Get all the spectrum of x coordinates, in a normalized space:

var arrayOfX = cs.getXSeriesInterpolated();

Note that if your canvas is 500px wide, you will get 500 values from 0 to 1 with regular spacing.

Along with this regular x go the interpolated y array:

var interpolatedYs = cs.getYSeriesInterpolated();

Events

CanvasSpliner can trigger two events:

• When grabbing a point and moving it, called at every mousemove event

cs.on( "movePoint", function( csObj ){
  // here, csObj is the same object as cs. We can then call
  // cs.getXSeriesInterpolated() or
  // cs.getYSeriesInterpolated()
})

• When a point was grabed but id just released

cs.on( "releasePoint", function( csObj ){
  // here, csObj is the same object as cs. We can then call
  // cs.getXSeriesInterpolated() or
  // cs.getYSeriesInterpolated()
})

Styling

If you want to adapt the styling of CanvasSpliner to match you own project, you can. After changing the styling, be sure you call the method cs.draw() to refresh!

• Change the size of the control point with a number of pixels:

cs.setControlPointRadius( 6 )

• Set the color of the control points, depending on the state. The state can be "idle", "hovered" or "grabbed" and the color must be a css-like string (ie. "rgba(244, 66, 167, 0.5)")

cs.setControlPointColor( state, color )

• Set the color of the curve, depending on its state. The state can be "idle" or "moving" and the color must be a css-like string (ie. "rgba(244, 66, 167, 0.5)")

cs.setCurveColor( state, color )

• Set the color of the grid with a css-like string (ie. "rgba(244, 66, 167, 0.5)")

cs.setGridColor( color )

• Set the step of the grid (both horizontal and vertical) in normalized size ( in [0, 1])

cs.setGridStep( gs )

• Set the color of the text with a css-like string (ie. "rgba(244, 66, 167, 0.5)")

cs.setTextColor( color )

• Set the thickness of the curve in pixel

cs.setCurveThickness( t )

• Set the color of the background with a css-like string (ie. "rgba(244, 66, 167, 0.5)") of set it to null / false or 0 to have a transparent background.

cs.setBackgroundColor( color )

Bundled in this module

CanvasSpliner uses George MacKerron's splines, wrapped in a propper npm package by Marcio Augusto Guimarães.