Module

Puregrain

Package
purescript-puregrain
Repository
roman-mkh/puregrain

Error-diffusion and ordered dithering, in one import. This module re-exports what a typical application needs:

  • ditherImage, which dithers an image in memory; ditherRows, which dithers a lazy stream of rows, each when it's needed; and initDithering with ditherRow, one row at a time from any source;
  • the kernels floydSteinberg, atkinson, jarvisJudiceNinke, stucki, burkes, sierra3, sierra2, sierraLite, fan, shiauFan and shiauFan2, and noDiffusion for none;
  • the quantizers threshold, nearestLevel with evenRamp, and perChannel for color; nearestColor with the palette presets; bayer and ordered for ordered dithering;
  • ditherImageWith, ditherRowsWith and initDitheringWith, the same with a gamma curve, gammaOff, gamma1p2, gamma1p5, gamma1p8 or gammaSrgb, which says how the stored numbers turn into light; and toGray, a color's gray by that curve;
  • the pixel types RGB and RGBA, and the types for signatures.

Import it qualified, as names like threshold or c64 are short:

import Puregrain as P

dithered = P.ditherImage P.floydSteinberg (P.threshold 128.0) image

The building blocks for your own variants (distance metrics, threshold maps, custom quantizers) are in the modules they come from: Puregrain.Palette, Puregrain.Ordered, Puregrain.Quantize, Puregrain.Pixel, Puregrain.Kernel and Puregrain.Gamma. Dithering with cells, as on the screens of 8-bit machines, is in Puregrain.Cells and Puregrain.Machine.ZxSpectrum, outside this module.

Re-exports from Puregrain.Dither

#Dithering Source

newtype Dithering a

An image being dithered one row at a time, for ditherRow: the kernel, the quantizer, and the error waiting for the rows still to come; a is the pixel type. Opaque.

An immutable value: keep and reuse one, for an undo, say. Dithering a row from it again redoes that row's work, and no more.

#initDitheringWith Source

initDitheringWith :: forall a. ColorChannels a => Gamma -> Kernel -> Quantize a -> Dithering a

The state before the first row, for ditherRow, keeping the amount of light the curve gives each value.

  • a and Gamma: as for ditherImageWith.
  • Kernel and Quantize a: as for initDithering.

ditherRow then gives the same rows as ditherImageWith, each as stored values.

#initDithering Source

initDithering :: forall a. Kernel -> Quantize a -> Dithering a

The state before the first row, for ditherRow.

  • Kernel: where each pixel's error goes; noDiffusion for nowhere.
  • Quantize a: picks each pixel's output value.

Dithers nothing yet; the first row fixes the image's width.

#ditherRowsWith Source

ditherRowsWith :: forall a. Ring a => Scalable a => ColorChannels a => Gamma -> Kernel -> Quantize a -> List (Array a) -> List (Array a)

Dithers a lazy stream of rows, keeping the amount of light the curve gives each value.

  • a and Gamma: as for ditherImageWith.
  • Kernel, Quantize a, LL.List (Array a): as for ditherRows.

Returns the dithered rows as a lazy list, the same rows as ditherImageWith, each read and dithered when it's first needed.

#ditherRows Source

ditherRows :: forall a. Ring a => Scalable a => Kernel -> Quantize a -> List (Array a) -> List (Array a)

Dithers a lazy stream of rows.

  • a, Kernel and Quantize a: as for ditherImage.
  • LL.List (Array a): the rows, top to bottom, all of the same length; the list may be endless.

Returns the dithered rows as a lazy list, the same rows as ditherImage. Each row is read and dithered only when its result is first needed, so only the rows in flight are in memory. At a row whose length differs from the first row's, it stops with an error naming the row; the rows before it have come out.

#ditherRow Source

ditherRow :: forall a. Ring a => Scalable a => Dithering a -> Array a -> Either String { next :: Dithering a, row :: Array a }

Dithers the next row.

  • Dithering a: the state, from initDithering or the previous row.
  • Array a: the row, as long as the first one.

Returns the dithered row and the state for the next one: the same rows as ditherImage. Left, with a message naming the row, for a row of a different length; the state passed in is untouched, so you can carry on with a corrected row.

#ditherImageWith Source

ditherImageWith :: forall a. Ring a => Scalable a => ColorChannels a => Gamma -> Kernel -> Quantize a -> Array (Array a) -> Array (Array a)

Dithers an image in memory, keeping the amount of light the curve gives each value rather than the average of the stored numbers.

  • a: the pixel type, Number, RGB or RGBA; any type with Ring, Scalable and ColorChannels works.
  • Gamma: how the stored numbers turn into light: gammaOff, the same as ditherImage, or gamma1p2, gamma1p5, gamma1p8 or gammaSrgb (linear light).
  • Kernel, Quantize a, Array (Array a): as for ditherImage.

Returns the dithered image as stored values: each row is taken to light, dithered there, and brought back. The error and the amounts of light (ordered dithering's patterns) are in light; the choices of the nearest level or color stay on stored values, as the eye sees them; a level or a palette color of whole numbers comes back exactly. Stops with an error naming a row whose length differs from the first row's.

ditherImageWith gammaSrgb floydSteinberg (threshold 128.0) image

#ditherImage Source

ditherImage :: forall a. Ring a => Scalable a => Kernel -> Quantize a -> Array (Array a) -> Array (Array a)

Dithers an image in memory.

  • a: the pixel type, Number for gray, RGB or RGBA; any type with Ring and Scalable works.
  • Kernel: where each pixel's error goes; noDiffusion for nowhere.
  • Quantize a: picks each pixel's output value.
  • Array (Array a): the image, rows top to bottom, each left to right, all of the same length.

Returns the dithered image, all at once. Stops with an error naming a row whose length differs from the first row's.

Re-exports from Puregrain.Gamma

#Gamma Source

data Gamma

A curve between a picture's stored values and light: one of Puregrain.Gamma's presets, gammaOff, gamma1p2, gamma1p5, gamma1p8 and gammaSrgb.

#toGray Source

toGray :: Gamma -> RGB -> Number

A color's gray, for dithering a color picture in gray.

  • Gamma: the curve, which decides the formula; give the dithering the same one.
  • RGB: the color, as stored.

Returns the gray as a stored value, 0 to 255. A neutral color, with red, green and blue equal, gives exactly that value. With gammaOff, the gray is luma, 0.299 R + 0.587 G + 0.114 B on the stored values, the classic conversion. With a curve, it's the gray that gives off as much light as the color: 0.2126 R + 0.7152 G + 0.0722 B on the channels' light (luminance, with gammaSrgb), brought back to a stored value. Saturated colors then come out lighter than with luma, pure blue 76 instead of 29 with gammaSrgb; natural colors such as skin barely change.

toGray gammaOff (RGB { r: 0.0, g: 0.0, b: 255.0 })    -- 29.07
toGray gammaSrgb (RGB { r: 0.0, g: 0.0, b: 255.0 })   -- 75.96…

ditherImageWith gammaSrgb floydSteinberg (threshold 128.0)
  (map (map (toGray gammaSrgb)) image)

#gammaSrgb Source

gammaSrgb :: Gamma

Linear light: the sRGB standard's curve (IEC 61966-2-1), a straight piece near black and a power of 2.4 above it, which behaves much like a power of 2.2 overall.

#gammaOff Source

gammaOff :: Gamma

No conversion: the stored numbers are taken as amounts of light, as dithering has always taken them. The default.

#gamma1p8 Source

gamma1p8 :: Gamma

A power curve: light = (value / 255)^1.8 × 255, the gamma of Apple RGB, the classic Macintosh's color space.

#gamma1p5 Source

gamma1p5 :: Gamma

A power curve: light = (value / 255)^1.5 × 255.

#gamma1p2 Source

gamma1p2 :: Gamma

A power curve: light = (value / 255)^1.2 × 255.

Re-exports from Puregrain.Kernel

#Offset Source

type Offset = { dx :: Int, dy :: Int, weight :: Number }

One neighbour that gets a share of a pixel's error.

  • dx: columns to the right; negative to the left.
  • dy: rows down.
  • weight: the share of the error.

#Kernel Source

newtype Kernel

A checked list of neighbours. Build one with fromOffsets, or use a ready-made one. Opaque, so every kernel ditherImage gets is valid.

Instances

#stucki Source

stucki :: Kernel

Stucki (Peter Stucki, IBM Zurich, 1981): 12 neighbours over the next 2 rows, like Jarvis–Judice–Ninke, with weights that give a clean, sharp result.

#sierraLite Source

sierraLite :: Kernel

Sierra Lite (Frankie Sierra, 1989–1990; also "Filter Lite" or "Sierra-2-4A"): 3 neighbours, one fewer than Floyd–Steinberg, for similar results.

#sierra3 Source

sierra3 :: Kernel

Sierra 3 (Frankie Sierra, 1989–1990; also "Sierra" or "three-row Sierra"): 10 neighbours over the next 2 rows, for results like Jarvis–Judice–Ninke's with fewer neighbours.

#sierra2 Source

sierra2 :: Kernel

Sierra 2 (Frankie Sierra, 1989–1990; also "two-row Sierra"): 7 neighbours over the next row, a faster Sierra 3.

#shiauFan2 Source

shiauFan2 :: Kernel

Shiau–Fan 2 (Jeng-Nan Shiau and Zhigang Fan, 1993): the same aim with 5 neighbours, reaching three columns to the left.

#shiauFan Source

shiauFan :: Kernel

Shiau–Fan (Jeng-Nan Shiau and Zhigang Fan, 1993): 4 neighbours, with weights in eighths, made to reduce the "worm" patterns of Floyd–Steinberg.

#noDiffusion Source

noDiffusion :: Kernel

No neighbours: no error is passed on, so each pixel is quantized on its own. With Puregrain.Ordered, that's pure ordered dithering; with threshold or nearestLevel, plain rounding to a level.

#jarvisJudiceNinke Source

jarvisJudiceNinke :: Kernel

Jarvis–Judice–Ninke (1976): 12 neighbours over the next 2 rows, for the smoothest texture, at about 2.5 times Floyd–Steinberg's cost.

#floydSteinberg Source

floydSteinberg :: Kernel

Floyd–Steinberg (1976): 4 neighbours, the classic.

#fan Source

fan :: Kernel

Fan (Zhigang Fan, 1993): Floyd–Steinberg's 4 neighbours with one weight moved, its 1/16 from below-right to two columns left.

#burkes Source

burkes :: Kernel

Burkes (Daniel Burkes, 1988): Stucki without its last row, so 7 neighbours over the next row: a little less clean, at a lower cost.

#atkinson Source

atkinson :: Kernel

Atkinson (Apple, 1980s): 6 neighbours over the next 2 rows, each getting 1/8, so only 3/4 of the error is passed on: crisper and higher in contrast, at the cost of detail in dark and light tones.

Re-exports from Puregrain.Ordered

#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.

#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.

#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)

Re-exports from Puregrain.Palette

#nearestColor Source

nearestColor :: NonEmptyArray RGB -> Quantize RGB

A quantizer that turns each pixel into the nearest palette color, all three channels together, by distance2; on a tie, the earlier color.

  • NonEmptyArray RGB: the palette, e.g. from Puregrain.Palette.Presets.
ditherImage floydSteinberg (nearestColor websafe216) image

With a gamma (Puregrain.Dither.ditherImageWith), the nearest color is still chosen on stored values, as the eye sees them: each corrected pixel is brought back from light for the comparison, and the chosen color taken to light, while the error stays in light. A pixel that's exactly a byte's light comes back as that byte, so without diffusion the result is the one ditherImage gives.

Re-exports from Puregrain.Palette.Presets

#zxSpectrum Source

zxSpectrum :: NonEmptyArray RGB

The ZX Spectrum's 15 distinct colors: its 8 (black, blue, red, magenta, green, cyan, yellow, white) at normal brightness, then the 7 non-black ones with BRIGHT (bright black is black). Normal is 0xD8 = 216, about 85% of bright, the common model: the real colors were never measured, and many emulators use 0xD7 or 0xCD instead. This is the per-pixel palette; for the real machine's 2 colors per 8×8 cell, see Puregrain.Machine.ZxSpectrum. Source: en.wikipedia.org/wiki/ZX_Spectrum_graphic_modes; values as lospec.com/palette-list/zx-spectrum.

#websafe216 Source

websafe216 :: NonEmptyArray RGB

The 216 "web-safe" colors: every combination of 0, 51, 102, 153, 204 and 255 per channel (a 6×6×6 cube), r varying slowest, so it starts at black and ends at white. Being a complete grid, its nearest color is the nearest step in each channel separately — the same result as perChannel (nearestLevel (evenRamp 6)).

#cga16 Source

cga16 :: NonEmptyArray RGB

The 16-color IBM PC palette, CGA's "RGBI" colors in index order 0–15: each channel 0x00 or 0xAA, plus an intensity bit adding 0x55, with the IBM 5153 monitor's brown (color 6 is #AA5500, not dark yellow). Also EGA's and VGA's defaults and the DOS text colors; the Linux console uses the same values, in ANSI order. EGA's full 64 colors need no preset: perChannel (nearestLevel (evenRamp 4)). Source: en.wikipedia.org/wiki/Color_Graphics_Adapter (RGBI palette).

#c64 Source

c64 :: NonEmptyArray RGB

The Commodore 64's 16 colors, in VIC-II index order: black, white, red, cyan, purple, green, blue, yellow, orange, brown, light red, dark grey, grey, light green, light blue, light grey. There's no official RGB definition; these are Colodore's values, Pepto's model of the VIC-II's colors (2017), with the display set to brightness 47.5, contrast 100 and saturation 70. Source: pepto.de/projects/colorvic (the model); the values as in VICE's data/C64/colodore.vpl, which those settings reproduce exactly.

#blackWhite Source

blackWhite :: NonEmptyArray RGB

Black, then white. With nearestColor it dithers a color image straight down to pure black and white, choosing by RGB distance — which isn't brightness: pure green is nearer to black.

#ansi256 Source

ansi256 :: NonEmptyArray RGB

xterm's 256 colors: ansi16 (indices 0–15), a 6×6×6 cube (16–231, index 16 + 36r + 6g + b, levels 0, 95, 135, 175, 215, 255), and 24 grays (232–255, 8 + 10i). 7 cube colors repeat ansi16 ones, so 249 are distinct; nearestColor picks the earlier index of a pair. In a real terminal the first 16 come from its theme. Source: xterm's 256colres.pl.

#ansi16 Source

ansi16 :: NonEmptyArray RGB

The 16 ANSI terminal colors as xterm's defaults, in index order: black, red, green, yellow, blue, magenta, cyan, white, then the 8 bright ones. ANSI names the colors but defines no RGB, and terminals differ; the Linux console's values are cga16, in CGA order. Source: xterm's XTerm-col.ad, matching the xterm column of en.wikipedia.org/wiki/ANSI_escape_code.

Re-exports from Puregrain.Pixel

#RGBA Source

newtype RGBA

A color pixel with alpha: as RGB, plus a, which error diffusion treats like the other channels.

Constructors

Instances

#RGB Source

newtype RGB

A color pixel: red, green and blue, each from 0 to 255 by convention. Adds, subtracts and scales channel by channel, as error diffusion needs.

Constructors

Instances

#Gray Source

type Gray = Number

A gray pixel: one channel, a plain Number, from 0 (black) to 255 (white) by convention.

#ColorChannels Source

class ColorChannels a 

A pixel type whose color channels can be mapped one by one, leaving any other channel as it is: what converting a pixel between stored values and light needs (Puregrain.Gamma.toLight and fromLight), since alpha isn't on a light curve. Laws, as for MapChannels:

mapColorChannels identity == identity
mapColorChannels (f <<< g) == mapColorChannels f <<< mapColorChannels g

Instances

#MapChannels Source

class MapChannels a 

A pixel type whose channels can be mapped one by one: what Puregrain.Quantize.perChannel needs to run a one-channel quantizer on every channel. Laws, as for any functor-like mapping:

mapChannels identity == identity
mapChannels (f <<< g) == mapChannels f <<< mapChannels g

Instances

#Scalable Source

class (Ring a) <= Scalable a 

A pixel type that error diffusion can scale by a kernel's weights. With Ring, for adding and subtracting error, it's what ditherImage needs from a pixel type.

Instances

Re-exports from Puregrain.Quantize

#Quantize Source

newtype Quantize a

A quantizer: picks a pixel's output value; a is the pixel type. Build one with quantize, or quantizeWith when the decision depends on the pixel's position; run one with runQuantize. Opaque, so its representation can change without breaking anyone.

It gets the pixel's corrected value, with the error diffused into it already added, and must be total: accumulated error pushes values beyond the nominal range, below 0 or above 255, and the quantizer must still return a sensible value. ditherImage diffuses the difference between the corrected value and the output to the neighbours.

#Context Source

type Context = { x :: Int, y :: Int }

Where the pixel being quantized sits: column x and row y, from 0 at the top-left. A record so it can grow, with a seed say, without breaking quantizers: a helper that needs only some fields can take forall r. { x :: Int, y :: Int | r }.

#threshold Source

threshold :: Number -> Quantize Number

The classic 1-bit quantizer: 0 (black) below the threshold, 255 (white) at or above it.

  • Number: the threshold, usually 128.

nearestLevel (evenRamp 2) is the same with the cut fixed at 127.5.

With a gamma (ditherImageWith), the cut stays at the stored value: it's converted to light once, so a gray below it still goes to black.

#runQuantize Source

runQuantize :: forall a. Quantize a -> Context -> a -> a

Runs a quantizer.

  • Quantize a: the quantizer.
  • Context: the pixel's position.
  • a: the corrected value.

Returns the output value. For many pixels, apply it to the quantizer once and keep the result, let q = runQuantize quantizer, then call q for each pixel: some quantizers prepare things first.

#quantizeWith Source

quantizeWith :: forall a. (Context -> a -> a) -> Quantize a

A quantizer that also gets the pixel's position: ordered or noise dithering, say, or a lookup in per-pixel data such as a mask.

  • Context -> a -> a: from the position and the corrected value to the output value.
-- 1-bit with the cut at 64 and 192 in a checkerboard
quantizeWith \{ x, y } v ->
  if v < (if (x + y) `mod` 2 == 0 then 64.0 else 192.0) then 0.0 else 255.0

With a gamma other than gammaOff, as for quantize: the function still sees stored values, at two conversions per pixel.

#quantize Source

quantize :: forall a. (a -> a) -> Quantize a

A quantizer that ignores the pixel's position, the common case.

  • a -> a: from the corrected value to the output value.
-- 1-bit with the cut at 100
quantize \v -> if v < 100.0 then 0.0 else 255.0

With a gamma other than gammaOff (Puregrain.Dither.ditherImageWith), the function still gets and returns stored values: each pixel is brought back from light before it and its result taken to light after, while the error stays in light. That's two conversions per pixel; a quantizer built with quantizeInLight needs none.

#perChannel Source

perChannel :: forall a. MapChannels a => Quantize Number -> Quantize a

Runs a one-channel quantizer on every channel of a pixel, independently, each with the pixel's position.

  • a: the pixel type, with MapChannels: Number, RGB or RGBA.
  • Quantize Number: the quantizer for one channel.

Dithering an RGB image this way gives exactly what dithering its three channel planes separately would: a Quantize Number only ever sees one channel, so it can't couple them. For a quantizer that looks at the whole pixel, see Puregrain.Palette.nearestColor.

-- 4 levels per channel
perChannel (nearestLevel (evenRamp 4)) :: Quantize RGB

#nearestLevel Source

nearestLevel :: NonEmptyArray Number -> Quantize Number

Snaps a value to the nearest of the given levels: the one-channel sibling of Puregrain.Palette.nearestColor.

  • NonEmptyArray Number: the levels, in any order; on an exact tie, the earlier wins.

Values below the lowest level snap to it, values above the highest to that one.

nearestLevel (evenRamp 4)   -- 0, 85, 170 or 255

With a gamma (ditherImageWith), a value still takes the level nearest on stored values, while the error stays in light. Levels that aren't whole numbers are rounded first (evenRamp 3's 127.5 to 128), so that every level comes back exactly.

#evenRamp Source

evenRamp :: Int -> NonEmptyArray Number

Evenly spaced levels from 0 to 255, both ends included, for nearestLevel.

  • Int: how many; 1 or less gives the single midpoint, 127.5.

evenRamp 2 == [0.0, 255.0], evenRamp 4 == [0.0, 85.0, 170.0, 255.0].