{ "openapi": "3.1.1", "info": { "title": "Color Region Cutout & Mask API", "version": "1.0.0", "summary": "Select a matching color region and export a transparent cutout and feathered mask.", "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://luminacolorregion.usefulweb.app" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Select a matching color region and export a transparent cutout and feathered mask.", "description": "Click by percentage coordinates to select similar colors. Choose contiguous four-connected pixels or every matching pixel, tune tolerance, invert the selection and feather its boundary. Download a PNG cutout or erased region plus a grayscale mask. This file tool uploads to the server; Lumina Selection Lab performs the same selection locally.\n\nMethodology:\n- Auto-orient and convert the first frame to 8-bit sRGB. Reject inputs over 16 MP and reduce the longest side to at most 1024 pixels without enlargement. Output dimensions are this working size; metadata is stripped.\n- A pixel matches when the largest absolute difference of premultiplied encoded-sRGB R, G, B or alpha from the seed is at most tolerance. Every candidate is compared with the original seed, never a running neighbor color. Hidden RGB at zero alpha does not affect matching.\n- Contiguous mode uses four-connected flood fill. Global mode tests every pixel. Inversion happens before feathering; counts and bounds describe the hard binary selection. Coordinates of 100% address the final pixel.\n- Feather is one separable box blur with edge-normalized support. It extends inward and outward. The resulting coverage multiplies original alpha for cutout, or its complement for erase. The grayscale PNG mask stores coverage as opaque gray. This is color matching, not subject recognition.", "tags": [ "apps" ], "x-mcp-tool": "lumina_color_region", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LuminaColorRegionInput" }, "examples": { "example1": { "summary": "Keep the red image region", "value": { "image": { "filename": "red.png", "contentType": "image/png", "contentBase64": "iVBORw0KGgoAAAANSUhEUgAAACAAAAAgAQMAAABJtOi3AAAABlBMVEX/////AADrWueTAAAAEklEQVQI12NgIBb8/09dgjgAAPcnH+GApkH4AAAAAElFTkSuQmCC" }, "x": 50, "y": 50, "tolerance": 0, "feather": 0 } }, "example2": { "summary": "Erase the matching region", "value": { "image": { "filename": "red.png", "contentType": "image/png", "contentBase64": "iVBORw0KGgoAAAANSUhEUgAAACAAAAAgAQMAAABJtOi3AAAABlBMVEX/////AADrWueTAAAAEklEQVQI12NgIBb8/09dgjgAAPcnH+GApkH4AAAAAElFTkSuQmCC" }, "operation": "erase" } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LuminaColorRegionResult" } } } }, "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" } } } } } }, "LuminaColorRegionInput": { "type": "object", "additionalProperties": false, "properties": { "image": { "title": "Image (PNG, JPEG, WebP or GIF; up to 8 MB and 16 MP)", "type": "object", "description": "Upload as {filename, contentType?, contentBase64}. Max 7813 KiB. Accepts .png,.jpg,.jpeg,.webp,.gif.", "additionalProperties": false, "required": [ "filename", "contentBase64" ], "properties": { "filename": { "type": "string" }, "contentType": { "type": "string" }, "contentBase64": { "type": "string" } } }, "x": { "title": "Seed X (%)", "type": "number", "minimum": 0, "maximum": 100, "default": 50 }, "y": { "title": "Seed Y (%)", "type": "number", "minimum": 0, "maximum": 100, "default": 50 }, "tolerance": { "title": "Color tolerance (0–255)", "type": "integer", "minimum": 0, "maximum": 255, "default": 24 }, "connected": { "title": "Contiguous pixels only", "type": "boolean", "default": true }, "invert": { "title": "Invert selection", "type": "boolean", "default": false }, "feather": { "title": "Feather radius (working pixels)", "type": "integer", "minimum": 0, "maximum": 24, "default": 0 }, "operation": { "title": "Result", "type": "string", "enum": [ "cutout", "erase" ], "default": "cutout" } }, "required": [ "image" ] }, "LuminaColorRegionResult": { "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": [ "width", "height", "selected", "percent", "bounds", "artifact", "maskArtifact" ], "properties": { "width": { "type": "integer" }, "height": { "type": "integer" }, "selected": { "type": "integer" }, "percent": { "type": "number" }, "bounds": { "anyOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "x", "y", "width", "height" ], "properties": { "x": { "type": "integer" }, "y": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" } } } ] }, "artifact": { "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)." } } }, "maskArtifact": { "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)." } } } } }, "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" } } } } } } } }