{ "openapi": "3.1.1", "info": { "title": "Kinetica Forward Kinematics API", "version": "1.0.0", "summary": "DH table or URDF + joint values → TCP pose, every joint frame, Jacobian and manipulability.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://kineticaforwardkinematics.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "DH table or URDF + joint values → TCP pose, every joint frame, Jacobian and manipulability.", "description": "Computes the tool-centre-point pose of a serial robot from its Denavit–Hartenberg table (standard or modified), a URDF subset or a library robot and the joint values. Returns the 4×4 transform, position and roll/pitch/yaw, quaternion, all intermediate frames, the geometric Jacobian, manipulability and singularity status, and static payload torques.\n\nMethodology:\n- Each joint compiles to Fᵢ = Fᵢ₋₁ · Preᵢ · Motionᵢ(qᵢ) · Postᵢ. Standard DH: Rz(θ+q)·Tz(d)·Tx(a)·Rx(α); modified DH (Craig): Rx(α)·Tx(a)·Rz(θ+q)·Tz(d); URDF: origin(xyz, rpy) · rotation about / translation along the joint axis.\n- TCP = base mount · F_n · tool offset. Orientation is reported as fixed-axis roll-pitch-yaw (R = Rz(yaw)·Ry(pitch)·Rx(roll), the URDF convention) and as a unit quaternion [w, x, y, z].\n- Geometric Jacobian at the TCP: revolute column [zᵢ × (p − oᵢ); zᵢ], prismatic column [zᵢ; 0]. Rows vx, vy, vz in mm per rad (or per mm), wx, wy, wz in rad per unit.\n- Manipulability: Yoshikawa √det(J·Jᵀ) of the Jacobian with translation rows divided by a characteristic length (the arm’s skeleton length), and σmin/σmax as a 0–1 singularity indicator (< 0.001 singular, < 0.03 near-singular).\n- Payload loads: static holding torque τ = −Jᵀ(cog)·m·g for the tool mass at its centre of gravity (g = 9.80665 m/s², gravity along −z world).\n- Verified against hand-computed planar cases, the PUMA 560 qz pose (452.1, −150.05, 1103.63) mm of the Robotics Toolbox model and the UR5 zero pose (−817.25, −191.45, −5.491) mm.\n\nKinematic simulation for planning and teaching. It is not a certified safety function: verify every program on the real controller with reduced speed and the cell safety system active.", "tags": [ "apps" ], "x-mcp-tool": "kinetica_forward_kinematics", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KineticaForwardKinematicsInput" }, "examples": { "example1": { "summary": "PUMA 560 at qz (all zeros) — textbook pose", "value": { "robot": "puma560", "joints": "0, 0, 0, 0, 0, 0" } }, "example2": { "summary": "UR5-style cobot at its upright home", "value": { "robot": "ur5-like", "joints": "0, -90, 90, -90, -90, 0" } }, "example3": { "summary": "Planar 2-link arm from a custom DH table (l1 = 300, l2 = 250)", "value": { "robot": "custom-dh", "convention": "dh", "dh": [ { "type": "revolute", "a": 300, "alpha": 0, "d": 0, "theta": 0 }, { "type": "revolute", "a": 250, "alpha": 0, "d": 0, "theta": 0 } ], "joints": "30, 60" } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KineticaForwardKinematicsResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "KineticaForwardKinematicsInput": { "type": "object", "additionalProperties": false, "properties": { "robot": { "title": "Robot", "description": "A library robot, or choose a custom DH table, URDF or Kinetica robot JSON.", "type": "string", "enum": [ "kx6-1400", "ur5-like", "puma560", "scara-550", "gantry-xyz", "planar2", "custom-dh", "urdf", "json" ], "default": "kx6-1400" }, "convention": { "title": "DH convention (custom table)", "type": "string", "enum": [ "dh", "mdh" ], "default": "dh" }, "dh": { "title": "DH table (custom)", "description": "One row per joint. Lengths in mm, angles in degrees. For revolute joints θ is the zero offset, for prismatic joints d is.", "type": "array", "maxItems": 12, "items": { "type": "object", "additionalProperties": false, "properties": { "type": { "title": "Type", "type": "string", "enum": [ "revolute", "prismatic" ], "default": "revolute" }, "a": { "title": "a (mm)", "type": "number", "default": 0 }, "alpha": { "title": "α (deg)", "type": "number", "default": 0 }, "d": { "title": "d (mm)", "type": "number", "default": 0 }, "theta": { "title": "θ (deg)", "type": "number", "default": 0 }, "min": { "title": "min", "type": "number" }, "max": { "title": "max", "type": "number" }, "vmax": { "title": "v max (/s)", "type": "number" }, "amax": { "title": "a max (/s²)", "type": "number" } }, "required": [] } }, "robotText": { "title": "URDF or robot JSON", "description": "Used when Robot is “URDF” or “Kinetica robot JSON”. URDF subset: links with box/cylinder/sphere, revolute/continuous/prismatic/fixed joints.", "type": "string", "maxLength": 400000 }, "tool": { "title": "Tool offset (TCP)", "description": "x, y, z (mm), roll, pitch, yaw (deg) in the flange frame, e.g. “0, 0, 150, 0, 0, 0”. Empty = robot default.", "type": "string", "default": "" }, "joints": { "title": "Joint values", "description": "Comma-separated, degrees for revolute and mm for prismatic joints. Empty = the robot’s home pose.", "type": "string", "default": "" } }, "required": [] }, "KineticaForwardKinematicsResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "required": [ "robot", "dof", "joints", "tcp", "matrix", "frames", "jacobian", "manipulability", "withinLimits" ], "properties": { "robot": { "type": "string" }, "dof": { "type": "integer" }, "joints": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "number" }, "unit": { "type": "string" } } } }, "tcp": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "z": { "type": "number" }, "roll": { "type": "number" }, "pitch": { "type": "number" }, "yaw": { "type": "number" }, "quat": { "type": "array", "items": { "type": "number" } } }, "required": [ "x", "y", "z", "roll", "pitch", "yaw", "quat" ] }, "flange": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "z": { "type": "number" }, "roll": { "type": "number" }, "pitch": { "type": "number" }, "yaw": { "type": "number" }, "quat": { "type": "array", "items": { "type": "number" } } }, "required": [ "x", "y", "z", "roll", "pitch", "yaw", "quat" ] }, "matrix": { "type": "array", "items": { "type": "array", "items": { "type": "number" } } }, "frames": { "type": "array", "items": { "type": "object" } }, "jacobian": { "type": "array", "items": { "type": "array", "items": { "type": "number" } } }, "manipulability": { "type": "object", "properties": { "yoshikawa": { "type": "number" }, "inverseCondition": { "type": "number" }, "status": { "type": "string" } } }, "payloadLoads": { "type": "array", "items": { "type": "number" } }, "withinLimits": { "type": "boolean" }, "violatedJoints": { "type": "array", "items": { "type": "string" } } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }