binarize

binarize(
  input: Clip,
  #{
    threshold?: Int | Float | Array<Int> | Array<Float>,
    lower?: Int | Float | Array<Int> | Array<Float>,
    upper?: Int | Float | Array<Int> | Array<Float>,
    planes?: Array<Int>,
  }
)

Sets each processed pixel to upper when the input sample is greater than or equal to threshold, or to lower when the input sample is below threshold.

The input must be one fixed-format planar Gray, YUV, or planar RGB clip. Integer formats use Int option values within the format’s code range, such as 0..=255 for 8-bit or 0..=1023 for 10-bit. Float formats use Float option values within 0.0..=1.0.

If an option is supplied as a scalar value, it applies to every processed plane. If an option is supplied as an array and planes is omitted, the array length must match the input plane count. If planes is supplied, each array length must match the number of listed planes and array entries map to the listed planes by position. Duplicate plane indexes are rejected.

upper does not need to be greater than lower. This lets you create inverted binary output by setting upper lower than lower.

For float clips, NaN input samples compare as below threshold, so they map to lower.

Examples

output = source("input.mkv").std.binarize()

output = source("input.mkv").std.binarize(#{
  threshold: 128,
  lower: 16,
  upper: 235,
  planes: [0],
})

output = source("input.mkv").std.binarize(#{
  threshold: [96, 128, 160],
  lower: [0, 128, 128],
  upper: [255, 255, 255],
})

output = source("input.mkv")
  .std.convert_format(#{ format: "grayf32" })
  .std.binarize(#{ threshold: 0.5, lower: 0.0, upper: 1.0 })

Input

One fixed-format planar Gray, YUV, or planar RGB clip.

Output

A clip with the same format, resolution, timing, and metadata, with selected planes replaced by binary lower/upper samples.

Options

• threshold (Int | Float | Array<Int> | Array<Float>, default: midpoint of the format range) – Compare each input sample against this value. Integer defaults use the upper midpoint, such as 128 for 8-bit and 512 for 10-bit. Float defaults use 0.5.
• lower (Int | Float | Array<Int> | Array<Float>, default: minimum format value) – Output sample for input samples below threshold. Integer defaults use 0. Float defaults use 0.0.
• upper (Int | Float | Array<Int> | Array<Float>, default: maximum format value) – Output sample for input samples greater than or equal to threshold. Integer defaults use the format maximum. Float defaults use 1.0.
• planes (Array<Int>, default: all planes) – Zero-based plane indexes to process. Unlisted planes are preserved without modification. An empty array processes no planes.