Trees       Indices       Help   
Package joy :: Module plans :: Class StickFilter
[hide private]
[frames] | no frames]

Class StickFilter

source code


StickFilter Plans are event processors designed to simplify the problem of
processing joystick and midi readings into continuous-time values.

The problem arises because pygame joystick events appear only when joystick
values change -- even if they are far from 'zero'. This means that triggering
actions directly from joystick events can lead to rather erratic responses.

StickFilter solves this problem by simulating the behavior of a regularly
sampled time-series for each incoming event type. All these time series
have the same sample interval (self.dt), but a different linear transfer 
function can be associated with the values in each channel.

In particular, StickFilter provides methods to lowpass filter joystick 
readings or to integrate them. The former is used to limit the "jerkiness"
of controller requests, whereas the latter is used to control velocity
with the joystick instead of position.

Channel Names
-------------

Currently, StickFilter supports the channel name schemata listed below.
Any given channel will only be instantiated if a filter is set for it
and the related events are .push()-ed into the StickFilter plan.

The schemata:
joy<joystick-number>ball<ball-number>
joy<joystick-number>hat<hat-number>
joy<joystick-number>axis<axis-number>, e.g. joy0axis1, for joystick events
Nx<node-id-2-HEX-digits>, e.g. Nx3C, for CKBOTPOSITION events
midi<dev-number>sc<scene><kind><index-number> MIDI input device
Instance Methods [hide private]
 
__init__(self, app, t0=None, dt=0.1)
Initialize a StickFilter		 source code
 
setLowpass(self, evt, tau, t0=None, func=float)
Process evt events with a first-order lowpass with time constant tau.		 source code
 
setIntegrator(self, evt, gain=1, t0=None, lower=-1e9, upper=1e-9, func=float)
Process evt events with a (leaky) integrator first-order lowpass with time constant tau.		 source code
 
setFilter(self, evt, t0=None, A=[1.0], B=[1.0], x0=None, y0=None, lower=-1e9, upper=1e9, func=float)
Specify a filter for an event channel.		 source code
 
feed(self, evt)
Feed an event into the StickFilter.		 source code
 
setToZero(self, evt)
Set a specific filter to zero Sets all previous state variables (X, Y) to zero		 source code
 
_runFilterTo(self, flt, t)
(private)		 source code
 
getValue(self, evt)
Obtain the filtered value for an event channel by using an event object or the string name of the event.		 source code
 
getterOf(self, evt)
Obtain a getter function for an event channel		 source code
 
onEvent(self, evt)
(final)		 source code
 
behavior(self)
(final)		 source code

Inherited from Plan: forDuration, isRunning, onStart, onStop, push, start, step, stop, untilTime

Inherited from Plan (private): _initBindings, _oneStep, _stepDoEvents, _stepNewSub, _unwind

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Class Methods [hide private]
 
nameValFor(cls, evt)
Generate channel name (a string) from an event object		 source code
Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self, app, t0=None, dt=0.1)
(Constructor)

source code 

Initialize a StickFilter

Overrides: object.__init__

setLowpass(self, evt, tau, t0=None, func=float)

source code 

Process evt events with a first-order lowpass with time constant tau.

Uses an approximation to the Butterworth construction

setIntegrator(self, evt, gain=1, t0=None, lower=-1e9, upper=1e-9, func=float)

source code 

Process evt events with a (leaky) integrator first-order lowpass with time constant tau.

By default, integrator is not leaky.

setFilter(self, evt, t0=None, A=[1.0], B=[1.0], x0=None, y0=None, lower=-1e9, upper=1e9, func=float)

source code  

Specify a filter for an event channel.

The filter equation is given by:
   A[0]*y[n] = B[0]*x[n] + B[1]*B[n-1] + ... + B[nb]*x[n-nb]
                         - A[1]*y[n-1] - ... - A[na]*y[n-na]

or, in terms of transfer functions:
                                      nb
        B[0] + B[1] z + ... + B[nb] z 
   Y = ------------------------------------ X
                                      na
        A[0] + A[1] z + ... + A[na] z 

INPUTS:
  evt -- event object from channel, or its name as string
  t0 -- float -- initial time to start channel, or None to use self.app.now
  A,B -- sequences of floats -- transfer function
  x0 -- sequence of len(B) floats -- initial state of x values (default 0-s)
  y0 -- sequence of len(A) floats -- initial state of y values (default 0-s)
  lower -- number -- lower limit on filter values (saturation value)
  upper -- number -- upper limit on filter values (saturation value)
  func -- callable -- input mapping applied to channel values before filtering

feed(self, evt)

source code  

Feed an event into the StickFilter.
Retrieves value and puts it on input queue for filter 

INPUT:
  evt -- EventType object

setToZero(self, evt)

source code  

Set a specific filter to zero
Sets all previous state variables (X, Y) to zero

INPUT:
  evt -- EventType object or string name of event channel

_runFilterTo(self, flt, t)

source code  
(private)

run filter off input in its queue until time t
INPUT:
    flt -- a filter state
    t -- float -- time

onEvent(self, evt)

source code 

(final)

Handle incoming events. Timer events allow the filters to update state; other events are pushed into the filters with .feed() and do not require the behavior() to run (hence return False).

Overrides: Plan.onEvent

behavior(self)

source code 

(final)

Runs periodically every dt time units.

Evolves states of all filters up to the current time.

Overrides: Plan.behavior

   Trees       Indices       Help   
Generated by Epydoc 3.0.1 on Thu Jan 4 16:46:17 2018 http://epydoc.sourceforge.net