{ "openapi": "3.1.1", "info": { "title": "Height Grid to Material Maps API", "version": "1.0.0", "summary": "Turn numeric height samples into normal, roughness, cavity and ORM maps.", "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://renderloomheightmaterial.usefulweb.app" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Turn numeric height samples into normal, roughness, cavity and ORM maps.", "description": "Author a rectangular height field from 0–1 samples, interpolate it into a texture, and generate seven PNG maps with explicit normal convention and editable roughness, cavity and metallic settings. Download a map ZIP and exact Renderloom material project.\n\nMethodology:\n- The grid has 2–64 equal-width rows and columns of 0–1 values. Bilinear interpolation creates a square RGBA8 source at 16–512 px. All computations and PNG exports are deterministic.\n- Tangent normals normalize (−dx × strength, +dy × strength, 1), using central differences and periodic neighbors. Image Y points down; default output is +Y tangent space. Green may be flipped for a −Y convention. Normal maps are data textures.\n- Roughness = clamp(base + (0.5 − height) × variation). Cavity = clamp(1 − max(0, periodic neighborhood mean − height) × strength × 4). This is a short-range cavity approximation, not ray-traced occlusion. Metallic is a uniform manually chosen value. ORM packs cavity in R, roughness in G and metallic in B.\n- Optional symmetric edge feathering averages opposite edges in a blend band. It removes boundary color jumps, but does not guarantee matching derivatives or hide repeated motifs. Review all maps in the target application.\n\nRoughness and cavity are authored heuristics. Metallic is a manual uniform value. This does not recover measured physical materials or create a glTF model.", "tags": [ "apps" ], "x-mcp-tool": "renderloom_height_material", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderloomHeightMaterialInput" }, "examples": { "example1": { "summary": "A raised rounded tile", "value": {} }, "example2": { "summary": "A matte diagonal ramp with green flipped", "value": { "grid": "0, 0.5, 1\n0, 0.5, 1\n0, 0.5, 1", "flipGreen": true, "roughness": 0.85, "normalStrength": 12, "seamBlend": 0.1 } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderloomHeightMaterialResult" } } } }, "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" } } } } } }, "RenderloomHeightMaterialInput": { "type": "object", "additionalProperties": false, "properties": { "grid": { "title": "Height grid (0–1, rows separated by newlines)", "type": "string", "maxLength": 24000, "default": "0.15, 0.3, 0.5, 0.3, 0.15\n0.3, 0.65, 0.85, 0.65, 0.3\n0.5, 0.85, 1, 0.85, 0.5\n0.3, 0.65, 0.85, 0.65, 0.3\n0.15, 0.3, 0.5, 0.3, 0.15" }, "size": { "title": "Square map size (px)", "type": "integer", "minimum": 16, "maximum": 512, "default": 128 }, "normalStrength": { "title": "Normal strength", "type": "number", "minimum": 0, "maximum": 20, "default": 8 }, "flipGreen": { "title": "Flip normal green channel", "type": "boolean", "default": false }, "roughness": { "title": "Base roughness", "type": "number", "minimum": 0, "maximum": 1, "default": 0.65 }, "variation": { "title": "Height-driven roughness variation", "type": "number", "minimum": 0, "maximum": 1, "default": 0.2 }, "cavityStrength": { "title": "Cavity strength", "type": "number", "minimum": 0, "maximum": 2, "default": 0.65 }, "cavityRadius": { "title": "Cavity neighborhood radius (px)", "type": "integer", "minimum": 1, "maximum": 16, "default": 5 }, "metalness": { "title": "Uniform metallic value", "type": "number", "minimum": 0, "maximum": 1, "default": 0 }, "seamBlend": { "title": "Edge feather fraction", "type": "number", "minimum": 0, "maximum": 0.25, "default": 0 } }, "required": [] }, "RenderloomHeightMaterialResult": { "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": [ "project", "diagnostics", "maps", "archive", "projectFile", "openInApp" ], "properties": { "project": { "type": "object", "additionalProperties": false, "required": [ "format", "version", "name", "source", "settings" ], "properties": { "format": { "const": "renderloom-material" }, "version": { "const": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "source": { "type": "object", "additionalProperties": false, "required": [ "width", "height", "png" ], "properties": { "width": { "type": "integer", "minimum": 2, "maximum": 1024 }, "height": { "type": "integer", "minimum": 2, "maximum": 1024 }, "png": { "type": "string", "maxLength": 6000000, "pattern": "^data:image/png;base64," } } }, "settings": { "type": "object", "additionalProperties": false, "required": [ "heightChannel", "heightInvert", "levelLow", "levelHigh", "heightGamma", "blur", "normalStrength", "flipGreen", "roughness", "roughnessVariation", "aoStrength", "aoRadius", "metalness", "seamBlend" ], "properties": { "heightChannel": { "enum": [ "luminance", "red", "green", "blue", "alpha" ] }, "heightInvert": { "type": "boolean" }, "levelLow": { "type": "number", "minimum": 0, "maximum": 0.99 }, "levelHigh": { "type": "number", "minimum": 0.01, "maximum": 1 }, "heightGamma": { "type": "number", "minimum": 0.2, "maximum": 4 }, "blur": { "type": "integer", "minimum": 0, "maximum": 8 }, "normalStrength": { "type": "number", "minimum": 0, "maximum": 20 }, "flipGreen": { "type": "boolean" }, "roughness": { "type": "number", "minimum": 0, "maximum": 1 }, "roughnessVariation": { "type": "number", "minimum": 0, "maximum": 1 }, "aoStrength": { "type": "number", "minimum": 0, "maximum": 2 }, "aoRadius": { "type": "integer", "minimum": 1, "maximum": 16 }, "metalness": { "type": "number", "minimum": 0, "maximum": 1 }, "seamBlend": { "type": "number", "minimum": 0, "maximum": 0.25 } } }, "packChannels": { "type": "array", "minItems": 4, "maxItems": 4, "items": { "enum": [ "ao", "roughness", "metallic", "height", "inv-ao", "inv-roughness", "inv-metallic", "inv-height", "black", "white" ] } } } }, "diagnostics": { "type": "object", "additionalProperties": false, "required": [ "heightMin", "heightMax", "heightMean", "flatHeight", "clippedPixels", "transparentPixels", "edgeBefore", "edgeAfter", "normalConvention", "warnings" ], "properties": { "heightMin": { "type": "number" }, "heightMax": { "type": "number" }, "heightMean": { "type": "number" }, "flatHeight": { "type": "boolean" }, "clippedPixels": { "type": "integer" }, "transparentPixels": { "type": "integer" }, "edgeBefore": { "type": "number" }, "edgeAfter": { "type": "number" }, "normalConvention": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "maps": { "type": "object", "additionalProperties": false, "required": [ "baseColor", "height", "normal", "roughness", "ao", "metallic", "orm" ], "properties": { "baseColor": { "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)." } } }, "height": { "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)." } } }, "normal": { "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)." } } }, "roughness": { "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)." } } }, "ao": { "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)." } } }, "metallic": { "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)." } } }, "orm": { "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)." } } } } }, "archive": { "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)." } } }, "projectFile": { "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" } } } } } } } }