Skip to content

Typescript library for lerping single and multi-sample data sets over time

License

Notifications You must be signed in to change notification settings

leewinder/tslerp

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

46 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

tslerp

Typescript library for lerping single and multi-sample data sets over time across a variety of styles and transitions.

Build Status

npm version

Master Branch

Build Status Dependency Status

Develop Branch

Build Status


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 linear

Style: Quadratic

Transition: Ease In

quad in

Transition: Ease Out

quad out

Transition: Ease In and Out

quad in out

Style: Sine

Transition: Ease In

sine in

Transition: Ease Out

sine out

Transition: Ease In and Out

sine in out

Cubic

Transition: Ease In

cube in

Transition: Ease Out

cube out

Transition: Ease In and Out

cube in out

Style: Exponential

Transition: Ease In

expo in

Transition: Ease Out

expo out

Transition: Ease In and Out

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

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

Optional

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

About

Typescript library for lerping single and multi-sample data sets over time

Resources

License

Stars

Watchers

Forks

Packages

No packages published