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.
Why Use TurtleTracerReader?
Section titled “Why Use TurtleTracerReader?”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:
- You save your project as a
.turtfile in TurtleTracer. - You put that file in the robot's assets or storage.
- Your Java code uses
TurtleTracerReaderto 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.
Uploading the File
Section titled “Uploading the File”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.
Usage in Code
Section titled “Usage in Code”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.
1. Initialization
Section titled “1. Initialization”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);2. Retrieving Poses
Section titled “2. Retrieving Poses”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 namesPose 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:
startPointtakes the heading of the first path the robot drives. - Line poses: a line's pose uses its fixed end angle, or
0when 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 asName (1),Name (2)) share the first one's pose. - Control points: Bézier control points are named
<line>_line<index>_control<n>, for examplegreg_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()returnsnullif 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();3. Building Paths
Section titled “3. Building Paths”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());4. Binding Event Markers
Section titled “4. Binding Event Markers”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.
5. Routines With Several Paths
Section titled “5. Routines With Several Paths”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);lineIndexis the line's index in the file, as listed bygetLines().segmentIndexis the line's position within its chain (0for 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.
Mirroring for the Other Alliance
Section titled “Mirroring for the Other Alliance”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.
Best Practices
Section titled “Best Practices”- Naming Conventions: Give your points clear, descriptive names in TurtleTracer (for example
preloadDroporsamplePickup1).TurtleTracerReaderrelies 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.
TurtleTracerReaderis meant for tweaking existing geometry. - Error Handling: The generated code lets the
IOExceptionpass 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.