{
"title": "fill3",
"category": "plotting",
"keywords": [
"fill3",
"3-D filled polygon",
"patch",
"polygon",
"matlab fill3",
"3d patch"
],
"summary": "Create MATLAB-compatible filled polygon patches in 3-D space.",
"gpu_support": {
"elementwise": false,
"reduction": false,
"precisions": [
"single",
"double"
],
"broadcasting": "none",
"notes": "`fill3` is a plotting sink. It lowers coordinate and color argument groups to `patch` objects, gathering GPU-resident coordinate inputs through the shared patch path."
},
"fusion": {
"elementwise": false,
"reduction": false,
"max_inputs": 4,
"constants": "inline"
},
"requires_feature": null,
"tested": {
"unit": "builtins::plotting::fill3::tests"
},
"description": "`fill3` creates filled polygon graphics objects from X, Y, and Z coordinate data. RunMat implements it as a thin wrapper over the shared `patch` machinery, so returned handles are patch graphics handles and common patch name-value properties apply.",
"behaviors": [
"`fill3(X, Y, Z, C)` creates one or more 3-D filled polygons from matching coordinate arrays.",
"Vector coordinate inputs create one polygon.",
"Matrix coordinate inputs create one polygon per column through the underlying `patch` parser.",
"Multiple `X,Y,Z,C` groups in one call create multiple patch objects and return a row vector of patch handles.",
"A single polygon group returns a scalar patch handle.",
"`fill3` initializes the target axes with the standard 3-D view, so even polygons in the z=0 plane render as 3-D patch content.",
"Trailing patch property name-value pairs are applied to every polygon group in the call.",
"The returned patch handles work with `get`, `set`, `ishandle`, and `isgraphics`.",
"Color strings and RGB triples are supported through the shared patch color parser.",
"Indexed or interpolated CData behavior is currently limited by the underlying `patch` implementation; concrete color strings, RGB triples, and common patch properties are the supported color path."
],
"options": [
"`FaceColor` accepts color names, RGB triples, `flat`, or `none` through `patch`.",
"`EdgeColor` accepts color names, RGB triples, or `none`.",
"`FaceAlpha` and `EdgeAlpha` accept numeric values from 0 to 1.",
"`LineWidth`, `DisplayName`, and `Visible` use the shared plotting property model.",
"Explicit axes handles are accepted as the leading argument, matching other RunMat plotting builtins."
],
"examples": [
{
"description": "Create a red square in the z=0 plane",
"input": "x = [0 1 1 0];\ny = [0 0 1 1];\nz = [0 0 0 0];\nh = fill3(x, y, z, 'r');\nget(h, 'Type')",
"output": "ans =\n 'patch'"
},
{
"description": "Create two filled polygons in one call",
"input": "x1 = [0 1 0];\ny1 = [0 0 1];\nz1 = [0 0 0];\nx2 = [2 3 3 2];\ny2 = [0 0 1 1];\nz2 = [1 1 1 1];\nh = fill3(x1, y1, z1, 'g', x2, y2, z2, [0 0 1]);"
},
{
"description": "Apply patch properties to a fill3 polygon",
"input": "x = [0 1 0];\ny = [0 0 1];\nz = [0.25 0.5 0.75];\nh = fill3(x, y, z, [0.25 0.5 0.75], 'EdgeColor', 'none', 'FaceAlpha', 0.5);"
},
{
"description": "Create one patch per matrix column",
"input": "X = [0 2; 1 3; 1 3; 0 2];\nY = [0 0; 0 0; 1 1; 1 1];\nZ = [0 1; 0 1; 0 1; 0 1];\nfill3(X, Y, Z, 'cyan');\nview(3);"
}
],
"faqs": [
{
"question": "What does fill3 return?",
"answer": "`fill3` returns patch graphics handles. A single polygon group returns one scalar handle; multiple groups return a row vector of handles."
},
{
"question": "How is fill3 related to patch?",
"answer": "`fill3` lowers its positional `X,Y,Z,C` inputs into the same `patch` object machinery. This keeps geometry validation, color parsing, property handling, rendering, and handle behavior consistent with `patch`."
},
{
"question": "Can I pass patch properties to fill3?",
"answer": "Yes. Trailing name-value pairs such as `'EdgeColor', 'none'`, `'FaceAlpha', 0.5`, and `'LineWidth', 2` are forwarded to the patch objects created by `fill3`."
},
{
"question": "Does fill3 support GPU-resident inputs?",
"answer": "GPU-resident coordinate inputs are gathered through the shared patch path for validation and polygon construction, then the resulting geometry is rendered through RunMat's GPU plotting renderer."
},
{
"question": "Does fill3 support indexed CData?",
"answer": "The current implementation is constrained by `patch`: color strings and RGB triples are supported, while full MATLAB indexed/interpolated CData behavior is deferred."
}
],
"links": [
{
"label": "patch",
"url": "./patch"
},
{
"label": "plot3",
"url": "./plot3"
},
{
"label": "scatter3",
"url": "./scatter3"
},
{
"label": "surf",
"url": "./surf"
},
{
"label": "view",
"url": "./view"
},
{
"label": "get",
"url": "./get"
},
{
"label": "set",
"url": "./set"
},
{
"label": "Graphics Handles",
"url": "/docs/plotting/graphics-handles"
},
{
"label": "Plot replay and export",
"url": "/docs/plotting/plot-replay-and-export"
}
],
"source": {
"label": "`crates/runmat-runtime/src/builtins/plotting/ops/fill3.rs`",
"url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/plotting/ops/fill3.rs"
},
"gpu_residency": "`fill3` is a plotting sink and fusion barrier. GPU-resident coordinate inputs are gathered before patch construction because MATLAB-compatible parsing requires shape validation and polygon assembly.",
"gpu_behavior": [
"`fill3` shares patch rendering behavior, so host and gathered-GPU coordinate inputs produce the same patch objects and graphics handles.",
"Rendered geometry flows through the shared GPU plotting renderer after the patch objects are built.",
"A future direct GPU path should preserve the same `X,Y,Z,C` grouping and patch property semantics while replacing only the coordinate gathering and geometry packing stage."
]
}