package matrix

  1. Overview
  2. Docs

Module Ansi.ColorSource

Colors.

Colors, as a terminal is told to show them.

A terminal is told a color in one of three ways, each with its own SGR codes. It is told an RGB value (38;2;r;g;b), an entry of its palette (38;5;n), or its default color (39 or 49). A color of this module records which, its intent (intent), so that SGR output names the color the program chose. It also records an RGBA value, its snapshot. The RGB of the snapshot is what this module assumes the color looks like, and its alpha weights the color when it is blended over another, by source-over compositing (blend). Blending and comparing work on snapshots, and SGR output works on intents.

The snapshot of a palette entry is the RGB the section Color depth gives it. The snapshot of the default foreground is white and that of the default background black. The colors a terminal shows for them, and for its entries, are its palette (Palette). A color whose alpha is 0 is transparent, and SGR writes a transparent RGB color as the default color.

Constructors clamp out-of-range components and do not raise, except of_hex_exn.

This blends a translucent red over the default background. The result is an RGB color, half the red's intensity over black:

let c =
  Ansi.Color.blend
    ~src:(Ansi.Color.of_rgba 255 0 0 128)
    ~dst:Ansi.Color.default_bg
in
assert (Ansi.Color.to_sgr_codes ~bg:true c = [ 48; 2; 128; 0; 0 ])

Colors

Sourcetype t

The type for colors.

Sourcetype intent =
  1. | Default
    (*

    The terminal's default color, SGR 39 or 49.

    *)
  2. | Indexed of int
    (*

    Palette entry i, in [0;255], SGR 38;5;i or 48;5;i.

    *)
  3. | Rgb
    (*

    The snapshot's RGB, SGR 38;2;r;g;b or 48;2;r;g;b, or the default color when the color is transparent.

    *)

The type for intents.

Constructors

Sourceval default_fg : t

default_fg is the opaque default foreground, with a white snapshot.

Sourceval default_bg : t

default_bg is the opaque default background, with a black snapshot.

Sourceval transparent : t

transparent is the transparent RGB color with a black snapshot. Blending it over a color leaves that color unchanged.

Palette colors

black to white are palette entries 0 to 7, and bright_black to bright_white entries 8 to 15, as indexed gives them.

Sourceval black : t
Sourceval red : t
Sourceval green : t
Sourceval yellow : t
Sourceval blue : t
Sourceval magenta : t
Sourceval cyan : t
Sourceval white : t
Sourceval bright_black : t
Sourceval bright_red : t
Sourceval bright_green : t
Sourceval bright_yellow : t
Sourceval bright_blue : t
Sourceval bright_magenta : t
Sourceval bright_cyan : t
Sourceval bright_white : t

Other colors

Sourceval of_rgb : int -> int -> int -> t

of_rgb r g b is the opaque RGB color (r, g, b), each component clamped to [0;255].

Sourceval of_rgba : int -> int -> int -> int -> t

of_rgba r g b a is the RGB color (r, g, b) with alpha a, each component clamped to [0;255].

Sourceval of_rgba_f : float -> float -> float -> float -> t

of_rgba_f r g b a is of_rgba of the components clamped to [0.0;1.0], scaled to [0;255] and rounded. For every color c, of_rgba_f of the components of to_rgba_f c has c's snapshot.

Sourceval indexed : int -> t

indexed i is palette entry i, clamped to [0;255], with the snapshot Color depth gives it.

Sourceval of_palette_index : int -> t

of_palette_index is indexed.

Sourceval grayscale : level:int -> t

grayscale ~level is palette entry 232 + level, the gray of level level, clamped to [0;23], from darkest to lightest.

Sourceval of_hsl : h:float -> s:float -> l:float -> ?a:float -> unit -> t

of_hsl ~h ~s ~l ?a () is the RGB color of hue h in degrees, saturation s and lightness l, with alpha a. h is taken modulo 360, and s, l and a are clamped to [0.0;1.0]. a defaults to 1.0.

Sourceval of_hex : string -> t option

of_hex s is the RGB color written in s as RGB, RGBA, RRGGBB or RRGGBBAA in hexadecimal digits, optionally after a '#', and None if s has another form. A digit of the short forms stands for two equal digits, and a form without alpha is opaque.

Sourceval of_hex_exn : string -> t

of_hex_exn s is like of_hex.

Raises Invalid_argument if s is none of the forms of_hex reads.

Predicates and comparisons

Sourceval equal : t -> t -> bool

equal a b is true iff a and b have the same intent and the same snapshot.

Sourceval equal_rgba : t -> t -> bool

equal_rgba a b is true iff a and b have the same snapshot, whatever their intents.

Sourceval compare : t -> t -> int

compare a b is a total order on colors, compatible with equal.

Sourceval hash : t -> int

hash c is a hash of c, compatible with equal.

Properties

Sourceval intent : t -> intent

intent c is c's intent.

Sourceval alpha : t -> float

alpha c is c's alpha, in [0.0;1.0].

Sourceval to_rgb : t -> int * int * int

to_rgb c is the RGB of c's snapshot.

Sourceval to_rgba : t -> int * int * int * int

to_rgba c is c's snapshot.

Sourceval to_rgba_f : t -> float * float * float * float

to_rgba_f c is c's snapshot with each component in [0.0;1.0].

Sourceval with_rgba_f : t -> (float -> float -> float -> float -> 'a) -> 'a

with_rgba_f c f is f r g b a, where (r, g, b, a) is to_rgba_f c. It builds no tuple.

Sourceval to_hsl : t -> float * float * float * float

to_hsl c is (h, s, l, a), the hue in [0.0;360.0\), the saturation and the lightness in [0.0;1.0] of c's snapshot, and its alpha.

Operations

Sourceval blend : src:t -> dst:t -> t

blend ~src ~dst is src composited over dst by source-over blending of their snapshots. It is dst if src is transparent and src if src is opaque, intents included. Otherwise it is an RGB color whose alpha combines the two.

Sourceval invert : t -> t

invert c is the opaque RGB color whose components are 255 - v for each component v of the RGB of c's snapshot.

Sourceval contrast : t -> t -> float

contrast a b is the contrast ratio of the RGB of a's and b's snapshots, from 1.0 for two equal colors to 21.0 for black and white. It is WCAG 2's ratio, (l1 + 0.05) / (l2 + 0.05), where l1 is the higher relative luminance of the two and l2 the lower, and it is symmetric. WCAG asks at least 4.5 of text against its background and 3.0 of a graphical object. Alpha and intent are ignored, so a palette entry or a default color is judged by the RGB this module assumes for it (Color depth). Palette.contrast judges colors as a terminal of a known palette shows them.

Color depth

A terminal shows colors at one of a few depths. With direct color it shows any RGB value (38;2). With 256 colors it shows the entries of xterm's palette (38;5). Entries 0 to 15 are the 16 colors below, 16 to 231 a 6×6×6 cube whose levels in each channel are 0, 95, 135, 175, 215 and 255, and 232 to 255 a ramp of grays from 8 to 238 by steps of 10, which leaves out black and white. With 16 colors it shows entries 0 to 15 (30..37, 90..97), with 8 colors entries 0 to 7, and a monochrome terminal shows only its default colors.

Entries 16 to 255 are the same in every terminal that has them. Entries 0 to 15 vary, since xterm takes them from its resources and users and themes set them, so a program cannot know them. indexed gives them the 16 colors of HTML 4.01 (maroon #800000, green #008000, ..., silver #c0c0c0, gray #808080, red #ff0000, ..., white #ffffff), which this module uses wherever it needs their RGB.

Sourcetype depth = [
  1. | `Truecolor
  2. | `Ansi256
  3. | `Ansi16
  4. | `Ansi8
  5. | `Mono
]

The type for color depths, which are direct color, 256, 16 and 8 colors, and only the default colors.

Sourceval to_depth : depth -> t -> t

to_depth d c is c as a terminal of depth d can show it:

  • A Default color is unchanged at every depth, and so is every color at `Truecolor.
  • At `Mono every color becomes the default color with c's snapshot.
  • At `Ansi256, `Ansi16 and `Ansi8, a color already Indexed within the depth, or with alpha 0, is unchanged. Any other color becomes the palette entry nearest to the RGB of its snapshot, one of 16 to 255 at `Ansi256, one of 0 to 15 at `Ansi16 and one of 0 to 7 at `Ansi8. It keeps c's alpha.

Nearest is by the squared Euclidean distance between RGB values, a tie going to the higher entry. xterm shows a direct color this way when it is built without direct-color support: "it uses the closest match in its palette for the given RGB" (ctlseqs, SGR 38). At `Ansi256 the search leaves out entries 0 to 15, whose colors the user sets, so the result shows the color it was chosen for. At `Ansi16 and `Ansi8 those are the only entries, and the result is nearest by the colors indexed assumes.

to_depth reads no environment. The caller gives the depth, from what the terminal reports.

SGR codes

Sourceval to_sgr_codes : ?depth:depth -> bg:bool -> t -> int list

to_sgr_codes ~depth ~bg c is the SGR codes of to_depth depth c's intent (intent), for the foreground, or for the background if bg is true. At `Ansi16 and `Ansi8 a palette entry i is written as 30 + i when i < 8 and as 82 + i otherwise, or 40 + i and 92 + i for the background, and at the other depths as 38;5;i or 48;5;i. depth defaults to `Truecolor.

Sourceval emit_sgr_codes : ?depth:depth -> bg:bool -> (int -> unit) -> t -> unit

emit_sgr_codes ~depth ~bg push c calls push on each code of to_sgr_codes ~depth ~bg c, in order, and builds no list.

Packed colors

Sourcemodule Packed : sig ... end

Colors as immediate integers, for code that stores many colors, such as the planes of a grid.

Converting

Sourceval to_hex : t -> string

to_hex c is "#rrggbb", the RGB of c's snapshot in lowercase hexadecimal digits.

Formatting

Sourceval pp : Format.formatter -> t -> unit

pp ppf c formats c for inspection, such as Red, Indexed(42), Rgb(1,2,3), Rgba(1,2,3,4) or Default.