PivotField

This field unit generates a spatial response curve based on a pivot point around which the field transitions happens. It can output sharp steps, smooth ramps, bumps or notches, across the normalized range [0, 1], making it ideal for creating animations on arrays of actuators such as LEDs or motors (eg. VU-meters, fades, or envelope-like visualizations).

Modes

The behavior of the field is defined by its mode:

  • PIVOT_FALLING (default): Values are 1.0 from the left up to the pivot, then fall to 0.0.

  • PIVOT_RISING : Values are 0.0 on the left and rise to 1.0 after the pivot.

  • PIVOT_BUMP: Peak at the pivot: 1.0 around the pivot, tapering down on both sides.

  • PIVOT_NOTCH: Inverse of PIVOT_BUMP: 0.0 around the pivot, 1.0 elsewhere.

Adjustments

The curve can be finely configured using many different parameters:

  • rampWidth: Ramp width as a fraction of total range (e.g., 0.2 for 20% width). Default: 0 (no ramp).

  • center: Point from which the curve starts (in [0, 1]). Examples:

    • 0.0 (default) Start from left side.

    • 0.5 Start from middle going in both directions.

    • 0.75 Start from ¾ (75%) going in both directions.

    • 1.0 Start from right side.

  • easing: Optional easing function applied to the ramp. Default: easeNone.

  • rampShift: Determines the horizontal shift of the ramp. Examples:

    • 0.0 Ramp ends at the pivot point.

    • 0.5 (default) Ramp is right in the middle of the pivot point.

    • 1.0 Ramp starts at the pivot point.

  • bumpWidth: When choosing PIVOT_BUMP or PIVOT_NOTCH, determines the width of the peak. Default: 0.25 (25%).

Example

This example uses a single PWM analog LED and two potentiometers to show the behavior of a PivotField. The first potentiometer is used to control the pivot point, then the second potentiometer is used to reveal the values of the PivotField from 0 to 1.

#include <Plaquette.h>

// Potentiometer #1 to control the pivot point.
AnalogIn pot(A0);

// Potentiometer #2 for exploring the field.
AnalogIn slider(A1);

// The PWM LED.
AnalogOut led(9);

// The pivot field.
PivotField field;

void begin() {
  // Parameters. Change at will to explore different configurations.
  field.rampWidth(0.2);
  field.easing(easeInSine);
  field.mode(PIVOT_FALLING); // default
  field.center(0); // default
  field.bumpWidth(0.25); // default
}

void step() {
  // Send potientiometer value to the pivot field.
  pot >> field;

  // Send field value at position of slider to LED.
  field.at(slider) >> led;
}

Reference

class PivotField : public AbstractField

Public Functions

PivotField()

Constructor.

inline virtual ~PivotField()
virtual float at(float proportion) override

Returns value at given proportion in [0, 1].

Parameters

proportion – the proportion of the field to read

Returns

the value

inline virtual float get() override

Returns value.

inline virtual float put(float value) override

Pushes value into the unit.

Parameters

value – the value sent to the unit

Returns

the new value of the unit

inline void mode(PivotFieldMode mode)

Sets mode to use.

Parameters

mode – the mode to set

inline PivotFieldMode mode() const

Returns mode.

inline void easing(easing_function easing)

Sets easing function to apply to ramp.

Parameters

easing – the easing function

inline void noEasing()

Remove easing function (linear/no easing).

void rampWidth(float rampWidth)

Sets ramp width as % of field range.

Parameters

rampWidth – the ramp width in [0, 1]

inline void noRampWidth()

Removes ramp width.

inline float rampWidth() const

Returns ramp width.

void rampShift(float rampShift)

Sets ramp shift in [0, 1] (default: 0.5 = center).

Parameters

rampShift – the ramp shift in [0, 1]

inline float rampShift() const

Returns ramp shift.

void bumpWidth(float bumpWidth)

Sets bump width as % of field range.

Only applies to PIVOT_BUMP and PIVOT_NOTCH modes.

Parameters

bumpWidth – the bump width in [0, 1]

inline float bumpWidth() const

Returns bump width.

inline void center(float center)

Sets center of the ramp in [0, 1].

Parameters

center – the center in [0, 1]

inline float center() const

Returns center of the ramp.

template<typename T>
inline void populate(T *array, size_t size, bool wrap = false)

Fills an array with values from this field.

Parameters

  • array – the array to read into

  • size – the size of the array

  • wrap – if true, the array is considered to be a circular buffer that wraps around

virtual void clearEvents()
inline float seconds() const

Returns engine time in seconds.

inline uint32_t milliSeconds() const

Returns engine time in milliseconds.

inline uint64_t microSeconds() const

Returns engine time in microseconds.

inline unsigned long nSteps() const

Returns number of engine steps.

inline float sampleRate() const

Returns engine sample rate.

inline float samplePeriod() const

Returns enginesample period.

inline operator float()

Object can be used directly to access its value.

inline virtual float mapTo(float toLow, float toHigh)

Maps value to new range.

This function guarantees that the value is within [toLow, toHigh]. If the unit’s values are unbounded, returns get() constrained to [toLow, toHigh].

inline explicit operator bool()

Operator that allows usage in conditional expressions.

Public Static Functions

static inline bool analogToDigital(float f)

Converts analog (float) value to digital (bool) value.

static inline float digitalToAnalog(bool b)

Converts digital (bool) value to analog (float) value.

See Also