Module

Puregrain.Quantize

Package
purescript-puregrain
Repository
roman-mkh/puregrain

Quantizers: the step of dithering that picks an output value for each pixel. A Quantize a gets the pixel's value, with the error diffused into it already added, and the pixel's position; ditherImage diffuses the difference between the two to the neighbours.

Ready-made: threshold (1-bit), nearestLevel with evenRamp (a few levels), and perChannel to use either on every channel of a color pixel. Palettes are in Puregrain.Palette, ordered (Bayer) dithering in Puregrain.Ordered. Build your own with quantize (position-blind) or quantizeWith (uses the position), or with quantizeInLight, which decides in light when the dithering has a gamma (Puregrain.Dither.ditherImageWith).

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

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

#quantizeInLight Source

quantizeInLight :: forall a. (Gamma -> Context -> a -> a) -> Quantize a

A quantizer that works in light, the way the ready-made ones are built.

  • Gamma -> Context -> a -> a: given the dithering's curve, prepares what it needs, then returns the function for each pixel, which gets the pixel's position and its corrected value in light, and returns the output in light.

The curve is gammaOff for ditherImage, where light and stored values are the same numbers, and the one given to ditherImageWith. Convert your own numbers with Puregrain.Gamma.toLight in a let outside the function for each pixel: there they're converted once per image, inside it once per pixel, since PureScript shares nothing by itself. An output that's the light of a whole number from 0 to 255 is written as exactly that number.

-- three tones: black, a mid gray, and white
threeTones = quantizeInLight \gamma ->
  let lo = toLight gamma 64.0
      hi = toLight gamma 192.0
      gray = toLight gamma 128.0
  in \_ v -> if v < lo then 0.0 else if v < hi then gray else 255.0

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

#runQuantizeWith Source

runQuantizeWith :: forall a. ColorChannels a => Gamma -> Quantize a -> Context -> a -> a

Runs a quantizer as ditherImageWith does with a gamma, for a stored value.

  • Gamma: the curve.
  • Quantize a: the quantizer.
  • Context: the pixel's position.
  • a: the corrected value, as stored.

Returns the output value, as stored: the value is taken to light, the quantizer decides there, and its output comes back. With gammaOff, the same as runQuantize. As with runQuantize, keep runQuantizeWith gamma quantizer for many pixels.

#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

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

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

Re-exports from Puregrain.Internal.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 }.