The SleipnirGroup team of developers is ready to release the open beta of Choreo for the 2025 season!
Please check the linked “Solution” post for the latest release, or find it on our releases page.
What Is Choreo?
Choreo (Constraint-Honoring Omnidirectional Route Editor and Optimizer, pronounced /koʊˈɹiːoʊ/, like K + “Oreo”) is a graphical tool for planning time-optimized trajectories for the FRC autonomous mode. Each trajectory takes full advantage of the drivetrain’s performance, while obeying its dynamics constraints, such as top speed and maximum acceleration on each module. Choreo provides a variety of additional constraints that affect the generated trajectory, such as waypoints, keep-in and keep-out zones, limits on speed and acceleration, etc. Choreo provides a vendor library to load and follow the trajectories, but they are also compatible with PathPlannerLib.
Thank you to all the teams that used Choreo in 2024 and shared your needs, struggles, and suggestions for improvement. Our work for 2025 has focused on many issues and enhancements.
General
Math Expressions with Variable and Unit Support:
This feature addresses a few struggles in 2024 Choreo:
-
Default units (SI, radians) being inflexible, unintuitive, and forcing the user to convert by hand.
-
No good way to define field constants or waypoint locations that are shared among all trajectories.
-
No good way to define robot configuration in terms of other constants (i.e. bumper size and module placement in terms of frame size.
To improve user experience, we have replaced almost every number input in the application with mathematical expression inputs, powered by mathJS. MathJS has full dimensional analysis awareness, allowing inputs to be specified in whichever unit you like, and rejecting inputs that are not dimensionally correct. Choreo will also save the expression as you typed it, instead of evaluating and discarding it at the moment of submission.
Furthermore, Choreo allows you to define a project-wide set of variables that can be substituted into any appropriate expression in the project. Variables can be defined as single numbers with a variety of dimensions, but Choreo also has aggregate variables to organize the x, y, and heading components of an important pose.
The expression and variable features open up a wide range of capabilities, similar to parametric sketches in a CAD program. We’re excited to see how teams use these new tools.
Robot Config
Support for non-centered/non-rectangular modules
Choreo 2024 asked for a wheelbase, track width, bumper length, and bumper width. This described many robots, but especially in 2024, many robots had intakes that made the bumpers not centered at the center of rotation, or they had module placement that was not centered or even rectangular. Choreo 2025 makes robot configuration more flexible, permitting and honoring these configurations.
NOTE: due to path mirroring, Choreo 2025 still only supports module and bumper dimensions that are symmetric across the robot x-axis (the front-back line, meaning left-right mirror symmetry). In robot configuration, users only edit the left side of the robot dimensions.
The user interface design for robot configuration is an area of planned improvement.
Generation
Command-Line Generation
Choreo now ships with a command-line tool that takes in a .chor file and one or more associated .traj, and generates the .traj files, modifying them in-place. Further details will be described in the docs.
Fix Inability to Cancel Generation
This issue was inherent to the architecture of Choreo, but through the architecture changes related to command-line generation, we were able to make generation individually cancelable at any point.
(Proper) Continuous Heading Support
Choreo 2025 modifies the internal logic of the solver to handle robot rotation as a unit vector instead of an angle number. This allows Choreo to take the fastest rotational movement, even if it would previously wrap -pi to pi. Therefore, heading initial guesses are not as important to manually tweak.
Waypoints
Heading Initial Guess
Choreo 2025 removes the ability to set the heading initial guess on translation and empty waypoints. Due to the above improvements to the solver, and other logic implemented to automatically calculate heading initial guesses, the feature was unnecessary, counterproductive, and cluttered the UI.
Remove Initial Guess Points
Choreo 2025 removes the (non-constrainable) initial guess point waypoint type and subsumes its functionality into the Empty Waypoint, whose location can be constrained using Keep-In or Keep-Out Zones. The Empty Waypoint can be the endpoint of a path, but not the start point.
Individual Sample Override
Instead of a default sample override being applied to an entire path, with the same number of samples for each waypoint, Choreo 2025 has a checkbox on each waypoint to specify an individual override between that waypoint and the next.
Constraints
Interactive Constraint Overlay
The user interface for adding and editing constraints has been revised. Previously, a click target for adding a constraint was at every waypoint and the midpoint of every segment. Now, click one waypoint, then click the other, without the UI clutter.
When a constraint is selected, the field highlights the range it applies to. For constraints with additional field points/lines to modify (currently Point At and Keep In/Out Zones), the field will also display draggable field objects tied to the constraint.
The display also shows when hovering over the constraint in the sidebar.
Keep-In Zones/Field Border Constraint
Choreo 2025 adds a new type of constraint, which is a zone (currently rectangle or circle) that the robot must stay entirely inside, including the bumpers, for the duration of the constraint scope. For the first beta, a Keep-In Rectangle the size of the field will be part of new paths. If and when arbitrary (convex) polygons are supported as Keep-In zones, functionality will be added to add a polygon that better fits the field border.
Obstacles (Keep-Out Zones) as Constraints
Obstacles have been changed to be part of the constraints system and renamed to Keep-Out zones for consistency. While the solver still struggles in some obstacle setups, the ability to apply the constraint to only a section of the path makes the problem more feasible.
Toggleable Constraints
Choreo 2025 adds a checkbox to each constraint that allows the constraint to be disabled without being deleted. This can be useful for comparing the effects of individual constraints.
Generation Pre-checks/Feedback
Choreo 2025 expands the additional checks on the trajectory, performed before starting the solver, which are intended to identify conflicting constraints and other causes of infeasibility. New checks include:
-
Verifying that Pose waypoints under Point-At constraints are compliant
-
Verifying that 0 Max Angular Velocity constraints do not conflict with Pose waypoints with differing headings
-
More to come!
Path Splitting
Splitting Paths
Splitting paths was previously done through a project-wide switch that made every Stop Point constraint be a path splitting point. In 2025, the Stop Point constraint is entirely separate from splitting. Every waypoint except for path endpoints has a checkbox which can be used to mark a waypoint as a split point. NOTE: Choreo does not enforce stopping at split points, but for most usage, adding a Stop Point constraint is still advised.
Artifacts
The releases now have many more artifacts than last year.
We support Windows arm64 and x86_64, MacOS aarch64 and x86_64, and Linux x86_64.
Users should normally be downloading the -setup installers for Windows, the .dmg for MacOS, and the AppImage, .deb for Debian and Ubuntu, or .rpm for Fedora.
For each platform, there is a separate executable for command-line generation. We hope to find a way to put the command-line functionality into the main Choreo app.
Finally, we have standalone executables. These are generated for potential bundling with WPILib 2025 and are not the recommended way of installing Choreo.
Choreolib
ChoreoLib 2025 Beta is compatible with WPILib 2024.
Python
ChoreoLib 2025 officially supports Python at PyPI (sleipnirgroup-choreolib). This is new for 2025.
C++/Java
For C++ and Java, the vendordep link is specific to 2025 betas. You will have to remove the existing 2024 vendordep. The API is similar, but breaking in many ways.
https://sleipnirgroup.github.io/ChoreoLib/dep/ChoreoLib2025Beta.json
Features
ChoreoLib 2025.0.0-beta-1 includes the following features.
| Feature | Python | Java | C++ |
|---|---|---|---|
| Load Differential Trajectories | Yes | Yes | Yes |
| Load Swerve Trajectories | Yes | Yes | Yes |
| Mirror Samples | Yes | Yes | Yes |
| Get Split Section of Trajectory | No | Yes | Yes |
| Get Event Marker by Name | No | Yes* | Yes* |
| Basic Following Command Factory | No | Yes* | Yes* |
*Event markers and commands are part of our autonomous routine builder framework. This section of the library is functional in C++ and Java, but is still especially subject to API change.
Beta Roadmap
Docs Revision
The docs at Home - Choreo Documentation will be updated over the coming months.
Event Markers
We plan to re-add support for PathPlannerLib-compatible event markers, as well as a new type of event marker that can be used with upcoming ChoreoLib changes to trigger commands.
Differential Drive Support
Much of the infrastructure required to support differential drive robots is already in place. However, the optimizer algorithm for it is not working as of beta 1. Thus, differential drive is considered a Work in Progress for beta 1. We plan to fix the issues with differential drive generation before the full release.
ChoreoLib: Trigger-based Auto Routines
Along with the triggers for event markers, ChoreoLib will feature functionality to build auto routines as loosely coupled commands using Triggers. This can be useful for branching autos or other composability benefits.
UI Features for Variables QoL
We plan to improve the user experience regarding editing variables and using them in expression inputs.
UI Features for Robot Config
We plan to make the robot configuration panel more intuitive and graphical.
Lane Constraint replaces Straight Line Constraint
The Straight Line Constraint will be replaced with a Lane Constraint, which is effectively an infinitely long keep-in zone for the center of the robot only. This gives a variable tolerance on the line.
File Schema Redesign
NOTE: Choreo 2025 has no backwards compatibility to upgrade Choreo 2024 projects.
Choreo 2025 solves a few issues related to the design choices of .chor and .traj files in 2024.
-
The prior design, where all “source” data is in one monolithic .chor file, caused issues with auditing changes and merge conflicts in version control.
-
Furthermore, the practice of exporting split trajectories as individual .traj files was fragile and depended on file system operations to find all the sections.
-
Finally, the design that put the .chor file in project root and the .traj files in the deploy directory required logic to determine the relative path between the project root and deploy directory. This logic was difficult to maintain and interfered with testing outside a robot project.
-
With the addition of event markers, .traj files had to be updated at times other than successful generations.
-
The .chor had to save the last generation and a portion of the data used to generate it, for rendering purposes. This duplicated significant information.
-
Without a full snapshot of the last generation’s input, the logic to determine if the trajectory needed to be regenerated was hacky and based on the undo history.
To address the above issues, Choreo 2025 uses the following schema:
.chor:
-
Holds the robot config and the project-wide variables, as well as other project-wide settings.
-
Now is placed adjacent to the .traj files.
-
Both .chor and .traj should be in the deploy/choreo directory for robot code integration.
.traj:
-
Describes one continuous trajectory per Choreo “path”. Due to the splitting feature, a single .traj file also contains sample indices which robot libraries can use to split the trajectory.
-
Is both an input and output file for the app. Deleting the .traj deletes the path completely.
-
Except for project-wide information in the .chor, it contains all necessary information for Choreo to present, edit, and generate the trajectory, and for the robot code to load and follow it.
NOTE:
- For debugging purposes, we will now need the full directory including both .chor and all .traj. We have a function in Choreo (“Export Diagnostic Report” in the main menu) to produce a .zip of the project files and program logs, which may be requested when asking for support.
Final Notes
Please feel free to share any issues or feedback in our issue tracker. We appreciate everyone who helps us continue to improve Choreo for the 2025 season!