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 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.
#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.
#quantizeInLight Source
quantizeInLight :: forall a. (Gamma -> Context -> a -> a) -> Quantize aA 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 -> 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.
#runQuantizeWith Source
runQuantizeWith :: forall a. ColorChannels a => Gamma -> Quantize a -> Context -> a -> aRuns 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 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
#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.
#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.
#evenRamp Source
evenRamp :: Int -> NonEmptyArray NumberEvenly 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 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.
- 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