starhue 1.0.0__tar.gz

starhue-1.0.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Devesh Aggarwal
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

starhue-1.0.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: starhue
+Version: 1.0.0
+Requires-Python: >=3.8
+License-File: LICENSE
+Dynamic: license-file

starhue-1.0.0/README.md

@@ -0,0 +1,281 @@
+# starhue
+
+`starhue` takes a temperature value in kelvin, and returns the actual sRGB color that a
+blackbody of that temperature would show to your eye — along with the physics behind it:
+the Planck spectrum, the Wien peak, Stefan–Boltzmann exitance, and the Harvard spectral
+class. It also runs in reverse, turning a color back into a correlated color temperature
+(CCT), and renders it all as a star card in your terminal.
+
+<p align="center">
+  <img src="starhue/assets/sun.png" alt="starhue card for the Sun (5772 K)" width="640">
+</p>
+
+---
+
+## Installation
+
+`starhue` is pure standard library — no third-party dependencies, just Python 3.8+.
+Clone the repo and install it editable into a virtualenv:
+
+```bash
+git clone https://github.com/devesh-aggarwal/starhue.git
+cd starhue
+python -m venv .venv && source .venv/bin/activate
+python -m pip install -e .
+```
+
+There is nothing else to fetch. Confirm it works:
+
+```bash
+python -m starhue 5772        # should print a star card for the Sun
+```
+
+## Quick start
+
+The standard use case is one or more temperatures in kelvin → a star card per temperature:
+
+```bash
+python -m starhue 5772             # the Sun
+python -m starhue 3500 5772 12100  # several stars at once
+python -m starhue --from-color '#ffd1a3'   # inverse: a color → its nearest blackbody
+python -m starhue 5772 --no-spectrum       # card without the sparkline
+```
+
+`python -m starhue 5772` prints:
+
+```text
+╭────────────────────────────────────────────────╮
+│ ★  5772 K                              class G  │
+│ ████████  #fff1ea  rgb(255, 241, 234)          │
+│ yellow, Sun-like · neutral white               │
+│                                                │
+│ peak λ    502.0 nm  ·  3.393e+14 Hz            │
+│ exitance  62.94 MW/m²                          │
+│                                                │
+│ ▄▄▅▆▆▇▇▇██████████▇▇▇▇▇▆▆▆▆▆▅▅▅▅▅▄▄▄▄▄▄▃▃▃▃▃▃▃ │
+│            ▲                                    │
+│ 300nm                                   1100nm │
+╰────────────────────────────────────────────────╯
+```
+
+Reading the card: the swatch with its `#rrggbb` / `rgb()` values is the star's display
+color; **peak λ** is the Wien peak wavelength (nm) and its frequency (Hz); **exitance** is
+the Stefan–Boltzmann radiant exitance (here in MW/m²); the sparkline is the Planck spectrum
+sampled 300–1100 nm, with ▲ marking the peak. *(In a real terminal the swatch and sparkline
+are full 24-bit color.)*
+
+## Python API
+
+```python
+import starhue
+
+# One-liners — pick the output format you want
+starhue.temperature_to_color(5772)          # '#fff1ea'        (hex by default)
+starhue.temperature_to_color(3500, 'rgb')   # (255, 200, 140)  (r, g, b), 0–255
+starhue.wavelength_to_color(550, 'rgb')      # color of a single wavelength
+
+# The high-level object
+star = starhue.Star(5772)
+star.hex                  # '#fff1ea'
+star.rgb                  # (255, 241, 234)
+star.peak_wavelength_nm   # 502.0     — Wien's displacement law
+star.peak_frequency_hz    # 3.39e14   — frequency-form Wien's law
+star.radiant_exitance     # 6.29e7 W/m²  — Stefan–Boltzmann
+star.spectral_type.letter # 'G'
+star.appearance           # 'neutral white'
+
+# The raw spectrum: list of (wavelength_nm, radiance)
+star.spectrum(380, 750, samples=100, normalize=True)
+```
+
+### Inverse: color → temperature (CCT)
+
+Go the other way too. The correlated color temperature is the nearest point on
+the Planckian locus in CIE 1960 *uv* space, so it round-trips with the forward
+model. `color_to_temperature` takes the color as a `#rrggbb` string or an
+`(r, g, b)` triple and returns the temperature in kelvin.
+
+```python
+starhue.color_to_temperature('#ffd1a3')        # 3911.0
+starhue.color_to_temperature((205, 217, 255))  # ~10000
+
+starhue.Star.from_color('#fff1ea')        # Star(5773 K, #fff1ea, class G)
+starhue.Star.from_color((255, 200, 140))  # also takes an (r, g, b) triple
+```
+
+## API reference
+
+These are the functions and objects you call. They're re-exported onto the
+top-level `starhue` namespace, so `import starhue` is enough to reach all of
+them; the table notes which submodule each lives in if you'd rather import from
+there.
+
+### Forward — temperature / wavelength → color
+
+Each returns a `#rrggbb` string by default, or an `(r, g, b)` triple (0–255) with
+`format="rgb"`.
+
+| Name | Signature → returns | Description |
+|---|---|---|
+| `temperature_to_color` | `(temperature_k, format="hex", step_nm=1.0) → str \| (int, int, int)` | Color of a blackbody at this temperature (full colorimetric pipeline). |
+| `wavelength_to_color` | `(wavelength_nm, format="hex") → str \| (int, int, int)` | Display color of a single monochromatic wavelength (a spectral ramp, for plots). |
+
+### Inverse — color → temperature
+
+| Name | Signature → returns | Description |
+|---|---|---|
+| `color_to_temperature` | `(color) → float` | Correlated color temperature (K) of a `#rrggbb` hex string or `(r, g, b)` triple — the nearest blackbody on the Planckian locus. |
+
+### Color utilities
+
+| Name | Signature → returns | Description |
+|---|---|---|
+| `hex_to_rgb` | `(value) → (int, int, int)` | Parse `#rgb`/`#rrggbb` → `(r, g, b)`, 0–255. |
+
+### Physics
+
+| Name | Signature → returns | Description |
+|---|---|---|
+| `planck` | `(wavelength_m, temperature_k) → float` | Planck spectral radiance, W·sr⁻¹·m⁻³ (wavelength in **metres**). |
+| `planck_nm` | `(wavelength_nm, temperature_k) → float` | Planck spectral radiance per nm (wavelength in **nanometres**). |
+| `spectrum` | `(temperature_k, lo_nm=300, hi_nm=1100, samples=200, *, normalize=False) → list[(float, float)]` | Sample the Planck curve → `(wavelength_nm, radiance)` pairs. |
+| `wien_peak_wavelength` | `(temperature_k, unit="nm") → float` | Wavelength of peak radiance (Wien); **nm** by default, `unit="m"` for metres. |
+| `wien_peak_frequency` | `(temperature_k) → float` | Frequency of peak radiance (frequency-form Wien), Hz. |
+| `stefan_boltzmann` | `(temperature_k) → float` | Total radiant exitance σT⁴, W·m⁻². |
+
+### Classification
+
+| Name | Kind | Signature → returns | Description |
+|---|---|---|---|
+| `spectral_class` | function | `(temperature_k) → SpectralType` | Harvard spectral type (O/B/A/F/G/K/M) for an effective temperature. |
+| `appearance_name` | function | `(temperature_k) → str` | Friendly perceptual color name, e.g. `"warm amber"`, as seen in a vacuum *(in `starhue.classify`)*. |
+| `SpectralType` | object | `NamedTuple(letter, description)` | The value `spectral_class` returns — read `.letter` (e.g. `'G'`) and `.description` off it. |
+
+### The `Star` object (`starhue.Star`)
+
+`Star(temperature_k, *, color_step_nm=1.0)` — the high-level facade. The keyword
+`color_step_nm` is the wavelength step (nm) of the color integration; smaller is
+more accurate but slower.
+
+**Inverse constructor** (color → nearest blackbody):
+
+| Constructor | Signature → returns | Description |
+|---|---|---|
+| `Star.from_color` | `(color_value) → Star` | From either a `#rrggbb` hex string or an sRGB `(r, g, b)` triple (0–255). |
+
+**Attributes, properties & methods:**
+
+| Member | Kind | Type / returns | Description |
+|---|---|---|---|
+| `temperature` | attribute | `float` | The star's temperature, K. |
+| `rgb` | property | `(int, int, int)` | Display sRGB color, 0–255. |
+| `hex` | property | `str` | Display sRGB color as `#rrggbb`. |
+| `peak_wavelength_nm` | property | `float` | Wien peak wavelength, nm. |
+| `peak_frequency_hz` | property | `float` | Wien peak frequency (frequency form), Hz. |
+| `radiant_exitance` | property | `float` | Stefan–Boltzmann exitance, W·m⁻². |
+| `spectral_type` | property | `SpectralType` | Harvard spectral classification. |
+| `appearance` | property | `str` | Friendly perceptual color name, e.g. `"neutral white"`. |
+| `planck(wavelength_nm)` | method | `float` | Spectral radiance at a wavelength in nm. |
+| `spectrum(lo_nm=300, hi_nm=1100, samples=200, *, normalize=False)` | method | `list[(float, float)]` | Sample the Planck curve → `(wavelength_nm, radiance)` pairs. |
+
+Anything not listed here (the colorimetry conversion steps in `starhue.color`,
+the physical constants in `starhue.constants`) is internal plumbing the functions
+above build on — usable, but not the intended surface.
+
+## CLI reference
+
+```
+python -m starhue [TEMPERATURES ...] [options]
+
+positional:
+  TEMPERATURES        one or more temperatures in kelvin (default: 5772, the Sun)
+
+options:
+  --no-spectrum       hide the spectrum sparkline in cards
+  --from-color COLOR  inverse mode: a color (#rrggbb or r,g,b) → its nearest blackbody
+  --color / --no-color   force or disable ANSI color (auto-detected by default)
+  --version
+```
+
+```bash
+python -m starhue --from-color '#ffd1a3'   # what temperature is this color?
+```
+
+Color output honours the `NO_COLOR` and `FORCE_COLOR` conventions.
+
+## Module map
+
+| module | role |
+|---|---|
+| `constants` | exact SI / CODATA physical constants |
+| `physics` | Planck's law, Wien's law, Stefan–Boltzmann, spectrum sampling |
+| `color` | CIE 1931 CMF → XYZ → sRGB; chromaticity; wavelength → display color |
+| `cct` | inverse direction: color → correlated color temperature |
+| `classify` | Harvard spectral class + perceptual color names |
+| `star` | the high-level `Star` object |
+| `render` | terminal card + spectrum sparkline |
+| `cli` | the command-line interface |
+
+## The science
+
+Everything is computed from first principles with the exact 2019-SI constants.
+
+**Planck's law** — spectral radiance of a blackbody:
+
+$$B_\lambda(T) = \frac{2hc^2}{\lambda^5}\,\frac{1}{\exp\!\left(\dfrac{hc}{\lambda k_B T}\right) - 1}$$
+
+**Wien's displacement law** — where that curve peaks: $\lambda_\text{max} = b / T$.
+
+**Stefan–Boltzmann law** — total power radiated per unit area: $j^\star = \sigma T^4$.
+
+**Temperature → color** follows the standard colorimetry pipeline:
+
+1. Sample the Planck curve across the visible band (360–830 nm).
+2. Integrate against the **CIE 1931 2° color-matching functions** → CIE *XYZ*.
+3. Map *XYZ* → linear sRGB with the D65 matrix.
+4. Clamp out-of-gamut negatives, normalize to constant luminance, gamma-encode.
+
+The color-matching functions use the analytic multi-lobe Gaussian fit of
+**Wyman, Sloan & Shirley (2013)**, which reproduces the tabulated CIE curves to
+within ~1% with no embedded data table.
+
+### Is it accurate?
+
+Yes — it lands on the textbook reference points:
+
+| Temperature | `starhue` | meaning |
+|------------:|:----------|:--------|
+| 6500 K | xy ≈ (0.313, 0.324) | essentially the **D65** white point |
+| 5772 K | `#fff1ea` | the Sun — a warm white, *not* yellow |
+| 3500 K | `#ffc88c` | amber (an M-type red giant) |
+| 12000 K | bluish white | hot B-type star |
+
+The full Planckian locus matches Mitchell Charity's well-known blackbody-color
+table closely.
+
+## Gallery
+
+A cool red giant — note the spectral peak sliding into the infrared:
+
+<p align="center">
+  <img src="starhue/assets/betelgeuse.png" alt="3500 K M-type star" width="560">
+</p>
+
+A hot blue star, peak pushed into the ultraviolet:
+
+<p align="center">
+  <img src="starhue/assets/rigel.png" alt="12100 K B-type star" width="560">
+</p>
+
+## References
+
+- M. Planck, *On the Law of Distribution of Energy in the Normal Spectrum* (1901).
+- CIE 1931 2° standard colorimetric observer.
+- C. Wyman, P. Sloan & P. Shirley, *Simple Analytic Approximations to the CIE
+  XYZ Color Matching Functions*, **JCGT** 2(2), 2013.
+- IEC 61966-2-1:1999 (sRGB).
+- M. Charity, *What color is a blackbody?* — reference color table.
+
+## License
+
+_To be decided by the project owner._

starhue-1.0.0/pyproject.toml

@@ -0,0 +1,12 @@
+[build-system]
+requires = ["setuptools >= 61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "starhue"
+version = "1.0.0"
+requires-python = ">=3.8"
+
+# starhue is pure standard library (math, argparse, os, sys, typing).
+# It has no third-party runtime dependencies.
+dependencies = []

starhue-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

starhue-1.0.0/starhue/__init__.py

@@ -0,0 +1,57 @@
+"""starhue — temperature → true star color + Planck spectrum.
+
+Give it a temperature in kelvin; get back the actual sRGB color a blackbody of
+that temperature would show your eye, the spectral curve behind it, and a pile
+of derived physics (Wien peak, Stefan–Boltzmann exitance, spectral class).
+
+    >>> import starhue
+    >>> starhue.temperature_to_color(5772)   # the Sun
+    '#fff1ea'
+    >>> star = starhue.Star(3500)
+    >>> star.spectral_type.letter
+    'M'
+
+See :class:`Star` for the high-level object and the ``color``/``physics``
+submodules for the underlying functions.
+"""
+
+from __future__ import annotations
+
+from .cct import color_to_temperature
+from .classify import SpectralType, spectral_class
+from .color import (
+    hex_to_rgb,
+    temperature_to_color,
+    wavelength_to_color,
+)
+from .physics import (
+    planck,
+    planck_nm,
+    spectrum,
+    stefan_boltzmann,
+    wien_peak_frequency,
+    wien_peak_wavelength,
+)
+from .star import Star
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "Star",
+    "SpectralType",
+    "spectral_class",
+    # color
+    "temperature_to_color",
+    "wavelength_to_color",
+    "hex_to_rgb",
+    # inverse CCT (color → temperature)
+    "color_to_temperature",
+    # physics
+    "planck",
+    "planck_nm",
+    "spectrum",
+    "stefan_boltzmann",
+    "wien_peak_wavelength",
+    "wien_peak_frequency",
+]

starhue-1.0.0/starhue/__main__.py

@@ -0,0 +1,8 @@
+"""Enable ``python -m starhue``."""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

starhue-1.0.0/starhue/cct.py

@@ -0,0 +1,82 @@
+"""Inverse direction: a color → its correlated color temperature (CCT).
+
+The CCT of a color is *defined* as the temperature of the blackbody whose
+chromaticity is closest to it in the CIE 1960 UCS ``(u, v)`` plane. We find it by
+searching our own Planckian locus, so ``T → color → T`` round-trips cleanly.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Tuple, Union
+
+from . import color as _color
+
+__all__ = ["color_to_temperature"]
+
+#: Temperature range over which CCT is meaningful, in kelvin.
+T_MIN = 1000.0
+T_MAX = 40000.0
+
+
+def _locus_uv(temperature_k: float) -> Tuple[float, float]:
+    return _color.xy_to_uv(*_color.xyz_to_xy(*_color.spectrum_to_xyz(temperature_k)))
+
+
+def _dist2_at_mired(mired: float, u: float, v: float) -> float:
+    lu, lv = _locus_uv(1e6 / mired)
+    return (u - lu) ** 2 + (v - lv) ** 2
+
+
+def _golden_min(f, a: float, b: float, iters: int = 40) -> float:
+    """Golden-section search for the minimizer of a unimodal ``f`` on ``[a, b]``."""
+    inv_phi = (math.sqrt(5.0) - 1.0) / 2.0
+    c = b - inv_phi * (b - a)
+    d = a + inv_phi * (b - a)
+    fc, fd = f(c), f(d)
+    for _ in range(iters):
+        if fc < fd:
+            b, d, fd = d, c, fc
+            c = b - inv_phi * (b - a)
+            fc = f(c)
+        else:
+            a, c, fc = c, d, fd
+            d = a + inv_phi * (b - a)
+            fd = f(d)
+    return (a + b) / 2.0
+
+
+def _cct_from_uv(u: float, v: float) -> float:
+    """Nearest blackbody temperature (K) for a CIE 1960 ``(u, v)`` color."""
+    # Work in mired (10⁶/T): the Planckian locus is nearly straight there, so a
+    # coarse grid reliably brackets the minimum before we refine.
+    m_lo, m_hi = 1e6 / T_MAX, 1e6 / T_MIN
+    grid = 80
+    best_i, best_d2 = 0, float("inf")
+    mireds = [m_lo + (m_hi - m_lo) * i / (grid - 1) for i in range(grid)]
+    for i, m in enumerate(mireds):
+        d2 = _dist2_at_mired(m, u, v)
+        if d2 < best_d2:
+            best_i, best_d2 = i, d2
+
+    a = mireds[max(0, best_i - 1)]
+    b = mireds[min(grid - 1, best_i + 1)]
+    m_best = _golden_min(lambda m: _dist2_at_mired(m, u, v), a, b)
+    return 1e6 / m_best
+
+
+def color_to_temperature(color: Union[str, Tuple[float, float, float]]) -> float:
+    """Correlated color temperature (K) of a color — the nearest blackbody on the
+    Planckian locus.
+
+    Round-trips with ``starhue.temperature_to_color``.
+
+    Args:
+        color (str | tuple[float, float, float]): A ``#rrggbb`` hex string or an
+            sRGB ``(r, g, b)`` triple (0–255).
+
+    Returns:
+        float: The correlated color temperature in kelvin.
+    """
+    rgb = _color.hex_to_rgb(color) if isinstance(color, str) else color
+    return _cct_from_uv(*_color.xy_to_uv(*_color.rgb_to_xy(rgb)))

starhue-1.0.0/starhue/classify.py

@@ -0,0 +1,80 @@
+"""Harvard spectral classification and plain-language color names."""
+
+from __future__ import annotations
+
+from typing import List, NamedTuple, Tuple
+
+__all__ = ["SpectralType", "spectral_class", "appearance_name", "MK_CLASSES"]
+
+
+class SpectralType(NamedTuple):
+    """A Harvard spectral classification result."""
+
+    letter: str          #: O, B, A, F, G, K or M
+    description: str      #: short prose description
+
+
+# (min_temp_K, letter, description). Upper-open on the hot end.
+MK_CLASSES: List[Tuple[float, str, str]] = [
+    (30000.0, "O", "blue, blistering and short-lived"),
+    (10000.0, "B", "blue-white, massive and luminous"),
+    (7500.0, "A", "white with strong hydrogen lines"),
+    (6000.0, "F", "yellow-white"),
+    (5200.0, "G", "yellow, Sun-like"),
+    (3700.0, "K", "orange, cooler than the Sun"),
+    (0.0, "M", "red, cool and abundant"),
+]
+
+
+def spectral_class(temperature_k: float) -> SpectralType:
+    """Return the Harvard spectral type for an effective temperature.
+
+    Args:
+        temperature_k (float): Effective temperature in kelvin.
+
+    Returns:
+        SpectralType: The matching spectral class and its description.
+    """
+    for min_t, letter, desc in MK_CLASSES:
+        if temperature_k >= min_t:
+            return SpectralType(letter, desc)
+    # The last bucket starts at 0 K, so the loop always returns for a normal
+    # temperature; this only guards a non-finite value slipping through.
+    _, letter, desc = MK_CLASSES[-1]
+    return SpectralType(letter, desc)
+
+
+# (max_temp_K exclusive, name). The colors people actually perceive.
+_APPEARANCE: List[Tuple[float, str]] = [
+    (1200.0, "dim ember red"),
+    (2200.0, "deep red"),
+    (3200.0, "reddish orange"),
+    (4200.0, "warm amber"),
+    (5000.0, "pale gold"),
+    (5600.0, "soft yellow-white"),
+    (6600.0, "neutral white"),
+    (8000.0, "cool white"),
+    (12000.0, "blue-white"),
+    (float("inf"), "icy blue"),
+]
+
+
+def appearance_name(temperature_k: float) -> str:
+    """A friendly, perceptual color name for a blackbody temperature.
+
+    This is the star's color as seen *in a vacuum* — the light leaving its
+    surface, before any atmosphere reddens it. So the Sun (5772 K) comes out a
+    neutral white here, not the yellow it looks from the ground (Earth's
+    atmosphere scatters away the blue and tints the disc yellow).
+
+    Args:
+        temperature_k (float): Absolute temperature in kelvin.
+
+    Returns:
+        str: A perceptual color name, e.g. ``"neutral white"``.
+    """
+    for max_t, name in _APPEARANCE:
+        if temperature_k < max_t:
+            return name
+    # The final bucket has max_t == inf, so the loop always returns above.
+    return _APPEARANCE[-1][1]

starhue-1.0.0/starhue/cli.py

@@ -0,0 +1,125 @@
+"""Command-line interface for starhue.
+
+    starhue 5772                      # one star card
+    starhue 3000 5772 9940           # several cards
+    starhue --from-color '#ffd1a3'   # inverse: a color → its nearest blackbody
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import List, Optional, Sequence
+
+from . import __version__
+from .cct import color_to_temperature
+from .color import hex_to_rgb
+from .render import star_card, supports_color
+from .star import Star
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Construct the argparse parser for the CLI.
+
+    Returns:
+        argparse.ArgumentParser: The configured parser.
+    """
+    p = argparse.ArgumentParser(
+        prog="starhue",
+        description="Temperature → true star color + Planck spectrum.",
+        epilog="Give a temperature in kelvin (e.g. 5772 for the Sun) and see its real color.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.add_argument("temperatures", nargs="*", type=float, help="one or more temperatures in kelvin")
+    p.add_argument(
+        "--no-spectrum", dest="spectrum", action="store_false", help="hide the spectrum sparkline"
+    )
+    p.add_argument(
+        "--from-color",
+        metavar="COLOR",
+        help="inverse mode: a color (#rrggbb or r,g,b) → its nearest blackbody",
+    )
+    color = p.add_mutually_exclusive_group()
+    color.add_argument("--color", dest="color", action="store_true", default=None, help="force ANSI color")
+    color.add_argument("--no-color", dest="color", action="store_false", help="disable ANSI color")
+    p.add_argument("--version", action="version", version=f"starhue {__version__}")
+    return p
+
+
+def _validate_temps(temps: Sequence[float]) -> None:
+    """Reject any non-positive temperature.
+
+    Args:
+        temps (Sequence[float]): Temperatures in kelvin to validate.
+
+    Raises:
+        SystemExit: If any temperature is not positive.
+    """
+    for t in temps:
+        if t <= 0:
+            raise SystemExit(f"starhue: temperature must be positive, got {t:g}")
+
+
+def _parse_color(value: str) -> tuple:
+    """Parse a CLI color: ``#rrggbb``/``#rgb`` or ``r,g,b``.
+
+    Args:
+        value (str): The color string from the command line.
+
+    Returns:
+        tuple: The ``(r, g, b)`` channels as 0–255 ints.
+
+    Raises:
+        SystemExit: If the color cannot be parsed.
+    """
+    s = value.strip()
+    if "," in s:
+        parts = s.split(",")
+        if len(parts) != 3:
+            raise SystemExit(f"starhue: expected 'r,g,b', got {value!r}")
+        try:
+            return tuple(max(0, min(255, int(p))) for p in parts)
+        except ValueError:
+            raise SystemExit(f"starhue: invalid r,g,b color {value!r}") from None
+    try:
+        return hex_to_rgb(s)
+    except ValueError as exc:
+        raise SystemExit(f"starhue: {exc}") from None
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    """Run the starhue command-line interface.
+
+    Args:
+        argv (list[str] | None): Argument vector; defaults to ``sys.argv`` when
+            None.
+
+    Returns:
+        int: Process exit code (0 on success).
+    """
+    args = _build_parser().parse_args(argv)
+    use_color = supports_color() if args.color is None else args.color
+
+    # --- inverse mode: a color → its nearest blackbody --------------------
+    if args.from_color:
+        rgb = _parse_color(args.from_color)
+        temperature = color_to_temperature(rgb)
+        print(
+            f"# {args.from_color.strip()} → nearest blackbody {temperature:.0f} K",
+            file=sys.stderr,
+        )
+        temps: List[float] = [temperature]
+    else:
+        temps = args.temperatures or [5772.0]  # default: show the Sun
+        _validate_temps(temps)
+
+    for i, t in enumerate(temps):
+        if i:
+            print()
+        print(star_card(Star(t), color=use_color, spectrum=args.spectrum))
+
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())