rewrite README with new image references

README.md

@@ -1,18 +1,15 @@
 # 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.
+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 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).
+_(Preview of light and dark alpine theme variants)_
 
 The name "monobiome" connects the palette to its two key sources of
 inspiration:
@@ -27,42 +24,79 @@ inspiration:
   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). 
+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.
 
-![Diagram of palette accents and monotones](images/palette.png)
+| Chroma curves | Color trajectories |
+|---|---|
+| ![Chroma curves](images/cstar-curves-v140.png) | ![Trajectories](images/trajectories.gif) |
 
-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.)*
+| Palette |
+|---|
+| ![Palette](images/palette.png) |
+
+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.
 
 ## Concrete themes
 
-![Dark themes](images/dark_themes.png)
+| Dark themes | Light themes |
+|---|---|
+| ![Dark themes](images/dark_themes.png) | ![Light themes](images/light_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. 
 
-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:
+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:
 
-![Diagram of the 36 available concrete theme options](images/themes.png)
+| | `-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) | ![](v140-demo-alpine-dark-d0.4.png) | ![](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.
 
 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:
+monotone range over which common theme elements can be defined.
+
+## Applications
+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
@@ -76,15 +110,15 @@ 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).
+identifiers, after which any user-provided parameters can be applied
+automatically. You can 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.
+This repo provides *relative* theme templates for `kitty`, `vim`/`neovim`, and
+`fzf` in the `templates/apps` directory, along with *concrete* themes in
+`app-config/`. You can also find raw palette colors in `templates/apps/groups/`
+if you want to use them to define static themes for other applications.
 
 Each of the files in the `app-config/` directory are named according to
 
@@ -93,7 +127,7 @@ Each of the files in the `app-config/` directory are named according to
 ```
 
 For example, `monobiome-tundra-dark-soft.vim` is the Vim theme file for the
-dark `tundra` variant with the soft harshness level.
+dark `tundra` variant with a soft harshness level.
 
 ## Applications
 - `kitty`

pyproject.toml

@@ -6,8 +6,24 @@ build-backend = "setuptools.build_meta"
 name = "monobiome"
 version = "1.4.0"
 description = "Monobiome color palette"
-readme = "README.md"
 requires-python = ">=3.12"
+authors = [
+  { name="Sam Griesemer", email="git@olog.io" },
+]
+readme = "README.md"
+license = "MIT"
+keywords = [
+    "tempate-engine",
+    "color-palette",
+]
+classifiers = [
+    "Programming Language :: Python",
+    "Operating System :: OS Independent",
+    "Development Status :: 3 - Alpha",
+
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+]
 dependencies = [
     "coloraide>=5.1",
     "imageio[ffmpeg]>=2.37.2",
@@ -22,20 +38,35 @@ dependencies = [
     "scipy>=1.16.2",
 ]
 
-[dependency-groups]
-dev = [
-    "ipykernel>=7.0.1",
-]
-
 [project.scripts]
 monobiome = "monobiome.__main__:main"
 
+[project.optional-dependencies]
+dev = [
+    "ipykernel",
+]
+doc = [
+    "furo",
+    "myst-parser",
+    "sphinx",
+    "sphinx-togglebutton",
+    "sphinx-autodoc-typehints",
+]
+test = [
+    "pytest",
+]
+
 [project.urls]
 Homepage = "https://doc.olog.io/monobiome"
 Documentation = "https://doc.olog.io/monobiome"
 Repository = "https://git.olog.io/olog/monobiome"
 Issues = "https://git.olog.io/olog/monobiome/issues"
 
+[dependency-groups]
+dev = [
+    "ipykernel>=7.0.1",
+]
+
 [tool.setuptools.packages.find]
 include = ["monobiome*"]
 

scripts/screens.sh

@@ -7,29 +7,32 @@ prefix=${1:-}
 script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 render_script="$script_dir/render.sh"
 
-biomes=(alpine badlands chaparral savanna grassland tundra reef heathland moorland)
-modes=(light)
+biomes=(alpine) # badlands chaparral savanna grassland tundra reef heathland moorland)
+modes=(dark)
+distances=(0.3 0.4 0.5)
 
 for biome in "${biomes[@]}"; do
     for mode in "${modes[@]}"; do
-        echo "Applying $biome-$mode theme"
-        monobiome scheme "$mode" "$biome" \
-            -d 0.42 \
-            -l 90 \
-            -o ~/.config/symconf/groups/theme/monobiome-none.toml
-        symconf config \
-            -a kitty,nvim \
-            -m "$mode" \
-            -s monobiome \
-            -T font=Berkeley
-        sleep 1
+        for dist in "${distances[@]}"; do
+            echo "Applying $biome-$mode theme"
+            monobiome scheme "$mode" "$biome" \
+                -d "$dist" \
+                -l 20 \
+                -o ~/.config/symconf/groups/theme/monobiome-none.toml
+            symconf config \
+                -a kitty,nvim \
+                -m "$mode" \
+                -s monobiome \
+                -T font=Berkeley
+            sleep 1
 
-        echo "Taking screenshot..."
-        "$render_script" 1920 1440 "images/render/$prefix-$biome-$mode.png" nvim \
-            +':highlight Cursor blend=100' \
-            +':set guicursor=n:block-Cursor' \
-            +':silent! setlocal nonumber nocursorline signcolumn=no foldcolumn=no' \
-            +':lua vim.diagnostic.config({virtual_text=false,signs=false,underline=false})' \
-            examples/class.py
+            echo "Taking screenshot..."
+            "$render_script" 1920 1440 "images/render/$prefix-$biome-$mode-d$dist.png" nvim \
+                +':highlight Cursor blend=100' \
+                +':set guicursor=n:block-Cursor' \
+                +':silent! setlocal nonumber nocursorline signcolumn=no foldcolumn=no' \
+                +':lua vim.diagnostic.config({virtual_text=false,signs=false,underline=false})' \
+                examples/class.py
+        done
     done
 done