Skip to content

Latest commit

 

History

History
161 lines (137 loc) · 5.6 KB

readme.md

File metadata and controls

161 lines (137 loc) · 5.6 KB
Raw

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.