tslerp
Typescript library for lerping single and multi-sample data sets over time across a variety of styles and transitions.
Build Status
Master Branch
Develop Branch
End User Documentation
Installation
- Add the package to your 'dependencies' list in
package.json
and runnpm install
"tslerp": "^2.0.0"
Optionally, you can manually install the package using the npm command line
npm install tslerp --save
- Add tslerp to both your
map
andpackages
structures insystemjs.config.js
var map = ... 'tslerp': 'node_modules/tslerp';
var packages = ... 'tslerp': main: 'index.js' defaultExtension: 'js' ;
- Optionally, add the
rootDir
option totsconfig.json
to make sure TypeScript's default root path algorithm doesn't pull in thenode_modules
folder
Usage
Examples of using tslerp can also be found in the tslerp test packages in lerp.spec.ts
Triggering a simple lerp
// Import the lerp class from tslerpimport { TsLerp } from 'tslerp'; class ClassToLerpSomething { // Define our lerp object private tsLerp: TsLerp = new TsLerp(); // Starts a transition using TsLerp public startTransition() { // Define the properties of the lerp, this can contain a single set of // points to lerp between, or multiple data points // The format of the function is define([ [start, end], ...], duration); // The following defines two data sets, one to lerp between 0 and 10, and one // to lerp between 30 and 50. Both sets will take 10 seconds to complete this.tsLerp.define([ [0, 10], [30, 50] ], 10); // Trigger the lerp, providing a callback that will be called constantly // as the lerp progresses from start to finish // This callback will be called every 33 milliseconds providing a constent // 30 FPS on stable systems. For none stable systems, the transition is // framerate independent to will always take the defined amount of time to finish this.tsLerp.lerp((results: number[], time: number) => { this.lerpCallback(results, time); }); } // Function called from TsLerp.lerp every 33 milliseconds private lerpCallback(results: number[], time: number) { // This callback is passed // - results: An array of values containing the current lerp values of the data // sets passed through in TsLerp.define. The order of the results // is guarenteed to be the same order as originally defined. // - time: The current passage of time in the range [0..1]. When time is // 1, the lerp has completed and the callback will cease to be called. }}
Chaining lerp sequences
// Import the lerp class from tslerpimport { TsLerp } from 'tslerp'; class ClassToLerpSomething { ... // Lerp callback containing the results of the current lerp process private lerpCallback(results: number[], time: number) { // It is perfectly acceptable to request an a new set of lerp values // during a current lerp. In the following example, when the first // set of lerp values has completed, a sequential set of lerp values // is initiated. // Note that calling TsLerp.define will reset the current lerp values // which means triggering a new set of lerp points in the middle of // a current lerp sequence may result in unwanted results. // Call this when the current lerp has finished if (time === 1) { // Define a lerp between [10..100] over 5 seconds this.tsLerp.define([ [10, 100] ], 5); // We can use the same callback or a different callback depending on // the expected results. Note in this case, we're creating an infinite // loop of lerp events, something you probably don't want to do... this.tsLerp.lerp((results: number[], time: number) => { this.lerpCallback(results, time); }); } }}
Controlling an in-progress lerp
It is possible to pause or delay an in-progress lerp in response to external events
// Import the lerp class from tslerpimport { TsLerp } from 'tslerp'; class ClassToLerpSomething { ... // Generic event indicating the page or animation needs to pause private onSomeEventToPause() { // You can call TsLerp.pause to stop the current transition // This will stop the lerp from progressing and stop all calls // to the user provided callback in TsLerp.lerp. this.tsLerp.pause(true); ... } // Generic event indicating the page or animation can continue private onSomeEventToResume() { // You can call TsLerp.pause to resume the current transition // This will start the progression of the lerp again and resume // calls to the user provided callback in TsLerp.lerp. this.tsLerp.pause(false); ... } // Generic event indicating the transition needs to terminate private onSomeEventToStop() { // You can call TsLerp.stop to cancel the current lerp and // stop all calls to the user defined callback in tsLerp.lerp this.tsLerp.stop() ... }}
Styling a lerp transition
TsLerp.define
allows you to specify the kind of transition and style the lerp will travel.
// Import the lerp types from tslerpimport { TsLerp, TsLerpTransition, TsLerpStyle } from 'tslerp'; class ClassToLerpSomething { ... // Starts a transition using TsLerp public startTransition() { // Define a lerp that eases out of the transition using a quadratic path this.tsLerp.define([ [0, 10], [30, 50] ], 10, TsLerpTransition.EaseOut, TsLerpStyle.Quadratic); ... } // Lerp callback containing the results of the current lerp process private lerpCallback(results: number[], time: number) { // Regardless of the type of style or transition used for the lerp, the // time value of the callback will always increment in a linear manner. }}
The following animations show the various transitions and styles available, samples over a 1 second period. All animations were captured from Easing Equations by Robert Penner
Style: Linear
Note that the TsLerpTransition
option is ignored when choosing a Linear style
Style: Quadratic
Transition: Ease In
Transition: Ease Out
Transition: Ease In and Out
Style: Sine
Transition: Ease In
Transition: Ease Out
Transition: Ease In and Out
Cubic
Transition: Ease In
Transition: Ease Out
Transition: Ease In and Out
Style: Exponential
Transition: Ease In
Transition: Ease Out
Transition: Ease In and Out
Change Log
2.0.0
- Removed Typings dependency
1.0.5
- Updated project to latest TypeScript (v2.3.2) and fixed resultant errors
1.0.4
- Documentation update stating Typings as a Dependency
1.0.3
- Updated package requirements to Typescript ^2.0.0 plus related package upgrades
1.0.2
- Minor readme updates
1.0.1
- Updated correct acknowledgment for Easing Equations by Robert Penner
1.0.0
- Added support for Linear, Sine, Cubic and Exponential styles
- Added support for Ease In, Out and In/Out transitions for all styles
0.0.1
- Initial release
- Support for Ease In Quadratic lerps only
Contribution Guidelines
Requirements
- node.js and npm
- Typescript 2.6.2+
Optional
- Visual Studio Code
- Recommended VS Code Extensions are included in the workspace
Development
- Branch from */develop
- Browse to /development and run
npm install
- Compile by running
tsc
(by default this will watch for changes) - Run tests in watch mode by running
npm run-script testdev
Merging Back
- Raise a pull request which will run a set of Travis-CI tests
- Once passed, the change will be squashed into develop if approved