tslerp
Version:
Typescript library for lerping single and multi-sample data sets over time
325 lines (217 loc) • 10.3 kB
Markdown
Typescript library for lerping single and multi-sample data sets over time across a variety of styles and transitions.
[](https://badge.fury.io/js/tslerp)
**Master Branch**
[](https://travis-ci.org/leewinder/tslerp)
[](https://dependencyci.com/github/leewinder/tslerp)
**Develop Branch**
[](https://travis-ci.org/leewinder/tslerp)
<br>
1. Add the package to your 'dependencies' list in `package.json` and run `npm install`
`"tslerp": "^2.0.0"`
Optionally, you can manually install the package using the npm command line
`npm install tslerp --save`
2. Add tslerp to both your `map` and `packages` structures in `systemjs.config.js`
```javascript
var map = {
...
'tslerp': 'node_modules/tslerp'
};
```
```javascript
var packages = {
...
'tslerp': { main: 'index.js', defaultExtension: 'js' },
};
```
3. Optionally, add the `rootDir` option to `tsconfig.json` to make sure TypeScript's default root path algorithm doesn't pull in the `node_modules` folder
<br>
Examples of using tslerp can also be found in the tslerp test packages in [lerp.spec.ts](https://github.com/leewinder/tslerp/blob/master/development/src/tests/lerp/lerp.spec.ts)
```TypeScript
// Import the lerp class from tslerp
import { 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.
}
}
```
```TypeScript
// Import the lerp class from tslerp
import { 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);
});
}
}
}
```
It is possible to pause or delay an in-progress lerp in response to external events
```TypeScript
// Import the lerp class from tslerp
import { 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()
...
}
}
```
`TsLerp.define` allows you to specify the kind of transition and style the lerp will travel.
```TypeScript
// Import the lerp types from tslerp
import { 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](http://gizma.com/easing/)
Note that the `TsLerpTransition` option is ignored when choosing a Linear style
<br>
* Removed Typings dependency
* 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](http://gizma.com/easing/)
### 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
<br>
# Contribution Guidelines
## Requirements
* [node.js and npm](https://www.npmjs.com/get-npm)
* [Typescript](https://www.npmjs.com/package/typescript) 2.6.2+
## Optional
* [Visual Studio Code](https://code.visualstudio.com/)
* 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](https://travis-ci.org/leewinder/tslerp) tests
* Once passed, the change will be squashed into develop if approved