add types

Author: sabine

.gitattributes

@@ -0,0 +1,2 @@
+*.ml linguist-language=OCaml
+*.mli linguist-language=OCaml

.ocamlformat

@@ -0,0 +1 @@
+version = 0.26.1

CHANGES.md

@@ -0,0 +1,11 @@
+# 0.1.0
+
+First release.
+
+Provides:
+- record types for the different color spaces (HSLuv, HPLuv, RGB, XYZ, LCH, LUV)
+- HSLuv and HPLuv color conversion functions
+- color conversion functions between some of the other color spaces used to enable the HSLuv and HPluv conversions
+- pretty printers for all provided color types
+- a library `hsluv.float_conv` for conversions between float triples and the provided color types
+- tests against the HSLuv reference (revision 4)

README.md

@@ -18,17 +18,32 @@ The HSLuv color space is particularly beneficial in scenarios where perceptual u
 
 4. **Digital Art and Image Processing**: Offers fine-tuning of colors for subtle and precise adjustments.
 
-5. **Color Grading in Film and Photography**: Facilitates harmonious color transitions and adjustments.
-
 In summary, HSLuv's appeal lies in its ability to provide visually consistent and natural-looking colors, making it suitable for design, data visualization, and artistic applications.
 
-## Implementation 
+## Implementation Notes
+
+This started as a port of the [Go implementation of hsluv.org](https://github.com/hsluv/hsluv-go).
+
+The following color conversions are provided:
+
+| From/To      | HSLuv            | HPLuv            | RGB                 | XYZ                 | LUV                 | LCH                 | HEX                 |
+|--------------|------------------|------------------|---------------------|---------------------|---------------------|---------------------|---------------------|
+| **HSLuv**    | -                | -                | `hsluv_to_rgb`      | -                   | -                   | `conv_hsluv_lch`    | `hsluv_to_hex`      |
+| **HPLuv**    | -                | -                | `hpluv_to_rgb`      | -                   | -                   | `conv_hpluv_lch`    | `hpluv_to_hex`      |
+| **RGB**      | `hsluv_from_rgb` | `hpluv_from_rgb` | -                   | `conv_rgb_xyz`      | -                   | `conv_rgb_lch`      | `conv_rgb_hex`      |
+| **XYZ**      | -                | -                | `conv_xyz_rgb`      | -                   | `conv_xyz_luv`      | -                   | -                   |
+| **LUV**      | -                | -                | -                   | `conv_luv_xyz`      | -                   | `conv_luv_lch`      | -                   |
+| **LCH**      | `conv_lch_hsluv` | `conv_lch_hpluv` | `conv_lch_rgb`      | -                   | `conv_luv_lch`      | -                   | -                   |
+| **HEX**      | `hsluv_from_hex` | `hpluv_from_hex` | `conv_hex_rgb`      | -                   | -                   | -                   | -                   |
 
-This is a mostly faithful port of the Go implementation of hsluv.org at https://github.com/hsluv/hsluv-go.
+In addition to the HSLuv and HPLuv conversion functions, this package also exposes
+- color conversion functions between the various color spaces used to enable the HSLuv and HPluv conversions
+- pretty printers `pp_hsluv`, `pp_hpluv`, etc.
+- a library `hsluv.float_conv` for conversions between float triples and the provided color types
 
 ## Tests
 
-The implementation is tested against the [hsluv snapshot (revision 4)](https://raw.githubusercontent.com/hsluv/hsluv/master/snapshots/snapshot-rev4.json). Test cases are included and can be run with
+The implementation is tested against the [hsluv snapshot (revision 4)](https://raw.githubusercontent.com/hsluv/hsluv/master/snapshots/snapshot-rev4.json). Tests for all conversion functions are included and can be run with
 
 ```
 opam exec -- dune test

doc/dune

@@ -0,0 +1,2 @@
+(documentation
+ (package hsluv))

doc/index.mld

@@ -0,0 +1,21 @@
+{0 HSLuv}
+
+HSLuv is a color space designed to provide a more human-friendly and uniform representation of colors, compared to traditional color spaces like RGB or HSL.
+
+The key feature of HSLuv is its ability to maintain perceived color brightness and contrast uniformly across its hue and saturation range.
+
+HSLuv is particularly useful in applications where color consistency and perceptual uniformity are important, such as in graphical design, data visualization, and user interface development.
+
+You can find more information about HSLuv on {{: https://www.hsluv.org/}the official HSLuv website}.
+
+{1 Libraries}
+
+{2 hsluv}
+
+Module:
+- {!Hsluv} - HSLuv and HPLuv color models as well as other common color spaces like RGB and XYZ, modeled as record types; provides conversion functions between the different color spaces and pretty-printers for all the color types.
+
+{2 hsluv.float_conv}
+
+Module:
+- {!Hsluv_float_conv} - convert between the record types of the different color spaces defined in {!Hsluv} and float triple representations

dune-project

@@ -2,9 +2,10 @@
 
 (name hsluv)
 
-(documentation "https://ocaml.org/p/hsluv/latest")
+(version 0.1.0)
 
 (source (github sabine/hsluv-ocaml))
+(homepage "https://github.com/sabine/hsluv-ocaml")
 
 (license MIT)
 
@@ -19,7 +20,12 @@
 (package
  (name hsluv)
  (synopsis "HSLuv human-friendly color space implementation in OCaml")
- (description "This package implements the HSLuv color space model, providing a perceptually uniform alternative to traditional HSL. It includes functions for converting between HSLuv/HPLuv and other color spaces like RGB, XYZ, and Luv.")
+ (description "This package implements the HSLuv color space model,
+providing a perceptually uniform alternative to traditional HSL.
+It includes functions for converting between HSLuv/HPLuv
+and other color spaces like RGB, XYZ, LCH, and LUV, as well as hexadecimal
+color representation.")
+ (tags ("color" "hsluv" "hpluv" "rgb" "xyz" "lch" "luv" "color space" "color conversion" "perceptually uniform colors"))
  (depends 
  (ocaml (>= 4.08.0))
  dune

hsluv.opam

@@ -1,13 +1,29 @@
 # This file is generated by dune, edit dune-project instead
 opam-version: "2.0"
+version: "0.1.0"
 synopsis: "HSLuv human-friendly color space implementation in OCaml"
-description:
-  "This package implements the HSLuv color space model, providing a perceptually uniform alternative to traditional HSL. It includes functions for converting between HSLuv/HPLuv and other color spaces like RGB, XYZ, and Luv."
+description: """
+This package implements the HSLuv color space model,
+providing a perceptually uniform alternative to traditional HSL.
+It includes functions for converting between HSLuv/HPLuv
+and other color spaces like RGB, XYZ, LCH, and LUV, as well as hexadecimal
+color representation."""
 maintainer: ["Sabine Schmaltz"]
 authors: ["Sabine Schmaltz"]
 license: "MIT"
+tags: [
+  "color"
+  "hsluv"
+  "hpluv"
+  "rgb"
+  "xyz"
+  "lch"
+  "luv"
+  "color space"
+  "color conversion"
+  "perceptually uniform colors"
+]
 homepage: "https://github.com/sabine/hsluv-ocaml"
-doc: "https://ocaml.org/p/hsluv/latest"
 bug-reports: "https://github.com/sabine/hsluv-ocaml/issues"
 depends: [
   "ocaml" {>= "4.08.0"}

lib/dune hsluv/dunelib/dune renamed to hsluv/dune

@@ -1,5 +1,7 @@
 (* Ported from https://github.com/hsluv/hsluv-go/blob/cff9eb7ee0694105b0250075bb56243b1651165e/hsluv.go *)
 
+include Types
+
 (* Constants *)
 let pi = Float.pi
 
@@ -103,18 +105,18 @@ let l_to_y l = if l <= 8.0 then l /. kappa else ((l +. 16.0) /. 116.0) ** 3.0
 
 (* Conversions *)
 
-let conv_xyz_luv (x, y, z) =
-  if y = 0.0 then (0.0, 0.0, 0.0)
+let conv_xyz_luv { x; y; z } =
+  if y = 0.0 then { l = 0.0; u = 0.0; v = 0.0 }
   else
     let l = y_to_l y in
     let var_u = 4.0 *. x /. (x +. (15.0 *. y) +. (3.0 *. z)) in
     let var_v = 9.0 *. y /. (x +. (15.0 *. y) +. (3.0 *. z)) in
     let u = 13.0 *. l *. (var_u -. ref_u) in
     let v = 13.0 *. l *. (var_v -. ref_v) in
-    (l, u, v)
+    { l; u; v }
 
-let conv_luv_xyz (l, u, v) =
-  if l = 0.0 then (0.0, 0.0, 0.0)
+let conv_luv_xyz { l; u; v } =
+  if l = 0.0 then { x = 0.0; y = 0.0; z = 0.0 }
   else
     let var_u = (u /. (13.0 *. l)) +. ref_u in
     let var_v = (v /. (13.0 *. l)) +. ref_v in
@@ -125,48 +127,48 @@ let conv_luv_xyz (l, u, v) =
     let z =
       ((9.0 *. y) -. (15.0 *. var_v *. y) -. (var_v *. x)) /. (3.0 *. var_v)
     in
-    (x, y, z)
+    { x; y; z }
 
-let conv_luv_lch (l, u, v) =
+let conv_luv_lch { l; u; v } =
   let c = sqrt ((u ** 2.0) +. (v ** 2.0)) in
   let h_rad = atan2 v u in
   let h =
     if c < 0.00000001 then 0.0
     else mod_float (h_rad *. 360.0 /. (2.0 *. pi)) 360.0
   in
-  (l, c, h)
+  { l; c; h }
 
-let conv_lch_luv (l, c, h) =
+let conv_lch_luv { l; c; h } =
   let h_rad = h /. 360.0 *. 2.0 *. pi in
   let u = cos h_rad *. c in
   let v = sin h_rad *. c in
-  (l, u, v)
+  { l; u; v }
 
-let conv_hsluv_lch (h, s, l) =
-  if l > 99.9999999 || l < 0.00000001 then (l, 0., h)
+let conv_hsluv_lch { h; s; l } =
+  if l > 99.9999999 || l < 0.00000001 then { l; c = 0.; h }
   else
     let max = max_chroma_for_lh l h in
-    (l, max /. 100.0 *. s, h)
+    { l; c = max /. 100.0 *. s; h }
 
-let conv_lch_hsluv (l, c, h) =
-  if l > 99.9999999 || l < 0.00000001 then (h, 0., l)
+let conv_lch_hsluv { l; c; h } =
+  if l > 99.9999999 || l < 0.00000001 then { h; s = 0.; l }
   else
     let max = max_chroma_for_lh l h in
-    (h, c /. max *. 100.0, l)
+    { h; s = c /. max *. 100.0; l }
 
-let conv_hpluv_lch (h, s, l) =
-  if l > 99.9999999 || l < 0.00000001 then (l, 0., h)
+let conv_hpluv_lch { h; p; l } =
+  if l > 99.9999999 || l < 0.00000001 then { l; c = 0.; h }
   else
     let max = max_safe_chroma_for_l l in
-    (l, max /. 100. *. s, h)
+    { l; c = max /. 100. *. p; h }
 
-let conv_lch_hpluv (l, c, h) =
-  if l > 99.9999999 || l < 0.00000001 then (h, 0., l)
+let conv_lch_hpluv { l; c; h } =
+  if l > 99.9999999 || l < 0.00000001 then { h; p = 0.; l }
   else
     let max = max_safe_chroma_for_l l in
-    (h, c /. max *. 100.0, l)
+    { h; p = c /. max *. 100.0; l }
 
-let conv_rgb_hex (r, g, b) =
+let conv_rgb_hex { r; g; b } =
   let rV = round (max 0.0 (min r 1.0) *. 255.0) in
   let gV = round (max 0.0 (min g 1.0) *. 255.0) in
   let bV = round (max 0.0 (min b 1.0) *. 255.0) in
@@ -181,49 +183,57 @@ let conv_hex_rgb hex =
   let rV = int_of_string ("0x" ^ String.sub hex 0 2) in
   let gV = int_of_string ("0x" ^ String.sub hex 2 2) in
   let bV = int_of_string ("0x" ^ String.sub hex 4 2) in
-  (float_of_int rV /. 255.0, float_of_int gV /. 255.0, float_of_int bV /. 255.0)
+  {
+    r = float_of_int rV /. 255.0;
+    g = float_of_int gV /. 255.0;
+    b = float_of_int bV /. 255.0;
+  }
 
-let conv_xyz_rgb (x, y, z) =
+let conv_xyz_rgb { x; y; z } =
   let r = from_linear (dot_product m.(0) [| x; y; z |]) in
   let g = from_linear (dot_product m.(1) [| x; y; z |]) in
   let b = from_linear (dot_product m.(2) [| x; y; z |]) in
-  (r, g, b)
+  { r; g; b }
 
-let conv_rgb_xyz (r, g, b) =
+let conv_rgb_xyz { r; g; b } =
   let r = to_linear r in
   let g = to_linear g in
   let b = to_linear b in
   let x = dot_product m_inv.(0) [| r; g; b |] in
   let y = dot_product m_inv.(1) [| r; g; b |] in
   let z = dot_product m_inv.(2) [| r; g; b |] in
-  (x, y, z)
+  { x; y; z }
 
-let conv_lch_rgb (l, c, h) =
-  conv_lch_luv (l, c, h) |> conv_luv_xyz |> conv_xyz_rgb
+let conv_lch_rgb { l; c; h } =
+  conv_lch_luv { l; c; h } |> conv_luv_xyz |> conv_xyz_rgb
 
-let conv_rgb_lch (r, g, b) =
-  conv_rgb_xyz (r, g, b) |> conv_xyz_luv |> conv_luv_lch
+let conv_rgb_lch { r; g; b } =
+  conv_rgb_xyz { r; g; b } |> conv_xyz_luv |> conv_luv_lch
 
-let conv_hsluv_rgb (h, s, l) = conv_hsluv_lch (h, s, l) |> conv_lch_rgb
-let conv_rgb_hsluv (r, g, b) = conv_rgb_lch (r, g, b) |> conv_lch_hsluv
+let conv_hsluv_rgb { h; s; l } = conv_hsluv_lch { h; s; l } |> conv_lch_rgb
+let conv_rgb_hsluv { r; g; b } = conv_rgb_lch { r; g; b } |> conv_lch_hsluv
 
 (* Hsluv and Hpluv *)
 
-let hsluv_to_hex (h, s, l) = conv_hsluv_rgb (h, s, l) |> conv_rgb_hex
+let hsluv_to_hex { h; s; l } = conv_hsluv_rgb { h; s; l } |> conv_rgb_hex
 let hsluv_from_hex hex = conv_hex_rgb hex |> conv_rgb_hsluv
 let hsluv_to_rgb = conv_hsluv_rgb
 let hsluv_from_rgb = conv_rgb_hsluv
 
-let hpluv_to_hex (h, s, l) =
-  (h, s, l) |> conv_hpluv_lch |> conv_lch_luv |> conv_luv_xyz |> conv_xyz_rgb
+let hpluv_to_hex { h; p; l } =
+  { h; p; l } |> conv_hpluv_lch |> conv_lch_luv |> conv_luv_xyz |> conv_xyz_rgb
   |> conv_rgb_hex
 
 let hpluv_from_hex hex =
   hex |> conv_hex_rgb |> conv_rgb_xyz |> conv_xyz_luv |> conv_luv_lch
   |> conv_lch_hpluv
 
-let hpluv_to_rgb (h, s, l) =
-  (h, s, l) |> conv_hpluv_lch |> conv_lch_luv |> conv_luv_xyz |> conv_xyz_rgb
+let hpluv_to_rgb { h; p; l } =
+  { h; p; l } |> conv_hpluv_lch |> conv_lch_luv |> conv_luv_xyz |> conv_xyz_rgb
+
+let hpluv_from_rgb { r; g; b } =
+  { r; g; b } |> conv_rgb_xyz |> conv_xyz_luv |> conv_luv_lch |> conv_lch_hpluv
+
+(* Pretty-printers *)
 
-let hpluv_from_rgb (r, g, b) =
-  (r, g, b) |> conv_rgb_xyz |> conv_xyz_luv |> conv_luv_lch |> conv_lch_hpluv
+include Pretty_printers