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; andinitDitheringwithditherRow, one row at a time from any source;- the kernels
floydSteinberg,atkinson,jarvisJudiceNinke,stucki,burkes,sierra3,sierra2,sierraLite,fan,shiauFanandshiauFan2, andnoDiffusionfor none; - the quantizers
threshold,nearestLevelwithevenRamp, andperChannelfor color;nearestColorwith the palette presets;bayerandorderedfor ordered dithering; ditherImageWith,ditherRowsWithandinitDitheringWith, the same with a gamma curve,gammaOff,gamma1p2,gamma1p5,gamma1p8orgammaSrgb, which says how the stored numbers turn into light; andtoGray, a color's gray by that curve;- the pixel types
RGBandRGBA, 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 aAn 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 aThe state before the first row, for ditherRow, keeping the amount
of light the curve gives each value.
aandGamma: as forditherImageWith.KernelandQuantize a: as forinitDithering.
ditherRow then gives the same rows as ditherImageWith, each as
stored values.
#initDithering Source
initDithering :: forall a. Kernel -> Quantize a -> Dithering aThe state before the first row, for ditherRow.
Kernel: where each pixel's error goes;noDiffusionfor 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.
aandGamma: as forditherImageWith.Kernel,Quantize a,LL.List (Array a): as forditherRows.
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,KernelandQuantize a: as forditherImage.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, frominitDitheringor 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,RGBorRGBA; any type withRing,ScalableandColorChannelsworks.Gamma: how the stored numbers turn into light:gammaOff, the same asditherImage, orgamma1p2,gamma1p5,gamma1p8orgammaSrgb(linear light).Kernel,Quantize a,Array (Array a): as forditherImage.
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,Numberfor gray,RGBorRGBA; any type withRingandScalableworks.Kernel: where each pixel's error goes;noDiffusionfor 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 GammaA 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 -> NumberA 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)
Re-exports from Puregrain.Kernel
#sierraLite Source
sierraLite :: KernelSierra Lite (Frankie Sierra, 1989–1990; also "Filter Lite" or "Sierra-2-4A"): 3 neighbours, one fewer than Floyd–Steinberg, for similar results.
#noDiffusion Source
noDiffusion :: KernelNo 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 :: KernelJarvis–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 :: KernelFloyd–Steinberg (1976): 4 neighbours, the classic.
Re-exports from Puregrain.Ordered
#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.
#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.
#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)
Re-exports from Puregrain.Palette
#nearestColor Source
nearestColor :: NonEmptyArray RGB -> Quantize RGBA 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. fromPuregrain.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 RGBThe 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 RGBThe 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 RGBThe 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 RGBThe 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 RGBBlack, 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 RGBxterm'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 RGBThe 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
#RGB Source
newtype RGBA 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
#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
ColorChannels NumberA gray pixel is its one color channel.
ColorChannels RGBColorChannels RGBARed, green and blue; alpha stays as it is.
#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
MapChannels NumberA gray pixel is its one channel:
perChannelonNumberis the quantizer itself.MapChannels RGBMapChannels RGBAAlpha too, like the other channels, as in the
RingandScalableinstances.
Re-exports from Puregrain.Quantize
#Quantize Source
newtype Quantize aA 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.
#threshold Source
threshold :: Number -> Quantize NumberThe 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 -> aRuns 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 aA 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 aA 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 aRuns a one-channel quantizer on every channel of a pixel, independently, each with the pixel's position.
a: the pixel type, withMapChannels:Number,RGBorRGBA.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 NumberSnaps 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.
- 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
Alpha too, like the other channels, as in the
RingandScalableinstances.