ProgressTracker
The ProgressTracker is a utility class in TurtleTracerLib that tracks the completion percentage of a path or a turning operation. Its primary purpose is to simplify triggering mechanism events (such as moving an arm or spinning an intake) based on how far the robot has traveled along its trajectory.
Overview
Section titled “Overview”The tracker monitors robot traversal and evaluates registered events against progress, time, or field position thresholds.
Key features include:
- Path Progress: Tracks parametric progress along the current curve segment (
getPathProgress(), 0.0 to 1.0). - Total Progress: Tracks overall completion across the path (
getTotalProgress()/getCompletion(), 0.0 to 1.0). - Turn Progress: Tracks angular progress during in-place turns.
- Fluent Events: Register parametric, temporal, and spatial events directly on the tracker.
- Chained Paths: Scope events to one segment of a chain, and clear one path's events before the next.
- Loop Execution:
tracker.update()evaluates and executes events safely during your OpMode loop.
Basic Usage
Section titled “Basic Usage”To use ProgressTracker, instantiate it, register events or actions, and call tracker.update() in your OpMode loop.
1. Initialization
Section titled “1. Initialization”Create an instance of ProgressTracker, passing it your Follower and the OpMode's Telemetry.
import com.turtletracerlib.pathing.ProgressTracker;// ...
public class MyAuto extends OpMode { private Follower follower; private ProgressTracker progressTracker;
@Override public void init() { follower = Constants.create(hardwareMap); // ... progressTracker = new ProgressTracker(follower, telemetry); }}2. Registering Events
Section titled “2. Registering Events”Before starting a path or turn, register the events you want to trigger.
// Set the path to follow (Pedro Pathing 3.0 Path)progressTracker.setCurrentPath(myPath);
// Register an event named "DeployIntake" to trigger halfway through the path (0.5)progressTracker.registerEvent("DeployIntake", 0.5);
// Start followingfollower.follow(myPath);3. Checking for Triggers
Section titled “3. Checking for Triggers”In your loop(), you can call tracker.update() to evaluate and execute events automatically:
@Overridepublic void loop() { follower.update(); progressTracker.update(); // Evaluates and executes registered events safely}Or you can manually poll shouldTriggerEvent() for specific events:
@Overridepublic void loop() { follower.update();
if (progressTracker.shouldTriggerEvent("DeployIntake")) { // Option A: Execute code directly here intake.deploy();
// Option B: If "DeployIntake" is registered in NamedCommands, // you can use executeEvent() to schedule it automatically progressTracker.executeEvent("DeployIntake"); }}Fluent Events
Section titled “Fluent Events”You can attach actions directly to the tracker using fluent event methods:
// Parametric: triggers at 75% along the current curveprogressTracker.onParametric(0.75, () -> intake.start());
// Parametric range: triggers between 30% and 60%progressTracker.onParametric(0.3, 0.6, () -> lights.blink());
// Path completion: triggers at 80% of total pathprogressTracker.onCompletion(0.8, () -> arm.prepareScore());
// Temporal: triggers 500 ms after the path beginsprogressTracker.onTemporal(500, () -> arm.lift());
// Spatial: triggers within 2 inches of a target field poseprogressTracker.onSpatial(new Pose(24.0, 48.0, Math.toRadians(90)), 2.0, () -> claw.open());
// Named: maps to markers placed in the Turtle Tracer visualizerprogressTracker.onEvent("IntakeMarker", () -> intake.start());Event callbacks executed by progressTracker.update() run inside safe exception handling, logging any error to System.err without disrupting the follower.
Chained Paths and Several Paths in a Row
Section titled “Chained Paths and Several Paths in a Row”The follower reports progress per segment, so on a chained path the same threshold would trigger on whichever segment reaches it first. Two tools keep events on the right path.
Segment-Scoped Events
Section titled “Segment-Scoped Events”Pass the segment's index in the chain (0 is the first path) to onParametric. The event only counts progress while the follower is on that segment:
// Triggers at 75% of the second path in the chainprogressTracker.onParametric(1, 0.75, () -> intake.start());
// Range version: active between 30% and 60% of the second pathprogressTracker.onParametric(1, 0.3, 0.6, () -> lights.blink());Clearing a Path's Events
Section titled “Clearing a Path's Events”If you register events one path at a time, call clearPathEvents() before registering the next path's events. It removes the current path's parametric, temporal, spatial, and named-zone events, and keeps the actions you bound with onEvent.
progressTracker.clearPathEvents();progressTracker.onParametric(0.5, () -> arm.lift());progressTracker.setCurrentPath(nextPath);Example: Several Paths in a Row
Section titled “Example: Several Paths in a Row”TurtleTracer's Java export uses these methods in its state machine. Each time a path starts, the previous path's events are cleared, that path's events are registered, and the new path is set:
case 0: follower.follow(paths.DriveToShoot); tracker.clearPathEvents(); tracker.onParametric(0, 0.400, NamedCommands.getCommand("SpinUp")); tracker.setCurrentPath(paths.DriveToShoot); setPathState(1); break;case 1: if (!follower.isBusy()) { setPathState(2); } break;case 2: follower.follow(paths.ReturnToShoot); tracker.clearPathEvents(); tracker.onParametric(0, 0.500, NamedCommands.getCommand("Intake")); tracker.setCurrentPath(paths.ReturnToShoot); setPathState(3); break;Call tracker.update() in your loop() alongside follower.update().
When you load events from a .turt file, TurtleTracerReader.registerLineEvents(...) does the registering for one line. See TurtleTracerReader.
setCurrentPath() also ends any turn the tracker was following. A new path therefore can't be held up by a turn that was never seen finishing.
Integration with NamedCommands
Section titled “Integration with NamedCommands”If you have registered a command with NamedCommands that matches the name of a registered event, calling progressTracker.executeEvent(eventName) will automatically retrieve and run that command.
// Somewhere in your init()NamedCommands.registerCommand("ScoreSample", () -> scoreSample());
// ... later, setting up a path ...progressTracker.setCurrentPath(scoringPath);progressTracker.registerEvent("ScoreSample", 0.9); // Trigger near the end
// ... in your loop() ...if (progressTracker.shouldTriggerEvent("ScoreSample")) { progressTracker.executeEvent("ScoreSample");}Tracking Turns
Section titled “Tracking Turns”The ProgressTracker also simplifies event triggering during in-place turns.
Use the turn() method on the tracker to start a turn and register an event based on the turn's completion percentage.
// Turn to 90 degrees (PI/2 radians) and trigger "RaiseLift" when 75% completeprogressTracker.turn(Math.PI / 2, "RaiseLift", 0.75);
// In your loop:while (opModeIsActive() && progressTracker.isBusy()) { follower.update(); progressTracker.update();}turn() marks the follower busy again as it starts, so a turn straight after a finished path is tracked from the start instead of looking complete immediately (fixed in v3.0.1).
Reading Progress Values
Section titled “Reading Progress Values”You can read raw progress values directly from the tracker:
// Returns 0.0 to 1.0 for the current individual path segmentdouble currentSegmentPercent = progressTracker.getPathProgress();
// Returns 0.0 to 1.0 for the entire pathdouble totalProgress = progressTracker.getTotalProgress();double completion = progressTracker.getCompletion();Stopping
Section titled “Stopping”To stop path following or turning:
progressTracker.stop();
// breakFollowing() is supported as an aliasprogressTracker.breakFollowing();