Module

Puregrain.Ordered

Package
purescript-puregrain
Repository
roman-mkh/puregrain

Ordered dithering: a quantizer whose decision between two neighbouring levels depends on the pixel's position, through a repeating grid of thresholds — a threshold map. The best known one is the Bayer matrix (Bryce E. Bayer, Kodak, 1973).

It's an ordinary Quantize, so it works with ditherImage like any other quantizer. With noDiffusion (no error passed on), that gives pure ordered dithering; with any other kernel, the hybrid "threshold modulation": error diffusion keeps the tones right, and the map decides where the dots land. Background, formulas and what to look for: docs/ordered-dithering.md.

#ThresholdMap Source

newtype ThresholdMap

A threshold map: a grid of thresholds, each strictly between 0 and 1, repeated across the image. Build one with bayer or compileThresholdMap; opaque, so every map is checked: rectangular and non-empty.

#bayer Source

bayer :: Int -> Maybe ThresholdMap

The Bayer threshold map.

  • Int: the side, a power of 2 (1, 2, 4, 8, …).

Nothing for any other side. The thresholds are (rank + 0.5) / n² for side n (see compileThresholdMap). bayer 1 is 0.5 everywhere: ordered with it picks the nearer level, like nearestLevel.

-- pure 1-bit ordered dithering with the 8 × 8 map
map (\m -> ditherImage noDiffusion (ordered m (evenRamp 2)) image) (bayer 8)

#bayerMatrix Source

bayerMatrix :: Int -> Maybe (Array (Array Int))

The ranks of a Bayer matrix: the order in which its cells turn on.

  • Int: the side, a power of 2 (1, 2, 4, 8, …).

Nothing for any other side. Built by the standard recursion from the 1 × 1 matrix [[0]]:

M₂ₙ = | 4·Mₙ + 0   4·Mₙ + 2 |
      | 4·Mₙ + 3   4·Mₙ + 1 |

so bayerMatrix 2 == Just [[0, 2], [3, 1]], and every rank from 0 to n² − 1 appears exactly once. The result has n² entries: mind the size for large n.

#compileThresholdMap Source

compileThresholdMap :: Array (Array Int) -> Either String ThresholdMap

A threshold map from your own ranks: a clustered-dot screen or a blue-noise mask, say.

  • Array (Array Int): the ranks, row by row: the order in which the cells turn on as the input rises. The grid needn't be square, and ranks may repeat or skip values.

Each cell's threshold is (rank + 0.5) / (maxRank + 1), strictly between 0 and 1. Left says what's wrong: no rows, an empty row, rows of different lengths, or a negative rank (rows and columns counted from 0).

#thresholdAt Source

thresholdAt :: forall r. ThresholdMap -> { x :: Int, y :: Int | r } -> Number

The threshold at a pixel's position; the map repeats across the image.

  • ThresholdMap: the map.
  • { x :: Int, y :: Int | r }: the position, any record with x and y, such as a quantizer's Context.

Column x uses the map's column x mod width, row y its row y mod height.

#ordered Source

ordered :: ThresholdMap -> NonEmptyArray Number -> Quantize Number

Ordered dithering over levels. For a value v between two neighbouring levels lo < hi, it picks hi exactly when (v − lo) / (hi − lo) is above the pixel's threshold, else lo.

  • ThresholdMap: the thresholds, from bayer or compileThresholdMap.
  • NonEmptyArray Number: the levels, in any order; with 0 and 255, classic 1-bit ordered dithering.

A value at a level stays that level; values beyond the lowest or highest level snap to it, as accumulated error can push them there in the hybrid with error diffusion. For color, lift it with perChannel, which gives every channel the same position.

With a gamma (Puregrain.Dither.ditherImageWith), v, lo and hi are amounts of light, so each pattern gives off the light it stands for; levels that aren't whole numbers are rounded first. With few patterns, such as bayer 2 over two levels, the darkest grays then turn black: they're nearer to black's light than to the first pattern's.