{ "openapi": "3.1.1", "info": { "title": "Kinetica Inverse Kinematics API", "version": "1.0.0", "summary": "Target TCP pose → all joint solutions found, residuals, joint limits and reachability.", "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://kineticainversekinematics.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Target TCP pose → all joint solutions found, residuals, joint limits and reachability.", "description": "Solves the inverse kinematics of a serial robot (DH table, URDF subset or library robot) for a target TCP pose with damped least squares from several deterministic seeds, plus closed-form solutions for planar 2-link arms and SCARAs. Lists every distinct solution with its residual, joint-limit and singularity status, and explains why a target is unreachable.\n\nMethodology:\n- Error e = [Δp / L; Δφ] with Δφ the rotation vector from current to target orientation and L the arm’s characteristic length, restricted to the task rows the robot can actually control (e.g. x, y, z, yaw for a SCARA; x, y for a planar arm).\n- Damped least squares step Δq = Jᵀ(J·Jᵀ + λ²I)⁻¹e with adaptive damping λ (decrease after an improving step, increase after a failed one), step-size limit 0.5 rad, and projection onto the joint limits (revolute joints wrap by 2π when the range allows).\n- Restarts: the preferred configuration, the home pose, then pseudo-random configurations from a seeded mulberry32 generator; distinct converged solutions (position residual ≤ 1e-6 mm, orientation ≤ 1e-8 rad) are kept and sorted by distance to the preferred configuration.\n- Closed forms: planar 2R and SCARA use the law of cosines (two elbow branches), then FK verifies and a short DLS polish removes any remaining residual.\n- Unreachable targets report the distance from the first joint versus the skeleton length (upper bound of reach) and the closest configuration found.\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_inverse_kinematics", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KineticaInverseKinematicsInput" }, "examples": { "example1": { "summary": "6-axis arm, tool pointing down at (700, 200, 600) mm", "value": { "robot": "kx6-1400", "x": 700, "y": 200, "z": 600, "roll": 180, "pitch": 0, "yaw": 0 } }, "example2": { "summary": "SCARA closed form: (300, 250, 200) mm, yaw 45°", "value": { "robot": "scara-550", "x": 300, "y": 250, "z": 200, "roll": 180, "pitch": 0, "yaw": 45 } }, "example3": { "summary": "Planar arm: elbow-up and elbow-down for (350, 200)", "value": { "robot": "planar2", "x": 350, "y": 200, "z": 50, "roll": 0, "pitch": 0, "yaw": 0, "mode": "position" } }, "example4": { "summary": "Unreachable target (2 m away)", "value": { "robot": "ur5-like", "x": 2000, "y": 0, "z": 300, "roll": 180, "pitch": 0, "yaw": 0 } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KineticaInverseKinematicsResult" } } } }, "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" } } } } } }, "KineticaInverseKinematicsInput": { "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": "" }, "x": { "title": "Target x", "type": "number", "default": 700, "x-unit": "mm" }, "y": { "title": "Target y", "type": "number", "default": 200, "x-unit": "mm" }, "z": { "title": "Target z", "type": "number", "default": 600, "x-unit": "mm" }, "roll": { "title": "Roll", "type": "number", "default": 180, "x-unit": "deg" }, "pitch": { "title": "Pitch", "type": "number", "default": 0, "x-unit": "deg" }, "yaw": { "title": "Yaw", "type": "number", "default": 0, "x-unit": "deg" }, "mode": { "title": "Task", "type": "string", "enum": [ "auto", "full", "position" ], "default": "auto" }, "seed": { "title": "Preferred configuration", "description": "Joint values the solutions are sorted by (closest first). Empty = home pose.", "type": "string", "default": "" }, "restarts": { "title": "Random restarts", "type": "integer", "minimum": 0, "maximum": 64, "default": 12 }, "rngSeed": { "title": "Random seed", "description": "Seeds the deterministic restart generator, so the same input always gives the same solutions.", "type": "integer", "minimum": 0, "maximum": 2147483647, "default": 7 } }, "required": [ "x", "y", "z" ] }, "KineticaInverseKinematicsResult": { "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": [ "ok", "solutions", "reach", "message", "task" ], "properties": { "ok": { "type": "boolean" }, "message": { "type": "string" }, "task": { "type": "array", "items": { "type": "string" } }, "best": { "type": [ "object", "null" ] }, "solutions": { "type": "array", "items": { "type": "object", "properties": { "joints": { "type": "array", "items": { "type": "number" } }, "posError": { "type": "number" }, "rotErrorDeg": { "type": "number" }, "withinLimits": { "type": "boolean" }, "status": { "type": "string" }, "manipulability": { "type": "number" }, "source": { "type": "string" } } } }, "roundTrip": { "type": [ "object", "null" ] }, "reach": { "type": "object", "properties": { "distance": { "type": "number" }, "maxReach": { "type": "number" }, "inReach": { "type": "boolean" } } }, "closest": { "type": [ "object", "null" ] }, "attempts": { "type": "integer" } } }, "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" } } } } } } } }