{ "openapi": "3.1.1", "info": { "title": "3D Scene and Render Pass Preview API", "version": "1.0.0", "summary": "Light a Kerfwise concept and inspect beauty, color, normals, depth and object IDs.", "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://kerfwisescenepreview.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Light a Kerfwise concept and inspect beauty, color, normals, depth and object IDs.", "description": "Render a small deterministic SVG preview from a Form Studio project or Render Desk recipe. Download the preview and editable recipe, then continue locally in Kerfwise with higher resolution and sampling.\n\nMethodology:\n- Independent concept renderer for Kerfwise extrusions. It uses orthographic camera rays, direct light with sampled soft shadows, short-range ambient occlusion and one metal reflection. It does not run MoonRay or import its scenes.\n- Coordinates are millimetres, Z up. Hidden solids are excluded. Source colors are decoded from sRGB for lighting; the beauty pass returns display sRGB. Normal, depth and object-ID passes are display diagnostics, not EXR or Cryptomatte.\n- Seeds and sample positions are deterministic. API previews allow 32–128 pixels per side and 1–4 samples, at most 65536 pixel samples. Render Desk supports larger local previews, at most 4096 visible triangles, 384000 pixels and 6 million pixel samples.\n\nConcept previews only. No MoonRay execution, scene import, unbiased path tracing or EXR output.", "tags": [ "apps" ], "x-mcp-tool": "kerfwise_scene_preview", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KerfwiseScenePreviewInput" }, "examples": { "example1": { "summary": "Terraced forms in soft light", "value": {} }, "example2": { "summary": "Inspect surface normals", "value": { "pass": "normal", "samples": 1 } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KerfwiseScenePreviewResult" } } } }, "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" } } } } } }, "KerfwiseScenePreviewInput": { "type": "object", "additionalProperties": false, "properties": { "project": { "title": "Form project or render recipe JSON", "type": "string", "maxLength": 250000, "default": "{\"format\":\"kerfwise-form\",\"version\":1,\"name\":\"Terraced forms\",\"units\":\"mm\",\"grid\":100,\"snap\":true,\"objects\":[{\"id\":\"part-1\",\"name\":\"Terrace 1\",\"tag\":\"Objects\",\"color\":\"#d6c5ab\",\"profile\":[[0,0],[2200,0],[2200,1800],[0,1800]],\"height\":300,\"x\":-1100,\"y\":-900,\"z\":0,\"rotation\":0,\"visible\":true,\"locked\":false},{\"id\":\"part-2\",\"name\":\"Terrace 2\",\"tag\":\"Objects\",\"color\":\"#b5c5b6\",\"profile\":[[0,0],[1800,0],[1800,1500],[0,1500]],\"height\":300,\"x\":-900,\"y\":-750,\"z\":300,\"rotation\":0,\"visible\":true,\"locked\":false},{\"id\":\"part-3\",\"name\":\"Terrace 3\",\"tag\":\"Objects\",\"color\":\"#789b90\",\"profile\":[[0,0],[1400,0],[1400,1200],[0,1200]],\"height\":300,\"x\":-700,\"y\":-600,\"z\":600,\"rotation\":0,\"visible\":true,\"locked\":false},{\"id\":\"part-4\",\"name\":\"Terrace 4\",\"tag\":\"Objects\",\"color\":\"#3e6662\",\"profile\":[[0,0],[1000,0],[1000,900],[0,900]],\"height\":300,\"x\":-500,\"y\":-450,\"z\":900,\"rotation\":0,\"visible\":true,\"locked\":false}],\"scenes\":[{\"name\":\"Overview\",\"camera\":{\"azimuth\":-45,\"elevation\":32,\"target\":[0,0,600],\"span\":3548.2671827245476}},{\"name\":\"Plan view\",\"camera\":{\"azimuth\":-90,\"elevation\":90,\"target\":[0,0,600],\"span\":3548.2671827245476}}]}" }, "width": { "title": "Preview width (px)", "type": "number", "minimum": 32, "maximum": 128, "default": 96 }, "height": { "title": "Preview height (px)", "type": "number", "minimum": 32, "maximum": 128, "default": 72 }, "samples": { "title": "Samples per pixel", "type": "number", "minimum": 1, "maximum": 4, "default": 2 }, "pass": { "title": "Render pass", "type": "string", "enum": [ "beauty", "albedo", "normal", "depth", "shadow", "object" ], "default": "beauty" } }, "required": [] }, "KerfwiseScenePreviewResult": { "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", "additionalProperties": false, "required": [ "recipe", "plan", "pass", "preview", "recipeFile", "openInApp" ], "properties": { "recipe": { "type": "object", "additionalProperties": false, "required": [ "format", "version", "source", "camera", "settings", "materials" ], "properties": { "format": { "const": "kerfwise-render" }, "version": { "const": 1 }, "source": { "type": "object", "additionalProperties": false, "required": [ "format", "version", "name", "units", "grid", "snap", "objects", "scenes" ], "properties": { "format": { "const": "kerfwise-form" }, "version": { "const": 1 }, "name": { "type": "string", "maxLength": 120 }, "units": { "enum": [ "mm", "in" ] }, "grid": { "type": "number", "minimum": 0.1, "maximum": 10000 }, "snap": { "type": "boolean" }, "objects": { "type": "array", "maxItems": 128, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "tag", "color", "profile", "height", "x", "y", "z", "rotation", "visible", "locked" ], "properties": { "id": { "type": "string", "pattern": "^[-a-zA-Z0-9_]{1,64}$" }, "name": { "type": "string", "maxLength": 80 }, "tag": { "type": "string", "maxLength": 40 }, "color": { "type": "string", "pattern": "^#[a-fA-F0-9]{6}$" }, "profile": { "type": "array", "minItems": 3, "maxItems": 64, "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "number", "minimum": -100000, "maximum": 100000 } } }, "height": { "type": "number", "minimum": 1, "maximum": 100000 }, "x": { "type": "number", "minimum": -100000, "maximum": 100000 }, "y": { "type": "number", "minimum": -100000, "maximum": 100000 }, "z": { "type": "number", "minimum": -100000, "maximum": 100000 }, "rotation": { "type": "number" }, "tiltX": { "type": "number", "minimum": -180, "maximum": 180 }, "tiltY": { "type": "number", "minimum": -180, "maximum": 180 }, "visible": { "type": "boolean" }, "locked": { "type": "boolean" }, "orthogonal": { "type": "string", "maxLength": 12000 } } } }, "scenes": { "type": "array", "maxItems": 8, "items": { "type": "object", "additionalProperties": false, "required": [ "name", "camera" ], "properties": { "name": { "type": "string", "maxLength": 60 }, "camera": { "type": "object", "additionalProperties": false, "required": [ "azimuth", "elevation", "span", "target" ], "properties": { "azimuth": { "type": "number" }, "elevation": { "type": "number", "minimum": 5, "maximum": 90 }, "span": { "type": "number", "minimum": 10, "maximum": 1000000 }, "target": { "type": "array", "minItems": 3, "maxItems": 3, "items": { "type": "number" } } } } } } } } }, "camera": { "type": "object", "additionalProperties": false, "required": [ "azimuth", "elevation", "span", "target" ], "properties": { "azimuth": { "type": "number", "minimum": -3600, "maximum": 3600 }, "elevation": { "type": "number", "minimum": 5, "maximum": 90 }, "span": { "type": "number", "minimum": 10, "maximum": 1000000 }, "target": { "type": "array", "minItems": 3, "maxItems": 3, "items": { "type": "number", "minimum": -300000, "maximum": 300000 } } } }, "settings": { "type": "object", "additionalProperties": false, "required": [ "width", "height", "samples", "seed", "lightAzimuth", "lightElevation", "softness", "ambient", "exposure", "background", "ground", "transparent" ], "properties": { "width": { "type": "integer", "minimum": 32, "maximum": 800 }, "height": { "type": "integer", "minimum": 32, "maximum": 800 }, "samples": { "type": "integer", "minimum": 1, "maximum": 32 }, "seed": { "type": "integer", "minimum": 0, "maximum": 4294967295 }, "lightAzimuth": { "type": "number", "minimum": -360, "maximum": 360 }, "lightElevation": { "type": "number", "minimum": 5, "maximum": 90 }, "softness": { "type": "number", "minimum": 0, "maximum": 0.6 }, "ambient": { "type": "number", "minimum": 0, "maximum": 1 }, "exposure": { "type": "number", "minimum": -4, "maximum": 4 }, "background": { "type": "string", "pattern": "^#[a-fA-F0-9]{6}$" }, "ground": { "type": "boolean" }, "transparent": { "type": "boolean" } }, "description": "At most 384000 pixels and 6 million pixel samples." }, "materials": { "type": "object", "maxProperties": 128, "additionalProperties": { "enum": [ "matte", "satin", "metal" ] }, "description": "Keys reference source solid IDs. At most 4096 visible triangles." } } }, "plan": { "type": "object" }, "pass": { "enum": [ "beauty", "albedo", "normal", "depth", "shadow", "object" ] }, "preview": { "type": "object", "additionalProperties": false, "required": [ "artifactId", "filename", "mime", "bytes", "sha256", "path" ], "properties": { "artifactId": { "type": "string" }, "filename": { "type": "string" }, "mime": { "type": "string" }, "bytes": { "type": "integer" }, "sha256": { "type": "string" }, "path": { "type": "string", "description": "Download path on the same site (valid for about 2 hours)." } } }, "recipeFile": { "type": "object", "additionalProperties": false, "required": [ "artifactId", "filename", "mime", "bytes", "sha256", "path" ], "properties": { "artifactId": { "type": "string" }, "filename": { "type": "string" }, "mime": { "type": "string" }, "bytes": { "type": "integer" }, "sha256": { "type": "string" }, "path": { "type": "string", "description": "Download path on the same site (valid for about 2 hours)." } } }, "openInApp": { "type": [ "string", "null" ] } } }, "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" } } } } } } } }