Merge pull request #14 from lehins/example

Add an example to the README file

.github/workflows/haskell.yml

@@ -16,7 +16,8 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        resolver: [nightly, lts-18, lts-16, lts-14, lts-12]
+        # resolver: [nightly -- disabled for now, some issue with installing ghc
+        resolver: [lts-20, lts-19, lts-18, lts-16, lts-14, lts-12]
         include:
           - resolver: lts-12
             ghc: 8.4.4
@@ -30,9 +31,17 @@ jobs:
           # Latest stable for MacOS: ghc-8.8.4
           - resolver: lts-16
             os: macos-latest
+          - resolver: lts-19
+            os: macos-latest
+          - resolver: lts-20
+            os: macos-latest
           # Latest stable for Windows: ghc-8.6.4
           - resolver: lts-14
             os: windows-latest
+          - resolver: lts-19
+            os: windows-latest
+          - resolver: lts-20
+            os: windows-latest
 
     env:
       STACK_YAML: stack.yaml

Color/README.md

@@ -72,6 +72,73 @@ Currently supported:
   * RAL
   * SVG
 
+## Example
+
+Here is a short example how this library can be used. Here we assume a GHCi session that
+can be started like so:
+
+```shell
+$ stack ghci --package Color
+```
+
+### Perceived lightness
+
+Let's say we need find the perceived lightness as described in [this StackOverflow
+answer](https://stackoverflow.com/questions/596216/formula-to-determine-perceived-brightness-of-rgb-color/56678483#56678483)
+for an RGB triple `(128, 255, 65) :: (Word8, Word8, Word8)`.
+
+Before we can attempt getting the lightness we need to do these two things:
+
+1. Figure out what is the color space of the `RGB` triplet? In particular the `Illuminant`
+   and the `Linearity` of the `RGB` color space.
+2. Convert your `RGB` color to [`CIE
+   L*a*b*`](https://en.wikipedia.org/wiki/CIELAB_color_space) and then we can get the `L*`
+   out, which is the perceived lightness.
+
+More often than not an RGB image will be encoded in non-linear sRGB color space with 8 bits
+per channel, so we'll use that for this example:
+
+```haskell
+ghci> :set -XDataKinds
+ghci> import Graphics.Color.Space
+ghci> let rgb8 = ColorSRGB 128 255 65 :: Color (SRGB 'NonLinear) Word8
+ghci> print rgb8
+<SRGB 'NonLinear:(128,255, 65)>
+```
+
+Before we convert `sRGB` to `CIE L*a*b*` color space we need to increase the precision to
+`Double`, because for now `Word8` is not supported by the `LAB` color space implementation:
+
+```haskell
+ghci> let rgb = toDouble <$> rgb8
+ghci> print rgb
+<SRGB 'NonLinear:( 0.5019607843137255, 1.0000000000000000, 0.2549019607843137)>
+```
+
+In order to convert to another color space without changing the `Illuminant` we can use
+`convertColor` function. So here is how we convert to CIELAB and extract the perceived
+lightness `L*`:
+
+```haskell
+ghci> let lab@(ColorLAB l _ _) = convertColor rgb :: Color (LAB D65) Double
+ghci> lab
+<LAB * D65:(90.0867507593648500,-65.7999116680496000,74.4643898323530600)>
+ghci> l
+90.08675075936485
+```
+
+### Color adaptation
+
+When a change of `Illuminant` is also needed during color space conversion we can use
+`convert` function
+
+```haskell
+ghci> import Graphics.Color.Adaptation (convert)
+ghci> import qualified Graphics.Color.Illuminant.CIE1964 as CIE1964
+ghci> let lab@(ColorLAB l _ _) = convert rgb :: Color (LAB 'CIE1964.D50) Double
+ghci> lab
+<LAB CIE1964 'D50:(90.2287735564601500,-59.3846969983265500,72.9304679742930800)>
+```
 
 ## External resources
 

Color/src/Graphics/Color/Space/DIN99.hs

@@ -22,10 +22,10 @@ where
 
 import Foreign.Storable
 import GHC.Generics (Generic)
-import Graphics.Color.Illuminant.Wikipedia as W
 import Graphics.Color.Model.Internal
 import Graphics.Color.Space.Internal
 import Graphics.Color.Space.CIE1976.LAB
+import Graphics.Color.Illuminant.Wikipedia as W
 
 data DIN99 (i :: k)
 
@@ -128,12 +128,14 @@ deltaE ::
   e
 deltaE a b = sqrt $ sum ((a - b) ** 2)
 
--- | Bidirectional @DIN99@ @DIN99@ conversion as implemented in
--- https://github.com/colour-science/colour/blob/c3735e5d0ad67443022ece0b42b575e040eb61d1/colour/models/din99.py#L79
--- >>> labToDIN DIN99Method (ColorLAB 41.52787529 52.63858304 26.92317922 :: Color (LAB 'W.D65) Double)
--- <DIN99 Degree2 'D65:(53.2282198832885240,28.4163465573069870, 3.8983955176918417)>
--- >>> dinToLAB DIN99Method (ColorDIN99 53.22821988 28.41634656 3.89839552 :: Color (DIN99 'W.D65) Double)
--- <LAB Degree2 'D65:(41.5278752867329700,52.6385830477006900,26.9231792301717970)>
+-- | Bidirectional @DIN99@ @DIN99@ conversion as implemented in Python
+-- [colour](https://github.com/colour-science/colour/blob/c3735e5d0ad67443022ece0b42b575e040eb61d1/colour/models/din99.py#L79) package.
+--
+-- >>> import Graphics.Color.Illuminant.Wikipedia as W
+-- >>> labToDIN DIN99Method (ColorLAB 41.527874 52.638584 26.92318 :: Color (LAB 'W.D65) Float)
+-- <DIN99 Degree2 'D65:(53.22821400,28.41634600, 3.89839500)>
+-- >>> dinToLAB DIN99Method (ColorDIN99 53.228218 28.416348 3.8983955 :: Color (DIN99 'W.D65) Float)
+-- <LAB Degree2 'D65:(41.52787800,52.63859000,26.92318300)>
 labToDIN ::
   (RealFloat e) =>
   DINMethod ->

stack.yaml

@@ -1,4 +1,4 @@
-resolver: lts-17.14
+resolver: lts-18.28
 packages:
 - Color
 extra-deps: []