Ruckig

The Tracking Interface is designed to follow an arbitrary signal (position, velocity, acceleration) closely in time-optimal ways by predicting ahead. This is useful for robot servoing or signal tracking where standard target-setting would cause lag.

To use it online:

1. Construct a Trackig<DOFs> instance with the control cycle.
2. Set the current state and kinematic constraints in InputParameter.
3. In the control loop, call trackig.update(target_state, input, output) where target_state is the signal value at time t.
4. Use output.new_position for control and call output.pass_to_input(input).

To use it offline: Call smooth_trajectory = trackig.calculate_trajectory(target_states, input), where target_states is a std::vector of target states.

// Online tracking example
Trackig<1> trackig {0.01};
input.current_position = {0.0};
input.current_velocity = {0.0};
input.current_acceleration = {0.0};
input.max_velocity = {0.8};
input.max_acceleration = {2.0};
input.max_jerk = {5.0};

for (double t = 0; t < 10.0; t += trackig.delta_time) {
  auto target_state = signal(t); 
  auto res = trackig.update(target_state, input, output);
  // Use output.new_position
  output.pass_to_input(input);
}

// Offline tracking
smooth_trajectory = trackig.calculate_trajectory(target_states, input);

Ruckig uses three main interface classes: Ruckig, InputParameter, and OutputParameter.

To generate trajectories online (e.g., in a real-time control loop), you initialize a Ruckig instance with the number of Degrees of Freedom (DoFs) and the control cycle duration. You then populate the InputParameter with the current state, target state, and kinematic limits.

In each control cycle, call ruckig.update(input, output). If the result is Result::Working, you use the values in output to control your hardware. Crucially, you must call output.pass_to_input(input) at the end of every loop to copy the new kinematic state back into the input for the next iteration. The loop terminates when update returns Result::Finished.

Ruckig<6> ruckig {0.001}; // Number DoFs; control cycle in [s]

InputParameter<6> input;
input.current_position = {0.2, ...};
input.current_velocity = {0.1, ...};
input.current_acceleration = {0.1, ...};
input.target_position = {0.5, ...};
input.target_velocity = {-0.1, ...};
input.target_acceleration = {0.2, ...};
input.max_velocity = {0.4, ...};
input.max_acceleration = {1.0, ...};
input.max_jerk = {4.0, ...};

OutputParameter<6> output;

while (ruckig.update(input, output) == Result::Working) {
  // Make use of the new state here!
  // e.g. robot->setJointPositions(output.new_position);

  output.pass_to_input(input); // Don't forget this!
}

Ruckig's numerical exactness is maintained within specific absolute error tolerances: final position and velocity within 1e-8, final acceleration within 1e-10, and velocity, acceleration, and jerk limits within 1e-12.

To ensure stability, follow these guidelines:

• Scale your inputs: Use units that align with these absolute tolerances. For most real-world systems, using meters [m] instead of millimeters [mm] is recommended, as 1e-8m provides sufficient precision.
• Kinematic Limits: Keep all kinematic limits below 1e9.
• Trajectory Duration: The maximal supported trajectory duration is 7e3. While Ruckig can output values outside this range, correctness is not guaranteed.

If you are using the Ruckig Pro version, you can use position_scale and time_scale in the Calculator class to adjust the internal representation of parameters without affecting the resulting trajectory.

Ruckig<1> ruckig;  // Works also for Trackig

ruckig.calculator.position_scale = 1e2;  // Scales all positions in the input parameters
ruckig.calculator.time_scale = 1e3;  // Scale all times in the input parameters

The Ruckig Community Version supports intermediate waypoints via a cloud API. To use them, you must pre-allocate memory by passing the maximum number of waypoints to the Ruckig, InputParameter, and OutputParameter constructors.

Once allocated, you can set waypoints using input.intermediate_positions.

Note: Using intermediate positions switches the calculation to a non-real-time capable cloud API. For real-time local calculation, the Ruckig Pro Version is required. It is recommended to filter waypoints using ruckig.filter_intermediate_positions to ensure they meet a minimum distance threshold.

Ruckig<6> ruckig {0.001, 8};
InputParameter<6> input {8};
OutputParameter<6> output {8};

input.intermediate_positions = {
  {0.2, ...},
  {0.8, ...},
};

// Recommended: filter waypoints
input.intermediate_positions = ruckig.filter_intermediate_positions(input.intermediate_positions, {0.1, ...});