friction_simulation.dart 4.92 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter Authors. All rights reserved.
2 3 4
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

5 6 7 8
import 'dart:math' as math;

import 'simulation.dart';
import 'tolerance.dart';
9

Ian Hickson's avatar
Ian Hickson committed
10 11 12 13 14 15
/// A simulation that applies a drag to slow a particle down.
///
/// Models a particle affected by fluid drag, e.g. air resistance.
///
/// The simulation ends when the velocity of the particle drops to zero (within
/// the current velocity [tolerance]).
16
class FrictionSimulation extends Simulation {
Ian Hickson's avatar
Ian Hickson committed
17 18 19 20
  /// Creates a [FrictionSimulation] with the given arguments, namely: the fluid
  /// drag coefficient, a unitless value; the initial position, in the same
  /// length units as used for [x]; and the initial velocity, in the same
  /// velocity units as used for [dx].
21 22 23 24
  FrictionSimulation(
    double drag,
    double position,
    double velocity, {
25
    Tolerance tolerance = Tolerance.defaultTolerance,
26 27 28 29 30
  }) : _drag = drag,
       _dragLog = math.log(drag),
       _x = position,
       _v = velocity,
       super(tolerance: tolerance);
Ian Hickson's avatar
Ian Hickson committed
31

Ian Hickson's avatar
Ian Hickson committed
32 33 34 35 36 37 38 39 40 41 42
  /// Creates a new friction simulation with its fluid drag coefficient set so
  /// as to ensure that the simulation starts and ends at the specified
  /// positions and velocities.
  ///
  /// The positions must use the same units as expected from [x], and the
  /// velocities must use the same units as expected from [dx].
  ///
  /// The sign of the start and end velocities must be the same, the magnitude
  /// of the start velocity must be greater than the magnitude of the end
  /// velocity, and the velocities must be in the direction appropriate for the
  /// particle to start from the start position and reach the end position.
Ian Hickson's avatar
Ian Hickson committed
43
  factory FrictionSimulation.through(double startPosition, double endPosition, double startVelocity, double endVelocity) {
44
    assert(startVelocity == 0.0 || endVelocity == 0.0 || startVelocity.sign == endVelocity.sign);
Ian Hickson's avatar
Ian Hickson committed
45 46
    assert(startVelocity.abs() >= endVelocity.abs());
    assert((endPosition - startPosition).sign == startVelocity.sign);
47
    return FrictionSimulation(
Ian Hickson's avatar
Ian Hickson committed
48 49
      _dragFor(startPosition, endPosition, startVelocity, endVelocity),
      startPosition,
50
      startVelocity,
51
      tolerance: Tolerance(velocity: endVelocity.abs()),
52
    );
Ian Hickson's avatar
Ian Hickson committed
53 54
  }

55
  final double _drag;
56
  final double _dragLog;
57 58 59
  final double _x;
  final double _v;

60 61 62 63 64 65 66 67
  // Return the drag value for a FrictionSimulation whose x() and dx() values pass
  // through the specified start and end position/velocity values.
  //
  // Total time to reach endVelocity is just: (log(endVelocity) / log(startVelocity)) / log(_drag)
  // or (log(v1) - log(v0)) / log(D), given v = v0 * D^t per the dx() function below.
  // Solving for D given x(time) is trickier. Algebra courtesy of Wolfram Alpha:
  // x1 = x0 + (v0 * D^((log(v1) - log(v0)) / log(D))) / log(D) - v0 / log(D), find D
  static double _dragFor(double startPosition, double endPosition, double startVelocity, double endVelocity) {
68
    return math.pow(math.e, (startVelocity - endVelocity) / (startPosition - endPosition)) as double;
69 70
  }

71
  @override
72
  double x(double time) => _x + _v * math.pow(_drag, time) / _dragLog - _v / _dragLog;
73

74
  @override
75
  double dx(double time) => _v * math.pow(_drag, time);
76

77
  /// The value of [x] at `double.infinity`.
78 79 80 81
  double get finalX => _x - _v / _dragLog;

  /// The time at which the value of `x(time)` will equal [x].
  ///
82
  /// Returns `double.infinity` if the simulation will never reach [x].
83 84 85 86
  double timeAtX(double x) {
    if (x == _x)
      return 0.0;
    if (_v == 0.0 || (_v > 0 ? (x < _x || x > finalX) : (x > _x || x < finalX)))
87
      return double.infinity;
88 89 90
    return math.log(_dragLog * (x - _x) / _v + 1.0) / _dragLog;
  }

91
  @override
92
  bool isDone(double time) => dx(time).abs() < tolerance.velocity;
93
}
94

95
/// A [FrictionSimulation] that clamps the modeled particle to a specific range
Ian Hickson's avatar
Ian Hickson committed
96
/// of values.
97
class BoundedFrictionSimulation extends FrictionSimulation {
Ian Hickson's avatar
Ian Hickson committed
98 99 100 101 102 103 104
  /// Creates a [BoundedFrictionSimulation] with the given arguments, namely:
  /// the fluid drag coefficient, a unitless value; the initial position, in the
  /// same length units as used for [x]; the initial velocity, in the same
  /// velocity units as used for [dx], the minimum value for the position, and
  /// the maximum value for the position. The minimum and maximum values must be
  /// in the same units as the initial position, and the initial position must
  /// be within the given range.
105 106 107 108
  BoundedFrictionSimulation(
    double drag,
    double position,
    double velocity,
Hixie's avatar
Hixie committed
109
    this._minX,
110
    this._maxX,
111 112
  ) : assert(position.clamp(_minX, _maxX) == position),
      super(drag, position, velocity);
113 114 115 116

  final double _minX;
  final double _maxX;

117
  @override
118
  double x(double time) {
119
    return super.x(time).clamp(_minX, _maxX) as double;
120 121
  }

122
  @override
123 124 125 126 127 128
  bool isDone(double time) {
    return super.isDone(time) ||
      (x(time) - _minX).abs() < tolerance.distance ||
      (x(time) - _maxX).abs() < tolerance.distance;
  }
}