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 ThresholdMapA 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 ThresholdMapThe 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 ThresholdMapA 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 } -> NumberThe threshold at a pixel's position; the map repeats across the image.
ThresholdMap: the map.{ x :: Int, y :: Int | r }: the position, any record withxandy, such as a quantizer'sContext.
Column x uses the map's column x mod width, row y its row
y mod height.
#ordered Source
ordered :: ThresholdMap -> NonEmptyArray Number -> Quantize NumberOrdered 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, frombayerorcompileThresholdMap.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.
- Modules
- Puregrain
- Puregrain.
Cells - Puregrain.
Dither - Puregrain.
Gamma - Puregrain.
Internal. Exact - Puregrain.
Internal. Fifo - Puregrain.
Internal. Gamma - Puregrain.
Internal. Image - Puregrain.
Internal. Kernel - Puregrain.
Internal. Quantize - Puregrain.
Internal. Row - Puregrain.
Internal. SelfCheck - Puregrain.
Internal. State - Puregrain.
Internal. Step - Puregrain.
Internal. Util - Puregrain.
Kernel - Puregrain.
Machine. C64 - Puregrain.
Machine. ZxSpectrum - Puregrain.
Ordered - Puregrain.
Palette - Puregrain.
Palette. Presets - Puregrain.
Pixel - Puregrain.
Quantize - Puregrain.
SelfCheck