runmat 0.3.5 → 0.4.0

package/dist/generated/builtins/fread.js

@@ -0,0 +1,164 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "fread",
+    "category": "io/filetext",
+    "keywords": [
+        "fread",
+        "binary read",
+        "io",
+        "precision",
+        "machine format",
+        "skip"
+    ],
+    "summary": "Read binary data from a file identifier with MATLAB-compatible size, precision, skip, and machine-format semantics.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/fread.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Runs entirely on the host CPU. When arguments reside on the GPU, RunMat gathers them first; providers do not implement hooks for fread."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 4,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::filetext::fread::tests",
+        "integration": [
+            "builtins::io::filetext::fread::tests::fread_big_endian_machine_format",
+            "builtins::io::filetext::fread::tests::fread_like_gpu_provider_roundtrip"
+        ]
+    },
+    "description": "`fread` reads binary data from a file identifier returned by `fopen`. It mirrors MATLAB's handling of size, precision, skip, and machine-format arguments so existing MATLAB code can be ported without changes. The builtin tracks the file position, honours the machine format recorded by `fopen`, and returns both the data array and the number of elements successfully read.",
+    "behaviors": [
+        "`A = fread(fid)` reads to the end of the file, returning a column vector of doubles.",
+        "`A = fread(fid, sizeA)` reads at most `prod(sizeA)` elements, filling the result in column-major order. Use `[m n]` to request a matrix or `[m Inf]` to keep filling columns until EOF.",
+        "`A = fread(fid, precision)` controls how many bytes each element consumes and how the result is typed. RunMat supports the common precisions from MATLAB: `double`, `single`, `uint8`, `int8`, `uint16`, `int16`, `uint32`, `int32`, `uint64`, `int64`, and `char`. When no output class is specified, data is converted to double; `char` (and `*char`) return a MATLAB-style character array.",
+        "`A = fread(fid, sizeA, precision, skip, machinefmt)` honours optional byte skipping and machine-format overrides (`'native'`, `'ieee-le'`, `'ieee-be'`). The machine format defaults to the value recorded by `fopen`.",
+        "`[A, count] = fread(...)` returns the number of elements successfully read before encountering EOF.",
+        "If MATLAB requests more elements than available, `fread` pads matrix outputs with zeros (or `'\\0'` for character data) to satisfy the requested dimensions; the `count` output always reflects the number of real elements read from the file.",
+        "`A = fread(___, 'like', prototype)` matches the residency and logical or numeric flavour of `prototype`. GPU prototypes trigger an upload after reading so the result remains on the device, while logical prototypes convert the output using MATLAB's non-zero rule.",
+        "RunMat executes the builtin entirely on the host CPU. Arguments that reside on a GPU are gathered automatically before any I/O occurs."
+    ],
+    "examples": [
+        {
+            "description": "Reading double-precision values from a binary file",
+            "input": "fid = fopen('numbers.bin', 'w+b');\nfwrite(fid, [1 2 3], 'double');\nfrewind(fid);\n\n[values, count] = fread(fid);      % defaults to double precision\n% values is a 3x1 column vector [1; 2; 3], count == 3\n\nfclose(fid);\ndelete('numbers.bin')"
+        },
+        {
+            "description": "Reading bytes with a specific element count",
+            "input": "fid = fopen('payload.bin', 'w+b');\nfwrite(fid, uint8(1:6), 'uint8');\nfrewind(fid);\n\n[bytes, count] = fread(fid, 4, 'uint8');\n% bytes == [1; 2; 3; 4], count == 4\n\nfclose(fid);\ndelete('payload.bin')"
+        },
+        {
+            "description": "Loading a two-dimensional block of `uint8` data",
+            "input": "fid = fopen('frame.bin', 'w+b');\npayload = uint8(reshape(1:12, 3, 4));\nfwrite(fid, payload, 'uint8');\nfrewind(fid);\n\n[frame, count] = fread(fid, [3 4], 'uint8');\nframe = uint8(frame);              % convert back to uint8 if needed\n\nfclose(fid);\ndelete('frame.bin')"
+        },
+        {
+            "description": "Reading characters using the `*char` precision form",
+            "input": "fid = fopen('message.txt', 'w+b');\nfwrite(fid, 'RunMat', 'char');\nfrewind(fid);\n\n[text, count] = fread(fid, '*char');\ntext = text.';                      % row string 'RunMat'\n\nfclose(fid);\ndelete('message.txt')"
+        },
+        {
+            "description": "Skipping bytes between samples",
+            "input": "fid = fopen('interleaved.bin', 'w+b');\nfwrite(fid, uint8(1:12), 'uint8');\nfrewind(fid);\n\n[every_other, count] = fread(fid, 5, 'uint8', 1);   % read one byte, skip one byte\n% every_other == [1; 3; 5; 7; 9]\n\nfclose(fid);\ndelete('interleaved.bin')"
+        },
+        {
+            "description": "Respecting big-endian machine formats",
+            "input": "fid = fopen('sensors.be', 'w+b', 'ieee-be');\nfwrite(fid, uint16([258 772]), 'uint16');\nfrewind(fid);\n\n[values, count] = fread(fid, [2 1], 'uint16');\n% values == [258; 772], count == 2\n\nfclose(fid);\ndelete('sensors.be')"
+        },
+        {
+            "description": "Matching GPU residency with `'like'`",
+            "input": "fid = fopen('samples.bin', 'w+b');\nfwrite(fid, [2.5 4.5 6.5 8.5], 'double');\nfrewind(fid);\n\nprototype = gpuArray.zeros(4, 1);\n[values, count] = fread(fid, 4, 'double', 'like', prototype);\n% When a GPU provider is active, values stays on the GPU and count == 4.\n\nfclose(fid);\ndelete('samples.bin')"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What precision strings are supported?",
+            "answer": "RunMat implements the commonly used MATLAB precisions: `double`, `single`, `uint8`, `int8`, `uint16`, `int16`, `uint32`, `int32`, `uint64`, `int64`, and `char`. The short form `*char` is also recognised. When an output class is not specified explicitly (with `=>` or the `*class` syntax), the result is converted to double precision."
+        },
+        {
+            "question": "How are partial reads handled?",
+            "answer": "`fread` stops when it encounters EOF. Matrices requested with `[m n]` are padded with zeros (or `'\\0'`) when the file does not contain enough elements to fill every column. The `count` output records the number of real elements read before padding."
+        },
+        {
+            "question": "How do size arguments work?",
+            "answer": "Pass a scalar `N` to request a column vector with up to `N` elements, `[M N]` to request a matrix with `M` rows and `N` columns, or `[M Inf]` to keep reading additional columns until EOF. Omitting the size argument is equivalent to using `Inf` (read everything)."
+        },
+        {
+            "question": "How does the skip parameter behave?",
+            "answer": "`skip` specifies the number of bytes to skip after reading each element. It must be a non-negative integer. The file position advances by the element size plus the skip value for every element that is successfully read."
+        },
+        {
+            "question": "What does the `'like'` prototype control?",
+            "answer": "The `'like', prototype` pair matches the output residency and high-level type of `prototype`. Pass a GPU tensor to receive a GPU tensor, use a logical array to obtain logical output (non-zero becomes `true`), or use a character prototype together with a character precision to obtain a `CharArray`."
+        },
+        {
+            "question": "Which machine formats are supported?",
+            "answer": "The builtin recognises `'native'`, `'ieee-le'`, and `'ieee-be'` (including their MATLAB aliases such as `'little-endian'`, `'pc'`, `'big-endian'`, and `'mac'`). Unsupported formats (`'vaxd'`, `'cray'`, etc.) raise descriptive errors."
+        },
+        {
+            "question": "Can `fread` operate on standard input?",
+            "answer": "Standard input/output/error identifiers (0, 1, 2) are currently not supported by RunMat's `fread`. Open files explicitly with `fopen` before calling `fread`."
+        }
+    ],
+    "links": [
+        {
+            "label": "fopen",
+            "url": "./fopen"
+        },
+        {
+            "label": "fclose",
+            "url": "./fclose"
+        },
+        {
+            "label": "fwrite",
+            "url": "./fwrite"
+        },
+        {
+            "label": "fileread",
+            "url": "./fileread"
+        },
+        {
+            "label": "filewrite",
+            "url": "./filewrite"
+        },
+        {
+            "label": "feof",
+            "url": "./feof"
+        },
+        {
+            "label": "fgets",
+            "url": "./fgets"
+        },
+        {
+            "label": "fprintf",
+            "url": "./fprintf"
+        },
+        {
+            "label": "frewind",
+            "url": "./frewind"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/io/filetext/fread.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/io/filetext/fread.rs"
+    },
+    "gpu_residency": "```matlab:runnable\nfid = fopen('samples.bin', 'w+b');\nfwrite(fid, [2.5 4.5 6.5 8.5], 'double');\nfrewind(fid);\n\nprototype = gpuArray.zeros(4, 1);\n[values, count] = fread(fid, 4, 'double', 'like', prototype);\n% When a GPU provider is active, values stays on the GPU and count == 4.\n\nfclose(fid);\ndelete('samples.bin');\n```\n`values` stays on the GPU when an acceleration provider is active. Without a provider the function still returns correct data on the host.",
+    "gpu_behavior": [
+        "`fread` is a host-only operation. When the file identifier or optional arguments (size vectors, precision strings, skip counts) live on the GPU, RunMat gathers them to the host first. File handles are managed by the shared registry established by `fopen`, and GPU providers never participate in file I/O. When a `'like'` prototype is a GPU tensor, the builtin uploads the host result after the read so that the output mirrors the prototype's residency. Providers that fail the upload silently fall back to returning the host tensor."
+    ],
+    "key": "fread",
+    "slug": "fread",
+    "categoryPath": [
+        "io",
+        "filetext"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=fread.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fread.js","sourceRoot":"","sources":["../../../src/generated/builtins/fread.ts"],"names":[],"mappings":"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"}

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

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

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

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

package/dist/generated/builtins/frewind.js

@@ -0,0 +1,134 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "frewind",
+    "category": "io/filetext",
+    "keywords": [
+        "frewind",
+        "file",
+        "rewind",
+        "seek",
+        "io",
+        "file identifier"
+    ],
+    "summary": "Rewind the file position indicator to the beginning of an open file.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/frewind.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Runs entirely on the CPU. Arguments that live on the GPU are gathered automatically, and file handles remain host-resident."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::filetext::frewind::tests",
+        "integration": "builtins::io::filetext::frewind::tests::frewind_rewinds_to_beginning"
+    },
+    "description": "`frewind(fid)` moves the file position indicator back to the beginning of the file associated with `fid`. It is equivalent to calling `fseek(fid, 0, 'bof')` and is commonly used to re-read a file after an initial pass without closing and reopening it.",
+    "behaviors": [
+        "`frewind(fid)` rewinds the file position indicator to byte offset 0 for the file identified by `fid`.",
+        "`fid` must be a non-negative integer returned by `fopen`. Passing an invalid identifier raises an error.",
+        "Standard input/output identifiers (`0`, `1`, `2`) are silently accepted and treated as a no-op; RunMat does not support seeking on those streams.",
+        "`frewind` produces no output value. Assigning the result of `frewind` to a variable yields an empty output list.",
+        "After `frewind`, subsequent calls to `fread`, `fgets`, or `fscanf` start from the beginning of the file."
+    ],
+    "examples": [
+        {
+            "description": "Write then rewind and read back binary data",
+            "input": "fid = fopen('data.bin', 'w+b');\nfwrite(fid, [1 2 3], 'double');\nfrewind(fid);\nvalues = fread(fid, 'double');\nfclose(fid);\ndelete('data.bin')"
+        },
+        {
+            "description": "Read a text file twice without reopening",
+            "input": "fid = fopen('notes.txt', 'r');\nfirst_line = fgets(fid);\nfrewind(fid);\nsame_line = fgets(fid);\nfclose(fid)"
+        },
+        {
+            "description": "Rewind a binary file opened for reading bytes",
+            "input": "fid = fopen('payload.bin', 'w+b');\nfwrite(fid, uint8(1:6), 'uint8');\nfrewind(fid);\nbytes = fread(fid, 4, 'uint8');\nfclose(fid);\ndelete('payload.bin')"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What kind of input does `frewind` accept?",
+            "answer": "Pass a scalar numeric file identifier returned by `fopen`. The identifier must be a non-negative integer. Character vectors and strings are not accepted."
+        },
+        {
+            "question": "Does `frewind` return a value?",
+            "answer": "No. `frewind` is a void function and produces no output. Capturing its result assigns an empty output list."
+        },
+        {
+            "question": "How does `frewind` compare to `fseek`?",
+            "answer": "`frewind(fid)` is exactly equivalent to `fseek(fid, 0, 'bof')`. Use `frewind` when you only ever need to return to the beginning; use `fseek` when you need to jump to arbitrary positions."
+        },
+        {
+            "question": "Can I call `frewind` on a write-only file?",
+            "answer": "Yes, as long as the underlying file was opened with a mode that supports seeking (e.g. `'w+'` or `'w+b'`). Rewinding a write-only stream positions the cursor at the start so subsequent writes overwrite from the beginning."
+        },
+        {
+            "question": "Can I call `frewind` on a closed file?",
+            "answer": "No. Passing a closed or never-opened identifier raises `\"Invalid file identifier. Use fopen to generate a valid file ID.\"`"
+        }
+    ],
+    "links": [
+        {
+            "label": "fopen",
+            "url": "./fopen"
+        },
+        {
+            "label": "fclose",
+            "url": "./fclose"
+        },
+        {
+            "label": "fread",
+            "url": "./fread"
+        },
+        {
+            "label": "fwrite",
+            "url": "./fwrite"
+        },
+        {
+            "label": "feof",
+            "url": "./feof"
+        },
+        {
+            "label": "fgets",
+            "url": "./fgets"
+        },
+        {
+            "label": "fileread",
+            "url": "./fileread"
+        },
+        {
+            "label": "filewrite",
+            "url": "./filewrite"
+        },
+        {
+            "label": "fprintf",
+            "url": "./fprintf"
+        }
+    ],
+    "source": {
+        "label": "Open an issue",
+        "url": "https://github.com/runmat-org/runmat/issues/new/choose"
+    },
+    "gpu_residency": "No. File identifiers are always owned by the host-side registry maintained by `fopen`. Wrapping a scalar identifier in `gpuArray` does not keep the file handle on the GPU—the runtime gathers the scalar before performing the seek. The rewind operation itself executes entirely on the host.",
+    "gpu_behavior": [
+        "`frewind` is a host-only operation. If `fid` resides on the GPU (for example inside a `gpuArray`), RunMat gathers the scalar to host memory before consulting the file registry. File handles always remain on the CPU, so there are no provider hooks or fusion paths for this builtin."
+    ],
+    "key": "frewind",
+    "slug": "frewind",
+    "categoryPath": [
+        "io",
+        "filetext"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=frewind.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"frewind.js","sourceRoot":"","sources":["../../../src/generated/builtins/frewind.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,SAAS;IAClB,UAAU,EAAE,aAAa;IACzB,UAAU,EAAE;QACV,SAAS;QACT,MAAM;QACN,QAAQ;QACR,MAAM;QACN,IAAI;QACJ,iBAAiB;KAClB;IACD,SAAS,EAAE,sEAAsE;IACjF,YAAY,EAAE;QACZ,wDAAwD;KACzD;IACD,aAAa,EAAE;QACb,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,EAAE;QAChB,cAAc,EAAE,MAAM;QACtB,OAAO,EAAE,6HAA6H;KACvI;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,sEAAsE;KACtF;IACD,aAAa,EAAE,6PAA6P;IAC5Q,WAAW,EAAE;QACX,uGAAuG;QACvG,0GAA0G;QAC1G,mJAAmJ;QACnJ,kHAAkH;QAClH,0GAA0G;KAC3G;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,6CAA6C;YAC5D,OAAO,EAAE,mJAAmJ;SAC7J;QACD;YACE,aAAa,EAAE,0CAA0C;YACzD,OAAO,EAAE,+GAA+G;SACzH;QACD;YACE,aAAa,EAAE,+CAA+C;YAC9D,OAAO,EAAE,4JAA4J;SACtK;KACF;IACD,MAAM,EAAE;QACN;YACE,UAAU,EAAE,2CAA2C;YACvD,QAAQ,EAAE,2JAA2J;SACtK;QACD;YACE,UAAU,EAAE,gCAAgC;YAC5C,QAAQ,EAAE,6GAA6G;SACxH;QACD;YACE,UAAU,EAAE,wCAAwC;YACpD,QAAQ,EAAE,6LAA6L;SACxM;QACD;YACE,UAAU,EAAE,4CAA4C;YACxD,QAAQ,EAAE,+NAA+N;SAC1O;QACD;YACE,UAAU,EAAE,wCAAwC;YACpD,QAAQ,EAAE,8HAA8H;SACzI;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,SAAS;SACjB;QACD;YACE,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,UAAU;SAClB;QACD;YACE,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,SAAS;SACjB;QACD;YACE,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,UAAU;SAClB;QACD;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,SAAS;SACjB;QACD;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;QACD;YACE,OAAO,EAAE,WAAW;YACpB,KAAK,EAAE,aAAa;SACrB;QACD;YACE,OAAO,EAAE,SAAS;YAClB,KAAK,EAAE,WAAW;SACnB;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,eAAe;QACxB,KAAK,EAAE,wDAAwD;KAChE;IACD,eAAe,EAAE,kSAAkS;IACnT,cAAc,EAAE;QACd,0RAA0R;KAC3R;IACD,KAAK,EAAE,SAAS;IAChB,MAAM,EAAE,SAAS;IACjB,cAAc,EAAE;QACd,IAAI;QACJ,UAAU;KACX;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

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

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

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

package/dist/generated/builtins/fspecial.js

@@ -0,0 +1,145 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "fspecial",
+    "category": "image/filters",
+    "keywords": [
+        "fspecial",
+        "filter",
+        "gaussian",
+        "sobel",
+        "motion",
+        "laplacian",
+        "disk"
+    ],
+    "summary": "Generate classical 2-D correlation kernels used in MATLAB image processing workflows.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "Providers implement the optional 'fspecial' hook. When it is missing or a kernel is not yet accelerated (./motion), RunMat falls back to the host implementation transparently."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 0,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::image::filters::fspecial::tests",
+        "integration": "builtins::image::filters::fspecial::tests::fspecial_motion_sum_is_one",
+        "gpu": "builtins::image::filters::fspecial::tests::fspecial_gaussian_gpu_matches_cpu"
+    },
+    "description": "`fspecial(type, ...)` constructs well-known 2-D filter kernels such as averaging, Gaussian, Laplacian, Sobel, Prewitt, motion blur, Laplacian of Gaussian, unsharp masking, and disk (pillbox) filters. These kernels are intended for use with correlation and convolution routines like `imfilter` and `conv2`, and their outputs match MathWorks MATLAB behaviour for every supported option.",
+    "behaviors": [
+        "Uses MATLAB-compatible defaults for all optional parameters and validates scalar/vector inputs rigorously.",
+        "Produces double-precision column-major tensors that match MATLAB sample outputs to machine precision.",
+        "Normalises smoothing filters (average, disk, Gaussian, Laplacian of Gaussian, motion) to unit sum.",
+        "Emits derivative-style operators (Sobel, Prewitt, Laplacian, unsharp) using MATLAB's historical scaling.",
+        "Accepts scalar sizes or two-element vectors; zero/negative dimensions trigger MATLAB-style errors.\n\n### Supported filter types",
+        "`\"average\"`: rectangular mean filter with optional size argument.",
+        "`\"disk\"`: circular averaging filter parameterised by radius.",
+        "`\"gaussian\"`: Gaussian low-pass filter with optional size and standard deviation.",
+        "`\"laplacian\"`: 3×3 Laplacian operator controlled by `alpha` (0 ≤ alpha ≤ 1).",
+        "`\"log\"`: Laplacian of Gaussian with optional size and `sigma`.",
+        "`\"motion\"`: motion blur kernel with controllable length and angle (rounded to odd kernel width).",
+        "`\"prewitt\"`: 3×3 horizontal Prewitt edge detector.",
+        "`\"sobel\"`: 3×3 horizontal Sobel edge detector.",
+        "`\"unsharp\"`: 3×3 unsharp masking filter with optional `alpha`."
+    ],
+    "examples": [
+        {
+            "description": "Creating a box filter for local averaging",
+            "input": "H = fspecial(\"average\", 7);        % 7x7 box filter with unit sum"
+        },
+        {
+            "description": "Building a Gaussian smoothing kernel",
+            "input": "H = fspecial(\"gaussian\", [5 5], 1.0)"
+        },
+        {
+            "description": "Generating a disk filter for circular blur",
+            "input": "H = fspecial(\"disk\", 4)"
+        },
+        {
+            "description": "Constructing a Laplacian-of-Gaussian edge detector",
+            "input": "H = fspecial(\"log\", [9 9], 1.4)"
+        },
+        {
+            "description": "Synthesising a motion blur kernel at 30 degrees",
+            "input": "H = fspecial(\"motion\", 15, 30)"
+        },
+        {
+            "description": "Tuning an unsharp mask for edge enhancement",
+            "input": "H = fspecial(\"unsharp\", 0.6)"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Which filters does `fspecial` support?",
+            "answer": "All classic MATLAB filters are available: average, disk, Gaussian, Laplacian, Laplacian of Gaussian, motion, Prewitt, Sobel, and unsharp."
+        },
+        {
+            "question": "Does `fspecial` normalise the kernels?",
+            "answer": "All smoothing filters produce weights that sum to one. Derivative-style kernels follow MATLAB's scaling so that downstream edge detection behaves identically."
+        },
+        {
+            "question": "Can I generate a GPU-resident kernel directly?",
+            "answer": "Yes. Set `RUNMAT_ACCEL_FSPECIAL_DEVICE=1` and ensure the active provider exposes the `fspecial` hook. Unsupported filters or providers gather to host automatically, so results stay correct either way."
+        },
+        {
+            "question": "How do I specify the kernel size?",
+            "answer": "Most filters accept a scalar size or a two-element `[rows cols]` vector. When omitted, MATLAB-compatible defaults are used (for example, 3×3 for average/gaussian/laplacian/prewitt/sobel/unsharp)."
+        },
+        {
+            "question": "What happens if I provide invalid parameters?",
+            "answer": "`fspecial` raises MATLAB-compatible errors when arguments fall outside the documented range. Negative lengths, radii, or sigmas, as well as noninteger dimensions, produce descriptive error messages."
+        },
+        {
+            "question": "Are the filters symmetric with MATLAB outputs?",
+            "answer": "Yes. Each kernel matches MATLAB (R2023b) outputs within floating-point precision, including motion blur and disk filters that rely on geometric integration."
+        }
+    ],
+    "links": [
+        {
+            "label": "imfilter",
+            "url": "./imfilter"
+        },
+        {
+            "label": "conv2",
+            "url": "./conv2"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "filter2",
+            "url": "./filter2"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/image/filters/fspecial.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/image/filters/fspecial.rs"
+    },
+    "gpu_behavior": [
+        "When an acceleration provider is active, `fspecial` can materialise supported kernels directly on the GPU. Opt-in by setting `RUNMAT_ACCEL_FSPECIAL_DEVICE=1`. If the provider exports the `fspecial` hook (the WGPU backend covers average, gaussian, laplacian, prewitt, sobel, and unsharp), the builtin returns a `gpuArray` handle that remains device-resident for downstream fusion. Kernels without acceleration support and providers lacking the hook automatically fall back to the host path with identical numerical results."
+    ],
+    "key": "fspecial",
+    "slug": "fspecial",
+    "categoryPath": [
+        "image",
+        "filters"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=fspecial.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fspecial.js","sourceRoot":"","sources":["../../../src/generated/builtins/fspecial.ts"],"names":[],"mappings":"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"}

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

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

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

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