@horizon36596/zenith-import 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Horizon (FTC 36596)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,13 @@
+Zenith
+Copyright (c) 2026 Horizon (FTC 36596)
+
+Zenith is licensed under the MIT License; see LICENSE.
+
+Bundled fonts
+
+The following fonts are bundled in apps/web/public/fonts/. Each is licensed under the SIL Open Font
+License, Version 1.1. The full licence text ships next to each font file.
+
+- Jost, licensed under the SIL Open Font License 1.1 (jost-OFL.txt).
+- IBM Plex Sans, licensed under the SIL Open Font License 1.1 (ibm-plex-sans-OFL.txt).
+- JetBrains Mono, licensed under the SIL Open Font License 1.1 (jetbrains-mono-OFL.txt).

package/README.md

@@ -1,3 +1,91 @@
-# Temporary Holding Version
+# @horizon36596/zenith-import
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Bring paths from other planners into [Zenith](https://libraries.horizon36596.org/zenith/), the FTC
+autonomous planner by Horizon (FTC 36596). Licence: MIT.
+
+```
+npm install @horizon36596/zenith-import
+```
+
+## Package reference
+
+Pure, like `@horizon36596/zenith-core`: no DOM, no clock, no randomness, no Node APIs. Reading the
+file is the caller's job; `zenith import` in `@horizon36596/zenith-cli` does it for you.
+
+- `importPedroProject(json, field, options?)` turns a Pedro Pathing Visualizer project (`.pp`) into an
+  auto in the season's frame, and returns `{ auto, robotFootprint?, warnings }`. Paths become `path`
+  steps, headings keep Pedro's names, sequence waits become `wait` steps, and any sequence item of a
+  kind the importer does not know becomes a placeholder command `imported1`, `imported2` and so on, to
+  map to one of your robot's commands. Every pose carries `CARRIED OVER (Pedro Visualizer import)`.
+- `importTrajectory(json, field)` turns an interchange `trajectory.json` into a view projection:
+  poses at 10 Hz in the season's frame, rounded to 0.5 in and one degree. `readTrajectory` returns the
+  same with its warnings.
+- `importPath(json, field, options?)` turns an interchange `path.json` into an auto that can be
+  edited, and returns `{ auto, warnings }`. Every pose carries `CARRIED OVER (path.json import)`.
+- `interchangeKindOf(doc)` says which interchange file a document is, by its `kind` key
+  (`"trajectory"` or `"path"`), and `checkInterchange(kind, doc, field)` checks it the way importing
+  it would, returning `{ kind, errors, warnings }`. This is what `zenith validate` reports.
+- `scanCommands(sources)` reads a robot's `NamedCommands.register` and `registerCondition` calls
+  out of its Java or Kotlin source text (`{ path, text }[]`), with each command's arguments from its
+  `argInt`, `argDouble`, `argString` and `argEnum` calls, and lists what it could not read as
+  `issues` with the file and line. `checkCommandRegistry(robot, scan)` compares the result with
+  `robot.json`, and `mergeCommandScan(robot, scan)` adds the commands, conditions and params
+  `robot.json` lacks without changing anything already there. `zenith import-commands` does it for
+  you. `diffLines` and `formatDiff` preview the change as a line diff.
+- All three importers throw `ImportError`, whose `issues` name every field that is wrong by its JSON
+  path.
+
+The frames, file formats and APIs these rest on were read from source and are recorded in
+Zenith's ADR 0008, in the repository's decision records.
+
+## `trajectory.json`
+
+The JSON Schema is `json/trajectory.json`, served at
+`https://libraries.horizon36596.org/zenith/schema/v1/trajectory.json`. A planner writes its poses in
+its own coordinates and declares the frame, either by preset or key by key:
+
+| preset | origin | axes | units |
+|---|---|---|---|
+| `zenith` | field centre | the season's field frame | inches, radians counter-clockwise from +x |
+| `pedro` | the Pedro Visualizer's corner, centre at (70.75, 70.75) | the field frame's, for BIOBUZZ | inches, degrees counter-clockwise from +x |
+| `roadrunner` | field centre | MeepMeep's: +x toward the audience, +y away from the Red Wall, for BIOBUZZ | inches, radians counter-clockwise from +x |
+
+Keys given beside a preset override it. Without a preset every key is required: `originIn` (where
+the planner's origin is, in field-frame inches), `xAxis` and `yAxis` (the field-frame direction,
+`+x`, `-x`, `+y` or `-y`, each planner axis points along), `units` (`in`, `mm`, `cm` or `m`),
+`headingUnit` (`rad` or `deg`), `headingZero` (`+x` or `+y`, of the planner's axes) and
+`headingPositive` (`ccw` or `cw`).
+
+The rest of the file: `formatVersion: 1`, `kind: "trajectory"`, `season`, `alliance`, optional
+`title` and `source`, `rateHz` (samples per second; 10 or better), `poses` (`[x, y, heading]`, the
+i-th at i / rateHz seconds), `boundingBox` (`lengthIn` along the heading, `widthIn`, optional
+`centreOffsetIn` forward and left, optional `provenance`), and the optional `phases` (`startS`,
+`endS`, `label` from `drive`, `score`, `collect`, `wait`, `park`, `other`), `claims` (`elementId`,
+`action` `take` or `score`, `atS`) and `envelopes` (`startS`, `endS`, `polygon` of `{ x, y }` in the
+declared frame). Unknown keys are refused, with their path.
+
+`robot/meepmeep-export/` has a copy-in class that writes this file from MeepMeep.
+
+## `path.json`
+
+The JSON Schema is `json/path.json`, served at
+`https://libraries.horizon36596.org/zenith/schema/v1/path.json`. It is the structure of a
+propose-level projection with the commands taken out, and the same `frame` block as
+`trajectory.json`: `formatVersion: 1`, `kind: "path"`, `season`, `alliance`, optional `title` and
+`source`, `frame`, `startPose` (`{ x, y, heading }`) and `steps`. A step is a path step (`kind:
+"path"`, optional `id`, `segments` of `line` or `bezier` with one to three `control` points,
+optional `heading`, `speedFraction` and `timeoutS`) or a wait step (`kind: "wait"`, optional `id`,
+`seconds`). Heading modes are Zenith's: `tangent`, `tangentReversed`, `constant` (`heading`),
+`linear` (`from`, `to`, turning from one to the other as written), `facePoint` (`x`, `y`, optional
+`offset`) and `piecewise` (`ranges` of `{ startT, endT, heading }` running from 0 to 1). Positions
+and headings are in the declared frame's units, which is why their keys carry no unit suffix.
+
+## Fixtures
+
+`fixtures/pedro/` holds `.pp` projects in the visualizer's 1.5.0 format (and one saved by a newer,
+imagined 1.7.0, with an `event` item), `fixtures/trajectory/` interchange files, and each `broken/`
+folder files that must fail with a named field. `fixtures/path/` holds `path.json` files in the
+Pedro, RoadRunner and an explicit millimetre frame, with its own `broken/` folder. The tests hold every good `.pp` fixture to the
+milestone's contract: the imported auto loads, and its path lies within 0.5 in of the visualizer's.
+The `path.json` fixtures are held to the same: each imports to an auto with no error finding whose
+path lies within 0.5 in of the file's own.

package/dist/bezier.d.ts

@@ -0,0 +1,36 @@
+/** A point in field-frame inches. */
+export interface Point {
+    xIn: number;
+    yIn: number;
+}
+/**
+ * How far a replacement curve may stray from the curve it replaces, in inches. It is a tenth of the
+ * half inch allowed between an import and the planner's own path, so rounding on save
+ * and this approximation together stay well inside it.
+ */
+export declare const APPROXIMATION_TOLERANCE_IN = 0.05;
+/** The point at parameter u of the Bézier with control polygon `points` (de Casteljau). */
+export declare function bezierPoint(points: readonly Point[], u: number): Point;
+/** The derivative with respect to u, in inches per unit of u. */
+export declare function bezierDerivative(points: readonly Point[], u: number): Point;
+/**
+ * The same curve as control polygons of at most `maxControls` interior points each.
+ *
+ * A polygon that already fits is returned as it is, so the result is exact. A higher degree cannot be
+ * written exactly with fewer control points, so it is cut into equal stretches of u and each is
+ * replaced by the cubic with the same end points and the same end derivatives (a cubic Hermite
+ * piece), doubling the number of pieces until every one is within `toleranceIn` of the original at
+ * every sample. The distance is measured between points at the same parameter, which bounds the
+ * distance between the two curves from above.
+ */
+export declare function reduceDegree(points: readonly Point[], maxControls?: number, toleranceIn?: number): {
+    polygons: Point[][];
+    maxErrorIn: number;
+};
+/**
+ * The control polygon of the single Bézier that passes through every one of `through`, reached at
+ * evenly spaced parameters, which is what Pedro's `BezierCurve.through` builds (ADR 0008 section 1):
+ * solve the Bernstein matrix at u = i / (n - 1) for the control points.
+ */
+export declare function interpolateThrough(through: readonly Point[]): Point[];
+//# sourceMappingURL=bezier.d.ts.map

package/dist/bezier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bezier.d.ts","sourceRoot":"","sources":["../src/bezier.ts"],"names":[],"mappings":"AAEA,qCAAqC;AACrC,MAAM,WAAW,KAAK;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C,2FAA2F;AAC3F,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,KAAK,CAYtE;AAED,iEAAiE;AACjE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,KAAK,CAU3E;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,SAAS,KAAK,EAAE,EACxB,WAAW,GAAE,MAAkC,EAC/C,WAAW,GAAE,MAAmC,GAC/C;IAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAgC7C;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,KAAK,EAAE,GAAG,KAAK,EAAE,CAoBrE"}

package/dist/bezier.js

@@ -0,0 +1,133 @@
+import { MAX_BEZIER_CONTROL_POINTS } from "@horizon36596/zenith-schema";
+/**
+ * How far a replacement curve may stray from the curve it replaces, in inches. It is a tenth of the
+ * half inch allowed between an import and the planner's own path, so rounding on save
+ * and this approximation together stay well inside it.
+ */
+export const APPROXIMATION_TOLERANCE_IN = 0.05;
+/** The point at parameter u of the Bézier with control polygon `points` (de Casteljau). */
+export function bezierPoint(points, u) {
+    let current = points.slice();
+    while (current.length > 1) {
+        const next = [];
+        for (let i = 0; i + 1 < current.length; i += 1) {
+            const a = current[i];
+            const b = current[i + 1];
+            next.push({ xIn: a.xIn + (b.xIn - a.xIn) * u, yIn: a.yIn + (b.yIn - a.yIn) * u });
+        }
+        current = next;
+    }
+    return current[0];
+}
+/** The derivative with respect to u, in inches per unit of u. */
+export function bezierDerivative(points, u) {
+    const degree = points.length - 1;
+    if (degree < 1)
+        return { xIn: 0, yIn: 0 };
+    const differences = [];
+    for (let i = 0; i < degree; i += 1) {
+        const a = points[i];
+        const b = points[i + 1];
+        differences.push({ xIn: (b.xIn - a.xIn) * degree, yIn: (b.yIn - a.yIn) * degree });
+    }
+    return bezierPoint(differences, u);
+}
+/**
+ * The same curve as control polygons of at most `maxControls` interior points each.
+ *
+ * A polygon that already fits is returned as it is, so the result is exact. A higher degree cannot be
+ * written exactly with fewer control points, so it is cut into equal stretches of u and each is
+ * replaced by the cubic with the same end points and the same end derivatives (a cubic Hermite
+ * piece), doubling the number of pieces until every one is within `toleranceIn` of the original at
+ * every sample. The distance is measured between points at the same parameter, which bounds the
+ * distance between the two curves from above.
+ */
+export function reduceDegree(points, maxControls = MAX_BEZIER_CONTROL_POINTS, toleranceIn = APPROXIMATION_TOLERANCE_IN) {
+    if (points.length - 2 <= maxControls)
+        return { polygons: [points.slice()], maxErrorIn: 0 };
+    let best = null;
+    for (let pieces = 1; pieces <= 256; pieces *= 2) {
+        const polygons = [];
+        let maxErrorIn = 0;
+        for (let k = 0; k < pieces; k += 1) {
+            const u0 = k / pieces;
+            const u1 = (k + 1) / pieces;
+            const span = u1 - u0;
+            const p0 = bezierPoint(points, u0);
+            const p3 = bezierPoint(points, u1);
+            const d0 = bezierDerivative(points, u0);
+            const d3 = bezierDerivative(points, u1);
+            const cubic = [
+                p0,
+                { xIn: p0.xIn + (d0.xIn * span) / 3, yIn: p0.yIn + (d0.yIn * span) / 3 },
+                { xIn: p3.xIn - (d3.xIn * span) / 3, yIn: p3.yIn - (d3.yIn * span) / 3 },
+                p3,
+            ];
+            for (let i = 1; i < 16; i += 1) {
+                const s = i / 16;
+                const a = bezierPoint(cubic, s);
+                const b = bezierPoint(points, u0 + s * span);
+                maxErrorIn = Math.max(maxErrorIn, Math.hypot(a.xIn - b.xIn, a.yIn - b.yIn));
+            }
+            polygons.push(cubic);
+        }
+        best = { polygons, maxErrorIn };
+        if (maxErrorIn <= toleranceIn)
+            break;
+    }
+    return best;
+}
+/**
+ * The control polygon of the single Bézier that passes through every one of `through`, reached at
+ * evenly spaced parameters, which is what Pedro's `BezierCurve.through` builds (ADR 0008 section 1):
+ * solve the Bernstein matrix at u = i / (n - 1) for the control points.
+ */
+export function interpolateThrough(through) {
+    const n = through.length;
+    if (n <= 2)
+        return through.slice();
+    const degree = n - 1;
+    const binomial = (k) => {
+        let value = 1;
+        for (let i = 1; i <= k; i += 1)
+            value = (value * (degree - k + i)) / i;
+        return value;
+    };
+    // Rows are the n parameters, columns the n Bernstein basis polynomials.
+    const matrix = [];
+    for (let i = 0; i < n; i += 1) {
+        const u = i / degree;
+        const row = [];
+        for (let j = 0; j <= degree; j += 1)
+            row.push(binomial(j) * u ** j * (1 - u) ** (degree - j));
+        matrix.push(row);
+    }
+    const xs = solve(matrix, through.map((point) => point.xIn));
+    const ys = solve(matrix, through.map((point) => point.yIn));
+    return xs.map((xIn, i) => ({ xIn, yIn: ys[i] }));
+}
+/** Gaussian elimination with partial pivoting; the matrix is small (a handful of points). */
+function solve(matrix, rhs) {
+    const n = rhs.length;
+    const a = matrix.map((row, i) => [...row, rhs[i]]);
+    for (let col = 0; col < n; col += 1) {
+        let pivot = col;
+        for (let row = col + 1; row < n; row += 1) {
+            if (Math.abs(a[row][col]) > Math.abs(a[pivot][col]))
+                pivot = row;
+        }
+        [a[col], a[pivot]] = [a[pivot], a[col]];
+        const top = a[col];
+        const lead = top[col];
+        for (let row = 0; row < n; row += 1) {
+            if (row === col)
+                continue;
+            const current = a[row];
+            const factor = current[col] / lead;
+            for (let k = col; k <= n; k += 1)
+                current[k] = current[k] - factor * top[k];
+        }
+    }
+    return a.map((row, i) => row[n] / row[i]);
+}
+//# sourceMappingURL=bezier.js.map

package/dist/bezier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bezier.js","sourceRoot":"","sources":["../src/bezier.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,17 @@
+/** One thing wrong with an imported file: where, as a JSON path, and what, as a sentence. */
+export interface ImportIssue {
+    /** The JSON path of the offending value, such as `lines[2].endPoint.x`; empty for the whole file. */
+    path: string;
+    message: string;
+}
+/**
+ * Thrown when a file cannot be imported at all. Every issue names the field it is about, so a
+ * planner author can fix the file from the message alone.
+ */
+export declare class ImportError extends Error {
+    readonly issues: readonly ImportIssue[];
+    constructor(what: string, issues: readonly ImportIssue[]);
+}
+/** Formats a JSON path from its keys: `["lines", 2, "endPoint"]` is `lines[2].endPoint`. */
+export declare function jsonPath(keys: readonly (string | number)[]): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,MAAM,WAAW,WAAW;IAC1B,qGAAqG;IACrG,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;gBAE5B,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,WAAW,EAAE;CAKzD;AAED,4FAA4F;AAC5F,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,GAAG,MAAM,CAOnE"}

package/dist/errors.js

@@ -0,0 +1,24 @@
+/**
+ * Thrown when a file cannot be imported at all. Every issue names the field it is about, so a
+ * planner author can fix the file from the message alone.
+ */
+export class ImportError extends Error {
+    issues;
+    constructor(what, issues) {
+        super(`Cannot import ${what}:\n${issues.map((issue) => `  ${issue.path === "" ? "(file)" : issue.path}: ${issue.message}`).join("\n")}`);
+        this.name = "ImportError";
+        this.issues = issues;
+    }
+}
+/** Formats a JSON path from its keys: `["lines", 2, "endPoint"]` is `lines[2].endPoint`. */
+export function jsonPath(keys) {
+    let out = "";
+    for (const key of keys) {
+        if (typeof key === "number")
+            out += `[${String(key)}]`;
+        else
+            out += out === "" ? key : `.${key}`;
+    }
+    return out;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAOA;;;GAGG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,MAAM,CAAyB;IAExC,YAAY,IAAY,EAAE,MAA8B;QACtD,KAAK,CAAC,iBAAiB,IAAI,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACzI,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,4FAA4F;AAC5F,MAAM,UAAU,QAAQ,CAAC,IAAkC;IACzD,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,GAAG,IAAI,IAAI,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC;;YAClD,GAAG,IAAI,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,CAAC;IAC3C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/frame.d.ts

@@ -0,0 +1,89 @@
+import type { Field } from "@horizon36596/zenith-schema";
+/**
+ * A planner's coordinate frame, described by where it sits on the season's field (the frame of the
+ * season's `field.json`, which Zenith calls the field frame: for BIOBUZZ, centre origin, +x to the
+ * audience's right, +y away from the audience, inches, heading counter-clockwise from +x).
+ *
+ * Every direction is named as a direction of the field frame, so a frame that is turned, mirrored or
+ * offset against Zenith's can be written down exactly, and a frame written in any planner's own
+ * words has one reading.
+ */
+export interface FrameSpec {
+    /** Where the planner's (0, 0) sits, in field-frame inches. */
+    originIn: {
+        xIn: number;
+        yIn: number;
+    };
+    /** The field-frame direction the planner's +x points along. */
+    xAxis: AxisDirection;
+    /** The field-frame direction the planner's +y points along. */
+    yAxis: AxisDirection;
+    /** The length unit of the planner's positions. */
+    units: LengthUnit;
+    /** The unit of the planner's headings. */
+    headingUnit: "rad" | "deg";
+    /** The planner axis a heading of zero points along. */
+    headingZero: "+x" | "+y";
+    /** Which way a positive heading turns, seen from above in the planner's own axes. */
+    headingPositive: "ccw" | "cw";
+}
+export declare const AXIS_DIRECTIONS: readonly ["+x", "-x", "+y", "-y"];
+export type AxisDirection = (typeof AXIS_DIRECTIONS)[number];
+export declare const LENGTH_UNITS: readonly ["in", "mm", "cm", "m"];
+export type LengthUnit = (typeof LENGTH_UNITS)[number];
+/** Inches per unit. An inch is exactly 25.4 mm by definition. */
+export declare const INCHES_PER_UNIT: Record<LengthUnit, number>;
+export declare const FRAME_PRESETS: readonly ["zenith", "pedro", "roadrunner"];
+export type FramePreset = (typeof FRAME_PRESETS)[number];
+/**
+ * The Pedro Pathing Visualizer's field centre in its own coordinates, in inches: half its
+ * `FIELD_SIZE` of 141.5 in, the axis its own "Mirror Horizontally" export mirrors about
+ * (ADR 0008 section 2).
+ */
+export declare const PEDRO_VISUALIZER_CENTRE_IN: number;
+/**
+ * The seasons each preset's placement was checked against. A preset used with another season still
+ * converts, with a warning, because the check rests on where that season's field image and Red Wall
+ * sit (ADR 0008 sections 2 and 4).
+ */
+export declare const PRESET_VERIFIED_SEASONS: Record<FramePreset, readonly string[] | "any">;
+/**
+ * The three named frames (ADR 0008).
+ *
+ * - `zenith`: the field frame itself, inches and radians.
+ * - `pedro`: the Pedro Visualizer's frame: corner origin, the same axes as the field frame for
+ *   BIOBUZZ, inches, degrees counter-clockwise from +x.
+ * - `roadrunner`: MeepMeep's frame, which for BIOBUZZ is the FTC Field Coordinate System: centre
+ *   origin, +x toward the audience (field -y), +y away from the Red Wall (field +x), inches, radians.
+ */
+export declare function presetFrame(preset: FramePreset, pedroCentreIn?: number): FrameSpec;
+/** A warning when `preset` was not checked against this season's field, else null. */
+export declare function presetSeasonWarning(preset: FramePreset, field: Field): string | null;
+/** Null when the two axes are perpendicular, else a sentence saying why the frame is unusable. */
+export declare function frameProblem(frame: FrameSpec): string | null;
+/** A planner point in field-frame inches. */
+export declare function pointToField(frame: FrameSpec, x: number, y: number): {
+    xIn: number;
+    yIn: number;
+};
+/** A planner heading as a field-frame heading in radians, wrapped to (-pi, pi]. */
+export declare function headingToField(frame: FrameSpec, heading: number): number;
+/**
+ * A turn written in the planner's heading unit and direction (the difference between two headings,
+ * or an offset added to one), as a field-frame turn in radians. It is not wrapped: a turn of 270
+ * degrees stays 3 pi / 2, so a linear heading that turns the long way keeps doing so.
+ *
+ * A turn flips sign when the planner counts headings clockwise, and flips again when the planner's
+ * axes are mirrored against the field frame (a left-handed frame), since a counter-clockwise turn
+ * in such a frame is a clockwise one on the field.
+ */
+export declare function turnToField(frame: FrameSpec, turn: number): number;
+/** A planner pose in the field frame. */
+export declare function poseToField(frame: FrameSpec, x: number, y: number, heading: number): {
+    xIn: number;
+    yIn: number;
+    headingRad: number;
+};
+/** Wraps an angle to (-pi, pi]. */
+export declare function wrap(rad: number): number;
+//# sourceMappingURL=frame.d.ts.map

package/dist/frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../src/frame.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAEzD;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,8DAA8D;IAC9D,QAAQ,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACvC,+DAA+D;IAC/D,KAAK,EAAE,aAAa,CAAC;IACrB,+DAA+D;IAC/D,KAAK,EAAE,aAAa,CAAC;IACrB,kDAAkD;IAClD,KAAK,EAAE,UAAU,CAAC;IAClB,0CAA0C;IAC1C,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC;IAC3B,uDAAuD;IACvD,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC;IACzB,qFAAqF;IACrF,eAAe,EAAE,KAAK,GAAG,IAAI,CAAC;CAC/B;AAED,eAAO,MAAM,eAAe,mCAAoC,CAAC;AACjE,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D,eAAO,MAAM,YAAY,kCAAmC,CAAC;AAC7D,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,iEAAiE;AACjE,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAKtD,CAAC;AAEF,eAAO,MAAM,aAAa,4CAA6C,CAAC;AACxE,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,QAAY,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,KAAK,CAIlF,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,EAAE,aAAa,GAAE,MAAmC,GAAG,SAAS,CAiC9G;AAED,sFAAsF;AACtF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,IAAI,CAIpF;AASD,kGAAkG;AAClG,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAO5D;AAED,6CAA6C;AAC7C,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAQjG;AAED,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAWxE;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAOlE;AAED,yCAAyC;AACzC,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,EAChB,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,OAAO,EAAE,MAAM,GACd;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAElD;AAED,mCAAmC;AACnC,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAKxC"}

package/dist/frame.js

@@ -0,0 +1,145 @@
+export const AXIS_DIRECTIONS = ["+x", "-x", "+y", "-y"];
+export const LENGTH_UNITS = ["in", "mm", "cm", "m"];
+/** Inches per unit. An inch is exactly 25.4 mm by definition. */
+export const INCHES_PER_UNIT = {
+    in: 1,
+    mm: 1 / 25.4,
+    cm: 1 / 2.54,
+    m: 1 / 0.0254,
+};
+export const FRAME_PRESETS = ["zenith", "pedro", "roadrunner"];
+/**
+ * The Pedro Pathing Visualizer's field centre in its own coordinates, in inches: half its
+ * `FIELD_SIZE` of 141.5 in, the axis its own "Mirror Horizontally" export mirrors about
+ * (ADR 0008 section 2).
+ */
+export const PEDRO_VISUALIZER_CENTRE_IN = 141.5 / 2;
+/**
+ * The seasons each preset's placement was checked against. A preset used with another season still
+ * converts, with a warning, because the check rests on where that season's field image and Red Wall
+ * sit (ADR 0008 sections 2 and 4).
+ */
+export const PRESET_VERIFIED_SEASONS = {
+    zenith: "any",
+    pedro: ["biobuzz"],
+    roadrunner: ["biobuzz"],
+};
+/**
+ * The three named frames (ADR 0008).
+ *
+ * - `zenith`: the field frame itself, inches and radians.
+ * - `pedro`: the Pedro Visualizer's frame: corner origin, the same axes as the field frame for
+ *   BIOBUZZ, inches, degrees counter-clockwise from +x.
+ * - `roadrunner`: MeepMeep's frame, which for BIOBUZZ is the FTC Field Coordinate System: centre
+ *   origin, +x toward the audience (field -y), +y away from the Red Wall (field +x), inches, radians.
+ */
+export function presetFrame(preset, pedroCentreIn = PEDRO_VISUALIZER_CENTRE_IN) {
+    switch (preset) {
+        case "zenith":
+            return {
+                originIn: { xIn: 0, yIn: 0 },
+                xAxis: "+x",
+                yAxis: "+y",
+                units: "in",
+                headingUnit: "rad",
+                headingZero: "+x",
+                headingPositive: "ccw",
+            };
+        case "pedro":
+            return {
+                originIn: { xIn: -pedroCentreIn, yIn: -pedroCentreIn },
+                xAxis: "+x",
+                yAxis: "+y",
+                units: "in",
+                headingUnit: "deg",
+                headingZero: "+x",
+                headingPositive: "ccw",
+            };
+        case "roadrunner":
+            return {
+                originIn: { xIn: 0, yIn: 0 },
+                xAxis: "-y",
+                yAxis: "+x",
+                units: "in",
+                headingUnit: "rad",
+                headingZero: "+x",
+                headingPositive: "ccw",
+            };
+    }
+}
+/** A warning when `preset` was not checked against this season's field, else null. */
+export function presetSeasonWarning(preset, field) {
+    const verified = PRESET_VERIFIED_SEASONS[preset];
+    if (verified === "any" || verified.includes(field.season))
+        return null;
+    return `The ${preset} frame preset was checked against ${verified.join(", ")} only; on ${field.season} its placement may be turned. Declare the frame explicitly if the imported path looks rotated.`;
+}
+const UNIT_VECTOR = {
+    "+x": { x: 1, y: 0 },
+    "-x": { x: -1, y: 0 },
+    "+y": { x: 0, y: 1 },
+    "-y": { x: 0, y: -1 },
+};
+/** Null when the two axes are perpendicular, else a sentence saying why the frame is unusable. */
+export function frameProblem(frame) {
+    const ex = UNIT_VECTOR[frame.xAxis];
+    const ey = UNIT_VECTOR[frame.yAxis];
+    if (ex.x * ey.x + ex.y * ey.y !== 0) {
+        return `frame.xAxis (${frame.xAxis}) and frame.yAxis (${frame.yAxis}) must point along different field axes.`;
+    }
+    return null;
+}
+/** A planner point in field-frame inches. */
+export function pointToField(frame, x, y) {
+    const k = INCHES_PER_UNIT[frame.units];
+    const ex = UNIT_VECTOR[frame.xAxis];
+    const ey = UNIT_VECTOR[frame.yAxis];
+    return {
+        xIn: frame.originIn.xIn + k * (x * ex.x + y * ey.x),
+        yIn: frame.originIn.yIn + k * (x * ex.y + y * ey.y),
+    };
+}
+/** A planner heading as a field-frame heading in radians, wrapped to (-pi, pi]. */
+export function headingToField(frame, heading) {
+    const rad = frame.headingUnit === "deg" ? (heading * Math.PI) / 180 : heading;
+    const zero = frame.headingZero === "+x" ? 0 : Math.PI / 2;
+    const planner = zero + (frame.headingPositive === "ccw" ? rad : -rad);
+    // The direction in the planner's axes, carried into the field frame by the same axis map as a
+    // point, so a mirrored (left-handed) frame turns the right way too.
+    const ex = UNIT_VECTOR[frame.xAxis];
+    const ey = UNIT_VECTOR[frame.yAxis];
+    const c = Math.cos(planner);
+    const s = Math.sin(planner);
+    return wrap(Math.atan2(c * ex.y + s * ey.y, c * ex.x + s * ey.x));
+}
+/**
+ * A turn written in the planner's heading unit and direction (the difference between two headings,
+ * or an offset added to one), as a field-frame turn in radians. It is not wrapped: a turn of 270
+ * degrees stays 3 pi / 2, so a linear heading that turns the long way keeps doing so.
+ *
+ * A turn flips sign when the planner counts headings clockwise, and flips again when the planner's
+ * axes are mirrored against the field frame (a left-handed frame), since a counter-clockwise turn
+ * in such a frame is a clockwise one on the field.
+ */
+export function turnToField(frame, turn) {
+    const rad = frame.headingUnit === "deg" ? (turn * Math.PI) / 180 : turn;
+    const ex = UNIT_VECTOR[frame.xAxis];
+    const ey = UNIT_VECTOR[frame.yAxis];
+    const handedness = ex.x * ey.y - ex.y * ey.x;
+    const direction = frame.headingPositive === "ccw" ? 1 : -1;
+    return rad * direction * handedness;
+}
+/** A planner pose in the field frame. */
+export function poseToField(frame, x, y, heading) {
+    return { ...pointToField(frame, x, y), headingRad: headingToField(frame, heading) };
+}
+/** Wraps an angle to (-pi, pi]. */
+export function wrap(rad) {
+    let a = rad % (2 * Math.PI);
+    if (a <= -Math.PI)
+        a += 2 * Math.PI;
+    if (a > Math.PI)
+        a -= 2 * Math.PI;
+    return a;
+}
+//# sourceMappingURL=frame.js.map

package/dist/frame.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.js","sourceRoot":"","sources":["../src/frame.ts"],"names":[],"mappings":"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"}