threshold

Builtin index · Images

result = threshold(x, level)

Input: x, level · Output: result

What it is

x is an Image, Signal, Vec, or scalar; level is a number, the cutoff. Elementwise binary threshold, general-purpose (not image-specific). Image → binary black/white image of the same dimensions (per-pixel BT.601 luma vs level); Signal → same-Fs Signal of 0.0/1.0; Vec/scalar → identical to x >= level (a Mask/Bool via the shared compare path).

Overloads

x can be Image, Signal, Vec, or number; level can be Image, Signal, Mask, Vec, bool, or scalar.

3 forms. Each carries its own inputs, outputs and worked example — pick the tab for the one you are calling.

Image Signal Vec or scalar

Code	Input	Output	Description
`result = threshold(x, level)`	`x` Image`x` an `Image`. `level` ImageCompares each pixel's BT.601 luma against `level` and returns a new binary (0/255) `Image` of the same dimensions — the classic black-and-white segmentation mask.	`result` Image, Signal, Mask, Vec, or scalar	—

Examples

Written for this form and run by the build -- the output below is what the engine actually produced.

m = [10, 200; 50, 220]
img = image_from_matrix(m)
mask = threshold(img, 128)
imshow(mask)
print(mask.width, mask.height)   # 2 2

output

2 2

Code	Input	Output	Description
`result = threshold(x, level)`	`x` Signal`x` a `Signal`. `level` Signal or MaskElementwise compare against `level`, but returned as a same-`Fs` `Signal` of `0.0`/`1.0` values rather than a `Mask` — so it stays a `Signal` and can keep flowing through DSP functions that expect one.	`result` Image, Signal, Mask, Vec, or scalar	—

Examples

Written for this form and run by the build -- the output below is what the engine actually produced.

sig = signal([1, 5, 2, 8], 100)
print(threshold(sig, 4))   # signal(Fs=100) [0, 1, 0, 1]

output

signal(Fs=100) [0, 1, 0, 1]

Code	Input	Output	Description
`result = threshold(x, level)`	`x` Vec or number`x` a `Vec` or a plain number. `level` Mask, Vec, bool, or scalarIdentical to `x >= level` — a `Mask` for a `Vec`, a plain `bool` for a scalar — reusing the exact same shared `compare` path the `>=` operator itself uses, rather than any image-specific logic.	`result` Image, Signal, Mask, Vec, or scalar	—

Examples

Written for this form and run by the build -- the output below is what the engine actually produced.

v = [1, 5, 10, 2]
print(threshold(v, 4))    # [F, T, T, F]

print(threshold(7, 4))    # true

output

[F, T, T, F]
true

multithreshold branches on x's type the same way, but the results differ more: its Image case returns a posterized *image* (evenly-spaced gray bands), while its Signal/plain-numeric case returns a raw 0-based *band index* rather than anything image-shaped.

How it works

threshold(x, level) (§ thresholding, 2026-08-24, Ahmed: "Threshold & multithreshold should be implemented in signal too, [along with] Otsu method and better methods") — elementwise binary threshold. NOT the same job as foreground_mask above (that one is a blob/segmentation convenience — threshold + morphological opening in one call); this is the plain, general-purpose global threshold, with no morphology, usable on Image/Vec/Signal alike. Value::Image -> a binary black/white image (per-pixel BT.601 luma vs level, not three independently-thresholded channels — the standard convention ahead of segmentation, same luma computation foreground_mask/to_grayscale already use); Value::Signal -> a same-Fs Signal of 0.0/1.0; Value::Vec/scalar -> reuses the exact >= comparison operator's own output convention (a Mask for a vector, a Bool for a scalar) via compare, so threshold(x, level) and x >= level agree exactly on anything that isn't an Image/Signal. See apply_threshold's doc comment for the full rationale.

From the note above this builtin in the interpreter, where the reasoning was written down as it was built.