Skip to content

TurtleTracerReader

The TurtleTracerReader class is a utility in TurtleTracerLib for teams that use the Command-Based code export from TurtleTracer. It lets your robot read poses (points) from a .turt file stored on the robot, so the path geometry doesn't live in your Java code.

In the standard OpMode export, every X, Y, and heading value is written into your Java file. Any small tweak to a curve means exporting the code again, pasting it into Android Studio, and rebuilding the app.

TurtleTracerReader changes this workflow:

  1. You save your project as a .turt file in TurtleTracer.
  2. You put that file in the robot's assets or storage.
  3. Your Java code uses TurtleTracerReader to read the named points.

If you need to adjust a path at a competition, change it in TurtleTracer, save the .turt file, upload it to the robot, and run. No recompiling required.

Before you can read a file, it must be on the robot. The simplest option is to put .turt files in TeamCode/src/main/assets/AutoPaths.

When you use the Command-Based (SolversLib, NextFTC or Ivy) export option in TurtleTracer and leave Embed Pose Data off, the generated code already includes TurtleTracerReader.

Pass the name of the uploaded file and the hardware map's application context. This can throw an IOException if the file isn't found, so handle or declare it.

import com.turtletracerlib.TurtleTracerReader;
import com.qualcomm.robotcore.hardware.HardwareMap;
import java.io.IOException;
// Inside your OpMode or CommandGroup constructor:
public AutoPath(HardwareMap hw) throws IOException {
// Look for "AutoPath.turt" on the robot's storage
TurtleTracerReader reader = new TurtleTracerReader("AutoPath.turt", hw.appContext);
}

If the file isn't an Android asset, the reader also accepts an InputStream, a Reader, or the raw JSON as a String:

TurtleTracerReader fromStream = new TurtleTracerReader(inputStream);
TurtleTracerReader fromJson = new TurtleTracerReader(jsonString);

Once initialized, get any Pose by the name you gave the point or path in TurtleTracer.

import com.pedropathing.math.Pose;
// Retrieve points by their string names
Pose startPoint = reader.get("startPoint");
Pose point1 = reader.get("point1");
Pose scoringPosition = reader.get("ScoringPosition");

Poses are Pedro field coordinates, the same numbers TurtleTracer writes into generated code. They are worked out from the file's start point and lines, so nothing in the file is stored twice.

  • Start pose: startPoint takes the heading of the first path the robot drives.
  • Line poses: a line's pose uses its fixed end angle, or 0 when the robot follows the path.
  • Names: everything except letters and digits is dropped, and a line with no name is called point<n>. This matches the names the generated code asks for. Lines linked under one name (saved as Name (1), Name (2)) share the first one's pose.
  • Control points: Bézier control points are named <line>_line<index>_control<n>, for example greg_line1_control1, so two lines with the same name don't overwrite each other. The older <line>_control<n> form still returns the first line with that name.
  • Missing names: get() returns null if no pose has that name.

You can also read everything the file holds: getAllPoses(), getStartPoint(), getLines(), getSequence(), getShapes(), getHeader(), and getVersion(). For example, this prints each path's name and end point to the Driver Station:

for (TurtleTracerReader.TurtleTurt.Line line : reader.getLines()) {
telemetry.addData(line.name, "(%.1f, %.1f)", line.endPoint.x, line.endPoint.y);
}
telemetry.update();

After retrieving the poses, build your path with Pedro Pathing:

import com.pedropathing.api.Paths;
import com.pedropathing.paths.Path;
// ...
follower.setPose(startPoint);
Path startPointTOpoint1 = Paths.line(startPoint, point1)
.linear(startPoint.heading(), point1.heading());

Bind Java actions to event markers defined in the visualizer:

import com.turtletracerlib.pathing.ProgressTracker;
reader.onEvent("IntakeMarker", () -> intake.start())
.onEvent("ScoreMarker", () -> outtake.score());
// Registers every marker in the file and binds its action to the tracker:
reader.registerEvents(progressTracker);

The reader maps each marker to the right event type from the file: parametric markers become progress triggers, temporal markers become timers, and pose markers become proximity triggers. If you didn't bind an action with onEvent, the marker looks up a command registered in NamedCommands.

registerEvents registers the markers of every line at once. In a routine that follows several paths in a row, each marker could then trigger during whichever path happens to be running.

For those routines, register one line at a time. Clear the previous path's events, register the next line's markers, then set the path:

progressTracker.clearPathEvents();
reader.registerLineEvents(progressTracker, lineIndex, segmentIndex);
progressTracker.setCurrentPath(nextPath);
  • lineIndex is the line's index in the file, as listed by getLines().
  • segmentIndex is the line's position within its chain (0 for a path that isn't chained). Parametric progress is reported per segment, so this keeps a marker from triggering on the wrong segment of a chain.

The generated command-based and Java code already does this for you. See ProgressTracker for clearPathEvents() and segment-scoped events.

To run a path drawn for one alliance on the other, give the reader a mirror. It usually comes from the Auto Selector:

TurtleTracerReader reader = new TurtleTracerReader("AutoPath.turt", hw.appContext)
.mirrored(ctx.mirror());

After that, get(), getAllPoses() and pose event markers return mirrored poses. The raw file data from getStartPoint(), getLines() and getShapes() stays as it was saved. If you don't call mirrored, or pass null, nothing is mirrored.

  • Naming Conventions: Give your points clear, descriptive names in TurtleTracer (for example preloadDrop or samplePickup1). TurtleTracerReader relies on these names, with punctuation removed.
  • File Updates: If you change the structure of your path (adding segments, or renaming points), export the code again. TurtleTracerReader is meant for tweaking existing geometry.
  • Error Handling: The generated code lets the IOException pass up the chain. In a competition setup you may want to catch it and show a telemetry message so drivers know the file is missing before they press Start.