{
  "openapi": "3.1.1",
  "info": {
    "title": "Kinetica Collision Check API",
    "version": "1.0.0",
    "summary": "Robot pose + obstacles → collisions, minimum clearance and self-collision between links.",
    "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://kineticacollisioncheck.usefulweb.site"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "operationId": "calculate",
        "summary": "Robot pose + obstacles → collisions, minimum clearance and self-collision between links.",
        "description": "Checks a robot configuration against box, sphere and capsule obstacles and against itself. Robot links are modelled as capsules and boxes; the tool reports every pair closer than the safety margin, the minimum clearance and the closest pair, using exact segment–segment distances and an exact convex search for capsule–box distances.\n\nMethodology:\n- Robot links are capsules (segment + radius) and oriented boxes attached to the link frames; library robots generate capsules along the kinematic skeleton, URDF boxes/cylinders/spheres are imported (cylinders become capsules with caps ending at the cylinder faces; flat discs become an equal-area square prism).\n- Capsule–capsule: closest points between two segments minus both radii. Capsule–box: the squared distance from the segment to the box is convex in the segment parameter, so a 64-step golden-section search finds the minimum. Box–box: separating-axis test for overlap, else the minimum of the 24 edge-to-box distances.\n- Self-collision skips adjacent links, user-listed pairs and pairs that already touch in the robot’s home pose (as in MoveIt’s allowed-collision matrix); the static base link is not checked against the environment.\n- A pair counts as a contact when its clearance is below the safety margin.\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. Geometry is a simplified envelope of the real robot.",
        "tags": [
          "apps"
        ],
        "x-mcp-tool": "kinetica_collision_check",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/KineticaCollisionCheckInput"
              },
              "examples": {
                "example1": {
                  "summary": "6-axis arm above a table (clear)",
                  "value": {
                    "robot": "kx6-1400",
                    "joints": "0, 0, 0, 0, 90, 0",
                    "obstacles": [
                      {
                        "name": "Table",
                        "shape": "box",
                        "x": 900,
                        "y": 0,
                        "z": 350,
                        "sx": 700,
                        "sy": 900,
                        "sz": 700
                      }
                    ],
                    "margin": 10
                  }
                },
                "example2": {
                  "summary": "Arm reaching into a box (collision)",
                  "value": {
                    "robot": "kx6-1400",
                    "joints": "0, 40, 30, 0, 20, 0",
                    "obstacles": [
                      {
                        "name": "Machine",
                        "shape": "box",
                        "x": 1000,
                        "y": 0,
                        "z": 400,
                        "sx": 600,
                        "sy": 800,
                        "sz": 800
                      }
                    ],
                    "margin": 0
                  }
                },
                "example3": {
                  "summary": "Folded elbow: self-collision check",
                  "value": {
                    "robot": "kx6-1400",
                    "joints": "0, -90, 155, 0, 125, 0",
                    "self": true,
                    "margin": 0
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KineticaCollisionCheckResult"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      },
      "KineticaCollisionCheckInput": {
        "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": "Degrees / mm. Empty = home pose.",
            "type": "string",
            "default": ""
          },
          "obstacles": {
            "title": "Obstacles",
            "description": "Box: centre x, y, z and size sx, sy, sz. Sphere: centre and r. Capsule: start x, y, z, end x2, y2, z2 (in the size columns) and r. All in mm, world frame.",
            "type": "array",
            "maxItems": 50,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "name": {
                  "title": "Name",
                  "type": "string",
                  "maxLength": 40
                },
                "shape": {
                  "title": "Shape",
                  "type": "string",
                  "enum": [
                    "box",
                    "sphere",
                    "capsule"
                  ],
                  "default": "box"
                },
                "x": {
                  "title": "x",
                  "type": "number"
                },
                "y": {
                  "title": "y",
                  "type": "number"
                },
                "z": {
                  "title": "z",
                  "type": "number"
                },
                "sx": {
                  "title": "sx / x2",
                  "type": "number"
                },
                "sy": {
                  "title": "sy / y2",
                  "type": "number"
                },
                "sz": {
                  "title": "sz / z2",
                  "type": "number"
                },
                "r": {
                  "title": "r",
                  "type": "number",
                  "minimum": 0
                }
              },
              "required": [
                "x",
                "y",
                "z"
              ]
            }
          },
          "self": {
            "title": "Check self-collision",
            "type": "boolean",
            "default": true
          },
          "margin": {
            "title": "Safety margin",
            "type": "number",
            "minimum": 0,
            "maximum": 1000,
            "default": 10,
            "x-unit": "mm"
          }
        },
        "required": []
      },
      "KineticaCollisionCheckResult": {
        "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": [
              "collides",
              "minClearance",
              "contacts",
              "links",
              "checkedPairs"
            ],
            "properties": {
              "collides": {
                "type": "boolean"
              },
              "minClearance": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "closest": {
                "type": [
                  "object",
                  "null"
                ]
              },
              "contacts": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "a": {
                      "type": "string"
                    },
                    "b": {
                      "type": "string"
                    },
                    "distance": {
                      "type": "number"
                    },
                    "kind": {
                      "type": "string"
                    }
                  }
                }
              },
              "links": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "checkedPairs": {
                "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"
              }
            }
          }
        }
      }
    }
  }
}