{
"title": "plot3",
"category": "plotting",
"keywords": [
"plot3",
"3-D line plot",
"trajectory plot",
"parametric curve",
"matlab plot3",
"spatial path"
],
"summary": "Create 3-D line plots for trajectories, parametric curves, and spatial paths with MATLAB `plot3` semantics.",
"gpu_support": {
"elementwise": false,
"reduction": false,
"precisions": [
"single",
"double"
],
"broadcasting": "none",
"notes": "`plot3` uses the dedicated 3-D line rendering path and can keep plotting-compatible GPU inputs resident on device."
},
"fusion": {
"elementwise": false,
"reduction": false,
"max_inputs": 3,
"constants": "inline"
},
"requires_feature": null,
"tested": {
"unit": "builtins::plotting::plot3::tests"
},
"description": "`plot3` creates line plots in 3-D space from matching x, y, and z inputs. In RunMat it returns a line3 handle, participates in the graphics-object system, and supports both host and GPU-backed inputs through the dedicated 3-D line pipeline.",
"behaviors": [
"`plot3(x, y, z)` requires matching element counts in all three inputs.",
"The builtin returns a 3-D line handle that can be inspected and updated through `get` and `set`.",
"Multiple 3-D series in one call create multiple line objects and return the handle for the first created series.",
"`plot3` is camera-aware and naturally pairs with `view` and `zlabel` in the subplot-local 3-D state model.",
"GPU-backed 3-D line rendering is used when the shared plotting device can consume exported buffers directly."
],
"examples": [
{
"description": "Create a 3-D helix",
"input": "t = linspace(0, 6*pi, 300);\nplot3(cos(t), sin(t), t);"
},
{
"description": "Plot multiple 3-D trajectories and label them",
"input": "t = linspace(0, 4*pi, 200);\nh1 = plot3(cos(t), sin(t), t);\nset(h1, 'DisplayName', 'helix A');\nhold on;\nh2 = plot3(cos(t), sin(t), -t);\nset(h2, 'DisplayName', 'helix B');\nlegend;"
},
{
"description": "Control the camera and z-axis after plotting",
"input": "t = linspace(0, 4*pi, 150);\nh = plot3(cos(t), sin(t), t);\nzlabel('Height');\nview(45, 20);\nget(h, 'Type')",
"output": "ans =\n 'line'"
}
],
"faqs": [
{
"question": "How do I plot a 3-D trajectory from parametric equations?",
"answer": "Generate a parameter vector `t`, compute x(t), y(t), z(t), and pass all three to `plot3`. The line connects points in parameter order.\n\n```matlab\nt = linspace(0, 10*pi, 500);\nplot3(sin(t), cos(t), t);\nzlabel('z');\n```"
},
{
"question": "Can I overlay plot3 lines with scatter3 points?",
"answer": "Yes — use `hold on` between calls. Both `plot3` and `scatter3` share the same 3-D axes and camera state, so they compose directly.\n\n```matlab\nt = linspace(0, 4*pi, 200);\nplot3(cos(t), sin(t), t);\nhold on;\nscatter3(cos(t(1:20:end)), sin(t(1:20:end)), t(1:20:end));\n```"
},
{
"question": "How do I control the camera angle on a plot3 figure?",
"answer": "Call `view(az, el)` after plotting. `az` is the azimuth (horizontal rotation) and `el` is the elevation (vertical tilt), both in degrees. `view(3)` gives the default 3-D perspective. Camera state is subplot-local, so each subplot can have its own angle."
}
],
"links": [
{
"label": "scatter3",
"url": "./scatter3"
},
{
"label": "view",
"url": "./view"
},
{
"label": "zlabel",
"url": "./zlabel"
},
{
"label": "legend",
"url": "./legend"
},
{
"label": "Choosing the right plot type",
"url": "/docs/plotting/choosing-the-right-plot-type"
},
{
"label": "Styling plots and axes",
"url": "/docs/plotting/styling-plots-and-axes"
},
{
"label": "Plot replay and export",
"url": "/docs/plotting/plot-replay-and-export"
},
{
"label": "Complete plotting guide",
"url": "/blog/matlab-plotting-guide"
}
],
"source": {
"label": "`crates/runmat-runtime/src/builtins/plotting/ops/plot3.rs`",
"url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/plotting/ops/plot3.rs"
},
"gpu_residency": "`plot3` preserves GPU residency when the 3-D line pipeline can consume exported coordinate buffers directly. Fallback rendering gathers once while preserving the same handle and axes semantics.",
"gpu_behavior": [
"The dedicated 3-D line pipeline is separate from 2-D `plot`, which keeps camera-aware rendering and bounds handling explicit.",
"Subview state, labels, and line object behavior remain identical across GPU and host fallback paths."
]
}