monobiome 1.4.0__py3-none-any.whl → 1.5.1__py3-none-any.whl

monobiome/__main__.py

@@ -10,7 +10,7 @@ def main() -> None:
         configure_logging(args.log_level)
 
     if "func" in args:
-        args.func(args)
+        args.func(args, parser)
     else:
         parser.print_help()
 

monobiome/cli/__init__.py

@@ -1,7 +1,7 @@
 import logging
-import argparse
+from argparse import ArgumentParser
 
-from monobiome.cli import scheme, palette
+from monobiome.cli import fill, scheme, palette
 
 logger: logging.Logger = logging.getLogger(__name__)
 
@@ -12,8 +12,8 @@ def configure_logging(log_level: int) -> None:
 
     logger.setLevel(log_level)
 
-def create_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(
+def create_parser() -> ArgumentParser:
+    parser = ArgumentParser(
         description="Accent modeling CLI",
     )
     parser.add_argument(
@@ -26,7 +26,8 @@ def create_parser() -> argparse.ArgumentParser:
 
     subparsers = parser.add_subparsers(help="subcommand help")
 
-    palette.register_parser(subparsers)
+    fill.register_parser(subparsers)
     scheme.register_parser(subparsers)
+    palette.register_parser(subparsers)
 
     return parser

monobiome/cli/fill.py

@@ -0,0 +1,78 @@
+import sys
+import tomllib
+from pathlib import Path
+from argparse import Namespace, ArgumentParser
+
+from symconf.template import Template, TOMLTemplate
+
+from monobiome.util import _SubparserType
+from monobiome.palette import generate_palette
+
+
+def register_parser(subparsers: _SubparserType) -> None:
+    parser = subparsers.add_parser(
+        "fill",
+        help="fill scheme templates for applications"
+    )
+
+    parser.add_argument(
+        "scheme",
+        type=str,
+        help="scheme file path"
+    )
+    parser.add_argument(
+        "template",
+        nargs="?",
+        help="template file path (defaults to stdin)"
+    )
+    parser.add_argument(
+        "-p",
+        "--palette",
+        type=str,
+        help="palette file to use for color definitions",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=str,
+        help="output file to write filled template",
+    )
+
+    parser.set_defaults(func=handle_fill)
+
+
+def handle_fill(args: Namespace, parser: ArgumentParser) -> None:
+    scheme = Path(args.scheme)
+    output = args.output
+
+    if args.template is None:
+        if sys.stdin.isatty():
+            parser.error("no template provided (file or stdin)")
+            return
+        template_content = sys.stdin.read()
+    elif args.template == "-":
+        template_content = sys.stdin.read()
+    else:
+        try:
+            template_content = Path(args.template).read_text()
+        except OSError as e:
+            parser.error(f"cannot read template file: {e}")
+
+    if args.palette:
+        try:
+            palette_toml = Path(args.palette).read_text()
+        except OSError as e:
+            parser.error(f"cannot read palette file: {e}")
+            return
+    else:
+        palette_toml = generate_palette("hex", "toml")
+
+    palette_dict = tomllib.loads(palette_toml)
+    concrete_scheme = TOMLTemplate(scheme).fill_dict(palette_dict)
+    filled_template = Template(template_content).fill(concrete_scheme)
+
+    if output is None:
+        print(filled_template)
+    else:
+        with Path(output).open("w") as f:
+            f.write(filled_template)

monobiome/cli/palette.py

@@ -1,5 +1,5 @@
-import argparse
 from pathlib import Path
+from argparse import Namespace, ArgumentParser
 
 from monobiome.util import _SubparserType
 from monobiome.palette import generate_palette
@@ -17,7 +17,7 @@ def register_parser(subparsers: _SubparserType) -> None:
         type=str,
         default="hex",
         choices=["hex", "oklch"],
-        help="Color notation to export (either hex or oklch)",
+        help="color notation to export (either hex or oklch)",
     )
     parser.add_argument(
         "-f",
@@ -25,19 +25,19 @@ def register_parser(subparsers: _SubparserType) -> None:
         type=str,
         default="toml",
         choices=["json", "toml"],
-        help="Format of palette file (either JSON or TOML)",
+        help="format of palette file (either JSON or TOML)",
     )
     parser.add_argument(
         "-o",
         "--output",
         type=str,
-        help="Output file to write palette content",
+        help="output file to write palette content",
     )
 
     parser.set_defaults(func=handle_palette)
 
 
-def handle_palette(args: argparse.Namespace) -> None:
+def handle_palette(args: Namespace, parser: ArgumentParser) -> None:
     notation = args.notation
     file_format = args.format
     output = args.output

monobiome/cli/scheme.py

@@ -1,5 +1,5 @@
-import argparse
 from pathlib import Path
+from argparse import Namespace, ArgumentParser
 
 from monobiome.util import _SubparserType
 from monobiome.scheme import generate_scheme
@@ -16,13 +16,13 @@ def register_parser(subparsers: _SubparserType) -> None:
         "mode",
         type=str,
         choices=["dark", "light"],
-        help="Scheme mode (light or dark)"
+        help="scheme mode (light or dark)"
     )
     parser.add_argument(
         "biome",
         type=str,
         choices=list(monotone_h_map.keys()),
-        help="Biome setting for scheme."
+        help="biome setting for scheme"
     )
     parser.add_argument(
         "-m",
@@ -30,7 +30,7 @@ def register_parser(subparsers: _SubparserType) -> None:
         type=str,
         default="oklch",
         choices=["wcag", "oklch", "lightness"],
-        help="Metric to use for measuring swatch distances."
+        help="metric to use for measuring swatch distances"
     )
 
     # e.g., wcag=4.5; oklch=0.40; lightness=40
@@ -39,13 +39,13 @@ def register_parser(subparsers: _SubparserType) -> None:
         "--distance",
         type=float,
         default=0.40,
-        help="Distance threshold for specified metric",
+        help="distance threshold for specified metric",
     )
     parser.add_argument(
         "-o",
         "--output",
         type=str,
-        help="Output file to write scheme content",
+        help="output file to write scheme content",
     )
 
     # these params remain rooted in lightness; no need to accommodate metric
@@ -58,13 +58,13 @@ def register_parser(subparsers: _SubparserType) -> None:
         "--l-base",
         type=int,
         default=20,
-        help="Minimum lightness level (default: 20)",
+        help="minimum lightness level (default: 20)",
     )
     parser.add_argument(
         "--l-step",
         type=int,
         default=5,
-        help="Lightness step size (default: 5)",
+        help="lightness step size (default: 5)",
     )
 
     # gaps
@@ -72,25 +72,25 @@ def register_parser(subparsers: _SubparserType) -> None:
         "--fg-gap",
         type=int,
         default=50,
-        help="Foreground lightness gap (default: 50)",
+        help="foreground lightness gap (default: 50)",
     )
     parser.add_argument(
         "--grey-gap",
         type=int,
         default=30,
-        help="Grey lightness gap (default: 30)",
+        help="grey lightness gap (default: 30)",
     )
     parser.add_argument(
         "--term-fg-gap",
         type=int,
         default=65,
-        help="Terminal foreground lightness gap (default: 60)",
+        help="terminal foreground lightness gap (default: 60)",
     )
 
     parser.set_defaults(func=handle_scheme)
 
 
-def handle_scheme(args: argparse.Namespace) -> None:
+def handle_scheme(args: Namespace, parser: ArgumentParser) -> None:
     output = args.output
 
     mode = args.mode

monobiome/constants.py

@@ -121,3 +121,21 @@ for h_str, L_points_C in Lpoints_Cqbr_Hmap.items():
         max(0, min(_C, l_maxC_h(_L, _h)))
         for _L, _C in zip(L_points, L_points_C, strict=True)
     ]
+
+
+# strictly enforce curve bounds s.t. there are no intersections
+# order is determined by the max attained chromap
+max_Cstar_Horder = [
+    (h_str, max(Lpoints_Cstar))
+    for h_str, Lpoints_Cstar in Lpoints_Cstar_Hmap.items()
+]
+max_Cstar_Horder = sorted(max_Cstar_Horder, key=lambda t: t[1], reverse=True)
+
+for i in range(len(max_Cstar_Horder)-1):
+    outer_h, _ = max_Cstar_Horder[i]
+    inner_h, _ = max_Cstar_Horder[i+1]
+
+    Lpoints_Cstar_Hmap[inner_h] = [
+        min(inner_c, Lpoints_Cstar_Hmap[outer_h][ci])
+        for ci, inner_c in enumerate(Lpoints_Cstar_Hmap[inner_h])
+    ]

monobiome/curve.py

@@ -9,8 +9,8 @@ def quad_bezier_rational(
     P1: float,
     P2: float,
     w: float,
-    t: np.array,
-) -> np.array:
+    t: np.ndarray,
+) -> np.ndarray:
     """
     Compute the point values of a quadratic rational Bezier curve.
 
@@ -32,7 +32,7 @@ def bezier_y_at_x(
     w: float,
     x: float,
     n: int = 400,
-) -> np.array:
+) -> np.ndarray:
     """
     For the provided QBR parameters, provide the curve value at the given
     input.

monobiome/palette.py

@@ -1,4 +1,5 @@
 import json
+from typing import Any
 from functools import cache
 from importlib.metadata import version
 
@@ -12,7 +13,7 @@ from monobiome.constants import (
 
 
 @cache
-def compute_hlc_map(notation: str) -> dict[str, dict[int, str]]:
+def compute_hlc_map(notation: str) -> dict[str, Any]:
     hlc_map = {}
 
     for h_str, Lpoints_Cstar in Lpoints_Cstar_Hmap.items():
@@ -44,7 +45,7 @@ def generate_palette(
         hlc_map["version"] = mb_version
         return json.dumps(hlc_map, indent=4)
     else:
-        toml_lines = [f"version = {mb_version}", ""]
+        toml_lines = [f"version = \"{mb_version}\"", ""]
         for _h, _lc_map in hlc_map.items():
             toml_lines.append(f"[{_h}]")
             for _l, _c in _lc_map.items():

monobiome/plotting.py

@@ -1,6 +1,9 @@
+from importlib.metadata import version
+
 import numpy as np
 import matplotlib.pyplot as plt
 from coloraide import Color
+from matplotlib.collections import LineCollection
 
 from monobiome.palette import compute_hlc_map
 from monobiome.constants import (
@@ -10,11 +13,13 @@ from monobiome.constants import (
     accent_h_map,
     monotone_h_map,
     Lspace_Cmax_Hmap,
+    max_Cstar_Horder,
     Lpoints_Cstar_Hmap,
 )
 
+VERSION = version("monobiome")
 
-def plot_hue_chroma_bounds() -> None:
+def plot_hue_chroma_bounds() -> tuple[plt.Figure, plt.Axes]:
     name_h_map = {}
     ax_h_map = {}
     fig, axes = plt.subplots(
@@ -63,43 +68,54 @@ def plot_hue_chroma_bounds() -> None:
         ncol=3
     )
 
-    plt.suptitle("$C^*$ curves for hue groups")
-    plt.show()
+    plt.suptitle(f"$C^*$ curves for hue groups (v{VERSION})")
 
+    return fig, axes
 
-def plot_hue_chroma_star() -> None:
+def plot_hue_chroma_star() -> tuple[plt.Figure, plt.Axes]:
     fig, ax = plt.subplots(1, 1, figsize=(8, 6))
 
-    # uncomment to preview 5 core term colors
     colors = accent_h_map.keys()
-    #colors = set(["red", "orange", "yellow", "green", "blue"])
+    # uncomment to preview just the 5 core term colors
+    # colors = set(["red", "orange", "yellow", "green", "blue"])
+
+    for h_str, _ in max_Cstar_Horder:
+        Lpoints_Cstar = Lpoints_Cstar_Hmap[h_str]
 
-    for h_str in Lpoints_Cstar_Hmap:
         if h_str not in accent_h_map or h_str not in colors:
             continue
-        ax.fill_between(
-            L_points,
-            Lpoints_Cstar_Hmap[h_str],
-            alpha=0.2,
-            color='grey',
-            label=h_str
-        )
-
-        x, y = L_points, Lpoints_Cstar_Hmap[h_str]
-        n = int(0.45*len(x))
-        ax.text(x[n], y[n]-0.01, h_str, rotation=10, va='center', ha='left')
+
+        _h = h_map[h_str]
+        h_colors = [
+            Color('oklch', [_l/100, _c, _h]).convert("srgb")
+            for _l, _c in zip(L_points, Lpoints_Cstar, strict=True)
+        ]
+        
+        x = np.asarray(L_points)
+        y = np.asarray(Lpoints_Cstar)
+        pts = np.column_stack([x, y]).reshape(-1, 1, 2)
+        segs = np.concatenate([pts[:-1], pts[1:]], axis=1)
+        rgb = np.asarray(h_colors)
+        seg_colors = (rgb[:-1] + rgb[1:]) / 2
+        lc = LineCollection(segs, colors=seg_colors, linewidth=3,
+                            capstyle="round", joinstyle="round",
+                            label=h_str)
+
+        ax.add_collection(lc)
+        ax.autoscale_view()
         
     ax.set_xlabel("Lightness (%)")
     ax.set_xticks([L_points[0], 45, 50, 55, 60, 65, 70, L_points[-1]])
-    plt.suptitle("$C^*$ curves (v1.4.0)")
-    fig.show()
 
+    plt.suptitle(f"$C^*$ curves (v{VERSION})")
+
+    return fig, ax
 
 def palette_image(
     palette: dict[str, dict[int, str]],
     cell_size: int = 40,
     keys: list[str] | None = None
-) -> None:
+) -> tuple[np.ndarray, list[str], list[list[int]]]:
     names = list(palette.keys()) if keys is None else keys
         
     row_count = len(names)
@@ -114,41 +130,57 @@ def palette_image(
 
     for r, name in enumerate(names):
         shades = palette[name]
-        keys = sorted(shades.keys())
-        lightness_keys_per_row.append(keys)
-        for c, k in enumerate(keys):
+        lkeys = sorted(shades.keys())
+        lightness_keys_per_row.append(lkeys)
+        for c, k in enumerate(lkeys):
             col = Color(shades[k]).convert("srgb").fit(method="clip")
             rgb = [col["r"], col["g"], col["b"]]
             r0, r1 = r * cell_size, (r + 1) * cell_size
             c0, c1 = c * cell_size, (c + 1) * cell_size
             img[r0:r1, c0:c1, :] = rgb
 
-    return img, names, lightness_keys_per_row, cell_size, max_cols
-
+    return img, names, lightness_keys_per_row
 
 def show_palette(
     palette: dict[str, dict[int, str]],
     cell_size: int = 40,
-    keys: list[str] | None = None
-) -> None:
-    img, names, keys, cell_size, max_cols = palette_image(
-        palette, cell_size, keys=keys
-    )
+    keys: list[str] | None = None,
+    show_labels: bool = True,
+    dpi: int = 100,
+) -> tuple[plt.Figure, plt.Axes]:
+    img, names, _ = palette_image(palette, cell_size, keys=keys)
 
     fig_w = img.shape[1] / 100
     fig_h = img.shape[0] / 100
-    fig, ax = plt.subplots(figsize=(fig_w, fig_h))
 
-    ax.imshow(img, interpolation="none", origin="upper")
-    ax.set_xticks([])
+    if show_labels:
+        fig, ax = plt.subplots(figsize=(fig_w, fig_h), dpi=dpi)
 
-    ytick_pos = [(i + 0.5) * cell_size for i in range(len(names))]
-    ax.set_yticks(ytick_pos)
-    ax.set_yticklabels(names)
-    ax.set_ylim(img.shape[0], 0)   # ensures rows render w/o half-cells
+        ax.imshow(img, interpolation="none", origin="upper")
+        ax.set_xticks([])
 
-    plt.show()
+        ytick_pos = [(i + 0.5) * cell_size for i in range(len(names))]
+        ax.set_yticks(ytick_pos)
+        ax.set_yticklabels(names)
+        ax.set_ylim(img.shape[0], 0)  # ensures rows render w/o half-cells
+
+        return fig, ax
+
+    fig = plt.figure(figsize=(fig_w, fig_h), dpi=dpi, frameon=False)
+    ax = fig.add_axes((0, 0, 1, 1), frame_on=False)
+    ax.imshow(
+        img,
+        interpolation="nearest",
+        origin="upper",
+        extent=(0, img.shape[1], img.shape[0], 0),
+        aspect="auto",
+    )
+    ax.set_xlim(0, img.shape[1])
+    ax.set_ylim(img.shape[0], 0)
+    ax.axis("off")
+    fig.subplots_adjust(0, 0, 1, 1, hspace=0, wspace=0)
 
+    return fig, ax
 
 if __name__ == "__main__":
     keys = [

monobiome/scheme.py

@@ -1,5 +1,6 @@
 from functools import cache
 from collections.abc import Callable
+from importlib.metadata import version
 
 from coloraide import Color
 
@@ -88,7 +89,7 @@ def generate_scheme_groups(
     grey_gap: int,
     term_fg_gap: int,
     accent_color_map: dict[str, str],
-) -> tuple[dict[str, str], ...]:
+) -> tuple[list[tuple[str, str]], ...]:
     """
     Parameters:
         mode: one of ["dark", "light"]
@@ -125,15 +126,16 @@ def generate_scheme_groups(
     accent_colors = Lma_map.get(biome, {})
     
     meta_pairs = [
+        ("version", version("monobiome")),
         ("mode", mode),
         ("biome", biome),
         ("metric", metric),
-        ("distance", distance),
-        ("l_base", l_base),
-        ("l_step", l_step),
-        ("fg_gap", fg_gap),
-        ("grey_gap", grey_gap),
-        ("term_fg_gap", term_fg_gap),
+        ("distance", str(distance)),
+        ("l_base", str(l_base)),
+        ("l_step", str(l_step)),
+        ("fg_gap", str(fg_gap)),
+        ("grey_gap", str(grey_gap)),
+        ("term_fg_gap", str(term_fg_gap)),
     ]
 
     # note how selection_bg steps up by `l_step`, selection_fg steps down by
@@ -233,7 +235,11 @@ def generate_scheme(
             for lhs, rhs in pair_list
         ]
 
-    scheme_pairs = []
+    mb_version = version("monobiome")
+    scheme_pairs = [
+        "# ++ monobiome scheme file ++",
+        f"# ++ generated CLI @ {mb_version} ++",
+    ]
     scheme_pairs += pair_strings(meta)
     scheme_pairs += pair_strings(mt)
     scheme_pairs += pair_strings(ac)

monobiome-1.5.1.dist-info/METADATA

@@ -0,0 +1,344 @@
+Metadata-Version: 2.4
+Name: monobiome
+Version: 1.5.1
+Summary: Monobiome color palette
+Author-email: Sam Griesemer <git@olog.io>
+License-Expression: MIT
+Project-URL: Homepage, https://doc.olog.io/monobiome
+Project-URL: Documentation, https://doc.olog.io/monobiome
+Project-URL: Repository, https://git.olog.io/olog/monobiome
+Project-URL: Issues, https://git.olog.io/olog/monobiome/issues
+Keywords: tempate-engine,color-palette
+Classifier: Programming Language :: Python
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: coloraide>=5.1
+Requires-Dist: imageio[ffmpeg]>=2.37.2
+Requires-Dist: kaleido>=1.1.0
+Requires-Dist: matplotlib>=3.10.7
+Requires-Dist: nbformat>=5.10.4
+Requires-Dist: numpy>=2.3.4
+Requires-Dist: pillow>=12.0.0
+Requires-Dist: plotly>=6.3.1
+Requires-Dist: pyqt5>=5.15.11
+Requires-Dist: scipy>=1.16.2
+Requires-Dist: symconf>=0.8.4
+Provides-Extra: dev
+Requires-Dist: ipykernel; extra == "dev"
+Provides-Extra: doc
+Requires-Dist: furo; extra == "doc"
+Requires-Dist: myst-parser; extra == "doc"
+Requires-Dist: sphinx; extra == "doc"
+Requires-Dist: sphinx-togglebutton; extra == "doc"
+Requires-Dist: sphinx-autodoc-typehints; extra == "doc"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+
+# Monobiome
+`monobiome` is a minimal, balanced color palette for use in terminals and text
+editors. It was designed in OKLCH space to achieve perceptual uniformity across
+all hues at various levels of luminance, and does so for eight monotone bases
+and eight accent colors (plus one zero chroma default base). Each of the
+monotone base colors (named according to a natural biome whose colors they
+loosely resemble) are designed to achieve identical contrast with the accents,
+and thus any one of the options can be selected to change the feeling of
+downstream themes without sacrificing readability.
+
+![Theme preview](images/repo_preview_primary.png)
+_(Preview of light and dark alpine theme variants)_
+
+The name "monobiome" connects the palette to its two key sources of
+inspiration:
+
+- `mono-`: `monobiome` is inspired by the [`monoindustrial` theme][1], and
+  attempts to extend and balance its accents while retaining similar color
+  identities.
+- `-biome`: the desire for several distinct monotone options entailed finding a
+  way to ground the subtle color variations that were needed, and I liked the
+  idea of tying the choices to naturally occurring environmental variation like
+  Earth's biomes (even if it is a very loose affiliation, e.g., green-ish =
+  grass, basically).
+
+## Palette
+The `monobiome` palette is fundamentally a set of parameterized curves in OKLCH
+color space. Each color identity has one monotone curve and one accent curve,
+both of which have fixed hue values and vary from 10% to 98% lightness.
+Monotone curves have fixed chroma, whereas the accent curves' chroma varies
+smoothly as a function of lightness within sRGB gamut bounds.
+
+| Chroma curves                                            | Color trajectories                       |
+|----------------------------------------------------------|------------------------------------------|
+| ![Chroma curves](images/release/1.5.1/chroma-curves.png) | ![Trajectories](images/trajectories.gif) |
+
+| Palette                                      |
+|----------------------------------------------|
+| ![Palette](images/release/1.5.1/palette.png) |
+
+Chroma curves are designed specifically to establish a distinct role for each
+accent and are non-intersecting over the lightness domain (hence the distinct
+"bands" in the above chroma curve figure). There are eight monotone-accent
+pairs, plus a single grey trajectory:
+
+| Monotone / biome | Accent color | Hue  |
+| ---              | ---          | ---  |
+| alpine           | grey         | n/a  |
+| badlands         | red          | 29   |
+| chaparral        | orange       | 62.5 |
+| savanna          | yellow       | 104  |
+| grassland        | green        | 148  |
+| reef             | cyan         | 205  |
+| tundra           | blue         | 262  |
+| heathland        | violet       | 306  |
+| moorland         | magenta      | 350  |
+
+The `alpine`/`grey` curve has zero chroma (and is thus invariant to hue),
+varying only in lightness from dark to light grey.
+
+## Themes
+
+| Dark themes                            | Light themes                             |
+|----------------------------------------|------------------------------------------|
+| ![Dark themes](images/dark_themes.png) | ![Light themes](images/light_themes.png) |
+
+Themes are derived from the `monobiome` palette by selecting a monotone base
+(the "biome"), a base lightness, and a contrast level. Although one can use
+arbitrary contrast metrics, OKLCH distance (Euclidean distance in OKLab)
+is designed to capture perceptual distinction. As such, perceptually uniform
+themes under arbitrary monotones can be generated by calculating the accent
+colors equidistant from that base. This is equivalent to determining the points
+at which a sphere centered at the monotone base intersects with the accent
+curves; the radius of such a sphere effectively determines the theme contrast,
+and the colors on the sphere surface are equally perceptually distinct relative
+to the background. 
+
+The following plots show the intersection of the sphere centered at a fixed
+background color (`alpine` biome with a lightness of 20) under variable radii:
+
+|                     | `-l 20 -d 0.3`                                    | `-l 20 -d 0.4`                                    | `-l 20 -d 0.5`                                    |
+|---------------------|---------------------------------------------------|---------------------------------------------------|---------------------------------------------------|
+| Color visualization | ![](images/oklch/mb_b20_d30.gif)                  | ![](images/oklch/mb_b20_d40.gif)                  | ![](images/oklch/mb_b20_d50.gif)                  |
+| Editor preview      | ![](images/render/v140-demo-alpine-dark-d0.3.png) | ![](images/render/v140-demo-alpine-dark-d0.4.png) | ![](images/render/v140-demo-alpine-dark-d0.5.png) |
+
+In short, the base lightness (`-l`) dictates the brightness of the background,
+and the contrast (`-d`) controls how perceptually distinct the accent colors
+appear with respect to that background. These are free parameters of the
+`monobiome` model: themes can be generated under arbitrary settings that meet
+user preferences.
+
+## Generation
+When generating full application themes, fixed lightness steps are used in the
+chosen monotone trajectory to establish consistent levels of distinction
+between background layers. For example, the following demonstrates how
+background and foreground elements are chosen for the `monobiome` vim/neovim
+themes:
+
+![
+  Diagram depicting how themes colors are selected by harshness and mapped onto
+  application-specific elements
+](images/vim_theme_elements.png)
+
+Note how theme elements are mapped onto the general identifiers `bg0-bg3` for
+backgrounds, `fg0-fg3` for foregrounds, and `gray` for a central gray tone. The
+relative properties (lightness differences, contrast ratios) between colors
+assigned to these identifiers are preserved regardless of biome or harshness
+(e.g., `bg3` and `gray` are _always_ separated by 20 lightness points in any
+theme). As a result, applying `monobiome` themes to specific applications can
+effectively boil down to defining a single "relative template" that uses these
+identifiers, after which any user-provided parameters can be applied
+automatically. 
+
+The full palette $\rightarrow$ scheme $\rightarrow$ template $\rightarrow$
+theme pipeline can be seen in detail below: 
+
+![Generation pipeline](images/theme_generation_pipeline.png)
+
+This figure demonstrates how `kitty` themes are generated, but the process is
+generic to any palette, scheme, and app. This is implemented in two stages
+using the `monobiome` CLI:
+
+- First generate the scheme file, the lightness choices that achieve perceptual
+  uniformity of accents with respect to the base monotone:
+
+  ```sh
+  monobiome scheme dark grassland -d 0.42 -l 20 -o scheme.toml
+  ```
+
+  This calculates the accents a distance of `0.42` units in Oklab space from the
+  `grassland` monotone base at a lightness of `20`, and writes the output to
+  `scheme.toml`.
+- Then populate the scheme file with concrete palette colors and push it
+  through an app config template:
+
+  ```sh
+  monobiome fill scheme.toml templates/kitty/active.theme -o kitty.theme
+  ```
+
+  This writes a concrete `kitty` theme to `kitty.theme` that matches the user
+  preferences as captured in the previously generated scheme file, i.e., the
+  contrast (`-d`), background lightness (`-l`), mode (`dark`), and biome
+  (`grassland`). Every part of this process can be customized: the scheme
+  parameters, the scheme definitions/file, the app template.
+
+Running these commands in sequence from the repo root should work
+out-of-the-box after having installed the CLI tool.
+
+## Applications
+This repo provides palette-agnostic theme templates for `kitty`,
+`vim`/`neovim`, and `fzf` in the `templates/` directory. Pre-generated
+*concrete* themes can be found in `app-config/`, if you'd like to try an
+example out-of-the-box without using the `monobiome` CLI. Raw
+palette colors can be found in `colors/` if you want to use them to define
+static themes for other applications.
+
+Themes files in the `app-config/` directory are generated for light and dark
+modes of each biome, and named according to the following pattern:
+
+```sh
+<biome>-monobiome-<mode>.<filename>
+```
+
+One can set these themes for the provided applications as follows:
+
+- `kitty`
+
+  Find `kitty` themes in `app-config/kitty`. Themes can be activated in your
+  `kitty.conf` with
+  
+  ```sh
+  include <theme-file>
+  ```
+
+  Themes are generated using the [`kitty` theme
+  template](templates/kitty/active.theme).
+
+- `vim`/`neovim`
+
+  Find `vim`/`neovim` themes in `app-config/nvim`. Themes can be activated by placing a
+  theme file on Vim's runtime path and setting it in your
+  `.vimrc`/`init.vim`/`init.lua`
+
+  with
+  
+  ```sh
+  colorscheme <theme-name>
+  ```
+
+  Themes are generated using the [`vim` theme
+  template](templates/nvim/theme.vim).
+
+- `fzf`
+
+  In `app-config/fzf`, you can find scripts that can be ran to export FZF theme
+  variables. In your shell config (e.g., `.bashrc` or `.zshrc`), you can source
+  these files to apply them in your terminal:
+  
+  ```sh
+  source <theme-file>
+  ```
+
+  Themes are generated using the [`fzf` theme
+  template](templates/fzf/active.theme).
+
+- Firefox
+
+  Firefox themes for all monotone backgrounds are publicly listed as [Mozilla
+  add-ons][2], and switch between light/dark schemes based on system settings.
+  You can also download raw XPI files for each theme in `app-config/firefox/`,
+  each of which is generated using the [Firefox `manifest.json`
+  template](templates/firefox/auto-manifest.json).
+
+  Static [light][4] and [dark][5] themes are additionally available (i.e., that
+  don't change with system settings).
+
+## CLI installation
+A brief theme generation guide was provided in the [Generation
+section](#generation), making use of the `monobiome` CLI. This tool can be
+installed from PyPI, using `uv`/`pipx`/similar:
+
+```sh
+uv tool install monobiome
+# or
+pipx install monobiome
+```
+
+`monobiome` provides three subcommands:
+
+- `monobiome palette`: generate palette files from raw parameterized curves
+
+  ```
+  usage: monobiome palette [-h] [-n {hex,oklch}] [-f {json,toml}] [-o OUTPUT]
+
+  options:
+    -n {hex,oklch}, --notation {hex,oklch}
+                          color notation to export (either hex or oklch)
+    -f {json,toml}, --format {json,toml}
+                          format of palette file (either JSON or TOML)
+    -o OUTPUT, --output OUTPUT
+                          output file to write palette content
+  ```
+
+- `monobiome scheme`: generate scheme files that match perceptual parameters
+
+  ```
+  usage: monobiome scheme [-h] [-m {wcag,oklch,lightness}] [-d DISTANCE] [-o OUTPUT] [-l L_BASE]
+                          [--l-step L_STEP] [--fg-gap FG_GAP] [--grey-gap GREY_GAP]
+                          [--term-fg-gap TERM_FG_GAP]
+                          {dark,light}
+                          {alpine,badlands,chaparral,savanna,grassland,reef,tundra,heathland,moorland}
+  
+  positional arguments:
+    {dark,light}          scheme mode (light or dark)
+    {alpine,badlands,chaparral,savanna,grassland,reef,tundra,heathland,moorland}
+                          biome setting for scheme.
+  
+  options:
+    -m {wcag,oklch,lightness}, --metric {wcag,oklch,lightness}
+                          metric to use for measuring swatch distances.
+    -d DISTANCE, --distance DISTANCE
+                          distance threshold for specified metric
+    -o OUTPUT, --output OUTPUT
+                          output file to write scheme content
+    -l L_BASE, --l-base L_BASE
+                          minimum lightness level (default: 20)
+    --l-step L_STEP       lightness step size (default: 5)
+    --fg-gap FG_GAP       foreground lightness gap (default: 50)
+    --grey-gap GREY_GAP   grey lightness gap (default: 30)
+    --term-fg-gap TERM_FG_GAP
+                          terminal foreground lightness gap (default: 60)
+  ```
+
+- `monobiome fill`: produce concrete application themes from a given scheme and
+  app template
+
+  ```
+  usage: monobiome fill [-h] [-p PALETTE] [-o OUTPUT] scheme [template]
+
+  positional arguments:
+    scheme                scheme file path
+    template              template file path (defaults to stdin)
+  
+  options:
+    -p PALETTE, --palette PALETTE
+                          palette file to use for color definitions
+    -o OUTPUT, --output OUTPUT
+                          output file to write filled template
+  ```
+
+## Config management
+The `monobiome` CLI tool attempts to provide the minimal functionality needed
+to produce customized themes for individual applications. If seeking a more
+holistic, system-wide approach, you might consider using [`symconf`][3], a
+general-purpose application config manager. `symconf` provides the templating
+subsystem used for `monobiome` internals, and can be configured to apply live
+theme updates to many apps with a single command line invocation.
+
+
+[1]: https://github.com/isa/TextMate-Themes/blob/master/monoindustrial.tmTheme
+[2]: https://addons.mozilla.org/en-US/firefox/collections/18495484/monobiome/
+[3]: https://github.com/ologio/symconf
+[4]: https://addons.mozilla.org/en-US/firefox/collections/18495484/monobiome-light/
+[5]: https://addons.mozilla.org/en-US/firefox/collections/18495484/monobiome-dark/

monobiome-1.5.1.dist-info/RECORD

@@ -0,0 +1,18 @@
+monobiome/__init__.py,sha256=ChC5YFLK0kgvi0MJwD68LtZgUMJVCtNbtY32UQTvdA4,75
+monobiome/__main__.py,sha256=4K-CQWWiSXQbXgNLPqdOts6R3wOJeDJ0ygSARPI-eiA,439
+monobiome/constants.py,sha256=zkIDBtPS3unt9EulnTfpJV8r82Cc1Q-8c7u2Y2jcgBY,3694
+monobiome/curve.py,sha256=4IMn-YksJrqMOR-oYjA9oIJChI_Hz11AmynhYjLXl48,1754
+monobiome/palette.py,sha256=EhB90k1XINzbCxU8bBWc_fnEtbOXoJYfwAbtyx1nG-g,1505
+monobiome/plotting.py,sha256=pRGIsdW8SfjUbfEy8IZhLwzX5au6xc6vwtnDZymScvU,6127
+monobiome/scheme.py,sha256=5AwQW5Ibs-B7ZahGSXSmTE7CFZUpk3SKN42Qo-EW2AM,7793
+monobiome/util.py,sha256=qHLC-azOgslJcW1tNNX5TVeG3RPGpleUO2s9Nu1rbjY,1068
+monobiome/cli/__init__.py,sha256=bs2ZJZSWNg5tuxzAMzRzyB25Lbc4PDCVbrF2IKl2lK8,819
+monobiome/cli/fill.py,sha256=FbDpUZJegCUatFxPRk8hp4z2V93WBwqHPCOpw3rzJR4,2116
+monobiome/cli/palette.py,sha256=X1QET3UU1RxzT8D0JLWL1JKNlSQ6Dulwl1J-GLc_218,1265
+monobiome/cli/scheme.py,sha256=DNwA6Af3bJZpjImisncOgQo_kFHGTot-Ydv6o4FR1-Y,3769
+monobiome/data/parameters.toml,sha256=7ru0j_1G5rNFWc7AFKSHJUpyL_I2qdZYeDFt6q5wtQw,801
+monobiome-1.5.1.dist-info/METADATA,sha256=RBoL2842uiSvxZFi4wHxyJCX2GWFWUZm8Byus44J_Q0,14796
+monobiome-1.5.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+monobiome-1.5.1.dist-info/entry_points.txt,sha256=LpqkPxdTacTY_TaRn8eczICmPbVlXdRSoMqaxSfVxh4,54
+monobiome-1.5.1.dist-info/top_level.txt,sha256=ZA2wgRkPoG4xG0rSjyHKkuG8cdSHRr1U_DcrplXoi3A,10
+monobiome-1.5.1.dist-info/RECORD,,

monobiome-1.4.0.dist-info/METADATA

@@ -1,232 +0,0 @@
-Metadata-Version: 2.4
-Name: monobiome
-Version: 1.4.0
-Summary: Monobiome color palette
-Project-URL: Homepage, https://doc.olog.io/monobiome
-Project-URL: Documentation, https://doc.olog.io/monobiome
-Project-URL: Repository, https://git.olog.io/olog/monobiome
-Project-URL: Issues, https://git.olog.io/olog/monobiome/issues
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-Requires-Dist: coloraide>=5.1
-Requires-Dist: imageio[ffmpeg]>=2.37.2
-Requires-Dist: ipython>=9.6.0
-Requires-Dist: kaleido>=1.1.0
-Requires-Dist: matplotlib>=3.10.7
-Requires-Dist: nbformat>=5.10.4
-Requires-Dist: numpy>=2.3.4
-Requires-Dist: pillow>=12.0.0
-Requires-Dist: plotly>=6.3.1
-Requires-Dist: pyqt5>=5.15.11
-Requires-Dist: scipy>=1.16.2
-
-# Monobiome
-`monobiome` is a minimal, balanced color palette for use in terminals and text
-editors. It was designed in OKLCH space to achieve perceptual uniformity across
-all hues at various levels of luminance, and does so for _five_ monotone bases
-and _five_ accent colors (plus one gray "default"). Each of the monotone base
-colors (named according to a natural biome whose colors they loosely resemble)
-are designed to achieve identical contrast with the accents, and thus any one
-of the options can be selected to change the feeling of the palette without
-sacrificing readability.
-
-![Theme preview](images/repo_preview_primary.png)
-_(Preview of default light and dark theme variants)_
-
-See screenshots for the full set of theme variants in [THEMES](THEMES.md) (also
-discussed below).
-
-The name "monobiome" connects the palette to its two key sources of
-inspiration:
-
-- `mono-`: `monobiome` is inspired by the [`monoindustrial` theme][1], and
-  attempts to extend and balance its accents while retaining similar color
-  identities.
-- `-biome`: the desire for several distinct monotone options entailed finding a
-  way to ground the subtle color variations that were needed, and I liked the
-  idea of tying the choices to naturally occurring environmental variation like
-  Earth's biomes (even if it is a very loose affiliation, e.g., green-ish =
-  grass, basically).
-
-## Palette
-The `monobiome` palette consists of four monotone bases and five accent colors,
-each of which is anchored by hue and spread uniformly across lightness levels
-15 to 95 (in OKLCH space). 
-
-![Diagram of palette accents and monotones](images/palette.png)
-
-The chroma curve for each accent is carefully designed to vary smoothly across
-the lightness spectrum, with the goal of retaining strong color identity in all
-settings. Additionally, as alluded to above, the (WCAG 2) contrast ratio
-between any choice of monotone background at a given lightness level and the
-accent colors is virtually identical ($\pm 0.1$). Put another way, the relative
-contrast between accents depends only on the _lightness_ of the background
-monotone, not its hue. *(Note that this is not generally the case; at a fixed
-lightness level, the contrast between two colors depends on their hue.)*
-
-## Concrete themes
-
-![Split view of Alpine and Tundra biomes](images/theme-split-view.png)
-
-*(Light and dark theme splits of Alpine and Tundra biomes)*
-
-Themes are derived from the `monobiome` palette by varying both the monotone
-hue (the "biome") and the extent of the background/foreground lightness (the
-"harshness"). This is done for both light and dark schemes, and in each case
-accent colors are selected at a lightness level that ensures each meet a
-minimum contrast relative to the primary background. The following diagram
-shows each of the 36 resulting combinations:
-
-![Diagram of the 36 available concrete theme options](images/themes.png)
-
-The "soft" harshness level uses monotone shades closer to the mid-shade
-(lightness level 55), whereas "hard" harshness uses shades further from it.
-Once the biome and harshness level are chosen, we're left with a bounded
-monotone range over which common theme elements can be defined. For example,
-the following demonstrates how background and foreground elements are chosen
-for the `monobiome` Vim themes:
-
-![
-  Diagram depicting how themes colors are selected by harshness and mapped onto
-  application-specific elements
-](images/vim_theme_elements.png)
-
-Note how theme elements are mapped onto the general identifiers `bg0-bg3` for
-backgrounds, `fg0-fg3` for foregrounds, and `gray` for a central gray tone. The
-relative properties (lightness differences, contrast ratios) between colors
-assigned to these identifiers are preserved regardless of biome or harshness
-(e.g., `bg3` and `gray` are _always_ separated by 20 lightness points in any
-theme). As a result, applying `monobiome` themes to specific applications can
-effectively boil down to defining a single "relative template" that uses these
-identifiers, after which any of the 36 theme options can applied immediately.
-
-Read more about how themes are created in [DESIGN](DESIGN.md).
-
-# Usage
-This repo provides the 36 theme files for `kitty`, `vim`/`neovim`, and `fzf` in
-the `app-config/` directory. You can also find raw palette colors in
-`colors/monobiome.toml` if you want to use them to define themes for other
-applications.
-
-Each of the files in the `app-config/` directory are named according to
-
-```sh
-<harshness>-<biome>-monobiome-<mode>.<ext>
-```
-
-For example, `monobiome-tundra-dark-soft.vim` is the Vim theme file for the
-dark `tundra` variant with the soft harshness level.
-
-## Applications
-- `kitty`
-
-  Find `kitty` themes in `app-config/kitty`. Themes can be activated in your
-  `kitty.conf` with
-  
-  ```sh
-  include <theme-file>
-  ```
-
-  Themes are generated using the [`kitty` theme
-  template](templates/apps/kitty/templates/active.theme).
-
-- `vim`/`neovim`
-
-  Find `vim`/`neovim` themes in `app-config/nvim`. Themes can be activated by placing a
-  theme file on Vim's runtime path and setting it in your `.vimrc`/`init.vim`
-  with
-  
-  ```sh
-  colorscheme <theme-name>
-  ```
-
-  Themes are generated using the [`vim` theme
-  template](templates/apps/nvim/templates/theme.vim).
-
-- `fzf`
-
-  In `app-config/fzf`, you can find scripts that can be ran to export FZF theme
-  variables. In your shell config (e.g., `.bashrc` or `.zshrc`), you can source
-  these files to apply them in your terminal:
-  
-  ```sh
-  source <theme-file>
-  ```
-
-  Themes are generated using the [`fzf` theme
-  template](templates/apps/fzf/templates/active.theme).
-
-- Firefox
-
-  Firefox themes for all monotone backgrounds are publicly listed as [Mozilla
-  add-ons][2], and switch between light/dark schemes based on system settings.
-  You can also download raw XPI files for each theme in `app-config/firefox/`,
-  each of which is generated using the [Firefox `manifest.json`
-  template](templates/apps/firefox/templates/none-dark.manifest.json).
-
-  Static [light][4] and [dark][5] are additionally available.
-
-  ![Firefox theme previews](images/firefox/themes.png)
-
-# Switching themes
-[`symconf`][3] is a general-purpose application config manager that can be used
-to generate all `monobiome` variants from a single palette file, and set themes
-for all apps at once. You can find example theme templates in
-`templates/groups/theme`, which provide general theme variables you can use in
-your own config templates.
-
-For instance, in an app like `kitty`, you can define a template like
-
-```conf
-# base settings
-background           f{{theme.term.background}}
-foreground           f{{theme.term.foreground}}
-
-selection_background f{{theme.term.selection_bg}}
-selection_foreground f{{theme.term.selection_fg}}
-
-cursor               f{{theme.term.cursor}}
-cursor_text_color    f{{theme.term.cursor_text_color}}
-
-# black
-color0               f{{theme.term.normal.black}}
-color8               f{{theme.term.bright.black}}
-
-# red
-color1               f{{theme.term.normal.red}}
-color9               f{{theme.term.bright.red}}
-
-# green
-color2               f{{theme.term.normal.green}}
-color10              f{{theme.term.bright.green}}
-
-# yellow
-color3               f{{theme.term.normal.yellow}}
-color11              f{{theme.term.bright.yellow}}
-
-# blue
-color4               f{{theme.term.normal.blue}}
-color12              f{{theme.term.bright.blue}}
-
-# purple (red)
-color5               f{{theme.term.normal.purple}}
-color13              f{{theme.term.bright.purple}}
-
-# cyan (blue)
-color6               f{{theme.term.normal.cyan}}
-color14              f{{theme.term.bright.cyan}}
-
-## white
-color7               f{{theme.term.normal.white}}
-color15              f{{theme.term.bright.white}}
-```
-
-and use `symconf` to dynamically fill these variables based on a selected
-biome/harshness/mode. This can be done for any app config file.
-
-
-[1]: https://github.com/isa/TextMate-Themes/blob/master/monoindustrial.tmTheme
-[2]: https://addons.mozilla.org/en-US/firefox/collections/18495484/monobiome/
-[3]: https://github.com/ologio/symconf
-[4]: https://addons.mozilla.org/en-US/firefox/collections/18495484/monobiome-light/
-[5]: https://addons.mozilla.org/en-US/firefox/collections/18495484/monobiome-dark/

monobiome-1.4.0.dist-info/RECORD

@@ -1,17 +0,0 @@
-monobiome/__init__.py,sha256=ChC5YFLK0kgvi0MJwD68LtZgUMJVCtNbtY32UQTvdA4,75
-monobiome/__main__.py,sha256=k2Pu_FeAsW_wnE55Y-JJaRP_GgxAZEjW3z_Kmk3O8C8,431
-monobiome/constants.py,sha256=w4H9V2Tp2ZK3ddcjtBdDtokZdj2Y1ssW3RSopxqP7rw,3105
-monobiome/curve.py,sha256=tw44OoRGDSxTzljxJkgifWhCTEj05TBYnw4jOdrNgfA,1748
-monobiome/palette.py,sha256=fReZD1Aa7xOKQQgnYB8qRxszZy1nq9XLqjUIblENsvI,1489
-monobiome/plotting.py,sha256=QZ1nVAb6E-eb1pwaQAbwOhqhRhzQ0SgR_8mC63zNFIo,4909
-monobiome/scheme.py,sha256=CFP_WqTk-CwbgpVt2E_TczC9cZymAh_lqbkWmN4AsOg,7541
-monobiome/util.py,sha256=qHLC-azOgslJcW1tNNX5TVeG3RPGpleUO2s9Nu1rbjY,1068
-monobiome/cli/__init__.py,sha256=wtBhzdyyRy0-WM4fUpDESJBiedYy8MbwousVCdangUE,774
-monobiome/cli/palette.py,sha256=i3baWZs4Sverbd79YMBPYnH0P2rT0i7z3ZAtO_UBWNw,1219
-monobiome/cli/scheme.py,sha256=CkwtGBCPUEPt2TnK_WDQBg8TKTw_hjGoQtbjjBlNmH0,3725
-monobiome/data/parameters.toml,sha256=7ru0j_1G5rNFWc7AFKSHJUpyL_I2qdZYeDFt6q5wtQw,801
-monobiome-1.4.0.dist-info/METADATA,sha256=JsUQbx8Zr_LkhOIw8DY3kSSgMrJtxprJCK1f686082s,8974
-monobiome-1.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-monobiome-1.4.0.dist-info/entry_points.txt,sha256=LpqkPxdTacTY_TaRn8eczICmPbVlXdRSoMqaxSfVxh4,54
-monobiome-1.4.0.dist-info/top_level.txt,sha256=ZA2wgRkPoG4xG0rSjyHKkuG8cdSHRr1U_DcrplXoi3A,10
-monobiome-1.4.0.dist-info/RECORD,,