Merge branch 'main' into 2027

Author: jwbonner

.github/workflows/build.yml

@@ -30,6 +30,30 @@ jobs:
       - name: Check formatting
         run: npm run check-format
 
+  build-docs:
+    name: Build Docs
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20.x"
+          cache: "npm"
+      - name: Install Node.js dependencies
+        run: npm ci
+        env:
+          ASCOPE_NO_FFMPEG: true
+      - name: Build docs
+        run: npm run docs:build
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: docs/build/
+
   compile-frc6328:
     name: Compile for FRC 6328
     runs-on: ubuntu-latest

docs/docs/img/prefs.png

@@ -18,8 +18,8 @@ AdvantageScope is a robot diagnostics, log review/analysis, and data visualizati
 items={[
 {
 type: "category",
-label: "Getting Started",
-href: "/category/getting-started"
+label: "Overview",
+href: "/category/overview"
 },
 {
 type: "category",
@@ -34,7 +34,7 @@ href: "/category/more-features"
 {
 type: "category",
 label: "Championship Conference",
-href: "/getting-started/champs-conference"
+href: "/overview/champs-conference"
 }
 ]}
 />

docs/docs/img/xr.webp

@@ -4,7 +4,7 @@ sidebar_position: 2
 
 # Legacy Format Deprecation
 
-WPILib supports the type-safe and unit-safe **struct format** for publishing complex data types such as geometry objects, swerve states, and more! AdvantageScope takes advantage of the struct format to streamline the process of configuring fields for visualization. For example, 2D and 3D poses can now be used side-by-side on the [🗺 2D Field](tab-reference/2d-field.md) and [👀 3D Field](tab-reference/3d-field.md) tabs with **no manual configuration** and **no unit errors**.
+WPILib supports the type-safe and unit-safe **struct format** for publishing complex data types such as geometry objects, swerve states, and more! AdvantageScope takes advantage of the struct format to streamline the process of configuring fields for visualization. For example, 2D and 3D poses can now be used side-by-side on the [🗺 2D Field](tab-reference/2d-field) and [👀 3D Field](tab-reference/3d-field) tabs with **no manual configuration** and **no unit errors**.
 
 Before 2025, AdvantageScope supported both structs and the legacy "number array" format for geometry types. The legacy format packed structured data into a format like `double[]` (e.g. a pose would be represented by the array `[x, y, rotation]`).
 
@@ -143,7 +143,7 @@ logEntry.append(new Pose2d());
 The Phoenix signal logger does not support the modern struct format. Consider publishing geometry data using one of the logging libraries shown above instead of using custom signals in Phoenix.
 
 :::tip
-AdvantageScope can automatically merge log files from multiple sources, such as Hoot and WPILOG files. See [here](getting-started/manage-files.md) for details.
+AdvantageScope can automatically merge log files from multiple sources, such as Hoot and WPILOG files. See [here](/overview/log-files) for details.
 :::
 
 </details>

docs/docs/index.md

@@ -0,0 +1,46 @@
+---
+sidebar_position: 2
+---
+
+import PrefsImage from '../img/prefs.png';
+import CenterRotatedDiagram from './img/coordinate-system-center-rotated.png';
+
+# 📐 Coordinate Systems
+
+AdvantageScope includes support for several common coordinate systems on the [🗺️ 2D Field](/tab-reference/2d-field) and [👀 3D Field](/tab-reference/3d-field) tabs. Please reference the [WPILib coordinate system documentation](https://docs.wpilib.org/en/stable/docs/software/basic-programming/coordinate-system.html#wpilib-coordinate-system) for more information on the axis and rotation conventions used by AdvantageScope.
+
+### Customization
+
+By default, the coordinate system is automatically selected based on the chosen field image/model. To select a different coordinate system for use on all fields, open the preferences window by clicking `App` > `Show Preferences...` (Windows/Linux) or `AdvantageScope` > `Settings...` (macOS) and change the "Coordinate System" option.
+
+:::tip
+All coordinate system options are compatible with both FRC and FTC fields.
+:::
+
+## Blue Wall
+
+The origin is in the rightmost corner of the blue alliance wall with the +X axis facing the red alliance wall, as shown below. **This is the default coordinate system for FRC fields from 2023 to 2026.**
+
+![Blue wall coordinate system](./img/coordinate-system-blue-wall.png)
+
+## Alliance Wall
+
+The origin is in the rightmost corner of the alliance wall for the _robot's current alliance_ with the +X axis facing the opposite alliance wall, as shown below. **This is the default coordinate system for FRC in 2022.**
+
+![Alliance wall coordinate system](./img/coordinate-system-alliance-wall.png)
+
+## Center/Rotated
+
+The origin is in the center of the field with the +X axis facing to the right from the perspective of the red alliance wall, as shown below. **This is the default coordinate system for FTC fields from 2024-2025 to 2026-2027.**
+
+<img src={CenterRotatedDiagram} alt="Center/rotated coordinate system" height="400" />
+
+## Center/Red (SystemCore)
+
+The origin is in the center of the field with the +X axis facing away from the red alliance wall, as shown below. **This is the default coordinate system for FRC fields starting in 2027 and FTC fields starting in 2027-2028.**
+
+:::warning
+This coordinate system is only available in the 2027 (v27.x) releases of AdvantageScope.
+:::
+
+![Center/red coordinate system](./img/coordinate-system-center-red.png)

docs/docs/legacy-formats.md

@@ -0,0 +1,5 @@
+{
+  "label": "⚙️ Custom Assets",
+  "position": 3,
+  "collapsed": true
+}

docs/docs/more-features/coordinate-systems.md

@@ -1,10 +1,6 @@
----
-sidebar_position: 6
----
-
 # Converting Onshape & STEP Files to glTF
 
-AdvantageScope's 3D view accepts custom models for fields and robots, which can be installed using the process described [here](../more-features/custom-assets.md). All models must use the [glTF](https://www.khronos.org/gltf/) file format, chosen for its efficiency when storing and loading models. Note that AdvantageScope uses the binary form (.glb), which includes all resources in a single file, rather than the pure JSON form (.gltf).
+AdvantageScope's 3D view accepts custom models for fields and robots, which can be installed using the process described [here](/more-features/custom-assets). All models must use the [glTF](https://www.khronos.org/gltf/) file format, chosen for its efficiency when storing and loading models. Note that AdvantageScope uses the binary form (.glb), which includes all resources in a single file, rather than the pure JSON form (.gltf).
 
 ## Converting Onshape to STEP