@holoscript/robotics-plugin 1.0.0

package/dist/usd-codegen.d.ts

@@ -0,0 +1,18 @@
+/**
+ * HoloScript → USD Code Generator
+ *
+ * Generates Universal Scene Description (USD) files from HoloScript AST.
+ * Targets NVIDIA Isaac Sim with UsdPhysics schema.
+ */
+import { CompositionNode } from './ast';
+export declare class USDCodeGen {
+    private output;
+    private indentLevel;
+    generate(ast: CompositionNode): string;
+    private generateLink;
+    private generateJoint;
+    private indent;
+    private emit;
+    private geometryToUSD;
+    private vectorToAxisName;
+}

package/dist/usd-codegen.js

@@ -0,0 +1,361 @@
+"use strict";
+/**
+ * HoloScript → USD Code Generator
+ *
+ * Generates Universal Scene Description (USD) files from HoloScript AST.
+ * Targets NVIDIA Isaac Sim with UsdPhysics schema.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.USDCodeGen = void 0;
+class USDCodeGen {
+    constructor() {
+        this.output = [];
+        this.indentLevel = 0;
+    }
+    generate(ast) {
+        this.output = [];
+        this.indentLevel = 0;
+        // USD header
+        this.emit('#usda 1.0');
+        this.emit('(');
+        this.indentLevel++;
+        this.emit(`defaultPrim = "${ast.name}"`);
+        this.emit('upAxis = "Z"');
+        this.emit('metersPerUnit = 1.0');
+        this.emit('kilogramsPerMass = 1.0');
+        this.indentLevel--;
+        this.emit(')');
+        this.emit('');
+        // Root articulation
+        this.emit(`def Xform "${ast.name}" (`);
+        this.indentLevel++;
+        this.emit('prepend apiSchemas = ["PhysicsArticulationRootAPI"]');
+        this.indentLevel--;
+        this.emit(')');
+        this.emit('{');
+        this.indentLevel++;
+        // Collect joints for later generation
+        const joints = [];
+        // Separate joint and link objects
+        const jointObjects = [];
+        const linkObjects = [];
+        for (const obj of ast.objects) {
+            if (obj.traits.includes('joint_revolute') || obj.traits.includes('joint_prismatic')) {
+                jointObjects.push(obj);
+            }
+            else {
+                linkObjects.push(obj);
+            }
+        }
+        // Generate links
+        for (const obj of ast.objects) {
+            if (obj.traits.includes('joint_revolute') || obj.traits.includes('joint_prismatic')) {
+                // New template format: Joint is separate object
+                // Check if there's a corresponding link (child of this joint)
+                const childLink = linkObjects.find(link => link.properties.parent === obj.name);
+                if (childLink) {
+                    // Generate the child link
+                    this.generateLink(childLink);
+                    // Collect joint info
+                    const parent = obj.properties.parent || 'World';
+                    joints.push({
+                        name: obj.name,
+                        parent,
+                        child: childLink.name,
+                        props: obj.properties,
+                    });
+                }
+                else {
+                    // Old format: joint_parent property (backward compatibility)
+                    this.generateLink(obj);
+                    const parent = obj.properties.joint_parent || 'World';
+                    joints.push({
+                        name: `${obj.name}Joint`,
+                        parent,
+                        child: obj.name,
+                        props: obj.properties,
+                    });
+                }
+            }
+            else {
+                // Link object without joint (base, end effector, etc.)
+                // Only generate if not already generated as child of a joint
+                const isChildOfJoint = jointObjects.some(j => linkObjects.find(l => l.properties.parent === j.name && l.name === obj.name));
+                if (!isChildOfJoint) {
+                    this.generateLink(obj);
+                }
+            }
+        }
+        // Generate joints after all links
+        this.emit('');
+        this.emit('# Joints');
+        for (const joint of joints) {
+            this.generateJoint(joint);
+        }
+        this.indentLevel--;
+        this.emit('}');
+        return this.output.join('\n');
+    }
+    generateLink(obj) {
+        const geometry = obj.properties.geometry || 'box';
+        const usdType = this.geometryToUSD(geometry);
+        const isStatic = obj.traits.includes('static');
+        this.emit('');
+        this.emit(`# ${obj.name}`);
+        this.emit(`def ${usdType} "${obj.name}" (`);
+        this.indentLevel++;
+        // Add physics APIs (unless static)
+        if (!isStatic) {
+            this.emit('prepend apiSchemas = ["PhysicsCollisionAPI", "PhysicsRigidBodyAPI", "PhysicsMassAPI"]');
+        }
+        this.indentLevel--;
+        this.emit(')');
+        this.emit('{');
+        this.indentLevel++;
+        // Geometry dimensions (support both array and individual properties)
+        if (geometry === 'cylinder') {
+            let radius, height;
+            if (obj.properties.dimensions) {
+                // Old format: dimensions: [radius, height]
+                const dims = obj.properties.dimensions;
+                [radius, height] = dims;
+            }
+            else {
+                // New format: radius: 0.2, height/length: 0.2
+                radius = obj.properties.radius || 0.1;
+                height = (obj.properties.height || obj.properties.length) || 0.1;
+            }
+            this.emit(`float radius = ${radius}`);
+            this.emit(`float height = ${height}`);
+        }
+        else if (geometry === 'box') {
+            let length, width, height;
+            if (obj.properties.dimensions) {
+                // Old format: dimensions: [length, width, height]
+                const dims = obj.properties.dimensions;
+                [length, width, height] = dims;
+            }
+            else {
+                // New format: length: 1.0, width: 0.1, height: 0.1
+                length = obj.properties.length || 1.0;
+                width = obj.properties.width || 1.0;
+                height = obj.properties.height || 1.0;
+            }
+            this.emit('double size = 1.0');
+            this.emit(`float3 xformOp:scale = (${length}, ${width}, ${height})`);
+            this.emit('uniform token[] xformOpOrder = ["xformOp:scale"]');
+        }
+        else if (geometry === 'sphere') {
+            let radius;
+            if (obj.properties.dimensions) {
+                // Old format: dimensions: [radius]
+                const dims = obj.properties.dimensions;
+                [radius] = dims;
+            }
+            else {
+                // New format: radius: 0.08
+                radius = obj.properties.radius || 0.1;
+            }
+            this.emit(`float radius = ${radius}`);
+        }
+        // Color/Material
+        if (obj.properties.color) {
+            const color = obj.properties.color;
+            const [r, g, b] = color;
+            this.emit(`color3f[] primvars:displayColor = [(${r}, ${g}, ${b})]`);
+        }
+        else if (obj.properties.material) {
+            // Default colors based on material
+            const materialColors = {
+                'metal': '0.6, 0.6, 0.65',
+                'plastic': '0.8, 0.8, 0.8',
+                'wood': '0.6, 0.4, 0.2',
+                'glass': '0.9, 0.9, 1.0',
+            };
+            const material = obj.properties.material;
+            const color = materialColors[material] || '0.8, 0.8, 0.8';
+            this.emit(`color3f[] primvars:displayColor = [(${color})]`);
+        }
+        // Physics properties
+        if (!isStatic) {
+            this.emit('');
+            this.emit('# Physics properties');
+            const mass = obj.properties.mass || 1.0;
+            this.emit(`float physics:mass = ${mass}`);
+            if (obj.properties.inertia) {
+                const inertia = obj.properties.inertia;
+                this.emit(`float3 physics:diagonalInertia = (${inertia[0]}, ${inertia[1]}, ${inertia[2]})`);
+            }
+            this.emit('uniform token physics:approximation = "convexHull"');
+        }
+        else {
+            this.emit('');
+            this.emit('# Static object');
+            this.emit('uniform token physics:rigidBodyEnabled = false');
+        }
+        // Position (if specified)
+        if (obj.properties.position) {
+            const pos = obj.properties.position;
+            this.emit('');
+            this.emit(`double3 xformOp:translate = (${pos[0]}, ${pos[1]}, ${pos[2]})`);
+            if (!obj.properties.dimensions) {
+                this.emit('uniform token[] xformOpOrder = ["xformOp:translate"]');
+            }
+        }
+        this.indentLevel--;
+        this.emit('}');
+    }
+    generateJoint(joint) {
+        this.emit('');
+        this.emit(`def PhysicsRevoluteJoint "${joint.name}"`);
+        this.emit('{');
+        this.indentLevel++;
+        // Body references
+        this.emit(`rel physics:body0 = <../${joint.parent}>`);
+        this.emit(`rel physics:body1 = <../${joint.child}>`);
+        this.emit('');
+        // Joint frames
+        const origin = joint.props.joint_origin || joint.props.position;
+        if (origin) {
+            const pos = origin;
+            this.emit(`point3f physics:localPos0 = (${pos[0]}, ${pos[1]}, ${pos[2]})`);
+        }
+        else {
+            this.emit('point3f physics:localPos0 = (0, 0, 0)');
+        }
+        this.emit('quatf physics:localRot0 = (1, 0, 0, 0)');
+        this.emit('');
+        this.emit('point3f physics:localPos1 = (0, 0, 0)');
+        this.emit('quatf physics:localRot1 = (1, 0, 0, 0)');
+        this.emit('');
+        // Joint axis (support both old and new property names)
+        const axis = joint.props.joint_axis || joint.props.axis;
+        if (axis) {
+            const axisVec = axis;
+            const axisName = this.vectorToAxisName(axisVec);
+            this.emit(`uniform token physics:axis = "${axisName}"`);
+        }
+        else {
+            this.emit('uniform token physics:axis = "Y"');
+        }
+        this.emit('');
+        // Joint limits (support both old and new property names)
+        const limits = joint.props.joint_limits || joint.props.limits;
+        if (limits) {
+            const limitsVec = limits;
+            this.emit(`float physics:lowerLimit = ${limitsVec[0]}`);
+            this.emit(`float physics:upperLimit = ${limitsVec[1]}`);
+        }
+        this.emit('');
+        // Joint dynamics (support both old and new property names)
+        const effort = joint.props.joint_effort || joint.props.max_effort;
+        if (effort) {
+            this.emit(`float physics:maxForce = ${effort}`);
+        }
+        const velocity = joint.props.max_velocity;
+        if (velocity) {
+            this.emit(`float physics:maxVelocity = ${velocity}`);
+        }
+        this.indentLevel--;
+        this.emit('}');
+    }
+    indent() {
+        return '    '.repeat(this.indentLevel);
+    }
+    emit(line) {
+        this.output.push(this.indent() + line);
+    }
+    geometryToUSD(geometry) {
+        const mapping = {
+            'cylinder': 'Cylinder',
+            'box': 'Cube',
+            'sphere': 'Sphere',
+            'cone': 'Cone',
+            'plane': 'Plane',
+            'torus': 'Torus',
+        };
+        return mapping[geometry] || 'Cube';
+    }
+    vectorToAxisName(axis) {
+        const [x = 0, y = 0, z = 1] = axis;
+        if (Math.abs(x) > Math.abs(y) && Math.abs(x) > Math.abs(z)) {
+            return 'X';
+        }
+        else if (Math.abs(y) > Math.abs(z)) {
+            return 'Y';
+        }
+        else {
+            return 'Z';
+        }
+    }
+}
+exports.USDCodeGen = USDCodeGen;
+// Example usage
+if (require.main === module) {
+    Promise.resolve().then(() => __importStar(require('./lexer'))).then(({ Lexer }) => {
+        Promise.resolve().then(() => __importStar(require('./parser'))).then(({ Parser }) => {
+            const source = `
+composition "TwoLinkArm" {
+  object "Base" @static {
+    geometry: "cylinder"
+    dimensions: [0.1, 0.05]
+    material: "metal"
+    position: [0, 0, 0]
+  }
+
+  object "Link1" @joint_revolute {
+    geometry: "box"
+    dimensions: [0.5, 0.1, 0.1]
+    material: "metal"
+    joint_parent: "Base"
+    joint_axis: [0, 0, 1]
+    joint_limits: [-3.14, 3.14]
+    joint_effort: 100
+    mass: 1.0
+  }
+}
+`;
+            const lexer = new Lexer(source);
+            const tokens = lexer.tokenize();
+            const parser = new Parser(tokens);
+            const ast = parser.parse();
+            const codegen = new USDCodeGen();
+            const usd = codegen.generate(ast);
+            console.log('USD Output:');
+            console.log(usd);
+        });
+    });
+}

package/examples/robot-arm-complete.holo

@@ -0,0 +1,199 @@
+/**
+ * Complete Robotics Example: 2-DOF Robot Arm
+ * Demonstrates compile-time (USD/URDF) + runtime (ROS2/VR control)
+ *
+ * Features:
+ * - @ros_node: ROS2 runtime integration
+ * - @gazebo_sim: Gazebo physics simulation
+ * - @urdf_export: Export to URDF format
+ * - @robot_joint: Articulated joints with limits
+ * - VR teleoperation: Control robot with VR controllers
+ */
+
+scene "Robotics Lab" {
+  background: "#1a1a2e";
+  lighting: "industrial";
+  camera_position: [2, 1.5, 3];
+}
+
+// 2-DOF Robot Arm with ROS2 integration
+object "TwoLinkArm" @ros_node @gazebo_sim @urdf_export {
+  // ROS2 configuration
+  ros_bridge_url: "ws://localhost:9090",
+  namespace: "/robot_arm",
+  tf_prefix: "arm_",
+
+  // Gazebo simulation
+  gazebo_world: "empty.world",
+  physics_engine: "ode",
+  gravity: [0, 0, -9.81],
+
+  // Robot structure
+  links: [
+    {
+      name: "base_link",
+      visual: {
+        geometry: "cylinder",
+        dimensions: [0.1, 0.05],
+        material: "steel",
+      },
+      collision: { geometry: "cylinder", dimensions: [0.1, 0.05] },
+      inertial: { mass: 1.0, inertia: [0.01, 0.01, 0.01, 0, 0, 0] },
+      position: [0, 0, 0],
+    },
+    {
+      name: "link1",
+      visual: {
+        geometry: "box",
+        dimensions: [0.05, 0.05, 0.5],
+        material: "aluminum",
+      },
+      collision: { geometry: "box", dimensions: [0.05, 0.05, 0.5] },
+      inertial: { mass: 0.5, inertia: [0.01, 0.01, 0.001, 0, 0, 0] },
+    },
+    {
+      name: "link2",
+      visual: {
+        geometry: "box",
+        dimensions: [0.05, 0.05, 0.4],
+        material: "carbon_fiber",
+      },
+      collision: { geometry: "box", dimensions: [0.05, 0.05, 0.4] },
+      inertial: { mass: 0.3, inertia: [0.005, 0.005, 0.001, 0, 0, 0] },
+    },
+  ],
+
+  // Joints with actuators
+  joints: [
+    {
+      name: "shoulder_joint",
+      type: "revolute",
+      parent: "base_link",
+      child: "link1",
+      axis: [0, 0, 1],
+      origin: { position: [0, 0, 0.05], rotation: [0, 0, 0] },
+      limits: { lower: -3.14, upper: 3.14, effort: 10.0, velocity: 2.0 },
+      actuator: {
+        type: "position",
+        kp: 100.0,
+        kd: 10.0,
+      },
+    },
+    {
+      name: "elbow_joint",
+      type: "revolute",
+      parent: "link1",
+      child: "link2",
+      axis: [0, 1, 0],
+      origin: { position: [0, 0, 0.5], rotation: [0, 0, 0] },
+      limits: { lower: -2.0, upper: 2.0, effort: 5.0, velocity: 1.5 },
+      actuator: {
+        type: "position",
+        kp: 50.0,
+        kd: 5.0,
+      },
+    },
+  ],
+
+  // VR teleoperation
+  vr_control: {
+    enabled: true,
+    controller_mapping: {
+      left_hand: "shoulder_joint",  // Left VR controller → shoulder
+      right_hand: "elbow_joint",     // Right VR controller → elbow
+    },
+    force_feedback: true,            // Haptic feedback when robot hits limits
+    inverse_kinematics: true,        // IK solver for end-effector control
+  },
+
+  // Digital twin sync
+  twin_sync: {
+    enabled: true,
+    sync_rate: 30,  // 30 Hz (sync every 33ms)
+    bidirectional: true,  // Real robot ↔ VR twin
+    sensors: [
+      { type: "joint_states", topic: "/joint_states" },
+      { type: "tf", topic: "/tf" },
+    ],
+  },
+
+  // Export options
+  export: {
+    urdf: "build/two_link_arm.urdf",
+    sdf: "build/two_link_arm.sdf",
+    usd: "build/two_link_arm.usd",  // For NVIDIA Isaac Sim
+    mjcf: "build/two_link_arm.xml",  // For MuJoCo
+  },
+}
+
+// Example 2: Mobile robot (differential drive)
+object "MobileBot" @ros_node @gazebo_sim {
+  ros_bridge_url: "ws://localhost:9090",
+  namespace: "/mobile_bot",
+
+  // Chassis
+  links: [
+    {
+      name: "chassis",
+      visual: { geometry: "box", dimensions: [0.4, 0.3, 0.1], material: "plastic" },
+      inertial: { mass: 5.0 },
+    },
+    {
+      name: "left_wheel",
+      visual: { geometry: "cylinder", dimensions: [0.1, 0.05], material: "rubber" },
+      inertial: { mass: 0.5 },
+    },
+    {
+      name: "right_wheel",
+      visual: { geometry: "cylinder", dimensions: [0.1, 0.05], material: "rubber" },
+      inertial: { mass: 0.5 },
+    },
+  ],
+
+  joints: [
+    {
+      name: "left_wheel_joint",
+      type: "continuous",
+      parent: "chassis",
+      child: "left_wheel",
+      axis: [0, 1, 0],
+      actuator: { type: "velocity" },
+    },
+    {
+      name: "right_wheel_joint",
+      type: "continuous",
+      parent: "chassis",
+      child: "right_wheel",
+      axis: [0, 1, 0],
+      actuator: { type: "velocity" },
+    },
+  ],
+
+  // Differential drive controller
+  drive_controller: {
+    type: "diff_drive",
+    wheel_separation: 0.3,
+    wheel_radius: 0.1,
+    max_velocity: 1.0,  // m/s
+    max_angular_velocity: 2.0,  // rad/s
+  },
+
+  // Sensors
+  sensors: [
+    {
+      name: "lidar",
+      type: "laser",
+      update_rate: 10,
+      topic: "/scan",
+      range: { min: 0.1, max: 10.0 },
+      fov: 360,
+    },
+    {
+      name: "camera",
+      type: "camera",
+      update_rate: 30,
+      topic: "/camera/image_raw",
+      resolution: [640, 480],
+    },
+  ],
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@holoscript/robotics-plugin",
+  "version": "1.0.0",
+  "description": "HoloScript plugin for robotics: compile-time USD/URDF codegen + runtime ROS2/Gazebo integration. VR robot programming and digital twins.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "python",
+    "examples",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "jest --passWithNoTests",
+    "clean": "rimraf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "holoscript",
+    "plugin",
+    "robotics",
+    "ros2",
+    "gazebo",
+    "urdf",
+    "usd",
+    "vr",
+    "digital-twin",
+    "isaac-sim",
+    "webots",
+    "mujoco"
+  ],
+  "author": "HoloScript Contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/holoscript/holoscript-robotics-plugin.git"
+  },
+  "homepage": "https://github.com/holoscript/holoscript-robotics-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/holoscript/holoscript-robotics-plugin/issues"
+  },
+  "peerDependencies": {
+    "holoscript": "^3.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.0",
+    "@types/jest": "^29.5.0",
+    "rimraf": "^5.0.0"
+  },
+  "python": {
+    "requirements": [
+      "roslibpy>=1.6.0"
+    ],
+    "systemDependencies": [
+      "# ROS2 Humble or later (optional, for local ROS2 nodes)",
+      "# rosbridge-server (for WebSocket bridge)"
+    ]
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}