@foxglove/schemas 0.2.0 → 0.3.0

package/schemas/ros2/PoseInFrame.msg

@@ -1,4 +1,7 @@
-# Generated from PoseInFrame by @foxglove/schemas
+# foxglove_msgs/msg/PoseInFrame
+# A timestamped pose for an object or reference frame in 3D space
+
+# Generated by https://github.com/foxglove/schemas
 
 # Timestamp of pose
 builtin_interfaces/Time timestamp

package/schemas/ros2/PosesInFrame.msg

@@ -1,4 +1,7 @@
-# Generated from PosesInFrame by @foxglove/schemas
+# foxglove_msgs/msg/PosesInFrame
+# An array of timestamped poses for an object or reference frame in 3D space
+
+# Generated by https://github.com/foxglove/schemas
 
 # Timestamp of pose
 builtin_interfaces/Time timestamp

package/schemas/ros2/RawImage.msg

@@ -1,4 +1,7 @@
-# Generated from RawImage by @foxglove/schemas
+# foxglove_msgs/msg/RawImage
+# A raw image
+
+# Generated by https://github.com/foxglove/schemas
 
 # Timestamp of image
 builtin_interfaces/Time timestamp

package/schemas/ros2/Vector2.msg

@@ -1,4 +1,7 @@
-# Generated from Vector2 by @foxglove/schemas
+# foxglove_msgs/msg/Vector2
+# A vector in 2D space that represents a direction only
+
+# Generated by https://github.com/foxglove/schemas
 
 # x coordinate length
 float64 x

package/schemas/typescript/CameraCalibration.ts

@@ -1,4 +1,4 @@
-// Generated from CameraCalibration by @foxglove/schemas
+// Generated by https://github.com/foxglove/schemas
 
 import { Time } from "./Time";
 

package/schemas/typescript/CircleAnnotation.ts

@@ -1,4 +1,4 @@
-// Generated from CircleAnnotation by @foxglove/schemas
+// Generated by https://github.com/foxglove/schemas
 
 import { Color } from "./Color";
 import { Point2 } from "./Point2";

package/schemas/typescript/Color.ts

@@ -1,4 +1,4 @@
-// Generated from Color by @foxglove/schemas
+// Generated by https://github.com/foxglove/schemas
 
 /** A color in RGBA format */
 export type Color = {

package/schemas/typescript/CompressedImage.ts

@@ -1,4 +1,4 @@
-// Generated from CompressedImage by @foxglove/schemas
+// Generated by https://github.com/foxglove/schemas
 
 import { Time } from "./Time";
 

package/schemas/typescript/FrameTransform.ts

@@ -1,7 +1,8 @@
-// Generated from FrameTransform by @foxglove/schemas
+// Generated by https://github.com/foxglove/schemas
 
+import { Quaternion } from "./Quaternion";
 import { Time } from "./Time";
-import { Transform } from "./Transform";
+import { Vector3 } from "./Vector3";
 
 /** A transform between two reference frames in 3D space */
 export type FrameTransform = {
@@ -14,6 +15,9 @@ export type FrameTransform = {
   /** Name of the child frame */
   child_frame_id: string;
 
-  /** Transform from parent frame to child frame */
-  transform: Transform;
+  /** Translation component of the transform */
+  translation: Vector3;
+
+  /** Rotation component of the transform */
+  rotation: Quaternion;
 };

package/schemas/typescript/GeoJSON.ts

@@ -1,4 +1,4 @@
-// Generated from GeoJSON by @foxglove/schemas
+// Generated by https://github.com/foxglove/schemas
 
 /** GeoJSON data for annotating maps */
 export type GeoJSON = {

package/schemas/typescript/Grid.ts

@@ -1,4 +1,4 @@
-// Generated from Grid by @foxglove/schemas
+// Generated by https://github.com/foxglove/schemas
 
 import { PackedElementField } from "./PackedElementField";
 import { Pose } from "./Pose";

package/schemas/typescript/ImageAnnotations.ts

@@ -1,4 +1,4 @@
-// Generated from ImageAnnotations by @foxglove/schemas
+// Generated by https://github.com/foxglove/schemas
 
 import { CircleAnnotation } from "./CircleAnnotation";
 import { PointsAnnotation } from "./PointsAnnotation";

package/schemas/typescript/LaserScan.ts

@@ -1,4 +1,4 @@
-// Generated from LaserScan by @foxglove/schemas
+// Generated by https://github.com/foxglove/schemas
 
 import { Pose } from "./Pose";
 import { Time } from "./Time";

package/schemas/typescript/LocationFix.ts

@@ -1,4 +1,4 @@
-// Generated from LocationFix by @foxglove/schemas
+// Generated by https://github.com/foxglove/schemas
 
 import { PositionCovarianceType } from "./PositionCovarianceType";
 

package/schemas/typescript/Log.ts

@@ -1,4 +1,4 @@
-// Generated from Log by @foxglove/schemas
+// Generated by https://github.com/foxglove/schemas
 
 import { LogLevel } from "./LogLevel";
 import { Time } from "./Time";

package/schemas/typescript/LogLevel.ts

@@ -1,4 +1,4 @@
-// Generated from LogLevel by @foxglove/schemas
+// Generated by https://github.com/foxglove/schemas
 
 /** Log level */
 export enum LogLevel {

package/schemas/typescript/NumericType.ts

@@ -1,4 +1,4 @@
-// Generated from NumericType by @foxglove/schemas
+// Generated by https://github.com/foxglove/schemas
 
 /** Numeric type */
 export enum NumericType {

package/schemas/typescript/PackedElementField.ts

@@ -1,4 +1,4 @@
-// Generated from PackedElementField by @foxglove/schemas
+// Generated by https://github.com/foxglove/schemas
 
 import { NumericType } from "./NumericType";
 

package/schemas/typescript/Point2.ts

@@ -1,4 +1,4 @@
-// Generated from Point2 by @foxglove/schemas
+// Generated by https://github.com/foxglove/schemas
 
 /** A point representing a position in 2D space */
 export type Point2 = {

package/schemas/typescript/Point3.ts

@@ -1,4 +1,4 @@
-// Generated from Point3 by @foxglove/schemas
+// Generated by https://github.com/foxglove/schemas
 
 /** A point representing a position in 3D space */
 export type Point3 = {

package/schemas/typescript/PointCloud.ts

@@ -1,4 +1,4 @@
-// Generated from PointCloud by @foxglove/schemas
+// Generated by https://github.com/foxglove/schemas
 
 import { PackedElementField } from "./PackedElementField";
 import { Pose } from "./Pose";

package/schemas/typescript/PointsAnnotation.ts

@@ -1,4 +1,4 @@
-// Generated from PointsAnnotation by @foxglove/schemas
+// Generated by https://github.com/foxglove/schemas
 
 import { Color } from "./Color";
 import { Point2 } from "./Point2";

package/schemas/typescript/PointsAnnotationType.ts

@@ -1,4 +1,4 @@
-// Generated from PointsAnnotationType by @foxglove/schemas
+// Generated by https://github.com/foxglove/schemas
 
 /** Type of points annotation */
 export enum PointsAnnotationType {

package/schemas/typescript/Pose.ts

@@ -1,4 +1,4 @@
-// Generated from Pose by @foxglove/schemas
+// Generated by https://github.com/foxglove/schemas
 
 import { Quaternion } from "./Quaternion";
 import { Vector3 } from "./Vector3";

package/schemas/typescript/PoseInFrame.ts

@@ -1,4 +1,4 @@
-// Generated from PoseInFrame by @foxglove/schemas
+// Generated by https://github.com/foxglove/schemas
 
 import { Pose } from "./Pose";
 import { Time } from "./Time";

package/schemas/typescript/PosesInFrame.ts

@@ -1,4 +1,4 @@
-// Generated from PosesInFrame by @foxglove/schemas
+// Generated by https://github.com/foxglove/schemas
 
 import { Pose } from "./Pose";
 import { Time } from "./Time";

package/schemas/typescript/PositionCovarianceType.ts

@@ -1,4 +1,4 @@
-// Generated from PositionCovarianceType by @foxglove/schemas
+// Generated by https://github.com/foxglove/schemas
 
 /** Type of position covariance */
 export enum PositionCovarianceType {

package/schemas/typescript/Quaternion.ts

@@ -1,4 +1,4 @@
-// Generated from Quaternion by @foxglove/schemas
+// Generated by https://github.com/foxglove/schemas
 
 /** A [quaternion](https://eater.net/quaternions) representing a rotation in 3D space */
 export type Quaternion = {

package/schemas/typescript/RawImage.ts

@@ -1,4 +1,4 @@
-// Generated from RawImage by @foxglove/schemas
+// Generated by https://github.com/foxglove/schemas
 
 import { Time } from "./Time";
 

package/schemas/typescript/Vector2.ts

@@ -1,4 +1,4 @@
-// Generated from Vector2 by @foxglove/schemas
+// Generated by https://github.com/foxglove/schemas
 
 /** A vector in 2D space that represents a direction only */
 export type Vector2 = {

package/schemas/typescript/Vector3.ts

@@ -1,4 +1,4 @@
-// Generated from Vector3 by @foxglove/schemas
+// Generated by https://github.com/foxglove/schemas
 
 /** A vector in 3D space that represents a direction only */
 export type Vector3 = {

package/schemas/typescript/index.ts

@@ -23,6 +23,5 @@ export * from "./PosesInFrame";
 export * from "./PositionCovarianceType";
 export * from "./Quaternion";
 export * from "./RawImage";
-export * from "./Transform";
 export * from "./Vector2";
 export * from "./Vector3";

package/scripts/updateGeneratedFiles.ts

@@ -6,6 +6,7 @@ import { promisify } from "util";
 
 import { generateRosMsg, generateRosMsgDefinition } from "../src";
 import { generateJsonSchema } from "../src/generateJsonSchema";
+import { generateMarkdown } from "../src/generateMarkdown";
 import { generateProto } from "../src/generateProto";
 import { generateTypeScript, DURATION_TS, TIME_TS } from "../src/generateTypeScript";
 import { foxgloveEnumSchemas, foxgloveMessageSchemas } from "../src/schemas";
@@ -16,7 +17,7 @@ async function logProgress(message: string, body: () => Promise<void>) {
   process.stderr.write("done\n");
 }
 
-async function main({ outDir }: { outDir: string }) {
+async function main({ outDir, rosOutDir }: { outDir: string; rosOutDir: string }) {
   await logProgress("Removing any existing output directory", async () => {
     await promisify(rimraf)(outDir);
   });
@@ -33,27 +34,27 @@ async function main({ outDir }: { outDir: string }) {
 
   await logProgress("Generating ROS 1 msg files", async () => {
     await fs.mkdir(path.join(outDir, "ros1"), { recursive: true });
+    await fs.mkdir(path.join(rosOutDir, "ros1"), { recursive: true });
     for (const schema of Object.values(foxgloveMessageSchemas)) {
       if (schema.rosEquivalent != undefined) {
         continue;
       }
-      await fs.writeFile(
-        path.join(outDir, "ros1", `${schema.name}.msg`),
-        generateRosMsg(generateRosMsgDefinition(schema, { rosVersion: 1 })),
-      );
+      const msg = generateRosMsg(generateRosMsgDefinition(schema, { rosVersion: 1 }));
+      await fs.writeFile(path.join(outDir, "ros1", `${schema.name}.msg`), msg);
+      await fs.writeFile(path.join(rosOutDir, "ros1", `${schema.name}.msg`), msg);
     }
   });
 
   await logProgress("Generating ROS 2 msg files", async () => {
     await fs.mkdir(path.join(outDir, "ros2"), { recursive: true });
+    await fs.mkdir(path.join(rosOutDir, "ros2"), { recursive: true });
     for (const schema of Object.values(foxgloveMessageSchemas)) {
       if (schema.rosEquivalent != undefined) {
         continue;
       }
-      await fs.writeFile(
-        path.join(outDir, "ros2", `${schema.name}.msg`),
-        generateRosMsg(generateRosMsgDefinition(schema, { rosVersion: 2 })),
-      );
+      const msg = generateRosMsg(generateRosMsgDefinition(schema, { rosVersion: 2 }));
+      await fs.writeFile(path.join(outDir, "ros2", `${schema.name}.msg`), msg);
+      await fs.writeFile(path.join(rosOutDir, "ros2", `${schema.name}.msg`), msg);
     }
   });
 
@@ -96,8 +97,18 @@ async function main({ outDir }: { outDir: string }) {
     }
     await fs.writeFile(path.join(outDir, "typescript", `index.ts`), indexTS);
   });
+
+  await logProgress("Generating README.md", async () => {
+    await fs.writeFile(
+      path.join(outDir, "README.md"),
+      generateMarkdown(Object.values(foxgloveMessageSchemas), Object.values(foxgloveEnumSchemas)),
+    );
+  });
 }
 
-program.requiredOption("-o, --out-dir <dir>", "output directory").action(main);
+program
+  .requiredOption("-o, --out-dir <dir>", "output directory")
+  .requiredOption("--ros-out-dir <dir>", "output directory for additional copies of ROS msgs")
+  .action(main);
 
 program.parseAsync().catch(console.error);

package/src/generateJsonSchema.test.ts

@@ -8,7 +8,7 @@ describe("generateJsonSchema", () => {
   it("generates expected JSON Schema", () => {
     expect(generateJsonSchema(exampleMessage)).toMatchInlineSnapshot(`
       Object {
-        "$comment": "Generated from ExampleMessage by @foxglove/schemas",
+        "$comment": "Generated by https://github.com/foxglove/schemas",
         "description": "An example type",
         "properties": Object {
           "field_boolean": Object {
@@ -121,7 +121,7 @@ describe("generateJsonSchema", () => {
                 "title": "B",
               },
             ],
-            "title": "ExampleEnum: An example enum",
+            "title": "foxglove.ExampleEnum",
           },
           "field_enum_array": Object {
             "description": "An enum array field",
@@ -139,7 +139,7 @@ describe("generateJsonSchema", () => {
                   "title": "B",
                 },
               ],
-              "title": "ExampleEnum: An example enum",
+              "title": "foxglove.ExampleEnum",
             },
             "type": "array",
           },
@@ -164,7 +164,6 @@ describe("generateJsonSchema", () => {
             "type": "array",
           },
           "field_nested": Object {
-            "$comment": "Generated from NestedMessage by @foxglove/schemas",
             "description": "A nested field",
             "properties": Object {
               "field_enum": Object {
@@ -173,7 +172,7 @@ describe("generateJsonSchema", () => {
                 "type": "integer",
               },
             },
-            "title": "NestedMessage",
+            "title": "foxglove.NestedMessage",
             "type": "object",
           },
           "field_nested_array": Object {
@@ -184,7 +183,6 @@ describe("generateJsonSchema", () => {
       long
       description",
             "items": Object {
-              "$comment": "Generated from NestedMessage by @foxglove/schemas",
               "description": "An example nested message",
               "properties": Object {
                 "field_enum": Object {
@@ -193,7 +191,7 @@ describe("generateJsonSchema", () => {
                   "type": "integer",
                 },
               },
-              "title": "NestedMessage",
+              "title": "foxglove.NestedMessage",
               "type": "object",
             },
             "type": "array",
@@ -298,7 +296,7 @@ describe("generateJsonSchema", () => {
             "type": "array",
           },
         },
-        "title": "ExampleMessage",
+        "title": "foxglove.ExampleMessage",
         "type": "object",
       }
     `);

package/src/generateJsonSchema.ts

@@ -45,10 +45,11 @@ export function generateJsonSchema(schema: FoxgloveMessageSchema): Record<string
         break;
       case "nested":
         fieldType = generateJsonSchema(field.type.schema);
+        delete fieldType.$comment;
         break;
       case "enum":
         fieldType = {
-          title: `${field.type.enum.name}: ${field.type.enum.description}`,
+          title: `foxglove.${field.type.enum.name}`,
           description: field.description,
           oneOf: field.type.enum.values.map(({ name, value, description }) => ({
             title: name,
@@ -73,9 +74,9 @@ export function generateJsonSchema(schema: FoxgloveMessageSchema): Record<string
   }
 
   return {
-    $comment: `Generated from ${schema.name} by @foxglove/schemas`,
-    title: schema.name,
+    title: `foxglove.${schema.name}`,
     description: schema.description,
+    $comment: "Generated by https://github.com/foxglove/schemas",
     type: "object",
     properties,
   };

package/src/generateMarkdown.ts

@@ -0,0 +1,86 @@
+import { FoxgloveEnumSchema, FoxgloveMessageSchema } from "./types";
+
+export function generateMarkdown(
+  schemas: Iterable<FoxgloveMessageSchema>,
+  enums: Iterable<FoxgloveEnumSchema>,
+): string {
+  const sortedSchemas = [...schemas].sort((a, b) => a.name.localeCompare(b.name));
+  const sortedEnums = [...enums].sort((a, b) => a.name.localeCompare(b.name));
+
+  return [
+    `\
+# Foxglove schemas
+
+Generated by https://github.com/foxglove/schemas`,
+
+    "## Contents",
+
+    [
+      ...sortedEnums.map(({ name }) => `- [enum ${name}](#enum-${name.toLowerCase()})`),
+      ...sortedSchemas.map(({ name }) => `- [${name}](#${name.toLowerCase()})`),
+    ].join("\n"),
+    "----",
+    sortedEnums.map(
+      (enumSchema) => `\
+## enum ${enumSchema.name}
+
+${enumSchema.description}
+
+name | value | description
+---- | ----- | -----------
+${enumSchema.values
+  .map((value) => `\`${value.name}\` | ${value.value} | ${value.description ?? ""}`)
+  .join("\n")}
+
+`,
+    ),
+    ...sortedSchemas.map(
+      (schema) => `\
+## ${schema.name}
+
+${schema.description}
+
+<table>
+  <tr>
+    <th>field</th>
+    <th>type</th>
+    <th>description</th>
+  </tr>
+${schema.fields
+  .map((field) => {
+    const arraySuffix =
+      typeof field.array === "number" ? `[${field.array}]` : field.array === true ? "[]" : "";
+    let type: string;
+    switch (field.type.type) {
+      case "enum":
+        type = `[enum ${field.type.enum.name}](#enum-${field.type.enum.name.toLowerCase()})`;
+        break;
+      case "nested":
+        type = `[${field.type.schema.name}](#${field.type.schema.name.toLowerCase()})`;
+        break;
+      case "primitive":
+        type = field.type.name;
+        break;
+    }
+    return `\
+<tr>
+<td><code>${field.name}</code></td>
+<td>
+
+${type}${arraySuffix}
+
+</td>
+<td>
+
+${field.description}
+
+</td>
+</tr>`;
+  })
+  .join("\n")}
+</table>`,
+    ),
+  ]
+    .flat()
+    .join("\n\n");
+}

package/src/generateProto.test.ts

@@ -7,7 +7,7 @@ import { exampleEnum, exampleMessage } from "./testFixtures";
 describe("generateProto", () => {
   it("generates .proto files", () => {
     expect(generateProto(exampleMessage, [exampleEnum])).toMatchInlineSnapshot(`
-      "// Generated from ExampleMessage by @foxglove/schemas
+      "// Generated by https://github.com/foxglove/schemas
 
       syntax = \\"proto3\\";
 

package/src/generateProto.ts

@@ -80,7 +80,7 @@ export function generateProto(
   )}${fields.join("\n\n")}\n}`;
 
   const outputSections = [
-    `// Generated from ${schema.name} by @foxglove/schemas`,
+    `// Generated by https://github.com/foxglove/schemas`,
     'syntax = "proto3";',
 
     Array.from(imports)