runmat 0.4.10-dev.6 → 0.4.10-dev.8

package/dist/generated/builtins/print.d.ts

@@ -0,0 +1,4 @@
+import type { BuiltinDoc } from "../../builtins.js";
+declare const builtinDoc: BuiltinDoc;
+export default builtinDoc;
+//# sourceMappingURL=print.d.ts.map

package/dist/generated/builtins/print.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"print.d.ts","sourceRoot":"","sources":["../../../src/generated/builtins/print.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,QAAA,MAAM,UAAU,EAAE,UA2GjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/generated/builtins/print.js

@@ -0,0 +1,112 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "print",
+    "category": "plotting",
+    "keywords": [
+        "print",
+        "figure export",
+        "png",
+        "plotting",
+        "save figure"
+    ],
+    "summary": "Export the active or specified figure to a PNG file.",
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "`print` is a figure export sink. It gathers filename and option arguments when needed, then serializes the figure through the plotting renderer. Existing GPU-backed plot geometry can still use the shared WGPU plotting path during export."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 4,
+        "constants": "inline"
+    },
+    "requires_feature": "plot-core",
+    "tested": {
+        "unit": "builtins::plotting::print::tests",
+        "integration": "direct headless Chrome WASM verification of print.json examples"
+    },
+    "description": "`print` exports a figure to a file. RunMat currently supports PNG output with MATLAB-style device and resolution tokens, including `print('name', '-dpng')`, `print('name', '-dpng', '-r300')`, and `print(fig, 'name', '-dpng')`. In browser and WASM hosts the file is written through RunMat's virtual filesystem provider so the host can persist or download it.",
+    "behaviors": [
+        "`print(filename, '-dpng')` writes PNG bytes to `filename`. If the name has no `.png` extension, RunMat appends one.",
+        "`print(filename, '-dpng', '-rN')` scales the export dimensions from the default 800 by 600 canvas using `N` DPI relative to RunMat's 150 DPI default.",
+        "`print(fig, filename, '-dpng')` exports the specified figure handle instead of the active figure.",
+        "Command-style argument order is accepted when RunMat parses command calls into string arguments, such as `print -dpng plot.png`.",
+        "PDF, EPS, and SVG device tokens are recognized but return a clear unsupported-device error until those exporters are implemented."
+    ],
+    "examples": [
+        {
+            "description": "Export the active figure to a PNG file",
+            "input": "x = 0:0.1:2*pi;\nplot(x, sin(x));\nprint(\"sine_plot\", \"-dpng\");"
+        },
+        {
+            "description": "Export at a higher resolution",
+            "input": "x = 0:0.1:1;\nplot(x, x.^2, \"LineWidth\", 2);\nprint(\"quadratic_plot\", \"-dpng\", \"-r300\");"
+        },
+        {
+            "description": "Export a specific figure handle",
+            "input": "fig = figure();\nplot(1:5, [1 4 2 5 3]);\nprint(fig, \"explicit_handle_plot.png\", \"-dpng\");"
+        },
+        {
+            "description": "Command-style device order",
+            "input": "plot(1:4, [1 3 2 4]);\nprint -dpng command_style_plot.png"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Which formats does `print` support?",
+            "answer": "PNG is supported today with `-dpng`. RunMat recognizes PDF, EPS, and SVG device tokens, but they return an unsupported-device error until those exporters are available in the rendering stack."
+        },
+        {
+            "question": "Where does the file go in the browser?",
+            "answer": "The PNG is written through RunMat's filesystem provider. In the sandbox this is usually the in-memory or IndexedDB-backed virtual filesystem, and the host can expose the file as a download artifact."
+        },
+        {
+            "question": "Does `-r300` change the figure data?",
+            "answer": "No. It only changes the pixel dimensions used for export. The plot data and graphics handles remain unchanged."
+        }
+    ],
+    "links": [
+        {
+            "label": "figure",
+            "url": "./figure"
+        },
+        {
+            "label": "gcf",
+            "url": "./gcf"
+        },
+        {
+            "label": "plot",
+            "url": "./plot"
+        },
+        {
+            "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/print.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/plotting/ops/print.rs"
+    },
+    "gpu_residency": "`print` is an I/O sink and returns a host logical status. Filename and option arguments are gathered before parsing. GPU-resident plot data already captured in figure state may still be consumed by the plotting renderer without forcing user-visible gathers when the shared WGPU export path is available.",
+    "gpu_behavior": [
+        "No numeric GPU kernels are launched for `print` itself.",
+        "The PNG exporter first attempts the interactive GPU render path and falls back to CPU rasterization when headless GPU initialization is unavailable.",
+        "The builtin writes PNG bytes through RunMat's filesystem layer, so output storage is host or virtual-filesystem backed."
+    ],
+    "key": "print",
+    "slug": "print",
+    "aliases": [],
+    "categoryPath": [
+        "plotting"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=print.js.map

package/dist/generated/builtins/print.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"print.js","sourceRoot":"","sources":["../../../src/generated/builtins/print.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,OAAO;IAChB,UAAU,EAAE,UAAU;IACtB,UAAU,EAAE;QACV,OAAO;QACP,eAAe;QACf,KAAK;QACL,UAAU;QACV,aAAa;KACd;IACD,SAAS,EAAE,sDAAsD;IACjE,aAAa,EAAE;QACb,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,EAAE;QAChB,cAAc,EAAE,MAAM;QACtB,OAAO,EAAE,+OAA+O;KACzP;IACD,QAAQ,EAAE;QACR,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,CAAC;QACf,WAAW,EAAE,QAAQ;KACtB;IACD,kBAAkB,EAAE,WAAW;IAC/B,QAAQ,EAAE;QACR,MAAM,EAAE,kCAAkC;QAC1C,aAAa,EAAE,iEAAiE;KACjF;IACD,aAAa,EAAE,uWAAuW;IACtX,WAAW,EAAE;QACX,qHAAqH;QACrH,uJAAuJ;QACvJ,mGAAmG;QACnG,kIAAkI;QAClI,mIAAmI;KACpI;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,wCAAwC;YACvD,OAAO,EAAE,qEAAqE;SAC/E;QACD;YACE,aAAa,EAAE,+BAA+B;YAC9C,OAAO,EAAE,kGAAkG;SAC5G;QACD;YACE,aAAa,EAAE,iCAAiC;YAChD,OAAO,EAAE,gGAAgG;SAC1G;QACD;YACE,aAAa,EAAE,4BAA4B;YAC3C,OAAO,EAAE,2DAA2D;SACrE;KACF;IACD,MAAM,EAAE;QACN;YACE,UAAU,EAAE,qCAAqC;YACjD,QAAQ,EAAE,iMAAiM;SAC5M;QACD;YACE,UAAU,EAAE,wCAAwC;YACpD,QAAQ,EAAE,wMAAwM;SACnN;QACD;YACE,UAAU,EAAE,sCAAsC;YAClD,QAAQ,EAAE,gHAAgH;SAC3H;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,UAAU;SAClB;QACD;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;QACD;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,wBAAwB;YACjC,KAAK,EAAE,uCAAuC;SAC/C;QACD;YACE,OAAO,EAAE,yBAAyB;YAClC,KAAK,EAAE,6BAA6B;SACrC;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,4DAA4D;QACrE,KAAK,EAAE,yGAAyG;KACjH;IACD,eAAe,EAAE,iTAAiT;IAClU,cAAc,EAAE;QACd,yDAAyD;QACzD,sJAAsJ;QACtJ,yHAAyH;KAC1H;IACD,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,OAAO;IACf,SAAS,EAAE,EAAE;IACb,cAAc,EAAE;QACd,UAAU;KACX;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/generated/builtins/scatterplot.d.ts

@@ -0,0 +1,4 @@
+import type { BuiltinDoc } from "../../builtins.js";
+declare const builtinDoc: BuiltinDoc;
+export default builtinDoc;
+//# sourceMappingURL=scatterplot.d.ts.map

package/dist/generated/builtins/scatterplot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scatterplot.d.ts","sourceRoot":"","sources":["../../../src/generated/builtins/scatterplot.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,QAAA,MAAM,UAAU,EAAE,UA8GjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/generated/builtins/scatterplot.js

@@ -0,0 +1,115 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "scatterplot",
+    "category": "communications/plotting",
+    "keywords": [
+        "scatterplot",
+        "constellation diagram",
+        "communications toolbox",
+        "complex baseband",
+        "qam",
+        "psk",
+        "scatter"
+    ],
+    "summary": "Plot complex-baseband samples as a 2-D constellation diagram.",
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "single",
+            "double"
+        ],
+        "broadcasting": "none",
+        "notes": "`scatterplot` is a rendering sink. When GPU-resident samples can be split into real and imaginary buffers without decimation, RunMat forwards those buffers to the existing GPU scatter renderer. Decimated or unsupported inputs gather once and render through the same scatter semantics."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::plotting::scatterplot::tests",
+        "integration": "scatter GPU/rendering coverage is inherited from builtins::plotting::scatter and runmat-plot renderer tests"
+    },
+    "description": "`scatterplot` visualizes complex-baseband samples by plotting `real(x)` on the x-axis and `imag(x)` on the y-axis. It mirrors the MATLAB Communications Toolbox call forms for decimation, offset, marker styling, and target axes while using RunMat's shared `scatter` renderer and graphics-handle model.",
+    "behaviors": [
+        "`scatterplot(x)` plots every complex sample using a constellation-friendly default marker.",
+        "`scatterplot(x, n)` plots every `n`-th sample.",
+        "`scatterplot(x, n, offset)` starts at the zero-based offset before applying decimation, matching MATLAB's `x(offset+1:n:end)` behavior.",
+        "`scatterplot(x, n, offset, marker)` forwards the marker LineSpec to `scatter`.",
+        "`scatterplot(x, n, offset, marker, ax)` targets an existing axes handle.",
+        "The generated plot uses equal x/y scaling and grid lines so constellation geometry is not visually distorted."
+    ],
+    "examples": [
+        {
+            "description": "Plot a simple QPSK constellation",
+            "input": "x = [1+1i; -1+1i; -1-1i; 1-1i];\nscatterplot(x);"
+        },
+        {
+            "description": "Plot every fourth received sample with a custom marker",
+            "input": "rx = randn(1000, 1) + 1i*randn(1000, 1);\nscatterplot(rx, 4, 0, 'gx');"
+        },
+        {
+            "description": "Target a subplot axes",
+            "input": "ax = subplot(1, 2, 1);\nx = [1+1i; 1-1i; -1+1i; -1-1i];\nscatterplot(x, 1, 0, 'b.', ax);"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "How is scatterplot different from scatter?",
+            "answer": "`scatterplot` is specialized for complex symbols. It derives x/y coordinates from the real and imaginary parts of one input vector, applies Communications Toolbox decimation/offset arguments, and configures the axes for constellation viewing. `scatter` expects explicit x and y coordinate arrays."
+        },
+        {
+            "question": "Does scatterplot support gpuArray inputs?",
+            "answer": "Yes. For the no-decimation case, RunMat asks the acceleration provider for real and imaginary GPU buffers and forwards them to the GPU scatter renderer. When decimation is requested or the provider cannot expose those buffers, RunMat gathers the samples once and renders the same visible plot."
+        }
+    ],
+    "links": [
+        {
+            "label": "scatter",
+            "url": "./scatter"
+        },
+        {
+            "label": "plot",
+            "url": "./plot"
+        },
+        {
+            "label": "real",
+            "url": "./real"
+        },
+        {
+            "label": "imag",
+            "url": "./imag"
+        },
+        {
+            "label": "Styling plots and axes",
+            "url": "/docs/plotting/styling-plots-and-axes"
+        },
+        {
+            "label": "GPU plotting and residency",
+            "url": "/docs/plotting/gpu-plotting-and-residency"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/plotting/ops/scatterplot.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/plotting/ops/scatterplot.rs"
+    },
+    "gpu_residency": "`scatterplot` preserves GPU residency for the common `scatterplot(x)` path when the active provider can materialize real and imaginary buffers on device. Decimation and provider gaps fall back to one host gather, after which the same `scatter` handle and axes behavior apply.",
+    "gpu_behavior": [
+        "The direct path reuses the existing 2-D scatter WGPU renderer and avoids an extra host round-trip for supported GPU inputs.",
+        "Decimated sample selection is currently performed on the host to preserve MATLAB-compatible offset semantics.",
+        "Marker styling, axes targeting, grid, and equal-axis behavior are consistent between GPU and host fallback rendering."
+    ],
+    "key": "scatterplot",
+    "slug": "scatterplot",
+    "aliases": [],
+    "categoryPath": [
+        "communications",
+        "plotting"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=scatterplot.js.map

package/dist/generated/builtins/scatterplot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scatterplot.js","sourceRoot":"","sources":["../../../src/generated/builtins/scatterplot.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,aAAa;IACtB,UAAU,EAAE,yBAAyB;IACrC,UAAU,EAAE;QACV,aAAa;QACb,uBAAuB;QACvB,wBAAwB;QACxB,kBAAkB;QAClB,KAAK;QACL,KAAK;QACL,SAAS;KACV;IACD,SAAS,EAAE,+DAA+D;IAC1E,aAAa,EAAE;QACb,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE;YACZ,QAAQ;YACR,QAAQ;SACT;QACD,cAAc,EAAE,MAAM;QACtB,OAAO,EAAE,8RAA8R;KACxS;IACD,QAAQ,EAAE;QACR,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,CAAC;QACf,WAAW,EAAE,QAAQ;KACtB;IACD,kBAAkB,EAAE,IAAI;IACxB,QAAQ,EAAE;QACR,MAAM,EAAE,wCAAwC;QAChD,aAAa,EAAE,6GAA6G;KAC7H;IACD,aAAa,EAAE,8SAA8S;IAC7T,WAAW,EAAE;QACX,4FAA4F;QAC5F,gDAAgD;QAChD,yIAAyI;QACzI,gFAAgF;QAChF,0EAA0E;QAC1E,+GAA+G;KAChH;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,kCAAkC;YACjD,OAAO,EAAE,kDAAkD;SAC5D;QACD;YACE,aAAa,EAAE,wDAAwD;YACvE,OAAO,EAAE,wEAAwE;SAClF;QACD;YACE,aAAa,EAAE,uBAAuB;YACtC,OAAO,EAAE,0FAA0F;SACpG;KACF;IACD,MAAM,EAAE;QACN;YACE,UAAU,EAAE,4CAA4C;YACxD,QAAQ,EAAE,0SAA0S;SACrT;QACD;YACE,UAAU,EAAE,2CAA2C;YACvD,QAAQ,EAAE,uSAAuS;SAClT;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,SAAS;YAClB,KAAK,EAAE,WAAW;SACnB;QACD;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,wBAAwB;YACjC,KAAK,EAAE,uCAAuC;SAC/C;QACD;YACE,OAAO,EAAE,4BAA4B;YACrC,KAAK,EAAE,2CAA2C;SACnD;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,kEAAkE;QAC3E,KAAK,EAAE,+GAA+G;KACvH;IACD,eAAe,EAAE,qRAAqR;IACtS,cAAc,EAAE;QACd,6HAA6H;QAC7H,+GAA+G;QAC/G,uHAAuH;KACxH;IACD,KAAK,EAAE,aAAa;IACpB,MAAM,EAAE,aAAa;IACrB,SAAS,EAAE,EAAE;IACb,cAAc,EAAE;QACd,gBAAgB;QAChB,UAAU;KACX;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/generated/builtins-manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builtins-manifest.d.ts","sourceRoot":"","sources":["../../src/generated/builtins-manifest.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE7E,eAAO,MAAM,eAAe,EAAE,oBAAoB,EA8yQjD,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAqa9D,CAAC;AAEF,eAAO,MAAM,4BAA4B,sEAC0C,CAAC"}
+{"version":3,"file":"builtins-manifest.d.ts","sourceRoot":"","sources":["../../src/generated/builtins-manifest.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE7E,eAAO,MAAM,eAAe,EAAE,oBAAoB,EAu1QjD,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAua9D,CAAC;AAEF,eAAO,MAAM,4BAA4B,sEAC0C,CAAC"}

package/dist/generated/builtins-manifest.js

@@ -5720,6 +5720,25 @@ export const builtinManifest = [
         "summary": "Evaluate a piecewise-polynomial structure.",
         "exampleCount": 1
     },
+    {
+        "key": "print",
+        "title": "print",
+        "slug": "print",
+        "aliases": [],
+        "category": "plotting",
+        "categoryPath": [
+            "plotting"
+        ],
+        "keywords": [
+            "print",
+            "figure export",
+            "png",
+            "plotting",
+            "save figure"
+        ],
+        "summary": "Export the active or specified figure to a PNG file.",
+        "exampleCount": 4
+    },
     {
         "key": "prod",
         "title": "prod",
@@ -6579,6 +6598,28 @@ export const builtinManifest = [
         "summary": "Create 3-D scatter plots for spatial point clouds, encoded markers, and MATLAB `scatter3` workflows.",
         "exampleCount": 4
     },
+    {
+        "key": "scatterplot",
+        "title": "scatterplot",
+        "slug": "scatterplot",
+        "aliases": [],
+        "category": "communications/plotting",
+        "categoryPath": [
+            "communications",
+            "plotting"
+        ],
+        "keywords": [
+            "scatterplot",
+            "constellation diagram",
+            "communications toolbox",
+            "complex baseband",
+            "qam",
+            "psk",
+            "scatter"
+        ],
+        "summary": "Plot complex-baseband samples as a 2-D constellation diagram.",
+        "exampleCount": 3
+    },
     {
         "key": "second",
         "title": "second",
@@ -8778,6 +8819,7 @@ export const builtinDocLoaders = {
     "pow2": () => import("./builtins/pow2.js").then((mod) => mod.default),
     "power": () => import("./builtins/power.js").then((mod) => mod.default),
     "ppval": () => import("./builtins/ppval.js").then((mod) => mod.default),
+    "print": () => import("./builtins/print.js").then((mod) => mod.default),
     "prod": () => import("./builtins/prod.js").then((mod) => mod.default),
     "pwd": () => import("./builtins/pwd.js").then((mod) => mod.default),
     "qammod": () => import("./builtins/qammod.js").then((mod) => mod.default),
@@ -8820,6 +8862,7 @@ export const builtinDocLoaders = {
     "sawtooth": () => import("./builtins/sawtooth.js").then((mod) => mod.default),
     "scatter": () => import("./builtins/scatter.js").then((mod) => mod.default),
     "scatter3": () => import("./builtins/scatter3.js").then((mod) => mod.default),
+    "scatterplot": () => import("./builtins/scatterplot.js").then((mod) => mod.default),
     "second": () => import("./builtins/second.js").then((mod) => mod.default),
     "semilogx": () => import("./builtins/semilogx.js").then((mod) => mod.default),
     "semilogy": () => import("./builtins/semilogy.js").then((mod) => mod.default),