tslerp

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

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

1. Add tslerp to both your map and packages structures in systemjs.config.js

var map = {
  ...
  'tslerp': 'node_modules/tslerp'
};

var packages = {
  ...
  'tslerp': { main: 'index.js', defaultExtension: 'js' },
};

1. 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

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 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.
  }
}

Chaining lerp sequences

// 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);
      });
    }
  }
}

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 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()
    
    ...
  }
}

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 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

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