Rapid Development Notice This project is currently undergoing rapid updates. Please check back regularly for bug fixes and new features. If you find an error, please report it via the Issues tab and revert to a previous version.

---

---

Table of Contents

• Overview
• Unmatched Features
• Installation
• Workflow & File Management
• Exporting Your Paths
• Tech Stack
• Troubleshooting
• Contributing
• License & Acknowledgments

---

Overview

Turtle Tracer is a powerful desktop application built with Electron and Svelte, designed to revolutionize how FIRST Tech Challenge teams plan their autonomous routines.

Unlike web-based alternatives, Turtle Tracer runs natively on your machine. This means superior performance, actual local file management, offline capabilities, and deep integration with your team's Git workflow.

---

Unmatched Features

Turtle Tracer isn't just a port of the web tool—it's a complete reimagining of what path planning should be.

Next-Level Performance & Workflow

• Native Desktop Experience: Blazing fast performance that works offline and integrates smoothly with your OS.

• Robust History: Never lose progress with Auto-Save, full Undo/Redo support, and a dedicated History Panel.

• Git Integration: See file status (Modified, Staged, Untracked) instantly. Version control your paths alongside your robot code.

  

Professional Analysis & Simulation

• Telemetry Overlay: Import real robot log data to see exactly how your path performed on the field compared to the plan.
• Physics-Based Simulation: Real-time kinematics simulation with accurate velocity constraints and acceleration profiles.
• Heatmaps & Stats: Visualize robot velocity along the path with color-coded gradients, Velocity Graphs, and Timing breakdowns.

Powerful Planning Tools

• File Macros: Reuse successful path sequences! Drag and drop .turt or legacy .pp files to use them as sub-routines (macros).

• Smart Validators: Get real-time feedback on Obstacles, Keep-In Zones, and continuous path safety validation.

• Path Optimizer: Single-click optimization to refine paths for maximum speed while respecting field boundaries.

  

UI & Efficiency Boosters

• Command Palette: Press Cmd+K (or Ctrl+K) to instantly search for paths, settings, or commands.
• Custom Field Maps: Import any field image with the built-in Calibration Wizard.
• Robot Profile Manager: Manage multiple robot configurations with unique dimensions and constraints.

---

Installation

macOS

One-Line Installer (Recommended):

curl -fsSL https://raw.githubusercontent.com/Mallen220/TurtleTracer/main/install.sh | bash

(Enter your password when prompted to complete installation)

Manual Installation

1. Download the latest `.dmg` from Releases.
2. Mount the DMG and drag the app to your Applications folder.
3. Important: Run the following command in Terminal to clear the quarantine attribute:
sudo xattr -rd com.apple.quarantine "/Applications/Turtle Tracer.app"

Windows

Microsoft Store (Recommended): Download from the Microsoft Store to receive seamless auto-updates for stable releases.

Manual Installation (.exe)

1. Download the latest `.exe` from Releases.
2. Run the installer.
3. Note: If SmartScreen appears, click "More info" > "Run anyway".

Linux

One-Line Installer (Recommended):

curl -fsSL https://raw.githubusercontent.com/Mallen220/TurtleTracer/main/install.sh | bash

AppImage / Manual Installation

1. Download the `.deb` or `.AppImage` from Releases.
2. For AppImage, grant execution permissions:
chmod +x TurtleTracer*.AppImage
./TurtleTracer*.AppImage
3. Ensure you have libfuse2 and zlib1g installed via your package manager.

---

Workflow & File Management

One of the critical advantages of Turtle Tracer over web-based tools is its Local File Management system.

• Security & Persistence: Paths are saved as actual .turt files on your hard drive—not in a fragile browser cache.
• Version Control Friendly: Easily commit .turt files to Git alongside your robot's Java code.
• Built-in Organizer: Use the native file browser to organize folders, duplicate routines, and manage backups without leaving the app.

---

Exporting Your Paths

The visualizer provides flexible export capabilities for any team's workflow:

1. Java Class: Generates a complete, ready-to-run Java file for your FTC robot controller (TurtleTracerLib compliant).
2. Sequential Commands: Exports code formatted for command-based frameworks.
3. Strategy Sheet: Export a printable summary of your routine for strategizing with alliance partners.
4. Visual Media: Export high-quality APNG, GIF, and Static Images of your paths for engineering notebooks.

---

Tech Stack

Turtle Tracer is built with modern web technologies packaged for the desktop:

---

Troubleshooting

• macOS "App is damaged" error: macOS requires you to un-quarantine manually installed apps. Run: sudo xattr -rd com.apple.quarantine "/Applications/Turtle Tracer.app"
• Windows SmartScreen warning: Click "More Info" and then "Run Anyway". The code is fully open-source and safe.
• Linux AppImage won't run: Ensure libfuse2 is installed and the file has execution permissions (chmod +x).

---

Contributing

Contributions are heavily encouraged! To get started developing locally:

# Clone the repository
git clone [https://github.com/Mallen220/TurtleTracer.git](https://github.com/Mallen220/TurtleTracer.git)
cd TurtleTracer

# Install dependencies and start the dev server
npm install
npm run dev

# Generate and refresh Lighthouse badges in README (for your deployed URL)
npm run badges:lighthouse -- --url https://live.turtletracer.com/

# Build for your current platform
npm run dist

See our Contribution Guidelines (if applicable) for more details.

AI Assistance Policy: We use AI tools to prototype and speed up development. However, no code is merged without human review and testing. We believe AI should augment human effort, not replace it.

---

License

This project is open-source and released under a Modified Apache 2.0 License.

Your privacy is important to us. Turtle Tracer runs locally and does not collect personal data. Review our full Privacy Policy.

Acknowledgments

• #16166 Watt's Up: For the initial concept, development, and inspiration.
• Pedro Pathing Developers: For the underlying library this visualizer supports.
• The FIRST Community: For continuous feedback, testing, and making this tool better for everyone.